尾矿库调洪演算系统 — 技术规格书

1. 输入参数规范

本系统涉及三大类输入数据：水文参数（用于洪水过程线计算）、地形/结构参数（用于水位-库容曲线和泄洪能力曲线构建），以及调洪演算控制参数。以下逐一定义每个参数的精确含义、数据类型、有效范围与取值方法。

1.1 洪水过程线计算参数（简化推理公式）

frequency_p（设计频率）：表示洪水重现期的概率百分数，数据类型为浮点数（float），数据类型对应关系为 2.0=50年一遇、1.0=100年一遇、0.5=200年一遇、0.2=500年一遇、0.1=1000年一遇。有效范围为 [0.1, 2.0]，单位为百分比（%）。该值通常由工程设计规范或安全鉴定报告确定，取值为常用标准频率档位之一。

area_f（汇水面积）：流域的平面投影总面积，数据类型为浮点数，单位为平方千米（km²），有效范围一般为 [0.1, 500]。取值方法为通过地形图、GIS 数据或实测测绘获得流域分水线所围合的面积。泉水沟尾矿库示例值为 2.5 km²。

h24（年最大 24 小时降雨均值）：流域内年最大 24 小时面降雨量的统计平均值，数据类型为浮点数，单位为毫米（mm）。取值方法为从当地水文站点长期观测记录中统计获得，或通过河南省暴雨参数图集查取。示例值为 90.0 mm。

channel_length（主沟长度）：流域内主要排水沟道从最远出口到尾矿库的直线距离或沿程距离，数据类型为浮点数，单位为千米（km），有效范围一般为 [0.1, 50]。取值方法为通过地形图量测或使用 GIS 工具计算河道中心线长度。示例值为 1.6 km。

slope_j（沟道平均坡降）：主沟道的平均水力坡度，即高程差与沟道长度的比值，数据类型为浮点数，无量纲（m/m），有效范围一般为 [0.001, 0.5]。取值方法为从起点和终点的高程差除以沟道长度计算得到。示例值为 0.022。

param_m（汇流参数）：反映流域地形、植被和下垫面特征对洪水汇流速度影响的经验参数，数据类型为浮点数，无量纲，有效范围一般为 [0.3, 1.5]。取值方法由详细推理公式通过 theta-m 关系表从 θ = L / (J^(1/3) × F^(1/4)) 计算 θ 值后查图获得；在简化公式中直接给定经验值。示例值为 0.85。

alpha24（24 小时径流系数）：24 小时设计降雨中转化为地表径流的比例，数据类型为浮点数，无量纲，有效范围 [0, 1]，取值方法根据流域地表类型（植被覆盖、土壤渗透性、城市化程度等）参照经验表格选取。示例值为 0.85。

1.2 洪水过程线计算参数（详细推理公式 — 河南省图集方法）

surface_type（下垫面类型）：流域地表的物理特征分类，数据类型为字符串，有效取值集合为 {“I”, “II”, “III”}，其中 I 类表示植被茂密（森林、密草）、汇流慢；II 类表示植被一般（农田、稀疏灌木）、汇流中等；III 类表示植被差（裸土、戈壁、矿区）、汇流快。取值方法参照河南省中小流域设计暴雨洪水图集的下垫面分类图。

cl_fq（产流分区编码）：流域所属的产流分区编号，数据类型为字符串，有效取值包括 “I”、“II”、“III”、“IV”、“V”、“VI-1”、“VI-2”、“VI-3”。每个分区对应不同的入渗率 μ 和最大初损值 Imax。取值方法由产流分区图确定，泉水沟尾矿库示例值为 “VI-1”（豫北山区和伊洛涧河黄土丘陵沟壑地区）。

1.3 水位-库容曲线参数

ev_curve_points（水位-库容数据点列）：描述尾矿库地形特征的离散数据序列，数据类型为列表，每个元素为二元组 (elevation, volume)，其中 elevation 表示水位标高（单位：米 m），volume 表示对应水位的蓄水容积（单位：万立方米 万m³）。数据点按水位升序排列，有效水位范围为 [720.0, 850.0]。取值方法来自尾矿库竣工测量报告或地形测绘数据。泉水沟尾矿库共 131 个数据点，从 720.0m 到 850.0m，间隔约 1m。

1.4 泄洪能力曲线参数

spillway_curve_points（泄流能力数据点列）：描述排水构筑物在不同水头下最大泄流量能力的离散数据序列，数据类型为列表，每个元素为二元组 (head, outflow)，其中 head 表示水头（单位：米 m），定义为当前库水位减去进水口标高；outflow 表示对应水头的最大泄洪流量（单位：立方米每秒 m³/s）。有效水头范围为 [0.0, 5.0]。取值方法来自排水设施的水力计算报告或实测数据，通过四种流态（自由流、孔口流、半压力流、压力流）的综合模型按封堵高度插值生成。

