Configuration guide¶

Training composes small Hydra groups instead of copying one complete experiment file. configs/modular.yaml is the composition root:

defaults:
  - data: geo_sar_common10_era5
  - model: deterministic_residual
  - trainer: default
  - logging: default
  - optional experiment: null
  - _self_

seed: 42

Groups and choices¶

A choice is the YAML filename without .yaml.

List filenames below configs/<group>/ to discover new choices. Each data and model config has a local _target_; adding one does not require a central runtime dispatch table.

Select groups¶

uv run geo2wf-train \
  data=geo_sar_common10_era5 \
  model=deterministic_residual

Stage 2 selects the constructor that loads its baseline from the environment:

GEO2WF_BASELINE_CKPT=/path/to/stage1.ckpt \
uv run geo2wf-train \
  data=geo_sar_common10_era5 \
  model=residual_diffusion_deterministic_baseline

The ERA5-only residual-diffusion ablation uses model=residual_diffusion.

Override values¶

Use dotted keys for one run:

uv run geo2wf-train \
  model=deterministic_residual \
  trainer.devices=2 \
  trainer.strategy=ddp_find_unused_parameters_false \
  data.loader.batch_size=2 \
  logging.wandb.name=stage1-two-gpu

Use null, booleans, lists, and strings with Hydra syntax. Quote shell-sensitive values. Unknown keys are rejected unless Hydra's explicit +new.key=value syntax is used; adding an unrecognized runtime key normally has no effect and should be avoided.

Channel compatibility¶

DataSpec records ordered condition and target channels, spatial shape, units, and available companions. Training calls model.validate_data_spec(...) before the first batch. A mismatch therefore reports the model width and actual channel names during startup.

The checked-in ERA5 data provides 23 data-condition channels:

10 GEO + 9 ERA5 + distance + 3 solar = 23

Model configs distinguish those data channels from masks, baselines, and noisy target channels appended internally. Do not copy channel values between model families without following their assembly description.

Trainer and checkpoint semantics¶

trainer.limit_train_batches and trainer.limit_val_batches

An integer means that many batches. A float in [0,1] means a fraction.

trainer.devices

Passed to Lightning. Requesting two devices still requires two usable devices.

trainer.checkpoint.monitor

Overrides the model's checkpoint_monitor. When null, the model default is used. The named metric must be logged during every eligible validation epoch.

trainer.default_root_dir

Parent of timestamped run directories. It is not the final run directory.

Logging configuration¶

logging:
  wandb:
    enabled: true
    project: geo2wf
    name: null
    log_model: false

WANDB_DISABLED=true disables W&B construction regardless of config. CSV metrics, run manifests, resolved configuration, and checkpoints remain active. WANDB_MODE=offline retains local W&B artifacts for later synchronization.

Resolved configuration¶

Every run writes resolved-config.yaml before training and records its absolute path in run-manifest.json. Environment-backed checkpoint paths are materialized there, making the actual run input inspectable.

Legacy full YAML files¶

Existing files such as configs/config_geo_sar_10bands_era5_residual.yaml are still accepted:

uv run geo2wf-train \
  --config configs/config_geo_sar_10bands_era5_residual.yaml

A full YAML file cannot be combined with Hydra overrides. Use the grouped configuration for new work. Legacy keys (model.type, optimization, and validation) are translated by the compatibility construction path and are documented in the configuration reference.