New L128 Vertical Grid for v4

[whannah1]

This changes the default vertical grid to the new L128v4. This new grid provides smoother transitions between regimes, finer and more uniform layers near the surface, and a top near 50km to facilitate improved stratospheric variability. The grid design process was originally documented here:
https://e3sm.atlassian.net/wiki/spaces/EAMXX/pages/6537019425/A+New+L128+Vertical+Grid+for+v4

The default atmosphere IC files have been updated for most configurations with new files generated from ERA5 data using HICCUP. Exceptions include RRM grids and compsets with MAMxx, which will require special attention. Namelist entries for the vertical coordinate file and the sponge layer settings are also updated.

This also updates how the vertical grid is specified. Instead of specifying SCREAM_NUM_VERTICAL_LEV as part of SCREAM_CMAKE_OPTIONS we can now specify EAMXX_VGRID, which takes a string in the form of "L128v4" or "L128v1" rather than a single integer number of levels.

[non-BFB]

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://E3SM-Project.github.io/E3SM/pr-preview/pr-8692/
Built to branch gh-pages at 2026-09-30 22:41 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[Copilot]

🔵 Needs a closer look

It changes core default model configuration (vertical grid/IC selection and build-time level derivation), which is high-impact and warrants final human review despite only minor actionable nits found.

Pull request overview

Update EAMxx/SCREAM’s default vertical grid to the new L128v4 and introduce
a higher-level case setting (EAMXX_VGRID) to select vertical grid variants
(e.g., L72, L128v1, L128v4) rather than manually setting
SCREAM_NUM_VERTICAL_LEV in SCREAM_CMAKE_OPTIONS.

Changes:

• Add EAMXX_VGRID as a CIME case variable (default L128v4) and derive
  SCREAM_NUM_VERTICAL_LEV from it at build time.
• Update namelist defaults / IC and vertical-coordinate selection to use the
  new vgrid selector keyed off EAMXX_VGRID.
• Update EAMxx testmods, scripts, and tutorial documentation to use
  EAMXX_VGRID.

File summaries

File	Description
components/eamxx/scripts/cime-nml-tests	Updates buildnml append test to switch vertical grids via EAMXX_VGRID.
components/eamxx/docs/_presentations_srcs/eamxx-tutorial-2025-part2.md	Updates tutorial commands to set EAMXX_VGRID separately from SCREAM_CMAKE_OPTIONS.
components/eamxx/cime_config/testdefs/testmods_dirs/eamxx/L72/shell_commands	Switches L72 testmod to set EAMXX_VGRID=L72.
components/eamxx/cime_config/testdefs/testmods_dirs/eamxx/L128v1/shell_commands	Adds a testmod to select the legacy 128-level vertical grid (L128v1).
components/eamxx/cime_config/testdefs/testmods_dirs/eamxx/L128/shell_commands	Updates this testmod to select L128v4 via EAMXX_VGRID.
components/eamxx/cime_config/namelist_defaults_eamxx.xml	Replaces nlev selector usage with vgrid, updates IC/vertical coordinate selections, and adjusts sponge-related defaults.
components/eamxx/cime_config/config_component.xml	Adds the EAMXX_VGRID case variable and removes vertical-level selection from SCREAM_CMAKE_OPTIONS defaults.
components/eamxx/cime_config/buildlib_cmake	Derives SCREAM_NUM_VERTICAL_LEV from EAMXX_VGRID and rejects cases that still set SCREAM_NUM_VERTICAL_LEV explicitly.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bartgol]

Looks good. One proposal. Are you wililng to wait a few days, so I can merge the PR that changes our IC to have U/V instead of horiz_winds, so we don't need to re-do the new IC files?

[whannah1]

I've updated all the initial condition files to use ERA5 data after discovering that the extrapolation of L128v1 produces very strong winds at the model top due to a thermal wind imbalance. After discussing several strategies for dealing with this it was decided that using ERA5 data was the best approach in the short term.

In the future we will need to allow EAMxx to write out initial condition format files, and HICCUP will need a way to extrapolate upwards without creating an unbalanced state, likely by blending in an observational climatology and MSIS data, and possibly adjusting the wind field to enforce thermal wind balance.

Aside from the DYAMOND2 file, I've chosen to use 2019-01-01 as the date of the ERA5 data, which is ENSO neutral based on the table of values here:
https://psl.noaa.gov/enso/mei/

The MAMxx compsets now default to using the old L128v1. We will need to generate new initial condition data at a later time.