hmp.calibrate#

Run a calibration workflow from a TOML file or a validated config object.

Signature#

hmp.calibrate(config, **kwargs) -> Any

Reference#

hydromodpy.calibrate(config, *, phase=None, list_phases=False, **kwargs)[source]

Run a calibration workflow from a TOML file or config object.

Paths route directly to run_calibration_cli(); in-memory config objects open a lazy Project so run_calibration_programmatic() has the project context it requires.

A TOML declaring [[calibration.phases]] routes to run_staged_calibration(): each phase calibrates its own parameters and freezes them for the next. The same declaration carried by an in-memory config object is refused: a phase forks its configuration from the source file, and there is none. Write the config out and pass the path.

Return type:

Any

Parameters:

  • config (Any)

  • phase (str | None)

  • list_phases (bool)

  • kwargs (Any)

Parameters#

config

Calibration TOML path or validated configuration object.

phase

Run only the named phase. It still needs the parameters its dependency froze, so a phase whose dependency has not run is refused rather than calibrated against un-frozen values.

list_phases

Return the declared phases without running anything.

kwargs

Options forwarded to the underlying calibration runner. The headless keyword controls the project initialization for the in-memory config branch and is ignored for the TOML branch (which builds no project).

Returns#

Any

Calibration report or workflow-specific result. A list of phase descriptions when list_phases is set.

Raises#

FileNotFoundError

If the calibration TOML path does not exist.

hydromodpy.core.exceptions.ConfigError

If the configuration cannot be read and the answer depends on reading it (phase or list_phases).

hydromodpy.core.exceptions.ConfigMissingError

If neither config_path nor parameters is supplied.

hydromodpy.core.exceptions.CalibrationError

If a staged calibration cannot be run as declared, if phase names a phase the configuration does not declare, or if the optimizer or objective evaluation fails.

Examples#

>>> import hydromodpy as hmp
>>> report = hmp.calibrate("calibration.toml")

See Also#

hydromodpy.calibration.runners.cli_runner.run_calibration_cli

TOML entry point used by the path branch.

hydromodpy.calibration.runners.staged_runner.run_staged_calibration

Staged entry point used when the TOML declares phases.

hydromodpy.calibration.runners.programmatic_runner.run_calibration_programmatic

Python entry point used by the config-object branch.

hydromodpy.calibration.CalibrationReport

Structured calibration result.

param config:

type config:

Any

param phase:

type phase:

str | None

param list_phases:

type list_phases:

bool

param kwargs:

type kwargs:

Any

Example#

import hydromodpy as hmp

report = hmp.calibrate("calibration.toml")

See Also#