[Move FluidFramework] FS-289 Moved Sec. 5.5 from

- Moved all general descriptions to doxygen.
- General descriptions were included in modules.txt
- New groups had to be added in modules.txt:
	-ConstraintSolver
	-EOS
	-ParameterCache

doc/doxygen/modules.txt

@@ -56,7 +56,67 @@
 
 /* ***************** Material ******************/
 /*!
- * \defgroup Material Material Properties and Laws
+ * \defgroup Material Material and Fluid Framework
+ * Short description of the most important concepts of the material and fluid framework:
+ *
+ *  - _Binary coefficient:_ Binary coefficients describe the relations
+ *  of a mixture of two components. Typical binary coefficients are
+ *  Henry coefficients or binary molecular diffusion
+ *  coefficients. So far, the programming interface for accessing binary
+ *  coefficients has not been standardized in Dumux. 
+ * 
+ *  - _Component:_ Components are fluid systems which provide the
+ *  thermodynamic relations for the liquid and gas phase of a single
+ *  chemical species or a fixed mixture of species. Their main purpose
+ *  is to provide a convenient way to access these quantities from
+ *  full-fledged fluid systems. Components are not supposed to be used
+ *  by models directly.
+ * 
+ *  - _Constraint solver:_ Constraint solvers are auxiliary tools to
+ *  make sure that a fluid state is consistent with some thermodynamic
+ *  constraints. All constraint solvers specify a well defined set of
+ *  input variables and make sure that the resulting fluid state is
+ *  consistent with a given set of thermodynamic equations.
+ * 
+ *  - _Equation of state:_ Equations of state (EOS) are auxiliary
+ *  classes which provide relations between a fluid phase's temperature,
+ *  pressure, composition and density. Since these classes are only used
+ *  internally in fluid systems, their programming interface is
+ *  currently ad-hoc.
+ * 
+ *  - _Fluid state:_ Fluid states are responsible for representing the
+ *  complete thermodynamic configuration of a system at a given spatial
+ *  and temporal position. A fluid state always provides access methods
+ *  to __all__ thermodynamic quantities, but the concept of a fluid state does not
+ *  mandate what assumptions are made to store these thermodynamic
+ *  quantities. What fluid states also do __not__ do is to make sure
+ *  that the thermodynamic state which they represent is physically
+ *  possible.
+ * 
+ *  - _Fluid system:_ Fluid systems express the thermodynamic relations 
+ *  Strictly speaking, these relations are
+ *  functions, mathematically.} between quantities. Since functions do
+ *  not exhibit any internal state, fluid systems are stateless classes,
+ *  i.e. all member functions are static. This is a conscious
+ *  decision since the thermodynamic state of the system is expressed by
+ *  a fluid state!
+ *   
+ *  - _Fluid-Matrix Interactions:_ Some parameters are functions of the fluid state as well as parameters of
+ *  the matrix. For example the capillary pressure is a function of the phase saturation
+ *  and the shape parameter \f$\lambda\f$ which is dependent on the material. All such relations
+ *  are gathered in this module.
+ * 
+ *  - _Parameter cache:_ Fluid systems sometimes require
+ *  computationally expensive parameters for multiple relations. Such
+ *  parameters can be cached using a so-called parameter
+ *  cache. Parameter cache objects are specific for each fluid system
+ *  but they must provide a common interface to update the internal
+ *  parameters depending on the quantities which changed since the last
+ *  update.
+ * 
+ *  - _Spatial Parameters:_ All parameters which depend on the matrix and
+ *   therefore on the position within the model domain are defined as spatial
+ *   parameters. For example permeability, porosity etc.
  */
     /*!
      * \ingroup Material
@@ -72,11 +132,27 @@
          */
     /*!
      * \ingroup Material
-     * \defgroup Fluidsystems Fluid Systems
+     * \defgroup ConstraintSolver Constraint Solver
+     * Constraint solvers connect the thermodynamic relations expressed by
+     * fluid systems with the thermodynamic quantities stored by fluid
+     * states. Using them is not mandatory for models, but given the fact
+     * that some thermodynamic constraints can be quite complex to solve,
+     * sharing this code between models makes sense.
+     */   
+    /*!
+     * \ingroup Material
+     * \defgroup EOS Equation of State
      */
     /*!
      * \ingroup Material
      * \defgroup FluidStates Fluid States
+     * Fluid state objects express the complete thermodynamic state of a system at a given spatial and
+     * temporal position.
+     */
+    /*!
+     * \ingroup Material
+     * \defgroup Fluidsystems Fluid Systems
+     * Fluid systems express the thermodynamic relations between the quantities of a fluid state.
      */
     /*!
      * \ingroup Material
@@ -89,7 +165,21 @@
          /*!
          * \ingroup fluidmatrixinteractions
          *  \defgroup fluidmatrixinteractionsparams Parameters for Fluid-Matrix Interactions
-         */
+         */  
+    /*!
+     * \ingroup Material
+     * \defgroup ParameterCache Parameter Cache
+     * All fluid systems must export a type for their __ParameterCache__
+     * objects. Parameter caches can be used to cache parameter that are
+     * expensive to compute and are required in multiple thermodynamic
+     * relations. For fluid systems which do need to cache parameters,
+     * Dumux provides a __NullParameterCache__ class.
+     * The actual quantities stored by parameter cache objects are specific
+     * to the fluid system and no assumptions on what they provide should be
+     * made outside of their fluid system. Parameter cache objects provide a
+     * well-defined set of methods to make them coherent with a given fluid
+     *state, though.
+     */ 
     /*!
      * \ingroup Material
      * \defgroup SpatialParameters Spatial Parameters

dumux/material/constraintsolvers/compositionalflash.hh

@@ -37,6 +37,7 @@
 namespace Dumux
 {
 /*!
+ * \ingroup ConstraintSolver
  * \brief Flash calculation routines for compositional decoupled models
  *
  *        Routines for isothermal and isobaric 2p2c and 1p2c flash.

dumux/material/constraintsolvers/compositionfromfugacities.hh

@@ -34,6 +34,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Calculates the chemical equilibrium from the component
  *        fugacities in a phase.
  */