well_config（排水井配置参数）：定义每个排水井的几何和水力属性，数据类型为 WellConfig 数据类实例，包含 well_id（字符串，如 “1#”、“2#”、“3#”、“4#”）、lowest_inlet（最低进水口标高 m）、top_elevation（井顶标高 m）、height（井高 m）、shaft_depth（竖井深度 m）、tunnel_length（排水隧洞计算长度 m）、tunnel_exit_center（隧洞出口中心标高 m）、well_base_elev（井座顶部实际标高 m）、mu_pressure（压力流流量系数，校准值）、phi_semi（半压力流流速系数，校准值）。泉水沟尾矿库配置四座框架式排水井，内径 5.0m，连接竖井（直径 4.0m）和隧洞（直径 3.5m）。

1.5 调洪演算控制参数

initial_elevation（起调水位）：调洪演算开始时尾矿库的初始蓄水位，数据类型为浮点数，单位为米（m），有效范围必须在 ev_curve 的有效水位范围内 [min_elevation, max_elevation]。取值方法根据实际运行状态或设计工况确定，示例值包括 775.76m（2024年）和 779.20m（2025年）。

safe_elevation（安全水位/警戒水位）：尾矿库允许的最高正常运行水位，超过该水位即视为超警戒状态，数据类型为浮点数，单位为米（m），有效范围在 ev_curve 范围内。取值方法由尾矿库安全鉴定报告或设计规范确定，示例值包括 778.03m（2024年）和 781.82m（2025年）。

dt（计算时段步长）：调洪演算的时间离散化间隔，数据类型为浮点数，单位为小时（h），有效范围一般为 [0.01, 2.0]。取值方法根据洪水过程线的分辨率和精度需求确定，默认值 0.5 小时。更小的步长提高精度但增加计算量。

method（求解算法）：选择数值积分方法的标识符，数据类型为字符串，有效取值集合为 {“standard_stage”, “rk4”, “trapezoidal”, “abm”, “sva”}。取值方法根据应用场景确定：标准阶段法适用于工程验收报告；RK4 适用于高精度需求；梯形积分法适用于复杂泄洪系统；ABM 适用于长历时序列批量演算；SVA 适用于初设快速筛查。

2. 处理管线中使用的算法目录

2.1 洪水过程线计算模块（两条独立路径）

2.1.1 水科院简化推理公式路径

目的：根据设计频率、流域特征参数快速估算概化三角形洪水过程线。

步骤与逻辑： 第一步，通过 P-III 分布模比系数表 KP_TABLE 获取当前 frequency_p 对应的 Kp 值。Kp 表基于 Cs/Cv = 3.5、Cv = 0.75 的假定，从 2.0（50年一遇，Kp=2.14）到 0.1（1000年一遇，Kp=6.02）。 第二步，计算设计频率 24 小时降雨量 H24P = Kp × H24。 第三步，计算暴雨雨力 Sp = H24P / 24^(1-n2)，其中 n2 = HYDRO_N2 = 0.75。 第四步，按降雨量比例缩放入渗率 mu = mu_ref × (H24P / H24P_ref)，其中 mu_ref = 3.39 mm/h、H24P_ref = 542.43 mm。 第五步，用简化公式计算洪峰流量初值 qp = Coeff_A × Sp^Coeff_B × (m × J^(1/3) / L)^Coeff_D × F^Coeff_C，其中 Coeff_A=0.481、Coeff_B=1.143、Coeff_C=0.571、Coeff_D=0.317。 第六步，用不动点迭代法求解 Qp 与 τ 的耦合方程组：τ = 0.278 × L / (m × J^(1/3) × Qp^0.25) 和 Qp = 0.278 × (Sp / τ^n − mu) × F，迭代次数上限为 30 次，收敛判据为相对误差小于 max(0.001, qp × 1e-5)。 第七步，计算洪水总量 Wtp = 1000 × alpha24 × H24P × F。 第八步，用概化多峰三角形形状模板（33个时段点，峰值位于 t=19h）乘以设计洪峰 Qp，生成最终的洪水过程线 [(t, Q(t))]。

依赖：需要 KP_TABLE 查找表、HYDRO_N1/HYDRO_N2 暴雨递减指数常量、COEFF_A/B/C/D 简化公式系数。

2.1.2 河南省详细推理公式路径

目的：按照《河南省中小流域设计暴雨洪水图集》方法，逐要素计算更精确的洪水过程线。

