Upload a model

Register a battery model with Ionworks — a built-in PyBaMM model or your own custom one — then bind it to parameters as a parameterized model.

Register a model so you can parameterize and simulate it. A model is the structural definition (SPM, DFN, or your own equations); a parameterized model binds a model to a cell spec and parameter values — that’s the runnable thing.

Install and authenticate first: pip install ionworks-api and set IONWORKS_API_KEY. See the Python API client page.

import pybamm
from ionworks import Ionworks

client = Ionworks()

# Option A — a built-in PyBaMM model. Pass the object directly (or a
# {"type": "SPM"} config dict); it's stored as a standard model + options.
model = client.model.create({
    "name": "SPM with SEI",
    "description": "SPM + SEI growth submodel",
    "config": pybamm.lithium_ion.SPM(options={"SEI": "ec reaction limited"}),
})

# Option B — your own pybamm.BaseModel subclass (new equations). Uploaded
# as a custom model.
custom_model = client.model.upload_custom(
    MyCustomModel(),             # a pybamm.BaseModel instance (or serialized-JSON path)
    name="My Custom Model",
    chemistry="lithium_ion",     # lithium_ion (default) | lithium_sulfur | ecm | generic
)

# Bind a model to a cell spec + parameter values to get a runnable parameterized model.
parameterized_model = client.parameterized_model.create_or_get("your-cell-spec-id", {
    "name": "LGM50 Chen2020",
    "model_id": model.id,
    "parameters": {...},
})

What’s happening

• Built-in vs custom. client.model.create takes a built-in PyBaMM model — pass the object (pybamm.lithium_ion.SPM(options=...)) or a {"type": "SPM"} config dict — and stores it as a standard model with its options (is_custom_model=False). Reach for client.model.upload_custom only for a model class that isn’t built in — your own pybamm.BaseModel subclass with new equations/submodels — which is stored as a custom model (is_custom_model=True).
• Custom uploads need a chemistry tag up front — it drives simulation fix-ups and can’t be reliably inferred (a Li-S model without it fails at simulation time).
• A Model holds no parameter values and can’t be simulated alone. Create a ParameterizedModel (against a cell_spec_id) to make it runnable — see Run a simulation in a study.

Learn more

• Models and Parameterized models
• Projects & studies