H2Matrix class

Class H2matrix represents H2-matrices in special low-parametric format.

class h2tools.h2matrix.H2matrix(problem, row_basis_size, col_basis_size, row_transfer, col_transfer, row_interaction, col_interaction, row_close, col_close, row_basis=None, col_basis=None, mpi_comm=None)

Low-parametric structure of H2-matrices.

Every H2-matrix is based on row and column cluster trees with corresponding transfer and interaction matrices. However, there is special case of H2-format, when interaction matrices are simply submatrices of a given matrix. In such case each interaction matrix can be computed on demand as a submatrix, based on corresponding rows and columns.

There are 2 types of structure and 2 types of memory allocation for H2matrix instance:

Types of structure:

1. “h2”: no conditions on far-field interaction matrices.
2. “mcbh”: far-field interaction matrices are submatrices of given matrix, based on lists of basis rows and columns.

Types of memory allocation:

1. “full”: all interaction matrices are stored in memory.
2. “low”: close-field interaction matrices are computed on demand, far field interaction matrices are also computed on demand for “mcbh”-type structure.

Usually, most memory consuming part of H2matrix is a list of far-field interaction matrices. Since main feature of “mcbh”-type structure of H2matrix is representation of far-field interaction matrices as submatrices of initial matrix, based on lists of basis rows and columns, using “low” memory allocation model saves a lot of memory in case of “mcbh”-type structure of H2matrix. For some problems, it decreases total memory consumption of H2matrix by an order of magnitude.

Parameters:

problem: Problem

Contains all information on problem (linear operator and block cluster tree).

row_basis_size : list or numpy.ndarray(ndim=1)

Size of basis of each node of row cluster tree.

col_basis_size : list or numpy.ndarray(ndim=1)

Size of basis of each node of column cluster tree.

row_transfer : list of numpy.ndarray(ndim=2)

Transfer matrix for each node of row cluster tree.

col_transfer : list of numpy.ndarray(ndim=2)

Transfer matrix for each node of column cluster tree.

row_interaction : list of list of numpy.ndarray(ndim=2)

Far-field interaction matrices for each node of row cluster tree. At least one of row_interaction and col_interaction must be set.

col_interaction : list of list of numpy.ndarray(ndim=2)

Far-field interaction matrices for each node of column cluster tree. At least one of row_interaction and col_interaction must be set.

row_close : list of list of numpy.ndarray(ndim=2)

Near-field interaction matrices for each node of row cluster tree. At least one of row_close and col_close must be set.

col_close : list of list of numpy.ndarray(ndim=2)

Near-field interaction matrices for each node of column cluster tree. At least one of row_close and col_close must be set.

row_basis : list of numpy.ndarray(ndim=1, dtype=numpy.uint64)

Basis rows for each node of row cluster tree.

col_basis : list of numpy.ndarray(ndim=1, dtype=numpy.uint64)

Basis columns for each node of column cluster tree.

mpi_comm : MPI communicator

Notes

Actual shape of matrix is (shape[0], element_shape[0], ..., element_shape[-1], shape[1]). If function of interaction is scalar, then element_shape is simply empty tuple () and actual shape of matrix is just a parameter shape.

Attributes

problem	(instance of class h2tools.Problem) Contains information about source and destination datas, cluster trees and lists of admissibly far and admissibly close nodes.
shape	(tuple) Shape of matrix, number of rows by a number of columns.
element_shape: tuple	Shape of each element of matrix (scalar/vector/matrix interactions).
dtype	(numpy.dtype) Data type of matrix elements.
h2_type	(string) Type of structure. Possible values are following: - “h2”: no conditions on interaction matrices, no basis rows or columns, standard H2matrix format. - “mcbh”: interaction matrices are submatrices of initial matrix (defined by problem), requires basis rows and columns.
mem_type	(string) Memory allocation model. Possible values are following: - “full”: all interaction matrices are stored in memory. - “low”: close-field interaction matrices are computed on demand, far field interaction matrices are also computed on demand (not stored in memory) if h2_type is “mcbh”.
row_basis	(list of numpy.ndarray(ndim=1, dtype=numpy.uint64)) Contains indexes of basis rows for each node of row cluster tree.
col_basis	(list of numpy.ndarray(ndim=1, dtype=numpy.uint64)) Contains indexes of basis columns for each node of column cluster tree.
row_transfer	(list of numpy.ndarray(ndim=2)) Transfer matrices from children to node for each node of row cluster tree.
col_transfer	(list of numpy.ndarray(ndim=2)) Transfer matrices from children to node for each node of column cluster tree.
row_interaction	(list of list of numpy.ndarray(ndim=2)) List of interaction matrices with corresponding admissibly far nodes for each node of row cluster tree.
col_interaction	(list of list of numpy.ndarray(ndim=2)) List of interaction matrices with corresponding admissibly far nodes for each node of column cluster tree.
row_close	(list of list of numpy.ndarray(ndim=2)) List of interaction matrices with corresponding admissibly close nodes for each node of row cluster tree.
col_close	(list of list of numpy.ndarray(ndim=2)) List of interaction matrices with corresponding admissibly close nodes for each node of column cluster tree.

