general revision of sphinx documentation (#8)

- move the directory tree depiction to a separate file (eccov4r2_dirtree.rst) which is now included inside of downloads.rst (rather than runs.rst) after eccov4r2_setup.rst - revise eccov4r2_setup.rst (download instructions) and the beginning of runs.rst - Clean-up "Re-Run Other Solutions" and add reference to O. Wang's release 3 directions. - Move sections 2.1 & 2.2 to separate rst files (eccov4r2_output.rst & eccov4r2_setup.rst) - Clean-up the tools section and add reference to I. Fenty's python tutorial.
gaelforget · Feb 6, 2018 · 84b4ca8 · 84b4ca8
1 parent d0ddd52
commit 84b4ca8
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 94 deletions.
diff --git a/docs/downloads.rst b/docs/downloads.rst
@@ -16,76 +16,61 @@ additional resources (:numref:`other-resources`).
 The Release 2 Solution
 ----------------------
 
-The ECCO v4 r2 state estimate output is permanently archived within the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2>`__ that provides citable identifiers for the various datasets as reported in this `README.pdf <https://dataverse.harvard.edu/api/access/datafile/2863409>`__. For download purposes, the ECCO v4 r2 output is also made available via this `ftp
-server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ by the `ECCO Consortium <http://ecco-group.org>`__. The various directory contents are summarized in this `README <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/README>`__ and specific details are provided in each subdirectory’s README. Under Linux or macOS for instance, a simple download method consists in using ``wget`` at the command line by typing
-
-::
-
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_grid
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_climatology
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_monthly
-
-and similarly for the other directories. The ``nctiles_`` directory prefix indicates that contents are provided on the native LLC90 grid in the nctiles format :cite:`for-eta:15` which can be read in `Matlab` using the `gcmfaces` toolbox (see :numref:`download-analysis`). Alternatively users can download interpolated fields, on a :math:`1/2\times1/2^\circ` grid in the netcdf format, from the ``interp_*`` directories. The ``input_*`` directories contain binary and netcdf input files that can be read by `MITgcm` (:numref:`download-setup` and :numref:`eccov4-baseline`). The ``profiles/`` directory (`see ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/profiles/>`_) additionally contains the MITprof collections of collocated in situ and state estimate profiles in `netcdf` format :cite:`for-eta:15`.
+.. include:: eccov4r2_output.rst
 
 .. _download-setup:
 
 The Release 2 Setup
 -------------------
 
-To :ref:`baseline` the solution and :ref:`testreportecco` in :numref:`eccov4-baseline`, user wants to install the following components. First, install the `MITgcm` either by downloading a copy from `this github repository <https://github.com/MITgcm/MITgcm/>`__. Second, create a subdirectory called ``MITgcm/mysetups/`` and download the model setup there from `this github
-repository <https://github.com/gaelforget/ECCO_v4_r2/>`__ by typing:
+.. include:: eccov4r2_setup.rst
 
-::
-
-    git clone https://github.com/MITgcm/MITgcm
-    mkdir MITgcm/mysetups
-    mv ECCO_v4_r2 MITgcm/mysetups/.
-    cd MITgcm/mysetups
-    git clone https://github.com/gaelforget/ECCO_v4_r2    
+The :ref:`mitgcmdirs` is shown below. While organizing the downloaded directories differently is certainly possible, the :numref:`eccov4-baseline` instructions to :ref:`baseline` the model and :ref:`testreportecco` are based on this organization.
 
-Third, download the model input forcing fields (96G of 6-hourly fields in ECCO v4 r2), initial condition, grid, etc. input (610M), and observational input data (25G) either from the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2inputs>`__ permanent archive or from the `ECCO ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ as follows:
 
-::
+.. _mitgcmdirs:
 
-    cd MITgcm/mysetups/ECCO_v4_r2
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing/
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_init/
-    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco/
-    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing forcing_baseline2
-    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco inputs_baseline2
-    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_init inputs_baseline2/.
+.. rubric:: Recommended Directory Organization
 
-Downloaded directories should be organized as shown under :ref:`mitgcmdirs` for use in :numref:`eccov4-baseline`. Experienced users should feel free to re-organize directories assuming that they are comfortable with modifying the :numref:`eccov4-baseline` instructions accordingly.
+.. include:: eccov4r2_dirtree.rst
 
 .. _download-analysis:
 
-Matlab Analysis Tools
----------------------
+The Gcmfaces Toolbox
+--------------------
 
-`Matlab` tools are provided to analyze model output one it has been downloaded (:numref:`download-solution`) or generated by user (:numref:`eccov4-baseline`) include the `gcmfaces <https://github.com/gaelforget/gcmfaces>`__ toolbox :cite:`for-eta:15`. It is typically installed by typing 
-::
+The `gcmfaces` toolbox :cite:`for-eta:15` can be used to analyze model output that has either been downloaded (:numref:`download-solution`) or reproduced (:numref:`eccov4-baseline`) by user. Matlab and Octave implementations are available in `this repository <https://github.com/gaelforget/gcmfaces>`__. They can be installed by typing, at the command line, either
+
+:: 
 
     git clone https://github.com/gaelforget/gcmfaces
 
-and can be used, for example, to re-generate the ECCO v4 standard analysis (i.e., the plots included in :cite:`dspace-eccov4r2` for ECCO v4 r2) from the released model output (:numref:`download-solution`) or from the plain, binary, model output (:numref:`eccov4-baseline`). Documentation for `gcmfaces` is provided in the `github repository <https://github.com/gaelforget/gcmfaces>`__.
+or
+
+::
+
+    git clone -b octave https://github.com/gaelforget/gcmfaces
+
+It can be used, for example, to reproduce the ECCO v4 standard analysis (i.e., the plots included in :cite:`dspace-eccov4r2` for ECCO v4 r2) from the released model output (:numref:`download-solution`) or from the plain, binary, model output (:numref:`eccov4-baseline`). Documentation for `gcmfaces` is provided in the `github repository <https://github.com/gaelforget/gcmfaces>`__.
 
 
 .. _other-resources:
 
 Other Resources
 ---------------
 
--  The ECCO v4 r2 state estimate can also be downloaded and analyzed via the `NASA` `Sea Level Change Portal <https://sealevel.nasa.gov>`__ tools (interpolated fields) and the `Harvard Dataverse <https://dataverse.harvard.edu>`__ APIs (native grid input and output).
-
--  A series of three presentations offered in May 2016 during the `ECCO` meeting at `MIT` provide an overview of the ECCO v4 r2 data sets and applications are available via researchgate.net
+-  A series of three presentations given at the May 2016 `MIT` ECCO meeting provides an overview of the ECCO v4 data sets and applications
    (`Overview <http://doi.org/10.13140/RG.2.2.33361.12647>`__;
    `Processes <http://doi.org/10.13140/RG.2.2.26650.24001>`__;
    `Tracers <http://doi.org/10.13140/RG.2.2.36716.56967>`__).
 
--  `netcdf` enabled software such as `Panoply <http://www.giss.nasa.gov/tools/panoply/>`__ can be used to read the interpolated output (``interp_*`` directories) under `MS-Windows`, `Linux`, or `macOS`.
+-  Various Python tools are available for analysis purposes (see `this Python tutorial <https://github.com/ECCO-GROUP/ECCO-v4-Python-Tutorial>`__).
+
+-  Any `netcdf` enabled software such as `Panoply <http://www.giss.nasa.gov/tools/panoply/>`__ (available for `MS-Windows`, `Linux`, or `macOS`) can be used to plot the interpolated output (``interp_*`` directories).
+
+-  The stand-alone `eccov4_lonlat.m <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/doc/eccov4_lonlat.m>`__ `Matlab` script can alternatively be used to extract the lat-lon sector, which spans the 69S to 56N latitude range, of native grid fields :cite:`for-eta:15`.
 
--  `xmitgcm <https://github.com/xgcm/xmitgcm>`__ provides a `python` alternative to using `Matlab` and `gcmfaces <https://github.com/gaelforget/gcmfaces>`__.
+-  The MITgcm ``utils/`` directory provides basic `Matlab` and `Python` functionalities.
 
--  ``MITgcm/utils/`` provides basic `Matlab` and `python` functionalities.
+-  ECCO v4 estimates can be plotted via the `NASA` `Sea Level Change Portal <https://sealevel.nasa.gov>`__ tools (interpolated output) or downloaded from the `Harvard Dataverse <https://dataverse.harvard.edu>`__ APIs (native grid input and output).
 
--  The stand-alone `eccov4_lonlat.m <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/doc/eccov4_lonlat.m>`__ `Matlab` script can be used to extract the lat-lon sector (i.e., array) of the gridded output that spans the 69S to 56N latitude range.
diff --git a/docs/eccov4r2_dirtree.rst b/docs/eccov4r2_dirtree.rst
@@ -0,0 +1,18 @@
+
+::
+
+   MITgcm/
+     model/   (MITgcm core)
+     pkg/     (MITgcm modules)
+     tools/
+       genmake2        (shell script)
+       build_options   (compiler options)
+     mysetups/         (user created)
+       ECCO_v4_r2/
+         build/                (build directory)
+         code/                 (compile-time settings)
+         input/                (run-time settings)
+         results_itXX/         (reference results)
+         forcing_baseline2/    (user installed)
+         inputs_baseline2/     (user installed)
+
diff --git a/docs/eccov4r2_output.rst b/docs/eccov4r2_output.rst
@@ -0,0 +1,12 @@
+
+The ECCO v4 r2 state estimate output is permanently archived within the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2>`__ that provides citable identifiers for the various datasets as reported in this `README.pdf <https://dataverse.harvard.edu/api/access/datafile/2863409>`__. For download purposes, the ECCO v4 r2 output is also made available via this `ftp
+server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ by the `ECCO Consortium <http://ecco-group.org>`__. The various directory contents are summarized in this `README <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/README>`__ and specific details are provided in each subdirectory’s README. Under Linux or macOS for instance, a simple download method consists in using ``wget`` at the command line by typing
+
+::
+
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_grid
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_climatology
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_monthly
+
+and similarly for the other directories. The ``nctiles_`` directory prefix indicates that contents are provided on the native LLC90 grid in the nctiles format :cite:`for-eta:15` which can be read in `Matlab` using the `gcmfaces` toolbox (see :numref:`download-analysis`). Alternatively users can download interpolated fields, on a :math:`1/2\times1/2^\circ` grid in the netcdf format, from the ``interp_*`` directories. The ``input_*`` directories contain binary and netcdf input files that can be read by `MITgcm` (:numref:`download-setup` and :numref:`eccov4-baseline`). The ``profiles/`` directory (`see ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/profiles/>`_) additionally contains the MITprof collections of collocated in situ and state estimate profiles in `netcdf` format :cite:`for-eta:15`.
+
diff --git a/docs/eccov4r2_setup.rst b/docs/eccov4r2_setup.rst
@@ -0,0 +1,23 @@
+
+Users can donwload the `MITgcm` from `this github repository <https://github.com/MITgcm/MITgcm/>`__ and the model setup there from `that github repository <https://github.com/gaelforget/ECCO_v4_r2/>`__ by typing:
+
+::
+
+    git clone https://github.com/MITgcm/MITgcm
+    mkdir MITgcm/mysetups
+    mv ECCO_v4_r2 MITgcm/mysetups/.
+    cd MITgcm/mysetups
+    git clone https://github.com/gaelforget/ECCO_v4_r2
+
+Re-running ECCO v4 r2 additionally requires downloading surface forcing input (96G of 6-hourly fields in ECCO v4 r2), initial condition, grid, etc. input (610M), and observational input (25G) either from the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2inputs>`__ permanent archive or from the `ECCO ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ as follows:
+
+::
+
+    cd MITgcm/mysetups/ECCO_v4_r2
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing/
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_init/
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco/
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing forcing_baseline2
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco inputs_baseline2
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_init inputs_baseline2/.
+