Representation of cluster bases for $\mathcal{H}^2$ -matrices. More...

Data Structures
struct	_clusterbasis
	Representation of a cluster basis. More...

Typedefs
typedef struct _clusterbasis	clusterbasis
	Representation of a cluster basis.

typedef clusterbasis *	pclusterbasis
	Pointer to clusterbasis object.

typedef const clusterbasis *	pcclusterbasis
	Pointer to constant clusterbasis object.

Functions
pclusterbasis	init_clusterbasis (pclusterbasis cb, pccluster t)
	Initialize a clusterbasis object. More...

pclusterbasis	init_leaf_clusterbasis (pclusterbasis cb, pccluster t)
	Initialize a clusterbasis object for a leaf. More...

pclusterbasis	init_sub_clusterbasis (pclusterbasis cb, pclusterbasis src, pccluster t, uint off)
	Initialize a clusterbasis object representing a leaf son cluster for a leaf cluster basis. More...

void	uninit_clusterbasis (pclusterbasis cb)
	Uninitializes a clusterbasis object. More...

pclusterbasis	new_clusterbasis (pccluster t)
	Create a new clusterbasis object. More...

pclusterbasis	new_leaf_clusterbasis (pccluster t)
	Create a new clusterbasis object for a leaf. More...

void	del_clusterbasis (pclusterbasis cb)
	Delete a clusterbasis object. More...

void	ref_clusterbasis (pclusterbasis *ptr, pclusterbasis cb)
	Set a pointer to a clusterbasis object, increase its reference counter, and decrease reference counter of original pointer target. More...

void	unref_clusterbasis (pclusterbasis cb)
	Reduce the reference counter of a clusterbasis object. More...

void	update_clusterbasis (pclusterbasis cb)
	Updates bookkeeping information, e.g., `cb->ktree,` for a clusterbasis object after its sons have been altered. More...

void	update_tree_clusterbasis (pclusterbasis cb)
	Updates bookkeeping information, e.g., `cb->ktree,` for a clusterbasis object and all its descendants. More...

void	resize_clusterbasis (pclusterbasis cb, uint k)
	Change the rank of a cluster basis and resize `cb->V,` `cb->son[i]->E` is resized for all sons. More...

void	setrank_clusterbasis (pclusterbasis cb, uint k)
	Change the rank of a cluster basis and resize `cb->V`, while `cb->son[i]->E` is resized for all sons. More...

pclusterbasis	build_from_cluster_clusterbasis (pccluster t)
	Construct a clusterbasis from a cluster tree. More...

pclusterbasis	clone_clusterbasis (pcclusterbasis cb)
	Create a copy of a clusterbasis. More...

pclusterbasis	clonestructure_clusterbasis (pcclusterbasis cb)
	Copy the tree structure of a clusterbasis. More...

uint	getactives_clusterbasis ()
	Get number of active clusterbasis objects. More...

size_t	getsize_clusterbasis (pcclusterbasis cb)
	Get the size of a given clusterbasis object. More...

void	clear_weight_clusterbasis (pclusterbasis cb)
	Delete all weight matrices of the clusterbasis and its descendants. More...

void	iterate_clusterbasis (pcclusterbasis cb, uint cbname, void(pre)(pcclusterbasis cb, uint cbname, void data), void(post)(pcclusterbasis cb, uint cbname, void data), void *data)
	Hierarchical iterator for a clusterbasis. More...

void	iterate_parallel_clusterbasis (pcclusterbasis cb, uint cbname, uint pardepth, void(pre)(pcclusterbasis cb, uint cbname, void data), void(post)(pcclusterbasis cb, uint cbname, void data), void *data)
	Parallel hierarchical iterator for a clusterbasis. More...

pclusterbasis *	enumerate_clusterbasis (pccluster t, pclusterbasis cb)
	Enumerate clusterbasis according to cluster tree. More...

pavector	new_coeffs_clusterbasis_avector (pcclusterbasis cb)
	Create coefficient vector for cluster basis. More...

void	forward_clusterbasis_avector (pcclusterbasis cb, pcavector x, pavector xt)
	Forward transformation. More...

