address comments

doc/modules/changes/20220630_haoyuan

@@ -1,5 +1,8 @@
 New: The values of the properties of material phases can be entered
-by the differences between adjacent phases. Besides, there are two ways
-to input these values of differences: arithmetic and logarithmic.
+by the differences between adjacent phases. If this is the case,
+then all the phase properties need to be entered by a value for the first phase
+followed by M-1 values for the differences between adjacent phases. 
+Also note that the quotients rather than the differences are used
+for the "Prefactors" in the flow laws.
 <br>
 (Haoyuan Li, 2022/06/30)

include/aspect/material_model/equation_of_state/multicomponent_incompressible.h

@@ -98,8 +98,9 @@ namespace aspect
         private:
           /**
            * Whether to define the phase properties based on the exact values, or the value differences.
-           * Based on this parameter, inputs will be either the exact values, one for each phase, or a value for the first phase
-           * for each composition followed by differences between adjacent phases.
+           * Based on this parameter, either M values, one for each phase, or a value for the first phase
+           * followed by M-1 values for the differences between adjacent phases will be used to define
+           * the phase properties.
            */
           bool use_values_instead_of_differences;
 

include/aspect/material_model/rheology/dislocation_creep.h

@@ -139,8 +139,9 @@ namespace aspect
 
           /**
            * Whether to define the phase properties based on the exact values, or the value differences.
-           * Based on this parameter, inputs will be either the exact values, one for each phase, or a value for the first phase
-           * for each composition followed by differences between adjacent phases.
+           * Based on this parameter, either M values, one for each phase, or a value for the first phase
+           * followed by M-1 values for the differences between adjacent phases will be used to define
+           * the phase properties.
            */
           bool use_values_instead_of_differences;
 

include/aspect/material_model/rheology/drucker_prager.h

@@ -142,8 +142,9 @@ namespace aspect
 
           /**
            * Whether to define the phase properties based on the exact values, or the value differences.
-           * Based on this parameter, inputs will be either the exact values, one for each phase, or a value for the first phase
-           * for each composition followed by differences between adjacent phases.
+           * Based on this parameter, either M values, one for each phase, or a value for the first phase
+           * followed by M-1 values for the differences between adjacent phases will be used to define
+           * the phase properties.
            */
           bool use_values_instead_of_differences;
       };

include/aspect/material_model/utilities.h

@@ -555,7 +555,8 @@ namespace aspect
       * is added to the logarithmic of the previous phase's value.
       */
       std::vector<double>
-      parse_map_differences_to_values( const std::vector<double> , const std::unique_ptr<std::vector<unsigned int>> &,
+      parse_map_differences_to_values( const std::vector<double>,
+                                       const std::unique_ptr<std::vector<unsigned int>> &,
                                        const PhaseUtilities::PhaseAveragingOperation=PhaseUtilities::arithmetic);
 
     }

include/aspect/utilities.h

@@ -135,7 +135,12 @@ namespace aspect
      * @param [in] allow_missing_keys Whether to allow that some keys are
      *   not set to any values, i.e. they do not appear at all in the
      *   @p key_value_map. This also allows a completely empty map.
-     *
+     * @param [in] use_values_instead_of_differences Whether to define the
+     *   phase properties based on the exact values rather than value differences.
+     *   if this is false, then all the phase properties need to be entered by
+     *   a value for the first phase followed by M-1 values for the differences
+     *   between adjacent phases. Also note that the quotients rather than the
+     *   differences are used for the "Prefactors" in the flow laws.
      * @return A vector of values that are parsed from the map, provided
      *   in the order in which the keys appear in the @p list_of_keys argument.
      *   If multiple values per key are allowed, the vector contains first all

source/material_model/equation_of_state/multicomponent_incompressible.cc

@@ -97,7 +97,7 @@ namespace aspect
                            "If only one value is given, then all use the same value. "
                            "Units: \\si{\\joule\\per\\kelvin\\per\\kilogram}.");
         prm.declare_alias ("Heat capacities", "Specific heats");
