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.

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

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

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.

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.

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.

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.

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.

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.

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

Open

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: remove model-specific references from documentation#4976

docs: remove model-specific references from documentation#4976
Copilot wants to merge 3 commits into
masterfrom
copilot/remove-model-references-docs

Copilot AI commented Apr 29, 2026 •

edited

Loading

Uh oh!

rljacob commented May 13, 2026 •

edited

Loading

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

billsacks May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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!

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