H2Lib  3.0
Data Structures | Macros | Typedefs | Functions
rkmatrix

Representation of a low-rank matrix in factorized form $R = A B^*$. More...

Data Structures

struct  _rkmatrix
 Representation of a low-rank matrix in factorized form $R = A B^*$. More...
 

Typedefs

typedef struct _rkmatrix rkmatrix
 Representation of a low-rank matrix in factorized form.
 
typedef rkmatrixprkmatrix
 Pointer to rkmatrix object.
 
typedef const rkmatrixpcrkmatrix
 Pointer to constant rkmatrix object.
 

Functions

prkmatrix init_rkmatrix (prkmatrix r, uint rows, uint cols, uint k)
 Initialize an rkmatrix object. More...
 
pcrkmatrix init_sub_rkmatrix (prkmatrix r, pcrkmatrix src, uint rows, uint roff, uint cols, uint coff)
 Initialize an rkmatrix object to represent a submatrix. More...
 
void uninit_rkmatrix (prkmatrix r)
 Uninitialize an rkmatrix object. More...
 
prkmatrix new_rkmatrix (uint rows, uint cols, uint k)
 Create a new rkmatrix object. More...
 
pcrkmatrix new_sub_rkmatrix (pcrkmatrix src, uint rows, uint roff, uint cols, uint coff)
 Create a new rkmatrix object representing a submatrix. More...
 
void del_rkmatrix (prkmatrix r)
 Delete an rkmatrix object. More...
 
void setrank_rkmatrix (prkmatrix r, uint k)
 Change the rank of an rkmatrix. More...
 
void resize_rkmatrix (prkmatrix r, uint rows, uint cols, uint k)
 Change the size of an rkmatrix. More...
 
size_t getsize_rkmatrix (pcrkmatrix r)
 Get size of a given rkmatrix object. More...
 
size_t getsize_heap_rkmatrix (pcrkmatrix r)
 Get heap size of a given rkmatrix object. More...
 
prkmatrix clone_rkmatrix (pcrkmatrix r)
 Create a copy of an rkmatrix. More...
 
void copy_rkmatrix (bool atrans, pcrkmatrix a, prkmatrix b)
 Copy an rkmatrix into another rkmatrix. More...
 
void scale_rkmatrix (field alpha, prkmatrix r)
 Scale an rkmatrix by a factor. More...
 
void random_rkmatrix (prkmatrix r, uint kmax)
 Fill an rkmatrix with random values. More...
 
void addeval_rkmatrix_avector (field alpha, pcrkmatrix r, pcavector x, pavector y)
 Multiply a low-rank matrix $R$ by a vector $x$, $y \gets y + \alpha R x$. More...
 
void addevaltrans_rkmatrix_avector (field alpha, pcrkmatrix r, pcavector x, pavector y)
 Multiply the adjoint of a low-rank matrix $R$ by a vector $x$, $y \gets y + \alpha R^* x$. More...
 
void mvm_rkmatrix_avector (field alpha, bool rtrans, pcrkmatrix r, pcavector x, pavector y)
 Multiply a low-rank matrix $R$ or its adjoint $R^*$ by a vector, $y \gets y + \alpha R x$ or $y \gets y + \alpha R^* x$. More...
 
real norm2_rkmatrix (pcrkmatrix R)
 Approximate the spectral norm $\|R\|_2$ of a matrix $R$. More...
 
real norm2diff_rkmatrix (pcrkmatrix a, pcrkmatrix b)
 Approximate the spectral norm $\|R_A-R_B\|_2$ of the difference of two low-rank matrices $R_A$ and $R_B$. More...
 
uint getrows_rkmatrix (pcrkmatrix r)
 Get the number of rows of an rkmatrix $R=A B^*$. More...
 
uint getcols_rkmatrix (pcrkmatrix r)
 Get the number of columns of an rkmatrix $R=A B^*$. More...
 
uint getrank_rkmatrix (pcrkmatrix r)
 Get the rank of an rkmatrix $R=A B^*$. More...
 
pamatrix getA_rkmatrix (prkmatrix r)
 Get the factor A of an rkmatrix $R=A B^*$. More...
 
pamatrix getB_rkmatrix (prkmatrix r)
 Get the factor B of an rkmatrix $R=A B^*$. More...
 

Detailed Description

Representation of a low-rank matrix in factorized form $R = A B^*$.

The rkmatrix class is used to approximate admissible blocks in hierarchical matrices.

Function Documentation

void addeval_rkmatrix_avector ( field  alpha,
pcrkmatrix  r,
pcavector  x,
pavector  y 
)

