模型输入与输出¶

PREP-SHOT 从一个 CSV 文件夹读取输入,并将求解结果写入 NetCDF 文件。params.json (位于仓库根目录) 把每个模型参数映射到对应的 CSV 文件名、声明文件是否必须、并在可选文件缺失时给出默认值。

输入文件格式¶

自 v1.5.0 起,所有输入采用 长格式 ("整洁") CSV——每个索引一列维度,加上末尾的单列 value。名为 unit、name、commodity、comment、note、label 或以 _name 结尾的列被视为文档注释,加载器会忽略它们。典型的二维文件形如:

zone,year,unit,value
BA1,2020,USD/tonneCO2,0
BA1,2025,USD/tonneCO2,5
BA2,2020,USD/tonneCO2,0

其中有四类 "Group 3" 查找表 (碳排放上限、扩展候选、分段水库函数、水流延迟矩阵、技术注册表) 仍为加载为 DataFrame 的宽表——它们具有多个值列,模型代码按列名切片读取。

当前输入文件的 schema 版本号写在 params.json 顶部,值为 "_schema_version": 2。从更早版本迁移的说明参见 Stability.rst 与 Changelog.rst。

文件名前缀按领域对输入分组:

demand —— 电力需求
economic_ —— 折现因子
finance_ —— (可选) WACC 与公共债务核算
policy_ —— 碳排放上限、碳税、碳抵消
reservoir_ —— 按站点的水库参数
storage_ —— 储能技术参数
tech_ —— 技术注册表、成本、容量、运行曲线
transmission_ —— 输电线路参数

输入¶

必备输入¶

参数 [单位]	说明	输入文件
demand [MW]	按区域、年份、月-小时给出的逐小时电力需求。PREP-SHOT 内部乘以 `dt` 将 MW 转换为每时段 MWh,与 `gen` 和 `charge` 单位一致。	demand
经济折现因子 [比例]	按区域和年份给出的折现率。用于折现固定、可变,以及在金融模块未启用时折现投资现金流。	economic_discount_factor
技术注册表 [N/A]	按技术的元数据:`tech`、`name`、`carrier` (自由格式字符串—— `hydro` 被特殊处理)、`is_storage` (布尔标志)。决定模型对水电 / 储能 / 可调度技术的分类。	tech_registry
现有装机 [MW]	每个已建容量块占一行:`(tech, zone, commission_year, capacity)`。稀疏存储——仅列出非零条目。在 v1.7.0 中替代 `historical_capacity`。	tech_existing
技术候选 [MW]	按 `(zone, tech, year)` 给出的可建设扩展选项,包含 `capacity_min` / `capacity_max` 列。条目缺失意味着 "该组合不可扩展"。	tech_candidates
技术容量上限 [MW]	每个 `(zone, tech, year)` 的总装机容量上限。设为 `inf` 时不施加约束。	tech_capacity_max
技术寿命 [年]	按技术、按投运年份的寿命。在投运年份处查表,所以一台在 `cy` 投运的机组将在 `cy + lifetime[te, cy]` 退役。 (已在 v1.8.1 中修复相关 bug。)	tech_lifetime
技术投资成本 [美元/MW]	按技术和年份的隔夜投资成本。	tech_investment_cost
技术固定 O&M 成本 [美元/MW/年]	按技术和年份的固定 O&M 成本。	tech_fixed_OM_cost
技术可变 O&M 成本 [美元/MWh]	按技术和年份的可变 O&M 成本。	tech_variable_OM_cost
技术燃料价格 [美元/MWh]	按技术和年份的燃料价格。	tech_fuel_price
技术排放系数 [tCO2/MWh]	按技术、年份和区域的排放系数。	tech_emission_factor
技术爬坡 / 减荷 [1/MW]	按技术和年份的小时爬坡限制。	tech_ramp_up, tech_ramp_down
储能充电 / 放电效率 [比例]	储能技术的循环效率。	storage_charge_efficiency, storage_discharge_efficiency
储能能量-功率比 [MWh/MW]	每单位功率容量对应的能量容量 (储能技术)。	storage_energy_to_power_ratio
储能初始电量 [比例]	储能技术的初始荷电状态 (能量容量的占比)。	storage_initial_level
已有输电 [MW]	按 `(zone1, zone2, commission_year)` 给出的现有输电线路容量。退役由 `transmission_lifetime` 控制。与 `tech_existing` 对称。	transmission_existing
输电候选 [MW]	按 `(zone1, zone2, year)` 给出的可建设输电选项,包含 `capacity_min` / `capacity_max` 列。	transmission_candidates
输电距离 [km]	区域间距离 (决定投资成本)。	transmission_distance
输电效率 [比例]	按线路的输电效率。	transmission_efficiency
输电投资成本 [美元/MW/km]	按线路的投资成本 (再乘以距离)。	transmission_investment_cost
输电固定 / 可变 O&M 成本	按线路的固定与可变 O&M 成本。	transmission_fixed_OM_cost, transmission_variable_OM_cost
输电寿命 [年]	按线路的寿命;控制现有线路的退役。	transmission_lifetime

