MatrixFacade and VectorFacade

Summary

The class VectorFacade is a base class and interface class for all vectors associated to the indices of a global basis and, correspondingly, the class MatrixFacade is a base class and interface class for all matrices associated to the indices of a row and column global basis.

Classes

Class Descriptions
MatrixFacade Base class for matrices
VectorFacade Base class for vectors

class MatrixFacade

Defined in header <amdis/linearalgebra/MatrixFacade.hpp>

template <class T, template <class> class MatrixImpl>
class MatrixFacade

MatrixFacade is an interface class for matrices storing the implementation and redirecting to its interface functions. It is, for example, the base class of the system matrix BiLinearForm.

The template parameter T defines the coefficient type of the matrix, MatrixImpl refers to the actual implementation of the matrix data-structure.

Note

The indices of the row and column bases are always flat multi-indices, since the AMDiS::GlobalBasis always uses a flat index-merging strategy.

Member functions

Function Descriptions
(constructor) MatrixFacade(RowBasis const& rowBasis, ColBasis const& colBasis), construct the backend from the index distributions of the bases
impl Return the underlying matrix backend
init init(pattern): prepare the matrix for insertion and allocate the sparsity pattern, init(): prepare for insertion keeping the pattern
finish Finish the insertion of values
insert insert(row, col, value): add a single value to the matrix entry at multi-indices row and col
scatter scatter(rowLocalView, colLocalView, localMatrix): add a local element matrix to the global matrix, with indices given by the bound local views
zeroRows zeroRows(rows, diag): set all entries of the given rows to zero and the diagonal entry to 1 if diag is true
zeroRowsColumns zeroRowsColumns(rows, diag[, x, b]): zero the given rows and columns, set the diagonal to 1 if diag is true, and optionally update the right-hand side b with the values of x
nnz Number of nonzeros in the matrix

The zeroRows and zeroRowsColumns functions additionally have overloads taking separate vectors of row and column indices, defining the positions of the diagonal entries as pairs.

Example

using Matrix = MatrixFacade<double, BackendTraits::template Matrix<Basis,Basis>::template Impl>;
using Pattern = typename BackendTraits::template Matrix<Basis,Basis>::SparsityPattern;

Pattern pattern{basis, basis};
Matrix matrix{basis, basis};
matrix.init(pattern);
auto localView = basis.localView();
for (auto const& e : entitySet(basis)) {
  localView.bind(e);
  FlatMatrix<double> localMat(localView.size(), localView.size());
  // ... fill the local matrix
  matrix.scatter(localView, localView, localMat);
}
matrix.finish();

class VectorFacade

Defined in header <amdis/linearalgebra/VectorFacade.hpp>

template <class T, template <class> class VectorImpl>
class VectorFacade

VectorFacade is an interface class for vectors storing the implementation and redirecting to its interface functions. It is, for example, the base class of DOFVector.

The template parameter T defines the coefficient type of the vector, VectorImpl refers to the actual implementation of the vector data-structure.

Member Types

Member Type Definition
size_type The size type of the backend implementation
value_type The value type of the backend implementation, often the same as T, but might be just something similar, like PetscScalar

Member functions

Function Descriptions
(constructor) Construct the VectorFacade
impl Return the vector implementation
state Return the internal state of the vector (for debugging purposes)

Capacity

Function Descriptions
localSize,globalSize The number of entries in the local/global part of the vector
resize,resizeZero Resize the vector to the size of the basis
init Prepare the vector for insertion of values
finish Finish the insertion of values

Element access

Function Descriptions
get Return the value of the vector at the given index
gather Extract values from the vector referring to the given local indices
forEach Apply a functor to each value at given indices

Modifiers

Function Descriptions
insert,set,add Insert a single value into the vector (add or overwrite to existing value)
scatter Insert a block of values into the vector
axpy,aypx,+=,-=,*=,/=,= Vector space operations

function VectorFacade::VectorFacade

template <class GlobalBasis>
VectorFacade(GlobalBasis const& basis)

