EAMxx: replace named initial-condition fields with constant_fields/copy_fields arrays

[bartgol]

Replace per-field entries in the EAMxx initial_conditions list with two arrays, constant_fields and copy_fields. Entries can be added or removed with atmchange.

---

Motivation

Constant initialization of a field needed an individual entry in namelist_defaults_eamxx.xml (e.g. <sfc_alb_dif_vis>0.0</sfc_alb_dif_vis>). Individual params cannot be removed with atmchange, but array entries can.

Design

This is a breaking change. Named fields are no longer supported in initial_conditions. Any testmod or user script doing atmchange initial_conditions::qr=... must switch to the array syntax. The driver now errors on any unrecognized parameter in the list, so stale inputs fail loudly instead of being silently ignored.

• constant_fields is an array(string) of entries name:value.
  • For vector fields, name:v1;v2;...;vN sets component i to vi. A single value is broadcast to all components.
  • ; is used for the components because , is the array separator. From the shell the argument must be quoted: ./atmchange initial_conditions::constant_fields+="dgnum:1e-7;2e-8;3e-7;4e-8".
• copy_fields is an array(string) of entries tgt:src. It replaces the old tgt: src string entries. That feature is only used by ad_tests.yaml, but it also needed a home once named entries were removed.
• Entries matching no field needing init are ignored, as before. A field listed twice, or in both arrays, is an error.
• Valid initial_conditions parameters are now: filename, topography_filename, constant_fields, copy_fields, perturbed_fields, and the perturbation_* / generate_perturbation_random_seed options.

./atmchange initial_conditions::constant_fields-=tke:0.0
./atmchange initial_conditions::constant_fields+=my_field:1.5

Changes

• AtmosphereDriver::set_initial_conditions: parse and validate the two arrays. initialize_constant_field now takes std::vector<double>.
• namelist_defaults_eamxx.xml:
  • The base constant_fields holds all 61 scalar entries plus the vector ones (dgnum, dgnumwet, wetdens).
  • The hgrid/compset-dependent entries (qc, qi, nc, ni, o3_volume_mix_ratio, phis for aquaplanet) are appended via append="last".
  • An empty copy_fields default is added so it can be edited with atmchange.
• Migrated all 38 hand-written test YAMLs that used named entries. A script checked that every old entry maps to exactly one new entry with the same value (0 mismatches). Descriptive inline unit comments on the wetdep_*/drydep_* entries were dropped.
• Docs: model_configuration.md and testing_for_development.md.

Testing

The full EAMxx build and tests have not been run, so please run CI, in particular the EAMxx standalone and v1 tests. What I did check:

• The entry parsing and validation code, extracted into a standalone program, compiles against the real EKAT ParameterList. It gives the expected values, and each error case (unknown param, bad or empty value, duplicate, in both arrays) errors as intended.
• The real evaluate_selectors on the defaults XML resolves constant_fields correctly for ne4, ne32, ne1024, aquaplanet and conus: 64 base entries, plus 4 / 2 / 1 / 1 conditional entries.
• atmchange -= and += work on the new arrays.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lk8pmRsy19mr1ZkXWBgV2v

[github-actions]

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

[mahf708]

this may be confusing to people (due to the quotes) but I think we may be able to avoid it altogether, yaml will still parse them correctly like above as a nested list, but you will need to come up with a better type than type="array(string)" in the xml

[bartgol]

CI status on ac868cd4, for reviewers:

• gnu / ERS_Ln22…small_kernels--eamxx-output-preset-5 reports NLFAIL (but otherwise OK). The model built and ran, and the failure is the namelist comparison against the master baseline (create_test -c -b master). This is expected for this PR, because it intentionally changes the generated initial_conditions section of scream_input.yaml, so the namelist baselines will need refreshing once it merges. Other model tests in this run should show the same NLFAIL.
• intel / ERS.ne4pg2_ne4pg2.F2010-SCREAMv1.eamxx-prod reports a plain FAIL (phase RUN). I could not read its TestStatus, because the log artifact is on a host blocked by my sandbox's egress policy. The same test also failed in the run for the unrelated PR New L128 Vertical Grid for v4 #8692 (L128 grid), but I have not confirmed that it fails for the same reason. I could not re-run it, since the workflow run is still in progress. If someone with access can share the TestStatus.log or the atm log for that job, I'll dig in.
• Passing: linter, docs build, the gnu script and nml tests, and intel-openmp / opt.

---

Generated by Claude Code