Python 接口 ​

HydroPilot 的公开 Python 接口提供了脚本化水文工作流最常用的运行入口。

主要公开对象 ​

• SimModel 是核心运行时入口
• BatchRunResult 用于保存一次或多次评估的结果
• UQPyLAdapter 用于把 HydroPilot 接到 UQPyL 优化工作流中

典型用法 ​

如果你想直接在 Python 中执行一次或多次评估，可以使用 SimModel：

from hydropilot import SimModel

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

这样就可以直接拿到目标值、约束、诊断项以及提取出的时间序列。

SimModel ​

SimModel(cfgPath) 会负责加载并校验配置，初始化运行时 session，并暴露模型评估所需的基础信息。

常见能力包括：

• 用一维向量执行单次评估
• 用二维数组执行批量评估
• 在单次评估时接收按名称组织的输入值
• 暴露上下界、变量名、目标数量、约束数量等问题定义信息

真正执行时，HydroPilot 通常会按下面的顺序工作：

1. 在配置的工作目录下创建工程副本
2. 将设计变量转换成物理参数
3. 把参数写入模型输入文件
4. 执行配置中的模型命令
5. 提取输出并计算目标、约束和诊断项

BatchRunResult ​

BatchRunResult 是 SimModel.run() 返回的结构化结果容器。

最重要的字段有：

• X：被评估的设计空间输入
• P：解析后的物理参数
• objs：目标函数值
• cons：约束值
• diags：诊断项
• series：提取出的时间序列

即使是单次评估，数组也仍然保持 batch 形状，只是 n_samples = 1。这样单次和批量流程在下游处理时更一致。

不运行模型时的参数写入 ​

Python 接口也支持在不执行模型的情况下生成工程副本：

• apply_design(X, out_dir)：先把设计值转换为物理参数，再写入工程
• apply_params(P, out_dir)：直接写入已经解析好的物理参数

这种方式适合先检查生成后的工程文件，或者把准备好的工程交给别的运行环境去执行。

UQPyLAdapter ​

UQPyLAdapter 也是公开 Python 接口的一部分，不过更偏向集成层。它会把 SimModel 包装成 UQPyL 的 Problem，这样优化算法就可以把 HydroPilot 配置当成标准优化目标来调用。

为什么使用 Python 接口 ​

• 方便在 notebook 或脚本中集成 HydroPilot
• 便于程序化执行重复评估
• 拿到结构化结果，而不只是终端摘要
• 进一步接入 UQPyL 这类上层工作流

建议继续阅读 ​

• UQPyL 集成
• 示例