Constructor that passes the index distribution of the global basis to the implementation and resizes the vector to the size of the basis, setting all entries to zero. The basis must provide a method indexDistribution(), as AMDiS::GlobalBasis does.

function VectorFacade::impl

Impl const& impl() const    // (1)
Impl&       impl()          // (2)
Return the underlying linear algebra implementation

function VectorFacade::localSize,globalSize

std::size_t localSize() const     // (1)
std::size_t globalSize() const    // (2)
Return the number of entries in the (1) local part of the vector, or (2) in the global vector.

function VectorFacade::resize,resizeZero

template <class Basis>
void resize(Basis const& basis)         // (1)
template <class Basis>
void resizeZero(Basis const& basis)     // (2)
Resize the vector to the size of the basis (1) and in case of (2) also set all entries to zero.

Note

The derived class DOFVector additionally provides resize() and resizeZero() without arguments that use the stored basis.

function VectorFacade::init

template <class Basis>
void init(Basis const& basis, bool clear)
Resize the vector to the size of the basis and prepare it for insertion of values, finish the insertion with a call to finish().

Arguments

Basis basis
The global basis defining the size of the vector
bool clear
If true, sets the vector to zero before insertion

function VectorFacade::finish

void finish()
Finish the insertion of values. Must be called at the end of the insertion. See also init().

function VectorFacade::get

template <class Index>
value_type get(Index const& dof) const
Return the value of the vector at the index dof. Note, an internal synchronization of the ghost values of the vector might be necessary. This is a collective communication operation. This communication is performed only if the vector is in unsynchronized state.

Note

Prefer a block operation to retrieve data, like gather().

Arguments

Index dof
Any (Multi-)index type. Since the AMDiS::GlobalBasis is always flat, only flat multi-indices are used.

function VectorFacade::gather

// (1)
template <class Node, class Buffer>
void gather(LocalView const& localView, Node const& node, Buffer& buffer) const
// (2)
template <class Buffer>
void gather(LocalView const& localView, Buffer& buffer) const
// (3)
template <class Index, class Buffer>
void gather(std::vector<Index> const& indices, Buffer& buffer)
Collect value at indices and store them into a buffer. The buffer must be a vector-like container with buffer.resize() and buffer.begin(). The indices are defined by (1) the nodeIndices(localView, node), (2) the nodeIndices(localView), or (3) are given explicitly as a vector of multi-indices.

If the vector is not in synchronized state, collects all necessary values possibly from neighboring processors. Gather can not be called during insertion state. This must be closed using finish() before.

Arguments

LocalView localView
The localView object of a global basis
Node node
A node in the basis tree
Buffer buffer
A resizable output range with resize() and begin() member functions.

Requirements

  • Node must be a model of the concept Dune::Functions::Concept::BasisNode

Preconditions

  • expects: localView is bound to an element
  • expects: node is in localView.tree()

function VectorFacade::insert,set,add

// (1)
template <class Index, class Assign = Assigner::plus_assign>
void insert(Index const& dof, value_type const& value, Assign assign = {})

// (2)
template <class Index>
void set(Index const& dof, value_type const& value)

// (3)
template <class Index>
void add(Index const& dof, value_type const& value)
(1) Inserts or adds a value into a certain location dof (given as dof multi-index) of a vector. The insertion mode is determined by the assign functor. Use Assigner::plus_assign for adding values (default) or Assigner::assign for overwriting (setting) values. Different insertion modes must not be mixed!

Insertion must be closed with a call to finish().

(2) and (3) are abbreviations for the general insert() method (1) by fixing the insertion mode.

Note

Prefer a block operation to insert data, like scatter().

Arguments

Index dof
Any (Multi-)index type. Since the AMDiS::GlobalBasis is always flat, only flat multi-indices are used.
value_type value
The single value to insert or to add to the container
Assign assign
An assignment functor with the signature void operator()(T const& from, S&& to) const

function VectorFacade::scatter

