$\mathcal{DH}^2$ -matrices. More...

Data Structures
struct	_dh2matrix
	Tree structure representing a $\mathcal{DH}^2$ -matrix. More...

Typedefs
typedef struct _dh2matrix	dh2matrix
	$\mathcal{DH}^2$ -matrix.

typedef dh2matrix *	pdh2matrix
	Pointer to a dh2matrix.

typedef const dh2matrix *	pcdh2matrix
	Pointer to a constant dh2matrix.

Functions
pdh2matrix	new_dh2matrix (pdclusterbasis rb, pdclusterbasis cb)
	Create a new empty dh2matrix object. More...

pdh2matrix	new_uniform_dh2matrix (pdclusterbasis rb, uint rd, pdclusterbasis cb, uint cd)
	Create a new dh2matrix object representing an admissible leaf. More...

pdh2matrix	new_full_dh2matrix (pdclusterbasis rb, pdclusterbasis cb)
	Create a new dh2matrix object representing an inadmissible leaf. More...

pdh2matrix	new_super_dh2matrix (pdclusterbasis rb, pdclusterbasis cb, uint rsons, uint csons)
	Create a new dh2matrix object representing a subdivided matrix. More...

void	update_dh2matrix (pdh2matrix h2)
	Update internal data structures after the sons have been modified, e.g., to recompute `desc`. More...

void	del_dh2matrix (pdh2matrix h2)
	Delete a dh2matrix object. More...

pdh2matrix	clone_dh2matrix (pcdh2matrix dh2, pdclusterbasis rb, pdclusterbasis cb)
	Builds a new dh2matrix with the same structure as `dh2` and dclusterbasis `rb` as directional row cluster basis and `cb` for the columns. More...

size_t	getsize_dh2matrix (pcdh2matrix h2)
	Compute the storage size of a dh2matrix, without the cluster bases. More...

size_t	getnearsize_dh2matrix (pcdh2matrix h2)
	Compute the storage size of the inadmissible leaves of a dh2matrix. More...

size_t	getfarsize_dh2matrix (pcdh2matrix h2)
	Compute the storage size of the admissible leaves of a dh2matrix. More...

size_t	gettotalsize_dh2matrix (pcdh2matrix h2)
	Compute the storage size of a dh2matrix, including the cluster bases. More...

uint	getrows_dh2matrix (pcdh2matrix h2)
	Return the number of rows of a dh2matrix. More...

uint	getcols_dh2matrix (pcdh2matrix h2)
	Return the number of columns of a dh2matrix. More...

pdh2matrix	buildfromblock_dh2matrix (pcdblock b, pdclusterbasis rb, pdclusterbasis cb)
	Construct a dh2matrix based on a dblock tree and cluster bases. More...

void	copynear_dh2matrix (pcamatrix G, pdh2matrix Gh)
	Copy nearfield matrices from a given matrix. More...

void	fastaddeval_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector xt, pavector yt)
	Fast matrix-vector multiplication. More...

void	fastaddevaltrans_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector xt, pavector yt)
	Fast adjoint matrix-vector multiplication. More...

void	addeval_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha G x$ . More...

void	addevaltrans_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Adjoint matrix-vector multiplication $y \gets y + \alpha G^* x$ . More...

