API Reference#

The API reference contains:

  • Functions: compute log-determinant and trace of functions of matrices.

  • Interpolators: interpolate functions of one-parameter family of affine matrix functions.

  • Linear Operators: classes that represent matrices and affine matrix functions.

  • Sample Matrices: generate matrices for test purposes.

  • Device Inquiry: inquiry information about CPU and GPU devices.

Functions#

The functions of this package are:

  • Log-Determinant: computes log-determinant of matrix.

  • Trace of Inverses: computes trace of the inverse of a matrix or any negative power of the matrix.

  • Trace: computes the trace of matrix or any positive power of the matrix.

  • TrExp: computes the trace of matrix exponential.

  • TrLinFrac: computes the trace of the linear fractional transformation of a matrix.

  • EigenCount: computes the number of eigenvalues of a matrix within an interval.

  • Density: computes the spectral density of a matrix within evaluated at a given eigenvalue.

  • Schatten Norm: computes the Schatten norm of order \(p\), which includes the above three functions.

Each of the above functions are implemented using both direct and randomized algorithms, suitable for various matrices sizes.

Log-Determinant#

imate.logdet(A[, gram, p, return_info, method])

Log-determinant of non-singular matrix or linear operator.

This function computes the log-determinant of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) where \(p\) is a real exponent.

The imate.logdet function has the following methods:

Method

Algorithm

Matrix size

Matrix type

Solution

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

Any

Exact

cholesky

Cholesky decomposition

Moderate \(n < 2^{15}\)

Symmetric Positive-definite

Exact

slq

Stochastic Lanczos Quadrature

Large \(n > 2^{12}\)

Any

Approximation

Trace of Inverse#

imate.traceinv(A[, gram, p, return_info, method])

Trace of inverse of non-singular matrix or linear operator.

This function computes the trace of \(\mathbf{A}^{-p}\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^{-p}\) where \(p\) is a positive real exponent.

The imate.traceinv function has the following methods:

Method

Algorithm

Matrix Size

Notes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

cholesky

Cholesky decomposition

Moderate \(n < 2^{15}\)

Exact solution

hutchinson

Hutchinson

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

Trace#

imate.trace(A[, gram, p, return_info, method])

Trace of matrix or linear operator.

This function computes the trace of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) where \(p\) is a positive real exponent.

The imate.trace function has the following methods:

Method

Algorithm

Matrix Size

Notes

exact

Direct

All sizes

For all purposes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

TrExp#

imate.trexp(A[, gram, p, coeff, ...])

Trace of the exponential of matrix or linear operator.

This function computes the trace of the exponential function of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) where \(p\) is a positive real exponent.

The imate.trexp function has the following methods:

Method

Algorithm

Matrix Size

Notes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

TrLinFrac#

imate.trlinfrac(A[, gram, p, coeff, ...])

Trace of the linear fractional transformation of matrix or linear operator.

This function computes the trace of the linear fractional transformation of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) where \(p\) is a positive real exponent.

The imate.trlinfrac function has the following methods:

Method

Algorithm

Matrix Size

Notes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

EigenCount#

imate.eigencount(A[, gram, p, interval, ...])

Eigencount of matrix or linear operator.

This function approximates the number of eigenvalues of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) within a given interval where \(p\) is a positive real exponent.

The imate.eigencount function has the following methods:

Method

Algorithm

Matrix Size

Notes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

Density#

imate.density(A[, gram, p, mu, sigma, ...])

Estimate the spectral density of matrix or linear operator.

This function approximates the spectral density of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) for a given eigenvalue where \(p\) is a positive real exponent.

The imate.density function has the following methods:

Method

Algorithm

Matrix Size

Notes

eigenvalue

Eigenvalue decomposition

Small \(n < 2^{12}\)

For testing and benchmarking other methods

slq

Stochastic Lanczos Quadrature

Large \(2^{12} < n\)

Randomized method using Monte-Carlo sampling

Schatten Norm#

