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