Config reference

A FUSION run is configured by a single YAML file. load_config reads it, validates it against the Pydantic models in fusion.config, and returns a Config object you pass to fusion.run (or to the individual pipeline steps). A validation error is re-raised as a ValueError naming the file, so a malformed config fails fast with the offending field in the message.

Each top-level key configures one part of the pipeline. Start from the complete example, then jump to the section you want to change.

At a glance

Key	Pipeline step	Controls
ensemble	load_data	Where the PSU-ISM run files live and how to read them.
observations	load_data	Which bundled observation version to score against.
grid	load_data	Target grid and regridding method.
regions	prepare	Region definitions for per-region scoring.
metric	prepare + sample	Comparison metric and per-stream uncertainty caps.
inference	sample	PyMC / NUTS sampler settings and likelihood weights.
projection	project	Forward-projection target year and quantity.

Defaults come from the prototype

Most fields have defaults that reproduce the PSUISM_HBM_V1 prototype bit-exactly. The fields under metric, inference.stream_weights, and inference.subsample are pinned science values. They are surfaced in config so they land in run metadata, not because they are meant to be tuned casually. Changing them breaks the validation baseline. See Validation and the Terminology glossary for bit-exactness and science territory.

Complete example

A config with every section filled in with its defaults:

ensemble:
  path: /path/to/psuism/runs/
  adapter: psuism
observations:
  source: source-coop
  version: "2026-04-30"
grid:
  target: obs_8km
  method: bilinear           # default decided Apr 27 (faster than conservative)
regions:
  source: imbie_basins       # MB / IMBIE basins via xOPR (NSIDC-0709 v2)
metric:
  type: pixelwise_gaussian
inference:
  obs_alpha: 0.5             # uniform per-observation weight (prototype default)
  stream_weights:
    thick: 0.5
    vel: 0.5
  subsample:
    size: 20000
    seed: 42
  draws: 500
  tune: 1000
  chains: 4
  target_accept: 0.95
projection:
  target_year: 2100
  quantity: grounded_ice_volume

Save it as my_run.yaml, edit ensemble.path, and run it as shown in Getting started.

ensemble

Where the ensemble lives on disk and how to read it. Consumed by load_data. path is the directory of PSU-ISM run files (one NetCDF per member, each read into an xarray.Dataset); adapter selects the reader.

ensemble:
  path: /path/to/psuism/runs/
  adapter: psuism

fusion.config.EnsembleConfig

Bases: BaseModel

Where the ensemble lives on disk and how to read it.

observations

Which bundled observations to score against. Consumed by load_data. version is an ISO date selecting a published bundle; the first run downloads it from Source.Coop and caches it under FUSION_CACHE (later runs are offline). See File locations.

observations:
  source: source-coop
  version: "2026-04-30"

fusion.config.ObservationsConfig

Bases: BaseModel

Which bundled observations to score against, and where to fetch them.

grid

Target grid the ensemble is regridded onto before scoring. Consumed by load_data.

grid:
  target: obs_8km
  method: bilinear      # use "conservative" for fluxes / extensive fields

v1 grid handling

v1 enforces that obs and ensemble already share a 761×761 (y, x) grid; native-resolution regridding is deferred to v1.1 and raises NotImplementedError. method is recorded in metadata but does not yet drive a regrid.

fusion.config.GridConfig

Bases: BaseModel

Target grid that the ensemble is regridded onto before scoring.

regions

Region definitions used for per-region scoring and subsampling. Consumed by prepare. imbie_basins uses the IMBIE / MEaSUREs NSIDC-0709 v2 basins.

regions:
  source: imbie_basins

fusion.config.RegionsConfig

Bases: BaseModel

Region definitions used for per-region scoring.

metric

Which comparison metric to use, plus the per-stream uncertainty caps applied in prepare to drop high-σ pixels. prepare finite-differences the gridded fields and flattens them into the 1-D numpy.ndarray vectors the likelihood sums over. v1 ships only the pixelwise Gaussian likelihood.

metric:
  type: pixelwise_gaussian
  thick_unc_threshold: 50.0   # m/yr   (prototype default)
  vel_unc_threshold: 10.0     # m/yr²  (prototype default)

Pinned science values

thick_unc_threshold and vel_unc_threshold default to the prototype's hardcoded thresholds. Changing them changes which pixels are masked and breaks Layer 1 bit-exactness against the validation baseline.

fusion.config.MetricConfig

Bases: BaseModel

Which comparison metric to use. v1 ships only the pixelwise Gaussian likelihood.

inference

The PyMC inference settings. The likelihood weights (obs_alpha, stream_weights) and the subsample are pinned science values; draws, tune, chains, target_accept, and seed are the standard sampler knobs. Consumed by sample.

inference:
  obs_alpha: 0.5
  stream_weights:
    thick: 0.5
    vel: 0.5
  subsample:
    size: 20000
    seed: 42
  draws: 500
  tune: 1000
  chains: 4
  target_accept: 0.95
  seed: 42

Sampler knobs. draws, tune, chains, and seed map directly onto the same-named arguments of pm.sample (seed is passed as its random_seed). target_accept is the NUTS step-size tuning target; raise it toward 0.99 to suppress divergences. The model itself uses half-normal priors (pm.HalfNormal), combines the per-stream log-likelihoods through a pm.Potential, and exposes the member weights as a softmax pm.Deterministic. For what to do when a run does not converge, see Interpreting results.

Pinned science values

obs_alpha, stream_weights, and subsample (size / seed) default to the prototype's values. They are exposed so they appear in run metadata and so v1.1 can evolve them, not for routine tuning. Changing them breaks bit-exactness. Note subsample.seed (the pixel draw) is independent of inference.seed (the MCMC seed); both default to 42.

fusion.config.InferenceConfig

Bases: BaseModel

PyMC inference settings.

Includes a per-observation weight (obs_alpha), per-stream likelihood weights, the subsample, and the standard NUTS knobs (draws, tune, chains, target_accept).

fusion.config.StreamWeights

Bases: BaseModel

Per-stream multipliers on the pixelwise log-likelihood.

thick weights the thickness-change term; vel weights the velocity-change term. Defaults match the prototype's hardcoded 0.5 / 0.5 (Apr 20 meeting).

fusion.config.SubsampleConfig

Bases: BaseModel

Random subsample applied within each region before the likelihood is summed.

size is the maximum number of pixels per region; seed makes the draw deterministic. Use the same seed as the validation harness in PSUISM_HBM_V1 to reproduce the prototype bit-exactly.

projection

Which forward-projection target to compute when applying the posterior weights. Consumed by project.

projection:
  target_year: 2100
  quantity: grounded_ice_volume

Projection magnitudes are provisional

The member-to-SLE reduction in v1 is a placeholder (a mean of ice thickness, not volume above flotation). Treat the projection's shape as illustrative, not its absolute magnitude. The weighting itself is validated and unaffected. See Interpreting results.

fusion.config.ProjectionConfig

Bases: BaseModel

Which forward-projection target to compute when applying the posterior weights.

Specifies the target year and the quantity to project.

Loading and validating

load_config wraps Pydantic's model_validate, so any constraint violation (unknown grid target, wrong type, missing required key) surfaces as a ValueError that names the file.

fusion.config.load_config(path)

Load and validate a FUSION config from a YAML file.

Validation errors (and other read errors) are raised as ValueError with the path included in the message.