Skip to main content
The ECM Parameterization tool fits an equivalent circuit model (ECM) to experimental battery cycling data directly in the browser. Fit a measurement that you’ve already uploaded to a project, upload your own file, or use one of the built-in example datasets to extract OCV, R0, and RC-pair parameters as functions of state of charge (SOC). There are two ways to launch the tool:
  • Inside a project — open the ECM Fitting page from the project sidebar. You can pick a measurement that’s already attached to one of the project’s cells and the result is saved back to the project.
  • Standalone demo — visit studio.ionworks.com/ecm-demo directly. No login is required, and you can experiment with example datasets or upload a one-off file without saving anything.

​
How it works

The tool fits a circuit consisting of an open-circuit voltage (OCV) source, a series resistance (R0), and one or more RC pairs to time-series voltage and current data. The fitting process extracts parameters as smooth functions of SOC. The circuit structure looks like this: 
  ┌───[ R0 ]───┬───[ R_rc1 ]───┬───[ R_rc2 ]───┐
  │             │               │               │
 OCV         [ C_rc1 ]       [ C_rc2 ]         V_terminal
  │             │               │               │
  └─────────────┴───────────────┴───────────────┘
Each RC pair captures a different timescale of dynamic polarization behavior. More RC pairs produce a more accurate fit but also increase model complexity.

​
Fitting a measurement in a project

Use this workflow when you want the fit to be associated with a specific project and cell, and to use a measurement you’ve already uploaded.
1

Open ECM Fitting from your project

Open the project, then click ECM Fitting in the sidebar. The page lists the cells in the project and the measurements attached to each one.
2

Pick one or more measurements

Select the cell measurements you want to fit. A preview plot of the voltage and current traces is shown so you can confirm it’s the right data before running the fit.Only time_series measurements with voltage, current, and time data can be fit. Properties and file-type measurements aren’t shown in the picker.You can select multiple measurements to fit them jointly as a single ECM. This is useful when each measurement covers a different part of the operating window (for example, separate pulse trains at different SOCs or on different cell instances). The fit treats each measurement as its own segment and shares a single set of SOC-dependent parameters across all of them.
3

Configure and run the fit

Set the number of RC pairs (0–5) and toggle Fit OCV as described in Configure the fit.When you select two or more measurements, you must enter an initial SOC (0–1) for each measurement in the configuration card. This tells the fitter where each segment starts on the SOC axis so it can stitch them together. Capacity remains a single value shared across all selected measurements (leave blank to estimate from the data). For a single measurement, the initial SOC field stays optional and is estimated automatically when left blank.Click Parameterize ECM to start.
4

Save the result to the project

When the fit completes, review the results and click Save to attach the fitted parameter set to the project’s cell. Saved fits appear in the cell’s measurement history and can be used as a starting point when creating a parameterized model.

​
Using the tool

The standalone demo at studio.ionworks.com/ecm-demo — and the fit configuration step inside a project — share the same controls.
1

Select your data

Choose from built-in example datasets or upload your own cycling data file. (Inside a project, you instead pick a measurement attached to one of the project’s cells, as described above.)Built-in examples include cells from published literature (Chen 2020, Ecker 2015, Prada 2013, and others) as well as drive-cycle profiles (UDDS, mixed current). Each example shows a recommended number of RC pairs.Uploaded files are automatically detected and parsed. The tool supports common cycler formats including CSV, Excel, and formats from BaSyTec, Maccor, and Biologic. Your file must contain time, voltage, and current columns. If an Open-circuit voltage [V] column is present, you can use it directly instead of fitting OCV.
2

Configure the fit

Set the number of RC pairs (0–5). More RC pairs capture faster dynamics but increase complexity. The recommended value depends on your data — example datasets show a suggested count.Toggle Fit OCV on or off. When your data includes a measured OCV column, you can disable OCV fitting to use the provided values directly and only fit R0 and RC parameters.
3

View results

After fitting, you see:
  • Model vs. data voltage comparison plot and RMSE
  • OCV(SOC) and R0(SOC) parameter curves
  • R_rc(SOC), C_rc(SOC), and τ_rc(SOC) curves for each RC pair
Full RC-pair parameters require ECM results access to be enabled for your organization. Contact info@ionworks.com to request access.

​
Downloading results as CSV

After a fit completes, click the Download CSV button in the results header to export the fitted parameters. The CSV contains 200 interpolated SOC points with these columns:
ColumnDescription
SOCState of charge (0 to 1)
OCV [V]Open-circuit voltage
R0 [mOhm]Series resistance in milliohms
R_rc_N [mOhm]RC pair N resistance
C_rc_N [F]RC pair N capacitance
tau_N [s]RC pair N time constant
Columns for each fitted RC pair follow this pattern (e.g. R_rc_1, R_rc_2, …).
RC-pair columns are included only when ECM results access is enabled for your organization. Otherwise the CSV contains SOC, OCV, and R0 only. Contact info@ionworks.com to request access.