步骤与逻辑： 第一步，对每个历时（10min、1h、6h、24h）分别用 P-III 分布计算模比系数 Kp = 1 + Cv × Phi，其中 Phi 由 scipy.stats.pearson3.ppf(1-P, skew=Cs) 求得，Cs = 3.5 × Cv。 第二步，根据流域面积 F 从 alpha_reduction.json 查点面折减系数 α，计算面雨量 H_面 = Kp × H_点 × α。 第三步，按公式 n1 = 1 - 1.285 × lg(H_1h面 / H_10min面)、n2 = 1 - 1.285 × lg(H_6h面 / H_1h面)、n3 = 1 - 1.661 × lg(H_24h面 / H_6h面) 计算暴雨递减指数。 第四步，计算 θ = L / (J^(1/3) × F^(1/4))，限制在 [5, 100] 范围内，从 theta_m.json 按 θ-m 关系表和 surface_type 插值得到汇流参数 m。 第五步，根据产流分区 cl_fq 从 mu_zone.json 查入渗率 mu_typical 和 Imax；按频率规则确定前期影响雨量 Pa：P ≤ 2% 时 Pa = Imax，否则 Pa = (2/3) × Imax。 第六步，用简化公式迭代求解洪峰流量 Qm 与汇流历时 τ，其中 S’ = S - mu × τ^n，τ = (term^(4/(4-n))) / (S’)^(1/(4-n))，迭代上限 30 次。 第七步，由 P+Pa 从 rainfall_runoff_curve.json 查降雨径流关系曲线得净雨深 R24；R6 = R24 × H_6h面 / H_24h面；Wtp = 1000 × R24 × F。 第八步，根据 n2p 和 n3p 从 net_rain_distribution.json 查净雨时程分配比例，构建 24h 每小时净雨量序列，用公式 Q = R(mm) × F(km²) / 3.6 转换为流量；做 3 小时移动平均平滑后，缩放使过程线峰值匹配 Qm。 第九步，对退水段（h=25~32）应用指数衰减 q = peak_flow × exp(-0.35 × decay_h)，延申到 t=32h。

依赖：rainfall_data.json、alpha_reduction.json、mu_zone.json、theta_m.json、rainfall_runoff_curve.json、net_rain_distribution.json 六个数据文件，以及 scipy.stats.pearson3 库。

2.2 泄洪能力计算模块

2.2.1 全流态泄流模型（DischargeCalculator）

目的：根据排水井结构参数和当前水头，综合四种流态计算最大泄流量。

步骤与逻辑： 第一步，确定当前库水位对应的水头 head = water_level - inlet_elevation。 第二步，分别计算四种流态的泄流量：自由流 Q_free（基于参考曲线按封堵高度插值）、孔口流 Q_orifice（基于参考曲线直接插值）、半压力流 Q_semi = phi × Fs × sqrt(2gH)（Fs 为竖井截面积、H 为库水位与隧洞入口中心标高之差）、压力流 Q_pressure = mu × Fx × sqrt(2gHz)（Fx 为隧洞截面积、Hz 为库水位与隧洞出口中心标高之差）。 第三步，取四种流态的最小值作为控制泄流量：Q_out = min(Q_free, Q_orifice, Q_semi, Q_pressure)。 第四步，对于 3#井使用精确数据驱动模式（calc_well3_flows），基于 2024/2025 年调洪报告表3-3 数据按封堵高度插值；其他井使用通用水力公式。

依赖：WellConfig 结构参数、REF_CURVE_2024_FREE、REF_CURVE_2025_FREE、REF_CURVE_2025_ORIFICE 参考曲线、物理常数 G=9.81 m/s²、SHAFT_AREA ≈ 12.566 m²、TUNNEL_AREA ≈ 9.621 m²。

2.2.2 泄流能力曲线构建（build_spillway_head_curve）

目的：根据起调水位自动生成覆盖水头 0~4m 的离散泄流能力曲线。

步骤与逻辑：以 0.05m 为步长，从水头 0 到 4.0m 遍历每个水头点，对每个水头调用 calc_all 计算控制泄流量，生成 [(head, outflow)] 数据点列。对于 3#井使用精确插值模式，其他井使用通用水力公式。

2.3 调洪演算求解器模块（五大算法）

2.3.1 标准阶段法（standard_stage）— 默认推荐

目的：利用辅助曲线预计算和查表方法高效求解水量平衡方程，为水工规范首选方法。

步骤与逻辑： 第一步，校验起调水位在 ev_curve 范围内。 第二步，预计算两条辅助曲线：aux_plus(H) = V(H) + q(H) × Δt/2 和 aux_minus(H) = V(H) − q(H) × Δt/2，其中 H 覆盖 [initial_elevation, max_elevation+5m]，步长 0.01m。 第三步，初始化状态：current_volume_wan = ev_curve.get_volume(initial_elevation)，V0_m3 = current_volume_wan × 1e4，计算初始出库流量 q_out = spillway_curve.get_outflow(0)。记录初始状态 12 元组。 第四步，对每个时段 [t1, t2]：取入库流量 Q1=Q(t1)、Q2=Q(t2)，计算平均入库流量 Q_avg = (Q1+Q2)/2；取时段初出库流量 q1 = O(H1 − start_level)；计算 aux_minus_1 = V1 − q1 × Δt/2。 第五步，求目标值 target = aux_minus_1 + Q_avg × Δt，在 aux_plus 曲线上用 np.interp 反查 H2。 第六步，由 H2 得到 q2 = O(H2 − start_level)、V2 = ev_curve.get_volume(H2)。 第七步：计算时段入库水量 W_in = Q_avg × dt × 3600、出库水量 W_out = q_avg × dt × 3600（q_avg = (q1+q2)/2）、净变化 delta_V = W_in − W_out。更新当前水位和库容，追踪峰值水位和最大库容，检查安全水位超限和水位-库容曲线范围超限。 第八步：循环至洪水过程线结束，组装 FloodRoutingResult 返回。

