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.

doc/source/cice_index.rst

@@ -620,7 +620,7 @@ 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."
@@ -661,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/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