API Reference
@precision
precision.m
Parameters
--------------------
base - array | str, default='h'
For the string type, the arithmetic format supports:
'q43', 'fp8-e4m3' - NVIDIA quarter precision (4 exponent bits,
3 significand (mantissa) bits),
'q52', 'fp8-e5m2' - NVIDIA quarter precision (5 exponent bits,
2 significand bits),
'b', 'bfloat16' - bfloat16,
'h', 'half', 'fp16' - IEEE half precision (the default),
's', 'single', 'fp32' - IEEE single precision,
'd', 'double', 'fp64' - IEEE double precision,
'c', 'custom' - custom format.
The custom (base 2) format is defined by array (2-element, [t, emax]),
where t is the number of bits in the significand
(including the hidden bit) and emax is the maximum value of the
exponent. The minimu exponent is taken to be emin = 1 - emax and
the IEEE floating-point number representation is assumed, so that
emax and the number of bits e in the exponent are related by
emax = 2^(e-1) - 1.
round - int, default=1
1: round to nearest using round to even last bit to break ties
(the default);
2: round towards plus infinity (round up);
3: round towards minus infinity (round down);
4: round towards zero;
5: stochastic rounding - round to the next larger or next smaller
f.p. (floating-point) number with probability proportional to
1 minus the distance to those f.p. numbers;
6: stochastic rounding - round to the next larger or next smaller
f.p. number with equal probability.
subnormal - int
specifies whether subnormal numbers are supported, if `subnormal=0`,
subnormals are flushed to zero:
0 = do not support subnormals (the default for base='b', i.e., bfloat16 format),
1 = support subnormals (the default if base is set to others).
explim - int, default=1
``explim = 0`` make emax (the maximal exponent) for the specified arithmetic disabled,
so overflow, underflow, or subnormal numbers will be produced only if necessary
for the data type. This parameter is for exploring
low precisions independent of range limitations.
flip - int, default=0
Determine whether each element of the rounded value has a randomly chosen bit in
its significand flipped with a certain probability.
prob - double, default=0.5
if flip = 1 then each element of the rounded
value has a randomly chosen bit in its significand flipped with probability ``prob``.
randfunc - func, default=@(n) rand(n, 1)
The random function for stochastic rounding.
If options.randfunc is supplied, then in stochastic rounding (modes
5 and 6) the random numbers used for rounding will be generated
using that function. It should be a function that has a single argument
for the number of random numbers to generate and returns a vector of
the random numbers.
Properties
--------------------
Same as parameters, except
u - double
Unit roundoff computed for current floating point format.
@hodlr
hodlr.m
Parameters
--------------------
A - double | single
Matrix to be converted.
max_level - int, default=9999
Maximum level for cluster tree.
min_block_size - int, default=2
The minimum size for HODLR blocks.
method - str, default='svd'
The method to perform compression for off-diagonal blocks.
vareps - double, default=1.0e-12
The vareps value used for truncation of low rank approximation.
trun_norm_tp - str, default='2'
Norm type for the the off-diagonal block truncation ``||A - B||_trun_norm_tp <= vareps * ||B||``.
Properties
--------------------
U1, V2, U2, V1 - double
The right upper block matrix of each level, we have A12 = U1 * V2 and A21 = U2 * V1.
A11, A22 - hodlr
The diagonal block matrix in HODLR format (access in the next level).
shape - array
The shape of object in the current level.
level - int
The level for cluster tree.
max_level - int
The maximum level of cluster tree after transformation.
@mphodlr
mphodlr.m
Parameters
--------------------
precs - cell
The cell array that contains the precision used for compression of each level.
Each element is a precision class.
A - double | single
Matrix to be converted.
max_level - int, default=9999
Maximum level for cluster tree.
min_block_size - int, default=2
The minimum size for HODLR blocks.
method - str, default='svd'
The method to perform compression for off-diagonal blocks.
vareps - double, default=1.0e-12
The vareps value used for truncation of low rank approximation.
trun_norm_tp - str, default='2'
Norm type for the the off-diagonal block truncation ``||A - B||_trun_norm_tp <= vareps * ||B||``.
Properties
--------------------
U1, V2, U2, V1 - double
The right upper block matrix of each level, we have A12 = U1 * V2 and A21 = U2 * V1.
A11, A22 - hodlr
The diagonal block matrix in HODLR format (access in the next level).
shape - array
The shape of object in the current level.
level - int
The level for cluster tree.
max_level - int
The maximum level of cluster tree after transformation.
@amphodlr
amphodlr.m
Parameters
--------------------
precs - cell
The cell array that contains the precision used for compression of each level.
Each element is a precision class.
A - double | single
Matrix to be converted.
max_level - int, default=9999
Maximum level for cluster tree.
min_block_size - int, default=2
The minimum size for HODLR blocks.
method - str, default='svd'
The method to perform compression for off-diagonal blocks.
vareps - double, default=1.0e-12
The vareps value used for truncation of low rank approximation.
trun_norm_tp - str, default='2'
Norm type for the the off-diagonal block truncation ``||A - B||_trun_norm_tp <= vareps * ||B||``.
Properties
--------------------
U1, V2, U2, V1 - double
The right upper block matrix of each level, we have A12 = U1 * V2 and A21 = U2 * V1.
A11, A22 - hodlr
The diagonal block matrix in HODLR format (access in the next level).
shape - array
The shape of object in the current level.
level - int
The level for cluster tree.
max_level - int
The maximum level of cluster tree after transformation.
Compute rountines
hadd.m
The function is used for the operation of summation or subtraction for HODLR matrix A and B.
Parameters
--------------------
A - hodlr | double
Input matrix - hodlr class / dense tyle.
B - hodlr | double
Input matrix - hodlr class / dense tyle.
operator - str, default = '+'
The operator of add ('+') or minus ('-'), string type.
oformat - str, default = 'hodlr'
The format of returns.
Returns
--------------------
C - hodlr | double
Return matrix in hodlr class or dense array.
hdot.m
Compute dot product of A and B.
Parameters
--------------------
A - hodlr | double
Matrix in HODLR format or double array.
B - hodlr | double
Matrix in HODLR format or double array.
oformat - str, default='hodlr'
Output format: 'hodlr' or 'dense'.
Returns
--------------------
C - hodlr | double
The matrix of product.
mhdot.m
Compute dot product of A and B.
Parameters
--------------------
A - hodlr | double
Matrix in HODLR format or double array.
B - hodlr | double
Matrix in HODLR format or double array.
oformat - str, default='hodlr'
Output format: 'hodlr' or 'dense'.
Returns
--------------------
C - hodlr | double
The matrix of product.
hlu.m
Compute LU factorization for HODLR matrix H.
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
oformat - str, default='hodlr'
The output format. 'dense' or 'hodlr'.
epsilon - double, default is the vareps of holdlr matrix H
The vareps for recompression.
Returns
--------------------
L - double
The upper triangular matrix L is computed such that L * U = H.
U - double
The upper triangular matrix U is computed such that L * U = H.
mhlu.m
Compute LU factorization for HODLR matrix H.
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
oformat - str, default='hodlr'
The output format. 'dense' or 'hodlr'.
vareps - double, default is the vareps of holdlr matrix H
The vareps for recompression.
Returns
--------------------
L - double
The upper triangular matrix L is computed such that L * U = H.
U - double
The upper triangular matrix U is computed such that L * U = H.
hchol.m
Compute Cholesky factorization for symmetric positive-definite HODLR matrix H.
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
oformat - str, default='hodlr'
The output format, either 'hodlr' or ''dense.
Returns
--------------------
R - double
The upper triangular matrix R is computed such that R' * R = H.
mhchol.m
Compute Cholesky factorization for symmetric positive-definite HODLR matrix H.
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
oformat - str, default='hodlr'
The output format, either 'hodlr' or ''dense.
Returns
--------------------
R - double
The upper triangular matrix R is computed such that R' * R = H.
recover.m
The function is to recover a HODLR format into array format
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
issparse - boolean
`1` indicates returning sparse format, `0` indicates returning full arrary.
Returns
--------------------
A - double
Array in sparse or not.
hsize.m
The function is to return the shape of HOLDR matrix.
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
oformat - int, default=1
If input is not the leafnode of the HODLR matrix:
1: Outputs of varying number [m, n, m1, m2, n1, n2] for hierarchical block matrices.
2: Outputs of varying number [m1, m2, n1, n2] for hierarchical block matrices.
Otherwise:
Outputs of varying number [m, n] for hierarchical block matrices.
Returns
--------------------
[m, n, su1, su2, sv1, sv2] - int
Indicates the size of rows and columns for H, size(H.U1, 1), size(H.U2, 1), size(H.V1, 2), size(H.V2, 2), respectively.
inverse.m
Parameters
--------------------
H - hodlr
Matrix in HODLR format - hodlr class.
algorithm - int, default=1
The algorithm to implement inverse
oformat - str, default = 'hodlr'
The format of returns.
Returns
--------------------
C - hodlr | double
Return matrix in hodlr class or dense array.
lu_solve.m
Compute Hx = b using LU factorization.
Parameters
--------------------
Setting 1:
H - hodlr
Matrix in HODLR format - hodlr class.
b - double/single
Setting 2:
l - hodlr
Matrix in HODLR format - hodlr class.
U - hodlr
Matrix in HODLR format - hodlr class.
b - double/single
Returns
--------------------
x - double
The solution.
hstorage.m
Measure the theoretical storage of HODLR matrix
Parameters
--------------------
H - hodlr, mphodlr, and amphodlr
The input of HODLR matrix.
Returns
--------------------
y - double
The number of bits for storage.
hstorage.m
Function to truncate the off-diagonal blocks of HODLR matrix to rank ``rnk``.
Parameters
--------------------
H - hodlr, mphodlr, and amphodlr
The input of HODLR matrix.
rnk - int
the maximum rank for off-diagonal blocks.
hqr.m
The function is to perform QR factorization based on HODLR representation.
Parameters
--------------------
A - hodlr
Input matrix - hodlr class / dense tyle.
method - str
Options: 'lintner', 'bebendorf' and 'kressner'.
Returns
--------------------
Q, R - hodlr
Return matrix in hodlr class.
mhqr.m
The function is to perform QR factorization in multiple precision based on HODLR representation.
Parameters
--------------------
A - hodlr
Input matrix - hodlr class / dense tyle.
method - str
Options: 'lt', 'lt2' and 'dk'.
Returns
--------------------
Q, R - hodlr
Return matrix in hodlr class.