Updating section names to more useful categories, alphabetizing names within each section by mkavulich · Pull Request #140 · ESCOMP/ESMStandardNames

mkavulich · 2026-03-12T05:00:13Z

Description

This PR reorganizes the existing standard names (with no changes, except some updated descriptions) into a new section heirarchy that removes references to specific modeling systems (specifically GFS typedefs). The new sections are mostly descriptive of the way the variable is used, and I attempted to make the sections as generic as possible. With this type of natural language organization I believe it's impossible to unambiguously assign certain variables to certain sections, but I have attempted to keep things as organized as possible. The new sections are in bold below

Base names
- Generic names
- Chemical species
- Base standard Names
Dimensions
Constants
Coordinates
Timing Variables defining or relating to timing, dates, calendar, and related concepts
Atmospheric properties
Marine
Tracers Tracers are numerically zero-mass particles advected in fluid flow, typically representing some trace gas, particle, or other physical substance
Atmospheric composition
- Gasses
- Precipitation, cloud, and hydrometeor variables
- Aerosols
- Emissions Emissions variables, contributed for the Community Emissions Data System (CEDS)
Application-specific variables
- Required CCPP framework-provided variables
- Optional CCPP framework-provided variables
System variables
Control variables Variables that indicate or control some action.
Indices Values indicating the index of some array or other data structure
Coefficients Coefficients includes scaling factors, tunable parameters, and other similar variables
Thresholds Thresholds represent some value at which the behavior of some process changes, including maximums and minimums
Stochastic physics variables
Radiation
Atmospheric surface and boundary layer
Land surface, subsurface, and vegetation properties
Convective physics parameters
Gravity wave drag parameters
Tendencies
Chemistry processes

I am very open to feedback about changing these specific section names, so please review away. I tried to keep the sections as generic as possible, avoiding references to specific models or types of parameterization, but it wasn't always possible from my point of view.

Within each section, standard names are now alphabetized to give a more logical and unambiguous sorting. This was accomplished with a new tool, tools/sort_standard_names.py, written by Claude Code running locally with gpt-oss:20b. I also added another Claude-Code-written tool, tools/list_names.py, that gives a monolithic alphabetized list of all standard names; I used this to ensure that no names were accidentally lost in the reorganization. I have thoroughly reviewed the Claude-generated scripts, and attest that I understand and approve of their functionality.

I have integrated the alphabetization check into the GitHub CI, and added a rule about this alphabetization to the Rules document.

Because the alphabetization is maintained by a tool, it does constrain the formatting and indentation of the XML. I believe this is a fine tradeoff, since the Metadata files are designed to be human-readable and it's a lesser concern for the XML. But I'm open to feedback on this.

