doc, ice_history: correct units for 'sigP' and improve doc for stress…

… variables (CICE-Consortium#817)

* doc/source/conf.py: adjust for sphinxcontrib.bibtex 2.0

The sphinxcontrib.bibtex Sphinx extension used for the bibliography now
wants the bibliography file to be configured in the Sphinx configuration
file (conf.py) instead of in the source file where the bibliography is
included. This is new in sphinxcontrib.bibtex 2.0 [1], so let's do that.

Keeping the filename also in zreferences.rst does not hurt and lets us
stay compatible with earlier versions of sphinxcontrib.bibtex, so let's
keep it there also.

[1] https://sphinxcontrib-bibtex.readthedocs.io/en/latest/changes.html#id5

* ice_history: correct units for 'sigP'

The intenal ice pressure 'sigP' is is units of N/m, as can be seen in
ice_dyn_shared::principal_stress. However, the corresponding history
variable is wrongly defined in ice_history::init_hist with unit '1'
(dimensionless). This means the wrong unit is written to the NetCDF
history output. This dates back to the introduction of that variable in
6ed2359 (Added pressure, modified norm of principal stresses and made
small modifs to basal stress following Till's comments, 2018-03-02).

Fix the unit. While at it, add an entry for 'sigP' in the index, from
which this variable is missing.

Reported-by: Frederic Dupont <[email protected]>
Reported-by: Jean-Francois Lemieux <[email protected]>

* doc: clarify stress variables

Try to make the doc a little less confusing by cross-referencing the
code variables used for stress computations with the corresponding
variables in the science guide a little bit more, and vice-versa:

- mention the doc variables sigma_1, sigma_2 in the index entries for
stressp, stressm
- mention the code variables stressp, stressm when the doc variables
sigma_1, sigma_2 are introduced
- introduce new doc variables sigma_n,1 and sigma_n,2 to denote the
normalized principal stresses, and add the equation for those. This
allows mentioning that they are normalized by the ice strength, which
was not mentioned elsewhere.
- mention these new doc variables in the index entry for sig1, sig2
- refer to the normal stress sigma_11, sigma_22 by their variable names
when mentioning them in the sentence that introduces the ice pressure
- mention the code variables sig1, sig2 in the "Implementation" part of
the user guide when mentioning the 'principal_stresses' subroutine.

Helped-by: Jean-Francois Lemieux <[email protected]>

(cherry picked from commit 0fcc140)

Cherry-pick related notes:
- We get a conflict in cice_index.rst due to the additional 'U' at the
end of strintx(y)U and strocnx(y)U. Let's keep those lines as they are
upstream in order to minimize potential conflicts in the future. I'm not
sure this is actually the best way to go, but we'll see how this goes.
- After rebasing, it turns out this was a good decision!

cicecore/cicedyn/analysis/ice_history.F90

@@ -1323,7 +1323,7 @@ subroutine init_hist (dt)
              "sig2 is instantaneous" // trim(description), c1, c0, &
              ns1, f_sig2)
 
-         call define_hist_field(n_sigP,"sigP","1",gridstr2d, gridstr, &
+         call define_hist_field(n_sigP,"sigP","N/m",gridstr2d, gridstr, &
              "ice pressure",                       &
              "sigP is instantaneous" // trim(description), c1, c0, &
              ns1, f_sigP)

doc/source/cice_index.rst

@@ -620,7 +620,8 @@ either Celsius or Kelvin units).  Deprecated parameters are listed at the end.
    "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"
@@ -660,8 +661,8 @@ either Celsius or Kelvin units).  Deprecated parameters are listed at the end.
    "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"
+   "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`"

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

@@ -449,8 +449,8 @@ Rheology
 ********
 
 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:
 
@@ -468,8 +468,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`.
 
 .. _stress-vp:

doc/source/user_guide/ug_implementation.rst

@@ -1207,7 +1207,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