Merge pull request #9 from jrscott/manual_edits

edits/restructure to manual, adding placeholders for all chapters

Author: jm-c

doc/auto_diff/auto_diff.rst

@@ -0,0 +1,3 @@
+Automatic Differentiation
+*************************
+

doc/contributing.rst renamed to doc/contributing/contributing.rst

@@ -25,7 +25,7 @@ To request a new feature, or guidance on how to implement it yourself, please op
 Using Git and Github
 ========================
 
-To contribute to the source code of the model you will need to fork the repository and place a pull request on GitHub. The two following sections describe this process in different levels of detail. If you are unfamiliar with git, you may wish to skip the quickstart guide and use the detailed instructions. All contributions are expected to conform with the :ref:`sec_code_style_guide`.
+To contribute to the source code of the model you will need to fork the repository and place a pull request on GitHub. The two following sections describe this process in different levels of detail. If you are unfamiliar with git, you may wish to skip the quickstart guide and use the detailed instructions. All contributions to the source code are expected to conform with the :ref:`sec_code_style_guide`. Contributions to the manual should follow the same procedure and conform with :numref:`contrib_manual`.
 
 
 Quickstart Guide
@@ -204,19 +204,15 @@ The MITgcm uses the continuous integration service Travis-CI to test code before
 
 **Detailed instructions or link to be added.**
 
+.. _contrib_manual:
 
 Contributing to the manual
 ==========================
 