void	mvm_dh2matrix_avector (field alpha, bool h2trans, pcdh2matrix h2, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha G x$ or $y \gets y + \alpha G^* x$ . More...

void	addeval_parallel_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha G x$ , parallelized version. More...

void	addevaltrans_parallel_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Adjoint matrix-vector multiplication $y \gets y + \alpha G^* x$ , parallelized version. More...

void	slowaddeval_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Matrix-vector multiplication $y \gets y + \alpha G x$ , slow version for debugging, all submatrices are handled independently. More...

void	slowaddevaltrans_dh2matrix_avector (field alpha, pcdh2matrix h2, pcavector x, pavector y)
	Adjoint matrix-vector multiplication $y \gets y + \alpha G^* x$ , slow version for debugging, all submatrices are handled independently. More...

void	expand_dh2matrix (field alpha, pcdh2matrix h2, pamatrix G)
	Add a $\mathcal{DH}^2$ -matrix to a standard matrix, $G \gets G + \alpha \widetilde{G}$ . More...

pdh2matrix *	enumerate_dh2matrix (pdh2matrix h2)
	Enumerate all submatrices of a dh2matrix tree. More...

void	iterate_dh2matrix (pdh2matrix G, uint mname, uint rname, uint cname, uint pardepth, void(pre)(pdh2matrix G, uint mname, uint rname, uint cname, uint pardepth, void data), void(post)(pdh2matrix G, uint mname, uint rname, uint cname, uint pardepth, void data), void *data)
	Apply functions to all submatrices of a dh2matrix tree. More...

real	norm2_dh2matrix (pcdh2matrix DH2)
	Approximate the spectral norm $\\|H\\|_2$ of a matrix . More...

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

void	draw_cairo_dh2matrix (cairo_t *cr, pcdh2matrix G, bool storage, bool ranks, uint levels)
	Draw a dh2matrix tree to a cairo surface. More...

void	resize_coupling_dh2matrix (pdh2matrix A, pdclusteroperator ro, pdclusteroperator co)
	Computes new coupling matrices after the directional cluster basis has been orthogonalized. More...

pdh2matrix	build_projected_dh2matrix (pcdh2matrix dh2, pdclusterbasis rb, pdclusterbasis cb, pdclusteroperator ro, pdclusteroperator co)
	Builds a new $\mathcal{DH}^2$ -matrix approximation of a given $\mathcal{DH}^2$ -matrix with new cluster bases. More...

pdh2matrix	compress_dh2matrix_dh2matrix (pcdh2matrix G, bool rbortho, bool cbortho, pctruncmode tm, real eps)
	Computes a $\mathcal{DH}^2$ -matrix approximation of a $\mathcal{DH}^2$ -matrix. More...

void	truncate_dclusterbasis (pdclusterbasis cold, pdclusterbasis cnew, pdclusteroperator co, pdclusteroperator bco, pctruncmode tm, real eps)
	Computes truncated directional cluster basis and save basis change matrices. More...

Detailed Description

$\mathcal{DH}^2$ -matrices.

Function Documentation

void addeval_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

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

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

void addeval_parallel_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha G x$ , parallelized version.

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

void addevaltrans_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

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

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

void addevaltrans_parallel_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

Adjoint matrix-vector multiplication $y \gets y + \alpha G^* x$ , parallelized version.

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

pdh2matrix build_projected_dh2matrix	(	pcdh2matrix	dh2,
		pdclusterbasis	rb,
		pdclusterbasis	cb,
		pdclusteroperator	ro,
		pdclusteroperator	co
	)

Builds a new $\mathcal{DH}^2$ -matrix approximation of a given $\mathcal{DH}^2$ -matrix with new cluster bases.

The structure and nearfield matrices of the old $\mathcal{DH}^2$ -matrix are copied, new coupling matrices are computed with the basis change matrices saved in the directional cluster operator objects.

Parameters

dh2	Original $\mathcal{DH}^2$ -matrix.
rb	New directional row basis.
ro	dclusteroperator describing the basis change from old row basis `dh2->rb` to the new basis `rb`.
cb	New directional column basis.
co	dclusteroperator describing the basis change from old column basis `dh2->cb` to the new basis `cb`.

Returns: The new $\mathcal{DH}^2$ -matrix approximation.

pdh2matrix buildfromblock_dh2matrix	(	pcdblock	b,
		pdclusterbasis	rb,
		pdclusterbasis	cb
	)

Construct a dh2matrix based on a dblock tree and cluster bases.

Parameters

b	Directional block tree.
rb	Row basis.
cb	Column basis.

Returns: New dh2matrix.

pdh2matrix clone_dh2matrix	(	pcdh2matrix	dh2,
		pdclusterbasis	rb,
		pdclusterbasis	cb
	)

Builds a new dh2matrix with the same structure as dh2 and dclusterbasis rb as directional row cluster basis and cb for the columns.

All coupling and nearfield matrices from dh2 will be copied.

Parameters

dh2	dh2matrix which should be cloned.
rb	Directional row cluster basis for the clone.
cb	Directional column cluster basis for the clone.

Returns: New dh2matrix with the same structure and submatricies as dh2.

pdh2matrix compress_dh2matrix_dh2matrix	(	pcdh2matrix	G,
		bool	rbortho,
		bool	cbortho,
		pctruncmode	tm,
		real	eps
	)

Computes a $\mathcal{DH}^2$ -matrix approximation of a $\mathcal{DH}^2$ -matrix.

Parameters

G	Source dh2matrix .
rbortho	Set if the original row basis is orthogonal, this allows the algorithm to avoid computing row weights.
cbortho	Set if the original column basis is orthogonal, this allows the algorithm to avoid computing column weights.
tm	Truncation mode.
eps	Truncation accuracy.

Returns: $\mathcal{DH}^2$ -matrix approximation of .

void copynear_dh2matrix	(	pcamatrix	G,
		pdh2matrix	Gh
	)

Copy nearfield matrices from a given matrix.

If we approximate a given dense matrix $G$ by a $\mathcal{DH}^2$ -matrix, we can copy the nearfield matrices directly from $G$ instead of recomputing them.

Parameters

G	Source matrix .
Gh	Target $\mathcal{DH}^2$ -matrix.

void del_dh2matrix ( pdh2matrix h2 )

Delete a dh2matrix object.

Parameters

h2	Object to be deleted.

void draw_cairo_dh2matrix	(	cairo_t *	cr,
		pcdh2matrix	G,
		bool	storage,
		bool	ranks,
		uint	levels
	)

Draw a dh2matrix tree to a cairo surface.

Parameters

cr	Cairo surface to be drawn to.
G	Matrix to be drawn.
storage	Set if the storage requirements of the leaf submatrices are to be displayed.
ranks	Flag that indicates if the size of the row and column cluster should be depicted into the graphic.
levels	Number of levels of the dh2matrix that should be drawn. For `level==0`, all levels will be drawn.

pdh2matrix* enumerate_dh2matrix ( pdh2matrix h2 )

Enumerate all submatrices of a dh2matrix tree.

The root is placed at the beginning of the array, followed by the enumerations of the sons in column-major order.

Parameters

h2 Matrix.

Returns: Array of h2->desc pointers to all submatrices of h2.

void expand_dh2matrix	(	field	alpha,
		pcdh2matrix	h2,
		pamatrix	G
	)

Add a $\mathcal{DH}^2$ -matrix to a standard matrix, $G \gets G + \alpha \widetilde{G}$ .

Parameters

alpha	Scaling factor $\alpha$ .
h2	Matrix $\widetilde{G}$ .
G	Target matrix .

void fastaddeval_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	xt,
		pavector	yt
	)