-        prm.declare_entry ("Define phase properties by exact values instead of differences", "true",
+        prm.declare_entry ("Define phase properties by differences instead of exact values", "true",
                            Patterns::Bool (),
                            "Whether to list phase transitions properties by differences between adjacent phases or an exact values on each phase."
                            "If this parameter is true, "
@@ -123,7 +123,7 @@ namespace aspect
         const std::vector<std::string> list_of_composition_names = this->introspection().get_composition_names();
 
         // Parse multicomponent properties
-        use_values_instead_of_differences = prm.get_bool("Define phase properties by exact values instead of differences");
+        use_values_instead_of_differences = prm.get_bool("Define phase properties by differences instead of exact values");
 
         std::vector<double> density_inputs = Utilities::parse_map_to_double_array (prm.get("Densities"),
                                                                                    list_of_composition_names,

source/material_model/rheology/diffusion_creep.cc

@@ -176,7 +176,7 @@ namespace aspect
                            "Units: \\si{\\meter\\cubed\\per\\mole}.");
         prm.declare_entry ("Grain size", "1e-3", Patterns::Double (0.),
                            "Units: \\si{\\meter}.");
-        prm.declare_entry ("Define phase properties by exact values instead of differences", "true",
+        prm.declare_entry ("Define phase properties by differences instead of exact values", "true",
                            Patterns::Bool (),
                            "Whether to list phase transitions properties by differences between adjacent phases or an exact values on each phase."
                            "If this parameter is true, "
@@ -200,7 +200,7 @@ namespace aspect
         const bool has_background_field = true;
 
         // Read parameters, each of size of number of composition + number of phases + 1
-        use_values_instead_of_differences = prm.get_bool("Define phase properties by exact values instead of differences");
+        use_values_instead_of_differences = prm.get_bool("Define phase properties by differences instead of exact values");
 
         std::vector<double> prefactors_diffusion_inputs = Utilities::parse_map_to_double_array(prm.get("Prefactors for diffusion creep"),
                                                           list_of_composition_names,

source/material_model/rheology/dislocation_creep.cc

@@ -169,7 +169,7 @@ namespace aspect
                            "for a total of N+1 values, where N is the number of compositional fields. "
                            "If only one value is given, then all use the same value. "
                            "Units: \\si{\\meter\\cubed\\per\\mole}.");
-        prm.declare_entry ("Define phase properties by exact values instead of differences", "true",
+        prm.declare_entry ("Define phase properties by differences instead of exact values", "true",
                            Patterns::Bool (),
                            "Whether to list phase transitions properties by differences between adjacent phases or an exact values on each phase."
                            "If this parameter is true, "
@@ -192,7 +192,7 @@ namespace aspect
         const bool has_background_field = true;
 
         // Read parameters, each of size of number of composition + number of phases + 1
-        use_values_instead_of_differences = prm.get_bool("Define phase properties by exact values instead of differences");
+        use_values_instead_of_differences = prm.get_bool("Define phase properties by differences instead of exact values");
         std::vector<double> prefactors_dislocation_inputs = Utilities::parse_map_to_double_array(prm.get("Prefactors for dislocation creep"),
                                                             list_of_composition_names,
                                                             has_background_field,

source/material_model/rheology/drucker_prager.cc

@@ -195,7 +195,7 @@ namespace aspect
         prm.declare_entry ("Plastic damper viscosity", "0.0", Patterns::Double(0),
                            "Viscosity of the damper that acts in parallel with the plastic viscosity "
                            "to produce mesh-independent behavior at sufficient resolutions. Units: \\si{\\pascal\\second}");
-        prm.declare_entry ("Define phase properties by exact values instead of differences", "true",
+        prm.declare_entry ("Define phase properties by differences instead of exact values", "true",
                            Patterns::Bool (),
                            "Whether to list phase transitions properties by differences between adjacent phases or an exact values on each phase."
                            "If this parameter is true, "
@@ -217,7 +217,7 @@ namespace aspect
         // Establish that a background field is required here
         const bool has_background_field = true;
 
-        use_values_instead_of_differences = prm.get_bool("Define phase properties by exact values instead of differences");
+        use_values_instead_of_differences = prm.get_bool("Define phase properties by differences instead of exact values");
 
         std::vector<double> angles_internal_friction_inputs = Utilities::parse_map_to_double_array(prm.get("Angles of internal friction"),
                                                               list_of_composition_names,

tests/visco_plastic_phases_viscosity_jump.prm

@@ -83,7 +83,7 @@ subsection Material model
     set Phase transition widths = background:1e3|1e3, right:1e3|1e3
     set Phase transition temperatures = background:273|273, right:273|273
     set Phase transition Clapeyron slopes = background:0|0, right:0|0
-    set Define phase properties by exact values instead of differences = false
+    set Define phase properties by differences instead of exact values = false
 
     set Densities = background:3300|100|100, right:3600|100|100
     set Thermal expansivities = background:3.5e-5|-1.5e-5|-0.5e-5, right:3.5e-5|-1.5e-5|-0.5e-5