hutch
trace.hutch(A, fun=None, maxiter=200, deg=20, atol=None, rtol=None, stop=['confidence', 'change'], ncv=2, orth=0, quad='fttr', confidence=0.95, pdf='rademacher', rng='pcg64', seed=-1, num_threads=0, verbose=False, info=False, plot=False, **kwargs)
Estimates the trace of a matrix A or matrix function f(A) via a Girard-Hutchinson estimator.
This function uses up to maxiter
random isotropic vectors to form an unbiased estimator of the trace of A
. The estimator is obtained by averaging quadratic forms of A (or f(A)), rescaling as necessary.
Notes
For matrix functions, the Lanczos method up to degree deg
is used to approximate the action of f(A). By default,
Parameters
Name | Type | Description | Default |
---|---|---|---|
A |
ndarray, sparray, or LinearOperator | real symmetric operator. | required |
fun |
str or typing.Callable | real-valued function defined on the spectrum of A . |
"identity" |
maxiter |
int | Maximum number of random vectors to sample for the trace estimate. | 10 |
deg |
int | Degree of the quadrature approximation. Must be at least 1. | 20 |
atol |
float | Absolute tolerance to signal convergence for early-stopping. See notes. | None |
rtol |
float | Relative tolerance to signal convergence for early-stopping. See notes. | 1e-2 |
stop |
str | Early-stopping criteria to test estimator convergence. See details. | "confidence" |
ncv |
int | Number of Lanczos vectors to allocate. Must be at least 2. | 2 |
orth |
int | Number of additional Lanczos vectors to orthogonalize against. Must be less than ncv . |
0 |
quad |
str | Method used to obtain the weights of the Gaussian quadrature. See notes. | 'fttr' |
confidence |
float | Confidence level to consider estimator as converged. Only used when stop = “confidence”. |
0.95 |
pdf |
‘rademacher’, ‘normal’ | Choice of zero-centered distribution to sample random vectors from. | 'rademacher' |
rng |
‘splitmix64’, ’xoshiro256**‘, ’pcg64’, ‘lcg64’, ‘mt64’ | Random number generator to use. | 'splitmix64' |
seed |
int | Seed to initialize the rng entropy source. Set seed > -1 for reproducibility. |
-1 |
num_threads |
int | Number of threads to use to parallelize the computation. Set to <= 0 to let OpenMP decide. | 0 |
plot |
bool | If true, plots the samples of the trace estimate along with their convergence characteristics. | False |
info |
bool | If True, returns a dictionary containing all relevant information about the computation. | False |
kwargs |
dict | additional key-values to parameterize the chosen function ‘fun’. | {} |
Returns
Type | Description |
---|---|
float | Estimate of the trace of A, if fun = "identity" , otherwise estimates the trace of f(A). |
(dict, optional) | If ‘info = True’, additional information about the computation. |
See Also
lanczos : the lanczos algorithm.
Reference
[1] Ubaru, S., Chen, J., & Saad, Y. (2017). Fast estimation of tr(f(A)) via stochastic Lanczos quadrature. SIAM Journal on Matrix Analysis and Applications, 38(4), 1075-1099.