-Whether you are correcting typos or describing currently undocumented packages, we welcome all contributions to the manual. The following information will help you make sure that your contribution is consistent with the style of the MITgcm documentation. (We know that not all of the current documentation follows these guidelines - we're working on it)
+Whether you are simply correcting typos or describing undocumented packages, we welcome all contributions to the manual. The following information will help you make sure that your contribution is consistent with the style of the MITgcm documentation. (We know that not all of the current documentation follows these guidelines - we're working on it)
 
-Once you've made your changes to the manual, you should build it locally to verify that it works as expected. To do this you will need a working python installation with the following modules installed (use :code:`pip install MODULE` in the terminal):
-
- - sphinx
- - sphinxcontrib-bibtex
- - sphinx_rtd_theme
-
-Then, run :code:`make html` in the :code:`docs` directory.
+The manual is written in **rst** format, which is short for ReStructuredText directives. rst offers many wonderful features: it automatically does much of the formatting for you, it is reasonably well documented on the web (e.g. primers available `here <http://www.sphinx-doc.org/en/stable/rest.html>`_ and
+`here <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), it can accept raw latex syntax and track equation labelling for you, in addition to numerous other useful features. On the down side however, it can be very fussy about formatting, requiring exact spacing and indenting, and seemingly innocuous things such as blank spaces at ends of lines can wreak havoc. We suggest looking at the existing rst files in the manual to see exactly how something is formatted, along with the syntax guidelines specified in this section, prior to writing and formatting your own manual text.
 
 
 Section headings
@@ -231,67 +227,109 @@ Section headings
 N.B. all underlinings should be the same length as the heading. If they are too short an error will be produced.
 
 
-Cross referencing
------------------
+Internal document references
+----------------------------
+
+rst allows internal referencing of figures, tables, section headings, and equations, i.e. clickable links that bring the reader to the respective figure etc. in the manual.
+To be referenced, a unique label is required. To reference figures, tables, or section headings by number,
+the rst (inline) directive is ``:numref:`LABELNAME```. For example, this syntax would write out ``Figure XX`` on a line. and when clicked, would relocate your position
+in the manual to figure XX.  Section Headings can also be referenced so that the name is written out instead of the section number, instead using this 
+directive ``:ref:`LABELNAME```.
+
+Equation references have a slightly different inline syntax: ``:eq:`LABELNAME``` will produce a clickable equation number reference,  surrounded by parentheses. 
 
-Labels go above the section they refer to, with the format ``.. _LABELNAME:``. The leading underscore is important.
+For instructions how to assign a label to tables and figures, see below. To label a section heading, labels go above the section they refer to, with the format ``.. _LABELNAME:``.
+Note the necessary leading underscore.
 
-To reference sections/figures/tables/equations by number use this format for the reference: ``:numref:`sec_eg_baro```
 
-To reference sections by name use this format: ``:ref:`sec_eg_baro```
+External references
+--------------------
 
+hyperlinks
+filelink
+varlink
 
-Maths
------
+Symbolic Notation
+-----------------
 
-Inline maths is done with ``:math:`LATEX_HERE```
+Inline math is done with ``:math:`LATEX_HERE```
 
 Separate equations, which will be typeset on their own lines, are produced with::
 
   .. math::
-      :label: eqn_label_here
+     LATEX_HERE
+     :label: EQN_LABEL_HERE
 
-      LATEX_HERE
 
+Labelled separate equations are assigned an equation number, which may be referenced elsewhere in the document (see :numref:`referencing`). Omitting the ``:label:`` above
+will still produce an equation on its own line, except without an equation label.
+Note that using using latex formatting ``\begin{aligned}`` ...  ``\end{aligned}`` across multiple lines of equations will not work in conjunction with unique equation labels for each separate line.
 
-.. _subsec_manual_style_guide:
 
+Figures and tables
+------------------
 
-Units
------
+provide example syntax of each
 
-Units should be typeset in normal text, and exponents added with the ``:sup:`` command. 
 
-::
+Other text blocks
+-----------------
 
-  100 N m\ :sup:`--2`
+To set several lines apart in an whitespace box, e.g. useful for showing lines in from a terminal session, rst uses ``::`` to set off a ‘literal block’.
+For example::
 
-If the exponent is negative use two dashes ``--`` to make the minus sign long enough. The backslash removes the space between the unit and the exponent.
+   ::
 
+       % unix_command_foo
+       % unix_command_fum 
 
 
 
-Describing subroutine inputs and outputs
-----------------------------------------
+A splashier way to outline a block, including a box label, is to employ what is termed in rst as an ‘admonition block’.
+In the manual these are used to show calling trees and for describing subroutine inputs and outputs. An example of 
+a subroutine input/output block is as follows:
 
-This information should go in an 'adominition' block. The source code to achieve this is:
 
-::
+.. admonition:: This is an admonition block showing subroutine in/out syntax
+   :class: note
 
-  .. admonition:: Subroutine
-    :class: note
+   |   .. admonition:: :filelink:`SUBROUTINE_NAME </model/src/subroutine_name.F>`
+   |     :class: note
+   | 
+   |     | :math:`var1` : **VAR1** ( :filelink:`WHERE_VAR1_DEFINED.h </model/inc/where_var1_defined.h>`)
+   |     | :math:`var2` : **VAR1** ( :filelink:`WHERE_VAR2_DEFINED.h </model/inc/where_var2_defined.h>` )
+   |     | :math:`var3` : **VAR1** ( :filelink:`WHERE_VAR3_DEFINED.h </model/inc/where_var3_defined.h>` )
 
-    S/R GMREDI_CALC_TENSOR (*pkg/gmredi/gmredi_calc_tensor.F*)
 
-    :math:`\sigma_x`: **SlopeX** (argument on entry)
 
-    :math:`\sigma_y`: **SlopeY** (argument on entry)
+An example of a calling tree syntax is :filelink:`here </doc/discrete_algorithm/discret_algorithm.rst>`.
 
-    :math:`\sigma_z`: **SlopeY** (argument)
 
-    :math:`S_x`: **SlopeX** (argument on exit)
 
-    :math:`S_y`: **SlopeY** (argument on exit)
+
+.. _subsec_manual_style_guide:
+
+
+Other style conventions
+-----------------------
+
+double quotes for inline literal computer output, variables, typing etc.
+how to break up into smaller files
+probably want to add more to this subsection; maybe add another subsection “other useful rst syntax”
+
+
+Building the manual
+-------------------
+
+Once you've made your changes to the manual, you should build it locally to verify that it works as expected. To do this you will need a working python installation with the following modules installed (use :code:`pip install MODULE` in the terminal):
+
+ - sphinx
+ - sphinxcontrib-bibtex
+ - sphinx_rtd_theme
+
+Then, run :code:`make html` in the :code:`docs` directory.
+
+
 
 .. _sec_pullreq:
 
@@ -332,3 +370,40 @@ and switch to the desired branch
 You now have a local copy of the code from the pull request and can run tests locally. If you have write access to the main repository you can push fixes or changes directly to the pull request.
 
 None of these steps, apart from pushing fixes back to the pull request, require write access to either the main repository or the repository of the person proposing the pull request. This means that anyone can review pull requests. However, unless you are one of the core developers you won't be able to directly push changes. You will instead have to make a comment describing any problems you find.
+
+
+Old Stuff to remove:
+
+Units should be typeset in normal text, and exponents added with the ``:sup:`` command. 
+
+::
+
+  100 N m\ :sup:`--2`
+
+If the exponent is negative use two dashes ``--`` to make the minus sign long enough. The backslash removes the space between the unit and the exponent.
+
+
+
+
+Describing subroutine inputs and outputs
+----------------------------------------
+
+This information should go in an 'adminition' block. The source code to achieve this is:
+
+::
+
+  .. admonition:: Subroutine
+    :class: note
+
+    S/R GMREDI_CALC_TENSOR (*pkg/gmredi/gmredi_calc_tensor.F*)
+
+    :math:`\sigma_x`: **SlopeX** (argument on entry)
+
+    :math:`\sigma_y`: **SlopeY** (argument on entry)
+
+    :math:`\sigma_z`: **SlopeY** (argument)
+
+    :math:`S_x`: **SlopeX** (argument on exit)
+
+    :math:`S_y`: **SlopeY** (argument on exit)
+

doc/figs/git_setup.ai renamed to doc/contributing/figs/git_setup.ai

@@ -0,0 +1,40 @@
+C grid staggering of variables
+------------------------------
+
+The basic algorithm employed for stepping forward the momentum equations
+is based on retaining non-divergence of the flow at all times. This is
+most naturally done if the components of flow are staggered in space in
+the form of an Arakawa C grid (Arakawa and Lamb, 1977 :cite:`arakawa:77`).
+
+:numref:`cgrid3d` shows the components of flow
+(:math:`u`,\ :math:`v`,\ :math:`w`) staggered in space such that the
+zonal component falls on the interface between continuity cells in the
+zonal direction. Similarly for the meridional and vertical directions.
+The continuity cell is synonymous with tracer cells (they are one and
+the same).
+
+  .. figure:: figs/cgrid3d.*
+    :width: 60%
+    :align: center
+    :alt: cgrid3d
+    :name: cgrid3d
+
+    Three dimensional staggering of velocity components. This facilitates the natural discretization of the continuity and tracer equations.
+
+Grid initialization and data
+----------------------------
+
+Initialization of grid data is controlled by subroutine :filelink:`INI_GRID <model/src/ini_grid.F>`
+which in calls :filelink:`INI_VERTICAL_GRID <model/src/ini_vertical_grid.F>` to initialize the vertical grid,
+and then either of :filelink:`INI_CARTESIAN_GRID <model/src/ini_cartesian_grid.F>`,
+:filelink:`INI_SPHERICAL_POLAR_GRID <model/src/ini_spherical_polar_grid.F>`
+or :filelink:`INI_CURVILINEAR_GRID <model/src/ini_curvilinear_grid.F>` to initialize the horizontal grid for
+cartesian, spherical-polar or curvilinear coordinates respectively.
+
+The reciprocals of all grid quantities are pre-calculated and this is
+done in subroutine :filelink:`INI_MASKS_ETC <model/src/ini_masks_etc.F>` which is called later by subroutine
+:filelink:`INITIALISE_FIXED <model/src/initialise_fixed.F>`.
+
+All grid descriptors are global arrays and stored in common blocks in
+:filelink:`GRID.h <model/inc/GRID.h>` and a generally declared as ``_RS``.
+

doc/figs/git_setup.pdf renamed to doc/contributing/figs/git_setup.pdf

@@ -0,0 +1,101 @@
+.. _crank-nicolson_baro:
+
+Crank-Nicolson barotropic time stepping
+---------------------------------------
+
+The full implicit time stepping described previously is
+unconditionally stable but damps the fast gravity waves, resulting in
+a loss of potential energy. The modification presented now allows one
+to combine an implicit part (:math:`\beta,\gamma`) and an explicit
+part (:math:`1-\beta,1-\gamma`) for the surface pressure gradient
+(:math:`\beta`) and for the barotropic flow divergence
+(:math:`\gamma`). For instance, :math:`\beta=\gamma=1` is the previous fully implicit
+scheme; :math:`\beta=\gamma=1/2` is the non damping (energy
+conserving), unconditionally stable, Crank-Nicolson scheme;
+:math:`(\beta,\gamma)=(1,0)` or :math:`=(0,1)` corresponds to the
+forward - backward scheme that conserves energy but is only stable for
+small time steps. In the code, :math:`\beta,\gamma` are defined as parameters,
+respectively :varlink:`implicSurfPress`, :varlink:`implicDiv2DFlow`. They are read
+from the main parameter file ``data`` (namelist ``PARM01``) and are set
+by default to 1,1.
+
+Equations :eq:`ustar-backward-free-surface` –
+:eq:`vn+1-backward-free-surface` are modified as follows:
+
+.. math::
+   \frac{ \vec{\bf v}^{n+1} }{ \Delta t }
+   + {\bf \nabla}_h b_s [ \beta {\eta}^{n+1} + (1-\beta) {\eta}^{n} ]
+   + \epsilon_{nh} {\bf \nabla}_h {\phi'_{nh}}^{n+1}
+   = \frac{ \vec{\bf v}^{n} }{ \Delta t }
+   + \vec{\bf G}_{\vec{\bf v}} ^{(n+1/2)}
+   + {\bf \nabla}_h {\phi'_{hyd}}^{(n+1/2)}
+
+.. math::
+   \epsilon_{fs} \frac{ {\eta}^{n+1} - {\eta}^{n} }{ \Delta t}
+   + {\bf \nabla}_h \cdot \int_{R_{fixed}}^{R_o}
+   [ \gamma \vec{\bf v}^{n+1} + (1-\gamma) \vec{\bf v}^{n}] dr
+   = \epsilon_{fw} (P-E)
+   :label: eta-n+1-CrankNick
+
+We set
+
+.. math::
+     \begin{aligned}
+     \vec{\bf v}^* & = &
+     \vec{\bf v} ^{n} + \Delta t \vec{\bf G}_{\vec{\bf v}} ^{(n+1/2)}
+     + (\beta-1) \Delta t {\bf \nabla}_h b_s {\eta}^{n}
+     + \Delta t {\bf \nabla}_h {\phi'_{hyd}}^{(n+1/2)}
+     \\
+     {\eta}^* & = &
+     \epsilon_{fs} {\eta}^{n} + \epsilon_{fw} \Delta t (P-E)
+     - \Delta t {\bf \nabla}_h \cdot \int_{R_{fixed}}^{R_o}
+     [ \gamma \vec{\bf v}^* + (1-\gamma) \vec{\bf v}^{n}] dr\end{aligned}
+
+In the hydrostatic case :math:`\epsilon_{nh}=0`, allowing us to find
+:math:`{\eta}^{n+1}`, thus:
+
+.. math::
+     \epsilon_{fs} {\eta}^{n+1} -
+     {\bf \nabla}_h \cdot \beta\gamma \Delta t^2 b_s (R_o - R_{fixed})
+     {\bf \nabla}_h {\eta}^{n+1}
+     = {\eta}^*
+
+and then to compute (:filelink:`CORRECTION_STEP <model/src/correction_step.F>`):
+
+.. math::
+     \vec{\bf v}^{n+1} = \vec{\bf v}^{*}
+     - \beta \Delta t {\bf \nabla}_h b_s {\eta}^{n+1}
+
+Notes:
+
+#. The RHS term of equation :eq:`eta-n+1-CrankNick` corresponds the
+   contribution of fresh water flux (P-E) to the free-surface variations
+   (:math:`\epsilon_{fw}=1`, :varlink:`useRealFreshWaterFlux` =.TRUE. in parameter
+   file ``data``). In order to remain consistent with the tracer equation,
+   specially in the non-linear free-surface formulation, this term is
+   also affected by the Crank-Nicolson time stepping. The RHS reads:
+   :math:`\epsilon_{fw} ( \gamma (P-E)^{n+1/2} + (1-\gamma) (P-E)^{n-1/2} )`
+ 
+
+#. The stability criteria with Crank-Nicolson time stepping for the pure
+   linear gravity wave problem in cartesian coordinates is:
+
+   -  :math:`\beta + \gamma < 1` : unstable
+
+   -  :math:`\beta \geq 1/2` and :math:`\gamma \geq 1/2` : stable
+
+   -  :math:`\beta + \gamma \geq 1` : stable if :math:`c_{max}^2 (\beta - 1/2)(\gamma - 1/2) + 1 \geq 0`
+      with :math:`c_{max} = 2 \Delta t \sqrt{gH} \sqrt{ \frac{1}{\Delta x^2} + \frac{1}{\Delta y^2} }`
+
+
+#. A similar mixed forward/backward time-stepping is also available for
+   the non-hydrostatic algorithm, with a fraction :math:`\beta_{nh}`
+   (:math:`0 < \beta_{nh} \leq 1`) of the non-hydrostatic pressure
+   gradient being evaluated at time step :math:`n+1` (backward in time)
+   and the remaining part (:math:`1 - \beta_{nh}`) being evaluated at
+   time step :math:`n` (forward in time). The run-time parameter
+   :varlink:`implicitNHPress` corresponding to the implicit fraction
+   :math:`\beta_{nh}` of the non-hydrostatic pressure is set by default
+   to the implicit fraction :math:`\beta` of surface pressure
+   (:varlink:`implicSurfPress`), but can also be specified independently (in
+   main parameter file ``data``, namelist ``PARM01``).