Skip to content

Commit

Permalink
update html for PR #1631
Browse files Browse the repository at this point in the history
  • Loading branch information
@bertinia
bertinia committed Jun 1, 2017
1 parent b3ae937 commit 1d96542
Show file tree
Hide file tree
Showing 6 changed files with 97 additions and 152 deletions.
138 changes: 53 additions & 85 deletions _sources/users_guide/cime-internals.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,13 @@
CIME internals
==============

The file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` contains all model specfic information that CIME utilizes to determine
compsets, compset component settings, model grids, machines, batch queue settings, and compiler settings. ``config_files.xml`` contains
the following xml nodes that are discussed below.

The file **$CIMEROOT/config/[cesm,acme]/config_files.xml** contains all model-specific information that CIME uses to determine compsets, compset component settings, model grids, machines, batch queue settings, and compiler settings. It contains the following xml nodes, which are discussed below or in subsequent sections of this guide.
::

compset definitions:
<entry id="COMPSETS_SPEC_FILE">

component specfic compset settings:
component specific compset settings:
<entry id="CONFIG_CPL_FILE">
<entry id="CONFIG_CPL_FILE_MODEL_SPECIFIC">
<entry id="CONFIG_ATM_FILE">
Expand All @@ -30,8 +27,8 @@ the following xml nodes that are discussed below.

grid definitions:
<entry id="GRIDS_SPEC_FILE">
machine specfic definitions:

machine specific definitions:
<entry id="MACHINES_SPEC_FILE">
<entry id="BATCH_SPEC_FILE">
<entry id="COMPILERS_SPEC_FILE">
Expand All @@ -57,66 +54,59 @@ the following xml nodes that are discussed below.
Where are compsets defined?
---------------------------

CIME looks at the xml element ``COMPSETS_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` 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 where to find the list of supported compsets lists all model components that set compsets.

In the case of CESM, this xml element has the following contents
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:

::

<entry id="COMPSETS_SPEC_FILE">
<type>char</type>
<default_value>unset</default_value>
<values>
<value component="allactive">$SRCROOT/cime_config/config_compsets.xml</value>
<value component="drv" >$CIMEROOT/src/drivers/mct/cime_config/config_compsets.xml</value>
<value component="cam" >$SRCROOT/components/cam/cime_config/config_compsets.xml</value>
<value component="cism" >$SRCROOT/components/cism/cime_config/config_compsets.xml</value>
<value component="clm" >$SRCROOT/components/clm/cime_config/config_compsets.xml</value>
<value component="cice" >$SRCROOT/components/cice/cime_config/config_compsets.xml</value>
<value component="pop" >$SRCROOT/components/pop/cime_config/config_compsets.xml</value>
<value component="allactive">$SRCROOT/cime_config/config_compsets.xml</value>
<value component="drv" >$CIMEROOT/src/drivers/mct/cime_config/config_compsets.xml</value>
<value component="cam" >$SRCROOT/components/cam/cime_config/config_compsets.xml</value>
<value component="cism" >$SRCROOT/components/cism/cime_config/config_compsets.xml</value>
<value component="clm" >$SRCROOT/components/clm/cime_config/config_compsets.xml</value>
<value component="cice" >$SRCROOT/components/cice/cime_config/config_compsets.xml</value>
<value component="pop" >$SRCROOT/components/pop/cime_config/config_compsets.xml</value>
</values>
<group>case_last</group>
<file>env_case.xml</file>
<desc>file containing specification of all compsets for primary component (for documentation only - DO NOT EDIT)</desc>
<schema>$CIMEROOT/config/xml_schemas/config_compsets.xsd</schema>
</entry>

where ``$SRCROOT`` is the root of your CESM sandbox and contains ``$CIMEROOT`` as a sub-directory.

.. note:: CIME searches each of the above ``<config_compsets.xml>`` files in the ``<value>`` nodes to determine if there is a match for the compset longname. If a match is found then the value of the ``component`` attribute is set for all other searches that appear below.
.. 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-specfic-compset-settings:
.. _defining-component-specific-compset-settings:

Where are component-specific settings defined for the target compset?
---------------------------------------------------------------------

Every model component contains a ``config_component.xml`` file that has two functions:
Every model component contains a **config_component.xml** file that has two functions:

1. Specifying the component-specfici definitions of what can appear after the ``%`` in the compset longname, (e.g. ``DOM`` in ``DOCN%DOM``).
1. Specifying the component-specific definitions of what can appear after the ``%`` in the compset longname, (for example, ``DOM`` in ``DOCN%DOM``).

2. Specifying the compset-specific ``$CASEROOT`` xml variables.
2. Specifying the compset-specific ``$CASEROOT`` xml variables.


CIME first parses the following nodes to determine the ``config_component.xml`` files for the driver. There are two such files, one is model independent
CIME first parses the following nodes to identify appropriate **config_component.xml** files for the driver. There are two such files; one is model-independent and the other is model-specific.
::