dumux/material/constraintsolvers/compositionfromfugacities2pncmin.hh

@@ -34,6 +34,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Calculates the chemical equilibrium from the component
  *        fugacities in a phase.
  */

dumux/material/constraintsolvers/computefromreferencephase.hh

@@ -40,6 +40,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes all quantities of a generic fluid state if a
  *        reference phase has been specified.
  *

dumux/material/constraintsolvers/computefromreferencephase2pnc.hh

@@ -40,6 +40,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes all quantities of a generic fluid state if a
  *        reference phase has been specified.
  *

dumux/material/constraintsolvers/computefromreferencephase2pncmin.hh

@@ -40,6 +40,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes all quantities of a generic fluid state if a
  *        reference phase has been specified.
  *

dumux/material/constraintsolvers/fluidsystemcomputefromreferencephase.hh

@@ -35,6 +35,7 @@
 
 namespace Dumux {
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes the composition of all phases from a function in the fluidsystem.
  *
  *        This is basically an interface in order to use ConstraintSolver with fluidsystems,

dumux/material/constraintsolvers/fluidsystemconstraintsolver.hh

@@ -35,6 +35,7 @@
 
 namespace Dumux {
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes the composition of all phases from a function in the fluidsystem.
  *
  *        This is basically an interface in order to use ConstraintSolver with fluidsystems,

dumux/material/constraintsolvers/immiscibleflash.hh

@@ -34,6 +34,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Determines the pressures and saturations of all fluid phases
  *        given the total mass of all components.
  *

dumux/material/constraintsolvers/miscible2pnccomposition.hh

@@ -34,6 +34,7 @@
 
 namespace Dumux {
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes the composition of all phases of a N-phase,
  *        N-component fluid system assuming that all N phases are
  *        present

dumux/material/constraintsolvers/misciblemultiphasecomposition.hh

@@ -34,6 +34,7 @@
 
 namespace Dumux {
 /*!
+ * \ingroup ConstraintSolver
  * \brief Computes the composition of all phases of a N-phase,
  *        N-component fluid system assuming that all N phases are
  *        present

dumux/material/constraintsolvers/ncpflash.hh

@@ -34,6 +34,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup ConstraintSolver
  * \brief Determines the phase compositions, pressures and saturations
  *        given the total mass of all components.
  *

dumux/material/eos/pengrobinson.hh

@@ -43,6 +43,7 @@ namespace Dumux
 {
 
 /*!
+ * \ingroup EOS
  * \brief Implements the Peng-Robinson equation of state for liquids
  *        and gases.
  *

dumux/material/eos/pengrobinsonmixture.hh

@@ -33,6 +33,7 @@ namespace Dumux
 {
 
 /*!
+ * \ingroup EOS
  * \brief Implements the Peng-Robinson equation of state for a
  *        mixture.
  */

dumux/material/eos/pengrobinsonparams.hh

@@ -34,6 +34,7 @@
 namespace Dumux
 {
 /*!
+ * \ingroup EOS
  * \brief Stores and provides access to the Peng-Robinson parameters
  *
  * See:

dumux/material/eos/pengrobinsonparamsmixture.hh

@@ -44,6 +44,7 @@ namespace Dumux
 {
 
 /*!
+ * \ingroup EOS
  * \brief The mixing rule for the oil and the gas phases of the SPE5 problem.
  *
  * This problem comprises \f$H_2O\f$, \f$C_1\f$, \f$C_3\f$, \f$C_6\f$,

dumux/material/fluidsystems/parametercachebase.hh

@@ -27,6 +27,7 @@
 namespace Dumux
 {
 /*!
+ * \ingroup ParameterCache
  * \brief The base class of the parameter cache classes for fluid systems
  */
 template <class Implementation>

dumux/material/fluidsystems/spe5parametercache.hh

@@ -37,6 +37,7 @@ namespace Dumux
 {
 /*!
  * \ingroup Fluidsystems
+ * \ingroup ParameterCache
  * \brief Specifies the parameters required by the SPE5 problem which
  *        are dependend on the thermodynamic state.
  */