imate.schatten(A[, gram, p, return_info, method])

Schatten p-norm and p-anti-norm of matrix.

This function computes the Schatten norm of \(\mathbf{A}^p\) or the Gramian matrix \((\mathbf{A}^{\intercal} \mathbf{A})^p\) where \(p\) is a real exponent.

Interpolators#

Interpolate the various matrix functions of the one-parameter family of affine matrix function:

\[t \mapsto \mathbf{A} + t \mathbf{B}.\]

imate.InterpolateLogdet(A[, B, options, ...])

Interpolate the log-deterinant of an affine matrix function.

imate.InterpolateTrace(A[, B, p, options, ...])

Interpolate the trace of the powers of an affine matrix function.

imate.InterpolateSchatten(A[, B, p, ...])

Interpolate Schatten norm (or anti-norm) of an affine matrix function.

Each of the above interpolator classes have the following interpolation methods:

kind

Description

Results

'ext'

Exact (no interpolation)

exact

'eig'

Eigenvalue (no interpolation)

exact

'mbf'

Monomial Basis Functions

interpolated

'imbf'

Inverse Monomial Basis Functions

interpolated

'rbf'

Radial Basis Functions

interpolated

'crf'

Chebyshev Rational Functions

interpolated

'spl'

Spline

interpolated

'rpf'

Rational Polynomial Functions

interpolated

Linear Operators#

Create linear operator objects as container for various matrix types with a unified interface, establish a fully automatic dynamic buffer to allocate, deallocate, and transfer data between CPU and multiple GPU devices on demand, as well as perform basic matrix-vector operations with high performance on both CPU or GPU devices. These objects can be passed to imate functions as input matrices.

imate.Matrix(A)

Create a linear operator object from an input matrix.

imate.AffineMatrixFunction(A[, B])

Create a one-parameter affine matrix function object from input matrices.

Sample Matrices#

Generate sample matrices for test purposes, such as correlation matrix and Toeplitz matrix. The matrix functions of Toeplitz matrix (such as its log-determinant, trace of its inverse, etc) are known analytically, making Toeplitz matrix suitable for benchmarking the result of randomized methods with analytical solutions.

imate.correlation_matrix([size, dimension, ...])

Generate symmetric and positive-definite matrix for test purposes.

imate.toeplitz(a, b[, size, gram, format, dtype])

Generate a sparse Toeplitz matrix for test purposes.

imate.sample_matrices.toeplitz_logdet(a, b, size)

Compute the log-determinant of Toeplitz matrix using an analytic formula.

imate.sample_matrices.toeplitz_trace(a, b, size)

Compute the trace of the Toeplitz matrix using an analytic formula.

imate.sample_matrices.toeplitz_traceinv(a, ...)

Computes the trace of the inverse of Toeplitz matrix using an analytic formula.

imate.sample_matrices.toeplitz_schatten(a, ...)

Compute the Schatten norm of Toeplitz matrix using an analytic formula.

Device Inquiry#

Measure the process time and consumed memory of the Python process during computation with the following classes.

imate.Timer([hold])

A timer to measure elapsed wall time and CPU process time of Python process.

imate.Memory()

Measures resident memory size or its change for the Python process.

Inquiry hardware information, including CPU and GPU devices employed during computation and get information about the CUDA Toolkit installation with the following functions.

imate.info([print_only])

Provides general information about hardware device, package version, and memory usage.

imate.device.get_processor_name()

Gets the model name of CPU processor.

imate.device.get_gpu_name()

Gets the model name of GPU device.

imate.device.get_num_cpu_threads()

Returns the number of available CPU processor threads.

imate.device.get_num_gpu_devices()

Returns the number of available GPU devices in multi-GPU platforms.

imate.device.get_nvidia_driver_version()

Gets the NVIDIA graphic driver version.

imate.device.locate_cuda()

Returns the directory paths and version of CUDA Toolkit installation.

imate.device.restrict_to_single_processor()

Restricts the computations to only one CPU thread.