Developer documentation

Prepare test data, fit and validate a model in the workspace, then use the parameters and results in your engineering workflow.

Open workspace

Supported scope

The standard workflow supports single NMC cells at 25°C and SOC 20%–100%. Each model's applicable range also depends on the fitting nodes, open-circuit voltage reference and coverage of the independent validation records. The model and report retain these conditions. Confirm support for LFP, multi-temperature or battery-pack analysis before preparing a task.

Workspace workflow

An analysis is recorded when a task successfully enters the compute queue. Plans with an allowance also use one credit; Advanced records actual usage. Resubmitting the same task is not counted again. Uploads and format checks are not counted.

Register, verify your email and open your workspace.
Create an analysis. Enter the cell, capacity, SOC nodes, current sign convention, data type and source authorization.
Select one fitting file, one independent validation file and one open-circuit voltage curve. Use the templates below to retain the exact headers.
Submit the task. The software checks the inputs, fits the model and validates it against the independent record. View its status or cancel it from the project page.
Review full coverage, errors and review notes, then download the report. Pro and Advanced also provide validation JSON and the candidate model.

Project and source information

Use readable text for names and sources. The data provider supplies SOC and the initial state. Keep the basis for the initial state of charge so that the model's conditions for use can be checked.

Information needed to create an analysis
Field	Meaning	Requirement
`name`	Project name	1–100 characters.
`cell_id`	Cell identifier	1–64 characters. Use a traceable sample identifier.
`capacity_ah`	Cell capacity	In Ah; greater than 0 and no more than 10000.
`nodes`	SOC nodes	2–12 finite values, strictly increasing within 0.2–1. Use fractions.
`current_sign`	Current sign convention	Choose discharge_positive or charge_positive to match the CSV data.
`data_kind`	Data type	measured for measured data; synthetic for simulated data.
`ocv_source`	Open-circuit voltage source	Required, up to 300 characters. State the source of the reference curve.
`authorization_reference`	Basis for data authorization	Required, up to 300 characters. Record your ownership or permission to use the data.
`authorized`	Authorization for this computation	Confirm your right to use the data and authorize its use for this computation and delivery.

CSV fields and templates

Save CSV files in UTF-8; a UTF-8 BOM is accepted. Use the exact template column names without duplicates. Add only the optional columns listed below. Every included column must contain finite numbers in every row, with no empty values, NaN or Infinity.

Use different test records for fitting and validation. Duplicate files or trajectories are rejected during input and computation checks.
File format, test conditions and computation size are checked separately.

File sizes and row counts
Record type	Limit per file	Data rows, excluding header
Fitting records	64 MiB (67,108,864 bytes)	2–500000
Independent validation records	64 MiB (67,108,864 bytes)	2–500000
Open-circuit voltage curve	8 MiB (8,388,608 bytes)	At least 2

Required columns for fitting and validation records
Column	Unit	How to fill it
`time_s`	s	Strictly increasing time. Adjacent rows must have different timestamps.
`current_A`	A	Match the selected current sign convention. Exported models use discharge-positive current.
`voltage_V`	V	Measured voltage at the corresponding time.
`soc`	Fraction	Use a decimal fraction: 0.8 means 80%.
`temp_C`	°C	Chamber temperature setpoint, consistent with the supported scope.

Optional columns
Column	Record type	Meaning and default
`loss_mask`	Fitting	0 or 1: whether the row participates in fitting. Defaults to 1 when the whole column is omitted.
`row_weight`	Fitting	A weight greater than 0. Defaults to 1 when the whole column is omitted.
`drive_mask`	Independent validation	0 or 1: marks driving segments. Defaults to 1 when the whole column is omitted.

Fitting template header

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

Independent validation template header

time_s,current_A,voltage_V,soc,temp_C,drive_mask

Open-circuit voltage header

soc,voltage_V

Use only these two columns, in this order. SOC must be strictly increasing within 0–1. Voltage is in V.

Validation metrics and decisions

The thresholds used for a task are retained with its validation results. They are acceptance conditions for the checks; the actual errors are computed from that task's data. Record decisions also use driving-segment metrics and model checks.

Newly fitted models are delivered as candidates. Use the review notes to confirm the initial state and conditions for engineering use. Customer acceptance is recorded separately. Counts of records not run, failed checks and excluded rows remain in the results.

Metrics in the report
Metric	Meaning
Total rows	All data rows in the validation record.
Rows in domain	Rows within the model's declared SOC range.
Scored rows	Valid rows in the domain that participate in error calculations.
In-domain coverage	Scored rows divided by rows in domain. Rows outside the domain and invalid rows within it are retained separately.
RMSE	Root mean square voltage error over scored rows, in mV.
Maximum error	Maximum absolute voltage error over scored rows, in mV.

Current standard validation thresholds
Metric	Condition
RMSE	≤ 10 mV
Maximum error	≤ 30 mV
In-domain coverage	≥ 99%

Deliverables

Every plan includes full validation metrics, scope and review notes online and a downloadable report. Pro and Advanced also provide engineering data and model exports. If validation fails, use the report and record details to identify the data or model conditions that need attention.

Validation report: Markdown with conclusions, record counts, errors, applicable conditions and review notes.
Pro and Advanced: validation JSON with metrics for each validation record, driving-segment metrics, validation thresholds and computation times.
Pro and Advanced: a candidate model ZIP after the relevant checks pass, containing model parameters in JSON, C and MATLAB parameter tables, CSV parameter tables and instructions.
The model package's simulation/ folder provides a C99 forward voltage predictor, example input and instructions for local simulation or integration into your own C program.

Model and simulation integration

Upload data and download results through the workspace. To use the model in your own program, start with the exported parameters and voltage prediction program. The model parameter JSON uses format version battery.customer.model.v1. Preserve the input conventions, initial state and conditions in conventions, initial_state, contract and warnings.

Use a C99 compiler that supports 64-bit double precision. The simulation input header is time_s,current_A,soc, in that order. Time must strictly increase. Current is positive on discharge, and SOC is a fraction. The temperature argument selects an existing model temperature table.

Outputs include voltage_V, valid and held. The valid flag checks whether an input is within the ranges declared by the model and OCV table. The held flag identifies points where boundary-node parameters are used.

An exit code of 0 means the output is complete. Discard output for any other exit code. Assess prediction errors for new load profiles using corresponding measured records. Check floating-point results and execution time on the target device. Follow the package README to compile and run the program.

Checks and troubleshooting

Download results or delete projects in the workspace. The privacy policy explains processing locations, retention and deletion. The relevant service policies cover billing, cancellation and refunds.

Responding to check results
Issue	Action
Encoding, header or missing-value errors	Save as UTF-8 CSV, use the matching template and check the values in every included column.
Time, SOC or temperature check fails	Check time order, SOC units and test conditions against the supported scope.
Fitting and validation records overlap	Provide independently collected or separately held validation records. Check how the data was grouped.
Data exceeds the supported computation size	Contact support to confirm the task size. Keep the original data and target conditions, then retry as agreed.
Coverage or error checks fail	Review valid rows in domain, driving segments and error metrics alongside data quality and model conditions.
Computation is incomplete or the service is recovering	Keep the project and uploaded files. Follow the page instructions to retry or contact [email protected].