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. Models belong to a project. list, create and upload_custom take a project_id, which defaults to the client’s project (Ionworks(project_id=...) or the IONWORKS_PROJECT_ID environment variable); without either they raise ValueError. Each project has its own copy of the built-in models (SPM, SPMe, DFN, ECM and the rest), listed alongside the project’s own models. A copy carries the built-in model’s name, and its source_model_id is the built-in model it came from. Copies are the project’s own: edit or delete them like any other model.

Listing models

from ionworks import Ionworks

client = Ionworks()

# List the project's models (project_id defaults to the client's project)
models = client.model.list()
for model in models.items:
    print(f"{model.name} ({model.id})")

# Filter by name (case-insensitive substring match)
models = client.model.list(name="SPM")

# Sort by name ascending
models = client.model.list(order_by="name", order="asc")

# Paginate results
models = client.model.list(limit=10, offset=0)
print(f"Showing {models.count} of {models.total} models")

list returns a paginated response with items, count, and total. Pass project_id= to list another project’s models. Supported filters: name, name_exact, created_by_email, created_after, created_before, updated_after, updated_before, order_by, order. Filters and sort parameters are applied server-side, so you can drill into large model libraries without pulling every page.

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 can also attach persistent simulation_settings (mesh + solver) that will be re-applied whenever the model is simulated — see Simulation settings for the full field list and precedence rules:

model = client.model.create({
    "name": "DFN with refined particle mesh",
    "config": {"type": "DFN"},
    "simulation_settings": {
        "var_pts": {"r_n": 20, "r_p": 20},
    },
})

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.

Creating a model from the PyBaMM model zoo

For a model from the PyBaMM model zoo, create_from_zoo uploads it as a custom model and creates a parameterized model for it in one call. Install the zoo first with pip install pybamm-model-zoo; a zoo model with its own dependencies also needs its extra (pip install "pybamm-model-zoo[zoo-<slug>]").

result = client.model.create_from_zoo(
    "LinearisedSPM",
    cell_spec_id="your-cell-spec-id",  # optional
    parameter_values="Chen2020",  # optional; defaults to the model's own
    options={"thermal": "lumped"},  # optional model options
)
print(result.model.id, result.parameterized_model.id)

parameter_values takes a parameter-set name, a pybamm.ParameterValues or a parameters dict. Under a cell specification, its capacity, voltage cut-offs and current replace the parameter set’s; without one, the parameterized model keeps the parameter set’s own. Models whose constructors take more than options get them through model_kwargs, e.g. model_kwargs={"num_physical_layers": 4} for MultiLayer3DThermalSPM.

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": "Electrical power [W]",
    "expression": 'CoupledVariable("Voltage [V]") * CoupledVariable("Current [A]")',
})

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 builds the model and returns its serialized form, so you can run it locally with only pybamm installed — no additional 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. A parameterized model usually belongs to a cell specification, whose capacity and voltage cut-offs override the parameter set’s. It can instead belong to a project with no cell specification, and keep the parameter set’s own values.

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,
    },
})

Pass simulation_settings to pin parameter-specific mesh or solver requirements. Parameter-level settings take precedence over the base model’s, so this is the usual place to record the grid a fit was performed on — see Simulation settings:

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

Pass None as the cell specification to create a parameterized model in a project instead. project_id defaults to the client’s project. parameters can also be a pybamm.ParameterValues or the name of a PyBaMM parameter set:

param_model = client.parameterized_model.create(None, {
    "name": "Chen2020 baseline",
    "model_id": "your-model-id",
    "parameters": "Chen2020",
})

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"},
)

Deleting a parameterized model

client.parameterized_model.delete("your-cell-spec-id", "your-parameterized-model-id")

update() and delete() take the parameterized model’s cell_spec_id, or None for one with no cell specification. A ParameterizedModel carries it as param_model.cell_spec_id.

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.

Model builders

A model builder is a recipe that turns a cell specification into a model’s parameters. The recipe is a pipeline of direct entries and calculations. An entry reads the cell specification with the same dotted mapping paths as a cell specification direct entry, but without a cell_spec_id, since a builder reads whichever cell specification it builds from. Data fits and validations are not allowed in a recipe.

recipe = {
    "elements": {
        "from cell spec": {
            "element_type": "entry",
            "mapping": {
                "Positive electrode thickness [m]": "cathode.properties.thickness",
                "Negative electrode thickness [m]": "anode.properties.thickness",
            },
        },
    },
}

# Try the recipe on a cell specification without saving anything
result = client.model_builder.dry_run("your-model-id", recipe, "your-cell-spec-id")
print(result["report"]["ready"], result["missing"])

builder = client.model_builder.create("your-model-id", "From cell spec", recipe)

config takes the dict above or an ionworks_schema.Pipeline. A builder belongs to a project, which defaults to the client’s.

Building from a cell specification

report = client.model_builder.check(builder.id, "your-cell-spec-id")
for issue in report.issues:
    print(issue.severity, issue.parameter, issue.path, issue.message)

result = client.model_builder.build(
    builder.id,
    "your-cell-spec-id",
    save=True,
    name="Cell A design parameters",
)
print(result.parameterized_model_id, result.missing)

check lists everything the cell specification lacks, each issue naming its path in the cell specification and the model parameter it feeds. build returns the parameters, any the model still needs (missing) and the readiness warnings. With save=True it also saves them as a parameterized model on the cell specification. Saving needs a name and is refused while any parameter is missing. Pass set_as_default=True to make it the cell specification’s default.

Writing a mapping

# Every value a mapping can read, under its dotted path
spec = client.model_builder.resolved_cell_spec("your-cell-spec-id")

# What a mapping reads, before and after unit conversion
client.model_builder.preview_mapping("your-cell-spec-id", {
    "Positive electrode thickness [m]": "cathode.properties.thickness",
})
# {"Positive electrode thickness [m]": {"found": "75.6 um", "converted": "7.56e-05 m", ...}}

# Calculations that produce a parameter the cell specification does not store
client.model_builder.calculations_producing("Positive electrode porosity")

client.model_builder.readiness(cell_spec_id) lists the builders a cell specification is ready for. list, get, update and delete manage builders. Deleting a builder keeps the parameterized models it produced.

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

Quickstarts

Core Concepts

Operate

Data

Build

Simulate

Optimize

Models

Listing models

Getting a model

Creating a model

Creating a model from the PyBaMM model zoo

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

Deleting a parameterized model

Getting parameter values

Getting variable names

Persisting simulation settings

Model builders

Building from a cell specification

Writing a mapping

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

​Creating a model from the PyBaMM model zoo

​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

​Deleting a parameterized model

​Getting parameter values

​Getting variable names

​Persisting simulation settings

​Model builders

​Building from a cell specification

​Writing a mapping

​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

Creating a model from the PyBaMM model zoo

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

Deleting a parameterized model

Getting parameter values

Getting variable names

Persisting simulation settings

Model builders

Building from a cell specification

Writing a mapping

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)