From 45be0510a425a5d7d77e30c863d559c2634dc32b Mon Sep 17 00:00:00 2001 From: BJ Smith Date: Mon, 5 Jun 2017 14:03:18 -0600 Subject: [PATCH 1/2] updating cime guide work through time 6/5 --- doc/source/users_guide/cime-internals.rst | 16 ++++---- doc/source/users_guide/customizing-a-case.rst | 39 ++++++++++--------- 2 files changed, 27 insertions(+), 28 deletions(-) diff --git a/doc/source/users_guide/cime-internals.rst b/doc/source/users_guide/cime-internals.rst index 678c57ad077..9726843eef9 100644 --- a/doc/source/users_guide/cime-internals.rst +++ b/doc/source/users_guide/cime-internals.rst @@ -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: @@ -78,8 +78,6 @@ In the case of CESM, this xml element has the contents shown here, where ``$SRCR $CIMEROOT/config/xml_schemas/config_compsets.xsd -.. Note:: CIME searches each of the **config_compsets.xml** files in the ```` 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? @@ -98,13 +96,13 @@ CIME first parses the following nodes to identify appropriate **config_component ... $CIMEROOT/driver_cpl/cime_config/config_component.xml .. - + $CIMEROOT/driver_cpl/cime_config/config_component_$MODEL.xml -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. :: @@ -116,7 +114,7 @@ CIME then parses each of the nodes listed below, using using the value of the *c -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. :: @@ -150,7 +148,7 @@ 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: @@ -158,7 +156,7 @@ A typical entry in **config_pes.xml** looks like this: :: - + ....... @@ -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 ```` 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 ```` are used in the subsequent search. 2. machine match diff --git a/doc/source/users_guide/customizing-a-case.rst b/doc/source/users_guide/customizing-a-case.rst index ccef5633f9a..b86ac7db3cc 100644 --- a/doc/source/users_guide/customizing-a-case.rst +++ b/doc/source/users_guide/customizing-a-case.rst @@ -33,7 +33,7 @@ Here are two examples of how to invoke **xmlchange**: -- OR -- xmlchange -id -val -file -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 @@ -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. @@ -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: @@ -92,7 +92,7 @@ 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 @@ -100,7 +100,7 @@ An important but often misunderstood point: The root processor for any given com 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: :: @@ -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 @@ -139,31 +140,31 @@ Data Atmosphere (DATM) ------------------------ DATM is discussed in detail in :ref:`data atmosphere overview `. -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 `. -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: @@ -171,7 +172,7 @@ The namelist file for DOCN is ``docn_in`` (or ``docn_in_NNN`` for multiple insta 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``. ------------------------ From d85a6ccf5b1f75add8b2340858f8dda546f1e32f Mon Sep 17 00:00:00 2001 From: BJ Smith Date: Mon, 5 Jun 2017 15:42:13 -0600 Subject: [PATCH 2/2] update cime users guide --- doc/source/users_guide/porting-cime.rst | 241 ++++++++++++------------ 1 file changed, 118 insertions(+), 123 deletions(-) diff --git a/doc/source/users_guide/porting-cime.rst b/doc/source/users_guide/porting-cime.rst index 99ae7900694..beb6598e9b5 100644 --- a/doc/source/users_guide/porting-cime.rst +++ b/doc/source/users_guide/porting-cime.rst @@ -1,154 +1,149 @@ .. _porting: ********************************************* -Porting and Validating CIME on a new Platform +Porting and validating CIME on a new platform ********************************************* -One of the first steps many users will have to address is getting CIME based models running on their local machine. -This section will describe that process. +One of the first steps for many users is getting CIME-based models running on their local machine. +This section describes that process. =========================== Required libraries/packages =========================== -- A functioning MPI environment (this is not required if you are only going to run on one core with the CIME mpi-serial library) -- Build tools gmake and cmake -- A netcdf library version 4.3 or newer built with the same compiler you will use for CIME -- Optionally a pnetcdf library. - -If you are using MPI, is usually very helpful to assure that you can run a basic mpi parallel program on your machine prior to attempting a CIME port. -A simple example for assuring this functionality is in :ref:`MPI example `. +The machine needs to have: + +- a functioning MPI environment (unless you plan to run on a single core with the CIME mpi-serial library). +- build tools gmake and cmake, +- a netcdf library version 4.3 or newer built with the same compiler you will use for CIME. + +A pnetcdf library is optional. + +If you are using MPI, make sure you can run a basic MPI parallel program on your machine before you attempt a CIME port. You can use this :ref:`MPI example ` to check. ================= Steps for porting ================= -The crux of porting CIME is for you to create **at a minimum** the xml file, **config_machines.xml** and place these files in your **$HOME/.cime** directory. +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. -.. note:: - - All files in **$HOME/.cime/** are appended to the xml objects read into memory from the **$CIME/config/[model]**, , where **[model]** can currently be 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 ``acme`` or ``cesm``. -A more detailed discussion of creating these files follows. - -The following steps should be followed: +Follow these steps: #. Create a **$HOME/.cime** directory -#. Create a **$HOME/.cime/config** file. At a minumum this should contain the following two lines: +#. Create a **config** file in that directory. It should contain the following two lines: :: [main] CIME_MODEL=cesm - or + or :: [main] CIME_MODEL=acme -#. Create a **$HOME/.cime/config_machines.xml** file. +#. Create a **config_machines.xml** file in the same directory. - This file contains all the information that a user needs to set in order to configure a new machine to be CIME complaint. + This file contains all the information you need to set in order to configure a new machine to be CIME-compliant. - We provide several level of templates that you can use to create this file. + Use one of the templates described here to create the file. - If you are on a MAC and have the libraries installed with either MacPorts or HomeBrew, copy **$CIME/config/cesm/machines/userdefined_laptop_template/config_machines.xml** to **$HOME/.cime/config_machines.xml**. - - Otherwise, copy the template file - **$CIME/config/xml_schemas/config_machines_template.xml** to + - Otherwise, copy **$CIME/config/xml_schemas/config_machines_template.xml** to **$HOME/.cime/config_machines.xml**. - Fill in the contents of **$HOME/.cime/config_machines.xml** that are specific to your machine. - - For more details see :ref:`customize the config_machines.xml file `. + Fill in the contents of **$HOME/.cime/config_machines.xml** that are specific to your machine. For more details see :ref:`customize the config_machines.xml file `. - Check that your **config_machines.xml** file conforms to the CIME schema definition by doing the following: + Check to ensure that your **config_machines.xml** file conforms to the CIME schema definition by doing the following: :: xmllint --noout --schema $CIME/config/xml_schemas/config_machines.xsd $HOME/.cime/config_machines.xml -#. Optionally, create a **$HOME/.cime/config_compilers.xml** file, if you have compiler settings that are specific to your machine. +#. 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 currently be either ``acme`` or ``cesm``. + The default compiler settings are set in **$CIME/config/[model]/machines/config_compilers.xml**, where **[model]** can be either ``acme`` or ``cesm``. There is no template for **config_compilers.xml**. -#. Optionally, create a **$HOME/.cime/config_batch.xml** file if you have a batch system. +#. 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 currently be either ``acme`` 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. -#. Once you have a basic configuration for your machine defined in your **$HOME/.cime** XML files, you should interactively run **scripts_regression_test.py** from the directory **$CIME/scripts/tests**. - This script will run a number of basic unit tests starting from the simplest tests and working toward more complicated ones. +After running those steps correctly, you are ready to try a case at your target compset and resolution. + Once you have successfully created the required xml files in your .cime directory and are satisfied with the results you can merge them into the default files in the **config/$CIME_MODEL/machines** directory. + If you would like to make this machine definition available generally you may then issue a pull request to add your changes to the git repository. -#. Finally when all the previous steps have run correctly, you are ready to try a case at your target compset and resolution. - Once you have successfully created the required xml files in your .cime directory and are satisfied with the results you can merge them into the default files in the **config/$CIME_MODEL/machines** directory. - If you would like to make this machine definition available generally you may then issue a pull request to add your changes to the git repository. - .. _customizing-machine-file: =========================================== config_machines.xml - machine specific file =========================================== -The machine specific files is defined in the model-specific :ref:`config_machines.xml `. +The machine-specific file is defined in the model-specific :ref:`config_machines.xml `. -The first step a user must take to make their machine CIME-compatible is to add the appropriate entries for their machine in **config_machines.xml**. +To make a machine CIME-compatible, add the appropriate entries for the machine in **config_machines.xml**. -Each ```` tag requires the following input: +Each ```` tag requires the following input: -- ``DESC``: a text description of the machine, this field is current not used -- ``NODENAME_REGEX``: a regular expression used to identify this machine it must work on compute nodes as well as login nodes, use machine option to create_test or create_newcase if this flag is not available -- ``OS``: the operating system of this machine. +- ``DESC``: a text description of the machine +- ``NODENAME_REGEX``: a regular expression used to identify the machine. It must work on compute nodes as well as login nodes. Use the ``machine`` option for **create_test** or **create_newcase** if this flag is not available. +- ``OS``: the machine's operating system - ``PROXY``: optional http proxy for access to the internet -- ``COMPILERS``: compilers supported on this machine, comma seperated list, first is default -- ``MPILIBS``: mpilibs supported on this machine, comma seperated list, first is default -- ``PROJECT``: A project or account number used for batch jobs can be overridden in environment or $HOME/.cime/config -- ``SAVE_TIMING_DIR``: (Acme only) directory to write timing output to -- ``CIME_OUTPUT_ROOT``: Base directory for case output, the bld and run directories are written below here -- ``DIN_LOC_ROOT``: location of the inputdata directory -- ``DIN_LOC_ROOT_CLMFORC``: optional input location for clm forcing data -- ``DOUT_S_ROOT``: root directory of short term archive files -- ``DOUT_L_MSROOT``: root directory on mass store system of long term archive files -- ``BASELINE_ROOT``: Root directory for system test baseline files -- ``CCSM_CPRNC``: location of the cprnc tool, 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 this 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 this machine -- ``PES_PER_NODE``: number of physical PES per shared node on this machine, in practice the MPI tasks per node will not exceed this value -- ``PROJECT_REQUIRED``: Does this machine require a project to be specified to the batch system? -- ``mpirun``: The mpi exec to start a job on this machine. - This is itself an element that has sub elements that must be filled: - - * Must have a required ```` element +- ``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 +- ``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 +- ``DOUT_S_ROOT``: root directory of short-term archive files +- ``DOUT_L_MSROOT``: root directory on mass store system for long-term archive files +- ``BASELINE_ROOT``: root directory for system test baseline files +- ``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 +- ``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 +- ``PES_PER_NODE``: number of physical PES per shared node on the machine. In practice the MPI tasks per node will not exceed this value. +- ``PROJECT_REQUIRED``: Does this machine require a project to be specified to the batch system? +- ``mpirun``: The mpi exec to start a job on this machine. + This is itself an element that has sub-elements that must be filled: + + * Must have a required ```` element * May have optional attributes of ``compiler``, ``mpilib`` and/or ``threaded`` - * May have an optional ```` element which in turn contain one or more ```` elements. - These specify the arguments to the mpi executable and as a result are dependent on your mpi library implementation. + * May have an optional ```` element which in turn contains one or more ```` elements. + These specify the arguments to the mpi executable and are dependent on your mpi library implementation. -- ``module_system``: How and what modules to load on this system. Module systems allow you to easily load multiple compiler environments on a given machine. CIME provides support for two types of module tools: `module `_ and `soft `_. If neither of these are available on your machine, the simply set ````. - -- ``environment_variables``: environment_variables to set on this system. - This contains sub elements, ```` with the ``name`` attribute specifying the environment variable name, and the element value specifying the corresponding environment variable value. If the element value is not set, then the corresponding environment variable will be unset in your shell. +- ``module_system``: How and what modules to load on this system. Module systems allow you to easily load multiple compiler environments on a machine. CIME provides support for two types of module tools: `module `_ and `soft `_. If neither of these is available on your machine, simply set ````. - As an example, the following sets the environment variable ``OMP_STACKSIZE`` to 256M. +- ``environment_variables``: environment_variables to set on the system + This contains sub-elements ```` with the ``name`` attribute specifying the environment variable name, and the element value specifying the corresponding environment variable value. If the element value is not set, the corresponding environment variable will be unset in your shell. + + For example, the following sets the environment variable ``OMP_STACKSIZE`` to 256M: :: 256M - and the following unsets this environment variable in the shell: + The following unsets this environment variable in the shell: :: - .. note:: These changes are **ONLY** activated for the CIME build and run environment, **BUT NOT** for your login shell. To activate them for your login shell, you would source either **$CASEROOT/.env_mach_specific.sh** or **$CASEROOT/.env_mach_specific.csh**, depending on your shell. + .. note:: These changes are **ONLY** activated for the CIME build and run environment, **BUT NOT** for your login shell. To activate them for your login shell, source either **$CASEROOT/.env_mach_specific.sh** or **$CASEROOT/.env_mach_specific.csh**, depending on your shell. .. _customizing-compiler-file: @@ -156,44 +151,41 @@ 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). -There is a heirarchy that is intrinsic to this file. +The **config_compilers.xml** file defines compiler flags for building CIME (and also CESM and ACME prognostic CIME-driven components). -.# General compiler flags (e.g. for the gnu compiler) that are machine and component independent are listed first. +#. General compiler flags (e.g., for the gnu compiler) that are machine- and componen-independent are listed first. -.# Compiler flags specific to a particular operating systems are listed next. +#. Compiler flags specific to a particular operating system are listed next. -.# Compiler flags that are specific to particular machines are listed next. +#. Compiler flags that are specific to particular machines are listed next. -.# Compiler flags that are specific to particular CIME-driven components are listed last. +#. Compiler flags that are specific to particular CIME-driven components are listed last. The order of listing is a convention and not a requirement. -The possible elements and attributes that can exist in this file are documented in **$CIME/config/xml_schemas/config_compilers_v2.xsd**. +The possible elements and attributes that can exist in the file are documented in **$CIME/config/xml_schemas/config_compilers_v2.xsd**. + +To clarify several conventions: -Its useful to clarify several conventions: +- The ```` element implies that any previous definition of that element's parent will be appended with the new element value. + As an example, the following entry in **config_compilers.xml** would append the value of ``CPPDEFS`` with ``-D $OS`` where ``$OS`` is the environment value of ``OS``. -- the ```` element implies that any previous defintion of that element's parent will be appended with the new element value. - As an example, the following entry in **config_compilers.xml**, would append the value of ``CPPDEFS`` with ``-D $OS`` - where ``$OS`` is the environment value of ``OS``. - :: - + - -DOS - + -DOS + -- the ```` element overwrites its parent element's value with its element text. - As an example, the following entry would overwrite the ``CONFIG_ARGS`` for machine ``melvin`` with a ``gnu`` compiler to be ``--host=Linux``. +- The ```` element overwrites its parent element's value. For example, the following entry would overwrite the ``CONFIG_ARGS`` for machine ``melvin`` with a ``gnu`` compiler to be ``--host=Linux``. :: --host=Linux - + @@ -205,42 +197,44 @@ config_batch.xml - batch directives The **config_batch.xml** schema is defined in **$CIMEROOT/config/xml_schemas/config_batch.xsd**. -CIME currently supports the following batch systems: pbs, cobalt, lsf and slurm. +CIME supports these batch systems: pbs, cobalt, lsf and slurm. -As is the case for **config_compilers.xml**, the entries in **config_batch.xml** are heirarchical. +As is the case for **config_compilers.xml**, the entries in **config_batch.xml** are hierarchical. -.# General configurations for each system are provided at the top of the file. +#. General configurations for each system are provided at the top of the file. -.# Specific modifications for a given machine are provided below. In particular each machine should define its own queues. +#. Specific modifications for a given machine are provided below. In particular each machine should define its own queues. -.# Following is a machine specific queue section. This section details the parameters for each queue on the target machine. +#. Following is a machine-specific queue section. This section details the parameters for each queue on the target machine. -.# The last section describes several things: +#. The last section describes several things: - - each job that will be submitted to the queue for a CIME workflow + - each job that will be submitted to the queue for a CIME workflow, - - the template file that will be used to generate that job + - the template file that will be used to generate that job, - - the prerequisets that must be met before the job is submitted + - the prerequisites that must be met before the job is submitted, and - - the dependancies that must be satisfied before that job is run + - the dependencies that must be satisfied before the job is run. -By default the CIME workflow consists of two jobs (**case.run**, **case.st_archive**). +By default the CIME workflow consists of two jobs (**case.run**, **case.st_archive**). -In addition, there is **case.test** job that is used by the CIME system test workflow. +In addition, there is **case.test** job that is used by the CIME system test workflow. ==================================================== Validating your port ==================================================== -The following port validation is recommended for any new machine. -Carrying out these steps does not guarantee the model is running properly in all cases nor that the model is scientifically valid on the new machine. -In addition to these tests, detailed validation should be carried out for any new production run. -That means verifying that model restarts are bit-for-bit identical with a baseline run, that the model is bit-for-bit reproducible when identical cases are run for several months, and that production cases are monitored very carefully as they integrate forward to identify any potential problems as early as possible. -These are recommended steps for validating a port and are largely functional tests. -Users are responsible for their own validation process, especially with respect to science validation. +The following port validation is recommended for any new machine. +Carrying out these steps does not guarantee the model is running properly in all cases nor that the model is scientifically valid on the new machine. + +In addition to these tests, detailed validation should be carried out for any new production run. +That means verifying that model restarts are bit-for-bit identical with a baseline run, that the model is bit-for-bit reproducible when identical cases are run for several months, and that production cases are monitored carefully as they integrate forward to identify any potential problems as early as possible. Users are responsible for their own validation process, especially with respect to science validation. + +These are the recommended steps for validating a port: + +1. Verify functionality by performing these `functionality tests `_: -1. Verify functionality by performing these `functionality tests `_. :: ERS_D.f19_g16.X @@ -255,6 +249,7 @@ Users are responsible for their own validation process, especially with respect ERS.T62_g16.DTEST ERT.ne30_g16.B1850CN + 2. Verify performance and scaling analysis. a. Create one or two `load-balanced `_ configurations to check into ``Machines/config_pes.xml`` for the new machine. @@ -263,13 +258,13 @@ Users are responsible for their own validation process, especially with respect c. Review timing summaries in ``$CASEROOT`` for load balance and throughput. - d. Review coupler "daily" timing output for timing inconsistencies. - As has been mentioned in the section on `load balancing a case `_, useful timing information is contained in cpl.log.$date file that is produced for every run. - The cpl.log file contains the run time for each model day during the model run. - This diagnostic is output as the model runs. - You can search for tStamp in this file to see this information. - This timing information is useful for tracking down temporal variability in model cost either due to inherent model variability cost (I/O, spin-up, seasonal, etc) or possibly due to variability due to hardware. - The model daily cost is generally pretty constant unless I/O is written intermittently such as at the end of the month. + d. Review coupler "daily" timing output for timing inconsistencies. + As mentioned in `load balancing a case `_, useful timing information is contained in a **cpl.log.$date** file that is produced for every run. + The file contains the run time for each model day during the model run. + This diagnostic is output as the model runs. + Searc for ``tStamp`` in this file to see this information. + The timing information is useful for tracking down temporal variability in model cost due to either inherent model variability cost (I/O, spin-up, seasonal, and so on) or hardware. + The model daily cost generally is pretty constant unless I/O is written intermittently, such as at the end of the month. 3. Perform validation (both functional and scientific): @@ -279,11 +274,11 @@ Users are responsible for their own validation process, especially with respect c. Follow the `CCSM4.0 POP2 port-validation procedure `_. -4. Perform two, one-year runs (using the expected load-balanced configuration) as separate job submissions and verify that atmosphere history files are bfb for the last month. - Do this after some performance testing is complete; you may also combine this with the production test by running the first year as a single run and the second year as a multi-submission production run. +4. Perform two, one-year runs (using the expected load-balanced configuration) as separate job submissions and verify that atmosphere history files are BFB for the last month. + Do this after some performance testing is complete; you can also combine this with the production test by running the first year as a single run and the second year as a multi-submission production run. This will test reproducibility, exact restart over the one-year timescale, and production capability all in one test. -5. Carry out a 20-30 year 1.9x2.5_gx1v6 resolution, B_1850_CN compset simulation and compare the results with the diagnostics plots for the 1.9x2.5_gx1v6 Pre-Industrial Control (see the `CCSM4.0 diagnostics `_). +5. Carry out a 20- to 30-year 1.9x2.5_gx1v6 resolution, B_1850_CN compset simulation and compare the results with the diagnostics plots for the 1.9x2.5_gx1v6 Pre-Industrial Control (see the `CCSM4.0 diagnostics `_). Model output data for these runs will be available on the `Earth System Grid (ESG) `_ as well.