Merge pull request #173 from ESCOMP/fischer/doc

Update documentation for CESM2.2.0.

Juggled around CESM vs CESM2. The approach I took was if it applied to both
CESM and CESM2, I left it as CESM. For example the section on inputdata, and version
naming. If something applied to only CESM2, I changed CESM to CESM2. An example
of this is the download instructions and different components.

In the download instructions, I needed to update the manage_externals -S output to reflect
the changes of the option components. Then included a note that this is the default and
CESM2 will still run.

doc/source/cesm_configurations.rst

@@ -1,11 +1,11 @@
 .. _configurations:
 
 ===============================
-CESM Configurations (|version|)
+CESM2 Configurations (|version|)
 ===============================
 
-The CESM system can be configured a number of different ways from both
-a science and technical perspective. CESM supports numerous
+The CESM2 system can be configured a number of different ways from both
+a science and technical perspective. CESM2 supports numerous
 `resolutions
 <http://www.cesm.ucar.edu/models/cesm2/cesm/grids.html>`_, and
 `component sets
@@ -42,13 +42,13 @@ of several modes: "active," "data," "dead," or "stub" that permits the
 whole system to activate and deactive component feedbacks by allowing
 for a variety of "plug and play" combinations.
 
-During the course of a CESM run, the model components integrate forward
+During the course of a CESM2 run, the model components integrate forward
 in time, periodically exchanging information with the coupler.
 The coupler meanwhile receives fields from the component models,
 computes, maps, and merges this information, then sends the fields back
 to the component models. The coupler brokers this sequence of
 communication interchanges and manages the overall time progression of
-the coupled system. A CESM component set is comprised of eight
+the coupled system. A CESM2 component set is comprised of eight
 components: one component from each model (atm, lnd, rof, ocn, ice, glc,
 wav, and esp) plus the coupler. Model components are written primarily in
 Fortran.
@@ -68,7 +68,7 @@ so ice, ocn, and glc stubs are used).
 
 The CESM2 components can be summarized as follows:
 
-.. csv-table:: "CESM model components"
+.. csv-table:: "CESM2 model components"
    :header: "Component Generic Type", "Component Generic Name", "Component Name", "Component Type", "Description"
    :widths: 12, 10, 10, 10, 60
 
@@ -86,6 +86,7 @@ The CESM2 components can be summarized as follows:
    "river", "rof", "xrof", "dead", "Used only for testing the driver/coupler"
    "river", "rof", "srof", "stub", "Used only to satisy the interface requirements"
    "ocean", "ocn", "pop", "active", "The ocean model is an extension of the `Parallel Ocean Program (POP) <http://www.cesm.ucar.edu/models/cesm2/ocean/>`_ Version 2 from Los Alamos National Laboratory (LANL)."
+   "ocean", "ocn", "mom6", "active", "Based on the `Modular Ocean Model version 6 <http://www.cesm.ucar.edu/models/cesm2/ocean/>`_; an early functional release is available starting in CESM2.2.   Note that MOM6 is not obtained by default; for instructions on obtaining it, see https://github.com/ESCOMP/MOM_interface/wiki/Detailed-Instructions."
    "ocean", "ocn", "docn", "data", "The `data ocean <http://esmci.github.io/cime/versions/master/html/data_models/data-ocean.html>`_ component has two distinct modes of operation. It can run as a pure data model, reading ocean SSTs (normally climatological) from input datasets, interpolating in space and time, and then passing these to the coupler. Alternatively, docn can compute updated SSTs based on a slab ocean model where bottom ocean heat flux convergence and boundary layer depths are read in and used with the atmosphere/ocean and ice/ocean fluxes obtained from the coupler."
    "ocean", "ocn", "xocn", "dead"
    "ocean", "ocn", "socn", "stub"
@@ -120,19 +121,19 @@ See `supported component sets
 <http://www.cesm.ucar.edu/models/cesm2/cesm/compsets.html>`_ for a
 complete list of supported compset options. Running **query_config**
 with the ``--compsets`` option will also provide a listing of the
