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.	`'.'`

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`	containing the battery format.

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. Args: base_battery (str): The base battery model for the battery format.

Returns:

Type	Description
`dict`	containing the battery format.

run_sim

run_sim(
    base_battery,
    cycler,
    designs=[],
    formats=[],
    initialSoC=0.5,
    initialTemperature_degC=25.0,
    ambientTemperature_degC=25.0,
)

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

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the simulation.	required
`cycler`	`dict`	The cycler parameters for the simulation.	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.	`0.5`
`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`

Returns:

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