Multiply a low-rank matrix $R$ by a vector $x$, $y \gets y + \alpha R x$.

The matrix $R$ is multiplied by the source vector $x$, the result is scaled by $\alpha$ and added to the target vector $y$.

Parameters
alphaScaling factor $\alpha$.
rMatrix $R$.
xSource vector $x$.
yTarget vector $y$.
void addevaltrans_rkmatrix_avector ( field  alpha,
pcrkmatrix  r,
pcavector  x,
pavector  y 
)

Multiply the adjoint of a low-rank matrix $R$ by a vector $x$, $y \gets y + \alpha R^* x$.

The adjoint $R^*$ is multiplied by the source vector $x$, the result is scaled by $\alpha$ and added to the target vector $y$.

Parameters
alphaScaling factor $\alpha$.
rMatrix $R$.
xSource vector $x$.
yTarget vector $y$.
prkmatrix clone_rkmatrix ( pcrkmatrix  r)

Create a copy of an rkmatrix.

Creates a new rkmatrix with identical parameters and copies the contents of $A$ and $B$.

Parameters
rSource rkmatrix.
Returns
Full copy of r.
void copy_rkmatrix ( bool  atrans,
pcrkmatrix  a,
prkmatrix  b 
)

Copy an rkmatrix into another rkmatrix.

Copies the contents of a->A and a->B to b->A and b->B.

Parameters
atransDetermines wether $A$ or $A^*$ should be copied.
aSource rkmatrix.
bTarget rkmatrix.
void del_rkmatrix ( prkmatrix  r)

Delete an rkmatrix object.

Releases the storage corresponding to the object.

Attention
Make sure that there are no submatrix objects referring to this object, since they will otherwise keep using pointers to invalid storage.
Parameters
rObject to be deleted.
pamatrix getA_rkmatrix ( prkmatrix  r)

Get the factor A of an rkmatrix $R=A B^*$.

Parameters
rMatrix $R$.
Returns
Factor $A$.
pamatrix getB_rkmatrix ( prkmatrix  r)

Get the factor B of an rkmatrix $R=A B^*$.

Parameters
rMatrix $R$.
Returns
Factor $A$.
uint getcols_rkmatrix ( pcrkmatrix  r)

Get the number of columns of an rkmatrix $R=A B^*$.

Parameters
rMatrix $R$.
Returns
Number of columns of $R$, i.e., number of rows of $B$.
uint getrank_rkmatrix ( pcrkmatrix  r)

Get the rank of an rkmatrix $R=A B^*$.

Parameters
rMatrix $R$.
Returns
Maximal rank of $R$, i.e., number of columns of $A$ and $B$.
uint getrows_rkmatrix ( pcrkmatrix  r)

Get the number of rows of an rkmatrix $R=A B^*$.

Parameters
rMatrix $R$.
Returns
Number of rows of $R$, i.e., number of rows of $A$.
size_t getsize_heap_rkmatrix ( pcrkmatrix  r)

Get heap size of a given rkmatrix object.

Computes the size of storage allocated for the coefficients on the heap, but not for the rkmatrix object itself. If the object uses the coefficients of another object (e.g., if it was created using new_sub_rkmatrix), no storage is required.

Parameters
rMatrix object.
Returns
Size of allocated heap storage in bytes.
size_t getsize_rkmatrix ( pcrkmatrix  r)

Get size of a given rkmatrix object.

Computes the size of the rkmatrix object and the storage allocated for the coefficients. If the object uses the coefficients of another object (e.g., if it was created using init_sub_rkmatrix), no coefficient storage is added.

Parameters
rMatrix object.
Returns
Size of allocated storage in bytes.
prkmatrix init_rkmatrix ( prkmatrix  r,
uint  rows,
uint  cols,
uint  k 
)

Initialize an rkmatrix object.

Sets up the components of the object and allocates storage for the matrices $A$ and $B$.

Remarks
Should always be matched by a call to uninit_rkmatrix.
Parameters
rObject to be initialized.
rowsNumber of rows.
colsNumber of columns.
kRank.
Returns
Initialized rkmatrix object.
pcrkmatrix init_sub_rkmatrix ( prkmatrix  r,
pcrkmatrix  src,
uint  rows,
uint  roff,
uint  cols,
uint  coff 
)

Initialize an rkmatrix object to represent a submatrix.

Sets up the components of the object and uses part of the storage of another rkmatrix for the matrix factors, leading to a new matrix representing a submatrix of the source.

