Namelist dual-mode

The model components (mpas_run, real, wrf) support two namelist modes, selected by a namelist_mode discriminator. BYO mode is the adoption feature: scientists trust their own namelists; they will not trust ours.

Templated mode renders the whole namelist from YAML parameters; bring-your-own patches only the cycle keys and preserves every other byte.

Templated mode

You provide YAML parameters; nwp-compose renders the namelist from a Jinja2 template the component owns.

components:
  forecast:
    type: wrf
    parameters:
      namelist_mode: templated
      time_step: 60
      history_interval: 60
      physics_suite: convection_permitting

• Cycle-derived keys (start_year, interval_seconds, …) are synthesized at generate time from cycling.initial_cycle_point — you never set them by hand.
• Rendering uses a sandboxed Jinja2 environment with StrictUndefined: a missing context key raises at render time rather than producing a silently blank namelist.
• Some keys are fixed in the template (e.g. &dynamics.hybrid_opt, &namelist_quilt.nio_groups) and are not exposed as parameters. To change those, use BYO mode.

Bring-your-own (BYO) mode

You provide your existing namelist; nwp-compose patches only the cycle-dependent keys and leaves everything else untouched.

components:
  forecast:
    type: wrf
    parameters:
      namelist_mode: byo_namelist
      namelist_path: ./namelist.input

What gets patched — and only that

Each component declares a machine-readable allowlist (byo_patchable_keys) of the (section, key) pairs the patcher may touch. For wrf/real that is the &time_control cycle keys (start_*/end_*, interval_seconds, run_hours). Any value outside the allowlist that the patcher is asked to change is a hard error (byo_namelist_illegal_patch) — the tool cannot be talked into editing a key it was not told is safe. geogrid has an empty allowlist: its namelist.wps is validated for existence and otherwise copied verbatim.

Byte-preservation guarantees

The patcher reconstructs each changed line preserving indentation, the = glue, and any trailing ! comment — and leaves every unchanged line byte-for-byte. It is comment-aware and string-literal-aware when scanning for the block terminator.

Per-domain vectors are protected

If your file has a heterogeneous per-domain vector — e.g. start_year = 2024, 2023, for a deliberate d02 cold-start stagger — and a scalar would broadcast over it, the patcher emits byo_namelist_scalar_broadcast and refuses rather than destroying your stagger. A matching-length vector is applied verbatim.

Known limitations (honest)

• Continuation lines (& Fortran continuations) within a patched block are currently collapsed to a single physical line — a documented Phase 3 deferral, covered by a test.
• Escaped single quotes inside single-quoted strings (don''t) are not parsed.
• Multi-domain (max_dom > 1) files can be supplied in BYO mode, but the templates assume max_dom = 1, so per-domain validation/preview is limited.

Editing interactively

nwp-compose namelist walks the templated parameters with units and validation, or previews a BYO patch (diff + warnings) before writing.

Next

• Interactive namelist configuration
• Components overview