Breathe Simulate

A class for interacting with the Breathe Simulate 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.

generate_ecm

generate_ecm(base_battery, design=None, **ecm_kwargs)

Generates equivalent circuit model (ECM) parameters for a cell design.

The physics model runs a virtual pulse characterisation over a grid of SoC and temperature operating points and fits an n-RC network to it. The result is a set of look-up tables (R0 and one R/C pair per RC branch) over SoC x temperature x C-rate for both current directions, plus the OCV curves and thermal constants needed to run the ECM — everything derived from the same cell design the physics simulations use.

This is a LONG-RUNNING job at large or default grids. It runs on the asynchronous workers and the call polls until the job completes: there is NO client-side time limit anywhere in the SDK (long-run governance belongs to the platform).

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model to fit the ECM to.	required
`design`	`dict`	A single run_sim-style design dict (with `designName`) to fit instead of the unmodified cell. The ageing knobs (`lli`/`lamne`/`lampe`) apply to the fitted physics, so a hand-specified aged state can be characterised directly.	`None`
`**ecm_kwargs`		The parameters of :func:`breathe_simulate.ecm.ecm_options` (`n_rc`, `soc_grid`, `temp_grid_degC`, `charge_c_rates`, ...). Alternatively pass a prebuilt block as `ecm=ecm_options(...)` — mutually exclusive with the individual keywords.	`{}`

Returns:

Type	Description
`EcmResults`	A results handler wrapping the fitted ECM, with
`EcmResults`	the parameter tables, `to_dataframe()`, `save()`/`load()`
`EcmResults`	and `plot_parameters()`.

Raises:

Type	Description
`BreatheException`	If the inputs are invalid or the response carries no ECM data.

generate_pulse_heating_lut

generate_pulse_heating_lut(base_battery, design=None, **lut_kwargs)

Builds the maximum safe pulse-heating current table for a cell design.

Pulse heating warms a cold cell from the inside with a high-frequency current train. How much amplitude it can safely carry is set by the electrode potentials -- plating at the anode, oxidation at the cathode -- so the safe amplitude has to be worked out per temperature and state of charge. This returns that table.

It is FAST. The backend evaluates the cell's own expressions at rest rather than simulating, so there is no cycler, no solve, and it returns in seconds -- unlike :meth:run_sim with a PULSE_HEATING cycler, which flies the table in a closed loop and takes tens of minutes.

A run never returns this table alongside its trace, so ask for it here. Building both from one set of variables -- the arguments below are the same ones :meth:breathe_simulate.cycler.Cycler.pulse_heating takes -- is what keeps the table you plot the table the simulation flew.

The cell must carry a fitted double layer and be an SPMe design; the backend refuses anything else, naming the reason.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model to build the table for.	required
`design`	`dict`	A single run_sim-style design dict (with `designName`) to table instead of the unmodified cell.	`None`
`**lut_kwargs`		The parameters of :func:`breathe_simulate.pulse_heating.pulse_heating_lut_options` (`freq_hz` and `v_cathode_max_v` required; `v_anode_min_v`, `v_margin_v`, `dl_factor`, `v_min_v`, `v_max_v` and the three breakpoint grids optional). Alternatively pass a prebuilt block as `pulse_heating_lut=pulse_heating_lut_options(...)` -- mutually exclusive with the individual keywords.	`{}`

Returns:

Type	Description
`PulseHeatingLutResults`	A results handler wrapping the table, with
`PulseHeatingLutResults`	`to_dataframe()`, `plot()` and the `metadata` recording the
`PulseHeatingLutResults`	limits it was built with.

Raises:

Type	Description
`BreatheException`	If the inputs are invalid or the response carries no pulse-heating data.

generate_resistance_vs_frequency

generate_resistance_vs_frequency(base_battery, design=None, **curve_kwargs)

Computes total cell resistance against pulse frequency for a design.

A cell opposes a fast alternating current less than it opposes a steady one: the double layer progressively shorts out the charge-transfer and electrolyte paths as the half-period falls below its time constant. This returns that curve, from the DC resistance at low frequency down towards an instantaneous floor at high frequency. The gap between those two limits is what a pulse-heating scheme has to gain by running fast.

