Python API

The ionworks-api Python package provides sub-clients for managing models and parameterized models programmatically. For installation and authentication, see the Python API client page.

Models

Use client.model to create, list, update, and delete models.

Listing models

from ionworks import Ionworks

client = Ionworks()

# List all models
models = client.model.list()
for model in models:
    print(f"{model.name} ({model.id})")

# Filter by name
models = client.model.list(name="SPM")

# Paginate results
models = client.model.list(limit=10, offset=0)

Supported filters: name, name_exact, created_by_email, created_after, created_before, updated_after, updated_before, order_by, order.

Getting a model

model = client.model.get("your-model-id")
print(model.config)
# {"type": "SPMe"}

The config field (e.g. {"type": "SPMe"}) is included on get responses. It may be None on the create response — re-fetch with get if you need it.

Creating a model

model = client.model.create({
    "name": "Custom SPM",
    "config": {"type": "SPM"},
    "description": "Single Particle Model with custom variables",
})

The type in config is the PyBaMM model class name (SPM, SPMe, DFN).

You only need to create a model when you want custom variables. For a standard model, reference a built-in system model by name (e.g. "SPMe (Full Cell)") when building a parameterized model — no model creation required. See Models.

Updating a model

model = client.model.update("your-model-id", {
    "name": "Custom SPM v2",
    "description": "Updated description",
})

Adding a custom variable

model = client.model.add_custom_variable("your-model-id", {
    "name": "Total energy [W.h]",
    "expression": "Voltage [V] * Current [A] * Time [s] / 3600",
})

Deleting a model

client.model.delete("your-model-id")

Downloading an Ionworks model as a PyBaMM model

Use client.model.download() to fetch an Ionworks model (ECM, LumpedSPMR, LumpedSPMeR, the MSMR models, GITTModel, …) as a ready-to-use PyBaMM model. The server constructs the model from the licensed ionworkspipeline package and returns its serialized form, so you can run it locally with only pybamm installed — no ionworkspipeline license required.

import pybamm

model = client.model.download("ECM")
# model is a pybamm.BaseModel — pass it straight to pybamm.Simulation
sim = pybamm.Simulation(model)

Pass model constructor options through options=, and optionally write the serialized JSON to disk with path= so you can reload it later or re-upload it as a custom model:

model = client.model.download(
    "LumpedSPMR",
    options={"thermal": "lumped", "surface temperature": "ambient"},
    path="lumped_spmr.json",
)

The available model names match the entries listed under "ionworks_models" by client.pybamm_models(). Standard PyBaMM models (SPM, SPMe, DFN, …) are not served by this endpoint — instantiate them directly with pybamm instead.

Serialization captures the model’s mathematical structure (rhs, algebraic, variables, events, initial conditions) but not Python helper methods such as set_initial_state or classmethods.When path is given, the file may contain bare Infinity/NaN tokens (PyBaMM uses infinite bounds and event thresholds). Python’s json and Serialise.load_custom_model read these fine, but strict parsers (JSON.parse, jq, …) will reject the file.

If you only need the raw serialized document — for example, to save it, re-upload it, or inspect it — use client.model.serialize(), which returns the dict without loading it through PyBaMM:

model_json = client.model.serialize("GITTModel")

Geometry and mesh are preserved

Downloaded models carry the serialized geometry, var_pts, spatial_methods, and submesh_types that the original Ionworks model was built with. When you re-upload one as a custom model — or feed it into a pipeline that goes through parse_model — those values are restored as the model’s default_geometry, default_var_pts, default_spatial_methods, and default_submesh_types, so a downstream pybamm.Simulation discretises against the correct mesh instead of falling back to empty defaults. You do not need to reconstruct the geometry by hand.

Parameterized models

Use client.parameterized_model to create, list, and update parameterized models. Parameterized models are scoped to a cell specification.

Listing parameterized models

You can list parameterized models scoped to a single cell specification or across every cell specification in a project.

# List parameterized models for a single cell specification
param_models = client.parameterized_model.list_by_cell_specification("your-cell-spec-id")
for pm in param_models:
    print(f"{pm.name} (ID: {pm.id})")