​
Data requirements

Your cycling data must include:
  • Time [s] — time in seconds
  • Voltage [V] — terminal voltage
  • Current [A] — applied current
Optionally, include Open-circuit voltage [V] to skip OCV fitting and use measured OCV directly.
The tool uses ionworksdata for format detection, so data exported from common cyclers is usually recognized automatically.

​
Validating on held-out data

Once you have a fitted ECM, use client.ecm.validate(...) from the Python API client to check how well it reproduces a held-out load case — a measurement, rate, or drive cycle the fit did not see. The call re-simulates the fitted model forward on the held-out current trace using the same engine the fit uses internally and returns aligned model-vs-data traces plus error metrics. The call is synchronous (no job, no pipeline) and is the right tool for ECM held-out validation — don’t route an ECM through a validation pipeline for this.

​
When to use it

  • After a fit, to gate whether the model is accurate enough for the application.
  • To compare a saved parameterized model against a new measurement at a different rate or drive cycle.
  • To produce a model-vs-data overlay and residual plot for a report.

​
Inputs

Provide exactly one held-out source and exactly one model source:
ArgumentDescription
measurement_idHeld-out cell measurement (not used in the fit). Mutually exclusive with example_id.
example_idBuilt-in example dataset to validate against.
fit_resultsIn-memory FitResults returned by wait_for_completion(...) or fit_from_example(...). Mutually exclusive with parameterized_model_id.
parameterized_model_idA saved ECM parameterized model (e.g. from save_to_project).
Optional arguments:
  • start_step, end_step — inclusive step bounds applied to the held-out measurement.
  • initial_soc — known SOC (0–1) at the start of the held-out trace. When omitted it is recovered from the trace’s first voltage via the fitted OCV(SOC) curve (assumes the trace starts near rest); pass it explicitly if the trace starts mid-load.
  • capacity — cell capacity [Ah] used for SOC integration. Defaults to the fit/model capacity (the SOC reference the curves were fitted against); it is never re-estimated from the held-out trace.

​
Example

from ionworks import Ionworks

client = Ionworks()

# `result` is the FitResults from an ECM fit, e.g.:
#   job = client.ecm.fit_from_example(...)
#   result = client.ecm.wait_for_completion(job)

# Validate the in-memory fit against a held-out measurement
val = client.ecm.validate(
    measurement_id="held-out-measurement-id",   # a load case NOT used in the fit
    fit_results=result,
)

print(f"RMSE: {val.rmse_mV:.2f} mV "
      f"(MAE {val.mae_mV:.2f} mV, Max {val.max_mV:.2f} mV)")

# Or validate a previously saved Parameterized Model. `save_to_project`
# returns a response whose `parameterized_model_id` identifies the saved model:
#   saved = client.ecm.save_to_project(name=..., cell_spec_id=..., fit_results=result)
val = client.ecm.validate(
    measurement_id="held-out-measurement-id",
    parameterized_model_id=saved.parameterized_model_id,
)

​
Results

The returned ValidationResults object carries error metrics plus aligned, downsampled traces ready to plot as a two-panel (overlay + residual) figure:
FieldDescription
rmse_mV, mae_mV, max_mVVoltage error metrics in millivolts.
timeDownsampled time grid [s].
data_voltageHeld-out measured voltage [V].
model_voltageRe-simulated model voltage [V].
residual_mVModel − data residual [mV].
initial_soc, capacity_AhValues used for the SOC integration.
num_rcs, model_sourceRC-pair count and origin of the validated model.
A typical plot overlays model_voltage and data_voltage against time in one row, with residual_mV against time in a second row sharing the x-axis: 
import matplotlib.pyplot as plt

fig, (ax_v, ax_e) = plt.subplots(2, 1, sharex=True, figsize=(9, 6))
ax_v.plot(val.time, val.data_voltage, label="data")
ax_v.plot(val.time, val.model_voltage, label="model", linestyle="--")
ax_v.set_ylabel("Voltage [V]")
ax_v.legend()
ax_v.set_title(f"Held-out validation — RMSE {val.rmse_mV:.1f} mV")
ax_e.plot(val.time, val.residual_mV)
ax_e.axhline(0, color="k", linewidth=0.8)
ax_e.set_ylabel("Error [mV]")
ax_e.set_xlabel("Time [s]")
fig.tight_layout()

​
Next steps