Representation of a hierarchical matrix. More...

Data Structures
struct	_hmatrix
	Representation of $\mathcal{H}$ -matrices. More...

Typedefs
typedef struct _hmatrix	hmatrix
	Representation of a hierarchical matrix.

typedef hmatrix *	phmatrix
	Pointer to a hmatrix object.

typedef const hmatrix *	pchmatrix
	Pointer to constant hmatrix object.

Functions
phmatrix	init_hmatrix (phmatrix hm, pccluster rc, pccluster cc)
	Initialize a hmatrix object. More...

void	uninit_hmatrix (phmatrix hm)
	Uninitialize a hmatrix object. More...

phmatrix	new_hmatrix (pccluster rc, pccluster cc)
	Create a new hmatrix object. More...

phmatrix	new_rk_hmatrix (pccluster rc, pccluster cc, uint k)
	Create a new hmatrix object representing a low-rank matrix. More...

phmatrix	new_full_hmatrix (pccluster rc, pccluster cc)
	Create a new hmatrix object representing a standard dense matrix. More...

phmatrix	new_super_hmatrix (pccluster rc, pccluster cc, uint rsons, uint csons)
	Create a new hmatrix object representing a subdivided matrix. More...

phmatrix	clone_hmatrix (pchmatrix src)
	Creates a clone of an existing hmatrix. More...

phmatrix	clonestructure_hmatrix (pchmatrix src)
	Clones the structure of an existing hmatrix. More...

void	update_hmatrix (phmatrix hm)
	Complete the initialisation of a hmatrix object. More...

void	del_hmatrix (phmatrix hm)
	Delete a hmatrix object. More...

void	ref_hmatrix (phmatrix *ptr, phmatrix hm)
	Set a pointer to a hmatrix object, increase its reference counter, and decrease reference counter of original pointer target. More...

void	unref_hmatrix (phmatrix hm)
	Reduce the reference counter of a hmatrix object. More...

size_t	getsize_hmatrix (pchmatrix hm)
	Get size of a given hmatrix object. More...

size_t	getnearsize_hmatrix (pchmatrix hm)
	Get size of the nearfield part of a given hmatrix object. More...

size_t	getfarsize_hmatrix (pchmatrix hm)
	Get size of the farfield part of a given hmatrix object. More...

uint	getrows_hmatrix (pchmatrix a)
	Get the number of rows of a hmatrix . More...

uint	getcols_hmatrix (pchmatrix a)
	Get the number of columns of a hmatrix . More...

void	clear_hmatrix (phmatrix hm)
	Set a hmatrix to zero by clearing all far- and nearfield matrices. More...

void	clear_upper_hmatrix (phmatrix hm, bool strict)
	Set the upper triangular part of a hmatrix to zero by clearing all far- and nearfield matrices. More...

void	copy_hmatrix (pchmatrix src, phmatrix trg)
	Copy a matrix `src` to an existing matrix `dst`. More...

void	identity_hmatrix (phmatrix hm)
	Fill a hmatrix with an identity matrix. More...

void	random_hmatrix (phmatrix hm, uint kmax)
	Fill a hmatrix with random field values. The maximal rank for admissible leaves is determined by `kmax`. More...

phmatrix	build_from_block_hmatrix (pcblock b, uint k)
	Build an hmatrix object from a block tree using a given local rank. More...

pblock	build_from_hmatrix_block (pchmatrix G)
	Build an block tree from an hmatrix. More...