# Paginate results
param_models = client.parameterized_model.list_by_cell_specification(
    "your-cell-spec-id", limit=10, offset=0
)

To list every parameterized model linked to any cell specification in a project, use list_by_project. When project_id is omitted it defaults to the project_id configured on the client (see API client).

# All parameterized models in the client's default project
param_models = client.parameterized_model.list_by_project()

# Explicit project, paginated
param_models = client.parameterized_model.list_by_project(
    project_id="your-project-id", limit=100, offset=0
)

# Narrow a project-scoped query to one cell specification
param_models = client.parameterized_model.list_by_project(
    project_id="your-project-id", cell_spec_id="your-cell-spec-id"
)

list_by_project accepts limit values up to 1000, so you can load every model for a project in a single request when populating UI selectors or bulk-processing models.

Getting a parameterized model

param_model = client.parameterized_model.get("your-parameterized-model-id")

Creating a parameterized model

param_model = client.parameterized_model.create("your-cell-spec-id", {
    "name": "NMC622 Fitted Parameters",
    "model_id": "your-model-id",
    "description": "Parameters from 1C discharge fitting",
    "parameters": {
        "Negative electrode diffusivity [m2.s-1]": 3.3e-14,
    },
})

Creating or getting a parameterized model

Use create_or_get to make setup scripts safely re-runnable. If a parameterized model with the same name already exists for the cell specification, the client returns the existing one instead of raising a 409 Conflict error.

param_model = client.parameterized_model.create_or_get("your-cell-spec-id", {
    "name": "NMC622 Fitted Parameters",
    "model_id": "your-model-id",
    "parameters": {
        "Negative electrode diffusivity [m2.s-1]": 3.3e-14,
    },
})

This mirrors the create_or_get behaviour already available on client.cell_spec, client.cell_instance, and client.cell_measurement — see idempotent uploads for the same pattern applied to cell data.

Updating a parameterized model

param_model = client.parameterized_model.update(
    "your-cell-spec-id",
    "your-parameterized-model-id",
    {"name": "NMC622 Fitted Parameters v2"},
)

Getting parameter values

Retrieve all parameter values as a dictionary, useful as baseline parameters for data fitting or optimization workflows.

params = client.parameterized_model.get_parameter_values("your-parameterized-model-id")
print(params)
# {"Negative electrode diffusivity [m2.s-1]": 3.3e-14, ...}

Getting variable names

List the scalar variable names available from a parameterized model.

variables = client.parameterized_model.get_variable_names("your-parameterized-model-id")
print(variables)
# ["Terminal voltage [V]", "Current [A]", ...]

Persisting simulation settings

A parameterized model can carry its own simulation settings — the mesh (var_pts, submesh_types), spatial discretisation (spatial_methods), and solver configuration to use whenever this model is simulated. Persisting settings ensures the model simulates the same way everywhere it’s used — a DataFit, a validation run, a downstream sweep — without you having to reconfigure the mesh and solver in each caller. Build a SimulationSettings from live PyBaMM objects with iws.models.SimulationSettings(...), then pass it under the simulation_settings key when creating or updating a parameterized model:

import pybamm
import ionworks_schema as iws

model = pybamm.lithium_ion.DFN()

settings = iws.models.SimulationSettings(
    var_pts={"x_n": 20, "x_s": 10, "x_p": 20, "r_n": 20, "r_p": 20},
    submesh_types=model.default_submesh_types,
    spatial_methods=model.default_spatial_methods,
    solver=pybamm.IDAKLUSolver(rtol=1e-6, atol=1e-6),
)

param_model = client.parameterized_model.create("your-cell-spec-id", {
    "name": "NMC622 — fine mesh",
    "model_id": "your-model-id",
    "parameters": {...},
    "simulation_settings": settings,
})

The stored settings come back on the parameterized model’s simulation_settings field. Omit simulation_settings on create and the model uses the built-in defaults for its underlying model type.

Two write-time limits are worth knowing before you build a settings block:

geometry is rejected. Persisting a geometry override returns 400 BAD_REQUEST; persist var_pts / submesh_types / spatial_methods / solver instead and let the geometry come from the model.
Solvers are allowlisted. Only IDAKLUSolver, AlgebraicSolver, and NonlinearSolver may be stored. The deprecated CasadiSolver and ScipySolver are rejected.