Fast matrix-vector multiplication.

This function handles the coupling phase of the matrix-vector multiplication. It is assumed that the transformed input vector is provided in $xt$ , and the results are added to the output vector $yt$ .

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
xt	Transformed input vector $\widehat{x}$ as computed by forward_dclusterbasis.
yt	Transformed output vector $\widehat{y}$ as required by backward_dclusterbasis.

void fastaddevaltrans_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	xt,
		pavector	yt
	)

Fast adjoint matrix-vector multiplication.

This function handles the coupling phase of the matrix-vector multiplication. It is assumed that the transformed input vector is provided in $xt$ , and the results are added to the output vector $yt$ .

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
xt	Transformed input vector $\widehat{x}$ as computed by forward_dclusterbasis.
yt	Transformed output vector $\widehat{y}$ as required by backward_dclusterbasis.

uint getcols_dh2matrix ( pcdh2matrix h2 )

Return the number of columns of a dh2matrix.

Parameters

h2 Matrix

Returns: Number of columns

size_t getfarsize_dh2matrix ( pcdh2matrix h2 )

Compute the storage size of the admissible leaves of a dh2matrix.

Parameters

h2 Matrix.

Returns: Farfield storage size in bytes.

size_t getnearsize_dh2matrix ( pcdh2matrix h2 )

Compute the storage size of the inadmissible leaves of a dh2matrix.

Parameters

h2 Matrix.

Returns: Nearfield storage size in bytes.

uint getrows_dh2matrix ( pcdh2matrix h2 )

Return the number of rows of a dh2matrix.

Parameters

h2 Matrix.

Returns: Number of rows.

size_t getsize_dh2matrix ( pcdh2matrix h2 )

Compute the storage size of a dh2matrix, without the cluster bases.

Parameters

h2 Matrix.

Returns: Storage size in bytes.

size_t gettotalsize_dh2matrix ( pcdh2matrix h2 )

Compute the storage size of a dh2matrix, including the cluster bases.

Parameters

h2 Matrix.

Returns: Storage size in bytes.

void iterate_dh2matrix	(	pdh2matrix	G,
		uint	mname,
		uint	rname,
		uint	cname,
		uint	pardepth,
		void()(pdh2matrix G, uint mname, uint rname, uint cname, uint pardepth, void data)	pre,
		void()(pdh2matrix G, uint mname, uint rname, uint cname, uint pardepth, void data)	post,
		void *	data
	)

Apply functions to all submatrices of a dh2matrix tree.

The function pre is called before the sons are processed, the function post is called afterwards.

Parameters

G	Matrix.
mname	Number of the submatrix, matching the order used by enumerate_dh2matrix.
rname	Number of the row cluster, matching the order used by enumerate_cluster and enumerate_dclusterbasis.
cname	Number of the column cluster, matching the order used by enumerate_cluster and enumerate_dclusterbasis.
pardepth	Maximal depth for recursive parallelization.
pre	Function to be called before visiting the sons.
post	Function to be called after the sons have been visited.
data	Additional data passed on to `pre` and `post`.

