Merge branch 'master' of https://github.com/altMITgcm/MITgcm into manual_edits

Author: jrscott

doc/_extensions/mitgcm.py

@@ -1,10 +1,71 @@
-from docutils import nodes
+"""
+Sphinx extension for the MITgcm documentation
+
+Provides two custom roles:
+
+:filelink:`path/to/file`
+  inserts a link to the file on github.  The full path will be shown unless an
+  explicit title is given as in :filelink:`title <path/to/file>` or the path is
+  prefixed with a tilde, :filelink:`~path/to/file`, in which case only the last
+  path component (file) is shown.
+
+:varlink:`identifier`
+  inserts a link to a code search based on lxr.
+
+Slightly modified from http://protips.readthedocs.io/link-roles.html.
+"""
+
+from docutils import nodes, utils
+
+from sphinx.util.nodes import split_explicit_title
+
 
 def setup(app):
-    app.add_role('filelink', autolink('https://github.com/altMITgcm/MITgcm/blob/master/%s'))
-    app.add_role('varlink', autolink('http://mitgcm.org/lxr/ident/MITgcm?_i=%s'))
+    app.add_role(
+        'filelink',
+        filelink('https://github.com/altMITgcm/MITgcm/blob/master/%s'))
+    app.add_role(
+        'varlink',
+        autolink('http://mitgcm.org/lxr/ident/MITgcm?_i=%s'))
+
+def filelink(pattern):
+    """
+    Return a role processor for external links to files based on a URL pattern.
+
+    %s in *pattern* will be replaced by the role text, a file path, with two
+    modifications:
+
+    - an explicit title can be specified as for internal sphinx cross
+      references: :role:`title <target>` will display *title* but link to a URL
+      formed from *target*.
+    - if the role text is prefixed with ~, only the last path component will be
+      displayed: :role:`~path/to/file` will display *file* but link to
+      path/to/file.
+    """
+    def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+        # extract explicit title if provided
+        text = utils.unescape(text)
+        has_explicit_title, title, part = split_explicit_title(text)
+        # if not, check for initial tilde
+        if not has_explicit_title and part[:1] == '~':
+            # remove it
+            part = part[1:]
+            # and extract last path component
+            title = part.split('/')[-1]
+        # form link target
+        url = pattern % (part,)
+        # make link node
+        node = nodes.reference(rawtext, title, refuri=url, **options)
+        # and return it (no messages)
+        return [node], []
+    return role
 
 def autolink(pattern):
+    """
+    Return a role processor for external links based on a URL pattern.
+
+    %s in *pattern* will be replaced by the role text.
+    """
     def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
         url = pattern % (text,)
         node = nodes.reference(rawtext, text, refuri=url, **options)

doc/conf.py

@@ -142,7 +142,13 @@
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-    'preamble': '\setcounter{secnumdepth}{3}',
+    'preamble': r'''
+    \setcounter{secnumdepth}{3}
+    \newcommand{\p}[1]{\frac{\partial }{\partial #1}}
+    \newcommand{\pp}[2]{\frac{\partial #1}{\partial #2}}
+    \newcommand{\dd}[2]{\frac{d #1}{d #2}}
+    \newcommand{\h}{\frac{1}{2}}
+    ''',
 
     # Latex figure (float) alignment
     #

doc/defs.hrst

@@ -0,0 +1,6 @@
+.. only:: html
+
+    :math:`\newcommand{\p}[1]{\frac{\partial }{\partial #1}}`
+    :math:`\newcommand{\pp}[2]{\frac{\partial #1}{\partial #2}}`
+    :math:`\newcommand{\dd}[2]{\frac{d #1}{d #2}}`
+    :math:`\newcommand{\h}{\frac{1}{2}}`

doc/phys_pkgs/exf.rst

@@ -124,7 +124,7 @@ General flags and parameters
     +-------------------------+------------------+-------------------------------------------------------------------------------+
     | twoDigitYear            | :code:`.FALSE.`  | instead of appending ``_YYYY`` append  ``YY``                                 |
     +-------------------------+------------------+-------------------------------------------------------------------------------+
-    | repeatPeriod            | 0.0              | :math:`\gt` 0: cycle through all input fields at the same period (in seconds) |
+    | repeatPeriod            | 0.0              | > 0: cycle through all input fields at the same period (in seconds) |
     +                         +                  +-------------------------------------------------------------------------------+
     |                         |                  | = 0: use period assigned to each field                                        |
     +-------------------------+------------------+-------------------------------------------------------------------------------+

doc/phys_pkgs/fizhi.rst

@@ -1,3 +1,5 @@
+.. include:: ../defs.hrst
+
 .. _sub_phys_pkg_fizhi:
 
 Fizhi: High-end Atmospheric Physics

doc/phys_pkgs/gmredi.rst

@@ -443,7 +443,7 @@ The LDD97 tapering scheme is activated in the model by setting
 **GM\_taper\_scheme = ’ldd97’** in *data.gmredi*.
 
 
-.. figure:: figure_missing
+.. figure::
     :width: 70%
     :align: center
     :alt: Mixed layer depth with GM

doc/phys_pkgs/kl10.rst

@@ -29,9 +29,9 @@ with the strength of the turbulence :math:`\epsilon`, and the
 stratification :math:`N`, as
 
 .. math::
+   :label: eq-pkg-kl10-Lo
 
-   \label{eq:pkg:kl10:Lo}
-     L_O^2 \approx \epsilon N^{-3}.
+   L_O^2 \approx \epsilon N^{-3}.
 
 The Osborn relation relates the strength of the dissipation to the
 vertical diffusivity as

doc/phys_pkgs/seaice.rst

