Breathe Design

A class for interacting with the Breathe Design API.

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

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. 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") } } 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 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`
`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. 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`

Returns:

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