update ACME to E3SM and changes related to Issue #1519 and PR #2062

.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*

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'),
 ]
 
 

doc/source/data_models/data-ocean.rst

@@ -13,31 +13,53 @@ 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 <https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/ocn/docn7/SOM/>`_. 
-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 <http://www.cesm.ucar.edu/models/ccsm1.1/data8/SOM.pdf>`_ 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
+<https://svn-ccsm-inputdata.cgd.ucar.edu/trunk/inputdata/ocn/docn7/SOM/>`_.
+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
+<http://www.cesm.ucar.edu/models/cesm1.2/data8/doc/SOM.pdf>`_ and more
+information on creating the SOM forcing is also available.
 
 .. _docn-xml-vars:
 
 -------------
 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``.
 

doc/source/index.rst

@@ -43,5 +43,5 @@ Python Module Indices and Search
 
 
 CIME is developed by the 
-`ACME <https://climatemodeling.science.energy.gov/projects/accelerated-climate-modeling-energy>`_ and 
+`E3SM <https://climatemodeling.science.energy.gov/projects/energy-exascale-earth-system-model>`_ and 
 `CESM <http://www.cesm.ucar.edu/>`_ projects.

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
 ==================

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.

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"

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). 
 

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 ``<machine>`` 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 ``<machine>`` 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 ``<machine>`` 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.
 

doc/source/users_guide/running-a-case.rst

@@ -457,19 +457,19 @@ 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
 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

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