@@ -374,7 +374,7 @@ The momentum equation of the sea-ice model is
    :label: eq_momseaice
 	   
      m \frac{D\mathbf{u}}{Dt} = -mf\mathbf{k}\times\mathbf{u} +
-     \mathbf{\tau}_{air} + \mathbf\tau}_{ocean}
+     \mathbf{\tau}_{air} + \mathbf{\tau}_{ocean}
      - m \nabla{\phi(0)} + \mathbf{F},
 
 where :math:`m=m_{i}+m_{s}` is the ice and snow mass per unit area;
@@ -448,9 +448,9 @@ depends on both thickness :math:`h` and compactness (concentration)
 :math:`c`:
 
 .. math::
+   :label: eq_icestrength
 
    P_{\max} = P^{*}c\,h\,\exp\{-C^{*}\cdot(1-c)\},
-   \label{eq:icestrength}
 
 with the constants :math:`P^{*}` (run-time parameter ``SEAICE_strength``) and
 :math:`C^{*}=20`. The nonlinear bulk and shear viscosities :math:`\eta`
@@ -487,8 +487,8 @@ Defining the CPP-flag ``SEAICE_ZETA_SMOOTHREG`` in ``SEAICE_OPTIONS.h`` before c
 bounding :math:`\zeta` by a smooth (differentiable) expression:
 
 .. math::
+   :label: eq_zetaregsmooth
 
-   \label{eq:zetaregsmooth}
      \begin{split}
      \zeta &= \zeta_{\max}\tanh\left(\frac{P}{2\,\min(\Delta,\Delta_{\min})
          \,\zeta_{\max}}\right)\\
@@ -693,17 +693,22 @@ shearing strain rates, :math:`D_T =
 the equations :eq:`eq_evpequation` can be written as:
 
 .. math::
+     :label: eq_evpstresstensor1
 
-   \begin{aligned}
-     \label{eq:evpstresstensor1}
      \frac{\partial\sigma_{1}}{\partial{t}} + \frac{\sigma_{1}}{2T} +
-     \frac{P}{2T} &= \frac{P}{2T\Delta} D_D \\
-     \label{eq:evpstresstensor2}
+     \frac{P}{2T} &= \frac{P}{2T\Delta} D_D
+
+.. math::
+     :label: eq_evpstresstensor2
+
      \frac{\partial\sigma_{2}}{\partial{t}} + \frac{\sigma_{2} e^{2}}{2T}
-     &= \frac{P}{2T\Delta} D_T \\
-     \label{eq:evpstresstensor12}
+     &= \frac{P}{2T\Delta} D_T
+
+.. math::
+     :label: eq_evpstresstensor12
+
      \frac{\partial\sigma_{12}}{\partial{t}} + \frac{\sigma_{12} e^{2}}{2T}
-     &= \frac{P}{4T\Delta} D_S \end{aligned}
+     &= \frac{P}{4T\Delta} D_S
 
 Here, the elastic parameter :math:`E` is redefined in terms of a damping
 timescale :math:`T` for elastic waves
@@ -751,17 +756,19 @@ terminology of , the evolution equations of stress :math:`\sigma_{ij}`
 and momentum :math:`\mathbf{u}` can be written as:
 
 .. math::
+     :label: eq_evpstarsigma
 
-   \begin{aligned}
-     \label{eq:evpstarsigma}
      \sigma_{ij}^{p+1}&=\sigma_{ij}^p+\frac{1}{\alpha}
      \Big(\sigma_{ij}(\mathbf{u}^p)-\sigma_{ij}^p\Big),
-     \phantom{\int}\\
-     \label{eq:evpstarmom}
+     \phantom{\int}
+
+.. math::
+     :label: eq_evpstarmom
+
      \mathbf{u}^{p+1}&=\mathbf{u}^p+\frac{1}{\beta}
      \Big(\frac{\Delta t}{m}\nabla \cdot{\bf \sigma}^{p+1}+
      \frac{\Delta t}{m}\mathbf{R}^{p}+\mathbf{u}_n
-     -\mathbf{u}^p\Big).\end{aligned}
+     -\mathbf{u}^p\Big).
 
 :math:`\mathbf{R}` contains all terms in the momentum equations except
 for the rheology terms and the time derivative; :math:`\alpha` and
@@ -782,8 +789,8 @@ Another variant is the aEVP scheme :cite:`kimmritz16`, where the value
 of :math:`\alpha` is set dynamically based on the stability criterion
 
 .. math::
+   :label: eq_aevpalpha
 
-   \label{eq:aevpalpha}
      \alpha = \beta = \max\left( \tilde{c}\pi\sqrt{c \frac{\zeta}{A_{c}}
        \frac{\Delta{t}}{\max(m,10^{-4}\text{\,kg})}},\alpha_{\min} \right)
 
@@ -805,8 +812,8 @@ Truncated ellipse method (TEM) for yield curve
 In the so-called truncated ellipse method the shear viscosity :math:`\eta` is capped to suppress any tensile stress:
 
 .. math::
+   :label: eq_etatem
 
-   \label{eq:etatem}
      \eta = \min\left(\frac{\zeta}{e^2},
      \frac{\frac{P}{2}-\zeta(\dot{\epsilon}_{11}+\dot{\epsilon}_{22})}
      {\sqrt{\max(\Delta_{\min}^{2},(\dot{\epsilon}_{11}-\dot{\epsilon}_{22})^2
@@ -1085,8 +1092,8 @@ concentration :math:`c` and effective snow thickness
 (:math:`c\cdot{h}_{s}`) are advected by ice velocities:
 
 .. math::
+   :label: eq_advection
 
-   \label{eq:advection}
      \frac{\partial{X}}{\partial{t}} = - \nabla\cdot\left({{\vec{\mathbf{u}}}}\,X\right) +
      \Gamma_{X} + D_{X}