水电输入 (在 `config.json` 中 `isinflow=true` 时启用)¶

水电站是一等技术 (在 tech_registry 中 carrier='hydro');这些按站点的水库参数把它们与模型的其余部分关联起来。

参数 [单位]	说明	输入文件
水库所属区域	把每个水电站映射到其所在区域。	reservoir_zone
水库入流 [m**3/s]	按站点的小时入流。	reservoir_inflow
水库水流延迟时间 [N/A]	相连水库之间的水流时间矩阵 (宽表格式)。	reservoir_water_delay_time
水库系数	按站点的发电系数。	reservoir_coefficient
水库水头 [m]	按站点的设计水头。	reservoir_head
水库容量上限 / 下限 [MW]	按站点的装机容量上下界。	reservoir_capacity_max, reservoir_capacity_min
水库下泄量上限 / 下限、发电流量上限 [m**3/s]	按站点、小时、月份给出的下泄量与发电流量约束。	reservoir_outflow_max, reservoir_outflow_min, reservoir_generation_flow_max
水库蓄水量上限 / 下限 [m**3]	按站点、月份、小时的库容上下界。	reservoir_storage_max, reservoir_storage_min
水库期初 / 期末库容 [m**3]	每年开始 / 结束时每个站点的库容。	reservoir_initial_storage_level, reservoir_final_storage_level
水库尾水位—下泄量曲线 [m 与 m**3/s]	尾水位作为总下泄量函数的分段查找表 (宽表格式)。	reservoir_tailrace_level_discharge_function
水库前池水位—库容曲线 [m 与 m**3]	前池水位作为库容函数的分段查找表 (宽表格式)。	reservoir_forebay_level_volume_function

可选输入 (缺失时跳过)¶

参数 [单位]	说明 (缺失时的默认值)	输入文件
技术最大出力曲线 [比例]	随时间变化的调度上限 (PyPSA 风格的 `p_max_pu`)。默认值:`1` (不在装机以下设上限)。在 v1.8.0 中替代 `capacity_factor`。	tech_max_gen_profile
技术最小出力曲线 [比例]	随时间变化的调度下限 (`p_min_pu`)。默认值:`0`。涵盖了旧版的 "必发" 行为。	tech_min_gen_profile
技术容量下限 [MW]	每个 `(zone, tech, year)` 的总装机容量下限。默认值:`0`。	tech_capacity_min
碳排放上限 [tCO2]	每个限制区域的净排放上限 (各行的 `zones` 字段以逗号分隔;每个区域、每个年份一行)。宽表格式。	policy_carbon_emission_limit
碳税 [美元/tCO2]	按区域、按年份对净排放征收的碳税。默认值:`0`。	policy_carbon_tax
碳抵消价格 [美元/tCO2]	按区域、按年份的抵消价格。默认值:`0`。	policy_carbon_offset_price
碳抵消上限 [tCO2]	按区域、按年份可购买抵消的上限。默认值:`0`。	policy_carbon_offset_limit
公共 / 私人债务占比 [比例]	按技术给出的项目资本中公共债务与私人债务所占比例。股权比例为残值 `1 - public - private`。启用 v1.9.0 金融模块。	finance_public_debt_ratio, finance_private_debt_ratio
公共 / 私人债务、股权融资成本 [比例]	每个 (tech, zone) 各融资份额的成本。综合得到项目级 WACC,用于折现建设支出。	finance_cost_of_public_debt, finance_cost_of_private_debt, finance_cost_of_private_equity
公共债务系统 / 区域上限 [美元]	对每年举借的公共债务在系统级和区域级的上限。设为 `inf` (或条目缺失) 时不施加约束。	finance_public_debt_max_system, finance_public_debt_max_zone

