Merge branch 'concepts/doc-pressure-unit' into 'concepts/main' (!14)

doc, ice_history: correct units for 'sigP' and improve doc for stress variables (CICE-Consortium#817)

Closes #20

cicecore/cicedynB/analysis/ice_history.F90

@@ -959,7 +959,7 @@ subroutine init_hist (dt)
              "sig2 is instantaneous", c1, c0,                  &
              ns1, f_sig2)
 
-         call define_hist_field(n_sigP,"sigP","1",ustr2D, ucstr, &
+         call define_hist_field(n_sigP,"sigP","N/m",ustr2D, ucstr, &
              "ice pressure",                       &
              "sigP is instantaneous", c1, c0,                  &
              ns1, f_sigP)

doc/source/cice_index.rst

@@ -578,7 +578,8 @@ either Celsius or Kelvin units).
    "shear", "strain rate II component", "1/s"
    "shlat", "southern latitude of artificial mask edge", "30\ :math:`^\circ`\ N"
    "shortwave", "flag for shortwave parameterization (‘ccsm3’ or ‘dEdd’)", ""
-   "sig1(2)", "principal stress components (diagnostic)", ""
+   "sig1(2)", "principal stress components :math:`\sigma_{n,1}`, :math:`\sigma_{n,2}` (diagnostic)", ""
+   "sigP", "internal ice pressure", "N/m"
    "sil", "silicate concentration", "mmol/m\ :math:`^3`"
    "sinw", "sine of the turning angle in water", "0."
    "Sinz", "ice salinity profile", "ppt"
@@ -599,10 +600,10 @@ either Celsius or Kelvin units).
    "strax(y)", "wind stress components from data", "N/m\ :math:`^2`"
    "strength", "ice strength", "N/m"
    "stress12", "internal ice stress, :math:`\sigma_{12}`", "N/m"
-   "stressm", "internal ice stress, :math:`\sigma_{11}-\sigma_{22}`", "N/m"
-   "stressp", "internal ice stress, :math:`\sigma_{11}+\sigma_{22}`", "N/m"
-   "strintx(y)", "divergence of internal ice stress, x(y)", "N/m\ :math:`^2`"
-   "strocnx(y)", "ice–ocean stress in the x(y)-direction (U-cell)", "N/m\ :math:`^2`"
+   "stressm", "internal ice stress, :math:`\sigma_{11}-\sigma_{22}` (:math:`\sigma_2` in the doc)", "N/m"
+   "stressp", "internal ice stress, :math:`\sigma_{11}+\sigma_{22}` (:math:`\sigma_1` in the doc)", "N/m"
+   "strintx(y)U", "divergence of internal ice stress, x(y)", "N/m\ :math:`^2`"
+   "strocnx(y)U", "ice–ocean stress in the x(y)-direction (U-cell)", "N/m\ :math:`^2`"
    "strocnx(y)T", "ice–ocean stress, x(y)-dir. (T-cell)", "N/m\ :math:`^2`"
    "strtltx(y)", "surface stress due to sea surface slope", "N/m\ :math:`^2`"
    "swv(n)dr(f)", "incoming shortwave radiation, visible (near IR), direct (diffuse)", "W/m\ :math:`^2`"

doc/source/conf.py

@@ -38,6 +38,9 @@
     'sphinxcontrib.bibtex',
 ]
 
+# Name of the bibliography file for sphinxcontrib.bibtex.
+bibtex_bibfiles = ['master_list.bib']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/source/science_guide/sg_dynamics.rst

@@ -356,8 +356,8 @@ Internal stress
 ***************
 
 For convenience we formulate the stress tensor :math:`\bf \sigma` in
-terms of :math:`\sigma_1=\sigma_{11}+\sigma_{22}`,
-:math:`\sigma_2=\sigma_{11}-\sigma_{22}`, and introduce the
+terms of :math:`\sigma_1=\sigma_{11}+\sigma_{22}` (``stressp``),
+:math:`\sigma_2=\sigma_{11}-\sigma_{22}` (``stressm``), and introduce the
 divergence, :math:`D_D`, and the horizontal tension and shearing
 strain rates, :math:`D_T` and :math:`D_S` respectively:
 
@@ -375,8 +375,16 @@ where
 .. math::
    \dot{\epsilon}_{ij} = {1\over 2}\left({{\partial u_i}\over{\partial x_j}} + {{\partial u_j}\over{\partial x_i}}\right)
 
-CICE can output the internal ice pressure which is an important field to support navigation in ice-infested water.
-The internal ice pressure (``sigP``) is the average of the normal stresses multiplied by :math:`-1` and 
+Note that :math:`\sigma_1` and :math:`\sigma_2` are not to be confused with the normalized principal stresses,
+:math:`\sigma_{n,1}` and :math:`\sigma_{n,2}` (``sig1`` and ``sig2``), which are defined as:
+
+.. math::
+   \sigma_{n,1}, \sigma_{n,2} = \frac{1}{P} \left( \frac{\sigma_1}{2} \pm \sqrt{\left(\frac{\sigma_2}{2}\right)^2 + \sigma_{12}^2} \right)
+
+where :math:`P` is the ice strength.
+
+In addition to the normalized principal stresses, CICE can output the internal ice pressure which is an important field to support navigation in ice-infested water.
+The internal ice pressure (``sigP``) is the average of the normal stresses (:math:`\sigma_{11}`, :math:`\sigma_{22}`) multiplied by :math:`-1` and
 is therefore simply equal to :math:`-\sigma_1/2`.
 
 Following the approach of :cite:`Konig10` (see also :cite:`Lemieux16`), the 

doc/source/user_guide/ug_implementation.rst

@@ -977,7 +977,7 @@ directory in **iceh\_ic.[timeID].nc(da)**. Several history variables are
 hard-coded for instantaneous output regardless of the ``hist_avg`` averaging flag, at
 the frequency given by their namelist flag.
 
-The normalized principal components of internal ice stress are computed
+The normalized principal components of internal ice stress (``sig1``, ``sig2``) are computed
 in *principal\_stress* and written to the history file. This calculation
 is not necessary for the simulation; principal stresses are merely
 computed for diagnostic purposes and included here for the user’s