It is FAST. The backend evaluates the cell's own expressions at a rest state rather than simulating, so there is no cycler, no solve, and it returns in seconds.

The resistance is current-dependent, so c_rate genuinely changes the answer rather than merely selecting a row of a table.

The cell must carry a fitted double layer and be an SPMe design -- the time constant shaping the curve is the double layer's -- so the backend refuses anything else, naming the reason. Results describe settled operation at beginning of life: a train started from rest shows a higher resistance for its first few cycles.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model to evaluate.	required
`design`	`dict`	A single run_sim-style design dict (with `designName`) to evaluate instead of the unmodified cell.	`None`
`**curve_kwargs`		The parameters of :func:`breathe_simulate.resistance.resistance_vs_frequency_options` (`temperature_c`, `soc`, `c_rate`, `freq_min_hz`, `freq_max_hz`, `n_frequencies`) -- all optional, so calling with none of them asks for the default operating point. Alternatively pass a prebuilt block as `resistance_vs_frequency=resistance_vs_frequency_options(...)` -- mutually exclusive with the individual keywords.	`{}`

Returns:

Type	Description
`ResistanceCurveResults`	A results handler wrapping the curve, with
`ResistanceCurveResults`	`to_dataframe()`, `plot()`, `at()` and the two asymptotes.

Raises:

