ctsm5.2.005 release note should be changed

[samsrabin]

It should focus on the stuff in 5.2, not the stuff from 5.2.001-005.

[wwieder]

Yes. I thought that was the plan, focus on what's new in 5.2 (and if needed a note about the namelist updates that went into 001-005.

[samsrabin]

How about this, from the 5.2.0 tag annotation (slightly modified)?

---

CTSM 5.2: New surface datasets and mksurfdata_esmf tool to create them

• All new surface datasets, with updated input datasets.
• New mksurfdata_esmf tool to make surface datasets.
• Transient urban and lake by default turned on for transient cases.
• Ocean is run as baresoil rather than wetland (for clm6_0).
• The urban streams file was also updated.
• Update the README files.

New surface datasets

The new surface datasets are incompatible with previous versions (for example the ctsm5.1 series)—ctsm5.2.0 and following versions can NOT use the previous ctsm5.1 datasets, and vice versa.

See the section below about the new datasets used in their creation. Improvements in how landunits on coastal areas were also made.

Fields added to the surface datasets in ctsm5.2:

• ORGC, BULK, CFRAG, PHAQ (soil data) (currently NOT used by CTSM)
• mapunits (map units from the soil dataset)
• LANDFRAC_MKSURFDATA (for reference NOT used by CTSM)
• PCT_OCEAN (previously PCT_WETLAND was used)

Fields removed from the surface datasets in ctsm5.2:

• AREA
• PFTDATA_MASK

New input data used for making surface datasets