-supported out-of-the-box component sets for the local version of CESM.
+supported out-of-the-box component sets for the local version of CESM2.
 
 
 CESM2 Grids
 -----------
 
 The `supported grid resolutions
 <http://www.cesm.ucar.edu/models/cesm2/cesm/grids.html>`_ are
-specified in CESM by setting an overall model resolution.  Once the
+specified in CESM2 by setting an overall model resolution.  Once the
 overall model resolution is set, components will read in appropriate
 grid files and the coupler will read in appropriate mapping weights
 files. Coupler mapping weights are always generated externally in
-CESM. The components will send the grid data to the coupler at
+CESM2. The components will send the grid data to the coupler at
 initialization, and the coupler will check that the component grids
 are consistent with each other and with the mapping weights files.
 
@@ -141,7 +142,7 @@ atmosphere, land, river runoff and land ice can each be on different grids.
 Each component determines its own unique grid decomposition based upon
 the total number of pes or processing elements assigned to that component.
 
-CESM supports several types of grids out-of-the-box including single
+CESM2 supports several types of grids out-of-the-box including single
 point, finite volume, cubed sphere, displaced pole, and
 tripole. These grids are used internally by the
 models. Input datasets are usually on the same grid but in some cases,
@@ -168,33 +169,33 @@ CESM2 Machines
 
 Scripts for `supported machines
 <http://www.cesm.ucar.edu/models/cesm2/cesm/machines.html>`_ and
-userdefined machines are provided with the CESM release. Supported
-machines have machine specific files and settings added to the CESM
-scripts and are machines that should run CESM cases
-out-of-the-box. Machines are supported in CESM on an individual basis
+userdefined machines are provided with the CESM2 release. Supported
+machines have machine specific files and settings added to the CESM2
+scripts and are machines that should run CESM2 cases
+out-of-the-box. Machines are supported in CESM2 on an individual basis
 and are usually listed by their common site-specific name. To get a
-machine ported and functionally supported in CESM, local batch, run,
-environment, and compiler information must be configured in the CESM
+machine ported and functionally supported in CESM2, local batch, run,
+environment, and compiler information must be configured in the CESM2
 scripts. The machine name "userdefined" machines refer to any machine
 that the user defines and requires that a user edit the resulting xml
 files to fill in information required for the target platform. This
 functionality is handy in accelerating the porting process and quickly
 getting a case running on a new platform. For more information on
 porting, see the `CIME porting guide
 <http://esmci.github.io/cime/versions/master/html/users_guide/porting-cime.html>`_.  The
-list of available machines are documented in `CESM supported machines
+list of available machines are documented in `CESM2 supported machines
 <http://www.cesm.ucar.edu/models/cesm2/cesm/machines.html>`_.
 Running **query_config** with the ``--machines`` option will also show
 the list of all machines for the current local version of
-CESM. Supported machines have undergone the full CESM porting
+CESM. Supported machines have undergone the full CESM2 porting
 process. The machines available in each of these categories changes as
 access to machines change over time.
 
 
 CESM2 Validation
 ----------------
 
-Although CESM can be run out-of-the-box for a variety of resolutions,
+Although CESM2 can be run out-of-the-box for a variety of resolutions,
 component combinations, and machines, MOST combinations of component
 sets, resolutions, and machines have not undergone rigorous scientific
 climate validation. Control runs accompany `scientifically supported

doc/source/downloading_cesm.rst

@@ -1,7 +1,7 @@
 .. _downloading:
 
 ============================
-Downloading CESM (|version|)
+Downloading CESM2 (|version|)
 ============================
 
 Downloading the code and scripts
@@ -19,7 +19,7 @@ software is at version 1.8.17. For more information or to download
 open source tools, visit `Subversion <http://subversion.apache.org/>`_
 and `git downloads <https://git-scm.com/downloads>`_.
 
-With valid git and svn clients installed on the machine where CESM will be
+With valid git and svn clients installed on the machine where CESM2 will be
 built and run, the user may download the latest version of the release
 code:
 
