capytaine.matrices.low_rank module

This module implements a class to describe a low-rank matrix as the tensor product of two smaller matrices. In particular, an implementation of the Adaptive Cross Approximation is used to build such a matrix.

It takes inspiration from the following works:

• openHmx module from Gypsilab by Matthieu Aussal (GPL licensed)

• HierarchicalMatrices by Markus Neumann (GPL licensed)

class capytaine.matrices.low_rank.LowRankMatrix(left_matrix, right_matrix)

Bases: object

Matrix defined as the tensor product of two small matrices.

Parameters:

• left_matrix (numpy.array) – Matrix of shape (nb_cols, rank).

• right_matrix (numpy.array) – Matrix of shape (rank, nb_rows).

Variables:

• shape (Tuple[int, int]) – The shape of the full matrix.

• rank (int) – The rank of the full matrix.

• dtype (numpy.dtype) – Type of data in the matrix.

astype(dtype)

property density

classmethod from_full_matrix_with_ACA(full_matrix, max_rank=None, tol=0.0)

Create a low rank matrix from a full matrix using Adaptive Cross Approximation. The user should provide either the max_rank optional argument or the tol optional argument.

Parameters:

• full_matrix (numpy.array) – The matrix that will be approximated.

• max_rank (int, optional) – The maximum rank allowed for the output low rank matrix. The default value is half the size of the full matrix, that is no gain in storage space.

• tol (float, optional) – The tolerance on the relative error (default: 0). If the Frobenius norm of the increment is lower than the tolerance, the iteration stops. If the tolerance is set to 0, the resulting matrix will have the maximum rank defined by max_rank.

Return type:

LowRankMatrix

classmethod from_full_matrix_with_SVD(full_matrix, max_rank)

Create a low rank matrix from a full matrix using Singular Value Decomposition.

Parameters:

• full_matrix (numpy array) – The matrix that will be approximated.

• max_rank (int) – Rank of the low-rank approximation.

Return type:

LowRankMatrix

classmethod from_function_with_ACA(func, nb_rows, nb_cols, max_rank=None, tol=0.0, dtype=<class 'numpy.float64'>)

Create a low rank matrix from a function using Adaptive Cross Approximation. The user should provide either the max_rank optional argument or the tol optional argument.

Parameters:

• func (Function) – Function such that func(i, j) returns the value of the (i, j) entry of the full matrix.

• nb_rows (int) – Number of rows in the full matrix.

• nb_cols (int) – Number of cols in the full matrix.

• max_rank (int, optional) – The maximum rank allowed for the output low rank matrix. The default value is half the size of the full matrix, that is no gain in storage space.

• tol (float, optional) – The tolerance on the relative error (default: 0). If the Frobenius norm of the increment is lower than the tolerance, the iteration stops. If the tolerance is set to 0, the resulting matrix will have the maximum rank defined by max_rank.

• dtype (numpy.dtype, optional) – Type of the data returned by the function.

Return type:

LowRankMatrix

classmethod from_rows_and_cols_functions_with_ACA(get_row_func, get_col_func, nb_rows, nb_cols, max_rank=None, tol=0.0, dtype=<class 'numpy.float64'>)

Create a low rank matrix from functions using Adaptive Cross Approximation. The user should provide either the max_rank optional argument or the tol optional argument.

Parameters:

• get_row_func (Function) – Function such that get_row_func(i) returns the i-th row of the full matrix.

• get_col_func (Function) – Function such that get_col_func(j) returns the j-th column of the full matrix.

• nb_rows (int) – Number of rows in the full matrix.

• nb_cols (int) – Number of columns in the full matrix.

• max_rank (int, optional) – The maximum rank allowed for the output low rank matrix. The default value is half the size of the full matrix, that is no gain in storage space.

• tol (float, optional) – The tolerance on the relative error (default: 0). If the Frobenius norm of the increment is lower than the tolerance, the iteration stops. If the tolerance is set to 0, the resulting matrix will have the maximum rank defined by max_rank.

• dtype (numpy.dtype, optional) – The type of data in the low rank matrix (default: float64).

Return type:

LowRankMatrix

classmethod from_rows_and_cols_functions_with_multi_ACA(get_row, get_col, nb_rows, nb_cols, nb_matrices=1, id_main=0, max_rank=None, tol=0.0, dtype=<class 'numpy.float64'>)

Create several low rank matrices while running an Adaptive Cross Approximation. The user should provide either the max_rank optional argument or the tol optional argument.

In Capytaine, the routines evaluating the influence matrices return the values of two matrices (S and V) at once, because there is a lot of common computations in their evaluation. The present function can be used to build the ACA of one of them while getting at the same time an approximation of the other for free.

Freely adapted from the routine hmxACA.m from Gypsilab.

Parameters:

• get_row (Function) – Function such that get_row(i) returns the i-th row of all the full matrices.

• get_col (Function) – Function such that get_col(j) returns the j-th column of all the full matrices.

• nb_rows (int) – Number of rows in all full matrices.

• nb_cols (int) – Number of columns in all full matrices.

• nb_matrices (int, optional) – The number of matrices approximated at the same time.

• id_main (int, optional) – The matrix used primarily in the ACA.

• max_rank (int, optional) – The maximum rank allowed for both output low rank matrices. The default value is half the size of the full matrix, that is no gain in storage space.

• tol (float, optional) – The tolerance on the relative error (default: 0). If the Frobenius norm of the increment is lower than the tolerance, the iteration stops. If the tolerance is set to 0, the resulting matrix will have the maximum rank defined by max_rank.

• dtype (numpy.dtype, optional) – The type of data in both low rank matrices (default: float64).

Return type:

List[LowRankMatrix]

full_matrix(dtype=None)

ndim = 2

recompress(tol=None, new_rank=None)

Recompress the matrix to a lower rank. Based on the routine hmxQRSVD.m from Gipsylab.

property sparcity

property stored_data_size

exception capytaine.matrices.low_rank.NoConvergenceOfACA

Bases: Exception