• New soil dataset: ISRIC/WISE dataset (Batjes, 2016; https://doi.org/10.1016/j.geoderma.2016.01.034)
• New PFT, soil-color, LAI datasets: Created by Peter J. Lawrence (2022)
• New Glacier datasets: Glacier outlines from RGI version 6 (Arendt et al., 2017).
  • vector data for GrIS and AIS retrieved from BedMachine version 4 and version 2 (Morlighem et al., 2017, 2020), respectively.
  • 30-arcsec topography/land mask retrieved GMTED2010 (Danielson and Gesch, 2011).
• New urban datasets: Gao and O'Neill (2021) and Gao and Pesaresi (2022), Oleson and Feddema (2020)
• New lake datasets: HydroLake: Messager et. al. (2016)

New mksurfdata_esmf Tool

mksurfdata_esmf is a parallel version of mksurfdata that uses ESMF regridding directly so that offline mapping files don't have to be created as a separate step. This allows surface datasets to be created at much higher resolutions.

The build for the tool is based on the CESM/CIME build system and uses cmake. This allows the build to be kept up with changes in CESM. Currently it's only setup and working on Derecho, but this design will enable it to be built and run on any CESM-supported machine (or a machine that a user ports to).

Any input grid from ccs_config can be used, or the user can supply their own mesh file to define the output grid. The user no longer has to add to the list of valid resolutions (as in the now-deprecated mksurfdata_map).

Creation of supported single point datasets. These datasets are created through the use of subset_data.

Test datasets for dynUrban, dynLake, and dynPFT is done with a simple NCO script.

All datasets can be easily made by running make all in the tools/mksurfdata_esmf/ directory.

For detailed instructions, see tools/mksurfdata_esmf/README.md.

[ekluzek]

@samsrabin thanks for pointing this out. You are right, to make these development release tags useful, we need to summarize the changes from the previous development release tag. So in this case primarily it would be ctsm5.2.0 notes. In looking at ctsm5.2.0 to ctsm5.2.005 changes it's primarily fixes needed to get ctsm5.2.0 functioning the way it was needed. One update worth mentioning is the regional and mesh file creation that went into ctsm5.2.003. You could mention the addition of 1979 and 1979-2026 datasets that went into ctsm5.2.004.

[samsrabin]

Okay, how about this? Bold is new.

---

CTSM 5.2: New surface datasets and mksurfdata_esmf tool to create them

• All new surface datasets, with updated input datasets.
• New mksurfdata_esmf tool to make global surface datasets.
• New tools to create inputs for regional simulations.
• ne0np4 grid: New 1979 surface dataset and 1979-2026 land use.
• Transient urban and lake by default turned on for transient cases.
• Ocean is run as baresoil rather than wetland (for clm6_0).
• The urban streams file was also updated.
• Update the README files.
• New FATES parameter file: Tree PFT allometry, allometric mode options, leaf maintenance scaling coefficients.

New surface datasets

The new surface datasets are incompatible with previous versions (for example the ctsm5.1 series)—ctsm5.2.0 and following versions can NOT use the previous ctsm5.1 datasets, and vice versa.

See the section below about the new datasets used in their creation. Improvements in how landunits on coastal areas were also made.

Fields added to the surface datasets in ctsm5.2:

• ORGC, BULK, CFRAG, PHAQ (soil data) (currently NOT used by CTSM)
• mapunits (map units from the soil dataset)
• LANDFRAC_MKSURFDATA (for reference NOT used by CTSM)
• PCT_OCEAN (previously PCT_WETLAND was used)

Fields removed from the surface datasets in ctsm5.2:

• AREA
• PFTDATA_MASK

New input data used for making surface datasets

• New soil dataset: ISRIC/WISE dataset (Batjes, 2016; https://doi.org/10.1016/j.geoderma.2016.01.034)
• New PFT, soil-color, LAI datasets: Created by Peter J. Lawrence (2022)
• New Glacier datasets: Glacier outlines from RGI version 6 (Arendt et al., 2017).
  • vector data for GrIS and AIS retrieved from BedMachine version 4 and version 2 (Morlighem et al., 2017, 2020), respectively.
  • 30-arcsec topography/land mask retrieved GMTED2010 (Danielson and Gesch, 2011).
• New urban datasets: Gao and O'Neill (2021) and Gao and Pesaresi (2022), Oleson and Feddema (2020)
• New lake datasets: HydroLake: Messager et. al. (2016)

New mksurfdata_esmf Tool

mksurfdata_esmf is a parallel version of mksurfdata that uses ESMF regridding directly so that offline mapping files don't have to be created as a separate step. This allows surface datasets to be created at much higher resolutions.

The build for the tool is based on the CESM/CIME build system and uses cmake. This allows the build to be kept up with changes in CESM. Currently it's only setup and working on Derecho, but this design will enable it to be built and run on any CESM-supported machine (or a machine that a user ports to).

Any input grid from ccs_config can be used, or the user can supply their own mesh file to define the output grid. The user no longer has to add to the list of valid resolutions (as in the now-deprecated mksurfdata_map).

Creation of supported single point datasets. These datasets are created through the use of subset_data.

Test datasets for dynUrban, dynLake, and dynPFT is done with a simple NCO script.

All datasets can be easily made by running make all in the tools/mksurfdata_esmf/ directory.

For detailed instructions, see tools/mksurfdata_esmf/README.md.

[ekluzek]

I like this as a framework though for documenting what we think is the best scientifically stable and tested version to use. This means the process is something like this:

• We create a minor version update tag that we start assessing if it's good to mark as a release (the minor version update will have had release testing done on it already)

Loop: Over the following till done...

• We run simulations from the tag
• If the simulations are good and we haven't found important problems we mark the minor version update as a release (which creates a DOI for it) -- exit Loop:
• If we do find problems, we create a tag that fixes the problems that has release testing done on it
• Go back to Loop:
• If we find problems with a development release tag -- we remove it as a release and go back to Loop:

Whatever is then made the development release tag for that minor version includes a description that summarizes changes since the previous development release tag.

So for example, I expect something like this to happen with ctsm5.3.0:

1. ctsm5.3.0 is created, but NOT marked as a release
2. We fix some issues in follow on ctsm5.3.001 and following tags
3. We get a tag with updated IC files that we do release testing on and have simulations that correspond to it
4. That tag is say ctsm5.3.007 -- we mark that as a release
5. The release notes describe the changes from ctsm5.2.005 until ctsm5.3.007
6. We'd leave ctsm5.3.007 as a release unless we find an important scientific problem with it -- if we did we'd delete it as a release (the DOI stays though). And we'd make a new tag that we mark as the ctsm5.3 development release tag (say ctsm5.3.21). The description for ctsm5.3.21 would then be changes from ctsm5.2.005 until ctsm5.3.21.

The idea then is that scientists would use ctsm5.3.007 as the recommended "last stable" vetted tag to use for their scientific development. It has a DOI associated with it, so it can be used for publications. Starting with the last development release tag will make it easier for everyone to bring those changes into CTSM main development.

Thoughts on that process outlined above everyone? @samsrabin @wwieder @adrifoster @slevis-lmwg @olyson We'll also talk about this next Thursday...

[samsrabin]

Yep, that's pretty much what I was thinking too! We could also mark ctsm5.3.0 as a pre-release, if we wanted, as long as that would still generate a DOI.