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

[phil-blain]

PR checklist

• Suggest PR reviewers from list in the column to the right.
• Please copy the PR test results link or provide a summary of testing completed below.
  Did not run a whole test suite as it does not change the results. I tested that sigP has the correct units in the history files.
• How much do the PR code changes differ from the unmodified code?
  • bit for bit
  • different at roundoff level
  • more substantial
• Does this PR create or have dependencies on Icepack or any other models?
  • Yes
  • No
• Does this PR update the Icepack submodule? If so, the Icepack submodule must point to a hash on Icepack's main branch.
  • Yes
  • No
• Does this PR add any new test cases?
  • Yes
  • No
• Is the documentation being updated? ("Documentation" includes information on the wiki or in the .rst files from doc/source/, which are used to create the online technical docs at https://readthedocs.org/projects/cice-consortium-cice/. A test build of the technical docs will be performed as part of the PR testing.)
  • Yes
  • No, does the documentation need to be updated at a later time?
    • Yes
    • No
• Please provide any additional information or relevant details below:

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]

[dabail10]

I guess I had always assumed that sigP was unitless like sig1 and sig2. Good catch.

[eclare108213]

The confusion might have originated with this statement in the sg_dynamics.rst doc (or maybe this statement is also a symptom):

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 -1 and is therefore simply equal to -\sigma_1/2.

"normal" does not mean "normalized" here, I think, but that's how I initially read it.
Could this bit of documentation be rephrased to be more clear?

[phil-blain]

Indeed, normal does not mean normalized there, that's my understanding. Maybe just referencing the variables sigma_11, sigma_22 already introduced above in the text would help lessen the confusion ? something like this:

diff --git a/./doc/source/science_guide/sg_dynamics.rst b/./doc/source/science_guide/sg_dynamics.rst
index 6b269d4..2135048 100644
--- a/./doc/source/science_guide/sg_dynamics.rst
+++ b/./doc/source/science_guide/sg_dynamics.rst
@@ -450,45 +450,45 @@ 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
 divergence, :math:`D_D`, and the horizontal tension and shearing
 strain rates, :math:`D_T` and :math:`D_S` respectively:

 .. math::
    D_D = \dot{\epsilon}_{11} + \dot{\epsilon}_{22},

 .. math::
    D_T = \dot{\epsilon}_{11} - \dot{\epsilon}_{22},

 .. math::
    D_S = 2\dot{\epsilon}_{12},

 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
+The internal ice pressure (``sigP``) is the average of the normal stresses (:math:`\sigma_{11}, \sigma_{22}`) multiplied by :math:`-1` and
 is therefore simply equal to :math:`-\sigma_1/2`.

@JFLemieux73 what do you think?

[phil-blain]

I just pushed a new version, here is the range-diff:

$ git range-diff  @{u}  3259e4 HEAD
-:  ------- > 1:  9b42771 doc/source/conf.py: adjust for sphinxcontrib.bibtex 2.0
1:  3259e46 ! 2:  59dbdc2 ice_history: correct units for 'sigP'
    @@ doc/source/cice_index.rst: either Celsius or Kelvin units).  Deprecated paramete
         "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)", ""
    -+   "sigP", "internal ice pressure", ""
    ++   "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"
-:  ------- > 3:  7b3ef24 doc: clarify stress variables

The first commit was needed to build the documentation locally. The 3rd commit tries to make the documentation clearer. Hopefully this addresses your comment, @eclare108213 :)

[eclare108213]

Awesome, thanks!