# DOFVector and DiscreteFunction {: #group-dofvector } ## Summary The class [DOFVector](#class-dofvector) acts as a container for storing the coefficients of the solution discrete function. It is attached to a global basis to give its coefficients a meaning. A [DiscreteFunction](#class-discretefunction) goes one step further and transforms a DOFVector or subspaces of a DOFVector (with respecto to a sub basis) into a [GridFunction](/reference/GridFunctions) that allows to use it like a function defined on a grid. Let $\{\phi_i\}$ be the set of basis functions of a finite-element space $V$. A function $u\in V$ can be represented as math u(\mathbf{x}) = \sum_i u_i \phi_i(\mathbf{x})  with coefficients $(u_i)$. The pair $\{(u_i),\{\phi_i\}\}$ is called DOFVector and the function $u=u(\mathbf{x})$ is called DiscreteFunction. ### Classes Class | Descriptions --------------------------------|--------------------------------------------- [DOFVector](#class-dofvector) | Standard container for storing solution coefficients associated to a functionspace basis [DiscreteFunction](#class-discretefunction) | Wrapper that transforms a DOFVector into a GridFunction ## class DOFVector Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp) c++ template > class DOFVector : public VectorFacade  DOFVector is a vector data-structure for the coefficients of a discrete function associated to a GlobalBasis GB. The template parameter GB defines the global basis type and T the value type of the coefficients in the vector. It defaults to double. The third parameter Traits is a collection of parameters characterizing the Linear-Algebra backend. It defaults to the default backend Traits. ### Member Types Member Type | Definition --------------------------------|--------------------------------------------- GlobalBasis | GB Traits | Traits size_type | typename GlobalBasis::size_type value_type | typename Backend::value_type The value_type is often the same as T, but might be just something similar, like PetscScalar. ### Member functions Function | Descriptions --------------------------------|--------------------------------------------- [*(constructor)*](#function-dofvectordofvector) | Construct the DOFVector [child](#function-dofvectorchild) | Return a DiscreteFunction of a given sub-space [backup](#function-dofvectorbackup) | Write DOFVector to file [restore](#function-dofvectorrestore) | Read backup data from file [dataTransfer](#function-dofvectordataTransfer) | Return the associated DataTransfer object ### Interpolation functions Function | Descriptions --------------------------------|--------------------------------------------- [interpolate](#function-dofvectorinterpolate) | Interpolation of GridFunction to DOFVector [interpolate_noalias](#function-dofvectorinterpolate) | Interpolation of GridFunction to DOFVector assuming no aliasing [operator<<](#function-dofvectorinterpolate) | Operator for the interpolation ??? seealso "Functions inherited from [VectorFacade](/reference/MatVecBase/#class-vectorfacade)" Function | Descriptions --------------------------------|--------------------------------------------- [basis](/reference/MatVecBase#function-vectorbasebasis) | Return the GlobalBasis associated with the vector [backend](/reference/MatVecBase#function-vectorbasebackend) | Return the backend vector wrapper implementing the actual algebra [localSize,globalSize](/reference/MatVecBase#function-vectorbasesize) | The number of entries in the local part of the vector [resize,resizeZero](/reference/MatVecBase#function-vectorbaseglobalSize)| Resize the vector to the size of the basis [init](/reference/MatVecBase#function-vectorbaseglobalSize) | Prepare the vector for insertion of values [finish](/reference/MatVecBase#function-vectorbaseglobalSize) | Finish the insertion of values [at](/reference/MatVecBase#function-vectorbaseat) | Return the value of the vector at the given local index [insert,set,add](/reference/MatVecBase#function-vectorbaseinsert) | Insert a single value into the matrix [gather](/reference/MatVecBase#function-vectorbasegather) | Extract values from the vector referring to the given local indices [scatter](/reference/MatVecBase#function-vectorbasescatter) | Insert a block of values into the vector [copy](/reference/MatVecBase#function-vectorbasescatter) | Copies a block of values into the vector [forEach](/reference/MatVecBase#function-vectorbasescatter) | Apply a functor to each value at given indices ## function DOFVector::DOFVector c++ template DOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE)  Constructs the DOFVector from a given global basis and optionally a DataTransferOperation that defines how the DOFVector is handled during grid adaption. #### Arguments Basis basis : Either a shared_ptr to the GlobalBasis type or anything that can be converted to that, e.g. a reference or a unique_ptr or a dune-functions DefaultGlobalBasis. References to lavlues are wrapped into non-destroying shared_ptrs whereas rvalue-references are moved into new basis objects. DataTransferOperation op : The operation performed during data-transfer, either DataTransferOperation::INTERPOLATE or DataTransferOperation::NO_OPERATION #### Example c++ using Grid = Dune::YaspGrid<2>; Grid grid({1.0, 1.0}, {2, 2}); using namespace Dune::Functions::BasisFactory; ParallelGlobalBasis basis1(grid.leafGridView(), lagrange<2>()); DOFVector vec0(basis1); DOFVector vec1(basis1); // C++17 only auto basis2 = makeUniquePtr(ParallelGlobalBasis(grid.leafGridView(), lagrange<2>())); DOFVector> vec2(std::move(basis2));  #### See Also - Generator function to construct a DOFVector: [makeDOFVector()](#function-makedofvector) ## function DOFVector::child c++ template auto child(TreePath const& path = {}) // (1) template auto child(TreePath const& path = {}) const // (2)  (1) Creates a mutable DiscreteFunction representing the sub-space w.r.t. the passed tree-path. The path thereby refers to the hierarchic global basis. (2) Creates a constant DiscreteFunction representing the sub-space w.r.t. the passed tree-path. The path thereby refers to the hierarchic global basis. #### Arguments TreePath path : A Treepath identifying a node in the basis tree. #### Example c++ DOFVector vec(basis); auto vec_ = vec.child(); auto vec_0 = vec.child(_0); auto vec_10 = vec.child(treepath(_1,0));  ## function DOFVector::backup c++ void backup(std::string const& filename);  Writes the coefficients of the DOFVector to file. Thereby the data is first extracted element-wise and then written using binary ofstreams. #### Arguments std::string filename : The filename of the backup file that is created. ## function DOFVector::restore c++ void restore(std::string const& filename);  Reads a backup of the DOFVector from file previously created using the [backup()](#function-dofvectorbackup) function. #### Arguments std::string filename : The filename of the backup file to read from. ## function DOFVector::interpolate,interpolate_noalias,operator<< {: #function-dofvectorinterpolate } c++ // (1) template void interpolate_noalias(Expr&& expr, Tag strategy) // (2) template void interpolate(Expr&& expr, Tag strategy) // (3) template DOFVector& operator<<(Expr&& expr)  (1) Interpolation of a GridFunction (or Expression) to the DOFVector, assuming that there is no reference to this DOFVector in the expression (no aliasing). (2) Interpolation of a GridFunction (or Expression) to the DOFVector, allowing aliasing. (3) Operator notation of (2) using averaging strategy. In case *aliasing* is allowed, a temporary DOFVector is created first as copy of *this* and the interpolation performed on the temporary using *noalias* interpolation (1). Then, this tempoary is moved back to *this*. #### Arguments Expr expr : An Expression representing a GridFunction Tag strategy : An interpolation strategy, either tag::average or tag::assign. The average strategy accumulates interpolation values on each dof and takes the average by dividing by the number of assignees. The assign strategy diretly assigns an interpolation value to a dof that might be overwritten in a subsequent interpolation step. ## function makeDOFVector Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp) c++ template DOFVector<...> makeDOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE)  Creates a DOFVector from a basis. This generator function accepts the basis as reference, temporary, or shared_ptr. Internally the reference is wrapped into a non-destroying shared_ptr and the temporary is moved into a new shared_ptr, see [DOFVector::DOFVector](#function-dofvectordofvector). The DataTransferOperation controls what is done during grid changes with the DOFVector. The default is interpolation of the data to the new grid. #### Arguments Basis basis : Reference, temporary, or shared_ptr to dune global basis or ParallelGlobalBasis DataTransferOperation op : The operation performed during data-transfer, either DataTransferOperation::INTERPOLATE or DataTransferOperation::NO_OPERATION #### Template types T : The type of the coefficients to store in the DOFVector #### Return value Returns a DOFVector with GlobalBasis = ParallelGlobalBasis::PreBasis>. The underlying type is either the remove_cvref_t for references, or the pointed-to type for smart pointers. #### Example c++ using namespace Dune::Functions::BasisFactory; // pass a reference to the basis ParallelGlobalBasis basis1(gridView, lagrange<2>()); auto vec1 = makeDOFVector(basis1); // pass a smart pointer auto basis2 = std::make_shared(basis1); auto vec2 = makeDOFVector(basis2, DataTransferOperation::NO_OPERATION);  ## class DiscreteFunction Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp) c++ template class DiscreteFunction  A DiscreteFunction is the interpretation of a DOFVector as grid function. ### Template parameters Coefficients : Type of the coefficient vector GlobalBasis : The type of the global basis associated with the DOFVector TreePath : The path in the basis tree representing the subspace represented by this DiscreteFunction ### Member Types Member Type | Definition ---------------------|--------------------------------------------- EntitySet | Set of entities the DiscreteFunction is defined on, GridViewEntitySet Domain | Global coordinates of the EntitySet Range | Range type of this DiscreteFunction, given by sub-tree and coefficient type ### Member functions of the const DiscreteFunction Function | Descriptions --------------------------------|--------------------------------------------- [*(constructor)*](#function-discretefunctiondiscretefunction) | Construct the const DiscreteFunction [entitySet](#function-discretefunctionentityset) | Return the stored GridViewEntitySet [basis](#function-discretefunctionbasis) | Return global basis bound to the DOFVector [treePath](#function-discretefunctiontreepath) | Return the treePath associated with this discrete function [coefficients](#function-discretefunctioncoefficients) | Return const coefficient vector [child](#function-discretefunctionchild) | Return the sub-range view of this DiscreteFunction ### Member functions of the mutable DiscreteFunction Function | Descriptions --------------------------------|--------------------------------------------- [*(constructor)*](#function-discretefunctiondiscretefunction) | Construct the mutable DiscreteFunction [interpolate_noalias](#function-discretefunctioninterpolate) | Interpolation of GridFunction to DOFVector assuming no aliasing [interpolate](#function-discretefunctioninterpolate) | Interpolation of GridFunction to DOFVector [operator<<](#function-discretefunctioninterpolate) | Interpolation of GridFunction to DOFVector [operator+=](#function-discretefunctioninterpolate) | Accumulated interpolation of GridFunction to DOFVector [operator-=](#function-discretefunctioninterpolate) | Accumulated interpolation of GridFunction to DOFVector ## function DiscreteFunction::DiscreteFunction c++ // (1) DiscreteFunction(DOFVector const& dofVector, TreePath const& treePath = {}) // (2) DiscreteFunction(DOFVector& dofVector, TreePath const& treePath = {})  Construction of a DiscreteFunction from a const (1) or mutable (2) DOFVector. The corresponding constructor is only available for the const or mutable is_const template parameter specialization. #### Arguments DOFVector<...> dofvector : The container storing the global coefficients. Is stored as pointer in the DiscreteFunction and thus must have a longer lifetime than the DiscreteFunction. TreePath treePath : A Dune::TypeTree::HybridTreePath<...> representing the coordinates of a node in the basis tree this DiscreteFunction is defined on. The type of the treePath also defines the Range type of the DiscreteFunction. #### See Also - Generator function to construct a DiscreteFunction: [makeDiscreteFunction()](#function-makediscretefunction) ## function DiscreteFunction::entitySet c++ EntitySet const& entitySet() const  Returns a Dune::Functions::GridViewEntitySet of the GridView associated to the GlobalBasis. ## function DiscreteFunction::basis c++ std::shared_ptr basis() const  Returns the global basis bound to the DOFVector. ## function DiscreteFunction::treePath c++ TreePath const& treePath() const  Returns the treePath associated with this DiscreteFunction. ## function DiscreteFunction::coefficients c++ DOFVector const& coefficients() const // (1) DOFVector& coefficients() // (2)  Returns the const (1) or mutable (2) coefficient vector. ## function DiscreteFunction::child c++ // (1) template auto child(TreePath const& path = {}) const // (2) template auto child(TreePath const& path = {})  Returns the const (1) or mutable (2) sub-range view of the stored DOFVector. #### Arguments TreePath path : A Treepath identifying a node in the basis tree. #### Example c++ ParallelGlobalBasis basis(gridView, power<3>(lagrange<1>())); auto vec = makeDOFVector(basis); auto df = makeDiscreteFunction(vec); auto df1 = df.child(); auto df2 = df.child(0); auto df3 = df.child(_0);  ## function DiscreteFunction::interpolate* {: #function-discretefunctioninterpolate } c++ // (1) template void interpolate_noalias(Expr&& expr, Tag strategy) // (2) template void interpolate(Expr&& expr, Tag strategy) // (3) template DiscreteFunction& operator<<(Expr&& expr) // (4) template DiscreteFunction& operator+=(Expr&& expr) // (5) template DiscreteFunction& operator+=(Expr&& expr)  (1) Interpolation of a GridFunction (or Expression) to the subtree of the DOFVector, assuming that there is no reference to this DOFVector in the expression (no aliasing). (2) Interpolation of a GridFunction (or Expression) to the subtree of the DOFVector, allowing aliasing. (3) Operator notation of (2) using averaging strategy. (4) Interpolate (*this) + expr to the subtree of the DOFVector. (5) Interpolate (*this) - expr to the subtree of the DOFVector. In case *aliasing* is allowed, a temporary DOFVector is created first as copy of *this* and the interpolation performed on the temporary using *noalias* interpolation (1). Then, this tempoary is moved back to *this*. Note, the range type of the expression must be compatible with the Range type of the DiscreteFunction. #### Arguments Expr expr : An Expression representing a GridFunction Tag strategy : An interpolation strategy, either tag::average or tag::assign. The average strategy accumulates interpolation values on each dof and takes the average by divising through the number of assignees. The assign strategy diretly assigns an interpolation value to a dof that might be overwritten in a subsequent interpolation step. #### Example c++ ParallelGlobalBasis basis(gridView, power<3>(lagrange<1>())); auto vec = makeDOFVector(basis); auto df1 = vec.child(); auto df2 = vec.child(0); // Range type is FieldVector df1 << [](FieldVector const& x) -> FieldVector { return x; }; // Range type is double df2 += 42.0;  ## function makeDiscreteFunction Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp) c++ // (1) template > auto makeDiscreteFunction(DOFVector const& dofVector, PreTreePath const& preTreePath = {}) // (2) template > auto makeDiscreteFunction(DOFVector& dofVector, PreTreePath const& preTreePath = {})  Constructs a const (1) or mutable (2) DiscreteFunction from a DOFVector and a tree path. The TreePath can therby by given by a pree-tree path, i.e. a sequence of integers or integral constants a Dune::TypeTree::HybridTreePath can be constructed from. #### Arguments DOFVector<...> dofVector : The container storing the global coefficients. Is stored as pointer in the DiscreteFunction and thus must have a longer lifetime than the DiscreteFunction. PreTreePath preTreePath : A pree-tree path, a Dune::TypeTree::HybridTreePath<...> can be created from. #### Return value Returns a DiscreteFunction if the DOFVector is const, or a DiscreteFunction if the DOFVector is mutable. The TREE_PATH is thereby given by the type of makeTreePath(preTreePath). #### Example c++ using namespace Dune::Functions::BasisFactory; // pass a reference to the basis ParallelGlobalBasis basis(gridView, power<2>(lagrange<2>())); auto vec = makeDOFVector(basis1); auto df1 = makeDiscreteFunction(vec); auto df2 = makeDiscreteFunction(vec, 1); auto df3 = makeDiscreteFunction(vec, _1); auto df4 = makeDiscreteFunction(vec, Dune::TypeTree::hybridTreePath(0));