Type	Description
`BreatheException`	If the inputs are invalid or the response carries no resistance data.

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`

Note

These arguments are uppercase here, but the same ageing state inside a run_sim design dict is written lowercase ({"lampe": …, "lamne": …, "lli": …}). The uppercase spelling is accepted in a design too and normalized with a warning.

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_operating_window

get_operating_window(base_battery)

Gets the operating window of a cell, for both simulation families.

Callable for ANY battery — with or without a degradation model:

performance (run_sim): the design's voltage cut-offs (the per-cell hard limits, enforced on every protocol step) and the nominal capacity (the C-rate reference). Currents and temperatures are user inputs to the physics model.
degradation (run_ageing_sim): whether ageing simulations are available for this cell at all and, when they are, the degradation calibration's validity window (temperature, voltage, SoC, charge/discharge C-rate limits) — the envelope the model was fitted in and the only range campaigns are accepted in. When the cell has no degradation model, the result says so explicitly (has_degradation_model is False and printing the result shows the reason) rather than the section silently missing.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The battery whose operating window to report.	required

Returns:

Type	Description
`OperatingWindow`	a results handler — print it for the
`OperatingWindow`	readable summary; `.performance` / `.degradation` hold the
`OperatingWindow`	raw sections, `.has_degradation_model` the availability flag,
`OperatingWindow`	and `.to_frame()` the enforced limits as a tidy 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").

get_virtual_battery

get_virtual_battery(virtual_battery_uuid)

Get the details of a Discover virtual battery by its UUID.

You must have access to a project that the virtual battery belongs to — a project in your own organisation, or a public project, whose design space contains the virtual battery. If no such project is visible to you the call fails (the server returns 404, raised here as a BreatheException), so a virtual battery you cannot reach is not confirmed to exist.

Parameters:

Name	Type	Description	Default
`virtual_battery_uuid`	`str`	The virtual battery's UUID.	required

Returns:

Type	Description
`dict`	The virtual battery's details, including its
`dict`	`battery_definition`, `organisation_uuids`, `is_public`,
`dict`	`is_baseline` and `id`.

Example

vb = api.get_virtual_battery("2ef233f6-021d-45e8-8184-46d9b7ed4ce5") vb["battery_definition"]

run_ageing_sim

run_ageing_sim(
    base_battery,
    ageing_cycler,
    rpt_cycler=None,
    max_cycles=200,
    rpt_every_n_cycles=10,
    stop_on_soh_pct=None,
    stop_on_dcir_ohm=None,
    stop_on_energy_throughput_Wh=None,
    stop_on_time_days=None,
    soc_reference="latest_rpt",
    performance_cycler=None,
    performance_start_soc=1.0,
    resume_from=None,
    initialTemperature_degC=25.0,
    ambientTemperature_degC=25.0,
    heatTransferCoefficient=35.0,
    heatCapacity_kJkgK=None,
    isothermal=False,
    return_rpt_timeseries=False,
    return_timeseries=False,
    return_dva=None,
    charge_time_soc_window=None,
    return_charge_analysis=False,
    timeseries_max_points_per_segment=None,
    show_progress=True,
    poll_interval_s=2.0,
    ecm=None,
)

Runs a cycle-by-cycle ageing (degradation) campaign for a base battery.

The campaign is: baseline RPT -> rpt_every_n_cycles ageing cycles -> RPT -> ... until a stop criterion fires. State of health (SoH) and DCIR are always measured by the reference performance test (RPT), never from the ageing cycles themselves. The base battery must have a degradation model; design or format modifications are not supported for ageing simulations (degradation models are calibrated per cell).

There is NO client-side time limit on the simulation: the call polls until the job completes. Long-run governance is handled by the platform.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the simulation. Must have a degradation model attached, otherwise the API returns an error.	required
`ageing_cycler`	`dict \| list`	The ageing protocol, built with :class:`breathe_simulate.ageing.AgeingCycler` (cyclic, calendar, custom, or from_csv). A LIST of `{"cycler": <protocol>, "cycles": N}` phases runs a mixed schedule back to back — e.g. 100 cyclic cycles, then calendar storage — with the campaign-level RPT cadence and stop criteria applying across the whole schedule. `cycles` is the number of ageing cycles the phase runs (for a calendar phase, the number of storage blocks). When the schedule is exhausted before `max_cycles` or any stop criterion, the campaign stops with `stop_condition["triggered"] == "schedule_complete"`. `result.cycles` carries a `phase` column (the 0-based phase index) for slicing per phase.	required
`rpt_cycler`	`dict`	The RPT protocol, built with :class:`breathe_simulate.ageing.RptCycler`. When omitted, the campaign runs ageing-only: no SoH/DCIR columns, and SoH/DCIR stop criteria are unavailable.	`None`
`max_cycles`	`int`	Hard ceiling on the number of ageing cycles. Defaults to 200.	`200`
`rpt_every_n_cycles`	`int`	Ageing cycles between RPTs (for calendar ageing, one storage block runs between RPTs instead). Defaults to 10.	`10`
`stop_on_soh_pct`	`float`	Stop when RPT-based SoH (in %, relative to the baseline RPT) falls to or below this value. Requires `rpt_cycler`.	`None`
`stop_on_dcir_ohm`	`float`	Stop when the RPT pulse resistance (Ohm) rises to or above this value. Requires `rpt_cycler`.	`None`
`stop_on_energy_throughput_Wh`	`float`	Stop when the cumulative discharged energy reaches this value (Wh). The counter includes the RPTs' own throughput, matching lab bookkeeping and the MATLAB reference implementation.	`None`
`stop_on_time_days`	`float`	Stop when the simulated time reaches this value (days) — the natural criterion for calendar ageing.	`None`
`soc_reference`	`Literal['latest_rpt', 'bol']`	How SoC bounds in the ageing protocol are defined: against the latest RPT's SoC-reference capacity (updates as the cell ages, like most lab protocols) or against the beginning-of-life capacity. Defaults to "latest_rpt".	`'latest_rpt'`
`performance_cycler`	`dict`	The END-OF-CAMPAIGN performance test: ANY run_sim cycler built with :class:`breathe_simulate.Cycler` (cc_chg, cc_dch, cccv, dcir, rate_cap, or custom — including drive cycles), executed on the LIVE aged cell with degradation still active. It runs ONCE, after a stop criterion has fired, characterising the final aged state. Before the test the cell is preconditioned to a defined state: CC-CV charge to the RPT's full, then a coulomb-counted discharge to `performance_start_soc`. Results are exposed as `result.performance` with the same dynamic-data structure as run_sim. Compare against the campaign's baseline RPT for the fresh-versus-aged story. Requires `rpt_cycler`.	`None`
`performance_start_soc`	`int \| float`	State of charge (0-1) the cell is brought to before the performance test, defined against the latest RPT's reference capacity. Defaults to 1.0 (test starts from full).	`1.0`
`resume_from`	`dict`	Reserved for resuming/branching from a previous campaign's saved state. Not supported in this release — must be None.	`None`
`initialTemperature_degC`	`int \| float`	Initial cell temperature in degC. Also the RPT reference temperature when the RPT's `reset_temperature` is enabled. Defaults to 25.	`25.0`
`ambientTemperature_degC`	`int \| float`	Ambient temperature during ageing in degC. Defaults to 25.	`25.0`
`heatTransferCoefficient`	`int \| float`	Heat transfer coefficient in W/m2/K. Defaults to 35.	`35.0`
`heatCapacity_kJkgK`	`int \| float`	Cell heat capacity in kJ/kg/K. If None, the battery model's own value is used.	`None`
`isothermal`	`bool`	Run the whole campaign isothermally — the cell temperature is held at `initialTemperature_degC` (no self-heating, no ambient exchange). Ambient temperatures (campaign-level and per-leg drive-cycle ambients) then have no thermal effect. Defaults to False (lumped thermal model).	`False`
`return_rpt_timeseries`	`bool`	Also return downsampled voltage/current/temperature traces for each RPT. Defaults to False.	`False`
`return_timeseries`	`bool`	Also return the labelled campaign timeseries — downsampled voltage/current/temperature/ SoC for EVERY segment (ageing cycles and RPT parts), stitched onto one campaign time axis and labelled with segment type, cycle number and RPT number. Exposed as `result.timeseries` and plotted with `result.plot_timeseries(kpi=...)`. Adds response size on long campaigns. Defaults to False.	`False`
`return_dva`	`bool`	Opt into the differential analysis (`result.dva`: DVA dV/dQ and ICA dQ/dV, both the charge and the discharge branch of every RPT) — an advanced diagnostic, OFF by default. `return_dva=True` differentiates RPT part 1's recharge and SoC-reference discharge at no extra simulation cost. Defining a DEDICATED slow DVA cycle on the RPT (the classic lab check-up, e.g. C/10 — `RptCycler.build(..., I_dva_dch=...)`) opts in by itself; combining that with an explicit `return_dva=False` is rejected as contradictory.	`None`
`charge_time_soc_window`	`tuple`	The SoC window the per-cycle charge time is measured over, as `(low, high)` fractions. Defaults to `(0.1, 0.8)`, the conventional fast-charge figure of merit. The measured time appears in `result.cycles` as `charge_time_<low>_<high>_pct_s` and is plotted by `result.plot_charge_time()`.	`None`
`return_charge_analysis`	`bool`	Include the per-cycle fast-charge analysis (`result.charge_analysis`): the SoC window and whether each cycle traversed it, achieved SoC at entry and exit, charge time, throughput, mean and peak current and C-rate, voltage at the boundaries, and the minimum anode potential and peak temperature INSIDE the window. `result.charge_analysis_definition` states where the SoC comes from and how each quantity is defined. An opt-in, defaulting to False, so campaigns that are not about fast charge are not littered with a table they will not read. The one-line charge time stays in `result.cycles` regardless.	`False`
`timeseries_max_points_per_segment`	`int`	Downsampling budget per segment for the campaign timeseries (None -> the backend default, 1000 points per segment).	`None`
`show_progress`	`bool`	Print campaign progress. On the synchronous transport (the current default) this is a start line and a completion summary — the platform cannot stream progress mid-request. On the queued transport it renders a live progress line; a cycle bar with ETA appears once the platform workers publish per-cycle progress in the poll status. Defaults to True.	`True`
`poll_interval_s`	`float`	Seconds between job status polls. Defaults to 2.	`2.0`
`ecm`	`bool \| dict`	Also fit an equivalent circuit model at the END-OF-CAMPAIGN aged state. `True` uses the default :func:`breathe_simulate.ecm.ecm_options` block; pass `ecm_options(...)` to customise the fit. The fit applies the campaign's final LLI / LAM state to the physics (SEI film resistance growth is not part of the aged parameter bridge today, matching aged run_sim). An ECM fit adds tens of minutes at the default grids. Exposed as `result.ecm`, whose `degradation_state` records the fitted aged state. Defaults to None (no fit).	`None`

Returns:

Type	Description
`AgeingSimulationResults`	A results handler with `.rpt` (per-RPT
`AgeingSimulationResults`	summary, including the LLI split into SEI vs plating), `.dcir`
`AgeingSimulationResults`	(per-pulse resistance table), `.cycles` (per-cycle trajectory,
`AgeingSimulationResults`	including the minimum anode potential — the plating-risk
`AgeingSimulationResults`	indicator), `.dva` (opt-in per-RPT differential voltage /
`AgeingSimulationResults`	incremental capacity curves, both branches — see
`AgeingSimulationResults`	`return_dva`), `.timeseries` (labelled campaign signal),
`AgeingSimulationResults`	`.performance` (in-campaign performance tests, run_sim-shaped),
`AgeingSimulationResults`	`.ecm` (the aged-state equivalent circuit model, when
`AgeingSimulationResults`	requested), `.stop_condition`, and plotting helpers. Printing
`AgeingSimulationResults`	the result shows the grouped overview.

run_sim

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

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

Only one of initialSoC or initialVoltage should be provided.

Pass either base_battery or virtual_battery_uuid, not both.

The simulation runs on the queued workers and there is NO client-side time limit: the call polls until the job completes. Long-run governance is handled by the platform.

Parameters:

Name	Type	Description	Default
`base_battery`	`str`	The base battery model for the simulation.	`None`
`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.	`None`
`designs`	`list[dict]`	The design parameters for the simulation. Design keys are validated before the request is sent: an unsupported key raises, listing the supported knobs, rather than failing server-side. The ageing state is spelled `lampe`/`lamne`/`lli` here (`get_aged_ocv` uses the uppercase form; it is accepted and normalized with a warning). Alongside the physical design knobs and the ageing state (`lampe`/`lamne`/`lli`), each design accepts `capacityVariationPercent` (-5 to +5): a cell-to-cell capacity variation in percent that scales the cell capacity and both electrodes' maximum lithium concentrations by `1 + percent/100`, leaving the OCV and electrode balancing untouched. Use it to simulate cells slightly above or below nominal capacity, for example `designs=[{"designName": "cell +2%", "capacityVariationPercent": 2.0}]`.	`[]`
`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`
`initialHysteresis`	`int \| float \| list[int \| float]`	The cell's initial OCV hysteresis state, in [-1, 1]. `-1` is a cell that was last discharged (it rests on the lower OCV envelope), `+1` a cell that was last charged (upper envelope) and `0` the mean OCV. Values in between describe a cell that has partly relaxed between the two. With `initialSoC` it sets the t=0 OCV at that SoC; with `initialVoltage` it selects the OCV branch the voltage is inverted on, so the same voltage resolves to a different SoC per branch. Defaults to the state the battery model carries (`0` for a voltage start). If a list of values is provided, multiple simulations will be run with each value.	`None`
`initialVoltageOcvType`	`Literal['mean', 'charge', 'discharge']`	DEPRECATED, use `initialHysteresis` (`charge` / `mean` / `discharge` is `+1` / `0` / `-1`). Only read with `initialVoltage`; cannot be combined with `initialHysteresis`.	`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. 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`
`virtual_battery_uuid`	`str`	Run a Discover virtual battery instead of `base_battery`, e.g. one from `get_virtual_battery`. The virtual battery's own design (including its design changes) is simulated, along with its unmodified baseline cell as `"Baseline"`; in the results the virtual battery's entry is named by its uuid. You need access to a Discover project the virtual battery belongs to, and to the design components it uses. Can't be combined with `designs` or `formats`. 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 743d2904