hydromodpy.calibration.runners.trial#

Trial primitive - “prepare once, evaluate many”.

The calibration loop needs a cheap inner step that lets the optimizer evaluate hundreds of parameter combinations without re-running the expensive setup phases (geographic, mesh, data loading) every time.

Three public entry points:

  • prepare_trials() - load the TOML, compute which pipeline steps are affected by the calibration overrides, and run the shared prefix (steps [0..earliest)) exactly once. Returns a TrialContext that downstream trials fork from.

  • run_trial_light() - fork the trial context, inject one parameter sample, run steps [earliest..8] with execution.lightweight = True so no Zarr / Parquet / provenance artefacts are written, extract the objective in RAM, and return a TrialResult.

  • promote_prepared_trial() - run the persistent downstream pipeline from the prepared context, writing Zarr + Parquet + catalog rows for the top-N iterations without repeating setup work.

The storage contract is strict: run_trial_light never writes to disk. Only promotion creates simulation artefacts.

Workflow access goes through get_trial_pipeline_provider() so the calibration package never imports the workflow package directly.

Functions

prepare_trials(cfg_path, *, override_paths)

Load TOML, run steps [0..earliest) once, return a fork-able context.

promote_prepared_trial(trial_ctx, values, *)

Run a full promoted simulation from an already prepared trial context.

promote_trial(cfg_path, values, *[, paths, ...])

Run the full simulation pipeline with calibration values baked in.

run_trial_light(trial_ctx, values, *[, ...])

Execute one lightweight trial and return its TrialResult.

Classes

TrialContext(base_cfg, ctx, earliest, ...[, ...])

Prepared runtime state that a calibration loop forks from.

TrialResult(values, metrics, primary_metric, ...)

Outcome of a single lightweight trial.