Finally, there was a lot of text in the comment of the Dimensions section that was specific to CCPP; I have removed this text and added it to the CCPP technical documentation (NCAR/ccpp-doc#80)

Issues

Resolves #135

…, and coordinates to appropriate sections

- New sections "timing" and "stochastic physics" - Continue populating dimensions, coordinates, system variables

- Rename "state_variables" --> "atmospheric properties" - Delete and reallocate "diagnostics" section - Rearrange atmospheric_composition into subsections - New "radiation" section - Continuing to depopulate bad "GFS_typedef" sections

- Fix some indentation - Rename "precipitation and hydrometeors" to "precipitation, cloud, and hydrometeor variables" - New section "control variables"; move all "do_" prefix variables here

…adding more parameterization-specific sections - New sections "Convective physics parameters", "Gravity wave drag parameters" - Merged the two different Aerosol sections; those that are model-specific added to description - Merged "Land and water surface properties" into "Land surface, subsurface, and vegetation properties" - Added an "Other" section for now, I hope to clean this up into more discrete categories going forward

…do this automatically

…; can be used for comparisons after reorganization

…mensions

- Update CI tests to consistently call python scripts with python3 - Add execution permissions to python scripts

climbfuji · 2026-03-12T11:49:37Z

.github/workflows/pull_request_ci.yml

        run: |
-            tools/check_xml_unique.py standard_names.xml
-            tools/check_xml_unique.py standard_names.xml --field="description"
+            python3 tools/check_xml_unique.py standard_names.xml


It doesn't hurt, but why do we need this?

All of the scripts have

#!/usr/bin/env python3

in the shebang.

I just wanted to go for consistency, but you're right it's unnecessary, so I've removed it from all script calls.

climbfuji · 2026-03-12T11:52:38Z

tools/list_names.py

+from pathlib import Path
+
+try:
+    from lxml import etree


Is there a reason we can't use functionality in lib/xml_tools.py, or at least the same Python XML libraries? Why install another, potentially redundant lxml library?

ESMStandardNames/tools/lib/xml_tools.py

Line 15 in 0a13a57

import xml.etree.ElementTree as ET

I thought of this, but for some reason I thought the built-in XML couldn't output these nicely formatted and indented XML files. Turns out the built-in is actually better, fixing a few indent problems I noticed.

StandardNamesRules.rst

svahl991 · 2026-03-12T17:42:16Z

Metadata-standard-names.yaml

+- name: Marine
+  comment: null
+  standard_names:
+  - name: derivative_of_diurnal_thermocline_layer_thickness_wrt_surface_skin_temperature


I noticed that for the atmospheric variables, the surface and boundary levels, (often used for coupling?) are in a separate category from the atmospheric properties. Should we have a similar structure for Marine variables?

I'm not opposed to further categorization, but I personally don't have a good sense of how ocean variables might be binned in this way. It seems to me that in all our current contexts (being atmosphere-centric), ocean modeling deals with just the surface and boundary layers, with nothing really done below that, so it might be redundant? I'm not sure to be honest.

…output these well-formatted XMLs with just the standard libraries. It even fixes some indent problems with the original script

Wording change from Dom Co-authored-by: Dom Heinzeller <dom.heinzeller@icloud.com>

climbfuji

Thanks very much for addressing my comments. This is a lot nicer now.

I am happy with the proposed sections.

mkavulich added 18 commits February 26, 2026 10:08

First round of section rearranging: move system variables, dimensions…

406df72

…, and coordinates to appropriate sections

Continued section rearranging:

0c03e31

- New sections "timing" and "stochastic physics" - Continue populating dimensions, coordinates, system variables

Continue section rearranging

b0ecfe5

- Rename "state_variables" --> "atmospheric properties" - Delete and reallocate "diagnostics" section - Rearrange atmospheric_composition into subsections - New "radiation" section - Continuing to depopulate bad "GFS_typedef" sections

Continue section rearranging

0072024

- Fix some indentation - Rename "precipitation and hydrometeors" to "precipitation, cloud, and hydrometeor variables" - New section "control variables"; move all "do_" prefix variables here

New sections: "Coefficients" and "Land surface and vegetation"

cf61264

More new sections: Indices and Thresholds

1ac7216

New sections: Tracers and Tendencies

80019bb

All bad sections eliminated!

8032a5f

Added two accidentally-dropped names

1f7a869

Alphabetize standard names by section, include script from Claude to …

a5b0a5f

…do this automatically

Commit alphabetized metadata files as well

850d048

Adding another script from Claude that lists all names alphabetically…

1c8073a

…; can be used for comparisons after reorganization

"Humanize" the AI-generated code

c72d2b2

Check for alphabetization in CI

ce189d3

Move some variables out of "Dimensions" section that werent really di…

21896da

…mensions

If we're forcing alphabetizing now, we should probably make it a rule.

8d44149

Standardize the case and punctuation of section names

c77a77a

mkavulich requested review from MarekWlasak, cacraigucar, climbfuji, dustinswales, gold2718, grantfirl, mwaxmonsky, nusbaume, peverwhee, ss421 and svahl991 as code owners March 12, 2026 05:00

- Fix bad description caught by CI

dcfa825

- Update CI tests to consistently call python scripts with python3 - Add execution permissions to python scripts

mkavulich added 2 commits March 11, 2026 23:09

Fix logic block of new CI test

a4d1950

Missed updating metadata files

4ad95dc

climbfuji reviewed Mar 12, 2026

View reviewed changes

Remove redundant "python3" in tool calls

c9cb808

svahl991 reviewed Mar 12, 2026

View reviewed changes

mkavulich and others added 4 commits March 12, 2026 14:32

Replace external library "lxml" with "xml" builtin. Turns out we can …

175f0c6

…output these well-formatted XMLs with just the standard libraries. It even fixes some indent problems with the original script

Update StandardNamesRules.rst

3123ee7

Wording change from Dom Co-authored-by: Dom Heinzeller <dom.heinzeller@icloud.com>

Missed additional sorting run after script change

150fc06

Accidentally removed "python -m pip install PyYaml" from test setup

9e2f801

climbfuji approved these changes Mar 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updating section names to more useful categories, alphabetizing names within each section#140

Updating section names to more useful categories, alphabetizing names within each section#140
mkavulich wants to merge 26 commits intoESCOMP:mainfrom
mkavulich:feature/update_sections

mkavulich commented Mar 12, 2026

Uh oh!

climbfuji Mar 12, 2026

Uh oh!

mkavulich Mar 12, 2026

Uh oh!

climbfuji Mar 12, 2026

Uh oh!

mkavulich Mar 12, 2026

Uh oh!

Uh oh!

svahl991 Mar 12, 2026

Uh oh!

mkavulich Mar 12, 2026

Uh oh!

climbfuji left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

mkavulich commented Mar 12, 2026

Description

Issues

Uh oh!

climbfuji Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

mkavulich Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

climbfuji Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

mkavulich Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

svahl991 Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

mkavulich Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

climbfuji left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants