Interactive namelist configuration

Namelists are where scientists most distrust a tool — they have hand-tuned files they do not want mangled. nwp-compose namelist makes both namelist modes interactive and previewable, and is explicit about exactly what it will and will not change.

nwp-compose namelist --component wrf --mode templated                       # guided params + preview
nwp-compose namelist --component wrf --mode byo --byo-file ./namelist.input  # patch your own

No schema risk

The editor drives the existing widget metadata and the existing byte-preserving patcher. It never changes the frozen schema; it only reads descriptors and writes values you confirm.

Templated mode — guided parameters with units

In templated mode the editor walks the component’s parameters using the same metadata that drives the GUI form fields (export_widget_descriptors). Each prompt shows the parameter’s type, unit, default, allowed choices, and help, and validates your input:

wrf · templated namelist
  time_step        [seconds]              : 60
  history_interval [minutes]  default 60  : 60
  dx_km            [km, min 0.1]          : 3
  mp_physics       [int]       default 8  : 8
  cu_physics       [int]       default 0  : 0

  Preview rendered namelist? [Y/n]

It then renders a preview of the namelist via the real render path, and writes the chosen values straight back into your workflow YAML’s components.<name>.parameters block — a lossless round-trip, because in templated mode the YAML parameters are the editable surface.

Templated preview is available where a template actually ships

Only the components that ship a Jinja2 namelist template support templated preview today: wrf, real, and geogrid (WPS). Several other components declare a templated namelist in the schema but their .j2 template is not yet shipped (the generator silently skips them). The editor checks for the template on disk and, if it is missing, tells you so and offers BYO mode instead — rather than rendering an empty namelist and reporting success.

Bring-your-own mode — patch preview, nothing silent

In BYO mode you point at your existing namelist.input. The editor first shows you the machine-readable allowlist of keys it is permitted to touch (the component’s byo_patchable_keys):

wrf · BYO namelist  (./namelist.input)
  nwp-compose will overwrite ONLY these &time_control cycle keys:
    start_year start_month start_day start_hour
    end_year   end_month   end_day   end_hour   interval_seconds run_hours
  Every other line is preserved byte-for-byte.

You provide (or it reads from the YAML) the cycle context, and it runs the patch as a dry run, showing the diff and any warnings before anything is written:

  &time_control
  - start_hour = 00,
  + start_hour = 06,
  ⚠ byo_namelist_scalar_broadcast: start_year had a per-domain vector (2024, 2023);
    a scalar 2024 would broadcast to (2024, 2024) and destroy your d02 stagger. Skipped.
  Apply? [y/N]

Your per-domain staggers are protected

If your file has a heterogeneous per-domain vector (a deliberate cold-start stagger), the patcher will not silently broadcast a scalar over it — it warns and refuses that key. This is exactly the multi-domain trap the design treats as a forecast-correctness issue, not a nit.

The honest boundary

There are namelist keys this editor cannot change, and it says so rather than pretending:

• Template-hardcoded constants (e.g. &dynamics.hybrid_opt, &physics.icloud, &namelist_quilt.nio_groups) are fixed in the Jinja2 template and are not exposed as parameters. To change them, switch the component to BYO mode and edit your own file.
• Physics scheme codes (mp_physics, cu_physics, …) are integers today, with no code-to-name table in the repo — so the editor shows the integer, not “Thompson”. A future additive enhancement will attach labeled choices to these parameters.

Why the boundary exists

Surfacing every Fortran key would mean inventing per-key metadata the frozen schema does not carry. The editor deliberately stays within what the schema and patcher already know to be safe — and points you to BYO mode for everything else. That honesty is the point.

Flags

Flag	Effect
-c, --component <type>	Required. The component to configure — wrf, real, or geogrid in this build.
--mode <templated|byo>	Required. templated prompts schema params + previews the render; byo dry-runs the cycle-key patch.
--byo-file <path>	BYO mode: your existing namelist file.
--dry-run	Preview only — write nothing, exit 0.
-o, --output <path>	Templated mode: the workflow.yaml to create/update (default ./workflow.yaml).
--force	Templated mode: overwrite --output if it exists.
--no-warnings	Suppress soft warnings (does not suppress the W-7..W-10 block).

Next

• Namelist dual-mode — the reference for how patching works.
• Tutorial: your first forecast — namelists in context.