Python API

Create, list, and manage models and parameterized models programmatically with the ionworks-api Python client

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} (type: {model.model_type})")

# 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)

Creating a model

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

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

Parameterized models

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

Listing parameterized models

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

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

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

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]", ...]

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.