开发者文档

准备测试数据，在工作台完成建模与验证，再将参数和结果用于工程分析。

进入工作台

支持范围

当前标准流程支持 NMC 单电芯、25°C、SOC 20%–100%。单次模型的适用范围还取决于拟合节点、开路电压参考和独立验证记录的覆盖情况，具体条件保留在模型与报告中。LFP、多温度和整包分析需先确认适配范围。

工作台流程

任务成功进入计算队列时记录 1 次分析；有额度的方案同时扣除 1 次额度，Advanced 记录实际使用量。重复提交同一任务、上传与格式检查不重复计量。

注册并验证邮箱，进入自己的工作空间。
新建分析，填写电芯、容量、SOC 节点、电流方向、数据类型和来源授权。
分别选择一份拟合记录、一份独立验证记录和一份开路电压曲线。使用下方模板保留准确表头。
提交后，软件依次检查输入、拟合模型并对照独立记录验证。可在项目页查看状态或取消任务。
查看完整的覆盖率、误差与复核提示并下载报告。Pro 和 Advanced 另可下载验证 JSON 和模型候选。

项目与来源信息

名称和来源使用可读文字。SOC 与初始状态由数据提供方给出；保留初始荷电状态的依据，便于核验模型使用条件。

创建分析所需的信息
字段	含义	要求
`name`	项目名称	1–100 个字符。
`cell_id`	电芯编号	1–64 个字符；使用可追溯的样品标识。
`capacity_ah`	电芯容量	单位 Ah；大于 0，上限 10000。
`nodes`	SOC 节点	2–12 个有限数值，严格递增，取值 0.2–1；按小数填写。
`current_sign`	电流正负约定	选择 discharge_positive（放电为正）或 charge_positive（充电为正），与 CSV 一致。
`data_kind`	数据类型	measured 表示实测数据；synthetic 表示模拟数据。
`ocv_source`	开路电压来源	必填，最长 300 个字符；说明参考曲线的来源。
`authorization_reference`	数据授权依据	必填，最长 300 个字符；记录自有数据或使用授权的依据。
`authorized`	本次计算授权	确认有权使用这些数据，并授权用于本次计算和结果交付。

CSV 字段与模板

CSV 使用 UTF-8 编码，允许 UTF-8 BOM。列名须与模板一致且不能重复；除下表列出的可选列外，不添加其他列。所有保留列逐行填写有限数值，不能留空或填写 NaN、Infinity。

拟合与验证使用不同的测试记录。重复文件或重复轨迹会在输入与计算检查中被拒绝。
文件格式、测试工况和计算规模分别检查。

文件大小与行数
记录类型	单文件上限	数据行数（不含表头）
拟合记录	64 MiB（67,108,864 bytes）	2–500000
独立验证记录	64 MiB（67,108,864 bytes）	2–500000
开路电压曲线	8 MiB（8,388,608 bytes）	至少 2 行

拟合与独立验证记录的必填列
列名	单位	填写方式
`time_s`	s	时间严格递增，相邻行不能使用相同时间。
`current_A`	A	按所选电流方向填写；导出的模型使用放电为正的约定。
`voltage_V`	V	对应时间点的测试电压。
`soc`	比例	使用小数，例如 0.8 表示 80%。
`temp_C`	°C	试验箱设定温度，与支持范围一致。

可选列
列名	适用记录	含义与默认值
`loss_mask`	拟合	0 或 1，控制该行是否参与拟合；省略整列时为 1。
`row_weight`	拟合	大于 0 的权重；省略整列时为 1。
`drive_mask`	独立验证	0 或 1，标记驾驶片段；省略整列时为 1。

拟合记录模板表头

time_s,current_A,voltage_V,soc,temp_C,loss_mask,row_weight

独立验证记录模板表头

time_s,current_A,voltage_V,soc,temp_C,drive_mask

开路电压曲线表头

soc,voltage_V

开路电压曲线只保留这两列，并按此顺序排列。SOC 取值 0–1，严格递增；电压单位为 V。

验证指标与判定

本次任务采用的阈值随验证结果保留。这些数值是核验条件；实际误差由本次数据计算得到。记录结果同时检查驾驶片段指标与模型核验结果。

新拟合模型以候选形式交付，需结合复核提示确认初始状态和工程使用条件。客户验收单独记录；未执行、未通过和排除行数在结果中保留。

报告中的指标
指标	含义
总行数	该验证记录包含的全部数据行。
域内行数	模型声明 SOC 范围内的数据行。
评分行数	域内实际参与误差计算的有效行。
域内覆盖率	评分行数除以域内行数；域外行与域内无效行另行保留。
RMSE	评分行上电压误差的均方根，单位 mV。
最大误差	评分行上电压误差绝对值的最大值，单位 mV。

当前标准核验阈值
指标	判定条件
RMSE	≤ 10 mV
最大误差	≤ 30 mV
域内覆盖率	≥ 99%

交付文件

所有方案均可查看完整的在线验证指标、范围与复核提示并下载报告。Pro 和 Advanced 另提供工程数据与模型导出。验证未通过时，检查报告和记录明细，按具体原因处理数据或模型条件。

验证报告：Markdown，包含结论、记录分母、误差、适用条件和复核说明。
Pro 和 Advanced：验证结果 JSON，保留每条验证记录的指标、驾驶片段指标、核验阈值和计算耗时。
Pro 和 Advanced：模型通过相应检查后提供 ZIP，包含参数 JSON、C 与 MATLAB 参数表、CSV 参数表及使用说明。
模型包中的 simulation/ 提供 C99 前向电压预测程序、示例输入和运行说明，可用于本地仿真或集成到自己的 C 程序。

模型与仿真集成

在工作台上传数据并下载结果。将模型用于自己的程序时，从导出的参数文件和电压预测程序开始。模型参数 JSON 的格式版本为 battery.customer.model.v1；读取时保留 conventions、initial_state、contract 和 warnings 中的输入约定、初始状态与使用条件。

使用支持 64 位双精度的 C99 编译器。仿真输入表头依次为 time_s,current_A,soc。时间须严格递增，电流以放电为正，SOC 使用小数。温度参数选择模型已有的温度表。

输出包含 voltage_V、valid 和 held。valid 表示输入位于模型与 OCV 表声明的范围内；held 表示该点使用边界节点的参数。

退出码为 0 时输出完整，其他退出码的输出应丢弃。用对应实测记录评估新负载工况的预测误差，并在目标设备上核对浮点结果与执行时间。编译和运行步骤见包内 README。

常见检查与处理

项目与结果可在工作台下载或删除。数据处理地区、保存期限与删除安排见隐私政策；费用、取消和退款处理以相应服务政策为准。

按提示定位问题
提示类型	处理方式
编码、表头或空值错误	另存为 UTF-8 CSV，使用对应模板，检查所有保留列的数值。
时间、SOC 或温度检查未通过	检查时间顺序、SOC 单位以及测试条件，按支持范围准备数据。
拟合与验证重复	提供独立采集或独立保留的验证记录，检查数据分组。
数据超出计算规模	联系支持确认任务规模；保留原数据及目标条件，按确认的安排重试。
覆盖率不足或误差未通过	查看域内有效行、驾驶片段和误差指标，结合数据质量与模型适用条件复核。
计算未完成或服务正在恢复	保留项目与已上传文件，按页面提示重试或联系 [email protected]。