Catch UNSET required file params in EAMxx buildnml at build time

[ndkeen]

Add a build-time check in EAMxx buildnml that detects when a required file-type namelist parameter is left UNSET because no entry in namelist_defaults_eamxx.xml matches the current grid and vertical-level combination (e.g. requesting 72 levels on a grid that only has defaults for a different nlev). Previously this surfaced much later as a confusing PIO "no such file" error at run time; it now fails case.build with a clear message naming the parameter, ATM_GRID, and nlev. A new optional="true" metadata attribute lets legitimately-optional file params, such as iop_file outside of DP/IOP runs, opt out of the check.

Fixes #7873

[bfb]

[ndkeen]

Summary

• Add detection of required file/array(file) namelist parameters still equal to UNSET after selector evaluation, which previously only failed at run time with an opaque PIO error.
• Add a new optional="true" metadata attribute so parameters that may intentionally stay UNSET can opt out of the check.
• Mark iop_file in namelist_defaults_eamxx.xml as optional="true" since it's only required for DP-EAMxx/IOP runs.

Motivation

Some grid + nlev combinations lack a matching entry in namelist_defaults_eamxx.xml for certain file params (e.g. topography, IC files). This silently leaves the param as the UNSET sentinel, and the case fails only at run time with a generic PIO "No such file or directory" error that is hard to trace back to the missing namelist entry.

Details

• eamxx_buildnml.py
  • METADATA_ATTRIBS gains optional.
  • perform_consistency_checks scans the resolved namelist XML for type="file"/type="array(file)" elements still equal to UNSET, skipping elements that still carry selector attributes (a selector intentionally set UNSET, e.g. topography_filename for aquaplanet) or are marked optional="true".
  • Any remaining offenders raise expect(False, ...) naming the parameter path(s), ATM_GRID, and nlev (parsed from SCREAM_CMAKE_OPTIONS), with guidance to add the missing entry to namelist_defaults_eamxx.xml.
• namelist_defaults_eamxx.xml
  • iop_file marked optional="true".

[github-actions]

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

[mahf708]

That's a good idea but I think it's adding to the spaghetti nature of this file, which may need a deeper rework ...

[ndkeen]

Yes it might be. Should we defer cleanup and add this as-is, or try to clean up now?

Note when I try with SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel
I get

Creating test directory /pscratch/sd/n/ndk/e3sm_scratch/pm-cpu/SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel.fix72b
RUNNING TESTS:
  SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel
Starting CREATE_NEWCASE for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel with 1 procs
Finished CREATE_NEWCASE for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel in 5.710684 seconds (PASS)
Starting XML for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel with 1 procs
Finished XML for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel in 0.370572 seconds (PASS)
Starting SETUP for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel with 1 procs
Finished SETUP for test SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel in 5.704943 seconds (FAIL). [COMPLETED 1 of 1]
    Case dir: /pscratch/sd/n/ndk/e3sm_scratch/pm-cpu/SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel.fix72b
    Errors were:
        Setting up test for SMS in directory /pscratch/sd/n/ndk/e3sm_scratch/pm-cpu/SMS_D_Ln22.conusx4v1pg2_r05_oECv3.F2010-SCREAMv1-noAero.pm-cpu_intel.fix72b
        ERROR: The following required file parameter(s) are UNSET for the current configuration (ATM_GRID='ne0np4_conus_x4v1_lowcon.pg2', nlev=128):
          initial_conditions -> filename
        This typically means no entry exists in namelist_defaults_eamxx.xml for this grid + vertical-level combination.
        To fix, add an entry for ATM_GRID='ne0np4_conus_x4v1_lowcon.pg2' with nlev=128 to namelist_defaults_eamxx.xml, or switch to a supported configuration.
        See existing entries in namelist_defaults_eamxx.xml for examples.

[mahf708]

Yeah, exactly, and we likely will run into more of these things. Problem is, we have varying conventions and a thorough sweep through the code will be needed to deal with this

[Copilot]

Pull request overview

This PR improves EAMxx/CIME namelist generation by failing fast during case.build
when a required type="file" (or type="array(file)") parameter remains UNSET
after selector evaluation, which previously could surface later as a confusing PIO
runtime error.

Changes:

• Add a build-time consistency check in eamxx_buildnml.py that detects required
  file parameters left as UNSET with no matched selector attributes, and emits
  a clear error including ATM_GRID and nlev.
• Introduce an optional="true" metadata attribute for file parameters where
  UNSET is intentional/valid, and treat it as metadata (not a selector).
• Mark iop_file as optional="true" in namelist_defaults_eamxx.xml.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
components/eamxx/cime_config/namelist_defaults_eamxx.xml	Marks iop_file as optional so it can remain UNSET without triggering the new required-file check.
components/eamxx/cime_config/eamxx_buildnml.py	Adds optional metadata and a post-processing consistency check to catch unmatched required file defaults at build time.