Breathe Simulate

A class for interacting with the Breathe Simulate API.

Behaviour is controlled by private attributes that can be flipped at runtime (e.g. between notebook cells, no kernel restart needed). Each attribute is seeded from a BD_* environment variable at construction time:

API_URL -> self._api_url: API base URL.
BD_DEBUG_PRINTS -> self._debug_prints: print trace/span IDs.
BD_USE_ASYNC_ENDPOINTS -> self._use_async_endpoints: use the queued (POST + poll) endpoints.
BD_DUMP_PAYLOAD -> self._dump_payload: dump the request body to request_payload.json.
BD_DUMP_RESPONSE -> self._dump_response: dump the response body to sim_response_<trace_id>.json.

download_designs

download_designs(base_battery, designs=[], formats=[], output_tag='', folder='.')

Send the design parameters for a given battery to the API, and get the resulting design, to be used with the Simulink blocks.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery to use to generate the design	required
`designs`	`list[str]`	The designs for the simulation.	`[]`
`formats`	`list[str]`	The formats for the simulation.	`[]`
`output_tag`	`str`	A tag to be included in the metadata description.	`''`
`folder`	`str`	The folder where design files will be saved. Defaults to current directory.	`'.'`

Returns: (list[str]): The list of the file paths for the downloaded designs. Raises: BreatheException: description

ensure_logged_in

ensure_logged_in()

Checks if a valid token is available and refreshes it if necessary.

get_active_materials

get_active_materials()

Gets a list of all acive materials.

Returns:

Type	Description
`Dataframe`	containing the battery active materials.

get_aged_ocv

get_aged_ocv(base_battery, LAMPE=0.0, LAMNE=0.0, LLI=0.0)

Gets the OCV summary table for a base battery.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the design parameters.	required
`LAMPE`	`float`	The electrolyte loss at positive electrode (PE) side.	`0.0`
`LAMNE`	`float`	The electrolyte loss at negative electrode (NE) side.	`0.0`
`LLI`	`float`	The loss of lithium inventory.	`0.0`

Returns:

Type	Description
`DataFrame`	containing the OCV summary table.

get_batteries

get_batteries()

Gets a list of all batteries in your library.

Returns:

Type	Description
`list[str]`	list of the available battery models. Use these strings in subsequent functions for the "base_battery" argument.

get_battery_format

get_battery_format(base_battery)

Gets the battery format for a base battery. These are the form factor and cell casing parameters available for change in the api.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the battery format.	required

Returns:

Type	Description
`dict`	A dictionary containing the battery format. The keys in the dictionary depend on the format shape:
`dict`	Common keys (all formats):
`dict`	`shape` (str): The format shape, either "cylinder" or "cuboid"
`dict`	`material` (str): The material used for the housing
`dict`	`housingThickness_mm` (float): Housing thickness in millimeters
`dict`	Cylindrical format keys (when `shape == "cylinder"`):
`dict`	`diameter_mm` (float): Outer diameter of the cylinder in millimeters
`dict`	`height_mm` (float): Height of the cylinder in millimeters
`dict`	`innerDiameter_mm` (float): Inner diameter of the cylinder in millimeters
`dict`	Cuboid format keys (when `shape == "cuboid"`):
`dict`	`length_mm` (float): Length of the cuboid in millimeters
`dict`	`width_mm` (float): Width of the cuboid in millimeters
`dict`	`thickness_mm` (float): Thickness of the cuboid in millimeters
`dict`	`assemblyType` (str, optional): Type of assembly (e.g., "Stacked", "Wound", "ZFolded")

Example

format = api.get_battery_format("Molicel P45B") if format["shape"] == "cylinder": ... print(f"Diameter: {format['diameter_mm']} mm") ... print(f"Height: {format['height_mm']} mm") elif format["shape"] == "cuboid": ... print(f"Length: {format['length_mm']} mm") ... print(f"Width: {format['width_mm']} mm")

get_design_parameters

get_design_parameters(base_battery)

Gets the design parameters for a base battery.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the design parameters.	required

Returns:

Type	Description
`dict`	containing the design parameters.

get_eqm_kpis

