From b0c1729478b44f4e20b51f863d8e820235ce80b2 Mon Sep 17 00:00:00 2001
From: Kilian Weishaupt <kilian.weishaupt@iws.uni-stuttgart.de>
Date: Fri, 12 Jan 2018 11:19:19 +0100
Subject: [PATCH] [assembly] Improve docu
---
dumux/assembly/boxlocalassembler.hh | 28 +++++----
dumux/assembly/cclocalassembler.hh | 27 +++++----
dumux/assembly/fvassembler.hh | 19 ++++--
dumux/assembly/fvlocalassemblerbase.hh | 75 ++++++++++++++++++++----
dumux/assembly/numericdifferentiation.hh | 10 ++--
5 files changed, 114 insertions(+), 45 deletions(-)
diff --git a/dumux/assembly/boxlocalassembler.hh b/dumux/assembly/boxlocalassembler.hh
index 58d8e7cac0..abad1cb4cf 100644
--- a/dumux/assembly/boxlocalassembler.hh
+++ b/dumux/assembly/boxlocalassembler.hh
@@ -31,8 +31,7 @@
#include <dumux/common/properties.hh>
#include <dumux/common/parameters.hh>
#include <dumux/assembly/diffmethod.hh>
-
-#include "fvlocalassemblerbase.hh"
+#include <dumux/assembly/fvlocalassemblerbase.hh>
namespace Dumux {
@@ -40,9 +39,10 @@ namespace Dumux {
* \ingroup Assembly
* \ingroup BoxDiscretization
* \brief A base class for all local box assemblers
- * \tparam TypeTag the TypeTag
- * \tparam Assembler the assembler type
- * \tparam Assembler The acutal Implementation
+ * \tparam TypeTag The TypeTag
+ * \tparam Assembler The assembler type
+ * \tparam Implementation The actual implementation
+ * \tparam implicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, class Assembler, class Implementation, bool implicit>
class BoxLocalAssemblerBase : public FVLocalAssemblerBase<TypeTag, Assembler, Implementation, implicit>
@@ -107,17 +107,25 @@ public:
// TODO: Dirichlet required here?
}
-
+ /*!
+ * \brief Evaluates the flux and source terms (i.e, the terms without a time derivative) of the local residual
+ */
auto evalLocalFluxAndSourceResidual(const ElementVolumeVariables& elemVolVars) const
{
return this->evalLocalFluxAndSourceResidual(elemVolVars);
}
+ /*!
+ * \brief Evaluates the storage term (i.e, the term with a time derivative) of the local residual
+ */
auto evalLocalStorageResidual() const
{
return this->evalLocalStorageResidual();
}
+ /*!
+ * \brief Evaluates Dirichlet boundaries
+ */
void evalDirichletBoundaries(JacobianMatrix& jac, SolutionVector& res)
{
// enforce Dirichlet boundaries by overwriting partial derivatives with 1 or 0
@@ -159,10 +167,10 @@ public:
/*!
* \ingroup Assembly
* \ingroup BoxDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (box method)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \brief An assembler for Jacobian and residual contribution per element (box methods)
+ * \tparam TypeTag The TypeTag
+ * \tparam DM The differentiation method to residual compute derivatives
+ * \tparam implicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, class Assembler, DiffMethod DM = DiffMethod::numeric, bool implicit = true>
class BoxLocalAssembler;
diff --git a/dumux/assembly/cclocalassembler.hh b/dumux/assembly/cclocalassembler.hh
index 9899669da9..4724492c4f 100644
--- a/dumux/assembly/cclocalassembler.hh
+++ b/dumux/assembly/cclocalassembler.hh
@@ -21,9 +21,6 @@
* \ingroup Assembly
* \ingroup CCDiscretization
* \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
*/
#ifndef DUMUX_CC_LOCAL_ASSEMBLER_HH
#define DUMUX_CC_LOCAL_ASSEMBLER_HH
@@ -37,17 +34,18 @@
#include <dumux/common/parameters.hh>
#include <dumux/assembly/diffmethod.hh>
#include <dumux/assembly/numericdifferentiation.hh>
-
-#include "fvlocalassemblerbase.hh"
+#include <dumux/assembly/fvlocalassemblerbase.hh>
namespace Dumux {
/*!
* \ingroup Assembly
* \ingroup CCDiscretization
- * \brief A base class for all local assemblers
- * \tparam TypeTag the TypeTag
- * \tparam Assembler the assembler type
+ * \brief A base class for all local cell-centered assemblers
+ * \tparam TypeTag The TypeTag
+ * \tparam Assembler The assembler type
+ * \tparam Implementation The actual implementation
+ * \tparam implicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, class Assembler, class Implementation, bool implicit>
class CCLocalAssemblerBase : public FVLocalAssemblerBase<TypeTag, Assembler, Implementation, implicit>
@@ -95,12 +93,17 @@ public:
res[globalI] = this->asImp_().evalLocalResidual()[0]; // forward to the internal implementation
}
-
+ /*!
+ * \brief Evaluates the flux and source terms (i.e, the terms without a time derivative) of the local residual
+ */
LocalResidualValues evalLocalFluxAndSourceResidual(const ElementVolumeVariables& elemVolVars) const
{
return this->evalLocalFluxAndSourceResidual(elemVolVars)[0];
}
+ /*!
+ * \brief Evaluates the storage term (i.e, the term with a time derivative) of the local residual
+ */
LocalResidualValues evalLocalStorageResidual() const
{
return this->evalLocalStorageResidual()[0];
@@ -111,9 +114,9 @@ public:
* \ingroup Assembly
* \ingroup CCDiscretization
* \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \tparam TypeTag The TypeTag
+ * \tparam DM The differentiation method to residual compute derivatives
+ * \tparam implicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, class Assembler, DiffMethod DM = DiffMethod::numeric, bool implicit = true>
class CCLocalAssembler;
diff --git a/dumux/assembly/fvassembler.hh b/dumux/assembly/fvassembler.hh
index 7fd5adcc05..4310071b2a 100644
--- a/dumux/assembly/fvassembler.hh
+++ b/dumux/assembly/fvassembler.hh
@@ -42,9 +42,9 @@ namespace Dumux {
/*!
* \ingroup Assembly
* \brief A linear system assembler (residual and Jacobian) for finite volume schemes (box, tpfa, mpfa, ...)
- * \tparam TypeTag the TypeTag
- * \tparam diffMethod the differentiation method to residual compute derivatives
- * \tparam isImplicit if to use an implicit or explicit time discretization
+ * \tparam TypeTag The TypeTag
+ * \tparam diffMethod The differentiation method to residual compute derivatives
+ * \tparam isImplicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, DiffMethod diffMethod, bool isImplicit = true>
class FVAssembler
@@ -237,36 +237,43 @@ public:
occupationPattern.exportIdx(*jacobian_);
}
- /*!
- * \brief Resizes the residual
- */
+ //! Resizes the residual
void setResidualSize()
{ residual_->resize(numDofs()); }
+ //! Returns the number of degrees of freedom
std::size_t numDofs() const
{ return fvGridGeometry_->numDofs(); }
+ //! The problem
const Problem& problem() const
{ return *problem_; }
+ //! The global finite volume geometry
const FVGridGeometry& fvGridGeometry() const
{ return *fvGridGeometry_; }
+ //! The gridview
const GridView& gridView() const
{ return fvGridGeometry().gridView(); }
+ //! The global grid variables
GridVariables& gridVariables()
{ return *gridVariables_; }
+ //! The global grid variables
const GridVariables& gridVariables() const
{ return *gridVariables_; }
+ //! The jacobian matrix
JacobianMatrix& jacobian()
{ return *jacobian_; }
+ //! The residual vector (rhs)
SolutionVector& residual()
{ return *residual_; }
+ //! The solution of the previous time step
const SolutionVector& prevSol() const
{ return *prevSol_; }
diff --git a/dumux/assembly/fvlocalassemblerbase.hh b/dumux/assembly/fvlocalassemblerbase.hh
index b1db5754b7..89ac085d05 100644
--- a/dumux/assembly/fvlocalassemblerbase.hh
+++ b/dumux/assembly/fvlocalassemblerbase.hh
@@ -19,11 +19,7 @@
/*!
* \file
* \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \copydoc Dumux::FVLocalAssemblerBase
*/
#ifndef DUMUX_FV_LOCAL_ASSEMBLER_BASE_HH
#define DUMUX_FV_LOCAL_ASSEMBLER_BASE_HH
@@ -42,10 +38,10 @@ namespace Dumux {
/*!
* \ingroup Assembly
- * \ingroup CCDiscretization
* \brief A base class for all local assemblers
- * \tparam TypeTag the TypeTag
- * \tparam Assembler the assembler type
+ * \tparam TypeTag The TypeTag
+ * \tparam Assembler The assembler type
+ * \tparam implicit Specifies whether the time discretization is implicit or not not (i.e. explicit)
*/
template<class TypeTag, class Assembler, class Implementation, bool implicit>
class FVLocalAssemblerBase
@@ -69,6 +65,9 @@ class FVLocalAssemblerBase
public:
+ /*!
+ * \brief The constructor
+ */
explicit FVLocalAssemblerBase(const Assembler& assembler,
const Element& element,
const SolutionVector& curSol)
@@ -83,6 +82,10 @@ public:
, elementIsGhost_((element.partitionType() == Dune::GhostEntity))
{}
+ /*!
+ * \brief Convenience function to evaluate the complete local residual for the current element. Automatically chooses the the appropriate
+ * element volume variables.
+ */
auto evalLocalResidual() const
{
if(this->assembler().isStationaryProblem() && !isImplicit())
@@ -98,7 +101,10 @@ public:
: evalLocalResidual(prevElemVolVars());
}
-
+ /*!
+ * \brief Evaluates the complete local residual for the current element.
+ * \param elemVolVars The element volume variables
+ */
auto evalLocalResidual(const ElementVolumeVariables& elemVolVars) const
{
if (!assembler().isStationaryProblem())
@@ -111,28 +117,55 @@ public:
return evalLocalFluxAndSourceResidual(elemVolVars);
}
+ /*!
+ * \brief Convenience function to evaluate the flux and source terms (i.e, the terms without a time derivative)
+ * of the local residual for the current element. Automatically chooses the the appropriate
+ * element volume variables.
+ */
auto evalLocalFluxAndSourceResidual() const
{
return isImplicit() ? evalLocalFluxAndSourceResidual(curElemVolVars())
: evalLocalFluxAndSourceResidual(prevElemVolVars());
}
+ /*!
+ * \brief Evaluates the flux and source terms (i.e, the terms without a time derivative)
+ * of the local residual for the current element.
+ *
+ * \param elemVolVars The element volume variables
+ */
auto evalLocalFluxAndSourceResidual(const ElementVolumeVariables& elemVolVars) const
{
return localResidual_.evalFluxSource(element_, fvGeometry_, elemVolVars, elemFluxVarsCache_, elemBcTypes_);
}
+ /*!
+ * \brief Convenience function to evaluate storage term (i.e, the term with a time derivative)
+ * of the local residual for the current element. Automatically chooses the the appropriate
+ * element volume variables.
+ */
auto evalLocalStorageResidual() const
{
return localResidual_.evalStorage(element_, fvGeometry_, prevElemVolVars_, curElemVolVars_);
}
- auto evalFluxResidual(const Element& neigbor,
- const SubControlVolumeFace& scvf) const
+ /*!
+ * \brief Evaluates the flux terms of the local residual for the neighboring element.
+ *
+ * \param neighbor The neighboring element
+ * \param scvf The sub control volume face
+ */
+ //TODO: put to CC ?
+ auto evalFluxResidual(const Element& neighbor,
+ const SubControlVolumeFace& scvf) const
{
- return localResidual_.evalFlux(problem(), neigbor, fvGeometry_, curElemVolVars_, elemFluxVarsCache_, scvf);
+ return localResidual_.evalFlux(problem(), neighbor, fvGeometry_, curElemVolVars_, elemFluxVarsCache_, scvf);
}
+ /*!
+ * \brief Convenience function bind and prepare all relevant variables required for the
+ * evaluation of the local residual.
+ */
void bindLocalViews()
{
// get some references for convenience
@@ -162,57 +195,75 @@ public:
}
}
+ //! The problem
const Problem& problem() const
{ return assembler_.problem(); }
+ //! The assembler
const Assembler& assembler() const
{ return assembler_; }
+ //! The current element
const Element& element() const
{ return element_; }
+ //! Returns if element is a ghost entity
bool elementIsGhost() const
{ return elementIsGhost_; }
+ //! The current solution
const SolutionVector& curSol() const
{ return curSol_; }
+ //! The global finite volume geometry
FVElementGeometry& fvGeometry()
{ return fvGeometry_; }
+ //! The current element volume variables
ElementVolumeVariables& curElemVolVars()
{ return curElemVolVars_; }
+ //! The element volume variables of the provious time step
ElementVolumeVariables& prevElemVolVars()
{ return prevElemVolVars_; }
+ //! The element flux variables cache
ElementFluxVariablesCache& elemFluxVarsCache()
{ return elemFluxVarsCache_; }
+ //! The local residual for the current element
LocalResidual& localResidual()
{ return localResidual_; }
+ //! The element's boundary types TODO: only for box?
ElementBoundaryTypes& elemBcTypes()
{ return elemBcTypes_; }
+ //! The finite volume geometry
const FVElementGeometry& fvGeometry() const
{ return fvGeometry_; }
+ //! The current element volume variables
const ElementVolumeVariables& curElemVolVars() const
{ return curElemVolVars_; }
+ //! The element volume variables of the provious time step
const ElementVolumeVariables& prevElemVolVars() const
{ return prevElemVolVars_; }
+ //! The element flux variables cache
const ElementFluxVariablesCache& elemFluxVarsCache() const
{ return elemFluxVarsCache_; }
+ //! The element's boundary types TODO: only for box?
const ElementBoundaryTypes& elemBcTypes() const
{ return elemBcTypes_; }
+ //! The local residual for the current element
const LocalResidual& localResidual() const
{ return localResidual_; }
+ // TODO: should this really be public?
template<class T = TypeTag, typename std::enable_if_t<!GET_PROP_VALUE(T, EnableGridVolumeVariablesCache), int> = 0>
VolumeVariables& getVolVarAccess(GridVolumeVariables& gridVolVars, ElementVolumeVariables& elemVolVars, const SubControlVolume& scv)
{ return elemVolVars[scv]; }
diff --git a/dumux/assembly/numericdifferentiation.hh b/dumux/assembly/numericdifferentiation.hh
index a6a5fdc491..cdf0ee3f1b 100644
--- a/dumux/assembly/numericdifferentiation.hh
+++ b/dumux/assembly/numericdifferentiation.hh
@@ -66,11 +66,11 @@ public:
/*!
* \brief Computes the derivative of a function with repect to a function parameter
- * \param function the function to derive
- * \param x0 the parameter at which the derivative is ought to be evaluated
- * \param partialDerivative the partial derivative (output)
- * \param fx0 the result of the function evaluated at x0
- * \param eps the numeric epsilon used in the differentiation
+ * \param function The function to derive
+ * \param x0 The parameter at which the derivative is ought to be evaluated
+ * \param derivative The partial derivative (output)
+ * \param fx0 The result of the function evaluated at x0
+ * \param eps The numeric epsilon used in the differentiation
*/
template<class Function, class Scalar, class FunctionEvalType>
static void partialDerivative(const Function& function, Scalar x0,
--
GitLab