<entry id="CONFIG_CPL_FILE">
...
...
<default_value>$CIMEROOT/driver_cpl/cime_config/config_component.xml</default_value>
..
</entry>

and the other is model specific
::
</entry>

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

CIME the parses each of the following nodes
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.
::

<entry id="CONFIG_ATM_FILE">
<entry id="CONFIG_ESP_FILE">
<entry id="CONFIG_ICE_FILE">
Expand All @@ -126,46 +116,44 @@ CIME the parses each of the following nodes
<entry id="CONFIG_ROF_FILE">
<entry id="CONFIG_WAV_FILE">

using the value of the ``component`` attribute determined
to determine the list of ``config_component.xml`` files to use for the requested compset longname.

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 **config_component.xml** files.
::

<entry id="CONFIG_ATM_FILE">
<type>char</type>
<default_value>unset</default_value>
<values>
<value component="cam" >$SRCROOT/components/cam/cime_config/config_component.xml</value>
<value component="datm">$CIMEROOT/components/data_comps/datm/cime_config/config_component.xml</value>
<value component="satm">$CIMEROOT/components/stub_comps/satm/cime_config/config_component.xml</value>
<value component="xatm">$CIMEROOT/components/xcpl_comps/xatm/cime_config/config_component.xml</value>
<value component="cam" >$SRCROOT/components/cam/cime_config/config_component.xml</value>
<value component="datm">$CIMEROOT/components/data_comps/datm/cime_config/config_component.xml</value>
<value component="satm">$CIMEROOT/components/stub_comps/satm/cime_config/config_component.xml</value>
<value component="xatm">$CIMEROOT/components/xcpl_comps/xatm/cime_config/config_component.xml</value>
</values>
<group>case_last</group>
<file>env_case.xml</file>
<desc>file containing specification of component specific definitions and values(for documentation only - DO NOT EDIT)</desc>
<schema>$CIMEROOT/cime_config/xml_schemas/entry_id.xsd</schema>
</entry>

If the compset's atm ``component`` attribute is ``datm`` then the file ``$CIMEROOT/components/data_comps/datm/cime_config/config_component.xml`` will specify all possible component settings for ``DATM``.
If the compset's atm component attribute is ``datm``, the file ``$CIMEROOT/components/data_comps/datm/cime_config/config_component.xml`` specifies all possible component settings for ``DATM``.

The schema for every ``config_component.xml`` file has a ``<description>`` node that specfies all possible values that can follow the ``%`` character in the compset name.
The schema for every **config_component.xml** file has a ``<description>`` node that specifies all possible values that can follow the ``%`` character in the compset name. To list the possible values, use the **manage_case** command with ``--query-component-name`` as shown in this example for CESM cam:
::

As an example, use the command **manage_case --query-component-name cam** to query the possibly ``%`` modifiers for CESM cam.
manage_case --query-component-name cam

.. _defining-pes:

Where are pe-settings defined for the target compset and model grid?
--------------------------------------------------------------------

