SparseMatrix< T > Class Template Reference

The sparse matrix class. More...

#include <SparseMatrix.hpp>

Collaboration diagram for SparseMatrix< T >:

Collaboration graph
[legend]
List of all members.

Public Member Functions

long TotalNOfLines () const
 returns the total number of lines
const Array< int > & DstGridSizes () const
 Returns the destination grid sizes.
int DstGridSize (int i) const
 Returns the destination grid size no. i.
long DstDimension () const
 returns the dimensionality of the dst. grid
bool IsScalar () const
int SrcBlockSize () const
int DstBlockSize () const
int MinLineEntries () const
bool IsDstVector (MultiVector< T > &x)
 Returns true if 'x' has the right size for the range of the matrix.
SparseMatrixLine< T > * operator[] (MultiIndex &i)
 Returns the matrix line with the index i.
SparseMatrixLine< T > * operator[] (long i)
 Returns the matrix line with the raw index i.
T & operator() (SparseMatrixLine< T > *l, long i)
 The 1st entry of the matrix block # 'i' in line 'l'.
long DstOffset (MultiIndex &I)
 Returns the offset in the dst. vec. for a given line.
T * FindEntry (SparseMatrixLine< T > *line, long ref_offset)
 Looks for an entry.
T * FindOrCreateEntry (SparseMatrixLine< T > *line, long ref_offset)
 Looks for a matrix entry in a given matrix line that references a given offset in the src. vec.
T * Adjoint (long l_index, long i)
 The adjoint entry for a given one (NULL if it does not exist).
T * Adjoint (MultiIndex &line_I, long i)
 The adjoint entry for a given one (NULL if it does not exist).
T * GetAdjoint (long l_index, long i)
 Finds or creates the adjoint entry for a given one.
T * GetAdjoint (MultiIndex &line_I, long i)
 Finds or creates the adjoint entry for a given one.
T * Connection (long i, long j)
 looks for a matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector.
T * SetConnection (long i, long j, T *entries)
 Initializes the matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector with given values.
T * SetConnection (long i, long j, T val)
 For scalar matrices - the same as the previous one but gets T instead of T *.
T * AddToConnection (long i, long j, T *entries)
 Adds given values to the matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector.
T * AddToConnection (long i, long j, T val)
 For scalar matrices - the same as the previous one but gets T instead of T *.
SparseMatrix< T > & SetZero ()
 Sets the matrix to the zero one.
SparseMatrix< T > & SetZeroDiag ()
 Sets the matrix to the zero one, but with existing diag. entries.
SparseMatrix< T > & SetDiag (T diag)
 Initializes with the diagonal matrix.
SparseMatrix< T > & operator= (SparseMatrix< T > &src)
 Copies the matrices AND the sizes.
SparseMatrix< T > & CopySortedTo (SparseMatrix< T > &dst)
 Copys the matrix and sorts the entries in the lines so that the diagonal one is the first one in the list, and the further ones are sorted in the ascending order of the offsets.
MultiVector< T > & mul (MultiVector< T > &x, MultiVector< T > &y)
 Operation $x \leftarrow A \cdot y$ for a given vector y.
MultiVector< T > & add_mul (MultiVector< T > &x, MultiVector< T > &y)
 Operation $ x \leftarrow x + A \cdot y$ for given vectors x, y.
MultiVector< T > & sub_mul (MultiVector< T > &x, MultiVector< T > &y)
 Operation $x \leftarrow x - A \cdot y$ for given vectors x, y.
MultiVector< T > & add_a_mul (MultiVector< T > &x, T a, MultiVector< T > &y)
 Operation $x \leftarrow x + a A \cdot y$ for given vectors x, y and a scalar a.
MultiVector< T > & residual (MultiVector< T > &f, MultiVector< T > &x, MultiVector< T > &r)
 Computation of the residual $ r := f - A \cdot x$ for given 'f' and 'x'.
T scal_prod (MultiVector< T > &x, MultiVector< T > &y)
 The energy scalar product $(Ax, y)$.
SparseMatrix< T > & operator *= (T a)
 Multiplies 'this' matrix by a scalar.
void Reset ()
 No memory, undefined grid sizes (i.e. zero matrix).
void Reset (const Array< int > &grid_sizes, int the_src_block_size, int the_dst_block_size, int the_min_line_entries=0)
 Sets all the sizes.
