Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for CESM2.2.0 #173

Merged
merged 1 commit into from
Sep 23, 2020
Merged

Update docs for CESM2.2.0 #173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions doc/source/cesm_configurations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
.. _configurations:

===============================
CESM Configurations (|version|)
CESM2 Configurations (|version|)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, this is another place where the "CESM2" is particularly redundant. But again, I don't have strong feelings.

===============================

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
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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"
Expand Down Expand Up @@ -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.

Expand All @@ -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,
Expand All @@ -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
Expand Down
41 changes: 34 additions & 7 deletions doc/source/downloading_cesm.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _downloading:

============================
Downloading CESM (|version|)
Downloading CESM2 (|version|)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one will show up like "Downloading CESM2 (CESM2.2)". That kind of makes the "2" in "CESM2" feel redundant, but I don't feel strongly.

============================

Downloading the code and scripts
Expand All @@ -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:

Expand All @@ -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

Expand All @@ -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:

Expand Down Expand Up @@ -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
Comment on lines +123 to +129
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding this.


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:

Expand Down
2 changes: 1 addition & 1 deletion doc/source/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down