Remarks
The function returns a pointer to a constant object in order to discourage changing the submatrix. Due to its factorized representation, changing the submatrix would lead to non-local changes to the entire matrix, and this is only rarely a good idea.
Should always be matched by a call to uninit_rkmatrix that will not release the coefficient storage.
Parameters
rObject to be initialized.
srcSource matrix.
rowsNumber of rows.
roffRow offset, should satisfy rows+roff<=src->rows.
colsNumber of columns.
coffColumn offset, should satisfy cols+coff<=src->cols.
Returns
Initialized rkmatrix object.
void mvm_rkmatrix_avector ( field  alpha,
bool  rtrans,
pcrkmatrix  r,
pcavector  x,
pavector  y 
)

Multiply a low-rank matrix $R$ or its adjoint $R^*$ by a vector, $y \gets y + \alpha R x$ or $y \gets y + \alpha R^* x$.

The matrix or its adjoint is multiplied by the source vector $x$, the result is scaled by $\alpha$ and added to the target vector $y$.

Parameters
alphaScaling factor $\alpha$.
rtransSet if $R^*$ is to be used instead of $R$.
rMatrix $R$.
xSource vector $x$.
yTarget vector $y$.
prkmatrix new_rkmatrix ( uint  rows,
uint  cols,
uint  k 
)

Create a new rkmatrix object.

Allocates storage for the object and sets up its components.

Remarks
Should always be matched by a call to del_rkmatrix.
Parameters
rowsNumber of rows.
colsNumber of columns.
kRank.
Returns
New rkmatrix object.
pcrkmatrix new_sub_rkmatrix ( pcrkmatrix  src,
uint  rows,
uint  roff,
uint  cols,
uint  coff 
)

Create a new rkmatrix object representing a submatrix.

Allocates storage for the object and uses part of the storage of another rkmatrix for the matrix factors, leading to a new matrix representing a submatrix of the source.

Remarks
The function returns a pointer to a constant object in order to discourage changing the submatrix. Due to its factorized representation, changing the submatrix would lead to non-local changes to the entire matrix, and this is only rarely a good idea.
Should always be matched by a call to del_rkmatrix.
Parameters
srcSource matrix.
rowsNumber of rows.
roffRow offset, should satisfy rows+roff<=src->rows.
colsNumber of columns.
coffColumn offset, should satisfy cols+coff<=src->cols.
Returns
New rkmatrix object.
real norm2_rkmatrix ( pcrkmatrix  R)

Approximate the spectral norm $\|R\|_2$ of a matrix $R$.

The spectral norm is approximated by applying a few steps of the power iteration to the matrix $R^* R$ and computing the square root of the resulting eigenvalue approximation.

Parameters
RLow rank matrix $R$.
Returns
Approximation of $\|R\|_2$.
real norm2diff_rkmatrix ( pcrkmatrix  a,
pcrkmatrix  b 
)

Approximate the spectral norm $\|R_A-R_B\|_2$ of the difference of two low-rank matrices $R_A$ and $R_B$.

The spectral norm is approximated by applying a few steps of the power iteration to the matrix $(R_A-R_B)^* (R_A-R_B)$ and computing the square root of the resulting eigenvalue approximation.

Parameters
aLow rank matrix $R_A$.
bLow rank matrix $R_B$.
Returns
Approximation of $\|R_A-R_B\|_2$.
void random_rkmatrix ( prkmatrix  r,
uint  kmax 
)

Fill an rkmatrix with random values.

Parameters
rTarget matrix.
kmaxMaximal rank.
void resize_rkmatrix ( prkmatrix  r,
uint  rows,
uint  cols,
uint  k 
)

Change the size of an rkmatrix.

This function resizes the matrices $A$ and $B$ without preserving their contents. The caller is responsible for ensuring that these matrices are initialized properly after they have been resized.

Parameters
rTarget matrix.
rowsNew number of rows.
colsNew number of columns.
kNew rank.
void scale_rkmatrix ( field  alpha,
prkmatrix  r 
)

Scale an rkmatrix by a factor.

Parameters
alphaScaling factor $\alpha$.
rTarget rkmatrix $R$, will be overwritten by $\alpha R$.
void setrank_rkmatrix ( prkmatrix  r,
uint  k 
)

Change the rank of an rkmatrix.

This function resizes the matrices $A$ and $B$ without preserving their contents. The caller is responsible for ensuring that these matrices are initialized properly after they have been resized.

Parameters
rTarget matrix.
kNew rank.
void uninit_rkmatrix ( prkmatrix  r)

Uninitialize an rkmatrix object.

Invalidates pointers, freeing corresponding storage if appropriate, and prepares the object for deletion.

Parameters
rObject to be uninitialized.