void	forward_parallel_clusterbasis_avector (pcclusterbasis cb, pcavector x, pavector xt, uint pardepth)
	Parallel forward transformation. More...

void	forward_nopermutation_clusterbasis_avector (pcclusterbasis cb, pcavector xp, pavector xt)
	Forward transformation for vectors using cluster numbering. More...

void	forward_notransfer_clusterbasis_avector (pcclusterbasis cb, pcavector x, pavector xt)
	Forward transformation without transfer matrices. More...

void	backward_clusterbasis_avector (pcclusterbasis cb, pavector yt, pavector y)
	Backward transformation. More...

void	backward_parallel_clusterbasis_avector (pcclusterbasis cb, pavector yt, pavector y, uint pardepth)
	Parallel backward transformation. More...

void	backward_nopermutation_clusterbasis_avector (pcclusterbasis cb, pavector yt, pavector yp)
	Backward transformation for vectors in cluster numbering. More...

void	backward_notransfer_clusterbasis_avector (pcclusterbasis cb, pavector yt, pavector y)
	Backward transformation without transfer matrices. More...

void	compress_clusterbasis_avector (pcclusterbasis cb, pcavector xp, pavector xt)
	Compute $\hat x_t = V_t^* x$ . More...

void	expand_clusterbasis_avector (pcclusterbasis cb, pavector yt, pavector yp)
	Add $V_t \hat y_t$ to target vector . More...

void	compress_clusterbasis_amatrix (pcclusterbasis cb, pcamatrix Xp, pamatrix Xt)
	Compute $\widehat{X}_t = V_t^* X$ . More...

void	compress_parallel_clusterbasis_amatrix (pcclusterbasis cb, pcamatrix Xp, pamatrix Xt, uint pardepth)
	Compute $\widehat{X}_t = V_t^* X$ . More...

void	forward_clusterbasis_amatrix (pcclusterbasis cb, pcamatrix Xp, pamatrix Xt)
	Matrix forward transformation. More...

void	forward_clusterbasis_trans_amatrix (pcclusterbasis cb, pcamatrix Xp, pamatrix Xt)
	Adjoint matrix forward transformation. More...

void	backward_clusterbasis_amatrix (pcclusterbasis cb, pamatrix Yt, pamatrix Yp)
	Matrix backward transformation. More...

void	backward_clusterbasis_trans_amatrix (pcclusterbasis cb, pamatrix Yt, pamatrix Yp)
	Adjoint matrix backward transformation. More...

void	addeval_clusterbasis_avector (field alpha, pcclusterbasis cb, pcavector yc, pavector yp)
	Compute $y \gets y + \alpha V_t \hat y_t$ . More...

void	addevaltrans_clusterbasis_avector (field alpha, pcclusterbasis cb, pcavector xp, pavector xc)
	Compute $\hat y_t \gets \hat y_t + \alpha V_t^* y$ . More...

void	ortho_clusterbasis (pclusterbasis cb, pclusteroperator co)
	Orthogonalize a cluster basis. More...

real	check_ortho_clusterbasis (pcclusterbasis cb)
	Check whether a cluster basis is orthogonal. More...

pclusteroperator	weight_clusterbasis_clusteroperator (pcclusterbasis cb, pclusteroperator co)
	Compute weight matrices for a cluster basis. More...

pamatrix	weight_enum_clusterbasis_clusteroperator (pcclusterbasis cb)
	Compute weight matrices for a cluster basis using an iterator over the cluster tree. More...

void	write_cdf_clusterbasis (pcclusterbasis cb, const char *name)
	Write clusterbasis to NetCDF file. More...

void	write_cdfpart_clusterbasis (pcclusterbasis cb, int nc_file, const char *prefix)
	Write clusterbasis to part of NetCDF file. More...

pclusterbasis	read_cdf_clusterbasis (const char *name, pccluster t)
	Read clusterbasis from NetCdf file. More...

pclusterbasis	read_cdfpart_clusterbasis (int nc_file, const char *prefix, pccluster t)
	Read clusterbasis from part of a NetCdf file. More...

Detailed Description

Representation of cluster bases for $\mathcal{H}^2$ -matrices.

