WIP: update docs for cesm3

.github/workflows/docs.yml

@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: 'gh-pages'
           fetch-depth: 0
@@ -64,17 +64,17 @@ jobs:
     name: Build and deploy documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           lfs: true
       - name: Install python 3.x
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: '3.x'
       # https://github.com/actions/cache/blob/main/examples.md#python---pip
       - name: Cache pip
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('doc/requirements.txt') }}
@@ -91,7 +91,7 @@ jobs:
         if: |
           github.event_name == 'pull_request' &&
           github.event.pull_request.head.repo.full_name == github.repository
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{secrets.GITHUB_TOKEN}}
           publish_dir: './_build/html'

doc/source/build_cpl/adding-components.rst

@@ -1,36 +1,203 @@
-.. _adding-components:
-
-===================
-Adding components
-===================
-
-Here are the steps to add prognostic components to CIME models.
-
-There are a couple of aspects of a component interface to CIME, the
-scripts interface which controls setting up component inputs and
-building the component and the run interface which controls connecting
-the component to the coupler and through the coupler, the other
-components of the CIME based model.
-
-The component should have a subdirectory **cime_config** and this
-subdirectory should have two files **buildnml** and **buildlib** The
-**buildnml** script is used to build the components instructional,
-runtime inputs.  These have traditionally been in the form of fortran
-namelists but may also follow other formats.  The **buildnml** may
-either be called from the command line or as a python subroutine.  If
-buildnml is called from the command line it will be passed the
-caseroot directory on the command line.  If it is called as a
-subroutine, the subroutine name must be buildnml and it will take
-three arguments, a Case object, a caseroot directory and a component
-name.  The **buildlib** script will always be called from the command
-line, it is called in the case.build step and is expected to build the
-the buildlib script will be called with three arguments in order they
-are caseroot, libroot (the location of the installed library,
-typically EXEROOT/lib) and bldroot, the location of the component
-build directory.  Look at the cime internal components such as datm
-for an example.
-
-The coupler interface is dependent on which coupler is used, for the mct coupler in cime
-the component model must provide NNN_INIT_MCT, NNN_RUN_MCT, NNN_FINAL_MCT where NNN is the
-component type of the particular component (eg ATM for an atmosphere, LND for a land model)
-these subroutines are expected to be in the component library.
+.. _adding-component-cime:
+
+Adding a New Component Model to CIME
+====================================
+
+Overview
+--------
+
+CIME’s modular design allows for seamless integration of new component models into its infrastructure. To add a new component model, you must ensure compatibility with CIME’s interfaces and follow the defined setup for component registration, coupling, and testing.
+
+This guide covers the essential steps to integrate a new component model into CIME.
+
+---
+
+Prerequisites
+-------------
+
+- Familiarity with the CIME framework and component model architecture.
+- A working implementation of the new component model, including its source code, build scripts, and runtime configuration files.
+- Access to the CIME source code repository.
+
+---
+
+Steps to Add a New Component Model
+----------------------------------
+
+1. Directory Structure
+~~~~~~~~~~~~~~~~~~~~~
+
+Each component model requires a dedicated directory under the ``components/`` directory in the CIME source tree. Follow these steps:
+
+1. **Create the Directory:**
+
+   .. code-block:: bash
+
+      mkdir components/<model_name>
+
+2. **Add Source Code:**
+   Place the source code, configuration files, and necessary scripts for the new model into the directory.
+
+3. **Follow Naming Conventions:**
+   Although not required, it is recommended to use consistent naming conventions for directory names and files. It is also conventional to define a subdirectory ``cime_config`` within the component directory. This subdirectory contains all files linking CIME to the component model. Three files are required:
+
+   - **``config_component.xml``:** Describes the component and its input options.
+   - **``buildlib``:** A Python script providing the interface to build the model.
+   - **``buildnml``:** A Python script to stage the component's inputs.
+
+   Additionally, other optional interface files may be provided in ``cime_config`` to support advanced functionality:
+
+   - **``config_archive.xml``:** Defines archiving rules for model outputs.
+   - **``config_compsets.xml``:** Defines compsets specific to the component.
+   - **``config_tests.xml``:** Describes test configurations.
+   - **``config_pes.xml``:** Specifies processor layout and scaling.
+
+   If the component includes system tests, it is conventional to add a subdirectory, typically named ``SystemTests``, to house these tests. This name is configurable via ``config_files.xml``.
+
+   Example structure:
+
+   .. code-block:: text
+
+      components/<model_name>/
+      ├── src/         # Source code
+      ├── build/       # Build scripts
+      ├── cime_config/ # CIME interface files
+      │   ├── config_component.xml
+      │   ├── buildlib
+      │   ├── buildnml
+      │   ├── config_archive.xml (optional)
+      │   ├── config_compsets.xml (optional)
+      │   ├── config_tests.xml (optional)
+      │   └── config_pes.xml (optional)
+      ├── SystemTests/ # System tests (optional)
+      └── README.md    # Documentation for the component
+
+---
+
+2. Configure the Component Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CIME requires each component model to adhere to a standard interface for communication with the coupler. Implement the following:
+
+**Component-Specific Interface File:**
+For components, the interface file should be named <class>_comp_<driver>.F90, where <class> specifies the component type (e.g., atm, lnd, ice, rof, glc, wav, cpl, esp) and <driver> specifies the coupling framework (nuopc or mct).
+
+**NUOPC:** For components using the NUOPC (National Unified Operational Prediction Capability) system, the file <class>_comp_nuopc.F90 must define a public routine SetServices that sets pointers to the model's phase routines (initialize, run, and finalize).
+
+**MCT:** For components using the MCT (Model Coupling Toolkit) system, phase routines must be explicitly named as initialize, run, and finalize.
+
+2. **Initialize the Component:**
+   Include an initialization routine (``<model_name>_init``) that defines initial conditions and grid mappings.
+
+3. **Run and Finalize Routines:**
+   Ensure the model includes ``run`` and ``finalize`` routines to handle time-stepping and cleanup.
+
+---
+
+3. Register the Component
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Define Component Root Directory:**
+   Each component model must define its root directory using the variable ``COMP_ROOT_DIR_XXX`` in the ``config_files.xml`` file, where ``XXX`` represents the component class (e.g., ATM, LND, ICE). For example:
+
+   .. code-block:: xml
+
+      <entry id="COMP_ROOT_DIR_ATM">
+    <type>char</type>
+    <values>
+      <value component="datm"  >$SRCROOT/components/cdeps/datm</value>
+      <value component="satm"  >$CIMEROOT/CIME/non_py/src/components/stub_comps_$COMP_INTERFACE/satm</value>
+      <value component="xatm"  >$CIMEROOT/CIME/non_py/src/components/xcpl_comps_$COMP_INTERFACE/xatm</value>
+
+      <value component="cam"                         >$SRCROOT/components/cam/</value>
+      <value component="ufsatm"                      >$SRCROOT/components/fv3/</value>
+      <value component="myatm"                      >$SRCROOT/components/myatm/</value>
+    </values>
+    <group>case_comps</group>
+    <file>env_case.xml</file>
+    <desc>Root directory of the case atmospheric component  </desc>
+    <schema>$CIMEROOT/CIME/data/config/xml_schemas/config_compsets.xsd</schema>
+  </entry>
+
+2. **Update ``config_compsets.xml``:**
+   The ``config_compsets.xml`` file can be used to define aliases for long compset names, easing the burden of specifying full names. However, aliases are optional. 
+
+   The component name in the long compset name must match the name used in the ``description`` section of the ``config_component.xml`` file. Additionally, the ``config_component.xml`` file must include a variable ``COMP_XXX`` (where ``XXX`` is the component class, e.g., ATM, LND, ICE). This variable is essential for defining the component in the context of CIME.
+
+---
+
+4. Modify the Coupler Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Edit ``cime_config/config_files.xml``:**
+   Add entries specifying how the new component interfaces with the coupler.
+
+2. **Define Flux Mappings:**
+   Ensure fluxes exchanged between the new model and other components (e.g., atmosphere, land, ocean) are well-defined.
+
+3. **Grid Compatibility:**
+   Verify the model supports the necessary grid resolutions and that mappings are registered.
+
+---
+
+5. Test the Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Create Test Cases:**
+   Write test cases in the ``tests/`` directory to validate the integration of the new component.
+
+2. **Run Validation Tests:**
+   Use CIME’s testing framework to ensure the new component functions correctly:
+
+   .. code-block:: bash
+
+      ./create_test --xml-testlist-file <test_list.xml>
+
+3. **Debug Errors:**
+   Review log files in the ``CaseDocs`` and ``Logs`` directories for issues.
+
+---
+
+6. Document the New Component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Write Documentation:**
+   Provide a README file in the ``components/<model_name>/`` directory describing:
+
+   - The component's purpose.
+   - Input and output data requirements.
+   - Build and runtime instructions.
+
+2. **Update Central Documentation:**
+   Add details about the new component to CIME’s central documentation files.
+
+---
+
+7. Submit Changes
+~~~~~~~~~~~~~~~~~
+
+1. **Commit the Changes:**
+
+   .. code-block:: bash
+
+      git add components/<model_name>
+      git commit -m "Add new component model: <model_name>"
+
+2. **Submit a Pull Request:**
+   Push the changes to the CIME repository and submit a pull request for review.
+
+---
+
+Example
+-------
+
+Adding a New Land Model (``MyLandModel``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Create ``components/mylandmodel/`` with the required directory structure.
+2. Implement the interface routines (``mylandmodel_init``, ``mylandmodel_run``, ``mylandmodel_finalize``).
+3. Define the component's root directory in ``config_files.xml`` using the variable ``COMP_ROOT_DIR_LND``.
+4. Register ``MyLandModel`` in ``config_compsets.xml``.
+5. Define flux mappings in the coupler configuration files.
+6. Test the integration using predefined compsets and submit results for validation.
+

doc/source/what_cime/index.rst

@@ -17,20 +17,20 @@
 Overview
 *********
 
-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:
+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 four main components of the Case Control System are:
 
 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
+2. CMake files that describe the model build and compiler flags. 
+3. Python scripts that take user commands and parse the XML and CMake 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.
+4. Testing utilities to run defined system tests and report results for different configurations of the coupled system.
 
 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.
-3. Scripts to conduct ensemble-based statistical consistency tests.
-4. Netcdf file comparison program (for bit-for-bit).
+2. Scripts to conduct ensemble-based statistical consistency tests.
+3. Netcdf file comparison program (for bit-for-bit): cprnc.
 
 CIME does **not** contain the source code for any Earth System Model drivers or components. It is typically included alongside the source code of a host model. However, CIME does include pointers to external repositories that contain drivers, data models and other test components. These external components can be easily assembled to facilitate end-to-end system tests of the CIME infrastructure, which are defined in the CIME repository.