void Reset (const Array< int > &sizes, int the_min_line_entries=0)
 Sets all the sizes (the scalar version).
 SparseMatrix ()
 A dummy object - no memory, no sizes.
 SparseMatrix (Array< int > grid_sizes, int the_src_block_size, int the_dst_block_size, int the_min_line_entries=0)
 An object by the grid and the block sizes.
 SparseMatrix (Array< int > sizes, int the_min_line_entries=0)
 A scalar matrix by the grid sizes.

Detailed Description

template<typename T>
class SparseMatrix< T >

The sparse matrix class.

This is a MultiArray of SparseMatrixLine<T>-objects, so that a SparseMatrix<T> object stores all the matrix lines associated to the grid positions. This class provides the matrix-grid-function and matrix-matrix arithmetics, as well as some facilities for assembing sparse matrices in discretizations.

The sparse matrix may be left uninitialized or reset by the 'Reset ()' method. Such a matrix is treated as a zero matrix. Then it occupies no memory.

Note:
This template depends on a type T. This type should satisfy the conditions listed in 'small_matrix.hpp' for small matrices.

Constructor & Destructor Documentation

template<typename T>
SparseMatrix< T >::SparseMatrix (  )  [inline]

A dummy object - no memory, no sizes.

template<typename T>
SparseMatrix< T >::SparseMatrix ( Array< int >  grid_sizes,
int  the_src_block_size,
int  the_dst_block_size,
int  the_min_line_entries = 0 
) [inline]

An object by the grid and the block sizes.

Parameters:
[in] grid_sizes Array of the dst. grid sizes (without the blocks)
[in] the_src_block_size The size of the blocks of the source vectors
[in] the_dst_block_size The size of the blocks of the destination vectors
[in] the_min_line_entries The mininum num. of blocks in the lines

template<typename T>
SparseMatrix< T >::SparseMatrix ( Array< int >  sizes,
int  the_min_line_entries = 0 
) [inline]

A scalar matrix by the grid sizes.

Parameters:
[in] sizes Array of the dst. grid sizes
[in] the_min_line_entries The mininum num. of blocks in the lines

Member Function Documentation

template<typename T>
long SparseMatrix< T >::TotalNOfLines (  )  const [inline]

returns the total number of lines

template<typename T>
const Array<int>& SparseMatrix< T >::DstGridSizes (  )  const [inline]

Returns the destination grid sizes.

template<typename T>
int SparseMatrix< T >::DstGridSize ( int  i  )  const [inline]

Returns the destination grid size no. i.

Parameters:
[in] i The index of the dimension

template<typename T>
long SparseMatrix< T >::DstDimension (  )  const [inline]

returns the dimensionality of the dst. grid

template<typename T>
bool SparseMatrix< T >::IsScalar (  )  const [inline]

template<typename T>
int SparseMatrix< T >::SrcBlockSize (  )  const [inline]

template<typename T>
int SparseMatrix< T >::DstBlockSize (  )  const [inline]

template<typename T>
int SparseMatrix< T >::MinLineEntries (  )  const [inline]

template<typename T>
bool SparseMatrix< T >::IsDstVector ( MultiVector< T > &  x  )  [inline]

Returns true if 'x' has the right size for the range of the matrix.

< for a zero matrix all vectors are admissible

template<typename T>
SparseMatrixLine<T>* SparseMatrix< T >::operator[] ( MultiIndex &  i  )  [inline]

Returns the matrix line with the index i.

template<typename T>
SparseMatrixLine<T>* SparseMatrix< T >::operator[] ( long  i  )  [inline]

Returns the matrix line with the raw index i.

template<typename T>
T& SparseMatrix< T >::operator() ( SparseMatrixLine< T > *  l,
long  i 
) [inline]

The 1st entry of the matrix block # 'i' in line 'l'.

Parameters:
[in] l The matrix line (may not be NULL!)
[in] i The index in the offset array (NOT in the matrix!)

template<typename T>
long SparseMatrix< T >::DstOffset ( MultiIndex &  I  )  [inline]

Returns the offset in the dst. vec. for a given line.

Parameters:
[in] I multiindex of the line

template<typename T>
T* SparseMatrix< T >::FindEntry ( SparseMatrixLine< T > *  line,
long  ref_offset 
) [inline]

Looks for an entry.

Parameters:
[in] line The line of the matrix
[in] ref_offset The offset to reference in the src. vec.
Returns:
The pointer to the matrix block or NULL if not found

template<typename T>
T * SparseMatrix< T >::FindOrCreateEntry ( SparseMatrixLine< T > *  line,
long  ref_offset 
) [inline]