The clusterbasis class represents a cluster basis $(V_t)_{t\in{\mathcal T}_{\mathcal{I}}}$ , typically described by transfer matrices $(E_t)_{t\in\mathcal{T}_{\mathcal{I}}}$ as $V_t = \sum_{t'\in\operatorname{sons}(t)} V_{t'} E_{t'}$ for non-leaf clusters $t$ .

Function Documentation

void addeval_clusterbasis_avector	(	field	alpha,
		pcclusterbasis	cb,
		pcavector	yc,
		pavector	yp
	)

Compute $y \gets y + \alpha V_t \hat y_t$ .

Similar to expand_clusterbasis_avector , but allocates and frees the required auxiliary storage automatically.

Parameters

alpha	Scaling factor $\alpha$ .
cb	Cluster basis.
yc	Source vector of dimension `cb->k`.
yp	Target vector of dimension `cb->t->size` using cluster numbering corresponding to `cb->t`.

void addevaltrans_clusterbasis_avector	(	field	alpha,
		pcclusterbasis	cb,
		pcavector	xp,
		pavector	xc
	)

Compute $\hat y_t \gets \hat y_t + \alpha V_t^* y$ .

Similar to compress_clusterbasis_avector , but allocates and frees the required auxiliary storage automatically.

Parameters

alpha	Scaling factor $\alpha$ .
cb	Cluster basis.
xp	Source vector of dimension `cb->t->size` using cluster numbering corresponding to `cb->t`.
xc	Target vector of dimension `cb->k`.

void backward_clusterbasis_amatrix	(	pcclusterbasis	cb,
		pamatrix	Yt,
		pamatrix	Yp
	)

Matrix backward transformation.

Compute $X \gets X + V_t \widehat{X}_t$ for all elements of the cluster basis.

Matrix version of backward_nopermutation_clusterbasis_avector.

Parameters

cb	Cluster basis.
Yt	Source matrix with `cb->ktree` rows, filled with a mix of transformed coefficients and permuted coefficients. The matrix will be overwritten by the function.
Yp	Target matrix using cluster numbering corresponding to `cb->t` in the rows.

void backward_clusterbasis_avector	(	pcclusterbasis	cb,
		pavector	yt,
		pavector	y
	)

Backward transformation.

Compute $y \gets y + V_t \widehat y_t$ for all elements of the cluster basis. This function also adds permuted coefficients contained in yt to the result vector. It can be used to add the result of fastaddeval_h2matrix_avector or fastaddevaltrans_h2matrix_avector to the target vector.

The contents of yt are interpreted as in the function forward_clusterbasis_avector : if cb is not a leaf, the first cb->k rows of yt are coefficients to be multiplied by $V_t$ , followed by cb->son[0]->ktree coefficients for the first son, and cb->son[i]->ktree coefficients for the i-th son, until the last son with i==sons-1 has been reached.

If cb is a leaf, the first cb->k rows of yt are also coefficients to be multiplied by $V_t$ , followed by cb->t->size coefficients in cluster numbering to be added to appropriate entries of the target vector.

Remarks: This function accesses the target vector y via the indices in cb->t->idx, so even if cb corresponds only to a small cluster, y usually has to be a vector corresponding to the root of the cluster tree in the original numbering. In order to work efficiently with subvectors, consider using backward_nopermutation_clusterbasis_avector .

Parameters

cb	Cluster basis.
yt	Source vector of dimension `cb->ktree`, filled with a mix of transformed coefficients and permuted coefficients. This vector will be overwritten by the function.
y	Target vector.

void backward_clusterbasis_trans_amatrix	(	pcclusterbasis	cb,
		pamatrix	Yt,
		pamatrix	Yp
	)

Adjoint matrix backward transformation.

Compute $X^* \gets X^* + V_t \widehat{X}_t$ for all elements of the cluster basis.

Matrix version of backward_nopermutation_clusterbasis_avector.

Parameters

cb	Cluster basis.
Yt	Source matrix with `cb->ktree` rows, filled with a mix of transformed coefficients and permuted coefficients. The matrix will be overwritten by the function.
Yp	Target matrix using cluster numbering corresponding to `cb->t` in the columns.

void backward_nopermutation_clusterbasis_avector	(	pcclusterbasis	cb,
		pavector	yt,
		pavector	yp
	)

Backward transformation for vectors in cluster numbering.

Version of backward_clusterbasis_avector that takes a vector using cluster numbering.

Parameters

cb	Cluster basis.
yt	Source vector of dimension `cb->ktree`, filled with a mix of transformed coefficients and permuted coefficients. This vector will be overwritten by the function.
yp	Target vector of dimension `cb->t->size` using cluster numbering corresponding to `cb->t`.

void backward_notransfer_clusterbasis_avector	(	pcclusterbasis	cb,
		pavector	yt,
		pavector	y
	)

Backward transformation without transfer matrices.

Version of backward_clusterbasis_avector that uses the matrices cb->V for all clusters, not only for leaves.

Remarks: This function is only intended for uniform hierarchical matrices, not for $\mathcal{H}^2$ -matrices.

Parameters

cb	Cluster basis with `cb->V` initialized for all descendants.
yt	Source vector of dimension `cb->ktree`, filled with a mix of transformed coefficients and permuted coefficients. This vector will be overwritten by the function.
y	Target vector.

void backward_parallel_clusterbasis_avector	(	pcclusterbasis	cb,
		pavector	yt,
		pavector	y,
		uint	pardepth
	)

Parallel backward transformation.

Parallel version of backward_clusterbasis_avector.

Parameters

cb	Cluster basis.
yt	Source vector of dimension `cb->ktree`, filled with a mix of transformed coefficients and permuted coefficients. This vector will be overwritten by the function.
y	Target vector.
pardepth	Parallelization depth.

pclusterbasis build_from_cluster_clusterbasis ( pccluster t )

Construct a clusterbasis from a cluster tree.

All ranks will be set to zero.

Parameters

t	Root cluster.

Returns: New root clusterbasis object following the structure of the cluster tree.

real check_ortho_clusterbasis ( pcclusterbasis cb )

Check whether a cluster basis is orthogonal.

Returns the maximum of $\|V_t^* V_t - I\|_F$ (for leaf clusters) and $\|\widehat{V}_t^* \widehat{V}_t - I\|_F$ (for non-leaf clusters). If the result is significantly larger than machine eps, the cluster basis should not be considered orthogonal.

Parameters

cb	Cluster basis.

Returns: Returns a measure for the orthogonality of the clusterbasis cb.

void clear_weight_clusterbasis ( pclusterbasis cb )

Delete all weight matrices of the clusterbasis and its descendants.

Parameters

cb	Target clusterbasis object.

pclusterbasis clone_clusterbasis ( pcclusterbasis cb )

Create a copy of a clusterbasis.

All sons are copied as well, including all coefficients.

Parameters

cb	Source clusterbasis.

Returns: Full copy of cb.

pclusterbasis clonestructure_clusterbasis ( pcclusterbasis cb )

Copy the tree structure of a clusterbasis.

All sons are copied as well. Coefficients are not copied, all ranks of the new clusterbasis are set to zero.

Parameters

cb	Source clusterbasis.

Returns: Structure copy of cb.

void compress_clusterbasis_amatrix	(	pcclusterbasis	cb,
		pcamatrix	Xp,
		pamatrix	Xt
	)

Compute $\widehat{X}_t = V_t^* X$ .

Version of compress_clusterbasis_avector that works for matrices instead of vectors, applying the transformation to all columns simultaneously.

Parameters

cb	Cluster basis.
Xp	Source matrix using cluster numbering corresponding to `cb->t` in the rows.
Xt	Target vector with `cb->kbranch` rows. Its first `cb->k` rows will be filled by the transformed coefficients.

void compress_clusterbasis_avector	(	pcclusterbasis	cb,
		pcavector	xp,
		pavector	xt
	)

Compute $\hat x_t = V_t^* x$ .

Similar to forward_nopermutation_clusterbasis_avector , this function computes $\hat x_t = V_t^* x$ using the transfer matrices $E_t$ and the leaf matrices $V_t$ .

It differs from forward_nopermutation_clusterbasis_avector in that $\hat x_t$ is returned only for the root cluster, not for its descendants. This allows the function to reduce auxiliary storage requirements by re-using storage among different branches of the cluster tree.

Parameters

cb	Cluster basis.
xp	Source vector using cluster numbering corresponding to `cb->t`.
xt	Target vector of dimension `cb->kbranch`. Its first `cb->k` rows will be filled by the transformed coefficients.

void compress_parallel_clusterbasis_amatrix	(	pcclusterbasis	cb,
		pcamatrix	Xp,
		pamatrix	Xt,
		uint	pardepth
	)

Compute $\widehat{X}_t = V_t^* X$ .

Parallel version of compress_clusterbasis_amatrix.

Parameters

cb	Cluster basis.
Xp	Source matrix using cluster numbering corresponding to `cb->t` in the rows.
Xt	Target vector with `cb->kbranch` rows. Its first `cb->k` rows will be filled by the transformed coefficients.
pardepth	Parallelization depth

void del_clusterbasis ( pclusterbasis cb )

Delete a clusterbasis object.

Releases the storage corresponding to the object. If this clusterbasis references sons, these sons are unreferenced.

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

Parameters

cb	Object to be deleted.

pclusterbasis* enumerate_clusterbasis	(	pccluster	t,
		pclusterbasis	cb
	)

Enumerate clusterbasis according to cluster tree.

The clusterbasis elements are enumerated in an array of size t->desc. The enumeration starts with 0 assigned to the root and then proceeds with cb->son[0] corresponding to the entries 1 to t->son[0]->desc in the array and ending with cb->son[sons-1] corresponding to the last t->son[sons-1]->desc entries.

Parameters

t	Cluster tree.
cb	Cluster basis matching the cluster tree given by `t`.

Returns: Array of size t->desc containing pointers to the clusterbasis objects corresponding to cb and its descendants.

void expand_clusterbasis_avector	(	pcclusterbasis	cb,
		pavector	yt,
		pavector	yp
	)

Add $V_t \hat y_t$ to target vector $y$ .

Similar to backward_nopermutation_clusterbasis_avector, this function computes $y \gets y + V_t \hat y_t$ using the transfer matrices $E_t$ and the leaf matrices $V_t$ .

It differs from forward_nopermutation_clusterbasis_avector in that only $V_t \hat y_t$ is added, not the contributions of the descendants. This allows the function to reduce auxiliary storage requirements by re-using storage among different branches of the cluster tree.

Parameters

cb	Cluster basis.
yt	Target vector of dimension `cb->kbranch`. Its first `cb->k` rows contain transformed coefficients.
yp	Source vector using cluster numbering corresponding to `cb->t`.

void forward_clusterbasis_amatrix	(	pcclusterbasis	cb,
		pcamatrix	Xp,
		pamatrix	Xt
	)

Matrix forward transformation.

Compute $\widehat{X}_t = V_t^* X$ for all elements of the cluster basis.

Matrix version of forward_nopermutation_clusterbasis_avector.

Parameters

cb	Cluster basis.
Xp	Source matrix using cluster numbering corresponding to `cb->t` in the rows.
Xt	Target matrix with `cb->ktree` rows, will be filled with a mix of transformed coefficients and permuted coefficients.

void forward_clusterbasis_avector	(	pcclusterbasis	cb,
		pcavector	x,
		pavector	xt
	)

Forward transformation.

Compute $\hat x_t = V_t^* x$ for all elements of the cluster basis. This function also stores the permuted coefficients corresponding to the leaves of the cluster basis in the result, preparing all the necessary information for the multiplication phase realized in fastaddeval_h2matrix_avector and fastaddevaltrans_h2matrix_avector.

If cb is not a leaf, the first cb->k rows of xt are filled with $\hat x_t = V_t^* x$ . The following cb->son[0]->ktree entries are filled with the coefficients for the first son, proceeding until the last cb->son[sons-1]->ktree entries are filled with the coefficients for the last son.

If cb is a leaf, the first cb->k rows of xt are also filled with $\hat x_t = V_t^* x$ . The following cb->t->size rows are filled with the coefficients of the original vector x using the cluster numbering of cb->t.

Remarks: This function accesses the source vector x via the indices in cb->t->idx, so even if cb corresponds only to a small cluster, x usually has to be a vector corresponding to the root of the cluster tree in the original numbering. In order to work efficiently with subvectors, consider using forward_nopermutation_clusterbasis_avector .

Parameters

cb	Cluster basis.
x	Source vector.
xt	Target vector of dimension `cb->ktree`, will be filled with a mix of transformed coefficients and permuted coefficients.

void forward_clusterbasis_trans_amatrix	(	pcclusterbasis	cb,
		pcamatrix	Xp,
		pamatrix	Xt
	)

Adjoint matrix forward transformation.

Compute $\widehat{X}_t = V_t^* X^*$ for all elements of the cluster basis.

Matrix version of forward_nopermutation_clusterbasis_avector.

Parameters

cb	Cluster basis.
Xp	Source matrix using cluster numbering corresponding to `cb->t` in the columns.
Xt	Target matrix with `cb->ktree` rows, will be filled with a mix of transformed coefficients and permuted coefficients.

void forward_nopermutation_clusterbasis_avector	(	pcclusterbasis	cb,
		pcavector	xp,
		pavector	xt
	)

Forward transformation for vectors using cluster numbering.

Version of forward_clusterbasis_avector that takes a vector using cluster numbering.

Parameters

cb	Cluster basis.
xp	Source vector of dimension `cb->t->size` using cluster numbering corresponding to `cb->t`.
xt	Target vector of dimension `cb->ktree`, will be filled with a mix of transformed coefficients and permuted coefficients.

void forward_notransfer_clusterbasis_avector	(	pcclusterbasis	cb,
		pcavector	x,
		pavector	xt
	)

Forward transformation without transfer matrices.

Version of forward_clusterbasis_avector that uses the matrices cb->V for all clusters, not only for leaves.

Remarks: This function is only intended for uniform hierarchical matrices, not for $\mathcal{H}^2$ -matrices.

Parameters

cb	Cluster basis with `cb->V` initialized for all descendants.
x	Source vector.
xt	Target vector of dimension `cb->ktree`, will be filled with a mix of transformed coefficients and permuted coefficients.

void forward_parallel_clusterbasis_avector	(	pcclusterbasis	cb,
		pcavector	x,
		pavector	xt,
		uint	pardepth
	)

Parallel forward transformation.

Parallel version of forward_clusterbasis_avector.

Parameters

cb	Cluster basis.
x	Source vector.
xt	Target vector of dimension `cb->ktree`, will be filled with a mix of transformed coefficients and permuted coefficients.
pardepth	Parallelization depth.

uint getactives_clusterbasis ( )

Get number of active clusterbasis objects.

Returns: Number of active clusterbasis objects.

size_t getsize_clusterbasis ( pcclusterbasis cb )

Get the size of a given clusterbasis object.

Yields the total size of this object and all its descendants.

Parameters

cb	clusterbasis root.

Returns: Size of allocated storage in bytes.

pclusterbasis init_clusterbasis	(	pclusterbasis	cb,
		pccluster	t
	)

Initialize a clusterbasis object.

Sets up the components of the object. If t is not a leaf, the array son is allocated, otherwise it is set to null.

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

Parameters

cb	Object to be initialized.
t	Corresponding cluster.

Returns: Initialized clusterbasis object.

pclusterbasis init_leaf_clusterbasis	(	pclusterbasis	cb,
		pccluster	t
	)

Initialize a clusterbasis object for a leaf.

Sets up the components of the object. Sets son to null. If t->sons>0, this yields a partial cluster basis.

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

Parameters

cb	Object to be initialized.
t	Corresponding cluster.

Returns: Initialized clusterbasis object.

pclusterbasis init_sub_clusterbasis	(	pclusterbasis	cb,
		pclusterbasis	src,
		pccluster	t,
		uint	off
	)

Initialize a clusterbasis object representing a leaf son cluster for a leaf cluster basis.

Sets up the components of the object, making V a submatrix of src->V. Sets son to null. If t->sons>0, this yields a partial cluster basis.

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

Parameters

cb	Object to be initialized.
src	Source cluster basis.
t	Corresponding cluster.
off	Row offset in `src->V,` should be number of elements of preceding sons.

Returns: Initialized clusterbasis object.

void iterate_clusterbasis	(	pcclusterbasis	cb,
		uint	cbname,
		void()(pcclusterbasis cb, uint cbname, void data)	pre,
		void()(pcclusterbasis cb, uint cbname, void data)	post,
		void *	data
	)

Hierarchical iterator for a clusterbasis.

Iterate over the cluster basis and all its descendants. The pre function is called for each element before its descendants are processed, the post function is called afterwards.

cbname will take values between cbname and cbname+cb->t->sons-1, where cbname is interpreted as the index of the root cb, while the indices of the first son start at cbname+1, the indices of the second at cbname+1+cb->t->son[0]->desc, and so on.

Parameters

cb	Root of the cluster basis tree.
cbname	Number of the root.
pre	Function to be called before the descendants of `cb` are processed.
post	Function to be called after the descentants of `cb` have been processed.
data	Additional data passed on to `pre` and `post`.

void iterate_parallel_clusterbasis	(	pcclusterbasis	cb,
		uint	cbname,
		uint	pardepth,
		void()(pcclusterbasis cb, uint cbname, void data)	pre,
		void()(pcclusterbasis cb, uint cbname, void data)	post,
		void *	data
	)

Parallel hierarchical iterator for a clusterbasis.

Iterate over the cluster basis and all its descendants. The pre function is called for each element before its descendants are processed, the post function is called afterwards.

cbname will take values between cbname and cbname+cb->t->sons-1, where cbname is interpreted as the index of the root cb, while the indices of the first son start at cbname+1, the indices of the second at cbname+1+cb->t->son[0]->desc, and so on.

Parameters

cb	Root of the cluster basis tree.
cbname	Number of the root.
pardepth	Parallelization depth.
pre	Function to be called before the descendants of `cb` are processed.
post	Function to be called after the descentants of `cb` have been processed.
data	Additional data passed on to `pre` and `post`.

pclusterbasis new_clusterbasis ( pccluster t )

Create a new clusterbasis object.

Allocates storage for the object and sets up its components.

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

Parameters

t	Corresponding cluster.

Returns: Returns the newly created clusterbasis object.

pavector new_coeffs_clusterbasis_avector ( pcclusterbasis cb )

Create coefficient vector for cluster basis.

Creates a vector of dimension cb->ktree to hold the coefficients computed by forward_clusterbasis_avector and expected by backward_clusterbasis_avector.

Parameters

cb	Cluster basis.

Returns: Coefficient vector of size cb->ktree.

pclusterbasis new_leaf_clusterbasis ( pccluster t )

Create a new clusterbasis object for a leaf.

Allocates storage for the object and sets up its components.

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

Parameters

t	Corresponding cluster.

Returns: Returns the newly created clusterbasis object.

void ortho_clusterbasis	(	pclusterbasis	cb,
		pclusteroperator	co
	)

Orthogonalize a cluster basis.

Replace a given cluster basis $(V_t)_{t\in\ct}$ by an orthogonal clusterbasis $(Q_t)_{t\in\ct}$ such that $V_t = Q_t R_t$ holds for suitable matrices $(R_t)_{t\in\ct}$ .

Parameters

cb	Original cluster basis $(V_t)_{t\in\ct}$ . Will be overwritten by the orthogonal basis $(Q_t)_{t\in\ct}$ .
co	If not null, will be filled with the matrices $(R_t)_{t\in\ct}$ describing the basis change from the old to the new basis. The structure of this cluster operator has to match the structure of the cluster basis, you might consider using build_from_clusterbasis_clusteroperator

pclusterbasis read_cdf_clusterbasis	(	const char *	name,
		pccluster	t
	)

Read clusterbasis from NetCdf file.

Parameters

name	File name.
t	Root cluster for cluster basis.

Returns: Cluster basis read from file.

pclusterbasis read_cdfpart_clusterbasis	(	int	nc_file,
		const char *	prefix,
		pccluster	t
	)

Read clusterbasis from part of a NetCdf file.

Parameters

nc_file	File handle.
prefix	Prefix for variable names.
t	Root cluster for cluster basis.

Returns: Cluster basis read from file.

void ref_clusterbasis	(	pclusterbasis *	ptr,
		pclusterbasis	cb
	)

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

Parameters

ptr	Pointer to the pclusterbasis variable that will be changed.
cb	clusterbasis that will be referenced.

void resize_clusterbasis	(	pclusterbasis	cb,
		uint	k
	)

Change the rank of a cluster basis and resize cb->V, cb->son[i]->E is resized for all sons.

Remarks: cb->E is not resized, since this is in most standard algorithms a task for the father cluster.

Parameters

cb	Cluster basis that will be changed.
k	New rank, i.e., number of columns of `V` or `cb->son[i]->E`.

void setrank_clusterbasis	(	pclusterbasis	cb,
		uint	k
	)

Change the rank of a cluster basis and resize cb->V, while cb->son[i]->E is resized for all sons.

Remarks: cb->E is not resized, since this is in most standard algorithms a task for the father cluster.

Parameters

cb	Cluster basis that will be changed.
k	New rank, i.e., number of columns of `V` or `cb->son[i]->E`.

void uninit_clusterbasis ( pclusterbasis cb )

Uninitializes a clusterbasis object.

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

If this clusterbasis references sons, these sons are unreferences.

Only objects with cb->refs==0 may be uninitialized.

Parameters

cb	Object to be uninitialized.

void unref_clusterbasis ( pclusterbasis cb )

Reduce the reference counter of a clusterbasis object.

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

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

Parameters

cb	clusterbasis that will be unreferenced.

void update_clusterbasis ( pclusterbasis cb )

Updates bookkeeping information, e.g., cb->ktree, for a clusterbasis object after its sons have been altered.

Remarks: This function will not update the sons recursively. See update_tree_clusterbasis if you really need to do this.

Parameters

cb	clusterbasis that will be updated.

void update_tree_clusterbasis ( pclusterbasis cb )

Updates bookkeeping information, e.g., cb->ktree, for a clusterbasis object and all its descendants.

Remarks: If you only want to update cb itself, consider using update_clusterbasis.

Parameters

cb	Root of the clusterbasis tree that will be updated.

pclusteroperator weight_clusterbasis_clusteroperator	(	pcclusterbasis	cb,
		pclusteroperator	co
	)

Compute weight matrices for a cluster basis.

Computes matrices $(R_t)_{t\in\mathcal{T}_{\mathcal{I}}}$ for all clusters such that $\|V_t \hat x_t\|_2 = \|R_t \hat x_t\|_2$ holds for all $\hat x_t$ .

Parameters

cb	Cluster basis $(V_t)_{t\in{\mathcal T}_{\mathcal{I}}}$ .
co	clusteroperator structure matching the tree of `cb`, will be overwritten with weight matrices. A simple way to set up this clusteroperator it to use build_from_clusterbasis_clusteroperator.

Returns: The clusteroperator co.

pamatrix weight_enum_clusterbasis_clusteroperator ( pcclusterbasis cb )

Compute weight matrices for a cluster basis using an iterator over the cluster tree.

Computes matrices $(R_t)_{t\in\mathcal{T}_{\mathcal{I}}}$ for all clusters such that $\|V_t \hat x_t\|_2 = \|R_t \hat x_t\|_2$ holds for all $\hat x_t$ .

Parameters

cb	Cluster basis $(V_t)_{t\in{\mathcal T}_{\mathcal{I}}}$ . should be computed.

Returns: Returns an array of the weight matrices $(R_t)_{t\in\mathcal{T}_{\mathcal{I}}}$ corresponding to an enumeration of the cluster tree $\mathcal{T}_{\mathcal{I}}$ .

void write_cdf_clusterbasis	(	pcclusterbasis	cb,
		const char *	name
	)

Write clusterbasis to NetCDF file.

Parameters

cb	Cluster basis.
name	File name.

void write_cdfpart_clusterbasis	(	pcclusterbasis	cb,
		int	nc_file,
		const char *	prefix
	)

Write clusterbasis to part of NetCDF file.

Parameters

cb	Cluster basis.
nc_file	File handle.
prefix	Prefix for variable names.

Data Structures

Typedefs

Functions

Detailed Description

Function Documentation