依赖：ev_curve.get_volume、spillway_curve.get_outflow、numpy.interp。

2.3.2 龙格-库塔四阶法（rk4）

目的：以四阶精度求解 ODE dV/dt = Q_in(t) − O(H(V))，适用于需要高精度对比的场景。

步骤与逻辑： 第一步：定义 ODE 右端函数 f(t, V_m3) = Q_in(t) − O(get_elevation(V_m3/1e4) − start_level)。 第二步：对每个时段 t ∈ [t1, t2]，计算 RK4 四阶增量：k1 = f(t1, V)，k2 = f(t1+h/2, V + h/2 × k1)，k3 = f(t1+h/2, V + h/2 × k2)，k4 = f(t2, V + h × k3)。 第三步：V_new = V + (h/6) × (k1 + 2×k2 + 2×k3 + k4)，其中 h = dt_s（秒）。若 V_new < 0 则截断为 0。 第四步：由 V_new 反查 H2 = get_elevation(V_new/1e4)、q2 = O(H2 − start_level)，记录结果并更新状态。

依赖：ev_curve.get_elevation、spillway_curve.get_outflow。条件稳定，洪峰处可能产生数值振荡。

2.3.3 梯形积分法（trapezoidal）— Crank-Nicolson 隐式格式

目的：以无条件稳定的隐式方法求解非线性调洪方程，适用于复杂泄洪系统或闸门调度场景。

步骤与逻辑： 第一步：构建隐式方程 g(V) = V + Δt/2 × O(H(V)) − RHS = 0，其中 RHS = V1 + Δt/2 × (Q1+Q2 − O(H(V1)))。 第二步：用牛顿法求解 g(V)=0：V_new = V_guess − g(V_guess)/g’(V_guess)，导数 g’(V) 通过中心差分数值近似：g’(V) = 1 + Δt/2 × dO/dH × dH/dV，其中 dO/dH 和 dH/dV 分别用 ±0.01m 扰动计算。 第三步：牛顿迭代收敛判据为 |g(V)| < tolerance × 1e4；若导数过小或牛顿法不收敛（超过 max_iterations），回退到二分法求解，在 [0, V_max_safe] 区间内二分共 50 次。 第四步：由 V2 反查 H2、q2，记录结果并更新状态。

依赖：ev_curve.get_elevation/get_volume、spillway_curve.get_outflow、numpy.interp。无条件稳定，但每步需要多次函数求值（牛顿迭代）。

2.3.4 Adams-Bashforth-Moulton 多步法（abm）

目的：以四阶预测-校正方法求解 ODE，在长历时水文序列批量演算中效率较高。

步骤与逻辑： 第一步：构建 ODE 右端函数 f(t, V_m3) = Q_in − O(H(V))。 第二步：前 3 步（或总步数 <4）使用 RK4 启动，保证初始精度。 第三步：从第 4 步起切换到 ABM：AB4 预测 V_p = V_i + (h/24) × (55×f_i − 59×f_{i-1} + 37×f_{i-2} − 9×f_{i-3})；AM4 校正 V_new = V_i + (h/24) × (9×f(V_p) + 19×f_i − 5×f_{i-1} + f_{i-2})。 第四步：用 deque(maxlen=4) 维护最近 4 个 f 值历史。若 V_new < 0 则截断为 0。 第五步：由 V_new 反查 H2、q2，记录结果并更新状态。

依赖：ev_curve.get_elevation、spillway_curve.get_outflow。条件稳定，每步仅 2 次函数求值（预测+校正）。

2.3.5 SVA 快速筛查法（sva）

目的：假设三角形入库洪水，用简化 V-Q 关系快速估算峰值水位与安全余量，适用于初设阶段或应急响应。

步骤与逻辑： 第一步：取 Qp = inflow_hydrograph.peak_flow、Wp = inflow_hydrograph.total_volume（通过梯形积分计算）。 第二步：构建两条曲线求交点问题：出流-调洪库容关系 q_storage = Qp × (1 − Vt/Wp) 与泄洪能力曲线 q_spill = O(H − start_level)。其中 Vt = (V(H) − V0) × 1e4。 第三步：从 initial_elevation 以 0.01m 步长向上扫描，当 f(H) = q_spill − q_storage 由负变正时，线性插值求交点 H_peak。 第四步：若未找到交点且 f始终<0，表示泄洪能力充足水位不上升；若 f始终>0，表示泄洪不足水位持续上升至曲线外推区域。 第五步：输出峰值水位 h_peak、对应最大库容 v_peak_wan 和调洪库容 v_peak_wan − V0_wan，构建简化时间序列 [初始点, 峰值点]。

