H2Lib  3.0
Data Structures | Macros | Typedefs | Functions
uniform

Representation of an admissible block for $ \mathcal H^2 $-matrices. More...

Data Structures

struct  _uniform
 Representation of an admissible block for $ \mathcal H^2 $-matrices. More...
 

Typedefs

typedef struct _uniform uniform
 Representation of an admissible block for $ \mathcal H^2 $-matrices.
 
typedef uniformpuniform
 Pointer to uniform object.
 
typedef const uniformpcuniform
 Pointer to a constant uniform object.
 

Functions

puniform new_uniform (pclusterbasis rb, pclusterbasis cb)
 Create a new uniform object. More...
 
void del_uniform (puniform u)
 Deletes an uniform object. More...
 
void ref_row_uniform (puniform u, pclusterbasis rb)
 Append this uniform object to the block row list. More...
 
void ref_col_uniform (puniform u, pclusterbasis cb)
 Append this uniform object to the block column list. More...
 
void unref_row_uniform (puniform u)
 Remove block row references to an uniform object. More...
 
void unref_col_uniform (puniform u)
 Remove block column references to an uniform object. More...
 
size_t getsize_uniform (pcuniform u)
 Get size of a given uniform object. More...
 
void clear_uniform (puniform u)
 Sets the coupling matrix to zero. More...
 
void copy_uniform (bool trans, pcuniform src, puniform trg)
 Copy a uniform matrix $G$. More...
 
puniform clone_uniform (pcuniform src)
 Clone a uniform matrix. More...
 
void scale_uniform (field alpha, puniform u)
 Scale a uniform matrix. More...
 
void random_uniform (puniform u)
 Fill a uniform matrix with random coefficients. More...
 
void mvm_uniform_avector (field alpha, bool trans, pcuniform u, pcavector x, pavector y)
 Computes the euclidean-norm of the coupling matrix and or the product of weight matrices with the coupling matrix. More...
 
void add_projected_uniform (pcuniform u, pcclusteroperator ro, pcclusteroperator co, puniform unew)
 Addition of two uniform matrices in different clusterbasis. More...
 
void project_inplace_uniform (puniform u, pclusterbasis rb, pcclusteroperator ro, pclusterbasis cb, pcclusteroperator co)
 Project uniform matrix into new clusterbasis. More...
 
void add_rkmatrix_uniform (pcrkmatrix r, puniform unew)
 Adds a low rank matrix to an uniform matrix. More...
 
uint getrows_uniform (pcuniform u)
 Get the number of rows of a uniform matrix $G=V S W^*$. More...
 
uint getcols_uniform (pcuniform u)
 Get the number of columns of a uniform matrix $G=V S W^*$. More...
 
pamatrix getS_uniform (puniform u)
 Get the factor S of a uniform matrix $G=V S W^*$. More...
 

Detailed Description

Representation of an admissible block for $ \mathcal H^2 $-matrices.

In case of $ \mathcal H^2$-matrices an admissible subblock is represented by

\[ G|_{t \times s} = V_t S_b W_s^*, \]

where $ V_t, W_s $ are the corresponding clusterbasis.

A uniform object stores the coupling-matrix $ S_b $ aswell as references to the row- and column-clusterbasis.

Function Documentation

void add_projected_uniform ( pcuniform  u,
pcclusteroperator  ro,
pcclusteroperator  co,
puniform  unew 
)

Addition of two uniform matrices in different clusterbasis.

Computes $ S_{b,\text{new}} \gets S_{b,\text{new}} + \hat S$, where $ \hat S $ can be either

\[ \hat S = S_b, \quad \hat S = C_t S_b, \quad \hat S = S_b C_s^* \quad \text{or} \quad \hat S = C_t S_b C_s^*, \]

which depends on the equality of the row- and column clusterbasis.

Parameters
uSource uniform matrix with the representation $ u = V_t S_b W_s^*$-
roClusteroperator defining the basis-change for the row clusterbasis. Its weight matrix is $ C_t $.
coClusteroperator defining the basis-change for the column clusterbasis. Its weight matrix is $ C_s $.
unewSource uniform matrix with the representation $ u_\text{new} = V_{t,\text{new}} S_{b,\text{new}} W_{s,\text{new}}^*$.
void add_rkmatrix_uniform ( pcrkmatrix  r,
puniform  unew 
)

Adds a low rank matrix to an uniform matrix.

Updates the coupling matrix $ S_b $ of $ u $ to $ S_b \gets S_b + V_t^* A B^* W_s $ for a low rank matrix $ r = A B^* $ .

Parameters
rlow rank matrix to be added to an uniform matrix.
unewuniform matrix storing the result of the computation.
void clear_uniform ( puniform  u)

Sets the coupling matrix to zero.

Parameters
uuniform object.
puniform clone_uniform ( pcuniform  src)

Clone a uniform matrix.

Parameters
srcSource matrix.
Returns
Clone of the source matrix.
void copy_uniform ( bool  trans,
pcuniform  src,
puniform  trg 
)

Copy a uniform matrix $G$.

Parameters
transSet if $G^*$ should be copied instead of $G$.
srcSource matrix.
trgtarget matrix.
void del_uniform ( puniform  u)

Deletes an uniform object.

Releases the memory corresponding to the object. Reference inside the block row and block column lists are automatically removed by this function.

Parameters
uObject to be deleted.
uint getcols_uniform ( pcuniform  u)

Get the number of columns of a uniform matrix $G=V S W^*$.

Parameters
uMatrix $G$.
Returns
Number of columns of $G$, i.e., number of rows of $W$.
uint getrows_uniform ( pcuniform  u)

