update from cime PR #1634

_sources/users_guide/building-a-case.txt

@@ -4,7 +4,7 @@
 Building a Case
 ******************
 
-The following summarizes details of building the model executable.
+The following describes the process of building the model executable.
 
 .. _building-the-model:
 
@@ -17,51 +17,47 @@ After calling **case.setup**, run **case.build** to build the model executable.
 1. Create the component namelists in ``$RUNDIR`` and ``$CASEROOT/CaseDocs``.
 2. Create the necessary compiled libraries ``mct``, ``pio``, ``gptl`` and ``csm_share``.
    The libraries will be placed in a path below ``$SHAREDLIBROOT``.
-3. Create the necessary component compiled libraries.
-   These will be placed in ``$EXEROOT/bld/lib``.
-4. Create the model executable (``$MODEL.exe``), which will be placed in ``$EXEROOT``.
+3. Create the necessary compiled libraries. These are be placed in ``$EXEROOT/bld/lib``.
+4. Create the model executable (``$MODEL.exe``), which is placed in ``$EXEROOT``.
 
 You do not need to change the default build settings to create the executable, but it is useful to become familiar with them in order to make optimal use of the system. The CIME scripts provide you with a great deal of flexibility in customizing the build process.
 
-The **env_build.xml** variables control various aspects of building the model executable.
-Most of the variables should not be modified, but users can modify these:
+The **env_build.xml** variables control various aspects of building the executable. Most of the variables should not be modified, but users can modify these:
 
 - ``$BUILD_THREADED``
 
 - ``$DEBUG``
 
 - ``$GMAKE_J``
 
-The best way to determine what xml variables are in your ``$CASEROOT`` directory is to use the ``xmlquery`` command. For usage information, run:
+The best way to see what xml variables are in your ``$CASEROOT`` directory is to use the **xmlquery** command. For usage information, run:
 ::
 
-   ./xmlquery --help
+   > ./xmlquery --help
 
 To build the model, change to your ``$CASEROOT`` directory and execute **case.build**.
 ::
 
    > cd $CASEROOT
    > ./case.build
 
-Diagnostic comments will appear as the build proceeds.
+Diagnostic comments appear as the build proceeds.
 
-The **case.build** command generates the utility and component libraries and the model executable, and it generates build logs for each component. Each build log file is date stamped, and a pointer to the build log file for that library or component is shown.
-
-The build log files have names in this form: **$component.bldlog.$datestamp**. They are located in ``$BLDDIR``. If they are compressed (as indicated by a .gz file extension), then the build ran successfully.
+The **case.build** command generates the utility and component libraries and the model executable, and it generates build logs for each component. Each log file is named form: **$component.bldlog.$datestamp**. They are located in ``$BLDDIR``. If they are compressed (as indicated by a .gz file extension), the build ran successfully.
 
 Invoking **case.build** creates the following directory structure in ``$EXEROOT`` if the Intel compiler is used:
 ::
 
    atm/, cpl/, esp/, glc/, ice/, intel/, lib/, lnd/, ocn/, rof/, wav/
 