Looks for a matrix entry in a given matrix line that references a given offset in the src. vec.

If not found, the entry is allocated and set to zero.

Parameters:
[in] line The line of the matrix
[in] ref_offset The offset of the block in the src. vec.
Returns:
The pointer to the matrix block

template<typename T>
T* SparseMatrix< T >::Adjoint ( long  l_index,
long  i 
) [inline]

The adjoint entry for a given one (NULL if it does not exist).

Parameters:
[in] l_index Index of the matrix line
[in] i The index in the offset array (NOT in the matrix!)

template<typename T>
T* SparseMatrix< T >::Adjoint ( MultiIndex &  line_I,
long  i 
) [inline]

The adjoint entry for a given one (NULL if it does not exist).

Parameters:
[in] line_I Multiindex of the matrix line
[in] i The index in the offset array (NOT in the matrix!)

template<typename T>
T* SparseMatrix< T >::GetAdjoint ( long  l_index,
long  i 
) [inline]

Finds or creates the adjoint entry for a given one.

Parameters:
[in] l_index Index of the matrix line
[in] i The index in the offset array (NOT in the matrix!)

template<typename T>
T* SparseMatrix< T >::GetAdjoint ( MultiIndex &  line_I,
long  i 
) [inline]

Finds or creates the adjoint entry for a given one.

Parameters:
[in] line_I Multiindex of the matrix line
[in] i The index in the offset array (NOT in the matrix!)

template<typename T>
T * SparseMatrix< T >::Connection ( long  i,
long  j 
) [inline]

looks for a matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector.

Parameters:
[in] i The src. vec.
[in] j The dst. vec.
Returns:
NULL if the block is not found, the pointer to the matrix block for the src. vec. otherwise
Note:
'i' and 'j' must correspond to the blocks in the vectors, NOT in the matrix

The indices i and j should be divisible by src_block_size and dst_block_size

template<typename T>
T * SparseMatrix< T >::SetConnection ( long  i,
long  j,
T *  entries 
) [inline]

Initializes the matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector with given values.

There must be mat_block_size values. If the block does not exist in the matrix, the function creates it.

Parameters:
[in] i The src. vec.
[in] j The dst. vec.
[in] entries The values to copy
Returns:
The pointer to the matrix block
Note:
'i' and 'j' must correspond to the blocks in the vectors, NOT in the matrix

The indices i and j should be divisible by src_block_size and dst_block_size

template<typename T>
T * SparseMatrix< T >::SetConnection ( long  i,
long  j,
T  val 
) [inline]

For scalar matrices - the same as the previous one but gets T instead of T *.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
[in] i The src. vec.
[in] j The dst. vec.
[in] val The value to copy
Returns:
The pointer to the matrix block
Note:
'i' and 'j' must correspond to the blocks in the vectors, NOT in the matrix

template<typename T>
T * SparseMatrix< T >::AddToConnection ( long  i,
long  j,
T *  entries 
) [inline]

Adds given values to the matrix block corresponding to a raw index i in the src. vector and a raw index j in the dst. vector.

There must be mat_block_size values. If the block does not exist in the matrix, the function creates it.

Parameters:
[in] i The src. vec.
[in] j The dst. vec.
[in] entries The values to add
Returns:
The pointer to the matrix block
Note:
'i' and 'j' must correspond to the blocks in the vectors, NOT in the matrix

The indices i and j should be divisible by src_block_size and dst_block_size

template<typename T>
T * SparseMatrix< T >::AddToConnection ( long  i,
long  j,
T  val 
) [inline]

For scalar matrices - the same as the previous one but gets T instead of T *.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

If the block is not found it is created. The function returns the pointer to it.

Parameters:
[in] i The src. vec.
[in] j The dst. vec.
[in] val The value to add
Returns:
The pointer to the matrix block
Note:
'i' and 'j' must correspond to the blocks in the vectors, NOT in the matrix

template<typename T>
SparseMatrix<T>& SparseMatrix< T >::SetZero (  )  [inline]

Sets the matrix to the zero one.

template<typename T>
SparseMatrix<T>& SparseMatrix< T >::SetZeroDiag (  )  [inline]

Sets the matrix to the zero one, but with existing diag. entries.

template<typename T>
SparseMatrix<T>& SparseMatrix< T >::SetDiag ( T  diag  )  [inline]

Initializes with the diagonal matrix.

Parameters:
[in] diag The diagonal coefficient to set
Note:
This function works only with scalar matrices.

