diff --git a/doc/doxygen/modules.txt b/doc/doxygen/modules.txt
index a0c634a90d749deb8f33c3f3c5dc28d9d10a80f4..deb1e09b52b4f47c35a369a114d1b85d8993575d 100644
--- a/doc/doxygen/modules.txt
+++ b/doc/doxygen/modules.txt
@@ -182,6 +182,7 @@
* but they must provide a common interface to update the internal
* parameters depending on the quantities which changed since the last
* update.
+ *
* 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
@@ -192,7 +193,19 @@
* 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.
- */
+ *
+ * Note, that the parameter cache interface only guarantees that if a
+ * more specialized <tt>update()</tt> method is called, it is not slower
+ * than the next more-general method (e.g. calling <tt>updateSingleMoleFraction()</tt>
+ * may be as expensive as <tt>updateAll()}</tt>. It is thus advisable to
+ * rather use a more general <tt>update()</tt> method once than multiple
+ * calls to specialized <tt>update()</tt> methods.
+ *
+ * To make usage of parameter caches easier for the case where all cached
+ * quantities ought to be re-calculated if a quantity of a phase was changed,
+ * it is possible to only define the <tt>updatePhase()</tt> method and
+ * derive the parameter cache from <tt>Dumux::ParameterCacheBase</tt>.
+ */
/*!
* \ingroup Material
* \defgroup SpatialParameters Spatial Parameters
diff --git a/dumux/material/constraintsolvers/compositionfromfugacities.hh b/dumux/material/constraintsolvers/compositionfromfugacities.hh
index 9fe0c9811dbb93de38523a4ee66b5e8f01f5e61b..03200efa4090e03223af500bdc3a3bff58bf222f 100644
--- a/dumux/material/constraintsolvers/compositionfromfugacities.hh
+++ b/dumux/material/constraintsolvers/compositionfromfugacities.hh
@@ -36,7 +36,18 @@ namespace Dumux {
/*!
* \ingroup ConstraintSolver
* \brief Calculates the chemical equilibrium from the component
- * fugacities in a phase.
+ * fugacities \f$ f^\kappa \f$ in the phase \f$ \alpha \f$.
+ *
+ * This constraint solver takes the component fugacity \f$f^\kappa\f$ of
+ * of component \f$\kappa\f$, the temperature \f$ T_\alpha \f$, the pressure
+ * \f$p_\alpha\f$ and the composition \f$x^\lambda_\alpha\f$ of a phase
+ * \f$\alpha\f$ as input and calculates the mole fraction of component
+ * \f$\kappa\f$ in that fluid phase \f$x^\kappa_\alpha\f$. This means
+ * that the thermodynamic constraints used by this solver are
+ *
+ * \f$ f^\kappa = \Phi^\kappa_\alpha(\{x^\lambda_\alpha \}, T_\alpha, p_\alpha) p_\alpha x^\kappa_\alpha\; \f$,
+ *
+ * where \f${f^\kappa}\f$, \f$ T_\alpha \f$ and \f$ p_\alpha \f$ are fixed values.
*/
template <class Scalar, class FluidSystem>
class CompositionFromFugacities
diff --git a/dumux/material/constraintsolvers/computefromreferencephase.hh b/dumux/material/constraintsolvers/computefromreferencephase.hh
index 2f4430e6b28031e744a670dd32ddff6e5cb03301..f12d4aab941fff8648f6b74326e0a92db46ad236 100644
--- a/dumux/material/constraintsolvers/computefromreferencephase.hh
+++ b/dumux/material/constraintsolvers/computefromreferencephase.hh
@@ -49,21 +49,32 @@ namespace Dumux {
* constraint solver assumes thermodynamic equilibrium. It assumes the
* following quantities to be set:
*
- * - composition (mole+mass fractions) of the *reference* phase
- * - temperature of the *reference* phase
- * - saturations of *all* phases
- * - pressures of *all* phases
+ * - composition (mole+mass fractions) of the *reference* phase \f$x^\kappa_\beta\f$
+ * - temperature of the *reference* phase \f$T_\beta\f$
+ * - saturations of *all* phases \f$S_\alpha\f$, \f$S_\beta\f$
+ * - pressures of *all* phases \f$p_\alpha\f$, \f$p_\beta\f$
+ *
+ * \f$ f^\kappa_\beta = f^\kappa_\alpha = \Phi^\kappa_\alpha(\{x^\lambda_\alpha \}, T_\alpha, p_\alpha) p_\alpha x^\kappa_\alpha\; \f$,
+ *
+ * \f$ p_\alpha = p_\beta + p_{c\beta\alpha}\; \f$,
*
* after calling the solve() method the following quantities are
* calculated in addition:
*
- * - temperature of *all* phases
+ * - temperature of *all* phases \f$T_\alpha\f$, \f$T_\beta\f$
* - density, molar density, molar volume of *all* phases
- * - composition in mole and mass fractions and molaries of *all* phases
- * - mean molar masses of *all* phases
+ * \f$\rho_\alpha\f$, \f$\rho_\beta\f$, \f$\rho_{mol, \alpha}\f$, \f$\rho_{mol, \beta}\f$,
+ * \f$V_{mol, \alpha}\f$, \f$V_{mol, \beta}\f$
+ * - composition in mole and mass fractions and molarities of *all* phases
+ * \f$x^\kappa_\alpha\f$, \f$x^\kappa_\beta\f$, \f$X^\kappa_\alpha\f$, \f$X^\kappa_\beta\f$,
+ * \f$c^\kappa_\alpha\f$, \f$c^\kappa_\beta\f$
+ * - mean molar masses of *all* phases \f$M_\alpha\f$, \f$M_\beta\f$
* - fugacity coefficients of *all* components in *all* phases
+ * \f$\Phi^\kappa_\alpha\f$, \f$\Phi^\kappa_\beta\f$
* - if the setViscosity parameter is true, also dynamic viscosities of *all* phases
+ * \f$\mu_\alpha\f$, \f$\mu_\beta\f$
* - if the setEnthalpy parameter is true, also specific enthalpies and internal energies of *all* phases
+ * \f$h_\alpha\f$, \f$h_\beta\f$, \f$u_\alpha\f$, \f$u_\beta\f$
*/
template <class Scalar, class FluidSystem>
class ComputeFromReferencePhase
diff --git a/dumux/material/fluidsystems/2pimmiscible.hh b/dumux/material/fluidsystems/2pimmiscible.hh
index dc0e751e2a3648aab7852cc1c5a9c8d85c130ffc..1416272208450db50261e144b4e70e9862e6e1d2 100644
--- a/dumux/material/fluidsystems/2pimmiscible.hh
+++ b/dumux/material/fluidsystems/2pimmiscible.hh
@@ -19,11 +19,7 @@
/*!
* \file
*
- * \brief A fluid system for two-phase models assuming immiscibility and
- * thermodynamic equilibrium
- *
- * The wetting and the non-wetting phase can be defined via their
- * individual components.
+ * \brief @copybrief Dumux::FluidSystems::TwoPImmiscible
*/
#ifndef DUMUX_2P_IMMISCIBLE_FLUID_SYSTEM_HH
#define DUMUX_2P_IMMISCIBLE_FLUID_SYSTEM_HH
@@ -48,6 +44,8 @@ namespace FluidSystems {
* \brief A fluid system for two-phase models assuming immiscibility and
* thermodynamic equilibrium
*
+ * The fluid phases are completely specified by means of their
+ * constituting components.
* The wetting and the non-wetting phase can be defined individually
* via Dumux::LiquidPhase<Component> and
* Dumux::GasPhase<Component>. These phases consist of one pure
@@ -421,7 +419,11 @@ public:
}
/*!
- * \brief Specific isobaric heat capacity of a fluid phase.
+ * @copybrief Base::thermalConductivity
+ *
+ * Additional comments:
+ *
+ * Specific isobaric heat capacity of a fluid phase.
* \f$\mathrm{[J/(kg*K)]}\f$.
*
* \param fluidState The fluid state of the two-phase model
diff --git a/dumux/material/fluidsystems/base.hh b/dumux/material/fluidsystems/base.hh
index 0d9f42397c7ccbad1c2911b3c07b66e9eed02dba..1877b34595a0878cbc1fd9efaf377a7eaae7b771 100644
--- a/dumux/material/fluidsystems/base.hh
+++ b/dumux/material/fluidsystems/base.hh
@@ -163,11 +163,20 @@ public:
}
/*!
- * \brief Thermal conductivity of a fluid phase \f$\mathrm{[W/(m K)]}\f$.
+ * \brief Thermal conductivity \f$\lambda_\alpha \f$ of a fluid phase \f$\mathrm{[W/(m K)]}\f$.
* \param fluidState The fluid state
* \param phaseIdx Index of the fluid phase
* \param paramCache mutable parameters
*
+ * Given a fluid state, an up-to-date parameter cache and a phase index,
+ * this method returns the thermal conductivity \f$\lambda_\alpha \f$ of the fluid
+ * phase. The thermal conductivity is defined by means of the relation
+ *
+ * \f$ q = \lambda_\alpha \mathbf{grad}\;T_\alpha \; \f$,
+ *
+ * where \f$ q\f$ is the local heat flux density caused by the temperature gradient
+ * \f$\mathbf{grad}\;T_\alpha\f$.
+ *
* Use the conductivity of air and water as a first approximation.
* Source:
* http://en.wikipedia.org/wiki/List_of_thermal_conductivities
@@ -181,11 +190,19 @@ public:
}
/*!
- * \brief Specific isobaric heat capacity of a fluid phase \f$\mathrm{[J/(kg*K)]}\f$.
+ * \brief Specific isobaric heat capacity \f$c_{p,\alpha}\f$ of a fluid phase \f$\mathrm{[J/(kg*K)]}\f$.
*
* \param paramCache mutable parameters
* \param phaseIdx for which phase to give back the heat capacity
* \param fluidState represents all relevant thermodynamic quantities of a fluid system
+ *
+ * Given a fluid state, an up-to-date parameter cache and a phase index, this method
+ * computes the isobaric heat capacity \f$c_{p,\alpha}\f$ of the fluid phase. The isobaric
+ * heat capacity is defined as the partial derivative of the specific enthalpy \f$h_\alpha\f$
+ * to the fluid pressure \f$p_\alpha\f$:
+ *
+ * \f$ c_{p,\alpha} = \frac{\partial h_\alpha}{\partial p_\alpha} \f$
+ *
*/
template <class FluidState>
static Scalar heatCapacity(const FluidState &fluidState,
diff --git a/dumux/material/fluidsystems/brineair.hh b/dumux/material/fluidsystems/brineair.hh
index 922eba52d3f95396f71f231a03be006afeaaa91f..3147ab86e0211d45f22dada8f12fbff39cf8663f 100644
--- a/dumux/material/fluidsystems/brineair.hh
+++ b/dumux/material/fluidsystems/brineair.hh
@@ -543,15 +543,14 @@ public:
* \param phaseIdx The index of the phase
*
* See:
- * Class Class 2000
+ * Class 2000
* Theorie und numerische Modellierung nichtisothermer Mehrphasenprozesse in NAPL-kontaminierten porösen Medien
* Chapter 2.1.13 Innere Energie, Wäremekapazität, Enthalpie \cite A3:class:2001 <BR>
*
* Formula (2.42):
* the specific enthalpy of a gas phase result from the sum of (enthalpies*mass fraction) of the components
* For the calculation of enthalpy of brine we refer to (Michaelides 1981)
- */
- /*!
+ *
* \todo This system neglects the contribution of gas-molecules in the liquid phase.
* This contribution is probably not big. Somebody would have to find out the enthalpy of solution for this system. ...
*/
diff --git a/dumux/material/fluidsystems/h2oair.hh b/dumux/material/fluidsystems/h2oair.hh
index 19ccdcc0bd3983c50401e93e42b20eee1a0ac19f..2bb209029e3bbca2e272b2c079a213df3ca7681c 100644
--- a/dumux/material/fluidsystems/h2oair.hh
+++ b/dumux/material/fluidsystems/h2oair.hh
@@ -20,8 +20,7 @@
/*!
* \file
*
- * \brief A fluid system with a liquid and a gaseous phase and \f$\mathrm{H_2O}\f$ and \f$\mathrm{Air}\f$
- * as components.
+ * \brief @copybrief Dumux::FluidSystems::H2OAir
*/
#ifndef DUMUX_H2O_AIR_SYSTEM_HH
#define DUMUX_H2O_AIR_SYSTEM_HH
@@ -55,8 +54,10 @@ namespace FluidSystems
* \brief A compositional twophase fluid system with water and air as
* components in both, the liquid and the gas phase.
*
- * This fluidsystem is applied by default with the tabulated version of
- * water of the IAPWS-formulation.
+ * This fluidsystem features gas and liquid phases of distilled water
+ * \f$(\mathrm{H_2O})\f$) and air (Pseudo component composed of \f$\mathrm{79\%\;N_2}\f$,
+ * \f$\mathrm{20\%\;O_2}\f$ and \f$\mathrm{1\%\;Ar}\f$) as components. It is applied by
+ * default with the tabulated version of water of the IAPWS-formulation.
*
* To change the component formulation (i.e. to use nontabulated or
* incompressible water), or to switch on verbosity of tabulation,
diff --git a/dumux/material/fluidsystems/h2oairmesitylene.hh b/dumux/material/fluidsystems/h2oairmesitylene.hh
index 66aedb8ab0ff20438cdced50a3e5188eeea611dc..5a59ad19f3a2e1f1e32eae3a28bc0c7ec4988d72 100644
--- a/dumux/material/fluidsystems/h2oairmesitylene.hh
+++ b/dumux/material/fluidsystems/h2oairmesitylene.hh
@@ -19,8 +19,7 @@
/*!
* \file
*
- * \brief A fluid system with water, gas and NAPL as phases and
- * \f$\mathrm{H_2O}\f$ and \f$\mathrm{Air}\f$ and \f$\mathrm{NAPL (contaminant)}\f$ as components.
+ * \brief @copybrief Dumux::FluidSystems::H2OAirMesitylene
*/
#ifndef DUMUX_H2O_AIR_MESITYLENE_FLUID_SYSTEM_HH
#define DUMUX_H2O_AIR_MESITYLENE_FLUID_SYSTEM_HH
@@ -46,8 +45,9 @@ namespace FluidSystems
/*!
* \ingroup Fluidsystems
- * \brief A compositional fluid with water and molecular nitrogen as
- * components in both, the liquid and the gas phase.
+ * \brief A three-phase fluid system featuring gas, NAPL and water as phases and
+ * distilled water \f$(\mathrm{H_2O})\f$ and air (Pseudo component composed of
+ * \f$\mathrm{79\%\;N_2}\f$, \f$\mathrm{20\%\;O_2}\f$ and Mesitylene \f$(\mathrm{C_6H_3(CH_3)_3})\f$ as components. It assumes all phases to be ideal mixtures.
*/
template <class Scalar,
class H2OType = Dumux::TabulatedComponent<Scalar, Dumux::H2O<Scalar> > >
diff --git a/dumux/material/fluidsystems/h2oairxylene.hh b/dumux/material/fluidsystems/h2oairxylene.hh
index c597bd0f8880eae18b2028a323fbd331370fffb0..847b6e43e5cbcb46e08f5360d08f2ead5e117abe 100644
--- a/dumux/material/fluidsystems/h2oairxylene.hh
+++ b/dumux/material/fluidsystems/h2oairxylene.hh
@@ -19,8 +19,7 @@
/*!
* \file
*
- * \brief A fluid system with water, gas and NAPL as phases and
- * \f$\mathrm{H_2O}\f$ and \f$\mathrm{Air}\f$ and \f$\mathrm{NAPL (contaminant)}\f$ as components.
+ * \brief @copybrief Dumux::FluidSystems::H2OAirXylene
*/
#ifndef DUMUX_H2O_AIR_XYLENE_FLUID_SYSTEM_HH
#define DUMUX_H2O_AIR_XYLENE_FLUID_SYSTEM_HH
@@ -44,8 +43,10 @@ namespace FluidSystems
/*!
* \ingroup Fluidsystems
- * \brief A compositional fluid with water and molecular nitrogen as
- * components in both, the liquid and the gas phase.
+ * \brief A three-phase fluid system featuring gas, NAPL and water as phases and
+ * distilled water \f$(\mathrm{H_2O})\f$ and air (Pseudo component composed of
+ * \f$\mathrm{79\%\;N_2}\f$, \f$\mathrm{20\%\;O_2}\f$ and Mesitylene \f$(\mathrm{C_8H_{10}})\f$ as components. It assumes all phases to be ideal mixtures.
+ */
*/
template <class Scalar,
class H2OType = Dumux::TabulatedComponent<Scalar, Dumux::H2O<Scalar> > >
diff --git a/dumux/material/fluidsystems/h2on2.hh b/dumux/material/fluidsystems/h2on2.hh
index 113cba34d10a47beeafc357c122b68c281266a3d..e369b8ae97d96a6a6ab2eeec9335e8f7f73b945d 100644
--- a/dumux/material/fluidsystems/h2on2.hh
+++ b/dumux/material/fluidsystems/h2on2.hh
@@ -19,7 +19,7 @@
/*!
* \file
*
- * \brief A twophase fluid system with water and nitrogen as components.
+ * \brief @copybrief Dumux::FluidSystems::H2ON2
*/
#ifndef DUMUX_H2O_N2_FLUID_SYSTEM_HH
#define DUMUX_H2O_N2_FLUID_SYSTEM_HH
@@ -52,7 +52,9 @@ namespace FluidSystems
/*!
* \ingroup Fluidsystems
*
- * \brief A twophase fluid system with water and nitrogen as components.
+ * \brief A two-phase fluid system featuring gas and liquid phases and destilled
+ * water \f$(\mathrm{H_2O})\f$ and pure molecular Nitrogen \f$(\mathrm{N_2})\f$ as
+ * components.
*
* This FluidSystem can be used without the PropertySystem that is applied in Dumux,
* as all Parameters are defined via template parameters. Hence it is in an
diff --git a/dumux/material/fluidsystems/h2on2kinetic.hh b/dumux/material/fluidsystems/h2on2kinetic.hh
index ba486da3e1f4ea6780fc6cfef4c83a198edf2b63..47cf819016ba124b655bb149e063447a10dcbd1c 100644
--- a/dumux/material/fluidsystems/h2on2kinetic.hh
+++ b/dumux/material/fluidsystems/h2on2kinetic.hh
@@ -19,7 +19,7 @@
/*!
* \file
*
- * \brief A twophase fluid system with water and nitrogen as components.
+ * \brief @copybrief Dumux::FluidSystems::H2ON2Kinetic
*/
#ifndef DUMUX_H2O_N2_FLUID_SYSTEM_KINETIC_HH
#define DUMUX_H2O_N2_FLUID_SYSTEM_KINETIC_HH
@@ -43,7 +43,8 @@ namespace FluidSystems
{
/*!
* \ingroup Fluidsystems
- * \brief A twophase fluid system with water and nitrogen as components.
+ * \brief A two-phase fluid system featuring gas and liquid phases and destilled
+ * water \f$(\mathrm{H_2O})\f$ and pure molecular Nitrogen \f$(\mathrm{N_2})\f$ as components.
*/
template <class Scalar, bool useComplexRelations = true>
class H2ON2Kinetic :
diff --git a/dumux/material/fluidsystems/parametercachebase.hh b/dumux/material/fluidsystems/parametercachebase.hh
index d4efca8511d34e9d094cea383b8ba0b500fa5ec5..95940e6707abf9886c12ec2634dd798d461b7d51 100644
--- a/dumux/material/fluidsystems/parametercachebase.hh
+++ b/dumux/material/fluidsystems/parametercachebase.hh
@@ -44,6 +44,13 @@ public:
ParameterCacheBase()
{}
+ /*!
+ * \brief Update all cached quantities for all phases.
+ *
+ * The <tt>except</tt> argument contains a bit field of the quantities
+ * which have not been modified since the last call to an <tt>update()</tt>
+ * method.
+ */
template <class FluidState>
void updateAll(const FluidState &fs, int exceptQuantities = None)
{
@@ -51,7 +58,10 @@ public:
asImp_().updatePhase(fs, phaseIdx);
}
-
+ /*!
+ * \brief Update all cached quantities which depend on the pressure of any
+ * fluid phase.
+ */
template <class FluidState>
void updateAllPressures(const FluidState &fs)
{
@@ -59,6 +69,10 @@ public:
asImp_().updatePhase(fs, phaseIdx);
}
+ /*!
+ * \brief Update all cached quantities which depend on the temperature of any
+ * fluid phase.
+ */
template <class FluidState>
void updateAllTemperatures(const FluidState &fs)
{
@@ -69,6 +83,9 @@ public:
/*!
* \brief Update all cached parameters of a specific fluid phase
+ *
+ * The quantities specified by the <tt>except</tt> bit field have not been
+ * modified since since the last call to an <tt>update()</tt> method.
*/
template <class FluidState>
void updatePhase(const FluidState &fs, int phaseIdx, int exceptQuantities = None)
diff --git a/dumux/material/fluidsystems/spe5.hh b/dumux/material/fluidsystems/spe5.hh
index a140755898147fd0083d7b5e7b217221a063b7c4..5d17a0c179995eb69642713250a2fe668389694b 100644
--- a/dumux/material/fluidsystems/spe5.hh
+++ b/dumux/material/fluidsystems/spe5.hh
@@ -19,16 +19,7 @@
/*!
* \file
*
- * \brief The mixing rule for the oil and the gas phases of the SPE5 problem.
- *
- * This problem comprises \f$\mathrm{H_2O}\f$, \f$\mathrm{C_1}\f$, \f$\mathrm{C_3}\f$, \f$\mathrm{C_6}\f$,
- * \f$\mathrm{C_10}\f$, \f$\mathrm{C_15}\f$ and \f$\mathrm{C_20}\f$ as components.
- *
- * See:
- *
- * J.E. Killough, et al.: Fifth Comparative Solution Project:
- * Evaluation of Miscible Flood Simulators, Ninth SPE Symposium on
- * Reservoir Simulation, 1987 \cite SPE5
+ * \brief @copybrief Dumux::FluidSystems::Spe5
*/
#ifndef DUMUX_SPE5_FLUID_SYSTEM_HH
#define DUMUX_SPE5_FLUID_SYSTEM_HH
@@ -46,8 +37,14 @@ namespace FluidSystems
* \ingroup Fluidsystems
* \brief The fluid system for the SPE-5 benchmark problem.
*
- * This problem comprises \f$\mathrm{H_2O}\f$, \f$\mathrm{C_1}\f$, \f$\mathrm{C_3}\f$, \f$\mathrm{C_6}\f$,
- * \f$\mathrm{C_10}\f$, \f$\mathrm{C_15}\f$ and \f$\mathrm{C_20}\f$ as components.
+ * A three-phase fluid system featuring gas, oil and water as phases and the seven
+ * components distilled water, Methane \f$(\mathrm{C_1})\f$, Propane \f$(\mathrm{C_3})\f$,
+ * Pentane \f$(\mathrm{C_5})\f$, Heptane \f$(\mathrm{C_7})\f$, Decane
+ * \f$(\mathrm{C_{10}})\f$, Pentadecane \f$(\mathrm{C_{15}})\f$ and Icosane
+ * \f$(\mathrm{C_{20}})\f$. For the water phase the IAPWS-97 formulation is used as
+ * equation of state, while for the gas and oil phases a Peng-Robinson
+ * equation of state with slightly modified parameters is used. This fluid system is highly
+ * non-linear, and the gas and oil phases also cannot be considered ideal.
*
* See:
*