void mvm_dh2matrix_avector	(	field	alpha,
		bool	h2trans,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha G x$ or $y \gets y + \alpha G^* x$ .

Parameters

alpha	Scaling factor $\alpha$ .
h2trans	Set if is to be used instead of .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

pdh2matrix new_dh2matrix	(	pdclusterbasis	rb,
		pdclusterbasis	cb
	)

Create a new empty dh2matrix object.

Parameters

rb	Row cluster basis.
cb	Column cluster basis.

Returns: New object.

pdh2matrix new_full_dh2matrix	(	pdclusterbasis	rb,
		pdclusterbasis	cb
	)

Create a new dh2matrix object representing an inadmissible leaf.

Parameters

rb	Row cluster basis.
cb	Column cluster basis.

Returns: New object.

pdh2matrix new_super_dh2matrix	(	pdclusterbasis	rb,
		pdclusterbasis	cb,
		uint	rsons,
		uint	csons
	)

Create a new dh2matrix object representing a subdivided matrix.

Parameters

rb	Row cluster basis.
cb	Column cluster basis.
rsons	Number of row sons.
csons	Number of column sons.

Returns: New object.

pdh2matrix new_uniform_dh2matrix	(	pdclusterbasis	rb,
		uint	rd,
		pdclusterbasis	cb,
		uint	cd
	)

Create a new dh2matrix object representing an admissible leaf.

Parameters

rb	Row cluster basis.
rd	Row direction (for directional cluster basis `rb`).
cb	Column cluster basis.
cd	Column direction (for directional cluster basis `cb`).

Returns: New object.

real norm2_dh2matrix ( pcdh2matrix DH2 )

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

DH2	Directional $\mathcal H^2$ matrix .

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

real norm2diff_dh2matrix	(	pcdh2matrix	a,
		pcdh2matrix	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	D $\mathcal H^2$ matrix .
b	D $\mathcal H^2$ matrix .

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

void resize_coupling_dh2matrix	(	pdh2matrix	A,
		pdclusteroperator	ro,
		pdclusteroperator	co
	)

Computes new coupling matrices $S_b$ after the directional cluster basis has been orthogonalized.

Computes the new coupling matrices $S_b$ for the orthogonal directional cluster basis for all admissible directional blocks $ b = (t,s) $ with direction $\iota_{t}$ through $R_{t,\iota_{t}} S_b R^{*}_{s,\iota_{t}}$ , where $R_{t, \iota_{t}}$ is the matrix describing the basis change of $V_{t, \iota_{t}}$ . This basis change matrices are computed during the orthogonalization and saved in a dclusteroperator object.

Remarks: Should be called after orthogonalize a given directional cluster basis with ortho_dclusterbasis.

Parameters

A	Directional $\mathcal{H}^2$ -matrix including the coupling matrices.
ro	Directional cluster operator for the directional row cluster basis.
co	Directional cluster operator for the directional column cluster basis.

void slowaddeval_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

Matrix-vector multiplication $y \gets y + \alpha G x$ , slow version for debugging, all submatrices are handled independently.

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

void slowaddevaltrans_dh2matrix_avector	(	field	alpha,
		pcdh2matrix	h2,
		pcavector	x,
		pavector	y
	)

Adjoint matrix-vector multiplication $y \gets y + \alpha G^* x$ , slow version for debugging, all submatrices are handled independently.

Parameters

alpha	Scaling factor $\alpha$ .
h2	$\mathcal{DH}^2$ -matrix .
x	Input vector .
y	Output vector .

void truncate_dclusterbasis	(	pdclusterbasis	cold,
		pdclusterbasis	cnew,
		pdclusteroperator	co,
		pdclusteroperator	bco,
		pctruncmode	tm,
		real	eps
	)

Computes truncated directional cluster basis and save basis change matrices.

For every cluster $ t $ and direction $\iota$ a singular value decomposition of the directional cluster basis multiplied by a weight matrix stored in co will be made. Then the smallest possible rank $ k_new $ for the desired accuracy and truncation mode is selected. The new directional cluster basis and transfer matrices for this rank are computed and saved in the dclusterbasis object cnew. Matrices describing the basis change are stored in bco.

Parameters

cold	Old dclusterbasis object.
cnew	dclusterbasis object for the truncated cluster basis.
co	dclusteroperator object including weight matrices.
bco	Directional cluster operator for saving basis change matrices.
tm	truncmode object for applied mode of truncation.
eps	Real value used as accuracy for the truncation.

void update_dh2matrix ( pdh2matrix h2 )

Update internal data structures after the sons have been modified, e.g., to recompute desc.

Parameters

h2 Matrix.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation