From 24652c9b24c7251957e89ecc01a1c8c3b047142b Mon Sep 17 00:00:00 2001 From: Alice Bertini Date: Thu, 16 Nov 2017 15:21:48 -0700 Subject: [PATCH] update ACME to E3SM and changes related to Issue #1519 and PR #2062 --- .gitignore | 4 +- doc/source/conf.py | 15 ++--- doc/source/data_models/data-ocean.rst | 58 +++++++++++++------ doc/source/index.rst | 2 +- doc/source/misc_tools/index.rst | 11 ++-- doc/source/users_guide/cloning-a-case.rst | 40 ++++++++++--- .../users_guide/introduction-and-overview.rst | 2 +- .../optimizing-processor-layout.rst | 2 +- doc/source/users_guide/porting-cime.rst | 14 ++--- doc/source/users_guide/running-a-case.rst | 14 ++--- doc/source/users_guide/testing.rst | 4 +- doc/source/xml_files/acme.rst | 24 ++++---- doc/source/xml_files/drivers.rst | 4 +- 13 files changed, 118 insertions(+), 76 deletions(-) diff --git a/.gitignore b/.gitignore index 80ad392be399..48e07c8e7910 100644 --- a/.gitignore +++ b/.gitignore @@ -5,8 +5,8 @@ buildnmlc # Ignore emacs backup files *~ -# Ignore doc/build/doctrees -##doc/build/doctrees # ignore for the merge to master and orphaning of the gh-pages branch doc/build +# ignore the JENKINS files created when make html is run +scripts/Tools/JENKINS* diff --git a/doc/source/conf.py b/doc/source/conf.py index 38c3af858f46..f6213988be9b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -55,16 +55,16 @@ # General information about the project. project = u'CIME' copyright = u'2017, U.S. National Science Foundation and U.S. Department of Energy' -author = u'Staff of the NSF/CESM and DOE/ACME projects' +author = u'Staff of the NSF/CESM and DOE/E3SM projects' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = u'5.3.0' +version = u'5.4.0' # The full version, including alpha/beta/rc tags. -release = u'5.3.0' +release = u'5.4.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -91,13 +91,14 @@ # a list of builtin themes. # #html_theme = 'alabaster' -html_theme = 'bizstyle' +#html_theme = 'bizstyle' +html_theme = 'classic' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -html_theme_options = { } +html_theme_options = {"stickysidebar": "true"} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -135,7 +136,7 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'on.tex', u'on Documentation', - u'Staff of the NSF/CESM and DOE/ACME projects', 'manual'), + u'Staff of the NSF/CESM and DOE/E3SM projects', 'manual'), ] @@ -166,7 +167,7 @@ (master_doc, u'CIME_Users_Guide', u'CIME Users Guide (PDF)', - u'Staff of the NSF/CESM and DOE/ACME projects'), + u'Staff of the NSF/CESM and DOE/E3SM projects'), ] diff --git a/doc/source/data_models/data-ocean.rst b/doc/source/data_models/data-ocean.rst index 02b3632044fb..fc680b3288db 100644 --- a/doc/source/data_models/data-ocean.rst +++ b/doc/source/data_models/data-ocean.rst @@ -13,21 +13,39 @@ DOCN has two distinct modes of operation. DOCN can run as a pure data model, reading in ocean SSTs (normally climatological) from input datasets, performing time/spatial interpolations, and passing these to the coupler. Alternatively, DOCN can compute updated SSTs by running as 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 driver. -DOCN running in prescribed mode assumes that the only field in the input stream is SST and also that SST is in Celsius and must be converted to Kelvin. -All other fields are set to zero except for ocean salinity, which is set to a constant reference salinity value. -Normally the ice fraction data (used for prescribed CICE) is found in the same data files that provide SST data to the data ocean model since SST and ice fraction data are derived from the same observational data sets and are consistent with each other. -For DOCN prescribed mode, default yearly climatological datasets are provided for various model resolutions. - -DOCN running as a slab ocean model is used in conjunction with active ice mode running in full prognostic mode (e.g. CICE for CESM). -This mode computes a prognostic sea surface temperature and a freeze/melt potential (surface Q-flux) used by the sea ice model. -This calculation requires an external SOM forcing data file that includes ocean mixed layer depths and bottom-of-the-slab Q-fluxes. -Scientifically appropriate bottom-of-the-slab Q-fluxes are normally ocean resolution dependent and are derived from the ocean model output of a fully coupled CCSM run. -Note that this mode no longer runs out of the box, the default testing SOM forcing file is not scientifically appropriate and is provided for testing and development purposes only. -Users must create scientifically appropriate data for their particular application or use one of the standard SOM forcing files from the full prognostic control runs. -For CESM, some of these are available in the `inputdata repository `_. -The user then modifies the ``$DOCN_SOM_FILENAME`` variable in env_run.xml to point to the appropriate SOM forcing dataset. - -.. note:: A tool is available to derive valid `SOM forcing `_ and more information on creating the SOM forcing is also available. +DOCN running in prescribed mode assumes that the only field in the +input stream is SST and also that SST is in Celsius and must be +converted to Kelvin. All other fields are set to zero except for +ocean salinity, which is set to a constant reference salinity value. +Normally the ice fraction data (used for prescribed CICE) is found in +the same data files that provide SST data to the data ocean model +since SST and ice fraction data are derived from the same +observational data sets and are consistent with each other. For DOCN +prescribed mode, default yearly climatological datasets are provided +for various model resolutions. + +DOCN running as a slab ocean model is used in conjunction with active +ice mode running in full prognostic mode (e.g. CICE for CESM). This +mode computes a prognostic sea surface temperature and a freeze/melt +potential (surface Q-flux) used by the sea ice model. This +calculation requires an external SOM forcing data file that includes +ocean mixed layer depths and bottom-of-the-slab Q-fluxes. +Scientifically appropriate bottom-of-the-slab Q-fluxes are normally +ocean resolution dependent and are derived from the ocean model output +of a fully coupled CCSM run. Note that this mode no longer runs out +of the box, the default testing SOM forcing file is not scientifically +appropriate and is provided for testing and development purposes only. +Users must create scientifically appropriate data for their particular +application or use one of the standard SOM forcing files from the full +prognostic control runs. For CESM, some of these are available in the +`inputdata repository +`_. +The user then modifies the ``$DOCN_SOM_FILENAME`` variable in +env_run.xml to point to the appropriate SOM forcing dataset. + +.. note:: A tool is available to derive valid `SOM forcing +`_ and more +information on creating the SOM forcing is also available. .. _docn-xml-vars: @@ -35,9 +53,13 @@ The user then modifies the ``$DOCN_SOM_FILENAME`` variable in env_run.xml to poi xml variables ------------- -The following are xml variables that CIME supports for DOCN. -These variables are defined in ``$CIMEROOT/src/components/data_comps/docn/cime_config/config_component.xml``. -These variables will appear in ``env_run.xml`` and are used by the DOCN ``cime_config/buildnml`` script to generate the DOCN namelist file ``docn_in`` and the required associated stream files for the case. +The following are xml variables that CIME supports for DOCN. These +variables are defined in +``$CIMEROOT/src/components/data_comps/docn/cime_config/config_component.xml``. +These variables will appear in ``env_run.xml`` and are used by the +DOCN ``cime_config/buildnml`` script to generate the DOCN namelist +file ``docn_in`` and the required associated stream files for the +case. .. note:: These xml variables are used by the the docn's **cime_config/buildnml** script in conjunction with docn's **cime_config/namelist_definition_docn.xml** file to generate the namelist file ``docn_in``. diff --git a/doc/source/index.rst b/doc/source/index.rst index aaf04d8ea06c..f39f87c32faf 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -43,5 +43,5 @@ Python Module Indices and Search CIME is developed by the -`ACME `_ and +`E3SM `_ and `CESM `_ projects. diff --git a/doc/source/misc_tools/index.rst b/doc/source/misc_tools/index.rst index 13fe0b4ec40a..b76a3291c24d 100644 --- a/doc/source/misc_tools/index.rst +++ b/doc/source/misc_tools/index.rst @@ -17,13 +17,10 @@ tools that are necessary and/or useful when building a climate model. Guides fo :numbered: -Statistical Ensemble Test - -Mapping Tools - -cprnc - -load-balancing-tool.rst + Statistical Ensemble Test + Mapping Tools + cprnc + load-balancing-tool.rst Indices and tables ================== diff --git a/doc/source/users_guide/cloning-a-case.rst b/doc/source/users_guide/cloning-a-case.rst index d2ae3e94c9f3..150123362b60 100644 --- a/doc/source/users_guide/cloning-a-case.rst +++ b/doc/source/users_guide/cloning-a-case.rst @@ -4,15 +4,23 @@ Cloning a Case ************************** -If you have access to a run that you want to clone, the **create_clone** command will create a new case while preserving local modifications to the case. +If you have access to a run that you want to clone, the +**create_clone** command will create a new case and run **case.setup** +while preserving local modifications to the case. Here is a simple example: :: > cd $CIMEROOT/scripts > create_clone --case $CASEROOT --clone $CLONEROOT + > cd $CLONEROOT + > case.build + > case.submit -The **create_clone** script preserves any local namelist modifications made in the **user_nl_xxxx** files as well as any source code modifications in the **SourceMods** tree. Otherwise, **$CASEROOT/** directory will appear as if **create_newcase** had just been run. +The **create_clone** script preserves any local namelist modifications +made in the **user_nl_xxxx** files as well as any source code +modifications in the **SourceMods** tree. Otherwise, **$CASEROOT/** +directory will appear as if **create_newcase** had just been run. **Important**: Do not change anything in the **env_case.xml** file. @@ -21,23 +29,37 @@ See the **help** text for more usage information. > create_clone --help -**create_clone** has several useful optional arguments. To point to the executable of the original case you are cloning from. +**create_clone** has several useful optional arguments. To point to +the executable of the original case you are cloning from. :: > create_clone --case $CASEROOT --clone $CLONEROOT --keepexe + > cd $CLONEROOT + > case.submit -If the ``--keepexe`` optional argument is used, then no SourceMods will be permitted in the cloned directory. -A link will be made when the cloned case is created pointing the cloned SourceMods/ directory to the original case SourceMods directory. +If the ``--keepexe`` optional argument is used, then no SourceMods +will be permitted in the cloned directory. A link will be made when +the cloned case is created pointing the cloned SourceMods/ directory +to the original case SourceMods directory. .. warning:: No changes should be made to ``env_build.xml`` or ``env_mach_pes.xml`` in the cloned directory. -**create_clone** also permits you to invoked the ``shell_commands`` and ``user_nl_xxx`` files in a user_mods directory by calling: +**create_clone** also permits you to invoked the ``shell_commands`` + and ``user_nl_xxx`` files in a user_mods directory by calling: :: > create_clone --case $CASEROOT --clone $CLONEROOT --user-mods-dir USER_MODS_DIR [--keepexe] Note that an optional ``--keepexe`` flag can also be used in this case. -.. warning:: If there is a ``shell_commands`` file, it should not have any changes to xml variables in either ``env_build.xml`` or ``env_mach_pes.xml``. - -Another approach to duplicating a case is to use the information in the case's **README.case** and **CaseStatus** files to create a new case and duplicate the relevant **xlmchange** commands that were issued in the original case. This alternative will *not* preserve any local modifications that were made to the original case, such as source-code or build-script revisions; you will need to import those changes manually. +.. warning:: If there is a ``shell_commands`` file, it should not have +any changes to xml variables in either ``env_build.xml`` or +``env_mach_pes.xml``. + +Another approach to duplicating a case is to use the information in +the case's **README.case** and **CaseStatus** files to create a new +case and duplicate the relevant **xlmchange** commands that were +issued in the original case. This alternative will *not* preserve any +local modifications that were made to the original case, such as +source-code or build-script revisions; you will need to import those +changes manually. diff --git a/doc/source/users_guide/introduction-and-overview.rst b/doc/source/users_guide/introduction-and-overview.rst index f87ea9f01f75..f39bb184f079 100644 --- a/doc/source/users_guide/introduction-and-overview.rst +++ b/doc/source/users_guide/introduction-and-overview.rst @@ -135,7 +135,7 @@ directory structure. :widths: 150, 300 "config/cesm/", "CESM-specific configuration options" - "config/acme/", "ACME-specific configuration options" + "config/acme/", "E3SM-specific configuration options" "src/components/", "CIME-provided components including data and stub models" "src/drivers/", "CIME-provided main driver for a climate model" "src/externals/", "Software provided with CIME for building a climate model" diff --git a/doc/source/users_guide/optimizing-processor-layout.rst b/doc/source/users_guide/optimizing-processor-layout.rst index 106e635d6bbb..afc2b655ff69 100644 --- a/doc/source/users_guide/optimizing-processor-layout.rst +++ b/doc/source/users_guide/optimizing-processor-layout.rst @@ -57,7 +57,7 @@ Finally, decide whether components should run sequentially, concurrently, or in Typically, a series of short test runs with the desired production configuration can establish a reasonable load balance setup for the production job. The timing output can be used to compare test runs to help determine the optimal load balance. Changing the pe layout of the model has NO IMPACT on the scientific results. The basic order of operations and calling sequence are hardwired into the driver and do not change with the pe layout. that doesn't change when the pe layout is changed. -There are some constraints on the ability of either the CESM or ACME fully active configuration fully concurrent. For example, the atmosphere model always run sequentially with the ice and land models for scientific reasons. As a result, running the atmosphere concurrently with the ice and land will result in idle processors at some point in the timestepping sequence. +There are some constraints on the ability of either the CESM or E3SM fully active configuration fully concurrent. For example, the atmosphere model always run sequentially with the ice and land models for scientific reasons. As a result, running the atmosphere concurrently with the ice and land will result in idle processors at some point in the timestepping sequence. For more information about how the driver is implemented, see (Craig, A.P., Vertenstein, M., Jacob, R., 2012: A new flexible coupler for earth system modeling developed for CCSM4 and CESM1.0. International Journal of High Performance Computing Applications, 26, 31-42, 10.1177/1094342011428141). diff --git a/doc/source/users_guide/porting-cime.rst b/doc/source/users_guide/porting-cime.rst index 052915c7e2d8..1ab636305c1d 100644 --- a/doc/source/users_guide/porting-cime.rst +++ b/doc/source/users_guide/porting-cime.rst @@ -28,7 +28,7 @@ Steps for porting Porting CIME involves several steps in which you create, at a minimum, a **config_machines.xml** file in your **$HOME/.cime** directory. In addition, if you have a batch system, you will also need to add a **config_batch.xml** file to your **$HOME/.cime** directory. -All files in **$HOME/.cime/** are appended to the xml objects that are read into memory from the **$CIME/config/[model]**, where **[model]** is either ``acme`` or ``cesm``. +All files in **$HOME/.cime/** are appended to the xml objects that are read into memory from the **$CIME/config/[model]**, where **[model]** is either ``e3sm`` or ``cesm``. Follow these steps: @@ -45,7 +45,7 @@ Follow these steps: :: [main] - CIME_MODEL=acme + CIME_MODEL=e3sm #. Create a **config_machines.xml** file in the same directory. @@ -69,13 +69,13 @@ Follow these steps: #. If you have compiler settings that are specific to your machine, create a **$HOME/.cime/config_compilers.xml** file. - The default compiler settings are set in **$CIME/config/[model]/machines/config_compilers.xml**, where **[model]** can be either ``acme`` or ``cesm``. + The default compiler settings are set in **$CIME/config/[model]/machines/config_compilers.xml**, where **[model]** can be either ``e3sm`` or ``cesm``. There is no template for **config_compilers.xml**. #. If you have a batch system, create a **$HOME/.cime/config_batch.xml** file. - Out-of-the-box batch settings are set in **$CIME/config/[model]/machines/config_batch.xml**, where **[model]** can be either ``acme`` or ``cesm``. + Out-of-the-box batch settings are set in **$CIME/config/[model]/machines/config_batch.xml**, where **[model]** can be either ``e3sm`` or ``cesm``. #. Once you have defined a basic configuration for your machine in your **$HOME/.cime** xml files, run **scripts_regression_test.py** interactively from the **$CIME/scripts/tests** directory. This performs a number of basic unit tests starting from the simplest and working toward more complicated ones. @@ -103,7 +103,7 @@ Each ```` tag requires the following input: - ``COMPILERS``: compilers supported on the machine, in comma-separated list, default first - ``MPILIBS``: mpilibs supported on the machine, in comma-separated list, default first - ``PROJECT``: a project or account number used for batch jobs; can be overridden in environment or in **$HOME/.cime/config** -- ``SAVE_TIMING_DIR``: (ACME only) target directory for writing timing output +- ``SAVE_TIMING_DIR``: (E3SM only) target directory for writing timing output - ``CIME_OUTPUT_ROOT``: Base directory for case output; the **bld** and **run** directories are written below here - ``DIN_LOC_ROOT``: location of the input data directory - ``DIN_LOC_ROOT_CLMFORC``: optional input location for clm forcing data @@ -113,7 +113,7 @@ Each ```` tag requires the following input: - ``CCSM_CPRNC``: location of the cprnc tool, which compares model output in testing - ``GMAKE``: gnu-compatible make tool; default is "gmake" - ``GMAKE_J``: optional number of threads to pass to the gmake flag -- ``TESTS``: (ACME only) list of tests to run on the machine +- ``TESTS``: (E3SM only) list of tests to run on the machine - ``BATCH_SYSTEM``: batch system used on this machine (none is okay) - ``SUPPORTED_BY``: contact information for support for this system - ``MAX_TASKS_PER_NODE``: maximum number of threads/tasks per shared memory node on the machine @@ -151,7 +151,7 @@ Each ```` tag requires the following input: config_compilers.xml - compiler paths and options ================================================= -The **config_compilers.xml** file defines compiler flags for building CIME (and also CESM and ACME prognostic CIME-driven components). +The **config_compilers.xml** file defines compiler flags for building CIME (and also CESM and E3SM prognostic CIME-driven components). #. General compiler flags (e.g., for the gnu compiler) that are machine- and componen-independent are listed first. diff --git a/doc/source/users_guide/running-a-case.rst b/doc/source/users_guide/running-a-case.rst index 280744650a65..71e3ee145b63 100644 --- a/doc/source/users_guide/running-a-case.rst +++ b/doc/source/users_guide/running-a-case.rst @@ -457,9 +457,9 @@ long-term archiver tool that supported mass tape storage and HPSS systems. However, with the industry migration away from tape archives, it is no longer feasible for CIME to support all the possible archival schemes available. -============================ +================================================ Data Assimilation and other External Processing -============================ +================================================ CIME provides a capability to run a task on the compute nodes either before or after the model run. CIME also provides a data assimilation @@ -467,9 +467,9 @@ capability which will cycle the model and then a user defined task for a user determined number of cycles. ---------------------- +------------------------- Pre and Post run scripts ---------------------- +------------------------- Variables ``PRERUN_SCRIPT`` and ``POSTRUN_SCRIPT`` can each be used to name a script which should be exectuted immediately prior starting or @@ -480,9 +480,9 @@ directory. If the script is written in python and contains a subroutine with the same name as the script, it will be called as a subroutine rather than as an external shell script. ---------------------- -Data Assimilatin scripts ---------------------- +------------------------- +Data Assimilation scripts +------------------------- Variables ``DATA_ASSIMILATION``, ``DATA_ASSIMILATION_SCRIPT``, and ``DATA_ASSIMILATION_CYCLES`` may also be used to externally control diff --git a/doc/source/users_guide/testing.rst b/doc/source/users_guide/testing.rst index de3d6ecf4cbf..aa6b89382ad1 100644 --- a/doc/source/users_guide/testing.rst +++ b/doc/source/users_guide/testing.rst @@ -171,10 +171,10 @@ A cs.status.$testid script will be put in the test root. This script will allow current status of all your tests. ======================== -Using create_test (ACME) +Using create_test (E3SM) ======================== -Usage will differ slightly depending on if you're using ACME or CESM. +Usage will differ slightly depending on if you're using E3SM or CESM. Using examples to illustrate common use cases diff --git a/doc/source/xml_files/acme.rst b/doc/source/xml_files/acme.rst index 14384bdf56cb..deb6b0b877c3 100644 --- a/doc/source/xml_files/acme.rst +++ b/doc/source/xml_files/acme.rst @@ -1,10 +1,10 @@ .. _acme: ############################# -ACME Coupled Model XML Files +E3SM Coupled Model XML Files ############################# -XML files for ACME in CIMEROOT/config/acme. +XML files for E3SM in CIMEROOT/config/acme. .. toctree:: :maxdepth: 1 @@ -13,15 +13,15 @@ XML files for ACME in CIMEROOT/config/acme. CIMEROOT/config/acme ******************** -ACME XML settings for short term archiver. +E3SM XML settings for short term archiver. .. literalinclude:: ../../../config/acme/config_archive.xml -ACME XML settings for defining CASEROOT env_*.xml file entries. +E3SM XML settings for defining CASEROOT env_*.xml file entries. .. literalinclude:: ../../../config/acme/config_files.xml -ACME XML settings for defining supported grids. +E3SM XML settings for defining supported grids. .. literalinclude:: ../../../config/acme/config_grids.xml @@ -30,15 +30,15 @@ ACME XML settings for defining supported grids. CIMEROOT/config/acme/allactive ****************************** -ACME XML settings for all-active component set (compset) configurations. +E3SM XML settings for all-active component set (compset) configurations. .. literalinclude:: ../../../config/acme/allactive/config_compsets.xml -ACME XML settings for all-active test configurations. +E3SM XML settings for all-active test configurations. .. literalinclude:: ../../../config/acme/allactive/testlist_allactive.xml -ACME XML settings for optimized processor elements (PEs) layout configurations. +E3SM XML settings for optimized processor elements (PEs) layout configurations. .. literalinclude:: ../../../config/acme/allactive/config_pesall.xml @@ -47,19 +47,19 @@ ACME XML settings for optimized processor elements (PEs) layout configurations. CIMEROOT/config/acme/machines ***************************** -ACME XML settings for supported batch queuing systems. +E3SM XML settings for supported batch queuing systems. .. literalinclude:: ../../../config/acme/machines/config_batch.xml -ACME XML settings for supported compilers. +E3SM XML settings for supported compilers. .. literalinclude:: ../../../config/acme/machines/config_compilers.xml -ACME XML settings for supported machines. +E3SM XML settings for supported machines. .. literalinclude:: ../../../config/acme/machines/config_machines.xml -ACME XML settings for Parallel Input/Output (PIO) library. +E3SM XML settings for Parallel Input/Output (PIO) library. .. literalinclude:: ../../../config/acme/machines/config_pio.xml diff --git a/doc/source/xml_files/drivers.rst b/doc/source/xml_files/drivers.rst index 08197abf7926..83af75db621a 100644 --- a/doc/source/xml_files/drivers.rst +++ b/doc/source/xml_files/drivers.rst @@ -25,11 +25,11 @@ XML variables and component descriptions specific to the driver/coupler .. literalinclude:: ../../../src/drivers/mct/cime_config/config_component.xml -XML variables and component descriptions specific to the ACME driver/coupler +XML variables and component descriptions specific to the E3SM driver/coupler .. literalinclude:: ../../../src/drivers/mct/cime_config/config_component_acme.xml -XML variables and component descriptions specific to the ACME driver/coupler +XML variables and component descriptions specific to the E3SM driver/coupler .. literalinclude:: ../../../src/drivers/mct/cime_config/config_component_cesm.xml