[calibration] CalibrationConfig

TOML section: [calibration]

Pydantic model: CalibrationConfig defined in hydromodpy.calibration.config.

Source on GitHub

Top-level [calibration] section.

The config selects the optimizer, iteration budget, candidate persistence policy, parameter declarations, observable outputs, and objective blocks. It is the stable user-facing schema used by CLI calibration and Project.calibrate.

When no explicit objective block is declared, HydroModPy can synthesize one from objective and variable if the matching output exists.

Show fields: User User + Dev All

Fields

method

str default = “grid” user source

Optimization method. Optuna is installed by default; install the calibration extra for cma_es and Optuna’s cmaes sampler.

max_iter

int default = 100 user source

Maximum number of calibration iterations.

batch_size

int default = 1 dev source

Number of suggestions drawn per ask (for parallel optimizers).

parallel

int default = 1 dev source

Number of trials evaluated concurrently inside one batch via a thread pool. parallel=1 keeps the legacy sequential loop.

seed

int | None default = None user source

Random seed for reproducibility.

save_runs

Literal[‘none’, ‘best_n’, ‘all’] default = “none” user source

How much to persist per iteration: - ‘none’: 1 DuckDB row per iteration, no Zarr. - ‘best_n’: same + promote top N to full simulations after the loop. - ‘all’: every iteration becomes a full simulation (Zarr included).

save_best_n

int default = 10 user source

Number of top iterations to promote when save_runs=’best_n’.

use_cache

bool default = True dev source

Enable params_hash content-addressable cache.

lightweight_extraction

bool default = True dev source

Skip Parquet/Zarr writes for lumped models (GR4J, …) and read simulated series from the per-trial RAM cache instead. Only the promoted runs go through the catalog write path.

objective

str default = “nse” user source

Metric key used by the default ScalarObjective.

variable

str default = “head” user source

Observed variable (for ObservationSet).

optimizer_kwargs in TOML: [calibration.optimizer_kwargs.<id>]

dict[str, Any] factory dev source

Extra keyword arguments forwarded to the optimizer adapter.

parameters in TOML: [calibration.parameters.<id>]

dict[str, CalibParameterDecl] factory user source

Per-parameter declarations (bounds, transform, prior, path).

Fields of CalibParameterDecl

bounds

list[float] | None default = None user source

[low, high] physical bounds. Inherits from Pydantic annotation when omitted.

transform

Literal[‘identity’, ‘log’, ‘logit’] default = “identity” user source

Transform applied before sampling. ‘log’ for strictly-positive quantities spanning orders of magnitude.

prior

Literal[‘uniform’, ‘log_uniform’, ‘normal’] default = “uniform” user source

Prior distribution used by Bayesian samplers.

path

str | None default = None user source

Dotted path into HydroModPyConfig. Optional: when omitted, the caller is responsible for injection.

target

str | None default = None user source

Readable alias for ‘path’. When both are set, ‘target’ wins.

mode

Literal[‘replace’, ‘scale’] default = “replace” user source

‘replace’ writes the sampled value as-is; ‘scale’ multiplies the base TOML value at the target path by the sample.

units

str | None default = None user source

Parameter units label.

outputs in TOML: [calibration.outputs.<id>]

support = “point” | “boundary” | “cell” factory user source

Named observables extracted from each candidate run.

Pick a tab below: setting support selects the matching schema.

point

TOML: [calibration.outputs.point.<id>] – model CalibOutputPoint (set support = "point").

variable

str required user source

Simulated variable to extract (e.g. ‘head’, ‘outlet_discharge’).

geometry in TOML: [calibration.outputs.point.<id>.geometry.<id>]

dict[str, Any] | None default = None user source

GeoJSON point geometry. Coordinates are in metres.

x

Optional[Any] default = None user source

X coordinate. Accepts a bare number (metres) or a pint string like ‘100 m’.

y

Optional[Any] default = None user source

Y coordinate. Accepts a bare number (metres) or a pint string like ‘100 m’.

time

Union[Literal[‘all’, ‘last’, ‘first’], list[str]] default = “all” user source

‘all’ keeps every time step; ‘last’ / ‘first’ selects one; a list of ISO timestamps selects specific steps.

reducer

Literal[‘mean’, ‘sum’, ‘last’, ‘none’] default = “none” user source

Aggregation over the retained time slice.

observed_values

list[float] | None default = None user source

Hard-coded observed values (used by twin-synthetic cases).

boundary

TOML: [calibration.outputs.boundary.<id>] – model CalibOutputBoundary (set support = "boundary").

variable

str required user source

Simulated variable to extract (e.g. ‘discharge’).

boundary_id

str required user source

Boundary package identifier.

time

Union[Literal[‘all’, ‘last’, ‘first’], list[str]] default = “all” user source

