From 8a719103983b64270bdb2f09cbd63be05325f443 Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Wed, 20 Dec 2017 13:48:41 +0100
Subject: [PATCH] [doc] Improve documentation of nonlinear folder
---
doc/doxygen/modules.txt | 2 +-
dumux/nonlinear/newtoncontroller.hh | 37 +++++++++++---------
dumux/nonlinear/newtonconvergencewriter.hh | 15 +++++---
dumux/nonlinear/newtonmethod.hh | 7 ++--
dumux/nonlinear/staggerednewtoncontroller.hh | 19 +++++-----
5 files changed, 45 insertions(+), 35 deletions(-)
diff --git a/doc/doxygen/modules.txt b/doc/doxygen/modules.txt
index b31c16d814..1f3f21bb43 100644
--- a/doc/doxygen/modules.txt
+++ b/doc/doxygen/modules.txt
@@ -422,7 +422,7 @@
/* ***************** Nonlinear ******************/
/*!
* \defgroup Nonlinear Nonlinear
- * TODO: Doc me in modules.txt!
+ * \brief Nonlinear solvers: Newton method
*/
/* ***************** Parallel ******************/
diff --git a/dumux/nonlinear/newtoncontroller.hh b/dumux/nonlinear/newtoncontroller.hh
index 2388cfc06f..39ff8a2ebb 100644
--- a/dumux/nonlinear/newtoncontroller.hh
+++ b/dumux/nonlinear/newtoncontroller.hh
@@ -18,6 +18,7 @@
*****************************************************************************/
/*!
* \file
+ * \ingroup Nonlinear
* \brief Reference implementation of a controller class for the Newton solver.
*
* Usually this controller should be sufficient.
@@ -34,16 +35,15 @@
#include <dumux/common/timeloop.hh>
#include <dumux/linear/seqsolverbackend.hh>
-namespace Dumux
-{
+namespace Dumux {
+
/*!
- * \ingroup Newton
- * \brief A reference implementation of a Newton controller specific
- * for the box scheme.
+ * \ingroup Nonlinear
+ * \brief An implementation of a Newton controller
*
- * If you want to specialize only some methods but are happy with the
- * defaults of the reference controller, derive your controller from
- * this class and simply overload the required methods.
+ * \note If you want to specialize only some methods but are happy with the
+ * defaults of the reference controller, derive your controller from
+ * this class and simply overload the required methods.
*/
template <class TypeTag>
class NewtonController
@@ -77,6 +77,7 @@ public:
initParams_();
}
+ //! the communicator for parallel runs
const Communicator& communicator() const
{ return comm_; }
@@ -134,6 +135,7 @@ public:
* \brief Returns true if another iteration should be done.
*
* \param uCurrentIter The solution of the current Newton iteration
+ * \param converged if the Newton method's convergence criterion was met in this step
*/
template<class SolutionVector>
bool newtonProceed(const SolutionVector &uCurrentIter, bool converged)
@@ -257,6 +259,7 @@ public:
* \brief Assemble the linear system of equations \f$\mathbf{A}x - b = 0\f$.
*
* \param assembler The jacobian assembler
+ * \param uCurrentIter The current iteration's solution vector
*/
template<class JacobianAssembler, class SolutionVector>
void assembleLinearSystem(JacobianAssembler& assembler,
@@ -268,7 +271,7 @@ public:
/*!
* \brief Solve the linear system of equations \f$\mathbf{A}x - b = 0\f$.
*
- * Throws NumericalProblem if the linear solver didn't
+ * \throws Dumux::NumericalProblem if the linear solver didn't
* converge.
*
* \param ls The linear solver to be used
@@ -516,6 +519,7 @@ public:
protected:
+ //! initialize the parameters by reading from the parameter tree
void initParams_()
{
const std::string group = GET_PROP_VALUE(TypeTag, ModelParameterGroup);
@@ -597,15 +601,16 @@ protected:
return result;
}
- // The grid view's communicator
+ //! The grid view's communicator
const Communicator& comm_;
+ //! The time loop for stationary simulations
std::shared_ptr<TimeLoop<Scalar>> timeLoop_;
- // message stream to be displayed at the end of iterations
+ //! message stream to be displayed at the end of iterations
std::ostringstream endIterMsgStream_;
- // switches on/off verbosity
+ //! switches on/off verbosity
bool verbose_;
// shift criterion variables
@@ -621,11 +626,11 @@ protected:
Scalar reductionTolerance_;
Scalar residualTolerance_;
- // optimal number of iterations we want to achieve
+ //! optimal number of iterations we want to achieve
int targetSteps_;
- // maximum number of iterations we do before giving up
+ //! maximum number of iterations we do before giving up
int maxSteps_;
- // actual number of steps done so far
+ //! actual number of steps done so far
int numSteps_;
// further parameters
@@ -637,6 +642,6 @@ protected:
bool satisfyResidualAndShiftCriterion_;
};
-} // namespace Dumux
+} // end namespace Dumux
#endif
diff --git a/dumux/nonlinear/newtonconvergencewriter.hh b/dumux/nonlinear/newtonconvergencewriter.hh
index 42f349027a..ce38c55959 100644
--- a/dumux/nonlinear/newtonconvergencewriter.hh
+++ b/dumux/nonlinear/newtonconvergencewriter.hh
@@ -18,7 +18,7 @@
*****************************************************************************/
/*!
* \file
- *
+ * \ingroup Nonlinear
* \brief This class provides the infrastructure to write the
* convergence behaviour of the newton method into a VTK file.
*/
@@ -34,9 +34,8 @@ namespace Dumux
{
/*!
- * \ingroup Newton
- * \brief Writes the intermediate solutions during
- * the Newton scheme
+ * \ingroup Nonlinear
+ * \brief Writes the intermediate solutions for every Newton iteration
* \note To use this create a unique_ptr to an instance of this class in the main file
* and pass it to newton.solve(x, convergencewriter). You can use the reset method
* to write out multiple Newton solves with a unique id, if you don't call use all
@@ -46,6 +45,12 @@ template <class Scalar, class GridView, int numEq>
class NewtonConvergenceWriter
{
public:
+ /*!
+ * \brief Constructor
+ * \param gridView the grid view we are solving on
+ * \param size the size of the solution data
+ * \param name base name of the vtk output
+ */
NewtonConvergenceWriter(const GridView& gridView,
std::size_t size,
const std::string& name = "newton_convergence")
@@ -126,6 +131,6 @@ private:
std::array<std::vector<Scalar>, numEq> x_;
};
-} // namespace Dumux
+} // end namespace Dumux
#endif
diff --git a/dumux/nonlinear/newtonmethod.hh b/dumux/nonlinear/newtonmethod.hh
index 43e5402b18..d67bdfa69d 100644
--- a/dumux/nonlinear/newtonmethod.hh
+++ b/dumux/nonlinear/newtonmethod.hh
@@ -18,7 +18,7 @@
*****************************************************************************/
/*!
* \file
- *
+ * \ingroup Nonlinear
* \brief The algorithmic part of the multi dimensional newton method.
*
* In order to use the method you need a Newtoncontroller
@@ -40,9 +40,12 @@ namespace Dumux
/*!
* \ingroup Newton
+ * \ingroup Nonlinear
* \brief The algorithmic part of the multi dimensional newton method.
*
- * In order to use the method you need a Newtoncontroller
+ * \tparam NewtonController the controller class is the driver implementation
+ * \tparam JacobianAssembler an assembler for the Jacobian and the residual
+ * \tparam LinearSolver the linear solver used to solve one iteration
*/
template <class NewtonController, class JacobianAssembler, class LinearSolver>
class NewtonMethod
diff --git a/dumux/nonlinear/staggerednewtoncontroller.hh b/dumux/nonlinear/staggerednewtoncontroller.hh
index bf264a80f6..ca427733d8 100644
--- a/dumux/nonlinear/staggerednewtoncontroller.hh
+++ b/dumux/nonlinear/staggerednewtoncontroller.hh
@@ -18,11 +18,9 @@
*****************************************************************************/
/*!
* \file
- * \brief A StaggeredModel specific controller for the newton solver.
- *
- * This controller 'knows' what a 'physically meaningful' solution is
- * which allows the newton method to abort quicker if the solution is
- * way out of bounds.
+ * \ingroup Nonlinear
+ * \ingroup StaggeredDiscretization
+ * \brief A newton controller for staggered finite volume schemes
*/
#ifndef DUMUX_STAGGERED_NEWTON_CONTROLLER_HH
#define DUMUX_STAGGERED_NEWTON_CONTROLLER_HH
@@ -37,12 +35,9 @@
namespace Dumux {
/*!
- * \ingroup StaggeredModel
- * \brief A StaggeredModel specific controller for the newton solver.
- *
- * This controller 'knows' what a 'physically meaningful' solution is
- * which allows the newton method to abort quicker if the solution is
- * way out of bounds.
+ * \ingroup Nonlinear
+ * \ingroup StaggeredDiscretization
+ * \brief A newton controller for staggered finite volume schemes
*/
template <class TypeTag>
@@ -78,6 +73,7 @@ public:
* If the linear solver doesn't accept multitype matrices we copy the matrix
* into a 1x1 block BCRS matrix for solving.
*
+ * \param ls the linear solver
* \param A The matrix of the linear system of equations
* \param x The vector which solves the linear system
* \param b The right hand side of the linear system
@@ -141,6 +137,7 @@ public:
* subtract deltaU from uLastIter, i.e.
* \f[ u^{k+1} = u^k - \Delta u^k \f]
*
+ * \param assembler The assembler for Jacobian and residual
* \param uCurrentIter The solution vector after the current iteration
* \param uLastIter The solution vector after the last iteration
* \param deltaU The delta as calculated from solving the linear
--
GitLab