// (1)
template <class Node, class NodeVector, class MaskRange, class Assign>
void scatter(LocalView const& localView, Node const& node, NodeVector const& nodeVec,
             MaskRange const& mask, Assign assign)
// (2)
template <class Node, class NodeVector, class Assign>
void scatter(LocalView const& localView, Node const& node, NodeVector const& nodeVec,
             Assign assign)
// (3)
template <class NodeVector, class Assign>
void scatter(LocalView const& localView, NodeVector const& nodeVec, Assign assign)
// (4)
template <class Index, class Buffer>
void scatter(std::vector<Index> const& indices, Buffer const& values)
Inserts or adds values into certain locations of a vector. Insertion indices are extracted from the given localView. The insertion mode is determined by the assign functor. Use Assigner::plus_assign for adding values (default) or Assigner::assign for overwriting (setting) values. Different insertion modes can not be mixed! The nodeVec is assumed to be a continuous memory container with a data() method to get a pointer to the beginning and must have the same size as the node.

The mask models a boolean range with at least a begin() method. Must be forward iterable for at least localVector.size() elements. Does not need an end() method. See, e.g. FakeContainer.

Insertion must be closed with a call to finish(). It is not allowed to switch insertion mode before calling finish().

(2) Same as (1) but all indices are inserted.

(3) Same as (2) but node == localView.tree()

(4) Sets (overwrites) the values at the explicitly given multi-indices.

Arguments

LocalView localView
The localView object of a global basis
Node node
A node in the basis tree
NodeVector nodeVec
Continuous range with a data() method to get a pointer to the beginning
MaskRange mask
An boolean forward iterable range with at least a begin() member functions.
Assign assign
An assignment functor, e.g., Assigner::assign or Assigner::plus_assign.

Requirements

  • Node must be a model of the concept Dune::Functions::Concept::BasisNode

Preconditions

  • expects: Vector is either in the same insertion mode as before (no mixing of different insertion modes), or in non-insertion mode.
  • expects: localView is bound to an element
  • expects: node is in localView.tree()
  • expects: nodeVec is of size node.size()
  • expects: mask must be forward iterable for at least nodeVec.size() elements

Postconditions

  • ensures: Vector is in insertion mode defined by the assign functor.

function VectorFacade::forEach

template <class LocalInd, class Func>
void forEach(LocalInd const& localInd, Func&& func)         // (1)
template <class LocalInd, class Func>
void forEach(LocalInd const& localInd, Func&& func) const   // (2)
First synchronizes the values of the vector, then applies the functor func to each (mutable (1) or const (2)) value associated to the indices localInd.

Vector space operations

template <class S>
VectorFacade& axpy(S const& alpha, VectorFacade const& x)   // (1)
template <class S>
VectorFacade& aypx(S const& alpha, VectorFacade const& x)   // (2)
VectorFacade& operator+=(VectorFacade const& x)             // (3)
VectorFacade& operator-=(VectorFacade const& x)             // (4)
template <class S>
VectorFacade& operator*=(S const& alpha)                    // (5)
template <class S>
VectorFacade& operator/=(S const& alpha)                    // (6)
template <class S>
VectorFacade& operator=(S const& alpha)                     // (7)
(1) Computes xthis=xthis+αx x_{this} = x_{this} + \alpha x , (2) computes xthis=αxthis+x x_{this} = \alpha x_{this} + x , (3) and (4) add or subtract the vector x, (5) and (6) scale all entries by α\alpha or 1/α1/\alpha, respectively, and (7) sets all entries to the scalar α\alpha. The scalar type S must be a number type. The vectors must be associated to the same basis.

Example

DOFVector dv{gridView, lagrange<1>()};
auto& v = dv.coefficients();
auto v2 = v;      // copy of the VectorFacade

v = 0.0;
v2 = 1.0;
v.axpy(2.0, v2);  // v = v + 2.0 * v2
v.aypx(1.5, v2);  // v = 1.5 * v + v2
v += v2;
v *= 0.5;