依赖：ev_curve.get_volume、spillway_curve.get_outflow、inflow_hydrograph.total_volume/peak_flow。不产生完整逐时段结果。

2.4 辅助模块

2.4.1 水位-库容插值（ElevationVolumeCurve）

目的：在离散水位-库容数据点上实现双向映射，支持线性插值和边界外推。

步骤与逻辑：get_volume(elevation) — 若 elevation ≤ min_elevation 返回最小库容；若 elevation > max_elevation 用最后一段斜率外推；否则用 numpy.interp 线性插值。get_elevation(volume) — 同理，volume < min_volume 返回最小水位；volume > max_volume 用最后一段斜率的倒数（dH/dV）外推；否则用 numpy.interp 线性插值。

2.4.2 洪水过程线插值（Hydrograph）

目的：在离散时间-流量数据点上实现任意时刻入库流量的查询，超出范围外推为 0。

步骤与逻辑：get_flow(time) — 若 time < start_time 或 time > end_time 返回 0；否则用 numpy.interp 线性插值，结果取 max(flow, 0)。total_volume — 对整个过程线应用梯形积分：sum((Q_i + Q_{i+1})/2 × (t_{i+1} − t_i) × 3600)。

2.4.3 泄洪能力曲线查询（SpillwayCurve）

目的：根据水头查询最大泄流量，支持线性插值和边界外推。

步骤与逻辑：get_outflow(head) — 若 head ≤ min_head 返回 0；若 head > max_head 用最后一段斜率外推；否则用 numpy.interp 线性插值，结果取 max(flow, 0)。

2.4.4 结果汇总（print_summary / build_result）

目的：将 FloodRoutingResult time_series 中的 12 元组数据格式化为可读的文本摘要。

步骤与逻辑：提取峰值水位及其出现时间、最大绝对库容、调洪库容（max_volume − initial_volume）、总入库水量 sum(W_in)、总出库水量 sum(W_out)；判断 safe_limit_exceeded 和 curve_range_exceeded 状态；按 t(h)、Q入、Q出、Q入Δt、ΔV+qΔt/2、q、ΔV-qΔt/2、ΔVt 的格式输出节选明细。

3. 数学公式全集

3.1 调洪演算核心方程

水量平衡方程（时段平均流量形式）：

$$\frac{Q_1 + Q_2}{2} \cdot \Delta t - \frac{q_1 + q_2}{2} \cdot \Delta t = V_2 - V_1$$

其中各变量定义如下。

Q₁, Q₂（入库流量）：时段始和时段末的流域汇入尾矿库的总流量，单位立方米每秒（m³/s）。由洪水过程线插值得到。

q₁, q₂（出库流量）：时段始和时段末通过排水设施的最大泄洪能力，单位 m³/s。由泄洪能力曲线 q = O(H − start_level) 确定。

V₁, V₂（库容）：时段始和时段末尾矿库的实际蓄水体积，单位立方米（m³）。由水位-库容曲线 V = f(H) 经插值得到。

Δt（计算时段）：时间离散化步长，单位秒（s），在代码中为 dt × 3600（dt 以小时为单位输入）。

3.2 标准阶段法辅助曲线方程

$$\text{aux\_plus}(H) = V(H) + \frac{q(H) \cdot \Delta t}{2}$$ $$\text{aux\_minus}(H) = V(H) - \frac{q(H) \cdot \Delta t}{2}$$ $$V_2 + \frac{q_2 \cdot \Delta t}{2} = \left(V_1 - \frac{q_1 \cdot \Delta t}{2}\right) + Q_{\text{avg}} \cdot \Delta t$$

其中 V(H) 由水位-库容曲线插值，q(H) = O(H − start_level) 由泄洪能力曲线插值。通过 aux_plus 曲线的反函数 H = aux_plus⁻¹(target) 求得 H₂。

3.3 RK4 求解方程

$$k_1 = f(t, V)$$ $$k_2 = f\left(t + \frac{h}{2}, V + \frac{h}{2} \cdot k_1\right)$$ $$k_3 = f\left(t + \frac{h}{2}, V + \frac{h}{2} \cdot k_2\right)$$ $$k_4 = f(t + h, V + h \cdot k_3)$$ $$V_{\text{new}} = V + \frac{h}{6}(k_1 + 2k_2 + 2k_3 + k_4)$$

其中 ODE 右端函数 f(t, V_m³) = Q_in(t) − O(H(V_m³/10⁴))，单位为 m³/s。

3.4 梯形积分法（Crank-Nicolson）隐式方程

$$V_{i+1} + \frac{\Delta t}{2} \cdot O(H(V_{i+1})) = V_i + \frac{\Delta t}{2} \cdot [Q_i + Q_{i+1} - O(H(V_i))]$$

牛顿迭代求解：

