Parameterized Models#

Manage parameterized models in Ionworks Studio.

For usage examples and guides, see Managing parameterized models on docs.ionworks.com.

Parameterized model client for managing parameterized battery models.

This module provides the ParameterizedModelClient for creating, reading, and updating parameterized models, which combine a base model with specific parameter values for a given cell specification.

class ionworks.parameterized_model.ParameterizedModelClient(client)[source]#

Bases: object

Client for managing parameterized models.

Parameterized models combine a base model (e.g. SPM, DFN) with specific parameter values for a given cell specification.

Parameters:

client (Any)

__init__(client)[source]#

Initialize the ParameterizedModelClient.

Parameters:

client (Any) – The HTTP client instance for making API requests.

Return type:

None

get(parameterized_model_id)[source]#

Get a specific parameterized model by ID.

Uses the non-cell-scoped endpoint so callers don’t need the cell spec ID just to fetch an existing model.

Parameters:

parameterized_model_id (str) – The ID of the parameterized model to retrieve.

Returns:

The requested parameterized model object.

Return type:

ParameterizedModel

list_by_cell_specification(cell_spec_id, limit=None, offset=None)[source]#

List parameterized models for a cell specification.

Parameters:

  • cell_spec_id (str) – The ID of the cell specification to list models for.

  • limit (int | None, optional) – Maximum number of models to return per page.

  • offset (int | None, optional) – Number of models to skip for pagination.

Returns:

A paginated list of parameterized model objects.

Return type:

PaginatedList[ParameterizedModel]

list_by_project(project_id=None, limit=None, offset=None, *, cell_spec_id=None)[source]#

List parameterized models across all cell specs in a project.

Unlike list(), which scopes to a single cell specification, this returns every parameterized model linked to any cell specification in the project.

Parameters:

  • project_id (str | None, optional) – The ID of the project to list models for. Defaults to the project_id set on the Ionworks client.

  • limit (int | None, optional) – Maximum number of models to return per page.

  • offset (int | None, optional) – Number of models to skip for pagination.

  • cell_spec_id (str | None, optional) – If provided, restrict results to a single cell specification within the project. Defaults to None (all cell specs in the project).

Returns:

A paginated list of parameterized model objects.

Return type:

PaginatedList[ParameterizedModel]

create(cell_spec_id, data)[source]#

Create a new parameterized model for a cell specification.

Parameters:

  • cell_spec_id (str) – The ID of the cell specification to create the parameterized model for.

  • data (dict[str, Any]) –

    Dictionary containing the parameterized model data. Required fields: name, model_id. Optional fields: description, parameters, simulation_settings.

    simulation_settings is a persistent bag of pybamm simulation kwargs (var_pts / submesh_types / spatial_methods / solver) that takes precedence over the base model’s settings when this parameterized model is simulated. Pass an iws.models.SimulationSettings(...) object (serialized for you) or its config dict (see ModelClient.create()).

Returns:

The newly created parameterized model object.

Return type:

ParameterizedModel

create_or_get(cell_spec_id, data)[source]#

Create a new parameterized model or get an existing one.

Creates a new parameterized model if one with the same name does not already exist for the cell specification, otherwise returns the existing one. This makes setup scripts safely re-runnable, matching the create_or_get behaviour of the cell spec, instance, and measurement clients.

Parameters:

  • cell_spec_id (str) – The ID of the cell specification the parameterized model belongs to.

  • data (dict[str, Any]) – Dictionary containing the parameterized model data, same as create().

Returns:

The parameterized model object (newly created or existing).

Return type:

ParameterizedModel

update(cell_spec_id, parameterized_model_id, data)[source]#

Update a parameterized model’s name, description, or simulation settings.

Parameters:

  • cell_spec_id (str) – The ID of the cell specification the model belongs to.

  • parameterized_model_id (str) – The ID of the parameterized model to update.

  • data (dict[str, Any]) – Dictionary containing the fields to update. Supports name, description, and simulation_settings (a SimulationSettings object or its config dict; send null to clear the persisted settings and fall back to the base model / defaults).

Returns:

The updated parameterized model object.

Return type:

ParameterizedModel

get_parameter_values(parameterized_model_id)[source]#

Get all parameter values from a parameterized model as JSON.

Returns the complete parameter set, suitable for use as baseline parameters in DataFit, parameterization, or optimization workflows. Version and citation metadata are excluded.

Parameters:

parameterized_model_id (str) – The ID of the parameterized model to fetch parameters from.

Returns:

All parameterized model parameter values as JSON.

Return type:

dict[str, Any]

get_variable_names(parameterized_model_id)[source]#

Get scalar variable names from a parameterized model.

Returns the names of all variables where the domain is empty or “current collector” (i.e. they are functions of time only).

Parameters:

parameterized_model_id (str) – The ID of the parameterized model to fetch variables from.

Returns:

List of variable names with empty or current collector domain.

Return type:

list[str]