void	mvm_hmatrix_avector (field alpha, bool atrans, pchmatrix a, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha A x$ or $y \gets y + \alpha A^* x$ . More...

void	fastaddeval_hmatrix_avector (field alpha, pchmatrix hm, pcavector xp, pavector yp)
	Matrix-vector multiplication $y \gets y + \alpha A x$ . More...

void	addeval_hmatrix_avector (field alpha, pchmatrix hm, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha A x$ . More...

void	fastaddevaltrans_hmatrix_avector (field alpha, pchmatrix hm, pcavector xp, pavector yp)
	Adjoint matrix-vector multiplication $y \gets y + \alpha A^* x$ . More...

void	addevaltrans_hmatrix_avector (field alpha, pchmatrix hm, pcavector x, pavector y)
	Adjoint matrix-vector multiplication $y \gets y + \alpha A^* x$ . More...

void	fastaddevalsymm_hmatrix_avector (field alpha, pchmatrix hm, pcavector xp, pavector yp)
	Matrix-vector multiplication $y \gets y + \alpha A x$ with symmetric matrix . More...

void	addevalsymm_hmatrix_avector (field alpha, pchmatrix hm, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha A x$ with symmetric matrix . More...

phmatrix *	enumerate_hmatrix (pcblock b, phmatrix hm)
	Enumerate hmatrix according to block tree. More...

real	norm2_hmatrix (pchmatrix H)
	Approximate the spectral norm $\\|H\\|_2$ of a matrix . More...

real	norm2diff_hmatrix (pchmatrix a, pchmatrix b)
	Approximate the spectral norm $\\|A-B\\|_2$ of the difference of two matrices and . More...

void	write_cdf_hmatrix (pchmatrix G, const char *name)
	Write a matrix into a NetCDF file. More...

void	write_cdfpart_hmatrix (pchmatrix G, int nc_file, const char *prefix)
	Write a matrix into a NetCDF file. More...

phmatrix	read_cdf_hmatrix (const char *name, pccluster rc, pccluster cc)
	Read a matrix from a NetCDF file. More...

phmatrix	read_cdfpart_hmatrix (int nc_file, const char *prefix, pccluster rc, pccluster cc)
	Read a matrix from a NetCDF file. More...

void	write_cdfcomplete_hmatrix (pchmatrix G, const char *name)
	Write hmatrix to NetCDF file, including cluster trees. More...

phmatrix	read_cdfcomplete_hmatrix (const char *name)
	Read hmatrix from NetCDF file, including cluster trees. More...

void	write_hlib_hmatrix (pchmatrix G, const char *filename)
	Write a matrix into an ASCII file in the old HLib format. More...

phmatrix	read_hlib_hmatrix (const char *filename)
	Read a matrix from an ASCII file in the old HLib format. More...

phmatrix	read_hlibsymm_hmatrix (const char *filename)
	Read a symmetric matrix from an ASCII file in the old HLib format. More...

void	draw_cairo_hmatrix (cairo_t *cr, pchmatrix hm, bool storage, uint levels)
	Draw a hierarchical matrix. More...

void	copy_sparsematrix_hmatrix (psparsematrix sp, phmatrix hm)
	Copy entries of a sparsematrix into a hierarchical matrix. More...

Detailed Description

Representation of a hierarchical matrix.

The hmatrix class is used to represent hierarchical matrices with arbitrary block structures and arbitrary rank distributions.

Function Documentation

void addeval_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha A x$ .

The matrix 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$ .
hm	Matrix .
x	Source vector .
y	Target vector .

void addevalsymm_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha A x$ with symmetric matrix $A$ .

The matrix is multiplied by the source vector $x$ , the result is scaled by $\alpha$ and added to the target vector $y$ . Only the lower triangular part of $A$ is used.

Parameters

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

void addevaltrans_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	x,
		pavector	y
	)

Adjoint matrix-vector multiplication $y \gets y + \alpha A^* x$ .

The matrix 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$ .
hm	Matrix .
x	Source vector .
y	Target vector .

phmatrix build_from_block_hmatrix	(	pcblock	b,
		uint	k
	)

Build an hmatrix object from a block tree using a given local rank.

Remarks: Submatrices for far- and nearfield leaves are created, but their coefficients are not initialized.

Parameters

b	Block tree.
k	Local rank.

Returns: New hmatrix object.

pblock build_from_hmatrix_block ( pchmatrix G )

Build an block tree from an hmatrix.

Parameters

G	Input hmatrix.

Returns: New block tree corresponding to the structure of G.

void clear_hmatrix ( phmatrix hm )

Set a hmatrix to zero by clearing all far- and nearfield matrices.

Parameters

hm	Target matrix.

void clear_upper_hmatrix	(	phmatrix	hm,
		bool	strict
	)

Set the upper triangular part of a hmatrix to zero by clearing all far- and nearfield matrices.

Parameters

hm	Target matrix.
strict	Is set, if only the strict upper triangular part should be cleared.

phmatrix clone_hmatrix ( pchmatrix src )

Creates a clone of an existing hmatrix.

This function creates a clone of an existing hmatrix. I.e. a new hmatrix object is created with the same block structure as the input matrix. Further all rank k matrices and dense matrices are copied to the clone aswell.

Parameters

src	Hmatrix to be cloned.

Returns: Clone of src.

phmatrix clonestructure_hmatrix ( pchmatrix src )

Clones the structure of an existing hmatrix.

This function clones the structure of an existing hmatrix. I.e. a new hmatrix object is created with the same block structure and local ranks as the input matrix. But the matrix entries from src are not copied out to the resulting matrix.

Parameters

src	Hmatrix to be cloned.

Returns: Clone of src.

void copy_hmatrix	(	pchmatrix	src,
		phmatrix	trg
	)

Copy a matrix src to an existing matrix dst.

It is assumed, that dst has exactly the same block structure as src.

Parameters

src	Source matrix.
trg	Target matrix.

void copy_sparsematrix_hmatrix	(	psparsematrix	sp,
		phmatrix	hm
	)

Copy entries of a sparsematrix into a hierarchical matrix.

Copy the entries of a sparsematrix into a hierarchical matrix of the same dimensions. The hierarchical matrix has to be allocated before calling this function.

Remarks: This function is can only be used for a sparsematrix descending of a discretization with FEM and a hierarchical matrix with admissible blocks, which only content zero entries (i.e. no storage is allocated for the rank k matrices).

Parameters

sp	source matrix.
hm	target matrix.

void del_hmatrix ( phmatrix hm )

Delete a hmatrix object.

Releases the storage corresponding to the object. If this hmatrix contains pointers to submatrices, the submatrices are released by unref_hmatrix.

Only objects with hm->refs==0 may be deleted.

Parameters

hm	Object to be deleted.

void draw_cairo_hmatrix	(	cairo_t *	cr,
		pchmatrix	hm,
		bool	storage,
		uint	levels
	)

Draw a hierarchical matrix.

Draw a hierarchical matrix with cairo, optionally the levels can be limited and the strorage of the blocks can be shown.

Parameters

cr	Cairo drawing context.
hm	This hierarchical matrix will be drawn.
storage	If staorage is true, the storage of the blocks in the hierarchical matrix will be shown.
levels	Number of levels of the blockclustertree, which will be drawn.

phmatrix* enumerate_hmatrix	(	pcblock	b,
		phmatrix	hm
	)

Enumerate hmatrix according to block tree.

The hmatrix submatrices are enumerated in an array of size b->desc. The enumeration starts with 0 assigned to the root and then proceeds column-wise starting with b->sons[0] corresponding to the entries 1 to b->sons[0]->desc in the array and ending with b->sons[rsons*csons-1] corresponding to the last b->sons[rsons*csons-1]->desc entries.

Parameters

b	Block tree.
hm	Matrix matching the block structure given by `b`.

Returns: Array of size b->desc containing pointers to the hmatrix objects corresponding to descendants of hm.

void fastaddeval_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	xp,
		pavector	yp
	)

Matrix-vector multiplication $y \gets y + \alpha A x$ .

The matrix 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$ .
hm	Matrix .
xp	Source vector in cluster numbering with respect to `hm->cc`.
yp	Target vector in cluster numbering with respect to `hm->rc`.

void fastaddevalsymm_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	xp,
		pavector	yp
	)