-Except for **intel/** and **lib/**, each of those directories contains an **obj/** directory for the compiled object files for the target model component.
+Except for **intel/** and **lib/**, each directory contains an **obj/** subdirectory for the target model component's compiled object files.
 
-The ``mct``, ``pio``, ``gptl`` and ``csm_share`` libraries are placed in a directory tree that reflects their dependencies. See the **bldlog** for a given component to locate the library.
+The *mct*, *pio*, *gptl* and *csm_share* libraries are placed in a directory tree that reflects their dependencies. See the **bldlog** for a given component to locate the library.
 
-Special **include** modules are also placed in **lib/include**. The model executable (for example, **cesm.exe** or **acme.exe**) is placed directly in ``$EXEROOT``.
+Special **include** modules are placed in **lib/include**. The model executable (**cesm.exe** or **acme.exe**, for example) is placed directly in ``$EXEROOT``.
 
-Component namelists, component logs, output datasets, and restart files are placed in ``$RUNDIR``.
-It is important to note that ``$RUNDIR`` and ``$EXEROOT`` are independent variables that are set as ``$CASEROOT/env_run.xml``.
+Component namelists, component logs, output data sets, and restart files are placed in ``$RUNDIR``.
+It is important to note that ``$RUNDIR`` and ``$EXEROOT`` are independent variables that are set in the **$CASEROOT/env_run.xml** file.
 
 .. _rebuilding-the-model:
 
@@ -71,7 +67,7 @@ Rebuilding the model
 
 Rebuild the model under the following circumstances:
 
-If either **env_build.xml** or **Macros.make** has been modified, and/or if code is added to ``SourceMods/src.*``, then it's safest to clean the build and rebuild from scratch as shown here:
+If either **env_build.xml** or **Macros.make** has been modified, and/or if code is added to **SourceMods/src.**, it's safest to clean the build and rebuild from scratch as shown here:
 ::
 
    > cd $CASEROOT
@@ -83,29 +79,41 @@ If you have ONLY modified the PE layout in **env_mach_pes.xml**, a clean may not
    > cd $CASEROOT
    > ./case.build
 
-If the threading has been turned on or off in any component relative to the previous build, the build script should fail with the following error and suggestion that the model be rebuilt from scratch:
+If the threading has been changed (turned on or off) in any component since the previous build, the build script should fail with the following error and suggestion that the model be rebuilt from scratch:
 ::
 
    ERROR SMP STATUS HAS CHANGED
    SMP_BUILD = a0l0i0o0g0c0
    SMP_VALUE = a1l0i0o0g0c0
-   A manual clean of your obj directories is strongly recommended
+   A manual clean of your obj directories is strongly recommended.
    You should execute the following:
       ./case.build --clean
       ./case.build
 
     ---- OR ----
 
-    You can override this error message at your own risk by executing
+    You can override this error message at your own risk by executing:
       ./xmlchange SMP_BUILD=0
-    Then rerun the build script interactively
+    Then rerun the build script interactively.
 
 If there is any doubt, rebuild.
 
-The **case.build --clean** command will clean all of the model components but not support libraries such as ``mct`` and ``gptl``.
-Use **case.build --clean-all** to clean everything associated with the build.
+Run this to clean all of the model components (except for support libraries such as *mct* and *gptl*):
+  ::
+
+     > case.build --clean
+
+Run this to clean everything associated with the build:
+  ::
+
+     > case.build --clean-all
 
-You can also clean an individual component using **case.build --clean compname**, where "compname" is the name of the component you want to clean (for example, atm, clm, pio and so on). Run **case.build --help** for details.
+You can also clean an individual component as shown here, where "compname" is the name of the component you want to clean (for example, atm, clm, pio and so on).
+  ::
+
+     > case.build --clean compname
+
+Review the **help** text for more information.
 
 .. _inputdata:
 
@@ -115,19 +123,22 @@ Input data
 
 All active components and data components use input data sets. In order to run CIME and the CIME-compliant active components, a local disk needs the directory tree that is specified by the xml variable ``$DIN_LOC_ROOT`` to be populated with input data.
 
-Input data is provided as part of the CIME release via data from a subversion input data server. It is downloaded from the server on an as-needed basis determined by the case. Data may already exist in the default local file system's input data area as specified by ``$DIN_LOC_ROOT``. (See below.)
+Input data is provided as part of the CIME release via data from a subversion input data server. It is downloaded from the server on an as-needed basis determined by the case. Data may already exist in the default local file system's input data area as specified by ``$DIN_LOC_ROOT``.
 
 Input data can occupy significant space on a system, so users should share a common ``$DIN_LOC_ROOT`` directory on each system if possible.
 
 The build process handles input data as follows:
 
-- The ``buildnml`` scripts in the various component ``cime_config`` directories create listings of required component input data sets in the ``Buildconf/$component.input_data_list`` files.
+- The **buildnml** scripts in the various component **cime_config** directories create listings of required component input data sets in the **Buildconf/$component.input_data_list** files.
 
 - **check_input_data**, which is called by **case.build**, checks for the presence of the required input data files in the root directory ``$DIN_LOC_ROOT``.
 
 - If all required data sets are found on the local disk, the build can proceed.
 
-- If any of the required input data sets are not found locally, the files that are missing will be listed. At this point, you must obtain the required data from the input data server using **check_input_data** with the **-export** option.
+- If any of the required input data sets are not found locally, the files that are missing are listed. At this point, you must obtain the required data from the input data server with **check_input_data** as shown here:
+  ::
+
+     check_input_data --export
 
 The **env_run.xml** variables ``$DIN_LOC_ROOT`` and ``$DIN_LOC_ROOT_CLMFORC`` determine where you should expect input data to reside on a local disk.
 

_sources/users_guide/case-basics.txt

@@ -8,13 +8,13 @@ Two concepts to understand before working with CIME are component sets and model
 
 - *Component sets*, which are usually referred to as "compsets," define both individual model components and any component-specific namelist or configuration settings that are used in a case.
 
-- *Model grids* specify the grid or resolution for each component making up the model.
+- *Model grids* specify the grid or resolution for each component of the model.
 
 Creating a CIME experiment or *case* requires, at a minimum, specifying a compset and a model grid.
 
-Out-of-the-box compsets and models grids are associated with two names: a longname and an alias name. Examples of both follow.
+Out-of-the-box compsets and models grids each have two names: a *longname* and an *alias* name. Examples of both follow.
 
-The CIME regression test system requires aliases, but aliases can also be used for convenience. Compset aliases are unique; each compset alias is associated with one and only one compset. Grid aliases, on the other hand, are overloaded; the same grid alias may result in a different grid depending on the associated compset. Always confirm that the *compset longname* and the *grid longname* are correct when using aliases to create a case.
+The CIME regression test system requires aliases, but aliases can also be used for convenience. *Compset aliases* are unique; each is associated with one and only one compset. *Grid aliases*, on the other hand, are overloaded; the same grid alias may result in a different grid depending on the associated compset. Always confirm that the *compset longname* and the *grid longname* are correct when using aliases to create a case.
 
 ================
  Component sets
@@ -24,6 +24,8 @@ A compset longname has this form::
 
   TIME_ATM[%phys]_LND[%phys]_ICE[%phys]_OCN[%phys]_ROF[%phys]_GLC[%phys]_WAV[%phys]_ESP[_BGC%phys]
 
+Here are the supported values for each element of the longname::
+
   TIME = model time period (e.g. 1850, 2000, 20TR, RCP8...)
 
   CIME supports the following values for ATM,LND,ICE,OCN,ROF,GLC,WAV and ESP.
@@ -59,15 +61,14 @@ A compset longname has this form::
   The OPTIONAL %phys attributes specify sub-modes of the given system.
   For example, DOCN%DOM is the DOCN data ocean (rather than slab-ocean) mode.
   ALL the possible %phys choices for each component are listed by
-  calling **manage_case** with the **-list** compsets argument.
+  calling manage_case with the -list compsets argument.
   ALL data models have a %phys option that corresponds to the data model mode.
 
-As an example, the CESM compset longname (below) refers to running a pre-industrial control with active CESM components CAM, CLM, CICE, POP2, MOSART, CISM2 and WW3 in a BDRD BGC coupling scenario.::
+As an example, this actual CESM compset longname refers to running a pre-industrial control with active CESM components CAM, CLM, CICE, POP2, MOSART, CISM2 and WW3 in a BDRD BGC coupling scenario::
 
    1850_CAM60_CLM50%BGC_CICE_POP2%ECO_MOSART_CISM2%NOEVOLVE_WW3_BGC%BDRD
 
-The alias for this compset is B1850. Input to **create_newcase** can be either a compset longname or a compset alias.
-It is also possible to create your own custom compset. See *How do I create my own compset?* in the FAQ.
+The alias for this compset is B1850. Either a compset longname or a compset alias can be input to **create_newcase**. You can also create your own custom compset. See *How do I create my own compset?* in the FAQ.
 
 ===============================
  Model Grids
@@ -77,6 +78,8 @@ A model grid longname has the form::
 
   a%name_l%name_oi%name_r%name_m%mask_g%name_w%name
 
+For reference::
+
   a%  = atmosphere grid
   l%  = land grid
   oi% = ocean/sea-ice grid (must be the same)
@@ -94,18 +97,18 @@ A model grid longname has the form::
   be identical to the land grid. The internal CISM grid can be different,
   however, and is specified by the g% value.
 
-As an example, examine this longname::
+As an example, examine this actual grid longname::
 
    a%ne30np4_l%ne30np4_oi%gx1v7_r%r05_m%gx1v7_g%null_w%null
 
-It refers to a model grid with a ne30np4 spectral element 1-degree atmosphere and land grids, gx1v7 Greenland pole 1-degree ocean and sea-ice grids, a 1/2 degree river routing grid, null wave and internal cism grids, and an gx1v7 ocean mask.
+It refers to a model grid with a ne30np4 spectral element, 1-degree atmosphere and land grids, gx1v7 Greenland pole, 1-degree ocean and sea-ice grids, a 1/2 degree river routing grid, null wave and internal cism grids, and an gx1v7 ocean mask.
 The alias for this grid is ne30_g16.
 
 CIME also permits users to introduce their own :ref:`user-defined grids <adding-a-grid>`.
 
 Component grids are denoted by the following naming convention:
 
-- "[dlat]x[dlon]" are regular lon/lat finite volume grids where dlat and dlon are the approximate grid spacing. The shorthand convention is "fnn" where nn generally is a pair of numbers indicating the resolution. An example is 1.9x2.5 or f19 for the approximately "2-degree" finite volume grid. Note that CAM uses an [nlat]x[nlon] naming convention internally for this grid.
+- "[dlat]x[dlon]" are regular lon/lat finite volume grids where dlat and dlon are the approximate grid spacing. The shorthand convention is "fnn" where nn generally is a pair of numbers indicating the resolution. An example is 1.9x2.5 or f19 for the approximately "2-degree" finite-volume grid. Note that CAM uses an [nlat]x[nlon] naming convention internally for this grid.
 
 - "Tnn" are spectral lon/lat grids where nn is the spectral truncation value for the resolution. The shorthand name is identical. Example: T85.
 
@@ -121,7 +124,7 @@ Component grids are denoted by the following naming convention:
 Querying CIME - calling **query_config**
 ==============================================
 
-The utility **$CIMEROOT/scripts/query_config** permits you to query the out-of-the-box compsets, components, grids and machines that are available for a model.
+Use the utility **$CIMEROOT/scripts/query_config** to see which out-of-the-box compsets, components, grids and machines are available for a model.
 
 Optional arguments include the following:
   ::
@@ -131,17 +134,21 @@ Optional arguments include the following:
      --grids
      --machines
 
-If CIME is downloaded in standalone mode, only standalone CIME compsets can be queried. If CIME is part of a larger checkout that includes the prognostic components of a model, **query_config** will allow you to query all prognostic component compsets, as well.
+If CIME is downloaded in standalone mode, only standalone CIME compsets can be queried. If CIME is part of a larger checkout that includes the prognostic components of a model, **query_config** will allow you to query all prognostic component compsets.
 
-Run **query_config -- --help** to see lists of available compsets, components, grids and machines.
+To see lists of available compsets, components, grids and machines, look at the **help** text:
+  ::
+
+     > query_config --help
 
 **Usage examples**
-  To run **query_config** for compset information, use the **---compsets** option and the component name, which is **drv** in this example:
+
+To run **query_config** for compset information, follow this example, where **drv** is the component name:
   ::
 
-     query_config --compsets drv
+     > query_config --compsets drv
 
-  The output will be similar to this:
+The output will be similar to this:
   ::
 
      --------------------------------------
@@ -158,12 +165,12 @@ Run **query_config -- --help** to see lists of available compsets, components, g
 
 Each model component specifies its own definitions of what can appear after the ``%`` modifier in the compset longname (for example, ``DOM`` in ``DOCN%DOM``).
 
-  To see what supported modifiers are for ``DOCN``, run **query_config** as in this example:
+To see what supported modifiers are for ``DOCN``, run **query_config** as in this example:
   ::
 
-     query_config --component docn
+     > query_config --component docn
 
-  The output will be similar to this:
+The output will be similar to this:
   ::
 
      =========================================

_sources/users_guide/cloning-a-case.txt

@@ -6,11 +6,11 @@ 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.
 
-Here is the simplest example of using **create_clone**:
+Here is a simple example:
 ::
 
-   cd $CIMEROOT/scripts
-   create_clone --case $CASEROOT --clone $CLONEROOT
+   > cd $CIMEROOT/scripts
+   > create_clone --case $CASEROOT --clone $CLONEROOT
 
 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.
 
@@ -19,6 +19,6 @@ The **create_clone** script preserves any local namelist modifications made in t
 See the **help** text for more usage information.
 ::
 
-   create_clone --help
+   > create_clone --help
 
 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.