var_pts keys, submesh classes, and spatial-method classes are validated against allowlists too, so an unrecognized value fails the write rather than the later simulation.

You can find the ID for any resource from the Ionworks Studio web app. The ID is displayed in the URL when you navigate to a resource’s detail page.

ECM parameterization

Use client.ecm to fit an Equivalent Circuit Model (R0 + N RC pairs, plus optional OCV) to cycling data and persist the result as a Parameterized Model. Authenticated fits run as background jobs — fit_from_measurements and fit_from_file return an EcmFitJob handle immediately, and wait_for_completion blocks until the worker finishes (typically 10–60 s). See ECM parameterization for the full guide, including ocv_soc_curve co-capacity fits, per-segment SOC seeds, and knot-resolution tuning.

Fitting from stored measurements

from ionworks import Ionworks

client = Ionworks()

fit_job = client.ecm.fit_from_measurements({
    "measurements": [
        {"id": "meas-id-1"},
        {"id": "meas-id-2", "start_step": 5, "end_step": 50, "initial_soc": 0.95},
    ],
    "ecm_options": {"num_rcs": 2, "fit_ocv": True},
})

result = client.ecm.wait_for_completion(fit_job, timeout=300)
print(f"RMSE: {result.rmse_mV:.2f} mV")

Fitting from a local file

fit_job = client.ecm.fit_from_file("data/pulse_test.csv", num_rcs=2, capacity=4.85)
result = client.ecm.wait_for_completion(fit_job)

fit_from_file accepts CSV, parquet, and any cycler format that ionworksdata can detect. Use client.ecm.detect_and_read(file) to preview a file before fitting.

Saving a fit as a Parameterized Model

saved = client.ecm.save_to_project(
    name="ECM 2RC — pulse test",
    cell_spec_id="cell-spec-id",
    fit_results=result,
)

print(saved.parameterized_model_id)

The returned parameterized_model_id can be used as parameterized_model in client.simulation.protocol(...).

Fitting a built-in example (no auth)

examples = client.ecm.list_examples()
result = client.ecm.fit_from_example(examples[0]["id"], num_rcs=2)

The demo endpoint is rate-limited (60/min) and synchronous. RC-pair parameters are only included for authenticated callers whose organization has ECM results access enabled.

Get Started

Core Concepts

Operate

Data

Build

Pipelines

Simulate

Optimize

Models

Listing models

Getting a model

Creating a model

Updating a model

Adding a custom variable

Deleting a model

Downloading an Ionworks model as a PyBaMM model

Geometry and mesh are preserved

Parameterized models

Listing parameterized models

Getting a parameterized model

Creating a parameterized model

Creating or getting a parameterized model

Updating a parameterized model

Getting parameter values

Getting variable names

Persisting simulation settings

ECM parameterization

Fitting from stored measurements

Fitting from a local file

Saving a fit as a Parameterized Model

Fitting a built-in example (no auth)

​Models

​Listing models

​Getting a model

​Creating a model

​Updating a model

​Adding a custom variable

​Deleting a model

​Downloading an Ionworks model as a PyBaMM model

​Geometry and mesh are preserved

​Parameterized models

​Listing parameterized models

​Getting a parameterized model

​Creating a parameterized model

​Creating or getting a parameterized model

​Updating a parameterized model

​Getting parameter values

​Getting variable names

​Persisting simulation settings

​ECM parameterization

​Fitting from stored measurements

​Fitting from a local file

​Saving a fit as a Parameterized Model

​Fitting a built-in example (no auth)

Models

Listing models

Getting a model

Creating a model

Updating a model

Adding a custom variable

Deleting a model

Downloading an Ionworks model as a PyBaMM model

Geometry and mesh are preserved

Parameterized models

Listing parameterized models

Getting a parameterized model

Creating a parameterized model

Creating or getting a parameterized model

Updating a parameterized model

Getting parameter values

Getting variable names

Persisting simulation settings

ECM parameterization

Fitting from stored measurements

Fitting from a local file

Saving a fit as a Parameterized Model

Fitting a built-in example (no auth)