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 . More...

Typedefs
typedef struct _rkmatrix	rkmatrix
	Representation of a low-rank matrix in factorized form.

typedef rkmatrix *	prkmatrix
	Pointer to rkmatrix object.

typedef const rkmatrix *	pcrkmatrix
	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 by a vector , $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 by a vector , $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 or its adjoint 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 . 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 and . More...

uint	getrows_rkmatrix (pcrkmatrix r)
	Get the number of rows of an rkmatrix . More...

uint	getcols_rkmatrix (pcrkmatrix r)
	Get the number of columns of an rkmatrix . More...

uint	getrank_rkmatrix (pcrkmatrix r)
	Get the rank of an rkmatrix . More...

pamatrix	getA_rkmatrix (prkmatrix r)
	Get the factor A of an rkmatrix . More...

pamatrix	getB_rkmatrix (prkmatrix r)
	Get the factor B of an rkmatrix . 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

alpha	Scaling factor $\alpha$ .
r	Matrix .
x	Source vector .
y	Target vector .

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

alpha	Scaling factor $\alpha$ .
r	Matrix .
x	Source vector .
y	Target vector .

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

r	Source 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

atrans	Determines wether or should be copied.
a	Source rkmatrix.
b	Target 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

r	Object to be deleted.

pamatrix getA_rkmatrix ( prkmatrix r )

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

Parameters

r Matrix .

Returns: Factor .

pamatrix getB_rkmatrix ( prkmatrix r )

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

Parameters

r Matrix .

Returns: Factor .

uint getcols_rkmatrix ( pcrkmatrix r )

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

Parameters

r Matrix .

Returns: Number of columns of , i.e., number of rows of .

uint getrank_rkmatrix ( pcrkmatrix r )

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

Parameters

r Matrix .

Returns: Maximal rank of , i.e., number of columns of and .

uint getrows_rkmatrix ( pcrkmatrix r )

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

Parameters

r Matrix .

Returns: Number of rows of , i.e., number of rows of .

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

r	Matrix 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

r	Matrix 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

r	Object to be initialized.
rows	Number of rows.
cols	Number of columns.
k	Rank.

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

r	Object to be initialized.
src	Source matrix.
rows	Number of rows.
roff	Row offset, should satisfy `rows+roff<=src->rows`.
cols	Number of columns.
coff	Column 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

alpha	Scaling factor $\alpha$ .
rtrans	Set if is to be used instead of .
r	Matrix .
x	Source vector .
y	Target vector .

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

rows	Number of rows.
cols	Number of columns.
k	Rank.

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

src	Source matrix.
rows	Number of rows.
roff	Row offset, should satisfy `rows+roff<=src->rows`.
cols	Number of columns.
coff	Column 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

R	Low rank matrix .

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

a	Low rank matrix .
b	Low rank matrix .

Returns: Approximation of $\|R_A-R_B\|_2$ .

void random_rkmatrix	(	prkmatrix	r,
		uint	kmax
	)

Fill an rkmatrix with random values.

Parameters

r	Target matrix.
kmax	Maximal 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

r	Target matrix.
rows	New number of rows.
cols	New number of columns.
k	New rank.

void scale_rkmatrix	(	field	alpha,
		prkmatrix	r
	)

Scale an rkmatrix by a factor.

Parameters

alpha	Scaling factor $\alpha$ .
r	Target rkmatrix , 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

r	Target matrix.
k	New rank.

void uninit_rkmatrix ( prkmatrix r )

Uninitialize an rkmatrix object.

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

Parameters

r	Object to be uninitialized.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation