From b57aa8d93442fb8592f13a1dfcffa4d2b0901b14 Mon Sep 17 00:00:00 2001 From: Chris Fischer Date: Wed, 23 Sep 2020 11:05:54 -0600 Subject: [PATCH] Update docs for CESM2.2 --- doc/source/cesm_configurations.rst | 39 ++++++++++++++-------------- doc/source/downloading_cesm.rst | 41 +++++++++++++++++++++++++----- doc/source/quickstart.rst | 2 +- 3 files changed, 55 insertions(+), 27 deletions(-) diff --git a/doc/source/cesm_configurations.rst b/doc/source/cesm_configurations.rst index e859914fca..b4e5583b3c 100644 --- a/doc/source/cesm_configurations.rst +++ b/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 `_, 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) `_ Version 2 from Los Alamos National Laboratory (LANL)." + "ocean", "ocn", "mom6", "active", "Based on the `Modular Ocean Model version 6 `_; 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 `_ 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,7 +121,7 @@ See `supported component sets `_ 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 @@ -128,11 +129,11 @@ CESM2 Grids The `supported grid resolutions `_ 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,13 +169,13 @@ CESM2 Machines Scripts for `supported machines `_ 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 @@ -182,11 +183,11 @@ 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 `_. The -list of available machines are documented in `CESM supported machines +list of available machines are documented in `CESM2 supported machines `_. 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. @@ -194,7 +195,7 @@ 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 diff --git a/doc/source/downloading_cesm.rst b/doc/source/downloading_cesm.rst index 51742f1dcd..5dc59bc193 100644 --- a/doc/source/downloading_cesm.rst +++ b/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 `_ and `git 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 `_ 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: diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index a1cd59dc7e..98b156530b 100644 --- a/doc/source/quickstart.rst +++ b/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 `_). +Download CESM2 (see `Downloading CESM2 `_). 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