Get the number of rows of a uniform matrix $G=V S W^*$.

Parameters
uMatrix $G$.
Returns
Number of rows of $G$, i.e., number of rows of $V$.
pamatrix getS_uniform ( puniform  u)

Get the factor S of a uniform matrix $G=V S W^*$.

Parameters
uMatrix $G$.
Returns
Factor $S$.
size_t getsize_uniform ( pcuniform  u)

Get size of a given uniform object.

Parameters
uuniform object.
Returns
Size of allocated storage in bytes.
void mvm_uniform_avector ( field  alpha,
bool  trans,
pcuniform  u,
pcavector  x,
pavector  y 
)

Computes the euclidean-norm of the coupling matrix and or the product of weight matrices with the coupling matrix.

Depending on given row- and column-clusteroperators this functions computed one of the following four values via vector iteration:

\[ // * \lVert S_b \rVert_2, \quad \lVert C_t S_b \rVert_2, \quad // * \lVert S_b C_s^* \rVert_2 \quad \text{or} \quad \lVert C_t S_b C_s^* \rVert_2 // * \]

@param u @ref _uniform "uniform" object.
@param rw Row @ref _clusteroperator "clusteroperator". If <tt>rw == NULL</tt>
then \form#940 is omitted in the computation of the norm.
@param cw Column @ref _clusteroperator "clusteroperator". If <tt>cw == NULL</tt>
then \form#941 is omitted in the computation of the norm.

@return Approximation of the euclidean-norm of one of the above mentioned
matrices.

Computes the frobenius-norm of the coupling matrix and or the product of weight matrices with the coupling matrix.

Depending on given row- and column-clusteroperators this functions computed one of the following four values:

\[ // * \lVert S_b \rVert_F, \quad \lVert C_t S_b \rVert_F, \quad // * \lVert S_b C_s^* \rVert_F \quad \text{or} \quad \lVert C_t S_b C_s^* \rVert_F // * \]

@param u @ref _uniform "uniform" object.
@param rw Row @ref _clusteroperator "clusteroperator". If <tt>rw == NULL</tt>
then \form#940 is omitted in the computation of the norm.
@param cw Column @ref _clusteroperator "clusteroperator". If <tt>cw == NULL</tt>
then \form#941 is omitted in the computation of the norm.

@return Approximation of the frobenius-norm of one of the above mentioned
matrices.

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

The uniform matrix or its adjoint is multiplied by the source vector $x$, the result is scaled by $\alpha$ and added to the target vector $y$. Here the uniform matrix is represented by $ u = V_t S_b W_s^* $

Parameters
alphaScaling factor $\alpha$.
transSet if $u^*$ is to be used instead of $u$.
uMatrix $A$.
xSource vector $x$.
yTarget vector $y$.
puniform new_uniform ( pclusterbasis  rb,
pclusterbasis  cb 
)

Create a new uniform object.

Allocates storage for the object and sets the clusterbasis pointers according to the input parameters.

Remarks
Should always be matched by a call to del_uniform.
Parameters
rbRow clusterbasis
cbColumn clusterbasis
Returns
Returns a pointer to a newly allocated uniform object.
void project_inplace_uniform ( puniform  u,
pclusterbasis  rb,
pcclusteroperator  ro,
pclusterbasis  cb,
pcclusteroperator  co 
)

Project uniform matrix into new clusterbasis.

The uniform matrix u is represented by $ u = V_t S_b W_S^* $. Depending on the equality of the old and the new clusterbasis $ S_b $ is being updated to

\[ S_b \gets S_b, \quad S_b \gets C_t S_b, \quad S_b \gets S_b C_s^*, \quad \text{or} \quad S_b \gets C_t S_b C_s^* \]

Parameters
uuniform object.
rbNew row clusterbasis for u.
roClusteroperator describing the basischangebetween the old and new row clusterbasis.
cbNew column clusterbasis for u.
coClusteroperator describing the basischangebetween the old and new column clusterbasis.
void random_uniform ( puniform  u)

Fill a uniform matrix with random coefficients.

Parameters
uTarget matrix $S$.
void ref_col_uniform ( puniform  u,
pclusterbasis  cb 
)

Append this uniform object to the block column list.

A reference to the uniform object will be set into a reference list inside the column clusterbasis cb. Vice versa a reference to the current object will also be inserted into the cnext respectively cprev list.

Remarks
If one wants to remove a reference to this uniform object, the function unref_col_uniform should be called.
Parameters
uUniform object to be referenced.
cbColumn clusterbasis to be referenced.
void ref_row_uniform ( puniform  u,
pclusterbasis  rb 
)

Append this uniform object to the block row list.

A reference to the uniform object will be set into a reference list inside the row clusterbasis rb. Vice versa a reference to the current object will also be inserted into the rnext respectively rprev list.

Remarks
If one wants to remove a reference to this uniform object, the function unref_row_uniform should be called.
Parameters
uUniform object to be referenced.
rbRow clusterbasis to be referenced.
void scale_uniform ( field  alpha,
puniform  u 
)

Scale a uniform matrix.

Parameters
alphaScaling factor $\alpha$.
uTarget matrix $S$, will be overwritten by $\alpha S$.
void unref_col_uniform ( puniform  u)

Remove block column references to an uniform object.

All previous made block column references to this uniform object will be removed. This is the counterpart of the function ref_col_uniform.

Parameters
uUniform object for which the references should be removed.
void unref_row_uniform ( puniform  u)

Remove block row references to an uniform object.

All previous made block row references to this uniform object will be removed. This is the counterpart of the function ref_row_uniform.

Parameters
uUniform object for which the references should be removed.