Porting CESM & CIME - version to use and appropriate documentation/testing

[jatkinson1000]

Reposting here as advised from GitHub, apologies.

I am working to port CIME to a new machine.
I have made a fair bit of progress but am now a bit stuck and had some questions I hope you can help with.

In reality the aim is to port CESM 2.x, for which I need to port CIME.
My main question is what version/tag/release/commit should I branch from?
It looks like there is currently a major refactor to version 6 going on in the master branch, but from what I can tell versions 5.6 and 5.8 are still maintained and used.
The Externals.cfg files from CESM tags I want to use often point to different tags of CIME, so I wondered where would be a sensible place to branch from?

Related to this - will CIME v6 be backwards compatible to older versions of CESM?
Would it make sense to work with v6, or start with v5?

Looking at the documentation here: 7. Porting and validating CIME on a new platform — CIME master documentation
the advice for running tests seems to differ from the wiki here: Testing
I ran the regression tests from the python script CIME/tests/scripts_regression_tests.py, but now want to explore the ones that fail in detail by running a category or specific test following the instructions here but when I look I cannot find the files CIME/tests/test_unit*

Is there different documentation available for the different versions of CIME?
I can only see master at https://esmci.github.io/cime/ though it seems this is a v5 set of docs rather than the WIP v6 on master?
Would you be able to clarify which versions of CIME the webdocs and wiki relate to?

For reference I have been working with tag cime5.6.49 which came from the CESM tag cesm2.1.5, but this was a somewhat arbitrary starting point and your advice is appreciated.

Thank you in advance for your help, and my apologies if I missed something obvious somewhere.

 

[jedwards]

If you are interested in using cmip6 data in your research then cesm2.1.5 is the version that you want and cime branch maint-5.6 is the
cime branch that works with that version of cesm. If your interest is more related to current cesm research and you would like to contribute
to upcoming cmip7 research and experiments then I recommend cesm3_0_beta03, the cime master branch is associated with this version of cesm.

The cesm2.2.2 and cime maint-5.8 are used in a few specialized cases but is not recommended for most situations.

 

[jatkinson1000]

Thanks, that's really useful.

I have one project working with 2.1.5, so will branch from maint-5.6 for that.
Another project is working with CAM7 which I believe will be in CESM3.0 and points at the cime6.0.175 tag, so guess I will need a second branch from master for that.

In terms of the documentation I see that it is now possible to select a version on the docs page, so will work off of the cesm2.1/cime5.6 version.

Looking at the master version of the docs it still suggests that xml configurations can be found in $CIMEROOT/config/$model/machines/ (see here).
But the master branch on GitHub no longer has this file, and it looks like the xml schemas are now in $CIMEROOT/CIME/data/config/ ?
Should I be looking elsewhere for the CIME-master/cesm-3.0 documentation on porting?

 

[jedwards]

I acknowledge that the cesm3 documentation is out of date and apologize for that. We will be updating the documentation as
one of the steps before the release, but it hasn't happened yet. The machines files are now in a separate repository:

GitHub - ESMCI/ccs_config_cesm: CESM CIME Case Control System configuration files

CESM CIME Case Control System configuration files. Contribute to ESMCI/ccs_config_cesm development by creating an account on GitHub.

github.com

 

[jatkinson1000]

Ah, brilliant, that's helpful, and explains why I couldn't find them anywhere!!
I'll await the v6 release eagerly. ;)

As last questions:
- if I were to fork and add a new machine to the maint-5.6 could I open a PR to have that merged back to make it easier for future users?
- I find that some of the regression tests are failing - would I be OK to ask for help on this forum after examining them if I can't work out what the issue is?

 

[jedwards]

Yes, please feel free to submit your PR to the maint-5.6 branch of cime and to ask questions about failing regression tests here.