本文档为案例函数 SDK 说明，根据现有案例脚本整理。文档描述脚本中已定义函数、参数、返回值、用途及出现位置。以下函数并非全部属于稳定公开 API；以下划线开头的函数视为案例内部实现。
case1_pv_battery_load_balance.py：Case 1：PV+BESS+Load 功率平衡case2_load_trajectory_loadcsv.py：Case 2：CSV 功率轨迹回放case3_pv_battery_load_pcc.py：Case 3：PV+BESS+Load+PCC 基础控制case3.2_more_complex_pv_battery_load_pcc.py：Case 3.2：复杂 PV/Load 扰动场景case4_rl_arbitrage.py：Case 4：SAC/RL 储能套利部署node3_cp_step_response_cv20.py：节点 CP 阶跃响应测试pro_case1_8node_2subnet_pv_bat_load_pcc.py：Pro Case：8节点双子网独立平衡pro_case1_8node_pv_bat_load_pcc.py：Pro Case：8节点统一功率分配template.py：Algorithm Load 基础模板test_readuid.py：设备 UID/标定参数读取测试api.node[node].p = -internal_power_w 完成内部符号到设备指令符号的转换。| 函数/类 | 分类 | 出现位置 |
|---|---|---|
| `_InternalRawPageSender` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:118` |
| `_InternalRawPageSender.__init__` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:119` |
| `_InternalRawPageSender.send_page_marker` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:122` |
| `_analyze_step` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:214` |
| `_as_float` | 数值与通用工具 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:49` |
| `_average_between` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:78` |
| `_average_tail` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:85` |
| `_calibration_labels` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:100` |
| `_collect_step` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:244` |
| `_decode_calibration_from_payload` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:57` |
| `_decode_uid_from_payload` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:85` |
| `_extract_response_value` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:55` |
| `_fit_first_order` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:137` |
| `_format_calibration_log` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:110` |
| `_format_offset_report` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:194` |
| `_interpolate_value` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:93` |
| `_is_finite_number` | 数值与通用工具 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:42` |
| `_iter_input_path_candidates` | 数据读取与路径处理 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:73` |
| `_linear_regression` | 数值与通用工具 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:114` |
| `_model_value` | 记录、分析与诊断 | 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:190` |
| `_normalize_run_duration_s` | 运行与入口 | Algorithm Load 基础模板，`template.py:46` 设备 UID/标定参数读取测试，`test_readuid.py:44` |
| `_pick_existing_col` | 数据读取与路径处理 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:62` |
| `_pick_value` | 数据读取与路径处理 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:182` |
| `_require_pandas` | 数据读取与路径处理 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:57` |
| `_send_power` | 调度、控制与状态更新 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:176` |
| `_u32_from_float32_slot` | 设备标识与底层报文 | 设备 UID/标定参数读取测试，`test_readuid.py:79` |
| `build_observation` | 调度、控制与状态更新 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:278` |
| `clamp` | 数值与通用工具 | Case 3：PV+BESS+Load+PCC 基础控制，`case3_pv_battery_load_pcc.py:22-23` Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:25-26` Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:99-100` Pro Case：8节点双子网独立平衡，`pro_case1_8node_2subnet_pv_bat_load_pcc.py:38-39` Pro Case：8节点统一功率分配，`pro_case1_8node_pv_bat_load_pcc.py:29-30` |
| `clip_to_soc` | 调度、控制与状态更新 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:304` |
| `get_latest_power_w` | 数据读取与路径处理 | Case 1：PV+BESS+Load 功率平衡，`case1_pv_battery_load_balance.py:28-36` Case 3：PV+BESS+Load+PCC 基础控制，`case3_pv_battery_load_pcc.py:48-56` Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:193-203` |
| `iter_case_dir_candidates` | 数据读取与路径处理 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:119` |
| `load3_wave_w` | 波形与场景生成 | Pro Case：8节点双子网独立平衡，`pro_case1_8node_2subnet_pv_bat_load_pcc.py:50` Pro Case：8节点统一功率分配，`pro_case1_8node_pv_bat_load_pcc.py:41` |
| `load7_wave_w` | 波形与场景生成 | Pro Case：8节点双子网独立平衡，`pro_case1_8node_2subnet_pv_bat_load_pcc.py:56` Pro Case：8节点统一功率分配，`pro_case1_8node_pv_bat_load_pcc.py:47` |
| `load_episode_data` | 数据读取与路径处理 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:221` |
| `load_schedule` | 数据读取与路径处理 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:130` |
| `load_torch_actor` | 调度、控制与状态更新 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:315` |
| `load_wave_w` | 波形与场景生成 | Case 1：PV+BESS+Load 功率平衡，`case1_pv_battery_load_balance.py:22-25` Case 3：PV+BESS+Load+PCC 基础控制，`case3_pv_battery_load_pcc.py:34-37` Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:106-180` |
| `local_battery_balance_w` | 调度、控制与状态更新 | Pro Case：8节点双子网独立平衡，`pro_case1_8node_2subnet_pv_bat_load_pcc.py:71` |
| `main` | 运行与入口 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:198` 节点 CP 阶跃响应测试，`node3_cp_step_response_cv20.py:273` |
| `pcc_wave_w` | 波形与场景生成 | Case 3：PV+BESS+Load+PCC 基础控制，`case3_pv_battery_load_pcc.py:40-46` Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:185-191` |
| `pv_wave_w` | 波形与场景生成 | Case 1：PV+BESS+Load 功率平衡，`case1_pv_battery_load_balance.py:16-19` Case 3：PV+BESS+Load+PCC 基础控制，`case3_pv_battery_load_pcc.py:26-31` Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:36-101` Pro Case：8节点双子网独立平衡，`pro_case1_8node_2subnet_pv_bat_load_pcc.py:42-47` Pro Case：8节点统一功率分配，`pro_case1_8node_pv_bat_load_pcc.py:33-38` |
| `quantile_fallback` | 数值与通用工具 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:103` |
| `read_node_power_timeout0` | 数据读取与路径处理 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:190` |
| `replay_schedule` | 调度、控制与状态更新 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:184` |
| `resolve_case_dir` | 数据读取与路径处理 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:159` |
| `resolve_input_path` | 数据读取与路径处理 | Case 2：CSV 功率轨迹回放，`case2_load_trajectory_loadcsv.py:118` |
| `save_power_soc_table` | 记录、分析与诊断 | Case 3.2：复杂 PV/Load 扰动场景，`case3.2_more_complex_pv_battery_load_pcc.py:206` |
| `split_battery_power` | 调度、控制与状态更新 | Pro Case：8节点统一功率分配，`pro_case1_8node_pv_bat_load_pcc.py:62` |
| `write_runtime_record_row` | 记录、分析与诊断 | Case 4：SAC/RL 储能套利部署，`case4_rl_arbitrage.py:200` |
main()case2_load_trajectory_loadcsv.py:198-219；节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:273-282None。_normalize_run_duration_s(value)功能：将运行时长参数标准化；支持 inf/infinite 等无限运行写法，非正或非有限值也转换为无限运行。
出现位置：Algorithm Load 基础模板，template.py:46-56；设备 UID/标定参数读取测试，test_readuid.py:44-55
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
未显式标注 |
无 |
待处理输入值 |
返回值：未显式标注。
clamp(value: float, lower: float, upper: float)功能：将数值限制在给定上下界之间，是功率、SOC、动作值等安全约束的基础工具。
出现位置：Case 3：PV+BESS+Load+PCC 基础控制，case3_pv_battery_load_pcc.py:22-23；Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:25-26；Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:99-100；Pro Case：8节点双子网独立平衡，pro_case1_8node_2subnet_pv_bat_load_pcc.py:38-39；Pro Case：8节点统一功率分配，pro_case1_8node_pv_bat_load_pcc.py:29-30
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
float |
无 |
待处理输入值 |
lower |
float |
无 |
允许的下限 |
upper |
float |
无 |
允许的上限 |
返回值：float。
quantile_fallback(values, q)功能：不依赖 NumPy，使用线性插值计算指定分位数。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:103-116
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
values |
未显式标注 |
无 |
输入数值序列 |
q |
未显式标注 |
无 |
分位数，范围0~1 |
返回值：未显式标注。
源码说明：Compute quantile without numpy, using linear interpolation.
_is_finite_number(value)功能：判断输入是否能够转换为有限浮点数。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:42-46
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
未显式标注 |
无 |
待处理输入值 |
返回值：bool。
_as_float(value, default=None)功能：在输入有效时转换为 float，否则返回默认值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:49-52
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
未显式标注 |
无 |
待处理输入值 |
default |
未显式标注 |
None |
输入无效时返回的默认值 |
返回值：未显式标注。
_linear_regression(xs, ys)功能：执行一元线性回归并返回斜率、截距和R²。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:114-134
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
xs |
未显式标注 |
无 |
自变量序列 |
ys |
未显式标注 |
无 |
因变量序列 |
返回值：未显式标注。
pv_wave_w(elapsed_s: float)功能：根据运行时间生成 PV 功率轨迹。不同 Case 中的周期、幅值和扰动结构不同。
出现位置：Case 1：PV+BESS+Load 功率平衡，case1_pv_battery_load_balance.py:16-19；Case 3：PV+BESS+Load+PCC 基础控制，case3_pv_battery_load_pcc.py:26-31；Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:36-101；Pro Case：8节点双子网独立平衡，pro_case1_8node_2subnet_pv_bat_load_pcc.py:42-47；Pro Case：8节点统一功率分配，pro_case1_8node_pv_bat_load_pcc.py:33-38
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
elapsed_s |
float |
无 |
案例启动后的经过时间，单位 s |
返回值：float。
注意事项：同名函数在不同 Case 中实现不同，不能仅按函数名判断轨迹。
load_wave_w(elapsed_s: float)功能：根据运行时间生成负载功率轨迹。不同 Case 中可能为正弦、峰谷组合或带突发事件的复杂负载。
出现位置：Case 1：PV+BESS+Load 功率平衡，case1_pv_battery_load_balance.py:22-25；Case 3：PV+BESS+Load+PCC 基础控制，case3_pv_battery_load_pcc.py:34-37；Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:106-180
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
elapsed_s |
float |
无 |
案例启动后的经过时间，单位 s |
返回值：float。
注意事项：同名函数在不同 Case 中实现不同，不能仅按函数名判断轨迹。
pcc_wave_w(elapsed_s: float)功能：生成 PCC 目标功率轨迹；部分案例中固定为 0 W，PCC主要工作在恒压模式。
出现位置：Case 3：PV+BESS+Load+PCC 基础控制，case3_pv_battery_load_pcc.py:40-46；Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:185-191
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
elapsed_s |
float |
无 |
案例启动后的经过时间，单位 s |
返回值：float。
注意事项：同名函数在不同 Case 中实现不同，不能仅按函数名判断轨迹。
load3_wave_w(elapsed_s: float)功能：生成节点3负载功率轨迹。
出现位置：Pro Case：8节点双子网独立平衡，pro_case1_8node_2subnet_pv_bat_load_pcc.py:50-53；Pro Case：8节点统一功率分配，pro_case1_8node_pv_bat_load_pcc.py:41-44
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
elapsed_s |
float |
无 |
案例启动后的经过时间，单位 s |
返回值：float。
注意事项：同名函数在不同 Case 中实现不同，不能仅按函数名判断轨迹。
load7_wave_w(elapsed_s: float)功能：生成节点7负载功率轨迹，通常用于与节点3形成不同周期或相位的负载。
出现位置：Pro Case：8节点双子网独立平衡，pro_case1_8node_2subnet_pv_bat_load_pcc.py:56-68；Pro Case：8节点统一功率分配，pro_case1_8node_pv_bat_load_pcc.py:47-59
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
elapsed_s |
float |
无 |
案例启动后的经过时间，单位 s |
返回值：float。
注意事项：同名函数在不同 Case 中实现不同，不能仅按函数名判断轨迹。
get_latest_power_w(node: int, fallback: float)功能：读取指定节点最新 p1 功率与在线状态；无有效数据时返回回退功率。
出现位置：Case 1：PV+BESS+Load 功率平衡，case1_pv_battery_load_balance.py:28-36；Case 3：PV+BESS+Load+PCC 基础控制，case3_pv_battery_load_pcc.py:48-56；Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:193-203
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
node |
int |
无 |
节点编号 |
fallback |
float |
无 |
读取失败时使用的回退功率，单位 W |
返回值：tuple[float, bool]。
注意事项：返回的功率方向取决于设备反馈定义；当前函数本身不统一转换符号。
_require_pandas()case2_load_trajectory_loadcsv.py:57-59None。_pick_existing_col(df, candidates, *, required: bool=True)功能：从候选列名中选择数据表实际存在的列，可配置是否必须存在。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:62-70
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
df |
未显式标注 |
无 |
pandas DataFrame |
candidates |
未显式标注 |
无 |
候选列名序列 |
required |
bool |
True |
未找到列时是否抛出异常 |
返回值：未显式标注。
_iter_input_path_candidates(raw_path: str)功能：按绝对路径、当前目录、脚本目录和包内 scriptcase 目录依次生成候选输入路径。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:73-115
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
raw_path |
str |
无 |
原始文件路径字符串 |
返回值：未显式标注。
resolve_input_path(raw_path: str)功能：搜索并返回真实存在的 CSV 路径；未找到时列出全部搜索位置。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:118-127
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
raw_path |
str |
无 |
原始文件路径字符串 |
返回值：Path。
load_schedule(path: Path)功能：读取 CSV，识别时间/功率/节点列，将时间转为相对秒并生成按时间排序的调度列表。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:130-173
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
path |
Path |
无 |
文件路径对象 |
返回值：未显式标注。
iter_case_dir_candidates()case4_rl_arbitrage.py:119-156未显式标注。resolve_case_dir(required_files=None)功能：查找同时包含指定必需文件的案例目录。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:159-179
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
required_files |
未显式标注 |
None |
目标目录必须包含的文件名集合 |
返回值：未显式标注。
源码说明：Resolve the on-disk case directory even when file is a runner placeholder.
_pick_value(row, keys)功能：从CSV行中按候选键顺序提取首个有效值。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:182-187
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
row |
未显式标注 |
无 |
CSV行或字典对象 |
keys |
未显式标注 |
无 |
候选字段名 |
返回值：未显式标注。
read_node_power_timeout0(node_id)功能：非阻塞读取节点功率；不可用时返回 NaN。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:190-197
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
node_id |
未显式标注 |
无 |
节点编号 |
返回值：未显式标注。
源码说明：Read node power using timeout=0, return NaN when unavailable.
load_episode_data(csv_path, preferred_episode)功能：从 episodes.csv 加载指定或可用的一个 episode，返回 PV、Load、Price 序列及 episode 信息。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:221-275
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
csv_path |
未显式标注 |
无 |
episode CSV路径 |
preferred_episode |
未显式标注 |
无 |
优先选择的episode编号 |
返回值：未显式标注。
源码说明：Load one episode from CSV. Returns: pv_data, load_data, price_data, selected_episode, available_episodes
_send_power(power_w: float, row_node=None)功能：将一条功率设定发送到指定节点，或在广播模式下发送。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:176-181
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
power_w |
float |
无 |
功率设定值，单位 W |
row_node |
未显式标注 |
None |
当前调度行指定的节点，可为空 |
返回值：None。
replay_schedule(schedule)功能：按照调度时间精确回放 CSV 功率事件，并执行赶帧逻辑。
出现位置：Case 2：CSV 功率轨迹回放，case2_load_trajectory_loadcsv.py:184-195
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
schedule |
未显式标注 |
无 |
按时间排序的调度事件列表 |
返回值：None。
build_observation(step, n_steps, soc_wh, net_load_w, price_now, price_data, last_action)功能：构造与训练环境一致的强化学习观测向量，包括SOC、净负荷、价格预测和上一动作。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:278-301
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
step |
未显式标注 |
无 |
当前步索引 |
n_steps |
未显式标注 |
无 |
总步数 |
soc_wh |
未显式标注 |
无 |
当前储能能量，单位Wh |
net_load_w |
未显式标注 |
无 |
净负荷功率，单位W |
price_now |
未显式标注 |
无 |
当前电价 |
price_data |
未显式标注 |
无 |
完整电价序列 |
last_action |
未显式标注 |
无 |
上一时刻动作 |
返回值：未显式标注。
源码说明：Construct 12-dim observation matching env_netload.py::_obs().
clip_to_soc(p_bat_w, energy_wh, min_wh, max_wh, dt_h)功能：根据SOC上下限、能量和步长裁剪电池充放电功率，确保动作物理可行。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:304-312
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
p_bat_w |
未显式标注 |
无 |
候选电池功率，单位W |
energy_wh |
未显式标注 |
无 |
当前电池能量，单位 Wh |
min_wh |
未显式标注 |
无 |
最小允许能量，单位Wh |
max_wh |
未显式标注 |
无 |
最大允许能量，单位Wh |
dt_h |
未显式标注 |
无 |
时间步长，单位h |
返回值：未显式标注。
源码说明：Clip battery power to SOC-feasible range, matching env_netload.py.
load_torch_actor(model_path)功能：加载导出的 PyTorch SAC Actor 权重，并返回 predict(obs) 推理函数。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:315-377
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model_path |
未显式标注 |
无 |
Actor权重文件路径 |
返回值：未显式标注。
源码说明：Load pure PyTorch actor weights exported by export_for_deploy.py. Returns a callable predict(obs) -> action_float.
注意事项：模型结构和观测维度必须与训练导出配置完全一致。
local_battery_balance_w(pv_cmd_w: float, load_cmd_w: float)功能：根据本地 PV 与 Load 指令计算使单个子网自平衡所需的电池功率。
出现位置：Pro Case：8节点双子网独立平衡，pro_case1_8node_2subnet_pv_bat_load_pcc.py:71-73
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pv_cmd_w |
float |
无 |
PV内部功率指令，单位 W |
load_cmd_w |
float |
无 |
Load内部功率指令，单位 W |
返回值：float。
源码说明：Return battery internal power that makes one subnet self-balanced.
split_battery_power(total_battery_w: float, mode: str, battery2_weight: float, battery6_weight: float)功能：按平均或权重比例将总电池功率需求分配给两个储能节点。
出现位置：Pro Case：8节点统一功率分配，pro_case1_8node_pv_bat_load_pcc.py:62-89
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
total_battery_w |
float |
无 |
需要分配的总电池功率，单位 W |
mode |
str |
无 |
分配模式：equal 或 ratio |
battery2_weight |
float |
无 |
电池2权重 |
battery6_weight |
float |
无 |
电池6权重 |
返回值：tuple[float, float]。
源码说明：Split the required total battery power to battery nodes 2 and 6. mode: - "equal": 50/50 split - "ratio": weighted split by battery2_weight:battery6_weight
save_power_soc_table(rows: list[list[float]], output_dir: Path)功能：将运行过程中的功率与SOC数据写入CSV结果表。
出现位置：Case 3.2：复杂 PV/Load 扰动场景，case3.2_more_complex_pv_battery_load_pcc.py:206-222
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
rows |
list[list[float]] |
无 |
待保存的数据行 |
output_dir |
Path |
无 |
输出目录 |
返回值：Path。
write_runtime_record_row(record_writer, record_fp, soc_pct, price, cashflow_aud, cumul_cashflow_aud)功能：写入一行运行遥测数据，并刷新文件缓冲区。
出现位置：Case 4：SAC/RL 储能套利部署，case4_rl_arbitrage.py:200-218
可见性建议：可复用函数，但复用前应确认功率符号、单位和节点映射
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
record_writer |
未显式标注 |
无 |
CSV writer对象 |
record_fp |
未显式标注 |
无 |
已打开的记录文件对象 |
soc_pct |
未显式标注 |
无 |
SOC百分比 |
price |
未显式标注 |
无 |
当前价格 |
cashflow_aud |
未显式标注 |
无 |
当前步现金流 |
cumul_cashflow_aud |
未显式标注 |
无 |
累计现金流 |
返回值：未显式标注。
源码说明：Write one runtime telemetry sample row.
_extract_response_value(payload)功能：从节点反馈字典或原始数组中提取阶跃响应功率值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:55-75
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
payload |
未显式标注 |
无 |
节点反馈字典 |
返回值：未显式标注。
_average_between(samples, start_s, end_s)功能：计算指定时间区间内采样值的平均值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:78-82
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
start_s |
未显式标注 |
无 |
区间起始时间，单位s |
end_s |
未显式标注 |
无 |
区间结束时间，单位s |
返回值：未显式标注。
_average_tail(samples, window_s)功能：计算采样序列尾部指定时间窗口的平均值，用于估计稳态值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:85-90
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
window_s |
未显式标注 |
无 |
尾部平均窗口，单位s |
返回值：未显式标注。
_interpolate_value(samples, offset_s)功能：在采样点之间进行线性插值，得到指定时间偏移处的响应值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:93-111
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
offset_s |
未显式标注 |
无 |
相对阶跃起点的时间偏移，单位s |
返回值：未显式标注。
_fit_first_order(samples, target_w)功能：将阶跃响应拟合为一阶惯性模型，估计稳态值、时间常数、增益和拟合优度。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:137-187
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
target_w |
未显式标注 |
无 |
阶跃目标功率，单位W |
返回值：未显式标注。
_model_value(fit, offset_s)功能：根据一阶拟合参数计算指定时刻的模型预测值。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:190-191
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
fit |
未显式标注 |
无 |
一阶模型拟合结果 |
offset_s |
未显式标注 |
无 |
相对阶跃起点的时间偏移，单位s |
返回值：未显式标注。
_format_offset_report(samples, target_w, fit, offset_s)功能：生成指定时间偏移处实测值、模型值和误差的日志文本。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:194-211
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
target_w |
未显式标注 |
无 |
阶跃目标功率，单位W |
fit |
未显式标注 |
无 |
一阶模型拟合结果 |
offset_s |
未显式标注 |
无 |
相对阶跃起点的时间偏移，单位s |
返回值：未显式标注。
_analyze_step(step_no, target_w, samples)功能：汇总一次阶跃试验结果，执行一阶拟合并输出关键动态指标。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:214-241
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
step_no |
未显式标注 |
无 |
阶跃序号 |
target_w |
未显式标注 |
无 |
阶跃目标功率，单位W |
samples |
未显式标注 |
无 |
(时间,数值)采样序列 |
返回值：未显式标注。
_collect_step(step_no, target_w)功能：下发一次阶跃设定并在保持时间内周期采集节点响应。
出现位置：节点 CP 阶跃响应测试，node3_cp_step_response_cv20.py:244-270
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
step_no |
未显式标注 |
无 |
阶跃序号 |
target_w |
未显式标注 |
无 |
阶跃目标功率，单位W |
返回值：未显式标注。
_decode_calibration_from_payload(payload)功能：从节点反馈中解析四个标定参数。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:57-76
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
payload |
未显式标注 |
无 |
节点反馈字典 |
返回值：未显式标注。
_u32_from_float32_slot(value)功能：将承载在 float32 数据槽中的原始比特重新解释为无符号32位整数。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:79-82
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
未显式标注 |
无 |
待处理输入值 |
返回值：未显式标注。
_decode_uid_from_payload(payload)功能：从 v1/i1/p1/v2 数据槽中解析固件版本和 UID 字段。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:85-97
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
payload |
未显式标注 |
无 |
节点反馈字典 |
返回值：未显式标注。
_calibration_labels(suffix)功能：根据标定通道后缀生成对应的 V/I 增益和偏置标签。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:100-107
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
suffix |
未显式标注 |
无 |
标定通道后缀 |
返回值：未显式标注。
_format_calibration_log(node, suffix, values)功能：将节点标定参数格式化为可读日志文本。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:110-115
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
node |
未显式标注 |
无 |
节点编号 |
suffix |
未显式标注 |
无 |
标定通道后缀 |
values |
未显式标注 |
无 |
输入数值序列 |
返回值：未显式标注。
class _InternalRawPageSendertest_readuid.py:118-127类对象。_InternalRawPageSender.__init__(self, node)功能：封装内部原始报文页标记发送逻辑。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:119-120
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
node |
未显式标注 |
无 |
节点编号 |
返回值：未显式标注。
_InternalRawPageSender.send_page_marker(self, marker_value, repeat=1)功能：封装内部原始报文页标记发送逻辑。
出现位置：设备 UID/标定参数读取测试，test_readuid.py:122-127
可见性建议：内部函数，不建议作为稳定SDK直接依赖
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
marker_value |
未显式标注 |
无 |
原始页标记值 |
repeat |
未显式标注 |
1 |
重复发送次数 |
返回值：未显式标注。
这些接口由 algorithm_load.script_runtime 注入，不是在案例脚本中定义，但所有 Case 均依赖它们。
| 接口 | 功能 | 典型用法 |
|---|---|---|
api.node[n].p = value |
设置节点恒功率（CP）指令 | api.node[pv_node].p = -internal_power_w |
api.node[n].v = value |
设置节点恒压（CV）指令 | api.node[pcc_node].v = 20.0 |
api.node[n].i = value |
设置节点恒流（CC）指令 | 按设备能力使用 |
api.node[n].get_data(timeout=0) |
非阻塞读取节点最新反馈字典 | 读取 p1、v1、online 等字段 |
api.node[n].shutdown() |
关断指定节点 | 脚本结束或异常处理 |
api.sleep(seconds) |
可中断延时 | 启动安全延时、事件调度 |
api.now() |
读取运行时逻辑时钟 | 控制循环计时 |
api.log(text) |
输出平台日志 | 运行状态、报警和指标 |
loop(period_s) |
生成可中断的精确定时循环 | for _ in loop(period_s): ... |
api.set_broadcast_p(value) |
广播功率指令 | CSV轨迹广播模式 |
api.to_relative_time(...) |
将时间列转换为相对时间 | CSV轨迹预处理 |
api.to_seconds_series(...) |
将时间列转换为秒序列 | 已有相对时间的标准化 |