Cycler

Cycler

Represents a battery cycler protocol used in the Breathe Simulate process for dynamic analysis. Has methods to generate different battery cycler protocols in the correct format.

__init__

__init__(selected_unit, cell_capacity)

Initialize a Cycler object with the selected unit and cell capacity. The default protocol is set to CC_CHG.

Parameters:

Name	Type	Description	Default
selected_unit	str	The unit of current (A or C) used in the cycler.	required
cell_capacity	float	The capacity of the battery cell in Ah.	required

cc_chg

cc_chg(
    I_chg,
    V_max,
    soc_target=None,
    anode_potential_threshold_mV=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Create a Constant Current Charge cycler protocol.

Parameters:

Name	Type	Description	Default
I_chg	float	The charging current in [A || C]. Required.	required
V_max	float	The maximum charging voltage in V. Required.	required
soc_target	float	Optional charge SoC target between 0 and 1.	None
anode_potential_threshold_mV	float	Optional minimum anode potential threshold for current derating.	None
temperature_threshold_degC	float	Optional maximum cell temperature threshold in degrees Celsius.	None
temperature_threshold_K	float	Optional maximum cell temperature threshold in Kelvin.	None

Returns:

Type	Description
dict	representing the CC-CHG cycling protocol.

cc_dch

cc_dch(
    I_dch,
    V_min,
    soc_target=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Create a Constant Current Discharge cycler protocol.

Parameters:

Name	Type	Description	Default
I_dch	float	The discharging current in [A || C]. Required.	required
V_min	float	The minimum discharging voltage in V. Required.	required
soc_target	float	Optional discharge SoC target between 0 and 1.	None
temperature_threshold_degC	float	Optional maximum cell temperature threshold in degrees Celsius.	None
temperature_threshold_K	float	Optional maximum cell temperature threshold in Kelvin.	None

Returns:

Type	Description
dict	representing the CC-DCH cycling protocol.

cccv

cccv(
    I_chg,
    I_dch,
    I_cut,
    V_max,
    V_min,
    t_restC,
    t_restD,
    charge_target_soc=None,
    discharge_target_soc=None,
    anode_potential_threshold_mV=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Create a Constant Current Constant Voltage (CCCV) cycler protocol.

Parameters:

Name	Type	Description	Default
I_chg	float	The charging current in [A || C]. Required.	required
I_dch	float	The discharging current in [A || C]. Required.	required
I_cut	float	The cut-off current in [A || C]. Required.	required
V_max	float	The maximum charging voltage in V. Required.	required
V_min	float	The minimum discharging voltage in V. Required.	required
t_restC	float	The rest time (in seconds) after charging. Required.	required
t_restD	float	The rest time (in seconds) after discharging. Required.	required
charge_target_soc	float	Optional charge-phase SoC target.	None
discharge_target_soc	float	Optional discharge-phase SoC target.	None
anode_potential_threshold_mV	float	Optional minimum anode potential threshold for charge derating.	None
temperature_threshold_degC	float	Optional maximum cell temperature threshold in degrees Celsius.	None
temperature_threshold_K	float	Optional maximum cell temperature threshold in Kelvin.	None

Returns:

Type	Description
dict	representing the CCCV cycling protocol.

custom

custom(
    experiment_text,
    period="1s",
    control_arrays=None,
    anode_potential_threshold_mV=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Create a CUSTOM / EXPERIMENT cycler payload for structured dynamic protocols.

Parameters:

Name	Type	Description	Default
experiment_text	Any	Experiment text as a string or structured list.	required
period	str	Output/sample period. Defaults to "1s".	'1s'
control_arrays	dict	Named drive-cycle arrays for structured current/voltage/power control.	None
anode_potential_threshold_mV	float	Optional top-level charge derating threshold in mV.	None
temperature_threshold_degC	float	Optional top-level thermal derating threshold in degrees Celsius.	None
temperature_threshold_K	float	Optional top-level thermal derating threshold in Kelvin.	None

Returns:

Name	Type	Description
dict	dict	The CUSTOM cycler payload.

dcir

dcir(I_app, t_dur, t_rest_before, t_rest_after, V_min, V_max)

Create a Direct Current Internal Resistance (DCIR) cycler protocol.

Parameters:

Name	Type	Description	Default
I_app	float	The applied current in [A || C]. Positive for charge, negative for discharge. Required.	required
t_dur	float	The duration of the current pulse in seconds. Required.	required
t_rest_before	float	The rest time before the current pulse in seconds. Required.	required
t_rest_after	float	The rest time after the current pulse in seconds. Required.	required
V_min	float	The minimum voltage in V. Required.	required
V_max	float	The maximum voltage in V. Required.	required

Returns:

Type	Description
dict	representing the DCIR cycling protocol.

pulse_heating

pulse_heating(
    freq_hz,
    v_cathode_max_v,
    duration_s,
    target_temperature_c=None,
    v_anode_min_v=None,
    v_margin_v=None,
    dl_factor=None,
    v_min_v=None,
    v_max_v=None,
    temperature_breakpoints_c=None,
    soc_breakpoints=None,
    c_rate_breakpoints=None,
)

Create a PULSE_HEATING cycler protocol: self-heating by a high-frequency current train whose amplitude tracks the cell's own safe limits.

Unlike every other protocol here, the drive is not written down in advance. The amplitude is looked up from a table of maximum safe current against temperature and SoC, and the model re-reads that table from its own state at every solver step, so the train backs off as the cell warms and its SoC moves. The limit arguments below are what size that table, and they are the same arguments :func:breathe_simulate.pulse_heating.pulse_heating_lut_options takes -- drive both from one set of variables and the table you plot is the table the simulation flew.

The cell must carry a fitted double layer; the backend refuses a design without one, naming the reason. Cost is roughly 2.5 s of wall time per simulated second at 100 Hz, so a 600 s heat-up is about 25 minutes.

Parameters:

Name	Type	Description	Default
freq_hz	float	Pulse train frequency in Hz. Required. Must lie in [1.0, 10000.0].	required
v_cathode_max_v	float	Highest cathode potential the chemistry tolerates, in V. Required, and deliberately without a default -- the ceiling is a materials judgement the design does not carry. Must lie in [2.0, 5.5].	required
duration_s	float	How long to drive the train, in seconds. Required. Must lie in [0.0, 3600.0].	required
target_temperature_c	float	Stop early once the cell reaches this temperature, in degrees Celsius. Runs the full duration_s if omitted.	None
v_anode_min_v	float	Anode potential floor in V, the plating margin. Negative values are permitted so plating-risk operation can be explored deliberately. Must lie in [-0.2, 1.5]. The backend uses 0.015 V if omitted.	None
v_margin_v	float	Safety margin held back from both electrode limits, in V. Must lie in [0.0, 0.5]. The backend uses 0.050 V if omitted.	None
dl_factor	str	How the double layer is accounted for. One of "volt_first_electrode_steady", "steady_state" or "first_cycle". The backend uses "volt_first_electrode_steady" if omitted.	None
v_min_v	float	Terminal voltage floor in V. Defaults to the cell's own lower cut-off.	None
v_max_v	float	Terminal voltage ceiling in V. Defaults to the cell's own upper cut-off.	None
temperature_breakpoints_c	Sequence[float]	Temperature axis of the table, in degrees Celsius. The backend picks a grid if omitted.	None
soc_breakpoints	Sequence[float]	State-of-charge axis of the table. The backend picks a grid if omitted.	None
c_rate_breakpoints	Sequence[float]	Candidate amplitudes searched at each grid point, in C. The backend picks a grid if omitted.	None

Returns:

Type	Description
dict	representing the PULSE_HEATING cycling protocol.

rate_cap

rate_cap(
    I_chg,
    I_dch,
    I_cut,
    V_max,
    V_min,
    t_restC,
    target_soc=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Create a Rate Capacity cycler protocol.

Parameters:

Name	Type	Description	Default
I_chg	float	The charging current in [A || C]. Required.	required
I_dch	float	The discharging current in [A || C]. Required.	required
I_cut	float	The cut-off current in [A || C]. Required.	required
V_max	float	The maximum charging voltage in V. Required.	required
V_min	float	The minimum discharging voltage in V. Required.	required
t_restC	float	The rest time (in seconds) after charging. Required.	required
target_soc	float	Optional SoC target for the discharge phase.	None
temperature_threshold_degC	float	Optional maximum cell temperature threshold in degrees Celsius.	None
temperature_threshold_K	float	Optional maximum cell temperature threshold in Kelvin.	None

Returns:

Type	Description
dict	representing the RateCap cycling protocol.

soc_current_profile staticmethod

soc_current_profile(steps)

Wrap a list of SoC current steps into a SoC-current profile.

soc_current_step

soc_current_step(
    mode,
    current,
    until_soc,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Build a SoC-terminated current step for a CUSTOM experiment.

step_current_profile staticmethod

step_current_profile(steps)

Wrap a list of mixed-target current steps into a step-current profile.

step_current_step

step_current_step(
    mode,
    current,
    until_soc=None,
    until_voltage_v=None,
    anode_potential_threshold_mV=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Build a mixed-target current step for a CUSTOM experiment.

At least one of until_soc or until_voltage_v must be provided. When both are present, the step ends when the first threshold is reached.

voltage_current_step

voltage_current_step(
    mode,
    current,
    until_voltage_v,
    anode_potential_threshold_mV=None,
    temperature_threshold_degC=None,
    temperature_threshold_K=None,
)

Build a voltage-terminated current step for a CUSTOM experiment.

Version 743d2904