[cig-commits] [commit] master: Better document a field. (8c47006)

[cig_noreply at geodynamics.org]

Repository : https://github.com/geodynamics/aspect

On branch  : master
Link       : https://github.com/geodynamics/aspect/compare/a4c3cb44df101429ee9ea0cf5e8e423bd9dec11f...c41f9897e232c1a2ff987b46a3d31767708bf7af

>---------------------------------------------------------------

commit 8c470061a240b59c23cef81257610ccc557b0ab1
Author: Wolfgang Bangerth <bangerth at math.tamu.edu>
Date:   Wed Aug 6 18:21:26 2014 -0500

    Better document a field.


>---------------------------------------------------------------

8c470061a240b59c23cef81257610ccc557b0ab1
 include/aspect/material_model/interface.h | 52 ++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 4 deletions(-)

diff --git a/include/aspect/material_model/interface.h b/include/aspect/material_model/interface.h
index 70f3997..373c158 100644
--- a/include/aspect/material_model/interface.h
+++ b/include/aspect/material_model/interface.h
@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 2011, 2012, 2013 by the authors of the ASPECT code.
+  Copyright (C) 2011, 2012, 2013, 2014 by the authors of the ASPECT code.
 
   This file is part of ASPECT.
 
@@ -576,6 +576,38 @@ namespace aspect
            * Change in composition due to chemical reactions at the given
            * positions. The term reaction_terms[i][c] is the change in
            * compositional field c at point i.
+	   *
+	   * The mental model behind prescribing actual changes in composition
+	   * rather than reaction rates is that we
+	   * assume that there is always an equilibrium between the
+	   * compositional fields (because the time scale of reactions is
+	   * normally much shorter than that of convection), so the quantity
+	   * returned by this function is an actual change in the amount of
+	   * material, which is added to or substracted from
+	   * the current value of the compositional field, and NOT a reaction
+	   * rate. The idea is, that in dependence of temperature, pressure,
+	   * position and the compositional fields themselves an equilibrium can
+	   * be calculated, and the difference between the current value and the
+	   * equilibrium can be added to the respective compositional field.
+	   *
+	   * For mass conservation it should ALWAYS be checked that what is
+	   * subtracted from one field is added to another field (and the other
+	   * way round) and that one never substracts more than the actual
+	   * value of a field (so it does not get negative).
+	   *
+	   * This function has a default implementation that sets the reaction
+	   * term to zero (assuming no reactions).
+	   *
+	   * @note In cases where one has slow chemical reactions (or cases
+	   * where compositional fields are used to track quantities different
+	   * than actual compositions, for example accumulated strains in
+	   * damage models), models are formulated as differential equations
+	   * with right hand sides, not as instantaneous equations. In such
+	   * cases, the reaction terms (i.e., the incremental additions to
+	   * the previous state) are usually of the form reaction rate times
+	   * time step size. To implement something like this, derive your
+	   * material model from SimulatorAccess so you can query the time step
+	   * used by the simulator in order to compute the reaction increment.
            */
           std::vector<std::vector<double> > reaction_terms;
         };
@@ -731,8 +763,9 @@ namespace aspect
          * due to reactions between different compositional fields. It is
          * assumed that there is always an equilibrium between the
          * compositional fields (because the time scale of reactions is
-         * normally much shorter than that of convection), so this is an
-         * actual amount of material, which is added to or substracted from
+         * normally much shorter than that of convection), so the quantity
+	 * returned by this function is an actual change in the amount of
+	 * material, which is added to or substracted from
          * the current value of the compositional field, and NOT a reaction
          * rate. The idea is, that in dependence of temperature, pressure,
          * position and the compositional fields themselves an equilibrium can
@@ -741,11 +774,22 @@ namespace aspect
          *
          * For mass conservation it should ALWAYS be checked that what is
          * subtracted from one field is added to another field (and the other
-         * way round) and that it is never more substracted than the actual
+         * way round) and that one never substracts more than the actual
          * value of a field (so it does not get negative).
          *
          * This function has a default implementation that sets the reaction
          * term to zero (assuming no reactions).
+	 *
+	 * @note In cases where one has slow chemical reactions (or cases
+	 * where compositional fields are used to track quantities different
+	 * than actual compositions, for example accumulated strains in
+	 * damage models), models are formulated as differential equations
+	 * with right hand sides, not as instantaneous equations. In such
+	 * cases, the reaction terms (i.e., the incremental additions to
+	 * the previous state) are usually of the form reaction rate times
+	 * time step size. To implement something like this, derive your
+	 * material model from SimulatorAccess so you can query the time step
+	 * used by the simulator in order to compute the reaction increment.
          */
         virtual double reaction_term (const double      temperature,
                                       const double      pressure,