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.api.parameterized_model.ParameterizedModelClient(client: Any)[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.

__init__(client: Any) → None[source]

Initialize the ParameterizedModelClient.

Parameters:

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

get(parameterized_model_id: str, summary: bool = False) → ParameterizedModel[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.

  • summary (bool, optional) – If True, return id, name, cell specification, base model and timestamps only, without the parameter values (see get_parameter_values()). Defaults to False.

Returns:

The requested parameterized model object.

Return type:

ParameterizedModel

list_by_cell_specification(cell_spec_id: str, limit: int | None = None, offset: int | None = None) → PaginatedList[ParameterizedModel][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: str | None = None, limit: int | None = None, offset: int | None = None, *, cell_spec_id: str | None = None, summary: bool = False) → PaginatedList[ParameterizedModel][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).

  • summary (bool, optional) – Return each model’s id, name, description, cell_spec_id, model_id, model_name and timestamps only, without its parameter values, which can be very large. Read one model’s values with get_parameter_values(). Defaults to False.

Returns:

A paginated list of parameterized model objects.

Return type:

PaginatedList[ParameterizedModel]

create(cell_spec_id: str | None, data: dict[str, Any], *, summary: bool = False) → ParameterizedModel[source]

Create a new parameterized model for a cell specification or a project.

Pass summary=True to return metadata without parameter values or model config.

Parameters:

  • cell_spec_id (str | None) – The ID of the cell specification to create the parameterized model for, whose capacity and voltage cut-offs override the parameter set’s. None creates a model with no cell specification in the project data["project_id"] (defaulting to the client’s project), which keeps the parameter set’s own values.

  • data (dict[str, Any]) –

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

    parameters may be a parameters dict, a pybamm.ParameterValues, or the name of a pybamm parameter set (e.g. "Chen2020"); the latter two are serialized for you.

    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 iw.pipeline.models.SimulationSettings(...) object (serialized for you) or its config dict (see ModelClient.create()).

Returns:

The newly created parameterized model object.

Return type:

ParameterizedModel

Raises:

ValueError – If cell_spec_id is None and no project_id is given or set on the client.

create_or_get(cell_spec_id: str, data: dict[str, Any]) → ParameterizedModel[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: str | None, parameterized_model_id: str, data: dict[str, Any], *, summary: bool = False) → ParameterizedModel[source]

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

Pass summary=True to return metadata without parameter values or model config.

Parameters:

  • cell_spec_id (str | None) – The ID of the cell specification the model belongs to, or None for a model with no cell specification.

  • 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

create_version(cell_spec_id: str | None, parameterized_model_id: str, parameters: dict[str, Any] | None = None, description: str | None = None, simulation_settings: Any = None, *, summary: bool = False) → ParameterizedModel[source]

Save a new version of a parameterized model with some parameters changed.

Pass summary=True to return metadata without parameter values or model config.

Parameter values cannot be edited in place, so this is how a model is revised. The version keeps the parent’s base model, cell specification and name, starts from the parent’s parameters (calculations kept, so changing an input recomputes them) and applies parameters on top. The parent is left unchanged, so runs made with it keep the values they used.

Parameters:

  • cell_spec_id (str | None) – The cell specification the model belongs to, or None for a model with no cell specification. A mismatch 404s.

  • parameterized_model_id (str) – The version to start from.

  • parameters (dict[str, Any] | None, optional) – Values that differ from the parent’s, by parameter name.

  • description (str | None, optional) – The new version’s description. Defaults to the parent’s.

  • simulation_settings (SimulationSettings | dict | None, optional) – The new version’s simulation settings. Defaults to the parent’s.

Returns:

The new version, with its version_number and family_id.

Return type:

ParameterizedModel

list_versions(parameterized_model_id: str, limit: int = 100, offset: int = 0) → PaginatedList[ParameterizedModel][source]

List every version in a parameterized model’s family, oldest first.

Parameters:

  • parameterized_model_id (str) – Any version in the family.

  • limit (int, optional) – Maximum number of versions to return. Defaults to 100.

  • offset (int, optional) – Number of versions to skip. Defaults to 0.

Returns:

Summaries without parameter values, each with version_number, parent_parameterized_model_id and is_current_version.

Return type:

PaginatedList[ParameterizedModel]

delete(cell_spec_id: str | None, parameterized_model_id: str) → None[source]

Delete a parameterized model, addressed under its cell spec if it has one.

Parameters:

  • cell_spec_id (str | None) – The cell specification the model belongs to, or None for a model with no cell specification. A mismatch 404s.

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

Raises:

IonworksError – 403 if the caller’s project role may not delete parameterized models.

get_parameter_values(parameterized_model_id: str, resolve: bool = True, names: list[str] | None = None, match: str | None = None) → dict[str, Any][source]

Get a parameterized model’s parameter values as JSON.

Returns the complete parameter set by default, 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.

  • resolve (bool, optional) – True (the default) returns calculated parameters as numbers. False keeps them as calculations: use it to copy values into a new model, so that changing an input there recomputes what depends on it.

  • names (list[str] | None, optional) – Only these parameters, by exact name. Names the model does not have are left out.

  • match (str | None, optional) – Only parameters whose name contains this text, case-insensitively (e.g. "electrolyte"). With names, a parameter must satisfy both.

Returns:

The parameter values as JSON, narrowed by names and match.

Return type:

dict[str, Any]

get_variable_names(parameterized_model_id: str) → list[str][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]