Skip to content
GitLab
Commit 37503b44 authored by Timo Koch's avatar Timo Koch
Browse files

[doc] Improve documentation in folder linear

parent 80646fe2
Hide whitespace changes
Inline Side-by-side
doc/doxygen/modules.txt
View file @ 37503b44
......@@ -416,7 +416,7 @@
/* ***************** Linear ******************/
/*!
* \defgroup Linear Linear
* TODO: Doc me in modules.txt!
* \brief Linear solvers and helpers
*/
/* ***************** Nonlinear ******************/
......
dumux/linear/amgbackend.hh
View file @ 37503b44
......@@ -19,8 +19,8 @@
/*!
* \file
* \ingroup Linear
*
* \brief Provides a linear solver based on the ISTL AMG.
* \brief Provides a linear solver based on the ISTL AMG preconditioner
* and the ISTL BiCGSTAB solver.
*/
#ifndef DUMUX_AMGBACKEND_HH
#define DUMUX_AMGBACKEND_HH
......@@ -39,6 +39,7 @@
namespace Dumux {
/*!
* \ingroup Linear
* \brief Scale the linear system by the inverse of
* its (block-)diagonal entries.
*
......@@ -69,7 +70,9 @@ void scaleLinearSystem(Matrix& matrix, Vector& rhs)
}
/*!
* \brief Provides a linear solver using the ISTL AMG.
* \ingroup Linear
* \brief A linear solver based on the ISTL AMG preconditioner
* and the ISTL BiCGSTAB solver.
*/
template <class TypeTag>
class AMGBackend : public LinearSolver<TypeTag>
......@@ -90,7 +93,8 @@ public:
/*!
* \brief Construct the backend.
*
* \param problem the problem at hand
* \param gridView the grid view on which we are performing the multi-grid
* \param dofMapper an index mapper for dof entities
*/
AMGBackend(const GridView& gridView, const DofMapper& dofMapper)
: gridView_(gridView)
......@@ -121,6 +125,7 @@ public:
using Criterion = Dune::Amg::CoarsenCriterion<Dune::Amg::SymmetricCriterion<BCRSMat, Dune::Amg::FirstDiagonal>>;
//! \todo Check whether the default accumulation mode atOnceAccu is needed.
//! \todo make parameters changeable at runtime from input file / parameter tree
Dune::Amg::Parameters params(15,2000,1.2,1.6,Dune::Amg::atOnceAccu);
params.setDefaultValuesIsotropic(Grid::dimension);
params.setDebugLevel(this->verbosity());
......@@ -138,6 +143,9 @@ public:
return result_.converged;
}
/*!
* \brief The name of the solver
*/
std::string name() const
{
return "AMG preconditioned BiCGSTAB solver";
......@@ -166,6 +174,8 @@ private:
* The function is called from the solve function. The call is
* forwarded to the corresponding function of a class template.
*
* \tparam Matrix the matrix type
* \tparam Vector the vector type
* \tparam isParallel decides if the setting is parallel or sequential
*/
template<class Matrix, class Vector, bool isParallel>
......
dumux/linear/amgparallelhelpers.hh
View file @ 37503b44
......@@ -18,7 +18,7 @@
*****************************************************************************/
/*!
* \file
*
* \ingroup Linear
* \brief Provides a helper class for nonoverlapping
* decomposition using the ISTL AMG.
*/
......@@ -32,10 +32,10 @@
#include <dumux/common/properties.hh>
#include <dumux/linear/amgtraits.hh>
namespace Dumux
{
namespace Dumux {
/*!
* \ingroup Linear
* \brief A parallel helper class providing a nonoverlapping
* decomposition of all degrees of freedom
*/
......@@ -63,8 +63,8 @@ class ParallelISTLHelper
const DofMapper& mapper_;
};
/**
* @brief GatherScatter implementation that makes a right hand side in the box model consistent.
/*!
* \brief GatherScatter implementation that makes a right hand side in the box model consistent.
*/
template<class V>
class ConsistencyBoxGatherScatter
......@@ -113,7 +113,7 @@ class ParallelISTLHelper
/**
* @brief Writes 1<<24 to each data item (of the container) that is gathered or scattered
* \brief Writes 1<<24 to each data item (of the container) that is gathered or scattered
* and is neither interior nor border.
*
* Can be used to mark ghost cells.
......@@ -169,7 +169,7 @@ class ParallelISTLHelper
};
/**
* @brief GatherScatter handle that sets 1<<24 for data items neither associated to
* \brief GatherScatter handle that sets 1<<24 for data items neither associated to
* the interior or border and take the minimum when scattering.
*
* Used to compute an owner rank for each unknown.
......@@ -230,7 +230,7 @@ class ParallelISTLHelper
};
/**
* @brief GatherScatter handle for finding out about neighbouring processor ranks.
* \brief GatherScatter handle for finding out about neighbouring processor ranks.
*
*/
struct NeighbourGatherScatter
......@@ -279,7 +279,7 @@ class ParallelISTLHelper
/**
* @brief GatherScatter handle for finding out about neighbouring processor ranks.
* \brief GatherScatter handle for finding out about neighbouring processor ranks.
*
*/
struct SharedGatherScatter
......@@ -329,7 +329,7 @@ class ParallelISTLHelper
};
/**
* @brief GatherScatter handle for finding out about neighbouring processor ranks.
* \brief GatherScatter handle for finding out about neighbouring processor ranks.
*
*/
template<typename GI>
......@@ -448,13 +448,13 @@ public:
#if HAVE_MPI
/**
* @brief Creates a matrix suitable for parallel AMG and the parallel information
* \brief Creates a matrix suitable for parallel AMG and the parallel information
*
*
* @tparam MatrixType The type of the ISTL matrix used.
* @tparam Comm The type of the OwnerOverlapCopyCommunication
* @param m The local matrix.
* @param c The parallel information object providing index set, interfaces and
* \tparam MatrixType The type of the ISTL matrix used.
* \tparam Comm The type of the OwnerOverlapCopyCommunication
* \param m The local matrix.
* \param c The parallel information object providing index set, interfaces and
* communicators.
*/
template<typename MatrixType, typename Comm>
......@@ -471,10 +471,11 @@ private:
}; // class ParallelISTLHelper
/**
* @brief Helper class for adding up matrix entries on border.
* @tparam GridOperator The grid operator to work on.
* @tparam MatrixType The MatrixType.
/*!
* \ingroup Linear
* \brief Helper class for adding up matrix entries on border.
* \tparam GridOperator The grid operator to work on.
* \tparam MatrixType The MatrixType.
*/
template<class TypeTag>
class EntityExchanger
......@@ -497,7 +498,7 @@ class EntityExchanger
public:
/*! \brief Constructor. Sets up the local to global relations.
\param[in] gridView The gridView on which we are operating
\param[in] dofMapper The local dof mapper
\param[in] mapper The local dof mapper
*/
EntityExchanger(const GridView& gridView, const DofMapper& mapper)
: gridView_(gridView), mapper_(mapper)
......@@ -522,7 +523,7 @@ public:
}
/**
* @brief A DataHandle class to exchange matrix sparsity patterns.
* \brief A DataHandle class to exchange matrix sparsity patterns.
*
* We look at a 2D example with a nonoverlapping grid,
* two processes and no ghosts with Q1 discretization.
......@@ -551,12 +552,12 @@ public:
//! Export type of data for message buffer
using DataType = IdType;
/** @brief Constructor
@param[in] mapper The local dof mapper.
@param[in] g2i Global to local index map.
@param[in] i2g Local to global index map.
@param[in] A Matrix to operate on.
@param[in] helper parallel istl helper.
/** \brief Constructor
\param[in] mapper The local dof mapper.
\param[in] g2i Global to local index map.
\param[in] i2g Local to global index map.
\param[in] A Matrix to operate on.
\param[in] helper parallel istl helper.
*/
MatPatternExchange (const DofMapper& mapper,
const std::map<IdType,int>& g2i,
......@@ -566,21 +567,21 @@ public:
sparsity_(A.N()), A_(A), helper_(helper)
{}
/** @brief Returns true if data for given valid codim should be communicated
/** \brief Returns true if data for given valid codim should be communicated
*/
bool contains (int dim, int codim) const
{
return (codim==dofCodim);
}
/** @brief Returns true if size of data per entity of given dim and codim is a constant
/** \brief Returns true if size of data per entity of given dim and codim is a constant
*/
bool fixedsize (int dim, int codim) const
{
return false;
}
/** @brief How many objects of type DataType have to be sent for a given entity
/** \brief How many objects of type DataType have to be sent for a given entity
*/
template<class EntityType>
size_t size (EntityType& e) const
......@@ -597,7 +598,7 @@ public:
return n;
}
/** @brief Pack data from user to message buffer
/** \brief Pack data from user to message buffer
*/
template<class MessageBuffer, class EntityType>
void gather (MessageBuffer& buff, const EntityType& e) const
......@@ -612,7 +613,7 @@ public:
}
/** @brief Unpack data from message buffer to user
/** \brief Unpack data from message buffer to user
*/
template<class MessageBuffer, class EntityType>
void scatter (MessageBuffer& buff, const EntityType& e, size_t n)
......@@ -632,7 +633,7 @@ public:
}
/**
* @brief Get the communicated sparsity pattern
* \brief Get the communicated sparsity pattern
* @return the vector with the sparsity pattern
*/
std::vector<std::set<int> >& sparsity ()
......@@ -669,11 +670,11 @@ public:
//! Export type of data for message buffer
using DataType = MatEntry;
/** @brief Constructor
@param[in] mapper The local dof mapper.
@param[in] g2i Global to local index map.
@param[in] i2g Local to global index map.
@param[in] A Matrix to operate on.
/** \brief Constructor
\param[in] mapper The local dof mapper.
\param[in] g2i Global to local index map.
\param[in] i2g Local to global index map.
\param[in] A Matrix to operate on.
*/
MatEntryExchange (const DofMapper& mapper, const std::map<IdType,int>& g2i,
const std::map<int,IdType>& i2g,
......@@ -681,21 +682,21 @@ public:
: mapper_(mapper), gid2Index_(g2i), index2GID_(i2g), A_(A)
{}
/** @brief Returns true if data for given valid codim should be communicated
/** \brief Returns true if data for given valid codim should be communicated
*/
bool contains (int dim, int codim) const
{
return (codim==dofCodim);
}
/** @brief Returns true if size of data per entity of given dim and codim is a constant
/** \brief Returns true if size of data per entity of given dim and codim is a constant
*/
bool fixedsize (int dim, int codim) const
{
return false;
}
/** @brief How many objects of type DataType have to be sent for a given entity
/** \brief How many objects of type DataType have to be sent for a given entity
*/
template<class EntityType>
size_t size (EntityType& e) const
......@@ -712,7 +713,7 @@ public:
return n;
}
/** @brief Pack data from user to message buffer
/** \brief Pack data from user to message buffer
*/
template<class MessageBuffer, class EntityType>
void gather (MessageBuffer& buff, const EntityType& e) const
......@@ -727,7 +728,7 @@ public:
}
/** @brief Unpack data from message buffer to user
/** \brief Unpack data from message buffer to user
*/
template<class MessageBuffer, class EntityType>
void scatter (MessageBuffer& buff, const EntityType& e, size_t n)
......@@ -753,9 +754,9 @@ public:
}; // class MatEntryExchange
/** @brief communicates values for the sparsity pattern of the new matrix.
@param A Matrix to operate on.
@param helper ParallelelISTLHelper.
/** \brief communicates values for the sparsity pattern of the new matrix.
\param A Matrix to operate on.
\param helper ParallelelISTLHelper.
*/
void getExtendedMatrix (Matrix& A, const ParallelISTLHelper<TypeTag>& helper)
{
......@@ -800,8 +801,8 @@ public:
}
}
/** @brief Sums up the entries corresponding to border vertices.
@param A Matrix to operate on.
/** \brief Sums up the entries corresponding to border vertices.
\param A Matrix to operate on.
*/
void sumEntries (Matrix& A)
{
......@@ -815,8 +816,8 @@ public:
#if HAVE_MPI
/**
* @brief Extends the sparsity pattern of the discretization matrix for AMG.
* @param A A reference to the matrix to change.
* \brief Extends the sparsity pattern of the discretization matrix for AMG.
* \param A A reference to the matrix to change.
*/
void getExtendedMatrix (Matrix& A) const;
#endif
......
dumux/linear/amgtraits.hh
View file @ 37503b44
......@@ -18,7 +18,6 @@
*****************************************************************************/
/*!
* \file
* \ingroup Properties
* \ingroup Linear
*
* \brief Define traits for the AMG backend.
......@@ -36,8 +35,7 @@
#include <dumux/common/properties.hh>
#include <dumux/discretization/methods.hh>
namespace Dumux
{
namespace Dumux {
// Forward declaration for the property definitions
template <class TypeTag> class AMGBackend;
......
dumux/linear/linearsolveracceptsmultitypematrix.hh
View file @ 37503b44
......@@ -18,7 +18,8 @@
*****************************************************************************/
/*!
* \file
* \brief Dumux mixeddimension iterative solver backend
* \ingroup Linear
* \brief Trait checking if linear solvers accept Dune::MultiTypeBlockMatrix or we need to convert the matrix
*/
#ifndef DUMUX_LINEAR_SOLVER_ACCEPTS_MULTITYPEMATRIX_HH
#define DUMUX_LINEAR_SOLVER_ACCEPTS_MULTITYPEMATRIX_HH
......@@ -32,13 +33,17 @@ template<typename TypeTag, typename LinearSolver>
struct LinearSolverAcceptsMultiTypeMatrixImpl
{ static constexpr bool value = true; };
//! Convenience using declaration
/*!
* \ingroup Linear
* \brief Trait checking if linear solvers accept Dune::MultiTypeBlockMatrix or we need to convert the matrix
*/
template <typename TypeTag>
using LinearSolverAcceptsMultiTypeMatrix = LinearSolverAcceptsMultiTypeMatrixImpl<TypeTag, typename GET_PROP_TYPE(TypeTag, LinearSolver)>;
//! Solvers that don't accept multi-type matrices
//! Those are all with ILU preconditioner that doesn't support the additional block level
//! And the direct solvers that have BCRS Matrix hardcoded
template<typename TypeTag>
struct LinearSolverAcceptsMultiTypeMatrixImpl<TypeTag, ILUnBiCGSTABBackend<TypeTag>>
{ static constexpr bool value = false; };
......
dumux/linear/matrixconverter.hh
View file @ 37503b44
......@@ -18,8 +18,8 @@
*****************************************************************************/
/*!
* \file
* \ingroup Linear
* \brief A helper classe that converts a Dune::MultiTypeBlockMatrix into a plain Dune::BCRSMatrix
*
*/
#ifndef DUMUX_MATRIX_CONVERTER
#define DUMUX_MATRIX_CONVERTER
......@@ -35,7 +35,8 @@
namespace Dumux {
/*!
* A helper classe that converts a Dune::MultiTypeBlockMatrix into a plain Dune::BCRSMatrix
* \ingroup Linear
* \brief A helper classe that converts a Dune::MultiTypeBlockMatrix into a plain Dune::BCRSMatrix
* TODO: allow block sizes for BCRSMatrix other than 1x1 ?
*
*/
......@@ -50,7 +51,6 @@ public:
/*!
* \brief Converts the matrix to a type the IterativeSolverBackend can handle
*
* \param M The converted matrix
* \param A The original multitype blockmatrix
*/
static auto multiTypeToBCRSMatrix(const MultiTypeBlockMatrix &A)
......@@ -184,7 +184,8 @@ private:
};
/*!
* A helper classe that converts a Dune::MultiTypeBlockVector into a plain Dune::BlockVector and transfers back values
* \ingroup Linear
* \brief A helper classe that converts a Dune::MultiTypeBlockVector into a plain Dune::BlockVector and transfers back values
*/
template<class MultiTypeBlockVector, class Scalar=double>
class VectorConverter
......@@ -197,7 +198,7 @@ public:
/*!
* \brief Converts a Dune::MultiTypeBlockVector to a plain 1x1 Dune::BlockVector
*
* \param A The original multitype blockvector
* \param b The original multitype blockvector
*/
static auto multiTypeToBlockVector(const MultiTypeBlockVector& b)
{
......@@ -262,6 +263,7 @@ private:
return size;
}
};
}
} // end namespace Dumux
#endif
dumux/linear/scotchbackend.hh
View file @ 37503b44
......@@ -19,8 +19,9 @@
/*!
* \file
* \ingroup Linear
* \brief An interface to the scotch library for matrix reordering
* \note This is adapted from the FEniCS implementation of the scotch interface
* \note You need to have PTSCOTCH installed to use this feature
*/
#ifndef DUMUX_SCOTCH_BACKEND_HH
#define DUMUX_SCOTCH_BACKEND_HH
......@@ -37,15 +38,21 @@ extern "C"
}
#endif
namespace Dumux
{
namespace Dumux {
/*!
* \file
* \ingroup Linear
* \brief A reordering backend using the scotch library
* \note You need to have PTSCOTCH installed to use this feature
*/
template<class IndexType>
class ScotchBackend
{
public:
//! the graph type
using Graph = std::vector<std::vector<IndexType>>;
public:
//! Compute reordering (map[old] -> new) using
//! Gibbs-Poole-Stockmeyer (GPS) re-ordering
static std::vector<int> computeGPSReordering(const Graph& graph,
......@@ -56,7 +63,7 @@ public:
return computeReordering(graph, strategy);
}
// Compute graph re-ordering
//! Compute graph re-ordering
static std::vector<int> computeReordering(const Graph& graph,
std::string scotchStrategy = "")
{
......@@ -65,7 +72,7 @@ public:
return permutation;
}
// Compute graph re-ordering
//! Compute graph re-ordering
static void computeReordering(const Graph& graph,
std::vector<int>& permutation,
std::vector<int>& inversePermutation,
......@@ -120,13 +127,6 @@ public:
exit(1);
}
// Check graph data for consistency
// if (SCOTCH_graphCheck(&scotchGraph))
// {
// std::cerr << "Consistency error in SCOTCH graph!" << std::endl;
// exit(1);
// }
// Re-ordering strategy
SCOTCH_Strat strat;
SCOTCH_stratInit(&strat);
......
dumux/linear/seqsolverbackend.hh
View file @ 37503b44
......@@ -18,7 +18,8 @@
*****************************************************************************/
/*!
* \file
* \brief Dumux sequential solver backends
* \ingroup Linear
* \brief Dumux sequential linear solver backends
*/
#ifndef DUMUX_SEQ_SOLVER_BACKEND_HH
#define DUMUX_SEQ_SOLVER_BACKEND_HH
......@@ -52,17 +53,13 @@ struct isBCRSMatrix<Dune::BCRSMatrix<T> > : public std::true_type {};
* combinations. Several parameters from the group LinearSolver are read to
* customize the solver and preconditioner:
*
* Verbosity: determines how verbose the linear solver should print output.
*
* MaxIterations: the maximum number of iterations for the linear solver.
*
* ResidualReduction: the threshold for declaration of convergence.
*
* PreconditionerRelaxation: relaxation parameter for the preconditioner.
*
* PreconditionerIterations: usually specifies the number of times the
* preconditioner is applied. In case of ILU(n), it specifies the order of the
* applied ILU.
* - Verbosity: determines how verbose the linear solver should print output.
* - MaxIterations: the maximum number of iterations for the linear solver.
* - ResidualReduction: the threshold for declaration of convergence.
* - PreconditionerRelaxation: relaxation parameter for the preconditioner.
* - PreconditionerIterations: usually specifies the number of times the
* preconditioner is applied. In case of ILU(n),
* it specifies the order of the applied ILU.
*/
class IterativePreconditionedSolverImpl
{
......
dumux/linear/solver.hh
View file @ 37503b44
......@@ -18,7 +18,8 @@
*****************************************************************************/
/*!
* \file
* \brief Dumux sequential solver backends
* \ingroup Linear
* \brief Base class for linear solvers
*/
#ifndef DUMUX_LINEAR_SOLVER_HH
#define DUMUX_LINEAR_SOLVER_HH
......@@ -41,7 +42,15 @@ public:
//! export scalar type (might be needed to set parameters from output)
using Scalar = typename GET_PROP_TYPE(TypeTag, Scalar);
//! default constructor sets some parameters
/*!
* \brief Contruct the solver
* \note Read parameters from the parameter tree
* - LinearSolver.Verbosity the verbosity level of the linear solver
* - LinearSolver.MaxIterations the maximum iterations of the solver
* - LinearSolver.ResidualReduction the residual reduction threshold, i.e. stopping criterion
* - LinearSolver.PreconditionerRelaxation precondition relaxation
* - LinearSolver.PreconditionerIterations the number of preconditioner iterations
*/
LinearSolver()
{
static const std::string modelParamGroup = GET_PROP_VALUE(TypeTag, ModelParameterGroup);
......@@ -52,6 +61,10 @@ public:
precondIter_ = getParamFromGroup<int>(modelParamGroup, "LinearSolver.PreconditionerIterations");
}
/*!
* \brief Solve the linear system Ax = b
* \note This has to be overloaded by the actual solver
*/
template<class Matrix, class Vector>
bool solve(const Matrix& A, Vector& x, const Vector& b)
{
......
dumux/linear/vectorexchange.hh
View file @ 37503b44
......@@ -18,6 +18,7 @@
*****************************************************************************/
/*!
* \file
* \ingroup Linear
* \brief Contains a class to exchange entries of a vector
*/
#ifndef DUMUX_VECTOR_EXCHANGE_HH
......@@ -28,6 +29,8 @@
namespace Dumux
{
/*!
* \ingroup Linear
* \todo why is this needed? is parallel/vectorexhange.hh not the same?
* \brief A data handle class to exchange entries of a vector
*/
template<class Mapper, class Vector> // mapper type and vector type
......@@ -51,9 +54,8 @@ public:
return true;
}
/*! how many objects of type DataType have to be sent for a given entity
Note: Only the sender side needs to know this size.
/*! \brief how many objects of type DataType have to be sent for a given entity
* \note Only the sender side needs to know this size.
*/
template<class Entity>
size_t size (Entity& entity) const
......@@ -68,10 +70,10 @@ public:
buff.write(dataVector_[mapper_.index(entity)]);
}
/*! unpack data from message buffer to user
n is the number of objects sent by the sender
*/
/*!
* \brief unpack data from message buffer to user
* \note n is the number of objects sent by the sender
*/
template<class MessageBuffer, class Entity>