From 294df099a4043c6038cb50b74e6aceadb9c44c82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20M=C3=BCller?= Date: Tue, 29 Sep 2020 17:23:48 +0200 Subject: [PATCH 1/5] Fix broken links --- docs/reference/DOFVector.md | 28 ++++++++++++++-------------- docs/reference/GridFunctions.md | 4 ++-- docs/reference/Operators.md | 14 +++++++------- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/reference/DOFVector.md b/docs/reference/DOFVector.md index 21fb3756..027bdda2 100644 --- a/docs/reference/DOFVector.md +++ b/docs/reference/DOFVector.md @@ -3,7 +3,7 @@ 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. +into a [GridFunction](../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 @@ -68,21 +68,21 @@ The value_type is often the same as T, but might be just something similar, [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)" +??? seealso "Functions inherited from [VectorFacade](../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 + [basis](../MatVecBase#function-vectorbasebasis) | Return the GlobalBasis associated with the vector + [backend](../MatVecBase#function-vectorbasebackend) | Return the backend vector wrapper implementing the actual algebra + [localSize,globalSize](../MatVecBase#function-vectorbasesize) | The number of entries in the local part of the vector + [resize,resizeZero](../MatVecBase#function-vectorbaseglobalSize)| Resize the vector to the size of the basis + [init](../MatVecBase#function-vectorbaseglobalSize) | Prepare the vector for insertion of values + [finish](../MatVecBase#function-vectorbaseglobalSize) | Finish the insertion of values + [at](../MatVecBase#function-vectorbaseat) | Return the value of the vector at the given local index + [insert,set,add](../MatVecBase#function-vectorbaseinsert) | Insert a single value into the matrix + [gather](../MatVecBase#function-vectorbasegather) | Extract values from the vector referring to the given local indices + [scatter](../MatVecBase#function-vectorbasescatter) | Insert a block of values into the vector + [copy](../MatVecBase#function-vectorbasescatter) | Copies a block of values into the vector + [forEach](../MatVecBase#function-vectorbasescatter) | Apply a functor to each value at given indices ## function DOFVector::DOFVector diff --git a/docs/reference/GridFunctions.md b/docs/reference/GridFunctions.md index 50e14daf..fc33b438 100644 --- a/docs/reference/GridFunctions.md +++ b/docs/reference/GridFunctions.md @@ -35,7 +35,7 @@ elementary terms. ### Examples of expressions Before we give examples where and how to use GridFunctions, we demonstrate what an Expression could be, to create a GridFunction from. In the following examples, -we assume that a [ProblemStat](reference/Problem#class-problemstat) named prob is already +we assume that a [ProblemStat](../Problem#class-problemstat) named prob is already created and initialized. #### 1. Discrete Functions @@ -95,7 +95,7 @@ prob.addMatrixOperator(opB, Row, Col); auto opL = makeOperator(LinearForm, Expression); prob.addVectorOperator(opL, Row);  -See also [makeOperator()](reference/Operators#function-makeoperator). +See also [makeOperator()](../Operators#function-makeoperator). #### 2. Usage of GridFunctions in BoundaryConditions: c++ diff --git a/docs/reference/Operators.md b/docs/reference/Operators.md index 37cfcc13..3c977d6f 100644 --- a/docs/reference/Operators.md +++ b/docs/reference/Operators.md @@ -19,9 +19,9 @@ auto makeOperator(Tag tag, Expr&& expr, QuadratureArgs&&... args)  Constructs a GridFunctionOperator that can be passed to a -[ProblemStat](reference/Problem#class-problemstat) in the member functions -[addMatrixOperator()](reference/Problem#function-problemstataddmatrixoperator) -or [addVectorOperator()](reference/Problem#function-problemstataddvectoroperator). +[ProblemStat](../Problem#class-problemstat) in the member functions +[addMatrixOperator()](../Problem#function-problemstataddmatrixoperator) +or [addVectorOperator()](../Problem#function-problemstataddvectoroperator). The tag therby identifies which type of operator to create, the expr is used as a coefficient function in the operator and the optional quadrature arguments are used to determine a quadrature rule for the integration of the operator on an @@ -35,14 +35,14 @@ element. zero-order terms, first-order terms, and second-order terms. See the examples below. Expr expr -: An Expression is anything, a [GridFunction](reference/GridFunctions) can +: An Expression is anything, a [GridFunction](../GridFunctions) can be created from, sometimes also called PreGridFunction. It includes constants, functors callable with GlobalCoordinates, and any combination of GridFunctions. QuadratureArgs args... : Arguments that are passed to a quadrature creator. Anything that needs a quadrature formula needs to determine the (approximative) polynomial degree - of the GridFunctions. If the [GridFunction](reference/GridFunctions) builds a + of the GridFunctions. If the [GridFunction](../GridFunctions) builds a polynomial expression, it can be deduced automatically, i.e. if it includes constants, DOFVectors, and arithmetic operator operator+, operator-, or operator*. If the polynomial order can not be deduced, the compiler gives an error. Then, this @@ -112,7 +112,7 @@ special basis, like a taylor-hood basis. ### Examples #### Tags and expressions The general procedure to describe a PDE is to decompose it into individual terms and add -all of them to a [ProblemStat](reference/Problem#class-problemstat): +all of them to a [ProblemStat](../Problem#class-problemstat): c++ using Grid = /* any dune grid type */; using Traits = TaylorHoodBasis; @@ -245,4 +245,4 @@ prob.addMatrixOperator(op, 0, 0); prob.addVectorOperator(op, 0);  -See also an example of usage in the examples folder examples/convection_diffusion.cc \ No newline at end of file +See also an example of usage in the examples folder examples/convection_diffusion.cc -- GitLab From ebf6682076035ca468c48e0646131d3a9b0ba990 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20M=C3=BCller?= Date: Fri, 17 Jul 2020 16:25:51 +0200 Subject: [PATCH 2/5] Add global basis use instructions and reference --- docs/reference/GlobalBasis.md | 201 ++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 202 insertions(+) create mode 100644 docs/reference/GlobalBasis.md diff --git a/docs/reference/GlobalBasis.md b/docs/reference/GlobalBasis.md new file mode 100644 index 00000000..2df96016 --- /dev/null +++ b/docs/reference/GlobalBasis.md @@ -0,0 +1,201 @@ +# Global Basis {: #group-globalbasis } +## Summary +In the context of the finite-element method we use a finite-element space $V$ with the set of basis functions $\{\phi_i\}$. Within AMDiS this concept is realized by the class ParallelGlobalBasis, contained in the header file amdis/functions/ParallelGlobalBasis.hpp. This extends the interface of the underlying Dune::Functions::DefaultGlobalBasis with an automatic update mechanism used in several places within AMDiS. We strongly advice to always use an AMDiS::ParallelGlobalBasis or a user-defined derived class instead of the DUNE data structure for the update mechanism to work properly. +For more information on the class interface visit the API documentation. + +## PreBasis classes and basis trees +Many finite-element spaces in applications can be constructed as a product of simple spaces $V = V_1 \times V_2 \times \dots \times V_k$. For example the Taylor-Hood-Element can be constructed as $V_{TH} = V_{v} \times V_{p}$ with the space of velocity functions $V_v$ and pressure functions $V_p$. The velocity space can again be decomposed into the vector components $V_v = V_{v_1} \times \dots \times V_{v_n}$. If we use second-degree lagrange basis functions for the velocity space and first-order lagrange basis functions for the pressure we get a decomposition $V_{TH} = V_{v_1} \times V_{v_n} \times V_p = L_2^n \times L_1$. + +The underlying numerics environment of AMDiS, DUNE, attempts to model the situation above. Hence a ParallelGlobalBasis in AMDiS can be defined by a tree structure using the Dune-PreBasis class, which itself is composed of nodes in a tree. The leaf nodes in this tree contain the implementation details of the simple basis, while inner nodes indicate composition of either identical children (called power nodes) or arbitrary children (called composite nodes). + +### Making a PreBasis +When we want to build a PreBasis we must first identify the structure of the basis we want to construct with a tree. We can then build that structure in AMDiS by nesting the functions Dune::Functions::BasisFactory::composite(Nodes...[, MergingStrategy]) for composite nodes, Dune::Functions::BasisFactory::power(Node[, MergingStrategy]) for power nodes and implementations (e.g. Dune::Functions::BasisFactory::lagrange())). The second optional argument MergingStrategy provides merging strategies to the inner nodes, specifying how the indices of the simple leaf basis should be merged to obtain the indexing of the global basis. Currently only flat indexing is supported by AMDiS. +The following code snippet shows how a PreBasisFactory for a Taylor-Hood-Element is constructed, that can later be used to build a global basis. + +c++ +using namespace Dune::Functions::BasisFactory; + +const int dow = 2; // world dimension +const int k = 1; // order parameter +auto taylorHoodPreBasisFactory = + composite( + power( + lagrange() + ), + lagrange() + ); + +auto taylorHoodPreBasisFactoryWithMergingStrategy = + composite( + power( + lagrange(), + flatInterleaved() + ), + lagrange(), + flatLexicographic() + ); + + +## Making a global basis +Using a PreBasisFactory we can easily make a global basis by defining the set of grid elements on which the basis functions of the FE-space should live. This can be done by providing a GridView and using the ParallelGlobalBasis constructors. An optional name can be provided that can be used to pass initfile parameters to the parallel communication class. + +c++ + // Name, Grid and Dune::DefaultGlobalBasis arguments + template + ParallelGlobalBasis(std::string const& name, Grid const& grid, Args&&... args); + + // As above with name defaulting to "" + template + ParallelGlobalBasis(Grid const& grid, Args&&... args); + + // Name, GridView and PreBasisFactory + template + ParallelGlobalBasis(std::string const& name, GridView const& gridView, PBF const& preBasisFactory); + + // As above with name defaulting to "" + template + ParallelGlobalBasis(GridView const& gridView, PBF const& preBasisFactory); + + +If we use a ProblemStat object most of the work will be done automatically for us. The PreBasis is specified via a Traits template parameter with the most frequently used cases already included in amdis/ProblemStatTraits.hpp. Those include + +c++ + // Composition of any number of lagrange bases with any degree + template + struct LagrangeBasis; + + // As above but a structured grid is chosen + template + struct YaspGridBasis; + + // The taylor-hood basis as discussed above + template + struct TaylorHoodBasis; + + +If one of the above traits class is provided ProblemStat will create a new global basis on a call to ProblemStat::initialize. Afterwards a pointer to the basis can be obtained using the function ProblemStat::globalBasis. + +c++ +using Grid = Dune::YaspGrid<2>; // 2-dimensional structured grid +ProblemStat> prob("myProblem"); +prob.initialize(INIT_ALL); +auto& basis = *prob.globalBasis(); + + +## Using the global basis +The ParallelGlobalBasis provides access to element indices and basis functions in the same way as a Dune-basis does, it is even derived from the Dune::DefaultGlobalBasis. + +### Getting the total number of DOFs +If we are simple interested in getting the total number of DOFs the basis contains we can simply call basis.dimension(). This can be useful for preparing matrices and vectors for insertion. + +c++ +std::size_t maxSize = basis.dimension(); +std::vector dofs; +dofs.resize(maxSize); + + +### Access to local basis functions using a LocalView +Within that interface we are restricted to elementwise access using a LocalView. This provides us with a way to work with the local basis functions on one grid element. We show a typical use in the following snippet. Note how we first need to bind the LocalView before we can use it. + +c++ +auto localView = basis.localView(); +for (const auto& e : elements(basis.gridView())) // loop over all grid elements the basis is defined on +{ + localView.bind(e); // a LocalView must be bound to an element before being used + // do something + localView.unbind(); +} + + +A bound LocalView has the method LocalView::index(size_type) mapping a local index to a global index. In other words it maps a local basis function defined on an element to its corresponding global basis function. We can use that to build a global stiffness matrix from local contributions on a single element and then insert those into a single matrix in global indices. +Another method is LocalView::tree() that returns the root node of the local basis tree. The main method all nodes share is Node::localIndex(size_type) which maps a leaf node index to the local index within the local basis tree. + +#### The for_each_node and for_each_leaf_node helper functions +Quite often we want to perform operations on certain nodes of the tree other than the root node. This can be useful if we want to work with the actual implementations wich are usually leaf nodes. For this we can use the helper functions for_each_node and for_each_leaf_node defined in amdis/typetree/Traversal.hpp. Those functions traverse the tree and call the given function on every (leaf) node with the node and a type of tree index we shall explain later as arguments. we show the usage with the following example using the Taylor-Hood-Basis defined above. Here we assume to have a LocalView localView that is bound to an element. + +c++ +auto root = localView.tree(); +for_each_leaf_node(root, [&](auto const& node, auto const& tp) { + // do something on node +}); + + +#### Working on specific nodes using a TreePath {: #globalbasis-using-treepath } +There are cases when we want to address a certain tree node. To come back to our Taylor-Hood example we might want to add an operator that only acts on the velocity vector or the pressure, or even just a single component of the velocity vector. For this end a type of node index exists, called TreePath. This defines a list of indices specifying which path to take from the root at each node on the way. For technical reasons the index type is either an int (for power nodes) or std::integral_constant for composite nodes. For convenience we can use Dune::Indices::_0 instead of writing std::integral_constant. Note how indices always start at 0 and follow the order we specify when creating the PreBasis. +Using once again the Taylor-Hood basis we can use the treepath(Args...) function to convert indices into a TreePath for certain nodes. + +c++ +auto tp_v = treepath(Dune::Indices::_0); // velocity vector +auto tp_p = treepath(Dune::Indices::_1); // pressure +auto tp_v2 = treepath(Dune::Indices::_0, 1); // second component of the velocity vector +auto tp_root = treepath(); // root + + +Recall that localView.tree() returns the root of the basis tree. Using a TreePath we can access a specific node using the free funtion Dune::TypeTree::child(Node, TreePath). + +c++ +auto root = localView.tree(); +auto node_v = Dune::TypeTree::child(root, tp_v); // power node representing the velocity vector +auto node_p = Dune::TypeTree::child(root, tp_p); // lagrange node representing the pressure + + +### Using the lagrange (pre-)basis +Many applications require only lagrange elements or compositions, for example a Navier-Stokes problem may use the Taylor-Hood basis we introduced above that consists of dim second order lagrange elements and one first order lagrange element. For that reason we will now take a closer look at the implementation of those lagrange elements in AMDiS. +AMDiS borrows the implementation from the underlying DUNE-functions module. This defines lagrange elements of a given order k. Recall that we can add lagrange nodes to a (pre-)basis using Dune::Functions::BasisFactory::lagrange(). In the previous section we have seen how we can access the leaf nodes of a basis. With that we can get the implementation of the local finite element with the function Dune::Functions::LagrangeNode::finiteElement(). +We shall show the usage of the local finite element class handed out by the function above. Its interface defines the functions size(), localCoefficients(), localInterpolation() and localBasis(). We shall explain those with an example. Assume we have localView bound to an element and have vectors dofs and dofs2 that store the coefficients of some grid function with global indexing (e.g. a solution vector). Domain is the type used for local coordinates of the reference element. + +c++ +auto root = localView.tree(); +for_each_leaf_node(root, [&](auto const& node, auto const& tp) { + // Extract some types from the node + using Node = Underlying_t; + using LocalFunction = typename Node::FiniteElement::Traits::LocalInterpolationType::FunctionType; + using Domain = typename LocalFunction::Traits::DomainType; + using Range = typename LocalFunction::Traits::RangeType; + + auto const& fe = node.finiteElement(); + auto feSize = fe.size(); + + // get information about the position of a basis function in the element + auto const& localCoefficients = fe.localCoefficients(); + for (std::size_t i = 0; i < feSize; ++i) + { + auto const& localKey = localCoefficients.localKey(i); + // do something + } + + // interpolate a local function onto an element + auto f_ = [](Domain const& x) -> Range { return x[0] + x[1]; }; + auto f = functionFromCallable(f_); + std::vector localCoeff; + fe.localInterpolation().interpolate(f, localCoeff); // interpolate f onto the local basis + for (std::size_t i = 0; i < feSize; ++i) + { + std::size_t globalIndex = localView.index(node.localIndex(i)); // get the global index + dofs[globalIndex] = localCoeff[i]; // set global coefficient to the local coefficient + } + + // evaluate at a local coordinate + std::vector localContrib(feSize); + fe.localBasis().evaluateFunction({0.2, 0.2}, localContrib); // get contributions of local basis functions at a given local coordinate + Range sum = 0; + for (std::size_t i = 0; i < feSize; ++i) + { + std::size_t globalIndex = localView.index(node.localIndex(i)); // get the global index + sum += dofs2[globalIndex] * localContrib[i]; // add contribution from i-th local basis function + } +}); + + +### Keeping indices and data updated when the grid changes +Within an adaptive simulation we may want to add or remove grid elements by refinement or coarsening. When this happens the number of total elements or their relative position may change. Therefore the indexing scheme used by the global basis must be updated when changes to the underlying grid happen. +For this purpose the update method exists, which takes a GridView of the Grid after it has been changed as its only argument. + +c++ + void update(GridView const& gv) + + +Usually we do not need to call this function - out of the box AMDiS with a ProblemStat doing most of the work will automatically call it for us. If user code is working with the underlying Dune-Grid directly there is no way for AMDiS to detect if any changes happen to it, therefore update must be called manually in such a scenario. + +### The globalRefineCallback function +Certain grid managers support the use of a callback function when doing global refinement. Using a ParallelGlobalBasis in this context is currently not supported. diff --git a/mkdocs.yml b/mkdocs.yml index 9e6b6034..06def300 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,6 +17,7 @@ nav: - tutorials/grids-and-discretefunctions.md - Reference: - DOFVector and DiscreteFunction: reference/DOFVector.md + - GlobalBasis: reference/GlobalBasis.md - GridFunctions: reference/GridFunctions.md - Operators: reference/Operators.md - Problem: reference/Problem.md -- GitLab From 8a9f959ff76ed077a24aa9764669f45aaa161f73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20M=C3=BCller?= Date: Tue, 21 Jul 2020 17:54:38 +0200 Subject: [PATCH 3/5] Add documentation for initfile parameters --- docs/reference/Initfile.md | 302 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 303 insertions(+) create mode 100644 docs/reference/Initfile.md diff --git a/docs/reference/Initfile.md b/docs/reference/Initfile.md new file mode 100644 index 00000000..f3477f3b --- /dev/null +++ b/docs/reference/Initfile.md @@ -0,0 +1,302 @@ +# Parameter file {: #group-initfile } +## Summary +Many functionalities of an AMDiS program can be controlled using a parameter file. This file is passed as first argument to the AMDiS executable. If we want to run the ellipt.2d example using the parameter file init/ellipt.dat.2d we can do so using the following console command in the examples directory: + + +./ellipt.2d init/ellipt.dat.2d [other arguments] + + +We will give a list of possible parameters at the [end of this document](#list-of-parameters-and-values). + +## Structure of a parameter file +Parameters in the parameter file have keys in the form of strings separated by ->. This allows grouping of parameters that are related to the same things. High-level classes like ProblemStat have a string constructor argument where a name can be provided that relates to an initfile key. + +c++ +examples/ellipt.cc: + using Param = LagrangeBasis; + ProblemStat prob("ellipt"); // make a ProblemStat with the name 'ellipt' + + + +examples/init/ellipt.dat.2d: + ellipt->mesh: elliptMesh % name of the mesh created by 'ellipt' + elliptMesh->num cells: 8 8 % size of the mesh 'elliptMesh' + + ellipt->solver: pcg % solver type used by 'ellipt' + ellipt->solver->max iteration: 10000 % solver parameter related to 'ellipt->solver' + + +As we saw above, parameters are separated from the keys with the : character and can be strings and numbers. Anything following a % character is considered a comment. + +## Reading from a parameter file +In the section above we learned that AMDiS classes can be given names that can then be used to specify parameters in the parameter file. In addition to the options AMDiS classes already provide we can add user-defined parameters. For this we simply have to add a key: value pair to the parameter file as we would do with the built-in options and read the value somewhere in our program using the function Parameters::get: + +c++ +// (1) Overwrites 'value' with the value related to 'key' if found +template +static void get(std::string const& key, T& value); + +// (2) Returns a std::optional containing the value related to 'key' if found +template +static std::optional get(std::string const& key); + + +We will now give an example of reading an int parameter called myParameter from an initfile that defaults to 3 if no parameter file containing the key is provided. + + +// example parameter file entry +myParameter: 42 + + +c++ +// using (1) +int i = 3; +Parameters::get("myParameter", i); + +// using (2) +int i = Parameters::get("myParameter").value_or(3); + + +## Writing to a parameter file +It is possible to change to value of a parameter given in a parameter file using the function + +c++ +template +static void set(std::string const& key, T const& value); + + +This can be useful if we want to override certain values within our program. + +## List of parameters and values +In the following section  denotes a placeholder for the name given to the class instance.  is a (possibly empty) comma-separated list of integers specifying a [TreePath](../GlobalBasis#globalbasis-using-treepath). + +### ProblemStat + key | type | values | default value +------------------------------|--------|--------------------------------|------------- +->mesh | string | Prefix used by the mesh | mesh +->restore->grid | string | Filename of the grid file | Not optional1 +->restore->solution | string | Filename of the solution file | Not optional1 +->symmetry | string | Symmetry of the stiffness matrix, one of:
spd,
symmetric,
hermitian,
structurally_symmetric,
unknown | unknown +->solver | string | Solver type, see [Solvers and Preconditioners](#solvers-and-preconditioners) | default +->marker[]| string | Prefix for marker parameters, see [Markers](#markers) | None2 +->output[]| string | Prefix for filewriter parameters, see [Filewriters](#filewriters)| None3 +->output | string | as ->output[] | None3 + +1Only required when ProblemStat::restore is called
+2No marker will be set up if the ->strategy subkey is not specified
+3No filewriter will be set up if the ->format subkey is not specified
+ +### Markers + key | type | values | default value +-------------------------------------|--------|----------------------------------|------------- +->strategy | string | Marking strategy, one of:
0 (no marking),
1 (global refinement),
2 (maximum strategy),
3 (equidistribution strategy),
4 (guaranteed error reduction strategy) | Not optional +->info | int | Verbosity | 0 +->max refinement level | int | Maximum refinement level | No maximum +->min refinement level | int | Minimum refinement level | 0 +->p123 | double | Power in estimator norm | 2.0 +->MSGamma1 | double | Marking parameter | 0.5 +->MSGammaC1 | double | Marking parameter | 0.1 +->ESTheta2 | double | Marking parameter | 0.9 +->EsThetaC2 | double | Marking parameter | 0.2 +->GERSThetaStar3| double | Marking parameter | 0.6 +->GERSNu3 | double | Marking parameter | 0.1 +->GERSThetaC3 | double | Marking parameter | 0.1 + +1Only for maximum strategy
+2Only for equidistribution strategy
+3Only for guaranteed error reduction strategy
+ +### Solvers and Preconditioners +#### Parameters used by the SolverInfo class + key | type | values | default value +-------------------------------------|--------|----------------------------------|------------- +->info | int | Solver verbosity level | 0 +->break if tolerance not reached|bool| If true throw an error if tolerance could not be reached| false + +#### PETSc + key | type | values | default value +--------------------------------|---------|----------------------------------|------------- +->info | int | Verbosity, one of:
0 (no convergence information),
1 (minimal output, print residual every 10th iteration),
2 (full convergence output) | 0 +->ksp | string | Name of a PETSc Krylov methoda| default + | string | alternative to ->ksp when not set | as above +->max it |PetscInt | Verbosity | PETSC_DEFAULT +->rtol |PetscReal| Relative convergence toleranceb| PETSC_DEFAULT +->atol |PetscReal| Absolute convergence toleranceb| PETSC_DEFAULT +->divtol |PetscReal| Divergence toleranceb | PETSC_DEFAULT +->prefix | string | The options prefix for the solverc | No prefix set +->mat solver | string | Sets the software that is used to perform the factorization d| umfpack (sequential matrix) or mumps (otherwise) +->pc | string | The preconditioner typee| default +->pc->mat solver1|string| Solver used by the LU preconditionerd| None +->pc->prefix | string | The options prefix for the preconditionerf|No prefix set +->scale2 |PetscReal| Damping factor used by richardson solver | 1.0 +->restart3 |PetscInt | Number of iterations until restart | 30 +->gramschmidt3|string| Orthogonalization routine used by gmres solversg: classical or modified | Use PETSc default +->restart3 | string | Type of iterative refinement to use in the classical Gram Schmidt orthogonalizationh, one of:
never (never refine),
ifneeded (refine if needed),
always (always refine)| Use PETSc default +->ell4 |PetscReal| Number of search directions in BiCGStab_ell| Use PETSc default +->restart5 |PetscInt | Number of iterations until restart | Use PETSc default + +1Only for lu preconditioner
+2Only for richardson solver
+3Only for gmres solver types
+4Only for BiCGStab_ell solver
+5Only for GCR solver
+ +aSee [PETSc documentation for Krylov methods](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPType.html)
+bSee [PETSc documentation for Krylov method tolerances](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetTolerances.html)
+cSee [PETSc documentation for Krylov method options](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOptionsPrefix.html)
+dSee [PETSc documentation for preconditioners](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCFactorSetMatSolverType.html)
+eSee [PETSc documentation for preconditioners](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCType.html)
+fSee [PETSc documentation for preconditioners](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCSetOptionsPrefix.html)
+gSee [PETSc documentation for GMRes solver](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESSetOrthogonalization.html)
+hSee [PETSc documentation for GMRes solver](https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPGMRESSetCGSRefinementType.html)
+ +#### EIGEN + key | type | values | default value +-------------------------------------|----------|-------------------------------------|---------- + | string | Solver type, one of:
cg (conjugate gradient solver),
bicgstab (bi-conjugate gradient stabilized solver),
bcgs (same as bicgstab),
minres (minimal residual algorithm for symmetric matrices),
gmres (generalized minimal residual algorithm),
dgmres (restarted gmres with deflation),
default (same as gmres),
umfpack1 (sparse LU factorization based on UmfPack),
superlu2 (sparse LU factorization based on SuperLU library),
direct (same as umfpack or superlu) | default +->reuse pattern | bool | Reuse matrix pattern if true | false +->relative tolerance |RealScalar| Tolerance threshold used by the stopping criteria| floating-point epsilon +->max iteration | int | Maximum number of iterations | 500 +->restart34 | int | Number of iterations until restart | 30 +->num eigenvalues4| int | Number of eigenvalues to deflate at each restart| 0 +->max num eigenvalues4|int | Maximum size of the deflation subspace| 5 +->precon->name5 | string | Preconditioner, one of:
no (no preconditioner),
diag (diagonal preconditioner),
jacobi (diagonal preconditioner),
ilu (incomplete LU factorization),
ic (incomplete Choleski factorization) | no +->precon->ordering6|string | Ordering used in Choleski factorization: amd or natural | amd +->precon->drop tolerance7|double| Drop any element whose magnitude is less than this tolerance| 1e-15l +->precon->fill factor7|int | This is used to compute the number of largest elements to keep on each row| 10 + +1Requires UmfPack
+2Requires SuperLU
+3Only for gmres solver
+4Only for dgmres solver
+5Does not apply to umfpack or superlu solvers
+6Only for incomplete Choleski factorization
+7Only for ilu solver
+ +#### MTL + key | type | values | default value +-------------------------------------|--------|----------------------------------|------------- + | string | Solver type, one of:
cg (conjugate gradient method),
cgs (stabilized conjugate gradient method),
bicg (BiCG method),
bcgs (stabilized BiCG(1) method),
bicgstab (as bcgs),
bcgs2 (stabilized BiCG(2) method),
bicgstab2 (as bcgs2),
qmr (quasi-minimal residual method),
tfqmr (transposed-free quasi-minimal residual method),
bcgsl (stabilized BiCG(ell) method),
bicgstab_ell (as bcgsl),
gmres (generalized minimal residual method),
fgmres (flexible gmres),
minres (minimal residual method),
idrs (induced dimension reduction method),
gcr (generalized conjugate residual method),
preonly (just apply a preconditioner),
default (as gmres),
umfpack1 (external UMFPACK solver),
direct (as umfpack) | default +->absolute tolerance2| type of matrix values | Absolute solver tolerance: ∥b-Ax∥ < absolute tolerance | 0 +->relative tolerance2| type of matrix values | Relative solver tolerance: ∥b-Ax∥ / ∥b-Ax0∥ < relative tolerance | 1.e-6 +->max iteration2| int | Maximal number of iterations | 1000 +->print cycle2 | int | Print solver residuals every print cycle iterations | 100 +->store symbolic3| bool | | false +->symmetric strategy3|int| | 0 +->alloc init3 | double | | 0.7 +->ell4 | int | Parameter of stabilized BiCG(ell)| 3 +->restart5 | int | Maximal number of orthogonalized vectors| 30 +->orthogonalization6|int | 1 (gram schmidt) or 2 (householder)| 1 +->s7 | int | Parameter of IDR(s) | 30 +->precon2 | string | Left preconditioner type, one of:
diag (diagonal preconditioner),
jacobi (as diag),
masslumping (mass lumping preconditioner),
ilu (incomplete LU preconditioner),
ilu0 (as ilu),
no (no preconditioner),
identity (as no),
solver (use a solver as preconditioner),
default (as no),
hypre8 (Hypre preconditioner) | default +->precon->solver9| int | Solver type used for the preconditioner, same options as for | default + +1Requires UmfPack
+2Does not apply to umfpack solver
+3Only umfpack solver
+4Only bcgsl solver
+5Only gmres, fgmres and gcr solvers
+6Only gmres and fgmres solvers
+7Only idrs solver
+8Requires Hypre, see amdis/linearalgebra/mtl/HyprePrecon.hpp for subkeys and possible values
+9Only solver preconditioner, subkeys use the same values as above e.g. ->precon->solver->max iteration: 500
+ +#### ISTL + key | type | values | default value +-------------------------------------|--------|----------------------------------|------------- + | string | Solver type, one of:
cg (conjugate gradient method),
pcg (generalized preconditioned conjugate gradient solver),
fcg1 (accelerated flexible conjugate gradient method),
cfcg1 (complete flexible conjugate gradient method),
bcgs (stabilized bi-conjugate gradient method),
bicgstab (as bcgs),
default (as bcgs),
minres (minimal residul method),
gmres (generalized minimal residual method),
fgmres1 (flexible generalized minimal residual (FGMRes) method),
umfpack2 (external UMFPACK solver),
ldl2 (external LDL solver),
spqr2 (external SQPR solver),
cholmod2 (external Cholmod solver),
superlu2 (external SuperLU solver),
direct (as umfpack or superlu) | default +->info | int | Verbosity | 0 +->max iteration3| int | Maximal number of solver iterations| 500 +->relative tolerance3|type of matrix values| Relative break tolerance| 1.e-6 +->restart4 | int | Restart parameter | 30 +->reuse vector5 | bool | Reuse vectors in subsequent calls to apply if true| true +->category | string | sequential (sequential solver),
overlapping (overlapping parallel solver),
nonoverlapping (nonoverlapping parallel solver),
default (chooses depending on grid and process count)| None9 +->precon3 | string | Preconditioner type, one of:
diag (diagonal preconditioner),
jacobi (as diag),
gs (Gauss-Seidel preconditioner),
gauss_seidel (as gs),
sor (Successive Overrelaxation methods),
ssor (Symmetric Successive Overrelaxation methods),
pssor (A parallel SSOR preconditioner (requires overlap)),
richardson (Richardson methods),
default (as richardson),
solver (Turns a solver into a preconditioner),
bjacobi (Block-Jacobi methods),
ilu (Incomplete LU factorization),
ilu0 (as ilu),
ildl (Incomplete LDL factorization),
amg6 (Algebraic multigrid method),
fastamg6 (Algebraic multigrid method),
kamg6 (Algebraic multigrid method) | default +->precon->relaxation3|double| Dumping/relaxation factor | 1.0 +->precon->iterations3|int| Number of iterations | 1 +->precon->solver7|string | Solver type used for the preconditioner, same options as for | default +->precon->sub precon8|string| Preconditioner used in each block, same options as for ->precon| default +solver category | string | as ->category | default + +1Requires dune-istl 2.7
+2Requires external solver package
+3Only for cg, pcg, fcg, cfcg, bcgs, minres, gmres and fgmres solvers
+4Only for pcg and gmres solvers
+5Only for superlu solver
+6See amdis/linearalgebra/istl/AMGPrecon.hpp for subkeys and possible values
+7Only solver preconditioner, subkeys use the same values as above e.g. ->precon->solver->max iteration: 500
+8Only for bjacobi preconditioner, subkeys use the same values as above e.g. ->precon->sub precon->iterations: 1
+9Checks global parameter solver category if not set
+ +### Grids + key | type | values | default value +------------------------------|--------|----------------------------------|------------- +->macro file name | string | Filename of the mesh file | None1 +->structured2| string | Type of the structured grid, one of:
cube (rectangular or cube grid),
simplex (triangular or tetrahedral grid) | Grid dependant +->global refinements| int | Number of initial global refinement steps| 0 +->load balance | bool | Perform initial load balance if true| No load balance +->min corner2 | dim-sized array of global coordinates | lower left corner of the domain | (0,...,0) +->max corner2 | dim-sized array of global coordinates | upper right corner of the domain | (1,...,1) +->num cells2 | dim-sized array of int | number of blocks in each coordinate direction | (1,...,1) +->overlap3| int | Number of overlap elements on a distributed grid | 0 +->periodic3|string| String of ones and zeros indicating if the grid is periodic in the xyz-direction, e.g. 010 periodic in y-direction | 0...0 (not periodic) + +1If no file name is given a structured grid will be constructed
+2Only for structured grid generation
+3YaspGrid only
+ +### Adaptivity +#### Parameters used by the AdaptInfo class + key | type | values | default value +-----------------------------------|------|----------------------------------|------------- +->tolerance |double| Tolerance for the (absolute or relative) error | 0.0 +->time tolerance |double| Time tolerance | 0.0 +->time relative tolerance|double| Relative time tolerance | 0.0 +->coarsen allowed | int | 0 (coarsening not allowed),
1 (coarsening allowed)| 0 +->refinement allowed | int | 0 (refinement not allowed),
1 (refinement allowed)| 0 +->sum factor |double| Factor to combine max and integral time estimate|1.0 +->max factor |double| Factor to combine max and integral time estimate|0.0 +->start time |double| Initial time | 0.0 +->timestep |double| Time step size to be used | 0.0 +->end time |double| Final time | 0.0 +->max iteration | int | Maximal allowed number of iterations of the adaptive procedure| No maximum +->max timestep iteration | int | Maximal number of iterations for choosing a timestep|30 +->max time iteration | int | Maximal number of time iterations| 30 +->min timestep |double| Minimal step size | Square root of floating-point epsilon +->max timestep |double| Maximal step size | Square root of floating-point maximal value +->number of timesteps | int | Number of fixed timestep iterations | None1 +->time tolerance |double| Tolerance for the overall time error| 1.0 + +1If this is set to a nonzero value the computation is done number of timesteps times with a fixed time step size
+ +#### Parameters used by the AdaptInstationary class + key | type | values | default value +------------------------------|------|----------------------------------|------------- +->strategy | int | 0 (explicit time strategy),
1 (implicit time strategy),
2 (simple adaptive time strategy) | 0 +->time delta 1 |double| Parameter Δ1 used in time step reduction| 1/√2 +->time delta 2 |double| Parameter Δ2 used in time step enlargement| √2 +->break when stable | bool | Stops the iteration when the instationary problem is stable when set to true| false + + +### Filewriters + key | type | values | default value +------------------------------|--------|----------------------------------|------------- +->format | vector<string> | List of format strings from the following list1:
vtk (VTK format using the dune-grid writer),
dune-vtk (VTK format using the dune-vtk writer)2,
gmsh (GMsh file format),
backup (backup writer) | Not optional +->filename | string | Filename of the output file excluding the file extension| solution +->output directory | string | Directory where to put the files | . +->name | string | Name of the data vector in the output file| solution +->write every i-th timestep|int| Timestep number interval | 0 +->write after timestep|double| Time interval | 0.0 +->animation345|bool| write .pvd file if true | false +->mode3 | int | 0 (output in ASCII),
1 (output appended base64 binary) | 0 +->subsampling3|int| Number of refinement intervals for subsampling| No subsampling +->mode4 | int | 0 (ASCII),
1 (binary),
2 (compressed) | 0 +->precision45| int| 0 (float),
1 (double) | 0 +->animation6|bool | Append timestepnumber if true, otherwise always override | false + +1One filewriter will be set up for each format string in the list
+2Requires the dune-vtk module
+3Only for vtk format
+4Only for dune-vtk format
+5Only for gmsh format
+6Only for backup format
diff --git a/mkdocs.yml b/mkdocs.yml index 06def300..08d3f1b1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - DOFVector and DiscreteFunction: reference/DOFVector.md - GlobalBasis: reference/GlobalBasis.md - GridFunctions: reference/GridFunctions.md + - Initfile: reference/Initfile.md - Operators: reference/Operators.md - Problem: reference/Problem.md - MatrixBase and VectorBase: reference/MatVecBase.md -- GitLab From c0c400c0ed8451c01a81810f5ea54b508ffa6ed6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20M=C3=BCller?= Date: Tue, 29 Sep 2020 18:07:39 +0200 Subject: [PATCH 4/5] Fix broken links to src/amdis/... --- docs/reference/DOFVector.md | 8 ++++---- docs/reference/GridFunctions.md | 8 ++++---- docs/reference/MatVecBase.md | 8 ++++---- docs/reference/Operators.md | 18 +++++++++--------- docs/reference/Problem.md | 14 +++++++------- 5 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/reference/DOFVector.md b/docs/reference/DOFVector.md index 027bdda2..d213e118 100644 --- a/docs/reference/DOFVector.md +++ b/docs/reference/DOFVector.md @@ -23,7 +23,7 @@ The pair $\{(u_i),\{\phi_i\}\}$ is called DOFVector and the function \$u=u(\ ## class DOFVector -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/DOFVector.hpp) c++ template ](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/DOFVector.hpp) c++ template ](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/DiscreteFunction.hpp) c++ template ](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/DiscreteFunction.hpp) c++ // (1) diff --git a/docs/reference/GridFunctions.md b/docs/reference/GridFunctions.md index fc33b438..4dc85fcc 100644 --- a/docs/reference/GridFunctions.md +++ b/docs/reference/GridFunctions.md @@ -152,7 +152,7 @@ auto value = integrate(Expression, prob.gridView()); ## function evalAtQP() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/AnalyticGridFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/AnalyticGridFunction.hpp) c++ template @@ -172,7 +172,7 @@ Creates a GridFunction that evaluates a functor in global coordinates. ## function X() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/CoordsGridFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/CoordsGridFunction.hpp) c++ inline auto X(); // (1) @@ -190,7 +190,7 @@ global coordinates (2). ## function gradientAtQP() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DerivativeGridFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/DerivativeGridFunction.hpp) c++ template @@ -218,7 +218,7 @@ gradientAtQP(X(0) + X(1) + prob.solution(_0)) ## function invokeAtQP() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/FunctorGridFunction.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/FunctorGridFunction.hpp) c++ template diff --git a/docs/reference/MatVecBase.md b/docs/reference/MatVecBase.md index 43d1b5c5..64e29fba 100644 --- a/docs/reference/MatVecBase.md +++ b/docs/reference/MatVecBase.md @@ -13,7 +13,7 @@ class for all matrices associated to the indices of a row and column global basi ## class MatrixBase -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/linearalgebra/MatrixBase.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/MatrixBase.hpp) c++ template ](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/linearalgebra/VectorBase.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/VectorBase.hpp) c++ template VectorBase(GB&& basis) // (2)  -(1) Constructor that stores the shared_ptr of the global basis. (2) Constructor that forwards to (1) by wrapping reference +(1) Constructor that stores the shared_ptr of the global basis. (2) Constructor that forwards to (1) by wrapping reference into (non-destroying) shared_ptr. #### Arguments @@ -311,4 +311,4 @@ to switch insertion mode before calling [finish()](#function-vectorbasefinish). - **expects:** mask must be forward iterable for at least nodeVec.size() elements ### Postconditions -- **ensures:** Vector is in insertion mode defined by the assign functor. \ No newline at end of file +- **ensures:** Vector is in insertion mode defined by the assign functor. diff --git a/docs/reference/Operators.md b/docs/reference/Operators.md index 3c977d6f..37f56392 100644 --- a/docs/reference/Operators.md +++ b/docs/reference/Operators.md @@ -11,7 +11,7 @@ ## function makeOperator() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/GridFunctionOperator.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/GridFunctionOperator.hpp) c++ template @@ -146,7 +146,7 @@ auto op3 = makeOperator(B, sin(X(0)), Dune::QuadratureRules(Dune::GeometryType:: ## function zot() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/ZeroOrderTestTrial.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/ZeroOrderTestTrial.hpp) c++ template @@ -161,10 +161,10 @@ the same as for makeOperator(). ## function fot() Defined in headers -- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/FirstOrderGradTestTrial.hpp) -- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/FirstOrderTestGradTrial.hpp) -- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/FirstOrderPartialTestTrial.hpp) -- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/FirstOrderTestPartialTrial.hpp) +- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/FirstOrderGradTestTrial.hpp) +- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/FirstOrderTestGradTrial.hpp) +- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/FirstOrderPartialTestTrial.hpp) +- [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/FirstOrderTestPartialTrial.hpp) c++ template @@ -190,7 +190,7 @@ and whether it is a full gradient or just the partial derivative. ## function sot() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/SecondOrderGradTestGradTrial.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/SecondOrderGradTestGradTrial.hpp) c++ template @@ -203,7 +203,7 @@ as for makeOperator(). ## function sot_ij() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/SecondOrderPartialTestPartialTrial.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/SecondOrderPartialTestPartialTrial.hpp) c++ template @@ -217,7 +217,7 @@ Creates a second-order term of partial derivatives. This is a shortcut for ## function convectionDiffusion() -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/localoperators/ConvectionDiffusionOperator.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/localoperators/ConvectionDiffusionOperator.hpp) c++ template diff --git a/docs/reference/Problem.md b/docs/reference/Problem.md index d7840432..ab11f6ff 100644 --- a/docs/reference/Problem.md +++ b/docs/reference/Problem.md @@ -36,7 +36,7 @@ These two classes build the basis for most AMDiS projects. ## class ProblemStat -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemStat.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemStat.hpp) c++ template @@ -368,7 +368,7 @@ prob.addDirichletBC(BoundaryType{1}, 0, 0, 0.0);  ## class ProblemInstat -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemInstat.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemInstat.hpp) c++ template @@ -393,7 +393,7 @@ Standard implementation of [ProblemTimeInterface](#class-problemtimeinterface) f ## class StandardProblemIteration -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/StandardProblemIteration.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/StandardProblemIteration.hpp) c++ class StandardProblemIteration @@ -416,7 +416,7 @@ A master problem for a single non-coupled problem. ## class ProblemStatBase -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemStatBase.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemStatBase.hpp) c++ class ProblemStatBase @@ -440,7 +440,7 @@ Base class for [ProblemStat](#class-problemstat). ## class ProblemInstatBase -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemInstatBase.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemInstatBase.hpp) c++ class ProblemInstatBase @@ -463,7 +463,7 @@ Base class for [ProblemInstat](#class-probleminstat). ## class ProblemIterationInterface -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemIterationInterface.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemIterationInterface.hpp) c++ class ProblemIterationInterface @@ -487,7 +487,7 @@ estimate, and adapt steps of the single problems in oneIteration(). ## class ProblemTimeInterface -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/ProblemTimeInterface.hpp) +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/ProblemTimeInterface.hpp) c++ class ProblemTimeInterface -- GitLab From 00898fc535b6e08cf1053e958d497aca8edf3b6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20M=C3=BCller?= Date: Wed, 30 Sep 2020 15:47:28 +0200 Subject: [PATCH 5/5] Update old ref pages --- amdis/linearalgebra/MatrixFacade.hpp | 1 - docs/reference/DOFVector.md | 56 ++++--- .../{MatVecBase.md => MatVecFacade.md} | 148 +++++++----------- mkdocs.yml | 2 +- 4 files changed, 93 insertions(+), 114 deletions(-) rename docs/reference/{MatVecBase.md => MatVecFacade.md} (55%) diff --git a/amdis/linearalgebra/MatrixFacade.hpp b/amdis/linearalgebra/MatrixFacade.hpp index d9bfe3ec..3fbbadef 100644 --- a/amdis/linearalgebra/MatrixFacade.hpp +++ b/amdis/linearalgebra/MatrixFacade.hpp @@ -18,7 +18,6 @@ namespace AMDiS * to a row and column global basis. * * \tparam T The coefficient type of the matrix - * \tparam Pattern The type of the sparsity pattern * \tparam MatrixImpl A linear-algebra backend for the matrix storage **/ template class MatrixImpl> diff --git a/docs/reference/DOFVector.md b/docs/reference/DOFVector.md index d213e118..23a40917 100644 --- a/docs/reference/DOFVector.md +++ b/docs/reference/DOFVector.md @@ -28,7 +28,7 @@ Defined in header [](https://gitlab.mn.tu-dresden.de/amdi c++ template > + class Traits = BackendTraits> class DOFVector : public VectorFacade  @@ -68,37 +68,41 @@ The value_type is often the same as T, but might be just something similar, [interpolate_noalias](#function-dofvectorinterpolate) | Interpolation of GridFunction to DOFVector assuming no aliasing [operator<<](#function-dofvectorinterpolate) | Operator for the interpolation -??? seealso "Functions inherited from [VectorFacade](../MatVecBase/#class-vectorfacade)" +??? seealso "Functions inherited from [VectorFacade](../MatVecFacade/#class-vectorfacade)" Function | Descriptions --------------------------------|--------------------------------------------- - [basis](../MatVecBase#function-vectorbasebasis) | Return the GlobalBasis associated with the vector - [backend](../MatVecBase#function-vectorbasebackend) | Return the backend vector wrapper implementing the actual algebra - [localSize,globalSize](../MatVecBase#function-vectorbasesize) | The number of entries in the local part of the vector - [resize,resizeZero](../MatVecBase#function-vectorbaseglobalSize)| Resize the vector to the size of the basis - [init](../MatVecBase#function-vectorbaseglobalSize) | Prepare the vector for insertion of values - [finish](../MatVecBase#function-vectorbaseglobalSize) | Finish the insertion of values - [at](../MatVecBase#function-vectorbaseat) | Return the value of the vector at the given local index - [insert,set,add](../MatVecBase#function-vectorbaseinsert) | Insert a single value into the matrix - [gather](../MatVecBase#function-vectorbasegather) | Extract values from the vector referring to the given local indices - [scatter](../MatVecBase#function-vectorbasescatter) | Insert a block of values into the vector - [copy](../MatVecBase#function-vectorbasescatter) | Copies a block of values into the vector - [forEach](../MatVecBase#function-vectorbasescatter) | Apply a functor to each value at given indices + [impl](../MatVecFacade#function-vectorbasebackend) | Return the backend vector wrapper implementing the actual algebra + [localSize,globalSize](../MatVecFacade#function-vectorbasesize) | The number of entries in the local part of the vector + [resize,resizeZero](../MatVecFacade#function-vectorbaseglobalSize)| Resize the vector to the size of the basis + [init](../MatVecFacade#function-vectorbaseglobalSize) | Prepare the vector for insertion of values + [finish](../MatVecFacade#function-vectorbaseglobalSize) | Finish the insertion of values + [at](../MatVecFacade#function-vectorbaseat) | Return the value of the vector at the given local index + [insert,set,add](../MatVecFacade#function-vectorbaseinsert) | Insert a single value into the matrix + [gather](../MatVecFacade#function-vectorbasegather) | Extract values from the vector referring to the given local indices + [scatter](../MatVecFacade#function-vectorbasescatter) | Insert a block of values into the vector + [forEach](../MatVecFacade#function-vectorbasescatter) | Apply a functor to each value at given indices ## function DOFVector::DOFVector c++ template DOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE) + +template +DOFVector(GV const& gridView, PBF const& preBasisFactory, 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. +Constructs the DOFVector from a given global basis or a grid view and a basis factory, 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. +: Either a shared_ptr to the GlobalBasis type or anything that can be converted to that, e.g. a reference or a unique_ptr. References to lvalues are wrapped into non-destroying shared_ptrs whereas rvalue-references are moved into new basis objects. + +GV gridView +: A grid view provided by the grid + +PBF preBasisFactory +: A factory to create a pre-basis, see [the ref page on GlobalBasis](../GlobalBasis#making-a-prebasis) DataTransferOperation op : The operation performed during data-transfer, either DataTransferOperation::INTERPOLATE or DataTransferOperation::NO_OPERATION @@ -316,10 +320,10 @@ A DiscreteFunction is the interpretation of a DOFVector as grid function. ## function DiscreteFunction::DiscreteFunction c++ // (1) -DiscreteFunction(DOFVector const& dofVector, +DiscreteFunction(DOFVector const& dofVector, GlobalBasis const& basis, TreePath const& treePath = {}) // (2) -DiscreteFunction(DOFVector& dofVector, +DiscreteFunction(DOFVector& dofVector, GlobalBasis const& basis, TreePath const& treePath = {})  @@ -331,6 +335,9 @@ only available for the const or mutable is_const template parameter specializa : The container storing the global coefficients. Is stored as pointer in the DiscreteFunction and thus must have a longer lifetime than the DiscreteFunction. +GlobalBasis const& basis +: The global basis associated with the dofvector. + 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. @@ -421,7 +428,7 @@ DiscreteFunction& operator+=(Expr&& expr) // (5) template -DiscreteFunction& operator+=(Expr&& expr) +DiscreteFunction& operator-=(Expr&& expr)  (1) Interpolation of a GridFunction (or Expression) to the subtree of the DOFVector, assuming that there is no @@ -474,11 +481,13 @@ Defined in header [](https://gitlab. template > auto makeDiscreteFunction(DOFVector const& dofVector, + GlobalBasis const& basis, PreTreePath const& preTreePath = {}) // (2) template > auto makeDiscreteFunction(DOFVector& dofVector, + GlobalBasis const& basis, PreTreePath const& preTreePath = {})  @@ -491,6 +500,9 @@ can be constructed from. : The container storing the global coefficients. Is stored as pointer in the DiscreteFunction and thus must have a longer lifetime than the DiscreteFunction. +GlobalBasis const& basis +: The global basis associated to dofVector. + PreTreePath preTreePath : A pree-tree path, a Dune::TypeTree::HybridTreePath<...> can be created from. diff --git a/docs/reference/MatVecBase.md b/docs/reference/MatVecFacade.md similarity index 55% rename from docs/reference/MatVecBase.md rename to docs/reference/MatVecFacade.md index 64e29fba..619953d6 100644 --- a/docs/reference/MatVecBase.md +++ b/docs/reference/MatVecFacade.md @@ -1,135 +1,103 @@ -# MatrixBase and VectorBase {: #group-matvecbase } +# MatrixFacade and VectorFacade {: #group-matvecbase } ## Summary -The class [VectorBase](#class-vectorbase) is a base class and interface class for all vectors associated to the -indices of a global basis and, correspondingly, the class [MatrixBase](#class-matrixbase) is a base class and interface +The class [VectorFacade](#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](#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 -----------------------------------|--------------------------------------------- -[MatrixBase](#class-matrixbase) | Base class for vectors -[VectorBase](#class-vectorbase) | Base class for Matrices + Class | Descriptions +--------------------------------------|----------------------------------------- +[MatrixFacade](#class-matrixfacade) | Base class for matrices +[VectorFacade](#class-vectorfacade) | Base class for vectors -## class MatrixBase -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/MatrixBase.hpp) +## class MatrixFacade +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/MatrixFacade.hpp) c++ -template -class MatrixBase +template class MatrixImpl> +class MatrixFacade  -MatrixBase is an interface class for matrices storing additionally pointers to the row and column basis, RowBasis and ColBasis, respectively. +MatrixFacade is an interface class for matrices storing the implementation and rediricting to its interface functions. -The template parameter Backend refers to the actual implementation of the matrix data-structure. +The template parameter T defines the coefficient type of the matrix, MatrixImpl refers to the actual implementation of the matrix data-structure. ### Member Types - Member Type | Definition ---------------------------------|--------------------------------------------- -RowBasis | The type of the finite element space / basis of the row -RowLocalView | typename RowBasis::LocalView -ColBasis | The type of the finite element space / basis of the column -ColLocalView | typename ColBasis::LocalView -Backend | The Linear-Algebra backend used to store the assembled coefficients + Member Type | Definition +--------------|--------------------------------------------------------------- +Impl | The Linear-Algebra implementation used to store the assembled coefficients -## class VectorBase -Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/VectorBase.hpp) +## class VectorFacade +Defined in header [](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/linearalgebra/VectorFacade.hpp) c++ -template -class VectorBase +template class VectorImpl> +class VectorFacade  -VectorBase is an interface class for vectors storing an additional pointer to the global basis, Basis. +VectorFacade is an interface class for vectors storing the implementation and rediricting to its interface functions. -The template parameter Backend refers to the actual implementation of the vector data-structure. +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 ---------------------------------|--------------------------------------------- -GlobalBasis | The type of the functionspace basis -LocalView | typename GlobalBasis::LocalView -Backend | The Linear-Algebra backend used to store the assembled coefficients + Member Type | Definition +-------------|---------------------------------------------------------------- +Impl | The Linear-Algebra implementation used to store the assembled coefficients ### Member functions Function | Descriptions --------------------------------|--------------------------------------------- -[*(constructor)*](#function-vectorbasevectorbase) | Construct the VectorBase -[basis](#function-vectorbasebasis) | Return the GlobalBasis associated with the vector -[backend](#function-vectorbasebackend) | Return the backend vector wrapper implementing the actual algebra +[*(constructor)*](#function-vectorfacadevectorfacade) | Construct the VectorFacade +[impl](#function-vectorfacadeimpl) | Return the vector implementation **Capacity** Function | Descriptions --------------------------------|--------------------------------------------- -[localSize,globalSize](#function-vectorbasesize) | The number of entries in the local/global part of the vector -[resize,resizeZero](#function-vectorbaseresize) | Resize the vector to the size of the basis -[init](#function-vectorbaseinit) | Prepare the vector for insertion of values -[finish](#function-vectorbasefinish) | Finish the insertion of values +[localSize,globalSize](#function-vectorfacadesize) | The number of entries in the local/global part of the vector +[resize,resizeZero](#function-vectorfacaderesize) | Resize the vector to the size of the basis +[init](#function-vectorfacadeinit) | Prepare the vector for insertion of values +[finish](#function-vectorfacadefinish) | Finish the insertion of values **Element access** Function | Descriptions --------------------------------|--------------------------------------------- -[at](#function-vectorbaseat) | Return the value of the vector at the given local index -[gather](#function-vectorbasegather) | Extract values from the vector referring to the given local indices +[at](#function-vectorfacadeat) | Return the value of the vector at the given local index +[gather](#function-vectorfacadegather) | Extract values from the vector referring to the given local indices **Modifiers** Function | Descriptions --------------------------------|--------------------------------------------- -[insert,set,add](#function-vectorbaseinsert) | Insert a single value into the matrix (add or overwrite to existing value) -[scatter](#function-vectorbasescatter) | Insert a block of values into the vector -[copy](#function-vectorbasescatter) | Copies a block of values into the vector -[forEach](#function-vectorbasescatter) | Apply a functor to each value at given indices +[insert,set,add](#function-vectorfacadeinsert) | Insert a single value into the matrix (add or overwrite to existing value) +[scatter](#function-vectorfacadescatter) | Insert a block of values into the vector +[forEach](#function-vectorfacadescatter) | Apply a functor to each value at given indices -## function VectorBase::VectorBase +## function VectorFacade::VectorFacade c++ -VectorBase(std::shared_ptr basis) // (1) - -template -VectorBase(GB&& basis) // (2) +VectorFacade(GlobalBasis const& basis)  -(1) Constructor that stores the shared_ptr of the global basis. (2) Constructor that forwards to (1) by wrapping reference -into (non-destroying) shared_ptr. - -#### Arguments -GB basis -: Reference (lvalue or rvalue) to a global basis. GB must be Concepts::Similar to the type GlobalBasis. If basis is a lvalue-reference, - it is wrapped into a non-destroying shared_ptr, if it is a rvalue-reference, it is moved into a new Object, created as shared_ptr. - See Dune::wrap_or_move. - -#### Requirements -- GB must be similar to GlobalBasis, i.e., the same type up to const and reference qualifiers. - - -## function VectorBase::basis -c++ -std::shared_ptr const& basis() const // (1) -std::shared_ptr const& basis() // (2) - -Return the basis associated to the vector +Constructor that passes the global basis to the implementation. -## function VectorBase::backend +## function VectorFacade::impl c++ -Backend const& backend() const // (1) -Backend& backend() // (2) +Impl const& impl() const // (1) +Impl& impl() // (2)  -Return the underlying linear algebra backend +Return the underlying linear algebra implementation -## function VectorBase::localSize,globalSize {: #function-vectorbasesize } +## function VectorFacade::localSize,globalSize {: #function-vectorfacadesize } c++ std::size_t localSize() const // (1) std::size_t globalSize() const // (2) @@ -137,7 +105,7 @@ 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 VectorBase::resize,resizeZero {: #function-vectorbaseresize } +## function VectorFacade::resize,resizeZero {: #function-vectorfacaderesize } c++ std::size_t resize() const // (1) std::size_t resizeZero() const // (2) @@ -145,25 +113,25 @@ std::size_t resizeZero() const // (2) Resize the vector to the size of the basis (1) and in case of (2) also set all entries to zero. -## function VectorBase::init +## function VectorFacade::init c++ void init(bool clear)  -Prepare the vector for insertion of values, finish the insertion with a call to [finish()](#function-vectorbasefinish). +Prepare the vector for insertion of values, finish the insertion with a call to [finish()](#function-vectorfacadefinish). #### Arguments bool clear : If true, sets the vector to zero before insertion -## function VectorBase::finish +## function VectorFacade::finish c++ void finish()  -Finish the insertion of values. Must be called at the end of the insertion. See also [init()](#function-vectorbaseinit). +Finish the insertion of values. Must be called at the end of the insertion. See also [init()](#function-vectorfacadeinit). -## function VectorBase::at {: #function-vectorbaseat } +## function VectorFacade::at {: #function-vectorfacadeat } c++ template typename Backend::value_type at(Index const& dof) const @@ -173,14 +141,14 @@ might be necessary. This is a collective communication operation. This communica unsynchronized state. !!! note - Prefer a block operation to retrieve data, like [gather()](#function-vectorbasegather). + Prefer a block operation to retrieve data, like [gather()](#function-vectorfacadegather). #### Arguments Index dof : Any (Multi-)index type. Currently only flat multiindices are supported. This will be relaxed in future versions of the library. -## function VectorBase::gather +## function VectorFacade::gather c++ // (1) template @@ -196,7 +164,7 @@ indices are defined by (1) the nodeIndices(localView, node) or (2) the 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()](#function-vectorbasefinish) before. +state. This must be closed using [finish()](#function-vectorfacadefinish) before. #### Arguments LocalView localView @@ -216,7 +184,7 @@ state. This must be closed using [finish()](#function-vectorbasefinish) before. - **expects:** node is in localView.tree() -## function VectorBase::insert,set,add {: #function-vectorbaseinsert } +## function VectorFacade::insert,set,add {: #function-vectorfacadeinsert } c++ // (1) template @@ -236,12 +204,12 @@ 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()](#function-vectorbasefinish). +Insertion must be closed with a call to [finish()](#function-vectorfacadefinish). (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()](#function-vectorbasescatter). + Prefer a block operation to insert data, like [scatter()](#function-vectorfacadescatter). #### Arguments Index dof @@ -254,7 +222,7 @@ Insertion must be closed with a call to [finish()](#function-vectorbasefinish). : An assignment functor with the signature void operator()(T const& from, S&& to) const -## function VectorBase::scatter +## function VectorFacade::scatter c++ // (1) template @@ -281,7 +249,7 @@ 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 \ref finish(). It is not allowed -to switch insertion mode before calling [finish()](#function-vectorbasefinish). +to switch insertion mode before calling [finish()](#function-vectorfacadefinish). (2) Same as (1) but all indices are inserted. diff --git a/mkdocs.yml b/mkdocs.yml index 08d3f1b1..2b4dceba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,7 +22,7 @@ nav: - Initfile: reference/Initfile.md - Operators: reference/Operators.md - Problem: reference/Problem.md - - MatrixBase and VectorBase: reference/MatVecBase.md + - MatrixFacade and VectorFacade: reference/MatVecFacade.md - API Documentation: - Modules: api/modules.html - Namespaces: api/namespaces.html -- GitLab