get_eqm_kpis(base_battery, designs=[], formats=[])

Gets the equilibrium kpis for a given base battery, designs, and initial conditions.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the simulation.	required
`designs`	`list[dict]`	The designs for the simulation.	`[]`
`formats`	`list[dict]`	The battery formats for the simulation.	`[]`

Returns:

Type	Description
`SingleSimulationResults`	A results handler object containing the equilibrium KPIs. Use the plot_sensitivities() method to generate sensitivity plots.

get_ocv

get_ocv(base_battery)

Gets the OCV summary table for a base battery.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the design parameters.	required

Returns:

Type	Description
`DataFrame`	containing the OCV summary table.

get_service_version

get_service_version()

Get the version number of the API

Returns:

Name	Type	Description
`_type_`	`Version`	description

get_updated_format

get_updated_format(base_battery, **kwargs)

Gets the battery format for a base battery and updates it with the additional keywords. These are the form factor and cell casing parameters available for change in the api.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the battery format.	required
`**kwargs`		Format parameters to update. The available parameters depend on the format shape: - For cylindrical formats: `diameter_mm`, `height_mm`, `innerDiameter_mm`, `material`, `housingThickness_mm` - For cuboid formats: `length_mm`, `width_mm`, `thickness_mm`, `material`, `housingThickness_mm` - `name`: Optional name for the updated format - `assemblyType`: Cannot be changed (raises an error if attempted)	`{}`

Returns:

Type	Description
`dict`	A dictionary containing the updated battery format. See `get_battery_format()` for details on the returned dictionary structure.

Raises:

Type	Description
`BreatheException`	If attempting to change `assemblyType` or if a key is not found in the battery format.

Example

For a cylindrical battery

format = api.get_updated_format( ... "Molicel P45B", ... name="Smaller Cell", ... diameter_mm=20.0, ... height_mm=65.0 ... )

For a cuboid battery

format = api.get_updated_format( ... "SomeCuboidBattery", ... name="Thinner Cell", ... thickness_mm=8.0 ... )

get_valid_assembly_types

get_valid_assembly_types()

Gets a list of valid assembly types for battery formats.

Returns:

Type	Description
`list[str]`	A sorted list of valid assembly type names that can be used when defining cuboid battery formats (e.g., "stacked", "wound", "zFolded").

get_valid_format_materials

get_valid_format_materials()

Gets a list of valid material types for battery formats.

Returns:

Type	Description
`list[str]`	A sorted list of valid material names that can be used when defining battery formats (e.g., "steel", "aluminum", "pouch_foil").

run_sim

run_sim(
    base_battery,
    cycler,
    designs=[],
    formats=[],
    initialSoC=None,
    initialVoltage=None,
    initialTemperature_degC=25.0,
    ambientTemperature_degC=25.0,
    heatTransferCoefficient=35.0,
    heatCapacity_kJkgK=None,
    initialVoltageOcvType="mean",
    isothermal=False,
    cellTemperatureProfile=None,
)

Runs a simulation for a given base battery, cycler, designs, and initial conditions.