$$V^{(n+1)} = V^{(n)} - \frac{g(V^{(n)})}{g'(V^{(n)})}$$

其中 g(V) = V + Δt/2 × O(H(V)) − RHS，导数 g’(V) ≈ 1 + (Δt/2) × (dO/dH) × (dH/dV)，通过中心差分数值近似。

3.5 ABM 多步法公式

AB4 预测器：

$$V_p = V_i + \frac{h}{24}(55f_i - 59f_{i-1} + 37f_{i-2} - 9f_{i-3})$$

AM4 校正器：

$$V_{i+1} = V_i + \frac{h}{24}(9f(V_p) + 19f_i - 5f_{i-1} + f_{i-2})$$

其中 h = dt × 3600（秒），f(t, V_m³) = Q_in(t) − O(H(V/10⁴))。

3.6 SVA 快速筛查方程

出流-调洪库容关系曲线：

$$q_{\text{storage}}(V_t) = Q_p \cdot \left(1 - \frac{V_t}{W_p}\right)$$

其中 V_t = (V(H) − V₀) × 10⁴（调洪库容，m³），Qp 为洪峰流量，Wp 为洪水总量。

交点条件：

$$O(H - H_0) = Q_p \cdot \left(1 - \frac{(V(H) - V_0) \times 10^4}{W_p}\right)$$

通过从 H₀ 向上扫描 f(H) = O(H − H₀) − q_storage(V_t)，当 f(H) 由负变正时线性插值求交点。

3.7 简化推理公式（水科院方法）

设计频率降雨量：

$$H_{24P} = K_p \cdot H_{24}$$

暴雨雨力：

$$S = \frac{H_{24P}}{24^{1 - n_2}}$$

入渗率（比例缩放）：

$$\mu = \mu_{\text{ref}} \times \frac{H_{24P}}{H_{24P}^{\text{ref}}}$$

汇流历时：

$$\tau = \frac{0.278 \cdot L}{m \cdot J^{1/3} \cdot Q_p^{0.25}}$$

洪峰流量（迭代耦合）：

$$Q_p = 0.278 \times \left(\frac{S}{\tau^n} - \mu\right) \times F$$

洪水总量：

$$W_{tp} = 1000 \cdot \alpha_{24} \cdot H_{24P} \cdot F$$

3.8 详细推理公式（河南省图集方法）

P-III 分布模比系数：

$$K_p = 1 + C_v \cdot \Phi(1 - P, C_s)$$

其中 Φ 为 P-III 分布的分位数函数，Cs = 3.5 × Cv。

点面折减：

$$H_{\text{面}} = K_p \cdot H_{\text{点}} \cdot \alpha$$

暴雨递减指数：

$$n_1 = 1 - 1.285 \times \lg\left(\frac{H_{1h,\text{面}}}{H_{10min,\text{面}}}\right)$$ $$n_2 = 1 - 1.285 \times \lg\left(\frac{H_{6h,\text{面}}}{H_{1h,\text{面}}}\right)$$ $$n_3 = 1 - 1.661 \times \lg\left(\frac{H_{24h,\text{面}}}{H_{6h,\text{面}}}\right)$$

汇流参数 θ：

$$\theta = \frac{L}{J^{1/3} \cdot F^{1/4}}$$

有效 n 选择规则：τ < 1 → n₁；1 ≤ τ < 6 → n₂；τ ≥ 6 → n₃。

净雨深（P+Pa 查表）：

R_{24} = f(P + P_a, I_{\text{max}}) \quad (\text{从 rainfall_runoff_curve.json 插值}

$$$$ $$R_6 = R_{24} \times \frac{H_{6h,\text{面}}}{H_{24h,\text{面}}}$$

净雨转流量：

$$Q(t) = \frac{R(t) \cdot F}{3.6}$$

退水段指数衰减：

$$q(h) = Q_p \cdot e^{-0.35 \times (h - h_{\text{peak}})} \quad (h > h_{\text{peak}})$$

3.9 泄流能力计算公式

自由流（堰流）：基于参考曲线插值，无解析公式。

孔口流：基于参考曲线插值，无解析公式。

半压力流：

$$Q = \phi \cdot F_s \cdot \sqrt{2gH}$$

其中 φ 为流速系数（由隧洞长度换算），Fs = π × (D_shaft/2)² ≈ 12.566 m²，g = 9.81 m/s²，H = water_level − tunnel_inlet_center。

压力流：

$$Q = \mu \cdot F_x \cdot \sqrt{2gH_z}$$

其中 μ 为流量系数（由隧洞长度换算），Fx = π × (D_tunnel/2)² ≈ 9.621 m²，Hz = water_level − tunnel_exit_center。

隧洞长度换算：

$$\mu = \frac{1}{\sqrt{1 + K \cdot L}}$$

其中 K 从基准井（3#井）反算：K = ((1/μ_ref)² − 1) / L_ref。

3.10 洪水过程线概化形状缩放

$$Q(t) = Q_p \times f_{\text{normalized}}(t)$$

其中 f_normalized(t) 为归一化的概化多峰三角形形状模板（峰值=1.0，共 33 个时段点），来源于参考文档的实际洪水过程线。

3.11 净雨时程分配

R6 分配（小时 11~16）：

$$R_{\text{hour}} = \frac{\text{ratio}_i}{100} \times R_6$$

(R24 − R6) 分配（小时 510 和 1724）：

$$R_{\text{hour}} = \frac{\text{ratio}_j}{100} \times (R_{24} - R_6)$$

移动平均平滑（3 小时窗口）：

$$\tilde{Q}(h) = \frac{1}{N}\sum_{d=-1}^{1} Q(h + d)$$

3.12 P-III 分布模比系数计算

$$\Phi_P = \text{pearson3.ppf}(1 - P, \text{skew}=C_s)$$ $$K_p = 1 + C_v \cdot \Phi_P$$

其中 P = frequency_p / 100，Cs = 3.5 × Cv。

4. 输出参数规范

4.1 调洪演算逐时段结果（time_series）

每个时段输出一组 12 元组记录，包含以下字段：

time（时间）：当前时段的时刻值，数据类型为浮点数，单位为小时（h），从洪水过程线起始时刻开始累加。表示该时段末的绝对计算时间点。

inflow（入库流量 Q_in）：时段平均入库流量，数据类型为浮点数，单位 m³/s。由洪水过程线在 t1 和 t2 时刻插值后取均值 (Q₁+Q₂)/2。物理含义为该时段的平均来水速率。

outflow（出库流量 q_out）：时段平均出库流量，数据类型为浮点数，单位 m³/s。由泄洪能力曲线根据时段始末水位对应的出水口流量 q1、q2 计算均值 (q₁+q₂)/2。物理含义为该时段的平均泄水速率。

w_in_m3（时段入库水量）：该时段累积的总入库水量，数据类型为浮点数，单位立方米（m³）。计算方式为 Q_avg × dt × 3600。物理含义为该时段内从流域汇入尾矿库的水体体积。

v_plus_qdt2（V+qΔt/2 辅助值）：辅助曲线值 V₂ + q₂·Δt/2，数据类型为浮点数，单位立方米（m³）相对值 = (V₂ − V₀) + q₂·Δt/2。用于标准阶段法查表求解 H₂。

q_end（时段末出库流量 q₂）：时段末时刻通过排水设施的最大泄洪能力，数据类型为浮点数，单位 m³/s。由泄洪能力曲线根据 H₂ 插值得到。物理含义为该水位下排水系统的最大理论泄流能力。

v_minus_qdt2（V−qΔt/2 辅助值）：辅助曲线值 V₂ − q₂·Δt/2，数据类型为浮点数，单位 m³ 相对值 = (V₂ − V₀) − q₂·Δt/2。用于标准阶段法辅助曲线的反向查询基准。

vt_m3（调洪库容 Vt）：当前调洪库容（绝对值），数据类型为浮点数，单位 m³ 相对值 = V₂ − V₀ = (V₂_wan − initial_volume_wan) × 10⁴。物理含义为当前蓄水量超出初始蓄水量的增量体积。

elevation（水位 H）：时段末尾矿库的蓄水位标高，数据类型为浮点数，单位米（m）。由调洪演算核心方程求解得到，通过水位-库容曲线反查 V₂ → H₂ 获得。物理含义为该时刻库面的绝对高程。

flood_reg_volume（调洪库容 v）：当前调洪库容相对值，数据类型为浮点数，单位万立方米（万m³）= V₂_wan − initial_volume_wan。物理含义为可用于调蓄洪水的有效库容。

w_out_m3（时段出库水量）：该时段累积的总出库水量，数据类型为浮点数，单位 m³。计算方式为 q_avg × dt × 3600。物理含义为该时段内通过排水设施排出的水体体积。

delta_v_m3（库容变化量 ΔV）：该时段的净入库水量，数据类型为浮点数，单位 m³ = W_in − W_out。正值表示库容增加，负值表示库容减少。

4.2 汇总统计结果

peak_elevation（最高水位）：演算过程中出现的最大水位值，数据类型为浮点数，单位 m。用于评估防洪安全性。若 peak_elevation ≥ safe_elevation，则 safe_limit_exceeded = true。

peak_time（峰值出现时间）：最高水位对应的时刻，数据类型为浮点数，单位 h。从 time_series 中搜索匹配 peak_elevation 的时间点获得。

max_volume（最大绝对库容）：演算过程中出现的最大蓄水容积，数据类型为浮点数，单位万m³ = V(H_peak)。物理含义为洪水期间尾矿库达到的最大蓄水量。

max_volume_time（最大库容出现时间）：最大库容对应的时刻，数据类型为浮点数，单位 h。从 time_series 中搜索匹配 max_volume 的时间点获得。

flood_regulation_volume（调洪库容）：有效防洪库容，数据类型为浮点数，单位万m³ = max_volume − initial_volume_wan。物理含义为起调水位以上可用于容纳洪水的有效容积。

safe_limit_exceeded（超警戒标志）：布尔值，表示最高水位是否超过安全水位。若 peak_elevation ≥ safe_elevation 则为 true。工程意义：true 表示尾矿库防洪能力不足，需要加强监控或增加泄洪措施。

curve_range_exceeded（曲线范围超限标志）：布尔值，表示计算过程中是否有水位超出水位-库容曲线的定义范围。若任何 H₂ > ev_curve.max_elevation 则为 true。工程意义：true 表示演算进入了外推区域，结果存在不确定性。

warnings（预警信息列表）：字符串数组，包含所有触发的事件警告，如超警戒起始时刻、超出曲线范围的提示、库容修正说明等。每条格式为 “⚠️ t=X.Xh: …”。

duration_above_safe（超警戒持续时间）：浮点数，单位 h = above_safe_times[-1] − above_safe_times[0]。表示水位持续高于安全水位的累计时长。

total_w_in_m3 / total_w_out_m3（总入库/出库水量）：整个演算期间 sum(W_in) 和 sum(W_out)，单位 m³。物理含义为洪水全过程的总来水和总去水量，用于水量平衡验证。

4.3 简化推理公式输出参数

kp（模比系数 Kp）：由 P-III 分布查表得到，无量纲。从 KP_TABLE 按 frequency_p 键值获取。若不在表中则默认取 6.02（对应 1000年一遇）。

h24p（设计频率 24h 降雨量）：浮点数，单位 mm = Kp × H24。表示该重现期下的 24 小时设计暴雨总量。

sp（暴雨雨力）：浮点数，单位 mm/h = H24P / 24^(1−n₂)。表示单位时间内的等效暴雨强度。

mu（入渗率）：浮点数，单位 mm/h。通过比例缩放 mu_ref × (H24P/H24P_ref) 得到，反映土壤的吸水能力。

tau（汇流历时）：浮点数，单位 h = 0.278 × L / (m × J^(1/3) × Qp^0.25)。表示洪水从流域最远点传播到尾矿库所需的时间。

n（暴雨递减指数）：浮点数，无量纲。τ ≤ 1 时取 n₁ = HYDRO_N1 = 0.5；否则取 n₂ = HYDRO_N2 = 0.75。

qp（设计洪峰流量）：浮点数，单位 m³/s。经迭代求解得到的理论洪峰值。

wtp / wtp_wan（洪水总量）：浮点数，单位分别为 m³ 和万m³ = 1000 × alpha24 × H24P × F。表示设计频率下的总降雨径流体积。

actual_peak（过程线实际洪峰）：浮点数，单位 m³/s。概化三角形缩放后的最大流量值。

4.4 详细推理公式输出参数

除上述参数的变体外，还包括：kp_10min/kp_1h/kp_6h/kp_24h（各历时模比系数）、h10min_face/h1h_face/h6h_face/h24h_face（各历时的面雨量）、alpha_10min/alpha_1h/alpha_6h/alpha_24h（点面折减系数）、n1/n2/n3（三个暴雨递减指数）、theta（汇流参数 θ）、m（汇流参数 m，由 theta-m 关系查得）、s（暴雨雨力 S = H_1h面）、psi（产流系数 ψ = 1 − μτ^n/S）、qm（洪峰流量 Qm）、pa（前期影响雨量）、imax（最大初损值）、r24/r6（净雨深 R24/R6）。

4.5 洪水过程线计算工具输出参数

hydrograph（洪水过程线）：列表，元素为 (时间 h, 流量 m³/s) 二元组。共 33 个时段点（t=0~32h），1 小时间隔。表示概化多峰三角形洪水过程的时程分布。

spillway_curve（泄洪能力曲线）：列表，元素为 (水头 m, 泄流量 m³/s) 二元组。覆盖水头 0.0~4.0m，步长 0.05m，共 81 个点。表示排水设施在不同水位下的最大泄流能力。

ev_curve（水位-库容曲线）：列表，元素为 (水位 m, 库容万m³) 二元组。覆盖 720.0~850.0m，步长约 1m，共 131 个点。表示尾矿库地形特征。

4.6 全流态泄流能力计算输出参数

free_flow / orifice_flow / semi_pressure_flow / pressure_flow（四种流态泄流量）：各为浮点数，单位 m³/s。分别表示在当前水头下该流态的理论最大泄流量。

controlling_flow（控制泄流量）：浮点数，单位 m³/s = min(自由流, 孔口流, 半压力流, 压力流)。物理含义为该水头下排水系统的实际最大安全泄流能力。

controlling_regime（控制流态）：字符串，指示哪种流态控制了泄流量（如”自由流”、“孔口流”、“半压力流”、“压力流”）。工程意义：帮助判断当前水位下的出流机制。

               ![图片1.png](/images/__1.png)