From 10455956fba14dbc0757ef83848bc8b77d5070b2 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Mon, 6 May 2024 22:17:07 -0500 Subject: [PATCH 1/6] Update cime directory content Update cime directory content. Was very out of date --- doc/source/users_guide/cime-dir.rst | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/doc/source/users_guide/cime-dir.rst b/doc/source/users_guide/cime-dir.rst index 15643de5f05..9bdb6540a63 100644 --- a/doc/source/users_guide/cime-dir.rst +++ b/doc/source/users_guide/cime-dir.rst @@ -25,25 +25,22 @@ CIME's content is split into several subdirectories. Users should start in the * ========================== ================================================================== Directory or Filename Description ========================== ================================================================== + **CIME/** **The main CIME source** + CIME/ParamGen Python tool for generating runtime params + CIME/Servers Scripts to interact with input data servers + CIME/SystemTests Scripts for create_test tests. + CIME/Tools Auxillary tools, scripts and functions. CMakeLists.txt For building with CMake + CONTRIBUTING.md Guide for contributing to CIME ChangeLog Developer-maintained record of changes to CIME ChangeLog_template Template for an entry in ChangeLog LICENSE.TXT The CIME license - README Brief intro to CIME + MANIFEST.in README.md README in markdown language - README.unit_testing Instructions for running unit tests with CIME - **config/** **Shared and model-specific configuration files** - config/cesm/ CESM-specific configuration options - config/e3sm/ E3SM-specific configuration options + conftest.py + doc Documentation for CIME in rst format + docker Container for CIME testing **scripts/** **The CIME user interface** - scripts/lib/ Infrastructure source code for CIME scripts and functions - scripts/Tools/ Auxiliary tools; scripts and functions - **src/** **Model source code provided by CIME** - 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 - src/share/ Model source code provided by CIME and used by multiple components - **tests/** **Tests** **tools/** **Standalone climate modeling tools** utils/ Some Perl source code needed by some prognostic components ========================== ================================================================== From 128c109895f13ff23552e6d372f4ec5072716c09 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 7 May 2024 00:41:05 -0500 Subject: [PATCH 2/6] Update what is cime Update what is cime to say its mostly CCS and CCS has 3 parts. --- doc/source/what_cime/index.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/source/what_cime/index.rst b/doc/source/what_cime/index.rst index f87b3bd6704..e2e3eade94a 100644 --- a/doc/source/what_cime/index.rst +++ b/doc/source/what_cime/index.rst @@ -17,12 +17,15 @@ Overview ********* -CIME, pronounced "SEAM", primarily consists of a Case Control System that supports the configuration, compilation, execution, system testing and unit testing of an Earth System Model. The two main components of the Case Control System are: +CIME (Common Infrastructure for Modeling the Earth, pronounced "SEAM") primarily consists of a Case Control System that supports the configuration, compilation, execution, system testing and unit testing of an Earth System Model. The three main components of the Case Control System are: -1. Scripts to enable simple generation of model executables and associated input files for different scientific cases, component resolutions and combinations of full, data and stub components with a handful of commands. -2. Testing utilities to run defined system tests and report results for different configurations of the coupled system. +1. XML files that describe the available machines, models and model configurations. +2. Python scripts that take user commands and parse the XML files to configure a set of models with their + build and runtime options for a specified machine and the provide additional commands to build executables and + submit jobs. +3. Testing utilities to run defined system tests and report results for different configurations of the coupled system. -CIME also contains additional stand-alone tools, including: +CIME also contains additional stand-alone tools useful for Earth system modeling including: 1. Parallel regridding weight generation program 2. Scripts to automate off-line load-balancing. From 8cfc2cb2dcc63d21245b2eef45fdd2abe09ce4db Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 7 May 2024 00:42:17 -0500 Subject: [PATCH 3/6] Add more key terms. Remove outdated info Add more key terms and remove outdated info. Mention CCS more then CIME. --- .../users_guide/introduction-and-overview.rst | 74 +++++++++++++------ 1 file changed, 53 insertions(+), 21 deletions(-) diff --git a/doc/source/users_guide/introduction-and-overview.rst b/doc/source/users_guide/introduction-and-overview.rst index 2371ef0fddc..4dbf673f2bf 100644 --- a/doc/source/users_guide/introduction-and-overview.rst +++ b/doc/source/users_guide/introduction-and-overview.rst @@ -26,7 +26,7 @@ Other prerequisites: CIME's commands are Python scripts and require a correct version of the Python interpreter to be installed. The Python version must be -greater than 2.7. Determine which version you have +greater than 2.11. Determine which version you have like this: :: @@ -37,7 +37,7 @@ Consult your local documentation if you need to update your python version. Key Terms and concepts ====================== -The following key terms and concepts are ingrained in CIME and used frequently in this documentation. +The following key terms and concepts are ingrained in the CCS and used frequently in this documentation. See the :ref:`glossary` for a more complete list of terms. **components** @@ -63,26 +63,61 @@ See the :ref:`glossary` for a more complete list of terms. *data*: For some climate problems, it is necessary to reduce feedbacks within the system by replacing an active model with a version that sends and receives the same variables to and from other models, but with the values read from files rather than computed from the equations. The values received are ignored. These active-model substitutes are called *data models*. - CIME provides data models for each of the possible components. You could add your own data model implementation of a component - but as for active models only one at a time can be used. - *stub*: For some configurations, no data model is needed, so CIME provides *stub* versions that simply occupy the - required place in the driver and do not send or receive any data. + *stub*: For some configurations, no data model is needed and one instead uses a *stub* version that simply occupies the + required place in the driver and does not send or receive any data. For example, if you are setting up an aqua-planet case + you would only need a stub for the land model. -**component set** or **compset**: The particular combination of active, data and stub versions of the 7 components is referred to +**component set** or **compset**: + + The particular combination of active, data and stub versions of the 7 components is referred to as a *component set* or *compset*. The Case Control System allows one to define - several possible compsets and configure and run them on supported platforms. See :ref:`Component Sets` for more information. + several possible compsets and configure and run them on supported platforms. + Here is an example of a component set *longname* from E3SM for a fully coupled active case: +:: + + 1850SOI_EAM%CMIP6_ELM%CNPRDCTCBCTOP_MPASSI_MPASO_MOSART_SGLC_SWAV + +See :ref:`Component Sets` for more information. "GLC" originally meant "glacier model" and is now an ice-sheet model but the GLC letters have stuck. + +**compset alias**: + + Typing a compset longname like the above can be exhausting so the CCS allows defining a shorter *compset alias* + which is a short string that substitutes for the longname. In E3SM, the above longname can be reffered to as "WCYCL1850". + +.. note:: + + Long ago, CESM established a convention for the first letter in a compset alias based + on the combination of active, data and stub components. + If you see mention of "B-case" or "F-case", it comes from these conventions. + They pre-date the introduction of a wave model as an option. + + === ======================================================================================== + A All data models + B All models fully active with stub glc + C Active ocean with data atm, river and sea ice. stub lnd, glc + D Active sea ice with data atm, ocean (slab) and river. stub lnd, glc + E Active atm, lnd, sea-ice, river, data ocean (slab), stub glc + F Active atm, lnd, river, sea-ice (thermodynamics only), data ocean (fixed SST), stub glc + G Active ocean and sea ice, data atmosphere and river, stub lnd and glc + H Active ocean and sea ice, data atmosphere, stub lnd, river and glc + I Active land and river model, data atmosphere, stub ocn, sea-ice, glc + IG Active land, river and ice-sheet, data atmosphere, stub ocn, sea-ice + S All stub models (for testing only) + X All x-compsets (2D sine waves for each component except stub glc; for testing only) + === ======================================================================================== +.. +**grid set**: -**grid** or **model grid**: Each active model must solve its equations on a numerical grid. CIME allows models within the system to have - different grids. The resulting set of all numerical grids is called the *model grid* or sometimes just the *grid*, where - *grid* is a unique name that denotes a set of numerical grids. Sometimes the *resolution* also refers to a specific set - of grids. + different grids. The resulting set of all numerical grids is called the *grid set* or usually just the *grid*. Like + the compset longnamme, the CCS allows one to define an alias to represent a grid set. This alias is also referred to + as the *grid* or sometimes the *resolution*. **machine and compilers**: The *machine* is the computer you are using to run CIME and build and run the climate model. It could be a workstation or a national supercomputer. The exact name of *machine* is typically the UNIX hostname but it could be any string. A machine - may have one more more versions of Fortran, C and C++ *compilers* that are needed to compile the model's source code and CIME + may have one more more versions of Fortran, C and C++ *compilers* that are needed to compile the model's source code and CIME. **case**: To build and execute a CIME-enabled climate model, you have to make choices of compset, model grid, @@ -95,10 +130,10 @@ See the :ref:`glossary` for a more complete list of terms. the model source code and version-controlled together, its possible to match supported out-of-the-box cases with specific versions of the model source code, promoting reproducibility and provenance. An out-of-the-box case is also called a *base case* -CIME and your environment +CCS and your environment ========================= -Before using any CIME commands, set the ``CIME_MODEL`` environment variable. In bash, use **export** as shown and replace +Before using any CCS commands, set the ``CIME_MODEL`` environment variable. In bash, use **export** as shown and replace **** with the appropriate text. Current possibilities are "e3sm" or "cesm." :: @@ -139,17 +174,14 @@ After you submit the case, you can follow the progress of your run by monitoring Repeat the command until you see the message ``case.run success``. -Discovering available cases with **query_config** +Discovering available pre-defined compsets with **query_config** ================================================= -Your CIME-driven model has many more possible cases besides the simple one in the above Quick Start. +Your CIME-driven model likely has many compset and gridset aliases defined for cases that are widely used by the +model developers. Use the utility `query_config <../Tools_user/query_config.html>`_ to see which out-of-the-box compsets, components, grids and machines are available for your model. -If CIME is downloaded in standalone mode, only standalone CIME compsets can be queried. - -If CIME is part of a CIME-driven model, `query_config <../Tools_user/query_config.html>`_ will allow you to query all prognostic component compsets. - To see lists of available compsets, components, grids and machines, look at the **help** text:: > query_config --help From 7be6553f934c63cfbc6b387a871e7a236e52b391 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 7 May 2024 00:44:56 -0500 Subject: [PATCH 4/6] Update file lists. Fix formatting Update file lists and fix formatting for table so rows aren't so long. --- doc/source/users_guide/create-a-case.rst | 56 +++++++++++--------- doc/source/users_guide/setting-up-a-case.rst | 36 ++++++++++--- 2 files changed, 60 insertions(+), 32 deletions(-) diff --git a/doc/source/users_guide/create-a-case.rst b/doc/source/users_guide/create-a-case.rst index c9257da19a6..3a74a0c87c2 100644 --- a/doc/source/users_guide/create-a-case.rst +++ b/doc/source/users_guide/create-a-case.rst @@ -63,7 +63,7 @@ In the argument to ``--case``, the case name is taken from the string after the The output from create_newcase includes information such as. - The compset longname is ``2000_DATM%NYF_SLND_DICE%SSMI_DOCN%DOM_DROF%NYF_SGLC_SWAV`` -- The model resolution is ``a%0.9x1.25_l%0.9x1.25_oi%gx1v6_r%r05_m%gx1v6_g%null_w%null`` +- The grid set is ``a%0.9x1.25_l%0.9x1.25_oi%gx1v6_r%r05_m%gx1v6_g%null_w%null`` `create_newcase <../Tools_user/create_newcase.html>`_ installs files in ``$CASEROOT`` that will build and run the model and to optionally archive the case on the target platform. @@ -74,23 +74,26 @@ Running `create_newcase <../Tools_user/create_newcase.html>`_ creates the follo - `case.build <../Tools_user/case.build.html>`_ Script to build component and utility libraries and model executable. +- `case.cmpgen_namelist <../Tools_user/case.submit.html>`_ + Script to perform namelist baseline operations (compare, generate, or both)." + +- case.qstatus + Script to query the queue on any queue system. + - `case.setup <../Tools_user/case.setup.html>`_ Script used to set up the case (create the case.run script, Macros file and user_nl_xxx files). -- `case.st_archive <../Tools_user/case.st_archive.html>`_ - Script to perform short term archiving to disk for your case output. Note that this script is run automatically by the normal CIME workflow. - - `case.submit <../Tools_user/case.submit.html>`_ Script to submit the case to run using the machine's batch queueing system. -- `case.cmpgen_namelist <../Tools_user/case.submit.html>`_ - Script to perform namelist baseline operations (compare, generate, or both)." +- `check_case <../Tools_user/check_case.html>`_ + Script to verify case is set up correctly. -- `xmlchange <../Tools_user/xmlchange.html>`_ - Script to modify values in the xml files. +- `check_input_data <../Tools_user/check_input_data.html>`_ + Script for checking for various input data sets and moving them into place. -- `xmlquery <../Tools_user/xmlquery.html>`_ - Script to query values in the xml files. +- `pelayout <../Tools_user/pelayout.html>`_ + Script to query and modify the NTASKS, ROOTPE, and NTHRDS for each component model. - `preview_namelists <../Tools_user/preview_namelists.html>`_ Script for users to see their component namelists in ``$CASEROOT/CaseDocs`` before running the model. @@ -98,15 +101,12 @@ Running `create_newcase <../Tools_user/create_newcase.html>`_ creates the follo - `preview_run <../Tools_user/preview_run.html>`_ Script for users to see batch submit and mpirun command." -- `check_input_data <../Tools_user/check_input_data.html>`_ - Script for checking for various input data sets and moving them into place. +- `xmlchange <../Tools_user/xmlchange.html>`_ + Script to modify values in the xml files. -- `check_case <../Tools_user/check_case.html>`_ - Script to verify case is set up correctly. +- `xmlquery <../Tools_user/xmlquery.html>`_ + Script to query values in the xml files. -- `pelayout <../Tools_user/pelayout.html>`_ - Script to query and modify the NTASKS, ROOTPE, and NTHRDS for each component model. - This a convenience script that can be used in place of `xmlchange <../Tools_user/xmlchange.html>`_ and `xmlquery <../Tools_user/xmlquery.html>`_. **XML Files** @@ -114,24 +114,30 @@ Running `create_newcase <../Tools_user/create_newcase.html>`_ creates the follo Defines patterns of files to be sent to the short-term archive. You can edit this file at any time. You **CANNOT** use `xmlchange <../Tools_user/xmlchange.html>`_ to modify variables in this file." -- env_mach_specific.xml - Sets a number of machine-specific environment variables for building and/or running. - You **CANNOT** use `xmlchange <../Tools_user/xmlchange.html>`_ to modify variables in this file. +- env_batch.xml + Sets batch system settings such as wallclock time and queue name." - env_build.xml Sets model build settings. This includes component resolutions and component compile-time configuration options. You must run the case.build command after changing this file. -- env_run.xml - Sets runtime settings such as length of run, frequency of restarts, output of coupler diagnostics, and short-term and long-term archiving. - This file can be edited at any time before a job starts. +- env_case.xml + Parameters set by create_newcase - env_mach_pes.xml Sets component machine-specific processor layout (see changing pe layout ). The settings in this are critical to a well-load-balanced simulation (see :ref:`load balancing `). -- env_batch.xml - Sets batch system settings such as wallclock time and queue name." +- env_mach_specific.xml + Sets a number of machine-specific environment variables for building and/or running. + You **CANNOT** use `xmlchange <../Tools_user/xmlchange.html>`_ to modify variables in this file. + +- env_run.xml + Sets runtime settings such as length of run, frequency of restarts, output of coupler diagnostics, and short-term and long-term archiving. + This file can be edited at any time before a job starts. + +- env_workflow.xml + Sets paramateres for the runtime workflow. **User Source Mods Directory** diff --git a/doc/source/users_guide/setting-up-a-case.rst b/doc/source/users_guide/setting-up-a-case.rst index feff58aaf49..2ffc473fafd 100644 --- a/doc/source/users_guide/setting-up-a-case.rst +++ b/doc/source/users_guide/setting-up-a-case.rst @@ -16,22 +16,39 @@ After creating a case or changing aspects of a case, such as the pe-layout, call This creates the following additional files and directories in ``$CASEROOT``: ============================= =============================================================================================================================== - .case.run A (hidden) file with the commands that will be used to run the model (such as “mpirun”) and any batch directives needed. - The directive values are generated using the contents - of **env_mach_pes.xml**. Running `case.setup --clean <../Tools_user/case.setup.html>`_ will remove this file. - This file should not be edited directly and instead controlled through XML variables in **env_batch.xml**. It should also - *never* be run directly. + .case.run A (hidden) file with the commands that will be used to run the model (such as “mpirun”) + + and any batch directives needed. The directive values are generated using the contents + + of **env_mach_pes.xml**. Running `case.setup --clean <../Tools_user/case.setup.html>`_ + + will remove this file. This file should not be edited directly and instead controlled + + through XML variables in **env_batch.xml**. It should also *never* be run directly. + + CaseStatus File containing a list of operations done in the current case. + + case.st_archive Script to perform short term archiving to disk for your case + + output. Note that this script is run automatically by the normal CIME workflow. + + Depends.* Lists of source code files that needs special build options. + + Macros.cmake File containing machine-specific makefile directives for your target platform/compiler. - Macros.make File containing machine-specific makefile directives for your target platform/compiler. This file is created if it does not already exist. The user can modify the file to change certain aspects of the build, such as compiler flags. + Running `case.setup --clean <../Tools_user/case.setup.html>`_ will not remove the file once it has been created. - However. if you remove or rename the Macros.make file, running `case.setup <../Tools_user/case.setup.html>`_ recreates it. + However. if you remove or rename the Macros.make file, running + + `case.setup <../Tools_user/case.setup.html>`_ recreates it. user_nl_xxx[_NNNN] Files where all user modifications to component namelists are made. **xxx** is any one of the set of components targeted for the case. + For example, for a full active CESM compset, **xxx** is cam, clm or rtm, and so on. NNNN goes from 0001 to the number of instances of that component. @@ -45,17 +62,22 @@ This creates the following additional files and directories in ``$CASEROOT``: Calling `case.setup --clean <../Tools_user/case.setup.html>`_ will *not remove* any user_nl files. Changing the number of instances in the **env_mach_pes.xml** file will cause only + new user_nl files to be added to ``$CASEROOT``. CaseDocs/ Directory that contains all the component namelists for the run. This is for reference only and files in this directory SHOULD NOT BE EDITED since they will + be overwritten at build time and runtime. .env_mach_specific.* Files summarizing the **module load** commands and environment variables that are set when + the scripts in ``$CASEROOT`` are called. These files are not used by the case but can be + useful for debugging **module load** and environment settings. software_environment.txt This file records some aspects of the computing system on which the case is built, + such as the shell environment. ============================= =============================================================================================================================== From b6ec8bee89ad6cae54897b685dc1474e2cfe1cd6 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 7 May 2024 00:45:47 -0500 Subject: [PATCH 5/6] Change section titles, move testing Change section titles and move testing up to new "use CCS". Remove timing documentation. --- doc/source/users_guide/index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 9df9b084490..c16896cdb28 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -6,7 +6,7 @@ .. _users-guide1: ####################################### -Case Control System Part 1: Basic Usage +Using the Case Control System ####################################### .. toctree:: @@ -22,12 +22,13 @@ Case Control System Part 1: Basic Usage cime-change-namelist.rst cime-config.rst cime-customize.rst + testing.rst troubleshooting.rst .. _users-guide2: ####################################################################################### -Case Control System Part 2: Configuration, Porting, Testing and Use Cases +Configuring the Case Control System ####################################################################################### .. toctree:: @@ -40,8 +41,6 @@ Case Control System Part 2: Configuration, Porting, Testing and Use Cases machine.rst pes-threads.rst porting-cime.rst - timers.rst - testing.rst unit_testing.rst multi-instance.rst workflows.rst From 7cacaa7fd5bbd14da0905ba00e010c4ae7419608 Mon Sep 17 00:00:00 2001 From: Robert Jacob Date: Tue, 7 May 2024 00:47:16 -0500 Subject: [PATCH 6/6] Add _build Add _build directory --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 0f54f714f75..a1c5112c573 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ buildnmlc buildlib.*c CIME.egg-info/ build/ +_build/ dist/ .coverage