English | 简体中文 | 中文文档

A configuration-first orchestration framework for hydrological model calibration, evaluation, and optimization.

HydroPilot turns the repetitive glue code around hydrological modeling into a reusable workflow: parameter mapping, input writing, model execution, result extraction, objective evaluation, and run reporting. The core is model-agnostic. Built-in templates give you shorter, model-specific configuration for supported models.

Current source version: 0.1.4. See the change log.

What is available today:

• version: general — model-agnostic workflow mode
• version: swat — template for SWAT 2012
• version: swatplus — template for SWAT+; see the support status
• version: xaj — template for XAJ (Xinanjiang)
• readers: text, csv
• writers: fixed_width, csv, formatted_text
• subprocess-based model execution
• built-in and external evaluation functions
• SQLite and CSV run reporting
• UQPyL integration

CLI entry points:

• hydropilot-validate — validate a configuration
• hydropilot-test — run one configuration test
• hydropilot-apply — apply parameters to a project copy
• hydropilot-run — single-run YAML entry point

Public Python API:

• SimModel — main runtime entry point
• BatchRunResult — batch evaluation result
• UQPyLAdapter — bridge to UQPyL optimization and calibration

Planned, not yet available:

• APEX
• HBV
• VIC
• HEC-HMS

Requires Python 3.10+.

pip install hydropilot

For local development:

pip install -e .
pip install -e .[dev]

With UQPyL integration:

pip install -e .[uqpyl]

hydropilot-validate path/to/config.yaml

hydropilot-test path/to/config.yaml

Runs one deterministic parameter vector through the full runtime, forces parallel = 1, keeps the runtime project copy, and writes test-report.md under the run archive.

hydropilot-apply path/to/apply.yaml

hydropilot-run path/to/run.yaml

Executes one parameter vector described by a run YAML file. It's a single-run entry point — it doesn't manage full experiments.

import numpy as np
from hydropilot import SimModel

X = np.array([
    [50.0, 0.5, 100.0],
])

with SimModel("examples/test_monthly.yaml") as model:
    result = model.run(X)
    print(result.objs)

from hydropilot.integrations import UQPyLAdapter

with UQPyLAdapter("examples/test_daily.yaml") as adapter:
    result = adapter.evaluate(X)
    print(result.objs)
    print(result.cons)

UQPyLAdapter directly inherits ModelProblem interfaces, including evaluate(X, target=...) and separate simulate(X) / objFunc(X, context) / conFunc(X, context) calls. Each context identifies one simulation; objective and constraint calls perform requested post-processing and reuse prior results. SQLite records are updated by stage, and CSV is exported from committed data. Observations are optional for ordinary optimization and required for calibration methods that compare simulations with observations.

The adapter currently requires the updated UQPyL development source exposing SimContext, SimulatorBase and ModelEvaluatorBase. The PyPI UQPyL 2.1.6 package does not yet provide these interfaces. Install the matching UQPyL checkout with pip install -e /path/to/UQPyL; SimModel works independently of UQPyL.

• Documentation hub — index of all documentation
• Architecture — config chain, runtime chain, and module layout

MIT