备注

值单元格中的 inf 意味着 "无上界"——模型会跳过对应约束。
对声明为 "drop_na": true 的文件,空单元格 (NaN) 会被加载器丢弃。
金融模块仅在提供 finance_public_debt_ratio.csv 时启用。未启用时,``inv_factor`` 退回为区域折现率——所以未提供金融输入的全新部署的目标值与 v1.8.x 完全一致。

输出¶

结果写入 NetCDF 文件 (默认为 year.nc;详见 config.json 的 output_filename)。可使用 xarray 读取;此教程是不错的入门资料。

输出变量¶
变量名	单位	说明
trans_export	每时段 MWh	在每个 `(hour, month, year)` 中从 `zone1` 向 `zone2` 送出的电力,扣除输电损耗之前。
gen	每时段 MWh	按 `(tech, zone, hour, month, year)` 的发电量。
install	MW	在新增与退役之后,按 `(year, zone, tech)` 的总装机容量。
charge	每时段 MWh	按 `(tech, zone, hour, month, year)` 的储能充电量。
carbon, carbon_breakdown	tCO2	每年的总排放,以及按 `(year, zone, tech)` 的明细。
cost	美元	整个规划期内系统总成本的净现值。
cost_var, cost_var_breakdown	美元	可变 O&M + 燃料成本 (总值与按 `(year, zone, tech)` 的明细)。
cost_fix, cost_fix_breakdown	美元	固定 O&M 成本 (总值与按 `(year, zone, tech)` 的明细)。
cost_newtech, cost_newtech_breakdown	美元	新增技术投资的折现成本 (总值与按 `(year, zone, tech)` 的明细)。
cost_newline, cost_newline_breakdown	美元	新增输电线路的折现投资成本 (总值与按 `(year, zone1, zone2)` 的明细)。
shadow_price_demand	美元/MWh (NPV)	节点边际电价——在每个 `(hour, month, year, zone)` 多供一兆瓦时需求的边际成本。已折现为 NPV;除以 `var_factor[year, zone]` 可恢复未折现的实际年度价格。符号已相对原始对偶值翻转,正值意味着 "满足更多需求更昂贵"。若求解器未返回对偶值 (如 MIP),会在记录警告后跳过该项。
public_debt_newtech 1	美元	新增技术投资引发的折现公共债务义务。仅在 v1.9.0 金融模块启用时输出。
income	美元	来自取水服务的折现收益 (仅当 `isinflow=true` 时)。
genflow, spillflow	m**3/s	按站点的水电发电流量与弃水流量 (仅当 `isinflow=true` 时)。

1: 可选输出—— 仅在提供 finance_public_debt_ratio.csv 时才存在于 NetCDF 文件中。

运行情景¶

可以通过 --<param_key> <suffix> 在命令行替换任意单个输入文件。PREP-SHOT 会把后缀追加到该参数的 file_name 后,加载得到的 CSV 而非原始文件。例如,要运行 "低需求" 情景,在输入目录中准备好 demand_low.csv 文件,然后执行:

python run.py --demand=low

CLI 参数按 参数键名 (params.json 中字典的键) 注册,而非文件名——文件重命名后两者可能不同。

设置全局参数¶

仓库根目录中的 config.json 包含全模型范围的设置:

设置	说明
input_folder	存放输入 CSV 的文件夹 (相对于仓库根目录)。
output_filename	写入 `output/` 的 NetCDF 结果文件名。
hour	每个时段的典型小时数。
month	每个时段的典型月份数。
dt	每个时段对应的小时数。`demand` 单位为 MW;平衡约束会乘以 `dt` 转换为每时段 MWh。
hours_in_year	用于成本汇总的全年小时数 (通常为 8760)。
isinflow	切换水电 / 水库约束。设为 `false` 时模型会跳过所有水库相关计算。
error_threshold	水电水头迭代循环的收敛阈值。
iteration_number	水头迭代的最大次数。
solver	求解器: `highs`、`gurobi`、`copt`、`mosek` 等 (透传给 PyOptInterface)。
solver_path	求解器动态库的路径;仅在自动检测失败时需要。参见 PyOptInterface 设置说明。
solver_parameters	针对各求解器的具体选项: mosek、gurobi、highs、copt。

调整 config.json 之后,按安装中描述的方式运行模型。随仓库提供的 input/ 文件夹是一个开箱即用的自包含算例。