Only one of initialSoC or initialVoltage should be provided.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the simulation.	required
`cycler`	`dict`	The cycler parameters for the simulation. Supports standard cycle types (CC_CHG, CC_DCH, etc.) and CUSTOM format. Built-in current-driven cycle types also support optional advanced controls: - `CC_CHG`: `soc_target`, `anode_potential_threshold_mV`, `temperature_threshold_degC` or `temperature_threshold_K` - `CC_DCH`: `soc_target`, `temperature_threshold_degC` or `temperature_threshold_K` - `CCCV`: `charge_target_soc`, `discharge_target_soc`, `anode_potential_threshold_mV`, `temperature_threshold_degC` or `temperature_threshold_K` - `RateCap`: `target_soc`, `temperature_threshold_degC` or `temperature_threshold_K` For CUSTOM cycles, the structure is: { "cycle_type": "CUSTOM", "control_parameters": { "control_arrays": { # Optional: define reusable current/time or power/time profiles "array_name": { "time": [0, 10, 20, ...], "current": [0.0, 2.0, 0.0, ...] # For current control # OR "power": [0.0, 10.0, -5.0, ...] # For power control (W) } }, "experiment_text": str \| list, # Can be a string or list of strings/array refs "period": str, # Time period (e.g., "1s") "anode_potential_threshold_mV": float, # Optional top-level Vne limit "temperature_threshold_degC": float, # Optional top-level thermal limit "temperature_threshold_K": float, # Optional top-level thermal limit } } When using control_arrays, experiment_text can be a list containing: - Strings: Direct experiment commands (e.g., "Rest for 60 s") - Dicts: References to control arrays: - {"type": "current", "array": "array_name"} for current control - {"type": "power", "array": "array_name"} for power control - Structured current-step dictionaries: - {"type": "soc_current", "mode": "charge"\|"discharge", "current_a": value, "until_soc": value_between_0_and_1} - {"type": "soc_current_profile", "steps": [...]} - {"type": "voltage_current", "mode": "charge"\|"discharge", "current_a": value, "until_voltage_v": value_in_volts} - {"type": "step_current", "mode": "charge"\|"discharge", "current_a": value, and one or both of "until_soc" / "until_voltage_v"; if both are provided, the step ends when the first threshold is reached} - {"type": "step_current_profile", "steps": [...]} Note: For power control, use "power" key in control_arrays and "type": "power" in references. Positive power = discharge, negative power = charge.	required
`designs`	`list[dict]`	The design parameters for the simulation.	`[]`
`formats`	`list[dict]`	The battery formats for the simulation.	`[]`
`initialSoC`	`int \| float \| list[int \| float]`	The initial state of charge for the simulation. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value.	`None`
`initialVoltage`	`int \| float \| list[int \| float]`	The initial voltage for the simulation. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value.	`None`
`initialVoltageOcvType`	`Literal['mean', 'charge', 'discharge']`	When an initial voltage is selected, this controls how the starting SOC is determined. "charge" - the charging OCV curve is used to find the corresponding starting SOC for the supplied initialVoltage "discharge" - the discharging OCV curve is used "mean" - the mean of the charge and discharge OCV curves is used	`'mean'`
`initialTemperature_degC`	`int \| float \| list[int \| float]`	The initial temperature for the simulation in degC. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value.	`25.0`
`ambientTemperature_degC`	`int \| float \| list[int \| float]`	The ambient temperature for the simulation in degC. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value.	`25.0`
`heatTransferCoefficient`	`int \| float \| list[int \| float]`	The heat transfer coefficient for the simulation in W/m2/K. Must be >= 0; there is no upper limit. Ignored when `isothermal=True`. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value.	`35.0`
`heatCapacity_kJkgK`	`int \| float \| list[int \| float]`	The heat capacity for the simulation in kJ/kg/K. If a single value is provided, it will be used for all simulations. If a list of values is provided, multiple simulations will be run with each value. If None, the default value from the battery model will be used.	`None`
`isothermal`	`bool`	If True, run the simulation isothermally — the cell temperature is held constant at `initialTemperature_degC` for the whole run (no self-heating, no exchange with ambient). `heatTransferCoefficient` and `ambientTemperature_degC` have no thermal effect in this mode. Defaults to False (lumped thermal model). Applies to every run in a batch sweep.	`False`
`cellTemperatureProfile`	`TemperatureProfile \| dict`	A prescribed cell-temperature trajectory for open-loop coupling to an external thermal model. Either a `TemperatureProfile` object or a plain dict `{"time": [seconds...], "value": [degC...]}`. When provided, the cell temperature follows this trajectory (interpolated to the solver time points; the boundary value is held outside the supplied range) instead of the model's own thermal calculation, and `ambientTemperature_degC`/`heatTransferCoefficient`/`isothermal` are unused. Works with any cycler. The heat generation is returned in the dynamic data (`"Heat generation total [W]"`) for feeding back into the external model. `time` must be strictly increasing with at least two points; `value` must be the same length. Mutually exclusive with `isothermal=True` and with batch sweeps (list-valued initial conditions). Defaults to None.	`None`

Returns:

Type	Description
`SimulationResults`	A results handler object containing the simulation results. This automatically handles both single and batch simulations.

Version 8e4a326f