ECM generation

Builder for the equivalent circuit model (ECM) generation settings.

ECM generation fits an n-RC equivalent circuit model to a cell design by running a virtual pulse characterisation on the physics model. The :func:ecm_options builder assembles the ecm request block consumed by BreatheSimulateModel.generate_ecm and BreatheSimulateModel.run_ageing_sim(..., ecm=...). Customer-facing units are Celsius; temperatures are converted to Kelvin on the wire.

ecm_options

ecm_options(
    n_rc=2,
    soc_grid=None,
    temp_grid_degC=None,
    charge_c_rates=None,
    discharge_c_rates=None,
    pulse_duration_s=60.0,
    rest_duration_s=1800.0,
    pulse_durations_s=None,
    soc_charge_only_below=0.08,
    soc_discharge_only_above=0.92,
    initial_soc=1.0,
    use_cell_voltage_limits=True,
    upper_voltage_cutoff_V=None,
    lower_voltage_cutoff_V=None,
    heatTransferCoefficient=30.0,
    ambientTemperature_degC=25.0,
    initialTemperature_degC=25.0,
)

Build the ecm settings block for ECM generation.

The block configures the virtual pulse characterisation the physics model runs and the RC network fitted to it. Grids left at None use the backend defaults noted below. Pass the result to BreatheSimulateModel.generate_ecm (as ecm=... or via its keyword arguments) or to BreatheSimulateModel.run_ageing_sim(..., ecm=...).

The fit cost scales with len(soc_grid) * len(temp_grid_degC) (one pulse train per operating point): the default grids take tens of minutes.

Parameters:

Name	Type	Description	Default
n_rc	int	Number of RC pairs in the fitted network: 1, 2 or 3. Defaults to 2.	2
soc_grid	list[float]	SoC breakpoints (0 to 1) the parameters are fitted at. Defaults to the backend's 11-point grid.	None
temp_grid_degC	list[float]	Temperature breakpoints in degC. Defaults to the backend's [10, 25, 40] degC grid.	None
charge_c_rates	list[float]	Charge pulse C-rates (positive). Defaults to [0.33, 1.0, 2.0, 3.0].	None
discharge_c_rates	list[float]	Discharge pulse C-rates (positive). Defaults to [0.33, 1.0, 2.0, 3.0].	None
pulse_duration_s	float	Pulse length in seconds. Defaults to 60.	60.0
rest_duration_s	float	Rest after each pulse in seconds (the relaxation the RC pairs are fitted to). Defaults to 1800.	1800.0
pulse_durations_s	list[float]	Advanced: several pulse lengths per operating point instead of a single pulse_duration_s.	None
soc_charge_only_below	float	Below this SoC only charge pulses are applied (discharge pulses would undershoot the window). Defaults to 0.08.	0.08
soc_discharge_only_above	float	Above this SoC only discharge pulses are applied. Defaults to 0.92.	0.92
initial_soc	float	SoC the characterisation starts from. Defaults to 1.	1.0
use_cell_voltage_limits	bool	Clamp pulses to the design's own voltage window (recommended: the fitted ECM covers exactly the window the cell is operated in). Breathe Discover's canonical ECM spec uses wide fixed cutoffs instead; set False with explicit cutoffs to reproduce it. Defaults to True.	True
upper_voltage_cutoff_V	float	Explicit upper voltage cutoff. Only sent when set; ignored by the backend when use_cell_voltage_limits is True.	None
lower_voltage_cutoff_V	float	Explicit lower voltage cutoff. Only sent when set; ignored by the backend when use_cell_voltage_limits is True.	None
heatTransferCoefficient	float	Heat transfer coefficient in W/m2/K during the characterisation. Defaults to 30.	30.0
ambientTemperature_degC	float	Ambient temperature in degC. Defaults to 25.	25.0
initialTemperature_degC	float	Initial cell temperature in degC. Defaults to 25.	25.0

Returns:

Type	Description
dict	The ecm request block, with temperatures in Kelvin and
dict	the backend's wire field names.

Raises:

Type	Description
BreatheException	If any parameter is out of bounds or of the wrong type.

Version fe1f5cb5