Matrix-vector multiplication $y \gets y + \alpha A x$ with symmetric matrix $A$ .

The matrix is multiplied by the source vector $x$ , the result is scaled by $\alpha$ and added to the target vector $y$ . Only the lower triangular part of $A$ is used.

Parameters

alpha	Scaling factor $\alpha$ .
hm	Matrix .
xp	Source vector in cluster numbering with respect to `hm->cc`.
yp	Target vector in cluster numbering with respect to `hm->rc`.

void fastaddevaltrans_hmatrix_avector	(	field	alpha,
		pchmatrix	hm,
		pcavector	xp,
		pavector	yp
	)

Adjoint matrix-vector multiplication $y \gets y + \alpha A^* x$ .

The matrix 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$ .
hm	Matrix .
xp	Source vector in cluster numbering with respect to `hm->rc`.
yp	Target vector in cluster numbering with respect to `hm->cc`.

uint getcols_hmatrix ( pchmatrix a )

Get the number of columns of a hmatrix $A$ .

Parameters

a Matrix .

Returns: Number of columns of .

size_t getfarsize_hmatrix ( pchmatrix hm )

Get size of the farfield part of a given hmatrix object.

Parameters

hm	$\mathcal{H}$ -matrix object.

Returns: Size of allocated storage for farfield in bytes.