CIME looks at the xml element ``PES_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` to determine where
to find the supported out-of-the-box model grids for the target ``component``. Currently, this node has the following contents (where ``MODEL`` can be ``[acme, cesm]``.
CIME looks at the xml element ``PES_SPEC_FILE`` in the **config_files.xml** file to determine where
to find the supported out-of-the-box model grids for the target component.

Each ``component`` that sets compsets, must also have an associated ``config_pes.xml`` file that specifies an out-of-the-box pe-layout for those compsets.
In addition, this out-of-the-box pe-layout might also have dependencies on the model grid and the target machine.
Finally, there might be more than one-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.
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.
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 the following:
A typical entry in **config_pes.xml** looks like this:

::

Expand All @@ -177,50 +165,32 @@ A typical entry in ``config_pes.xml`` looks like the following:
</mach>
</grid>

Given these various dependencies, an order of precedence has been established to determine the optimal match. This order is as follows:
Given the various dependencies, CIME uses an order of precedence to determine the optimal match. This order is as follows:

1. grid match

CIME first searches the grid nodes and tries to find a grid match in ``config_grids.xml``.
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 then used in the subsequent search. If there is no grid match, than 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

CIME next uses the list of nodes obtained in (1.) to match on the machine name using the ``<mach>`` nodes. If there is no machine match, then all nodes in (1.)
that have
::

<machine name="any">

are used in the subsequent search.
CIME next uses the list of nodes obtained in the grid match to search for the machine name using the ``<mach>`` nodes. If there is no machine match, then all nodes with ``<machine name="any">`` are used in the subsequent search.


3. pesize and compset match

CIME next uses the list of nodes obtained in (2.) to match on pesize and compset using the ``<pes>`` nodes. If there is no match, then the node in (2.) that has
::
CIME next uses the list of nodes obtained in the machine match to search for pesize and compset using the ``<pes>`` nodes. If there is no match, the node with ``<pes pesize="any" compset="any">`` is used.

<pes pesize="any" compset="any">

will be the one used.


**create_newcase** outputs the matches that are found in determining the best out-of-the-box peylayout.
The **create_newcase** script outputs the matches that are found in determining the best out-of-the-box pe-layout.

.. _defining-model-grids:

Where are model grids defined?
------------------------------

CIME looks at the xml node ``GRIDS_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` to determine where
to find the supported out-of-the-box model grids for the target model. Currently, this node has the following contents (where ``MODEL`` can be ``[acme, cesm]``.
CIME looks at the xml node ``GRIDS_SPEC_FILE`` in the **config_files.xml** file to identify supported out-of-the-box model grids for the target model. The node has the following contents:
::

<entry id="GRIDS_SPEC_FILE">
Expand All @@ -237,8 +207,7 @@ to find the supported out-of-the-box model grids for the target model. Currently
Where are machines defined?
---------------------------

CIME looks at the xml node ``MACHINE_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` to determine where
to find the supported out-of-the-box machines for the target model. Currently, this node has the following contents (where ``MODEL`` can be ``[acme, cesm]``.
CIME looks at the xml node ``MACHINE_SPEC_FILE`` in the **config_files.xml** file to identify supported out-of-the-box machines for the target model. The node has the following contents:
::

<entry id="MACHINES_SPEC_FILE">
Expand All @@ -250,15 +219,14 @@ to find the supported out-of-the-box machines for the target model. Currently, t
<schema>$CIMEROOT/cime_config/xml_schemas/config_machines.xsd</schema>
</entry>

As part of porting, you will need to :ref:`customize the config_machines.xml file <customizing-machine-file>`.
When porting, you will need to :ref:`customize the config_machines.xml file <customizing-machine-file>`.

.. _defining-the-batch-system:

Where are batch system settings defined?
----------------------------------------

CIME looks at the xml node ``BATCH_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` to determine where
to find the supported out-of-the-box batch system details for the target model. Currently, this node has the following contents (where ``MODEL`` can be ``[acme, cesm]``.
CIME looks at the xml node ``BATCH_SPEC_FILE`` in the **config_files.xml** file to identify supported out-of-the-box batch system details for the target model. The node has the following contents:
::

<entry id="BATCH_SPEC_FILE">
Expand All @@ -270,15 +238,14 @@ to find the supported out-of-the-box batch system details for the target model.
<schema>$CIMEROOT/cime_config/xml_schemas/config_batch.xsd</schema>
</entry>

As part of porting, you will need to :ref:`customize the config_batch.xml file <customizing-batch-file>`.
When porting, you will need to :ref:`customize the config_batch.xml file <customizing-batch-file>`.

.. _defining-compiler-settings:

Where are compiler settings defined?
------------------------------------

CIME looks at the xml element ``COMPILERS_SPEC_FILE`` in the file ``$CIMEROOT/config/[cesm,acme]/config_files.xml`` to determine where
to find the supported out-of-the-box batch system details for the target model. Currently, this node has the following contents (where ``MODEL`` can be ``[acme, cesm]``.
CIME looks at the xml element ``COMPILERS_SPEC_FILE`` in the **config_files.xml** file to identify supported out-of-the-box compiler details for the target model. The node has the following contents:
::

<entry id="COMPILERS_SPEC_FILE">
Expand All @@ -290,5 +257,6 @@ to find the supported out-of-the-box batch system details for the target model.
<schema>$CIMEROOT/cime_config/xml_schemas/config_compilers_v2.xsd</schema>
</entry>

As part of porting, you will need to :ref:`customize the config_batch.xml file <customizing-compiler-file>`.
When porting, you will need to :ref:`customize the config_compilers.xml file <customizing-compiler-file>`.


2 changes: 1 addition & 1 deletion _sources/users_guide/troubleshooting.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ If the model was running fine, but the wallclock limit was reached, either reduc
If the model hangs and then times out, that usually indicates an MPI or file system problem or possibly a model problem. If you suspect an intermittent system problem, try resubmitting the job. Also send a help request to local site consultants to provide them with feedback about system problems and to get help.

Another error that can cause a timeout is a slow or intermittently slow node.
The **cpl.log** file normally outputs the time used for every model simulation day. To review that data, grep the **cpl.log** file for the string``tStamp`` as shown here:
The **cpl.log** file normally outputs the time used for every model simulation day. To review that data, grep the **cpl.log** file for the string ``tStamp`` as shown here:
::

grep tStamp cpl.log.* | more
Expand Down
Binary file modified objects.inv
View file
Binary file not shown.
2 changes: 1 addition & 1 deletion searchindex.js
View file

Large diffs are not rendered by default.

Loading

0 comments on commit 1d96542

Please sign in to comment.