docs: remove model-specific references from documentation by Copilot · Pull Request #4976 · ESMCI/cime

Copilot · 2026-04-29T17:57:40Z

Description

Remove model-specific documentation (CESM namelist URLs, CESM-ECT branding, cheyenne machine references, CESM-specific paths) while preserving model references that provide useful context for users.

Removed (not directly relevant to CIME):

CESM-specific active component namelist section in setting-up-a-case.rst (CAM, CLM, CICE, POP2, CISM with cesm.ucar.edu URLs) — replaced with generic component namelist guidance
CESM-ECT branding/paths/URLs in tools/ect.rst and support-a-new-machine.rst
Cheyenne-specific test commands and paths throughout
CESM-specific path examples (/glade/scratch/cesm_user, $CESMDATAROOT)

Generalized (relevant to CIME, made model-agnostic):

Docker examples in contributing-guide.rst → <model> placeholders
Test output paths in system_testing.rst
Grid config paths in grids.rst
"CESM executable" → "model executable" in running-a-case.rst
"CAM and CLM history files" → "component history files" in troubleshooting.rst
Added context notes to model-specific example outputs (timers, preview_run)

Kept (provides useful context):

E3SM/CESM project links in footer, prerequisites, CIME_MODEL possibilities
Compset examples with model attribution, historical convention notes
XML config examples showing real values (cime_model="cesm")

Also fixes pre-existing typo: tempororal → temporal in pes.rst.

Checklist

My code follows the style guidelines of this project (black formatting)
I have performed a self-review of my own code
My changes generate no new warnings
I have added tests that exercise my feature/fix and existing tests continue to pass
I have commented my code, particularly in hard-to-understand areas
I have made corresponding additions and changes to the documentation

- Replace CESM-specific active component namelist section with generic guidance - Generalize CESM-ECT documentation to generic ECT documentation - Remove CESM-specific URLs to namelist documentation and verification website - Remove model-specific machine references (cheyenne) from examples - Generalize CESM-specific paths in examples to use placeholders - Add notes to model-specific example outputs for context - Keep model references where they provide useful context (e.g. listing CIME-driven models, historical conventions, concrete examples) Agent-Logs-Url: https://github.com/ESMCI/cime/sessions/2ef12468-32a6-42e3-a377-f05a2a354d5c Co-authored-by: jasonb5 <2191036+jasonb5@users.noreply.github.com>

Agent-Logs-Url: https://github.com/ESMCI/cime/sessions/2ef12468-32a6-42e3-a377-f05a2a354d5c Co-authored-by: jasonb5 <2191036+jasonb5@users.noreply.github.com>

rljacob · 2026-05-13T18:40:16Z

during meeting: some of these removals of CESM or E3SM don't help. Some of these sections need to be moved out fo CIME entirely (like how to make a new grid). Will give this a more thorough review and realize that really removing other model references will require a person to understand the context and make the decision.

billsacks · 2026-05-13T18:42:04Z


-6. CESM specific: If you are adding a new atmosphere grid, this means you are also generating a new land grid, and you will need to create a new CLM surface dataset. (Otherwise you can skip this step).
-   You need to first generate mapping files for CLM surface dataset (since this is a non-standard grid).
+6. If you are adding a new atmosphere grid, this means you are also generating a new land grid, and you may need to create a new land surface dataset. (Otherwise you can skip this step).


This section no longer applies to CESM. But in fact, more generally, this whole grids section needs to be rewritten since a lot of it no longer applies to CESM.

I have this generalized in another PR.

billsacks · 2026-05-13T19:38:44Z

 ---------------------------

-The distribution of CESM includes machines called **homebrew** and **centos7-linux** in the file **$CIMEROOT/config/cesm/machines/config_machines.xml**.
+Your model distribution may include generic machine definitions (e.g., **homebrew** and **centos7-linux**) in the file **$CIMEROOT/config/$model/machines/config_machines.xml**.


This is no longer the correct location... it is now model-specific

Updated to be generic and provide the user with required info to find model specific location.

billsacks · 2026-05-13T19:38:57Z

   A template to create this definition is provided in **$CIMEROOT/config/xml_schemas/config_machines_template.xml**. More details are provided in the template file.
   In addition, if you have a batch system, you will also need to add a **config_batch.xml** file to your **$HOME/.cime** directory.