size_t getnearsize_hmatrix ( pchmatrix hm )

Get size of the nearfield part of a given hmatrix object.

Parameters

hm	$\mathcal{H}$ -matrix object.

Returns: Size of allocated storage for nearfield in bytes.

uint getrows_hmatrix ( pchmatrix a )

Get the number of rows of a hmatrix $A$ .

Parameters

a Matrix .

Returns: Number of rows of .

size_t getsize_hmatrix ( pchmatrix hm )

Get size of a given hmatrix object.

Parameters

hm	$\mathcal{H}$ -matrix object.

Returns: Size of allocated storage in bytes.

void identity_hmatrix ( phmatrix hm )

Fill a hmatrix with an identity matrix.

The diagonals entries will be set to one and all other entries will be set to zero. Offdiagonal admissible blocks are set to rank-0-matrices.

Parameters

hm	hmatrix to be filled with the identity matrix.

phmatrix init_hmatrix	(	phmatrix	hm,
		pccluster	rc,
		pccluster	cc
	)

Initialize a hmatrix object.

Parameters

hm	hmatrix object to be initialized.
rc	Row cluster of current hmatrix.
cc	Column cluster of current hmatrix.

Returns: Initialized hmatrix object.

void mvm_hmatrix_avector	(	field	alpha,
		bool	atrans,
		pchmatrix	a,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha A x$ or $y \gets y + \alpha A^* 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$ .
atrans	Set if is to be used instead of .
a	Matrix .
x	Source vector .
y	Target vector .

phmatrix new_full_hmatrix	(	pccluster	rc,
		pccluster	cc
	)

Create a new hmatrix object representing a standard dense matrix.

Allocates storage for the object containing an amatrix object.

Remarks: Should always be matched by a call to del_hmatrix. This call happens automatically if the last object referencing this object (see ref_hmatrix) is deleted.

Parameters

rc	Row cluster.
cc	Column cluster.

Returns: New hmatrix object containing a new amatrix.

phmatrix new_hmatrix	(	pccluster	rc,
		pccluster	cc
	)

Create a new hmatrix object.

Allocates storage for the object and sets the matrix pointers to NULL, representing a zero matrix.

Remarks: Should always be matched by a call to del_hmatrix. This call happens automatically if the last object referencing this object (see ref_hmatrix) is deleted.

Parameters

rc	Row cluster.
cc	Column cluster.

Returns: New hmatrix object.

phmatrix new_rk_hmatrix	(	pccluster	rc,
		pccluster	cc,
		uint	k
	)

Create a new hmatrix object representing a low-rank matrix.

Allocates storage for the object containing an rkmatrix object.

Remarks: Should always be matched by a call to del_hmatrix.

Parameters

rc	Row cluster.
cc	Column cluster.
k	Rank.

Returns: New hmatrix object containing a new rkmatrix.

phmatrix new_super_hmatrix	(	pccluster	rc,
		pccluster	cc,
		uint	rsons,
		uint	csons
	)

Create a new hmatrix object representing a subdivided matrix.

Allocates storage for the object representing a matrix with submatrices. The submatrices are initialized with NULL pointers and have to be set up with ref_hmatrix.

Remarks: Should always be matched by a call to del_hmatrix. This call happens automatically if the last object referencing this object (see ref_hmatrix) is deleted.

Parameters

rc	Row cluster.
cc	Column cluster.
rsons	Number of block rows.
csons	Number of block columns.

Returns: New hmatrix object with submatrices.

real norm2_hmatrix ( pchmatrix H )

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

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

Parameters

H	Hierarchical matrix .

Returns: Approximation of $\|H\|_2$ .

real norm2diff_hmatrix	(	pchmatrix	a,
		pchmatrix	b
	)

Approximate the spectral norm $\|A-B\|_2$ of the difference of two matrices $A$ and $B$ .

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

Parameters

a	Hierarchical matrix .
b	Hierarchical matrix .

Returns: Approximation of $\|A-B\|_2$ .

void random_hmatrix	(	phmatrix	hm,
		uint	kmax
	)

Fill a hmatrix with random field values. The maximal rank for admissible leaves is determined by kmax.

Parameters

hm	hmatrix to be filled with random values.
kmax	Maximal rank for admissble leaves. Random values may lead to a rank lower than `kmax`.

phmatrix read_cdf_hmatrix	(	const char *	name,
		pccluster	rc,
		pccluster	cc
	)

Read a matrix from a NetCDF file.

This function constructs a new hmatrix object using data read from a NetCDF file.

If row and column cluster trees are provided by setting rc and cc, these clusters will be used. If null pointers are given, the function will reconstruct suitable cluster trees from the matrix structure.

Parameters

name	Name of the source file.
rc	Row cluster for the matrix, may be null.
cc	Column cluster for the matrix, may be null.

Returns: Hierarchical matrix.

phmatrix read_cdfcomplete_hmatrix ( const char * name )

Read hmatrix from NetCDF file, including cluster trees.

Parameters

name	File name.

Returns: hmatrix read from file.

phmatrix read_cdfpart_hmatrix	(	int	nc_file,
		const char *	prefix,
		pccluster	rc,
		pccluster	cc
	)

Read a matrix from a NetCDF file.

This function constructs a new hmatrix object using data read from an already open NetCDF file. The names of all dimensions and variables are prefixed with the string prefix in order to allow us to store multiple objects in the same file.

If row and column cluster trees are provided by setting rc and cc, these clusters will be used. If null pointers are given, the function will reconstruct suitable cluster trees from the matrix structure.

Parameters

nc_file	Handle of the NetCDF file.
prefix	String to be put in front of names of dimensions and variables.
rc	Row cluster for the matrix, may be null.
cc	Column cluster for the matrix, may be null.

Returns: Hierarchical matrix.

phmatrix read_hlib_hmatrix ( const char * filename )

Read a matrix from an ASCII file in the old HLib format.

Remarks: Since HLib does not store cluster trees, this function has to reconstruct them from available data. It will always use one-dimensional trees with no permutation.

Parameters

filename Name of the source file.

Returns: Hierarchical matrix reconstructed from file.

phmatrix read_hlibsymm_hmatrix ( const char * filename )

Read a symmetric matrix from an ASCII file in the old HLib format.

Remarks: Since HLib does not store cluster trees, this function has to reconstruct them from available data. It will always use one-dimensional trees with no permutation.

Parameters

filename Name of the source file.

Returns: Hierarchical matrix reconstructed from file.

void ref_hmatrix	(	phmatrix *	ptr,
		phmatrix	hm
	)

Set a pointer to a hmatrix object, increase its reference counter, and decrease reference counter of original pointer target.

Parameters

ptr	Pointer to the phmatrix variable that will be changed.
hm	hmatrix that will be referenced.

void uninit_hmatrix ( phmatrix hm )

Uninitialize a hmatrix object.

Releases the storage corresponding to the object. If this hmatrix contains pointers to submatrices, the submatrices are released by unref_hmatrix.

Only objects with hm->refs==0 may be deleted.

Parameters

hm	Object to be uninitialized.

void unref_hmatrix ( phmatrix hm )

Reduce the reference counter of a hmatrix object.

If the reference counter reaches zero, the object is deleted.

Remarks: Use ref_hmatrix with hm=NULL instead, since this guarantees that the pointer is properly invalidated.

Parameters

hm	hmatrix that will be unreferenced.

void update_hmatrix ( phmatrix hm )

Complete the initialisation of a hmatrix object.

Complete the initialisation of the hmatrix object after all sons have been initialised. The number of the descendants of the H-matrix is computed from the desc fields of its sons.

Parameters

hm	H-matrix to be completed.

void write_cdf_hmatrix	(	pchmatrix	G,
		const char *	name
	)

Write a matrix into a NetCDF file.

Parameters

G	Hierarchical matrix.
name	Name of the target file.

void write_cdfcomplete_hmatrix	(	pchmatrix	G,
		const char *	name
	)

Write hmatrix to NetCDF file, including cluster trees.

Parameters

G	Matrix.
name	File name.

void write_cdfpart_hmatrix	(	pchmatrix	G,
		int	nc_file,
		const char *	prefix
	)

Write a matrix into a NetCDF file.

This function takes an already open NetCDF file and adds the matrix to it, prefixing all dimensions and variables with the given string prefix. This allows us to store multiple objects in the same file.

Parameters

G	Hierarchical matrix.
nc_file	Handle of the NetCDF file.
prefix	String to be put in front of names of dimensions and variables.

void write_hlib_hmatrix	(	pchmatrix	G,
		const char *	filename
	)

Write a matrix into an ASCII file in the old HLib format.

Parameters

G	Hierarchical matrix.
filename	Name of the target file.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation