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

Jump to bottom

merge of bjsmith changes to cime users guide #1641

Merged
merged 3 commits into from
Jun 5, 2017
Merged

merge of bjsmith changes to cime users guide #1641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
45be051
updating cime guide work through time 6/5
Jun 5, 2017
eba838f
Syncing local with upstream master. bjsmith
Jun 5, 2017
d85a6cc
update cime users guide
Jun 5, 2017
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
16 changes: 7 additions & 9 deletions doc/source/users_guide/cime-internals.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The file **$CIMEROOT/config/[cesm,acme]/config_files.xml** contains all model-sp
Where are compsets defined?
---------------------------

CIME looks at the xml element ``COMPSETS_SPEC_FILE`` in the **config_files.xml** file to determine where to find the list of supported compsets lists all model components that set compsets.
CIME looks at the xml element ``COMPSETS_SPEC_FILE`` in the **config_files.xml** file to determine which xml file to read in order to satisfy the configuration specifications defined in the compset longname.

In the case of CESM, this xml element has the contents shown here, where ``$SRCROOT`` is the root of your CESM sandbox and contains ``$CIMEROOT`` as a subdirectory:

Expand All @@ -78,8 +78,6 @@ In the case of CESM, this xml element has the contents shown here, where ``$SRCR
<schema>$CIMEROOT/config/xml_schemas/config_compsets.xsd</schema>
</entry>

.. Note:: CIME searches each of the **config_compsets.xml** files in the ``<value>`` nodes to determine if there is a match for the compset longname. If a match is found, the value of the *component* attribute is set for all other searches that appear below.

.. _defining-component-specific-compset-settings:

Where are component-specific settings defined for the target compset?
Expand All @@ -98,13 +96,13 @@ CIME first parses the following nodes to identify appropriate **config_component
...
<default_value>$CIMEROOT/driver_cpl/cime_config/config_component.xml</default_value>
..
</entry>
</entry>

<entry id="CONFIG_CPL_FILE_MODEL_SPECIFIC">
<default_value>$CIMEROOT/driver_cpl/cime_config/config_component_$MODEL.xml</default_value>
</entry>

CIME then parses each of the nodes listed below, using using the value of the *component* attribute to determine which **config_component.xml** files to use for the requested compset longname.
CIME then parses each of the nodes listed below, using using the value of the *component* attribute to determine which xml files to use for the requested compset longname.
::

<entry id="CONFIG_ATM_FILE">
Expand All @@ -116,7 +114,7 @@ CIME then parses each of the nodes listed below, using using the value of the *c
<entry id="CONFIG_ROF_FILE">
<entry id="CONFIG_WAV_FILE">

As an example, the possible atmosphere components for CESM have the following associated **config_component.xml** files.
As an example, the possible atmosphere components for CESM have the following associated xml files.
::

<entry id="CONFIG_ATM_FILE">
Expand Down Expand Up @@ -150,15 +148,15 @@ CIME looks at the xml element ``PES_SPEC_FILE`` in the **config_files.xml** file
to find the supported out-of-the-box model grids for the target component.

Each component that sets compsets has an associated **config_pes.xml** file that specifies an out-of-the-box pe-layout for those compsets.
In addition, this pe-layout might also have dependencies on the model grid and the target machine.
The pe-layout might also have dependencies on the model grid and the target machine.
Finally, there might be more than one out-of-the-box pe-layout that could be used for a compset/grid/machine combination: one for a low processor setting and one for a high processor setting.

A typical entry in **config_pes.xml** looks like this:

::

<grid name="a%T62">
<mach name="yellowstone|pronghorn">
<mach name="cheyenne">
<pes pesize="any" compset="DATM%IAF">
.......
</pes>
Expand All @@ -171,7 +169,7 @@ Given the various dependencies, CIME uses an order of precedence to determine th

CIME first searches the grid nodes for a grid match in **config_grids.xml**.
The search is based on a regular expression match for the grid longname.
All nodes that have a grid match are used in the subsequent search. If there is no grid match, all nodes that have ``<grid name="any">`` are used in the subsequent search.
All nodes that have a grid match are used in the subsequent search. If there is no grid match, all nodes that have ``<grid name="any">`` are used in the subsequent search.


2. machine match
Expand Down
39 changes: 20 additions & 19 deletions doc/source/users_guide/customizing-a-case.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Here are two examples of how to invoke **xmlchange**:
-- OR --
xmlchange -id <entry id> -val <name> -file <filename>

The ``-id`` argument identifies the variable to be changed, and ``-val`` is the intended value of that variable. See the **help** text for more usage information.:
The ``-id`` argument identifies the variable to be changed, and ``-val`` is the intended value of that variable. See the **help** text for more usage information:
::

xmlchange --help
Expand All @@ -45,7 +45,7 @@ The ``-id`` argument identifies the variable to be changed, and ``-val`` is the
Customizing the PE layout
=================================================

Settings in the ``env_mach_pes.xml`` file determine:
Settings in the **env_mach_pes.xml** file determine:

- the number of processors and OpenMP threads for each component.
- the number of instances of each component.
Expand All @@ -58,7 +58,7 @@ The component processor layout is determined by three settings:

- the number of MPI tasks.
- the number of OpenMP threads per task.
- the toot MPI processor number from the global set.
- the total MPI processor number from the global set.

The entries in **env_mach_pes.xml** have the following meanings:

Expand Down Expand Up @@ -92,15 +92,15 @@ The scientific sequencing is hardwired into the driver. Changing processor layou

For a **fully active configuration**, the atmosphere component is hardwired in the driver to never run concurrently with the land or ice component. Performance improvements associated with processor layout concurrency therefore are constrained in this case such that there is never a performance reason not to overlap the atmosphere component with the land and ice components. Beyond that constraint, the land, ice, coupler and ocean models can run concurrently, and the ocean model can also run concurrently with the atmosphere model.

An important but often misunderstood point: The root processor for any given component is set relative to the MPI global communicator, not the hardware processor counts. For instance, in the following example, the atmosphere and ocean will run concurrently, each on 64 processors with the atmosphere running on MPI tasks 0-15 and the ocean running on MPI tasks 16-79.:
An important but often misunderstood point: The root processor for any given component is set relative to the MPI global communicator, not the hardware processor counts. For instance, in the following example, the atmosphere and ocean will run concurrently, each on 64 processors with the atmosphere running on MPI tasks 0-15 and the ocean running on MPI tasks 16-79.
::

NTASKS(ATM)=6 NTHRRDS(ATM)=4 ROOTPE(ATM)=0
NTASKS(OCN)=64 NTHRDS(OCN)=1 ROOTPE(OCN)=16

The first 16 tasks are each threaded 4 ways for the atmosphere. CIME ensures that the batch submission script (**$CASE.run**) automatically requests 128 hardware processors, and the first 16 MPI tasks will be laid out on the first 64 hardware processors with a stride of 4. The next 64 MPI tasks are laid out on the second set of 64 hardware processors.

If you had set ROOTPE_OCN=64 in this example, a total of 176 processors would be requested, the atmosphere would be laid out on the first 64 hardware processors in 16x4 fashion, and the ocean model would be laid out on hardware processors 113-176. Hardware processors 65-112 would be allocated but completely idle.
If you had set ``ROOTPE_OCN`` to 64 in this example, a total of 176 processors would be requested, the atmosphere would be laid out on the first 64 hardware processors in 16x4 fashion, and the ocean model would be laid out on hardware processors 113-176. Hardware processors 65-112 would be allocated but completely idle.

**Note**: **env_mach_pes.xml** *cannot* be modified after **case.setup** has been invoked without first running the following:
::
Expand All @@ -121,8 +121,9 @@ Driver namelist variables belong in two groups:

All driver namelist variables are defined in the file **$CIMEROOT/src/drivers/mct/cime_config/namelist_definition_drv.xml**.
The variables that can be changed only by modifying xml variables appear with the *entry* attribute ``modify_via_xml="xml_variable_name"``.

All other variables that appear in the **namelist_definition_drv.xml** file can be modified by adding a keyword value pair at the end of ``user_nl_cpl``.
For example, to change the driver namelist value of ``eps_frac`` to ``1.0e-15``, add the following line to the end of the ``user_nl_cpl``
For example, to change the driver namelist value of ``eps_frac`` to ``1.0e-15``, add the following line to the end of the ``user_nl_cpl``:
::

eps_frac = 1.0e-15
Expand All @@ -139,39 +140,39 @@ Data Atmosphere (DATM)
------------------------

DATM is discussed in detail in :ref:`data atmosphere overview <data-atm>`.
DATM can be user-customized by changing either its namelist input or its stream files.
DATM can be user-customized by changing either its *namelist input files* or its *stream files*.
The namelist file for DATM is **datm_in** (or **datm_in_NNN** for multiple instances).

- To modify **datm_in**, add the appropriate keyword/value pair(s) for the namelist changes that you want at the end of the ``$CASEROOT`` file **user_nl_datm** or the **user_nl_datm_NNN** file.

- To modify the contents of a DATM stream file, first use **preview_namelists** to obtain the contents of the stream txt files in the **CaseDocs/** directory. Then:
- To modify the contents of a DATM stream file, first run **preview_namelists** to list the *streams.txt* files in the **CaseDocs/** directory. Then, in the same directory:

1. Place a *copy* of the file in ``$CASEROOT`` with the string *"user_"* prepended.
2. **Make sure you change the permissions of the file to be writeable.** (chmod 644)
3. Modify the **user_datm.streams.txt.*** file.
1. Make a *copy* of the file with the string *"user_"* prepended.
``> cp datm.streams.txt.[extension] user_datm.streams.txt[extension.``
2. **Change the permissions of the file to be writeable.**
``chmod 644 user_datm.streams.txt[extension``
3. Edit the **user_datm.streams.txt.*** file.

**Example**

If the stream txt file is **datm.streams.txt.CORE2_NYF.GISS**, the modified copy in ``$CASEROOT`` should be **user_datm.streams.txt.CORE2_NYF.GISS**.
After calling **preview_namelists** again, you should see your new modifications appear in **CaseDocs/datm.streams.txt.CORE2_NYF.GISS**.
If the stream txt file is **datm.streams.txt.CORE2_NYF.GISS**, the modified copy should be **user_datm.streams.txt.CORE2_NYF.GISS**.
After calling **preview_namelists** again, your edits should appear in **CaseDocs/datm.streams.txt.CORE2_NYF.GISS**.

------------------------
Data Ocean (DOCN)
------------------------

DOCN is discussed in detail in :ref:`data ocean overview <data-ocean>`.
DOCN can be user-customized in by either changing its namelist input or its stream files.
The namelist file for DOCN is ``docn_in`` (or ``docn_in_NNN`` for multiple instances) and its values can be changed by editing the ``$CASEROOT`` file ``user_nl_docn`` (or ``user_nl_docn_NNN`` for multiple instances).
DOCN can be user-customized by changing either its namelist input or its stream files.
The namelist file for DOCN is **docn_in** (or **docn_in_NNN** for multiple instances).

- To modify ``docn_in``, add the appropriate keyword/value pair(s) for the namelist changes you want at the end of the ``$CASEROOT`` file ``user_nl_docn`` (or ``user_nl_docn_NNN`` for multiple instances).
- To modify **docn_in** or **docn_in_NNN**, add the appropriate keyword/value pair(s) for the namelist changes that you want at the end of the file in ``$CASEROOT``.

- To modify the contents of a DOCN stream file, first use **preview_namelists** to obtain the contents of the stream txt files in ``CaseDocs/``. Then:

1. place a *copy* of this file in ``$CASEROOT`` with the string *"user_"* prepended
2. **Make sure you change the permissions of the file to be writeable** (chmod 644)
3. modify the ``user_docn.streams.txt.*`` file.

As an example, if the stream text file in ``CaseDocs/`` is ``docn.stream.txt.prescribed``, the modified copy in ``$CASEROOT`` should be ``user_docn.streams.txt.prescribed``.
As an example, if the stream text file in ``CaseDocs/`` is ``docn.stream.txt.prescribed``, the modified copy in ``$CASEROOT`` should be ``user_docn.streams.txt.prescribed``.
After changing this file and calling **preview_namelists** again, you should see your new modifications appear in ``CaseDocs/docn.streams.txt.prescribed``.

------------------------
Expand Down
Loading