template<typename T>
SparseMatrix<T>& SparseMatrix< T >::operator= ( SparseMatrix< T > &  src  )  [inline]

Copies the matrices AND the sizes.

Parameters:
[in] src The matrix to copy

template<typename T>
SparseMatrix< T > & SparseMatrix< T >::CopySortedTo ( SparseMatrix< T > &  dst  )  [inline]

Copys the matrix and sorts the entries in the lines so that the diagonal one is the first one in the list, and the further ones are sorted in the ascending order of the offsets.

Parameters:
[in] dst To save the matrix
Returns:
The reference to the resulting matrix (dst)

template<typename T>
MultiVector< T > & SparseMatrix< T >::mul ( MultiVector< T > &  x,
MultiVector< T > &  y 
) [inline]

Operation $x \leftarrow A \cdot y$ for a given vector y.

The arrays x and y may not coincide. The function returns the reference to x. 'x' and 'y' should have the corresponding sizes

Parameters:
[out] x The result
[in] y The vector to multiply
Returns:
x

template<typename T>
MultiVector< T > & SparseMatrix< T >::add_mul ( MultiVector< T > &  x,
MultiVector< T > &  y 
) [inline]

Operation $ x \leftarrow x + A \cdot y$ for given vectors x, y.

The function returns the reference to x. 'x' and 'y' should have the corresponding sizes.

Parameters:
[in] x The first summand and the result
[in] y The vector to multiply
Returns:
x

template<typename T>
MultiVector< T > & SparseMatrix< T >::sub_mul ( MultiVector< T > &  x,
MultiVector< T > &  y 
) [inline]

Operation $x \leftarrow x - A \cdot y$ for given vectors x, y.

The function returns the reference to x. 'x' and 'y' should have the corresponding sizes

Parameters:
[in] x The result is saved here
[in] y The vector to multiply
Returns:
x

template<typename T>
MultiVector< T > & SparseMatrix< T >::add_a_mul ( MultiVector< T > &  x,
T  a,
MultiVector< T > &  y 
) [inline]

Operation $x \leftarrow x + a A \cdot y$ for given vectors x, y and a scalar a.

The function returns the reference to x. 'x' and 'y' should have the corresponding sizes.

Parameters:
[in] x The first summand and the result
[in] a The scalar
[in] y The vector to multiply
Returns:
x

template<typename T>
MultiVector< T > & SparseMatrix< T >::residual ( MultiVector< T > &  f,
MultiVector< T > &  x,
MultiVector< T > &  r 
) [inline]

Computation of the residual $ r := f - A \cdot x$ for given 'f' and 'x'.

The residual is saved in 'r' which is not expected to be initialized, except for the size. The sizes of 'f' and 'r' should be equal and consistent with the size of 'x'. The function returns the reference to 'r'

Parameters:
[in] f The right-hand side of the system
[in] x The current guess of the solution
[in] r To save the residual
Returns:
r

template<typename T>
T SparseMatrix< T >::scal_prod ( MultiVector< T > &  x,
MultiVector< T > &  y 
) [inline]

The energy scalar product $(Ax, y)$.

'x' and 'y' should have the corresponding sizes

template<typename T>
SparseMatrix< T > & SparseMatrix< T >::operator *= ( T  a  )  [inline]

Multiplies 'this' matrix by a scalar.

Parameters:
[in] a The scalar
Returns:
'this'

template<typename T>
void SparseMatrix< T >::Reset (  )  [inline]

No memory, undefined grid sizes (i.e. zero matrix).

template<typename T>
void SparseMatrix< T >::Reset ( const Array< int > &  grid_sizes,
int  the_src_block_size,
int  the_dst_block_size,
int  the_min_line_entries = 0 
) [inline]

Sets all the sizes.

Parameters:
[in] grid_sizes Array of the grid sizes (without the blocks)
[in] the_src_block_size The size of the blocks of the source vectors
[in] the_dst_block_size The size of the blocks of the dst. vectors
[in] the_min_line_entries The mininum num. of blocks in the lines

template<typename T>
void SparseMatrix< T >::Reset ( const Array< int > &  sizes,
int  the_min_line_entries = 0 
) [inline]

Sets all the sizes (the scalar version).

Parameters:
[in] sizes Array of the grid sizes
[in] the_min_line_entries The mininum num. of blocks in the lines

The documentation for this class was generated from the following files:
Generated on Fri Sep 21 12:34:40 2007 for SG2 by  doxygen 1.5.2