Python API ​

HydroPilot's public Python API exposes the runtime entry points needed for scripted hydrological workflows.

Main public objects ​

• SimModel is the primary runtime entry point
• BatchRunResult stores results for one or more evaluations
• UQPyLAdapter bridges HydroPilot into UQPyL optimization workflows

Typical Python usage ​

Use SimModel when you want to run one or more evaluations directly from Python:

from hydropilot import SimModel

with SimModel("config.yaml") as model:
    result = model.run([72.5, 0.3, 120])
    print(result.objs)

This gives you direct access to objective values, constraints, diagnostics, and extracted series.

SimModel ​

SimModel(cfgPath) loads and validates a configuration, initializes a runtime session, and exposes the metadata needed for model-driven workflows.

Common capabilities:

• run a single evaluation from a 1D vector
• run a batch from a 2D array
• accept named input values for single evaluations
• expose problem metadata such as bounds, labels, objective count, and constraint count

At execution time, HydroPilot will:

1. create a project copy under the configured work path
2. transform design values into physical parameters
3. write parameters into model input files
4. execute the configured model command
5. extract outputs and compute objectives, constraints, and diagnostics

BatchRunResult ​

BatchRunResult is the structured result container returned by SimModel.run().

The most important fields are:

• X for the evaluated design-space inputs
• P for resolved physical parameters when available
• objs for objective values
• cons for constraints
• diags for diagnostics
• series for extracted time series

For single evaluations, the arrays still use a batch shape with n_samples = 1. That makes downstream processing consistent across single and batch runs.

Applying parameters without running ​

The Python API also supports materializing project copies without executing the model:

• apply_design(X, out_dir) transforms design values and writes the resulting physical parameters
• apply_params(P, out_dir) writes already-resolved physical parameters directly

This is useful when you want to inspect the generated project files or hand the prepared project to another runtime.

UQPyLAdapter ​

UQPyLAdapter is part of the public Python-facing story, but conceptually it belongs to integration. It wraps SimModel as a UQPyL Problem so optimization algorithms can treat a HydroPilot config as a standard optimization target.

Why use the Python API ​

• integrate HydroPilot into notebooks or scripts
• run repeated evaluations programmatically
• access structured outputs instead of terminal summaries
• connect HydroPilot to higher-level workflows such as UQPyL

Read next ​

• UQPyL Integration
• Examples