-   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 ``e3sm`` or ``cesm``.
+   All files in **$HOME/.cime/** are appended to the xml objects that are read into memory from the **$CIME/config/$model** directory.


This is no longer the correct location... it is now model-specific

Updated to be generic and provide the user with required info to find model specific location.

billsacks · 2026-05-13T19:42:02Z

 After running those steps correctly, you are ready to try a case at your target compset and resolution.

-Validating a CESM port with prognostic components
+Validating a port with prognostic components


I feel like the removal of CESM here is misleading, since a lot of what's in this section is truly CESM (and maybe NorESM) specific. This probably needs to go in a new section that has a note that it's model-specific and still explicitly mentions CESM and maybe NorESM.

Added a note.

billsacks · 2026-05-13T20:18:07Z

 All examples will be run from ``$CIMEROOT`` which is should exist under ``$SRCROOT`` e.g. (``$CIMEROOT`` would be ``$SRCROOT/cime``).

-Next set the ``CIME_MODEL`` evnironment variable for your model, e.g. ``export CIME_MODEL=e3sm``.
+Next set the ``CIME_MODEL`` environment variable for your model, e.g. ``export CIME_MODEL=<model>``.


Here and elsewhere: I'm not sure I like the replacement of specific examples with the more generic <model>: the original was pretty clear that it was just an example, and the original made it somewhat more obvious what I'd do – even for cesm – than the new version.

I think it still better to use the placeholder, I've renamed it to <your-model> and then added a cross reference to a section to determine the users model name. I've also unified all instances of CIME_MODEL=... to use the same formatting.

billsacks · 2026-05-13T20:23:13Z

-``````
-
-CIME calls **$SRCROOT/components/mosart/cime_config/buildnml** to generate the MOSART namelist variables.
+ <variable_name>=<value>


I have mixed feelings on the use of angled brackets... I feel like some people can take them too literally and actually try to put them in the file... not sure what to do here... happy to defer to other people's feelings.

Replaced the bracket format with uppercase, it's a more common format.

billsacks · 2026-05-13T20:39:05Z


 Sometimes when a job times out or overflows disk space, the restart files will get mangled.
-With the exception of the CAM and CLM history files, all the restart files have consistent sizes.
+With the exception of component history files, all the restart files have consistent sizes.


This clause ("With the exception of component history files") doesn't really make sense, since history files are separate from restart files.

Updated this to only refer to restart files and check consistency between previous.

billsacks · 2026-05-13T20:48:55Z


 ==========================================
-CESM-ECT (CESM Ensemble Consistency Test):
+Ensemble Consistency Test (ECT):


I'm not sure that removing CESM is appropriate here... but this is also probably something that belongs outside of the CIME documentation.

billsacks · 2026-05-13T20:49:51Z

-$CESMDATAROOT/inputdata/validation/ensembles
-$CESMDATAROOT/inputdata/validation/uf_ensembles
-$CESMDATAROOT/inputdata/validation/pop_ensembles
+$CIME_INPUT_DATA_ROOT/validation/ensembles


Is CIME_INPUT_DATA_ROOT actually a thing? I don't see references to it elsewhere, so this change feels more confusing than helpful.

CIME_INPUT_DATA_ROOT not thing, i actually ended up reverting this entire file.

billsacks · 2026-05-13T20:51:51Z

  A test mod can contain any combination of ``user_nl_*``, ``shell_commands``, ``user_mods``, or ``params.py``.

-For example, the ``ERP`` test for an E3SM ``F-case`` can be modified to use a different radiation scheme by using ``eam-rrtmgp``::
+For example, the ``ERP`` test for an ``F-case`` can be modified to use a different radiation scheme by using ``eam-rrtmgp``::


As we discussed on the call today, I actually find this clearer in the old version where it made it clear that this example applied to E3SM.

Ok reverted this to the E3Sm specific example.

The "support a new machine" guide referenced legacy $CIMEROOT/config/$model/... paths that no longer reflect how the machines file is located (via MACHINES_SPEC_FILE in the model's config_files.xml) and described only one schema. Update paths to be model-agnostic, document the v2 (monolithic) and v3 (per-machine directory) layouts with examples, extend the xmllint snippet to cover both XSDs, and drop residual model-specific machine name examples so the page applies regardless of which model ships CIME.

The validation workflow uses the prealpha test category and pyCECT ECT tooling that target CAM/CLM/POP/CICE, which are CESM (and NorESM) constructs. Flag this up front so users of other CIME-based models look to their own documentation for the equivalent procedure.

Rename the bare <model> placeholder to <your-model> in CCS docs so readers cannot mistake it for a literal value, add a Sphinx label on the environment-setup section, and cross-reference it from the Quick Start so the valid CIME_MODEL values remain documented in a single authoritative place.

Replace angle-bracket placeholders like <variable>=<value> with ALL_CAPS tokens (VARIABLE=VALUE) so readers don't type the brackets literally. Also fix mismatched [extension] brackets in the five data model sections (DATM/DOCN/DICE/DLND/DROF).

- List all three CIME-accepted termination markers (SUCCESSFUL TERMINATION, END OF MODEL RUN, HAS ENDED) instead of just one; see TERMINATION_TEXT in CIME/case/case_run.py. - Note that the tStamp_write timing-diagnostics format is specific to MCT/cpl7-based drivers; other drivers may differ. - Replace stale external esmci.github.io URL with internal :ref: to the 'Restarting a Run' section, and add the corresponding label in running-a-case.rst.

ECT (Ensemble Consistency Test) is specific to CESM and targets CAM/CLM/POP/CICE components. Restore the original CESM-specific references, including CESMDATAROOT paths, cheyenne machine examples, and the CSEG-hosted verification web server.

The ERP F-case example with eam-rrtmgp is E3SM-specific. Restore the E3SM model reference and $E3SM source path, and clarify that pm-cpu_intel is the E3SM-specific Perlmutter CPU + Intel machine/compiler combination.

github-actions · 2026-06-24T16:54:01Z

You can preview documentation at https://esmci.github.io/cime/branch/copilot/remove-model-references-docs/html/index.html

Consolidate the explanation about mangled restart files into a single sentence for clarity.

billsacks

Thanks for the changes!

Initial plan

9d7b6bf

Copilot AI assigned Copilot and jasonb5 Apr 29, 2026

Copilot started work on behalf of jasonb5 April 29, 2026 17:57 View session

Copilot AI linked an issue Apr 29, 2026 that may be closed by this pull request

Remove model references from documentation #4975

Closed

Copilot AI and others added 2 commits April 29, 2026 18:09

docs: fix typo 'tempororal' -> 'temporal' in pes.rst

f25e523

Agent-Logs-Url: https://github.com/ESMCI/cime/sessions/2ef12468-32a6-42e3-a377-f05a2a354d5c Co-authored-by: jasonb5 <2191036+jasonb5@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Remove model references from documentation~~ docs: remove model-specific references from documentation Apr 29, 2026

Copilot finished work on behalf of jasonb5 April 29, 2026 18:11

Copilot AI requested a review from jasonb5 April 29, 2026 18:11

billsacks requested changes May 13, 2026

View reviewed changes

jasonb5 marked this pull request as ready for review June 24, 2026 14:49

jasonb5 added 7 commits June 24, 2026 08:58

docs: restore E3SM context in ERP testmods example

1ba4527

The ERP F-case example with eam-rrtmgp is E3SM-specific. Restore the E3SM model reference and $E3SM source path, and clarify that pm-cpu_intel is the E3SM-specific Perlmutter CPU + Intel machine/compiler combination.

jasonb5 requested a review from billsacks June 24, 2026 16:52

docs: tighten restart-file mangling note in troubleshooting

4aa7116

Consolidate the explanation about mangled restart files into a single sentence for clarity.

billsacks approved these changes Jun 24, 2026

View reviewed changes

jasonb5 merged commit 033eafd into master Jul 2, 2026
2 checks passed

jasonb5 deleted the copilot/remove-model-references-docs branch July 2, 2026 20:07

Uh oh!

Conversation

Copilot AI commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

rljacob commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

billsacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Apr 29, 2026 •

edited

Loading

rljacob commented May 13, 2026 •

edited

Loading