case2_load_trajectory_loadcsv.py）本文档说明 case2_load_trajectory_loadcsv.py 的用途、输入格式、参数、运行流程及结果判读方法。该脚本从 CSV 文件读取时间—功率设定点，按设定的时间倍率依次回放，并将功率命令发送到指定节点或广播接口。
本文档仅描述脚本中明确实现的逻辑。脚本未附带默认输入文件 csv_case.csv，因此本文不提供实际轨迹点数量、功率范围或运行结果。
本案例用于验证基于 CSV 数据的功率轨迹回放流程，主要包括：
SPEEDUP 设定的倍率调度事件；脚本还在加载 CSV 前设置 api.node[2].v = 20.0。该值为脚本设定值；其设备侧含义及是否对应真实电压下发，应以运行接口和现场节点配置为准。
当 AUTO_TO_RELATIVE = True 时，脚本调用 api.to_relative_time() 将源时间列转换为相对时间，并默认写入 time_rel_s。当其为 False 时，脚本调用 api.to_seconds_series() 将时间列转换为秒。
对每个有效轨迹点，调度时间按下式处理：
因此，负时间会被截断为 0.0 秒。事件回放时，SPEEDUP 作为 api.replay_relative_schedule() 的时间倍率参数。依据脚本注释，其时间换算关系为：
当 SPEEDUP > 1.0 时为加速回放；当前默认值为 0.5，对应以原轨迹一半速度回放，即时间间隔扩大为原来的 2 倍。
CSV 中读取的功率设定值记为 。回放事件触发时，脚本先执行符号转换：
随后 _send_power() 将 写入目标接口：
api.node[int(node)].p = power_w；api.set_broadcast_p(power_w)。因此，CSV 中的正功率值会转换为负的下发值，CSV 中的负功率值会转换为正的下发值。脚本未进一步定义正负功率在具体设备上的物理方向，实际含义应以现场接口定义为准。
目标节点按以下规则确定：
USE_NODE_FROM_CSV = True 且 CSV 中存在候选节点列时，使用该行的节点编号；TARGET_NODE；None 时，使用广播接口。当前默认配置为 TARGET_NODE = 1、USE_NODE_FROM_CSV = False，因此所有功率命令均下发至节点 1，即使 CSV 中包含节点列也不会读取该列。
脚本按候选名称从左到右选择第一个实际存在的列。
| 数据类型 | 候选列名（按优先级） | 是否必需 |
|---|---|---|
| 时间 | time、time_s、t、timestamp |
是 |
| 功率 | p、power、power_w、power_set |
是 |
| 目标节点 | node、target_node |
否；仅在 USE_NODE_FROM_CSV = True 时查找 |
源时间既可为秒数，也可为能够被运行接口转换的类日期时间字符串。可接受的具体日期时间格式由 api.to_relative_time() 和 api.to_seconds_series() 决定，脚本本身未进一步限定。
load_schedule() 对数据执行以下处理：
pandas.read_csv() 读取文件；mergesort 按调度时间升序排列；float，在启用 CSV 节点时将节点转换为 int；(t_rel, p_set, node) 列表。对于相同时间的多条记录，稳定排序会保留其在清洗前数据中的相对顺序。若清洗后没有有效记录，脚本抛出 ValueError 并停止。
main()；api.node[2].v = 20.0；resolve_input_path() 按路径候选顺序查找 CSV；START_DELAY_S > 0.0 时，输出延时提示并等待；默认等待 3.0 秒。脚本导入了 loop，但实际运行流程中未使用该对象，也未建立固定周期主循环。
若 CSV_PATH 为绝对路径，脚本仅检查该路径。若为相对路径，则依次尝试以下位置，并对重复的规范化路径去重：
src/algorithm_load/scriptcase/；algorithm_load 包目录下的 scriptcase/。若所有候选位置均不存在目标文件，脚本抛出 FileNotFoundError，错误信息会列出已搜索路径。
完成启动延时后，脚本调用 load_schedule() 读取并整理轨迹，随后记录有效轨迹点数量及实际采用的列名。replay_schedule() 将轨迹交给 api.replay_relative_schedule()，并传入时间倍率、粗粒度休眠余量和忙等阈值。
每个事件触发时，脚本读取该事件的功率及可选节点，先对功率取反，再按节点选择规则下发。底层调度函数负责基于单调时钟进行事件调度及追赶处理；具体追赶策略由 algorithm_load.script_runtime.api 的实现决定。
全部事件回放完成后，脚本输出 csv_case finished。脚本没有显式清零功率、恢复节点 2 的电压设定、调用 shutdown，也没有自定义异常捕获或键盘中断处理。因此，运行结束或异常退出后的设备状态应由运行环境及现场操作规程确认。
| 参数名 | 默认值 | 作用 |
|---|---|---|
CSV_PATH |
"csv_case.csv" |
输入 CSV 路径；相对路径按脚本定义的候选位置查找。 |
TIME_COL_CANDIDATES |
("time", "time_s", "t", "timestamp") |
时间列候选名称及识别优先级。 |
POWER_COL_CANDIDATES |
("p", "power", "power_w", "power_set") |
功率列候选名称及识别优先级。 |
NODE_COL_CANDIDATES |
("node", "target_node") |
可选节点列候选名称及识别优先级。 |
TARGET_NODE |
1 |
默认固定目标节点；设为 None 时启用广播。 |
USE_NODE_FROM_CSV |
False |
是否允许 CSV 节点列覆盖 TARGET_NODE。 |
AUTO_TO_RELATIVE |
True |
是否将源时间自动转换为相对时间。 |
RELATIVE_TIME_OUT_COL |
"time_rel_s" |
转换后时间列名；设为 None 时覆盖源时间列。 |
SPEEDUP |
0.5 |
回放时间倍率；当前值表示以原轨迹一半速度回放。 |
START_DELAY_S |
3.0 秒 |
发送功率命令前的启动延时；不大于 0.0 时跳过。 |
COARSE_SLEEP_GUARD_S |
0.010 秒 |
粗粒度休眠预留余量，用于降低过度休眠风险。 |
BUSY_WAIT_THRESHOLD_S |
0.002 秒 |
传递给回放接口的忙等阈值。 |
api.node[2].v |
20.0 |
main() 启动时写入节点 2 的 v 属性；单位及设备侧含义以接口定义为准。 |
SPEEDUP 的合法取值约束由 api.replay_relative_schedule() 决定，当前脚本未在调用前自行校验。上述数值均为脚本设定值，不代表设备额定能力或现场推荐值。
在具备有效 CSV 文件、pandas 依赖和可用运行接口的条件下，用户可通过日志观察：
脚本日志不逐点输出功率命令、节点反馈、跟踪误差或设备在线状态。因此，本文档不将该案例描述为带反馈的闭环轨迹跟踪，也不对跟踪精度作结论。
CSV_PATH 修改为实际路径。AUTO_TO_RELATIVE、RELATIVE_TIME_OUT_COL 和 SPEEDUP。2 的 v = 20.0 设置适用于当前环境。pandas 和 algorithm_load.script_runtime 的环境中运行脚本。建议先在隔离的测试环境中使用少量轨迹点演示：
TARGET_NODE = 1，保持 USE_NODE_FROM_CSV = False；SPEEDUP = 0.5 演示慢速回放，观察启动延时、加载信息和结束日志；USE_NODE_FROM_CSV 并增加有效节点列；TARGET_NODE = None，同时确保没有有效的 CSV 节点覆盖。演示前应对功率范围、节点编号及设备允许的控制模式进行现场确认。脚本自身不包含功率限幅或节点有效性检查。
| 观察项 | 判读方式 |
|---|---|
| 启动日志 | 核对 csv_path、speedup、target_node 和相关开关是否符合演示配置。 |
| 加载日志 | 核对有效点数及实际识别的列名，避免候选列优先级导致选中非预期列。 |
| 回放时序 | 根据相对时间和 SPEEDUP 计算理论触发时间；底层追赶逻辑可能在进程延迟后处理已到期事件。 |
| 功率方向 | 核对下发值与 CSV 值符号相反。 |
| 节点去向 | 默认应为节点 1；启用 CSV 节点时按每行节点值判断；最终节点为 None 时为广播。 |
| 完成状态 | 出现 csv_case finished 表示回放函数已返回并执行到脚本末尾，不代表设备已清零或关机。 |
若需评价实际调度误差、设备响应或轨迹跟踪精度，应结合运行接口记录、设备反馈或外部测量数据。当前脚本未生成这些评价数据。
csv_case.csv 当前未随脚本提供，运行前必须准备输入文件或修改路径。pandas 时，脚本在加载轨迹时抛出 RuntimeError。ValueError。float 的值可能导致运行异常。int 的节点值可能导致运行异常。RELATIVE_TIME_OUT_COL 若与现有列同名，其处理结果取决于时间转换接口的实现，使用前应核对输入数据。本文档依据 case2_load_trajectory_loadcsv.py 的静态代码生成，未执行实际设备测试。文中参数为脚本默认设定，不代表设备额定能力或特定现场的安全运行范围。节点映射、功率正负方向、v 属性含义、控制权限、设备保护、允许功率范围及结束处置应以现场接口定义、设备手册和项目配置为准。