close_dot(x)

Applies near-field part of H2matrix to vector from left side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of near-field A * x.

close_rdot(x)

Applies near-field part of H2matrix to vector from right side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of near-field A.T * x.

copy(verbose=False)

Copies all buffers into new instance of H2matrix.

Parameters:

verbose : boolean

If true, shows copy time.

diffnorm(factor2=None, far_only=False)

Computes relative spectral distance from H2matrix.

If factor2 is not given, distance is measured to initial linear operator, represented by problem attribute. Otherwise, distance is measured to factor2 operator with help of following methods, defined in factor2 object: dot, rdot, far_dot and far_rdot. Meaning of this methods is the same, as meaning of methods of this object.

If parameter far_only is True, measures relative error of approximation of far-field part only.

Parameters:

factor2 : Python object

If not defined, this function returns relative spectral error of approximation by H2matrix. If defined, this method returns relative spectral distance from H2matrix to factor2

far_only : boolean

If true, measures distance only by far-field part.

Returns:

float

Relative spectral distance to initial operator or factor2 object.

dot(x)

Applies multplication by H2matrix to vector from left side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of A * x.

far_dot(x)

Applies far-field part of H2matrix to vector from left side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of farfield A * x.

far_rdot(x)

Applies far-field part of H2matrix to vector from right side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of farfield A.T * x.

func(row, col)

Returns submatrix on intersection of given rows and columns.

Parameters:

row : numpy.ndarray(ndim=1, dtype=numpy.uint64)

rows, where to compute submatrix

col : numpy.ndarray(ndim=1, dtype=numpy.uint64)

columns, where to compute submatrix

Returns:

numpy.ndarray

Submatrix on intersection of given rows and columns.

mcbh(onfly=None, verbose=False)

Converts current H2matrix representation to “mcbh” H2-type.

Parameters:

onfly : boolean

If true, converts mem_type to “low”, otherwise converts it to “full”.

verbose : boolean

If true, outputs some additional information.

Notes

Works only in sequential programs.

nbytes(transfer=True, interaction=True, close=True, basis=True)

Returns memory, used by requested parts of H2matrix, in bytes.

Parameters:

transfer : boolean

If true, adds to result size of memory buffers, used by transfer matrices.

interaction : boolean

If true, adds to result size of memory buffers, used by far-field interaction matrices.

close : boolean

If true, adds to result size of memory buffers, used by near-field interaction matrices.

basis : boolean

If true, adds to result size of memory buffers, used by storage of indexes of basis rows and columns.

Returns:

integer

Number of bytes, consumed by given parts of H2matrix.

rdot(x)

Applies multplication by H2matrix to vector from right side.

Parameters:

x : numpy.ndarray

Vector or block-vector to multiply.

Returns:

numpy.ndarray

Result of A.T * x.

svdcompress(tau, verbose=False)

Decompression of H2matrix by SVD for block rows and columns.

Performs SVD decompression of each block row and block column inplace. Orthogonolizes transfer matrices of row cluster tree, then decompresses block columns of column cluster tree, then orthogonolizes transfer matrices of column cluster tree and then decompresses block rows of row cluster tree. Finally, transfer matrices of row cluster tree are orthogonolized one additional time to make all transfer matrices orthogonal.

Parameters:

tau : float

Spectral error tolerance for SVD decompressions of each block row and block column.

verbose : boolean

If true, shows memory before and after decompression and additional information in some cases.

Notes

Works only in sequential programs