Simulation#

Client for running battery simulations using UCP protocol and PyBaMM.

Simulation client for running battery simulations.

This module provides the SimulationClient for running battery simulations using the Universal Cycler Protocol (UCP) format. It supports single simulations, batch simulations with design of experiments (DOE), and PyBaMM-based modeling.

class ionworks.simulation.QuickModelConfig(*, capacity=1.0, chemistry='NMC/Graphite')[source]#

Bases: BaseModel

Quick model configuration for protocol-based simulations.

Parameters:
capacity: float#
chemistry: str#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.ProtocolExperimentConfig(*, protocol, name)[source]#

Bases: BaseModel

Protocol experiment configuration.

Parameters:
protocol: str#
name: str#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.ProtocolSimulationRequest(*, parameterized_model, protocol_experiment, experiment_parameters=None, design_parameters=None, max_backward_jumps=None, study_id=None, extra_variables=None)[source]#

Bases: BaseModel

Request model for single protocol-based simulation.

Parameters:
parameterized_model: Any#
protocol_experiment: ProtocolExperimentConfig#
experiment_parameters: dict[str, float] | None#
design_parameters: dict[str, float] | None#
max_backward_jumps: int | None#
study_id: str | None#
extra_variables: list[str] | None#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.DOERow(*, type, name, min=None, max=None, count=None, values=None, mean=None, std=None)[source]#

Bases: BaseModel

Design of experiments row configuration.

Parameters:
type: str#
name: str#
min: float | None#
max: float | None#
count: int | None#
values: list[float] | None#
mean: float | None#
std: float | None#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.DesignParametersDOE(*, sampling, rows, count=None)[source]#

Bases: BaseModel

Design of experiments configuration.

Parameters:
sampling: str#
rows: list[DOERow]#
count: int | None#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.ProtocolSimulationBatchRequest(*, parameterized_model, protocol_experiment, design_parameters_doe, experiment_parameters=None, max_backward_jumps=None, study_id=None, extra_variables=None)[source]#

Bases: BaseModel

Request model for batch protocol-based simulation.

Parameters:
parameterized_model: Any#
protocol_experiment: ProtocolExperimentConfig#
design_parameters_doe: DesignParametersDOE#
experiment_parameters: dict[str, float] | None#
max_backward_jumps: int | None#
study_id: str | None#
extra_variables: list[str] | None#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.SimulationResponse(*, simulation_id, job_id)[source]#

Bases: BaseModel

Response model for simulation creation.

Parameters:

  • simulation_id (str)

  • job_id (str)

simulation_id: str#
job_id: str#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ionworks.simulation.SimulationClient(client)[source]#

Bases: object

Client for running simulations.

Parameters:

client (Any)

__init__(client)[source]#

Initialize the SimulationClient.

Parameters:

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

Return type:

None

protocol(config)[source]#

Create a single protocol-based simulation.

Parameters:

config (dict[str, Any]) –

Configuration dictionary containing:

  • parameterized_model: quick_model dict, full model dict, or model ID string

  • protocol_experiment: ProtocolExperimentConfig dict with protocol and name fields

  • experiment_parameters: Optional dict with initial_soc and initial_temperature

  • design_parameters: Optional dict[str, float]

  • max_backward_jumps: Optional int

  • study_id: Optional str

  • extra_variables: Optional list[str] — extra variables to include in simulation output

Returns:

Response containing simulation_id and job_id.

Return type:

SimulationResponse

Raises:

ValueError – If the configuration is invalid.

protocol_batch(config)[source]#

Create multiple protocol-based simulations using DOE.

Parameters:

config (dict[str, Any]) –

Configuration dictionary containing:

  • parameterized_model: quick_model dict, full model dict, or model ID string

  • protocol_experiment: ProtocolExperimentConfig dict with protocol and name fields

  • design_parameters_doe: DesignParametersDOE dict

  • experiment_parameters: Optional dict

  • max_backward_jumps: Optional int

  • study_id: Optional str

  • extra_variables: Optional list[str] — extra variables to include in simulation output

Returns:

List of responses, each containing simulation_id and job_id.

Return type:

list[SimulationResponse]

Raises:

ValueError – If the configuration is invalid.

list()[source]#

List all simulations for the current user.

Returns:

List of simulation objects with joined model and experiment data.

Return type:

list[dict[str, Any]]

get(simulation_id)[source]#

Get a specific simulation by ID.

Parameters:

simulation_id (str) – The UUID of the simulation to retrieve.

Returns:

Simulation object with full joined data including model, experiment, and simulation_data (null if not completed).

Return type:

dict[str, Any]

get_result(simulation_id)[source]#

Get simulation data/result for a completed simulation.

Parameters:

simulation_id (str) – The UUID of the simulation.

Returns:

Simulation data object containing time_series, steps, and metrics. Returns 404 if simulation hasn’t completed yet.

Return type:

dict[str, Any]

Raises:

Exception – If simulation data not found (simulation may not be completed yet). The client will raise an appropriate error for 404 responses.

wait_for_completion(simulation_id, timeout=60, poll_interval=2, verbose=True)[source]#

Wait for simulation(s) to complete by polling until done or timeout.

Parameters:

  • simulation_id (str | list[str]) – Single simulation ID or list of simulation IDs to wait for.

  • timeout (int) – Maximum time to wait in seconds (default: 60).

  • poll_interval (int) – Time between polls in seconds (default: 2).

  • verbose (bool) – Whether to print status updates (default: True).

Returns:

Completed simulation(s). Returns single dict if single ID provided, list of dicts if list of IDs provided. Only returns completed simulations if timeout is reached.

Return type:

dict[str, Any] | list[dict[str, Any]]

Raises:

TimeoutError – If timeout is reached before all simulations complete.