安装¶

本页讲解 PREP-SHOT 的安装和作为 Python 库的使用方式。若想直接动手完成一次求解,请参阅 Quickstart (30 minutes)。

第 1 步:下载¶

克隆代码仓库:

git clone https://github.com/PREP-NexT/PREP-SHOT.git

或下载 zip 压缩包。

第 2 步:安装¶

建议使用单独的 conda 环境,以便隔离求解器依赖:

cd PREP-SHOT
conda create -n prep-shot python=3.11 -y
conda activate prep-shot
pip install -e .

pip install -e . 会以可编辑模式安装 PREP-SHOT,并自动安装 pyproject.toml 中声明的所有运行时依赖。默认求解器 HiGHS 以 wheel 形式自动安装;商用求解器需另行安装,并在算例的 config.json 中修改 solver 字段。

无需额外安装—— pip install -e . 已经引入了 highsbox,它将 HiGHS 以 wheel 形式提供。可用以下命令验证:

python -c "import highsbox; print('OK')"

在 config.json 中:

"solver_parameters": {"solver": "highs"}

从 gurobi.com 下载并安装 Gurobi,申请学术许可证。然后执行:

pip install gurobipy

在 config.json 中:

"solver_parameters": {"solver": "gurobi"}

从 copt.de 下载并安装 COPT;学术许可证免费。然后执行:

pip install coptpy

在 config.json 中:

"solver_parameters": {"solver": "copt"}

从 mosek.com 下载并安装 MOSEK;学术许可证免费。然后执行:

pip install mosek

在 config.json 中:

"solver_parameters": {"solver": "mosek"}

可选依赖组:

pip install -e .[notebook]   # jupyterlab, matplotlib, h5netcdf
pip install -e .[dev,docs]   # pytest, sphinx

我们计划随 v2.0 稳定性承诺一同发布 PyPI 版本 (pip install prepshot)。在此之前,如需锁定特定版本,可直接从 GitHub 安装:

pip install git+https://github.com/PREP-NexT/PREP-SHOT@v1.10.0

第 3 步:运行算例¶

examples/ 下的每个子目录都是一个自包含的算例。任选其一,进入该目录运行;参见 Quickstart (30 minutes) 对 three_zone 数据集的完整动手演练。

cd examples/three_zone   # or southeast_asia, thailand
python -m prepshot

仓库随附三个算例:three_zone (人工合成的 3 区域算例,被 Quickstart (30 minutes) 使用)、southeast_asia (湄公河下游,5 个国家,57 座水库)、thailand (单一区域,13 座湄公河流域水库)。

如要运行自定义算例,可复制 examples/three_zone/ 作为起始模板,然后编辑 input/*.csv 与 config.json。

第 4 步:作为 Python 库使用 PREP-SHOT¶

在执行 pip install -e . 之后,可以直接从你自己的 Python 代码中导入和驱动 PREP-SHOT。最简单的入口是 prepshot.cli.main,它与 prepshot 命令行脚本等价,会在含有 config.json 与 params.json 的目录上完整执行 "建模—求解—保存" 全过程:

from prepshot.cli import main

solved = main(root_dir="/path/to/my/scenario")
if not solved:
    raise RuntimeError("PREP-SHOT did not reach optimality")

如需更精细的控制——同一 Python 进程中运行多个算例、求解后查看模型、跳过默认 Excel 输出——可使用更底层的函数:

from prepshot.set_up import initialize_environment
from prepshot.model import create_model
from prepshot.solver import solve_model

parameters = initialize_environment({
    "filepath": "/path/to/scenario",
    "config_filename": "/path/to/scenario/config.json",
    "params_filename": "/path/to/scenario/params.json",
})

model = create_model(parameters)
solved = solve_model(model, parameters)
print("objective:", model.get_value(model.cost))

Python API 在整个 v1.x 系列保持稳定,是依赖 PREP-SHOT 的下游代码推荐使用的接口。完整的稳定性政策参见 Stability policy。