‘all’ keeps every time step; ‘last’ / ‘first’ selects one; a list of ISO timestamps selects specific steps.

reducer

Literal[‘mean’, ‘sum’, ‘last’, ‘none’] default = “none” user source

Aggregation over the retained time slice.

observed_values

list[float] | None default = None user source

Hard-coded observed values (used by twin-synthetic cases).

cell

TOML: [calibration.outputs.cell.<id>] – model CalibOutputCell (set support = "cell").

variable

str required user source

Simulated variable to extract (e.g. ‘head’).

cell_id

Optional[int] default = None user source

Flat cell index when the backend exposes one.

row

Optional[int] default = None user source

Structured row index.

col

Optional[int] default = None user source

Structured column index.

layer

int default = 0 user source

Structured layer index.

time

Union[Literal[‘all’, ‘last’, ‘first’], list[str]] default = “all” user source

‘all’ keeps every time step; ‘last’ / ‘first’ selects one; a list of ISO timestamps selects specific steps.

reducer

Literal[‘mean’, ‘sum’, ‘last’, ‘none’] default = “none” user source

Aggregation over the retained time slice.

observed_values

list[float] | None default = None user source

Hard-coded observed values (used by twin-synthetic cases).

objective_blocks in TOML: [[calibration.objective_blocks]]

list[CalibObjectiveBlockDecl] factory user source

Weighted blocks making up a composite objective. When empty, a single implicit block is built from ‘objective’ and ‘variable’.

Fields of CalibObjectiveBlockDecl

name

str required user source

Unique block identifier used in logs and persistence.

metric

Literal[‘rmse’, ‘nse’, ‘kge’, ‘mae’] default = “rmse” user source

Metric key. One of rmse, nse, kge, mae.

weight

float default = 1.0 user source

Relative weight of this block in the composite sum.

uses_outputs

list[str] required user source

Outputs (by name) consumed by this block.

normalize_cost

bool default = False user source

When True, divide the block cost by a reference scale (observed std fallback mean absolute value).

transform

Literal[‘identity’, ‘log’, ‘inverse’] default = “identity” user source

Per-block cost transform applied before weighting.

persist_iteration_detail

Literal[‘none’, ‘summary’, ‘full’] default = “summary” dev source

‘none’ skips component metrics; ‘summary’ keeps block totals; ‘full’ also stores per-block raw and normalized costs.

persist_model_distribution

bool default = False dev source

Persist the candidate distribution alongside the session.

rerun_best_with_outputs

bool default = False user source

Replay the best candidate with full outputs after the loop.

materialize_candidates

bool default = False dev source

Write a standalone override TOML for each candidate under ‘candidates_root’ so runs can be replayed later.

candidates_root

PurePosixPath | None default = None dev source

Directory for per-candidate overlay TOMLs. Required when materialize_candidates is True.

persistence in TOML: [calibration.persistence]

PersistenceConfig factory user source

Single switch governing every persistence sink (catalog, Zarr, Parquet, lockfile) for calibration outputs.

Fields of PersistenceConfig

save_catalog

bool default = True user source

Persist DuckDB rows (simulations, parameters, metrics, calibration_iterations). When False, catalog writes are skipped.

save_zarr

bool default = True user source

Persist per-simulation field arrays (head, concentration, derived) into the Zarr store.

save_parquet

bool default = True user source

Persist per-simulation tabular outputs (timeseries, budgets, mass_balance) as Parquet files.

save_lock

bool default = True user source

Generate and refresh the hydromodpy.lock reproducibility manifest after data ingestion.

compression

Literal[‘none’, ‘zstd’, ‘lz4’, ‘gzip’, ‘snappy’] default = “zstd” dev source

Codec used for Zarr field arrays and Parquet tables. ‘none’ disables compression.

compression_level

int default = 3 dev source

Compression level (codec-dependent). Ignored when compression=’none’.

Starter TOML snippet

Click to expand a copy-pasteable [calibration] TOML skeleton

Copy this block into your project.toml and uncomment the lines you want to set. Sub-tables ([parent.subfield]) appear in the order Pydantic expects them.

[calibration]
# method = "grid"
# max_iter = 100
# seed = ...  # default = None
# save_runs = "none"
# save_best_n = 10
# objective = "nse"
# variable = "head"
# [calibration.parameters.<id>]
# [calibration.outputs.<id>]
# rerun_best_with_outputs = false

[[calibration.objective_blocks]]
# name = ""  # REQUIRED
# metric = "rmse"
# weight = 1.0
# uses_outputs = []  # REQUIRED
# normalize_cost = false
# transform = "identity"

[calibration.persistence]
# save_catalog = true
# save_zarr = true
# save_parquet = true
# save_lock = true

Entity-relationship diagram

Click to zoom and pan. Press Esc or click outside to close.