@@ -28,13 +28,13 @@ code:
     git clone -b release-cesm2.2.0 https://github.com/ESCOMP/CESM.git my_cesm_sandbox
     cd my_cesm_sandbox
 
-To checkout a previous version of CESM, first view the available versions:
+To checkout a previous version of CESM2, first view the available versions:
 
 .. code-block:: console
 
     git tag --list 'release-cesm2*'
 
-To checkout a specific CESM release tag type, for example CESM2.0.1:
+To checkout a specific CESM2 release tag type, for example CESM2.0.1:
 
 .. code-block:: console 
 
@@ -50,7 +50,7 @@ run the **checkout_externals** script from /path/to/my_cesm_sandbox.
 The **checkout_externals** script will read the configuration file called ``Externals.cfg`` and
 will download all the external component models and CIME into /path/to/my_cesm_sandbox. 
 
-Details regarding the CESM checkout process are available in the CESM GitHub repo
+Details regarding the CESM2 checkout process are available in the CESM GitHub repo
 `README <http://github.com/ESCOMP/CESM/blob/master/README.rst>`_
 To see more details regarding the checkout_externals script from the command line, type:
 
@@ -82,25 +82,52 @@ columns of output, as in this example:
 
    Processing externals description file : Externals.cfg
    Processing externals description file : Externals_CLM.cfg
+   Processing externals description file : ../Externals_cime.cfg
    Processing externals description file : Externals_POP.cfg
    Processing externals description file : Externals_CISM.cfg
-   Checking status of externals: clm, fates, ptclm, mosart, ww3, cime, cice, pop, cvmix, marbl, cism, source_cism, rtm, cam,
+   Processing externals description file : .gitmodules
+   Processing submodules description file : .gitmodules
+   Processing externals description file : Externals_CAM.cfg
+   Checking status of externals: clm, fates, ptclm, mosart, cime, cmeps, ww3, cice, fms, pop, cvmix, marbl, cism, source_cism, rtm, cdeps, fox, mom, cam, silhs, clubb, pumas, atmos_phys, cosp2, chem_proc, atmos_cubed_sphere, carma, 
        ./cime
+   e-o ./cime/src/drivers/nuopc/
        ./components/cam
+       ./components/cam/chem_proc
+       ./components/cam/src/atmos_phys
+       ./components/cam/src/dynamics/fv3/atmos_cubed_sphere
+       ./components/cam/src/physics/carma/base
+       ./components/cam/src/physics/clubb
+       ./components/cam/src/physics/cosp2/src
+       ./components/cam/src/physics/pumas
+       ./components/cam/src/physics/silhs
+       ./components/cdeps
+       ./components/cdeps/fox
        ./components/cice
        ./components/cism
        ./components/cism/source_cism
        ./components/clm
        ./components/clm/src/fates
        ./components/clm/tools/PTCLM
+   e-o ./components/mom
        ./components/mosart
        ./components/pop
        ./components/pop/externals/CVMix
        ./components/pop/externals/MARBL
        ./components/rtm
        ./components/ww3
+   e-o ./libraries/FMS
+
+
+You should now have a default copy of the CESM2 source code in your /path/to/my_cesm_sandbox.
+
+These components are optional and are not needed to run CESM2.
+
+.. code-block:: console
+
+   e-o ./cime/src/drivers/nuopc/
+   e-o ./components/mom
+   e-o ./libraries/FMS
 
-You should now have a complete copy of the CESM2 source code in your /path/to/my_cesm_sandbox. 
 
 If there were problems obtaining an external, you might instead see something like:
 

doc/source/quickstart.rst

@@ -15,7 +15,7 @@ If you are new to CESM2, please consider reading the
 
 This is the procedure for quickly setting up and running a CESM2 case.
 
-Download CESM2 (see `Downloading CESM2 <downloading_cesm.rst>`_).
+Download CESM2 (see `Downloading CESM2 <downloading_cesm.html>`_).
 
 Select a component set, and a resolution for your case.  Details of available
 component sets and resolutions are available from the `query_config`_ tool located