materialize_candidate#

hydromodpy.calibration.materialize_candidate(base_config, params, space, out_dir, *, candidate_label=None, iteration_index=None, name=None, workspace_root=None, extra_sections=None, base_dir=None)[source]#

Write a standalone override TOML for one calibration candidate.

Return type:

Path

Parameters:

Parameters#

base_config

Path to the target simulation TOML or an in-memory HydroModPyConfig instance. When a config object is passed, the overlay is built from model_dump and base_config in the overlay falls back to base_dir (when supplied) so the file remains rechargeable.

params

Candidate values keyed by parameter name (must cover every parameter in space that has a target or path).

space

Calibration parameter space declaring dotted target paths and per-parameter mode ("replace" / "scale").

out_dir

Directory under which the overlay is written. A candidate_label or iteration_index argument picks the subfolder name.

candidate_label

Filesystem-safe label (e.g. "truth"). Either candidate_label or iteration_index must be supplied.

iteration_index

Iteration number when no explicit label is given. Produces a folder like iter_0042.

name

Value to write at simulation.name in the overlay.

workspace_root

Value to write at workspace.root. Required when the parent simulation TOML does not already declare a workspace root.

extra_sections

Optional mapping of additional TOML sections (e.g. {"display": {"enabled": False}}) applied on top of the overlay.

base_dir

Reference directory for relative path rewriting. When supplied, base_config and workspace.root paths inside the overlay are emitted relative to this directory; otherwise absolute paths are written (the historical behaviour).

Returns#

Path

Absolute path to the written overlay TOML.

param base_config:

type base_config:

Path | str | BaseModel

param params:

type params:

Mapping[str, float]

param space:

type space:

ParameterSpace

param out_dir:

type out_dir:

Path | str

param candidate_label:

type candidate_label:

str | None

param iteration_index:

type iteration_index:

int | None

param name:

type name:

str | None

param workspace_root:

type workspace_root:

Path | str | None

param extra_sections:

type extra_sections:

Mapping[str, Mapping[str, Any]] | None

param base_dir:

type base_dir:

Path | None