Experiment

Classes to define electrochemical cycling protocols.

class src.rfbzero.experiment.CyclingResults(duration: float, time_step: float, charge_first: bool = True, products_cls: list[str] | None = None, products_ncls: list[str] | None = None)

A container of the simulation result data.

Parameters:

• duration (float) – Simulation time (s).

• time_step (float) – Simulation time step (s).

• charge_first (bool, optional) – True if CLS charges first, False if CLS discharges first. Defaults to True.

• products_cls (list[str], optional) – The names of any additional product species in the CLS.

• products_ncls (list[str], optional) – The names of any additional product species in the NCLS.

max_steps: int

The number of time steps that were desired from the simulation.

steps: int

The number of time steps that were actually performed before the simulation terminated.

step_time: list[float]

The simulation time (s), at each time step.

step_is_charge: list[bool]

Whether the half cycle was charge (True) or discharge (False), at each time step.

current: list[float]

The instantaneous current flowing (A), at each time step.

cell_v: list[float]

The cell voltage (V), at each time step.

ocv: list[float]

The cell open circuit voltage (V), at each time step.

c_ox_cls: list[float]

The CLS concentration of oxidized species (M), at each time step.

c_red_cls: list[float]

The CLS concentration of reduced species (M), at each time step.

c_ox_ncls: list[float]

The NCLS concentration of oxidized species (M), at each time step.

c_red_ncls: list[float]

The NCLS concentration of reduced species (M), at each time step.

c_products_cls: dict[str, list[float]]

The CLS concentrations of any product species (M), at each time step.

c_products_ncls: dict[str, list[float]]

The NCLS concentrations of any product species (M), at each time step.

crossed_ox_mols: list[float]

Oxidized species crossing (mols), at each time step. Only meaningful for symmetric cell.

crossed_red_mols: list[float]

Reduced species crossing (mols), at each time step. Only meaningful for symmetric cell.

soc_cls: list[float]

The CLS state of charge, at each time step.

soc_ncls: list[float]

The NCLS state of charge, at each time step.

act: list[float]

The combined (CLS+NCLS) activation overpotential (V), at each time step.

mt: list[float]

The combined (CLS+NCLS) mass transport overpotential (V), at each time step.

total_overpotential: list[float]

The total cell overpotential (V), at each time step.

half_cycles: int

The number of complete half cycles performed during the simulation.

half_cycle_capacity: list[float]

The cell capacity (C), for each half cycle.

half_cycle_time: list[float]

The last time step, for each half cycle.

half_cycle_is_charge: list[bool]

Whether the half cycle was charge (True) or discharge (False), for each half cycle.

charge_cycle_capacity: list[float]

The cell capacity (C), for each charge half cycle.

charge_cycle_time: list[float]

The last time step, for each charge half cycle.

discharge_cycle_capacity: list[float]

The cell capacity (C), for each discharge half cycle.

discharge_cycle_time: list[float]

The last time step, for each discharge half cycle.

end_status: CyclingStatus

The reason for the simulation’s termination.

class src.rfbzero.experiment.CyclingStatus(value)

Used for keeping track of cycling status throughout simulation, and to report how the simulation terminated.

NORMAL = 'normal'

NEGATIVE_CONCENTRATIONS = 'negative species concentrations'

VOLTAGE_LIMIT_REACHED = 'voltage limits reached'

CURRENT_CUTOFF_REACHED = 'current cutoffs reached'

LIMITING_CURRENT_REACHED = 'current has exceeded the limiting currents for the cell concentrations'

LOW_CAPACITY = 'capacity is less than 1% of initial CLS capacity'

TIME_DURATION_REACHED = 'time duration reached'

class src.rfbzero.experiment.CyclingProtocol(voltage_limit_charge: float, voltage_limit_discharge: float, charge_first: bool = True)

Abstract class representing a cycling protocol.

Parameters:

• voltage_limit_charge (float) – Voltage above which cell will switch to discharge (V).

• voltage_limit_discharge (float) – Voltage below which cell will switch to charge (V).

• charge_first (bool) – True if CLS charges first, False if CLS discharges first.

abstract run(duration: int, cell_model: ZeroDModel, degradation: DegradationMechanism | None = None, cls_degradation: DegradationMechanism | None = None, ncls_degradation: DegradationMechanism | None = None, crossover: Crossover | None = None) → CyclingResults

Applies a cycling protocol and (optional) degradation/crossover mechanisms to a cell model.

Parameters:

• duration (int) – Simulation time (s).

• cell_model (ZeroDModel) – Defined cell parameters for simulation.

• degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS and NCLS.

• cls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS.

• ncls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to NCLS.

• crossover (Crossover, optional) – Crossover mechanism applied to cell.

class src.rfbzero.experiment.ConstantCurrent(voltage_limit_charge: float, voltage_limit_discharge: float, current: float | None = None, current_charge: float | None = None, current_discharge: float | None = None, charge_first: bool = True)

Provides a constant current (CC) cycling method.

Parameters:

• voltage_limit_charge (float) – Voltage above which cell will switch to discharge (V).

• voltage_limit_discharge (float) – Voltage below which cell will switch to charge (V).

• current (float) – Current (A) value used for charging. The negative of this value is used for discharging current.

• current_charge (float) – Desired charging current for CC cycling (A).

• current_discharge (float) – Desired discharging current for CC cycling (A). Input must be a negative value.

• charge_first (bool) – True if CLS charges first, False if CLS discharges first.

run(duration: int, cell_model: ZeroDModel, degradation: DegradationMechanism | None = None, cls_degradation: DegradationMechanism | None = None, ncls_degradation: DegradationMechanism | None = None, crossover: Crossover | None = None) → CyclingResults

Applies the constant current (CC) protocol and (optional) degradation/crossover mechanisms to a cell model.

Parameters:

• duration (int) – Simulation time (s).

• cell_model (ZeroDModel) – Defined cell parameters for simulation.

• degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS and NCLS.

• cls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS.

• ncls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to NCLS.

• crossover (Crossover, optional) – Crossover mechanism applied to cell.

Returns:

results – Container of simulation results.

Return type:

CyclingResults

class src.rfbzero.experiment.ConstantVoltage(voltage_limit_charge: float, voltage_limit_discharge: float, current_cutoff: float | None = None, current_cutoff_charge: float | None = None, current_cutoff_discharge: float | None = None, charge_first: bool = True)

Provides a constant voltage (CV) cycling method.

Parameters:

• voltage_limit_charge (float) – Voltage the cell is held at during charge (V).

• voltage_limit_discharge (float) – Voltage the cell is held at during discharge (V).

• current_cutoff (float) – Current below which cell will switch to charge, and above (the negative of this value) which will switch to discharge (A).

• current_cutoff_charge (float) – Current below which cell will switch to discharge (A).

• current_cutoff_discharge (float) – Current above which cell will switch to charge (A).

• charge_first (bool) – True if CLS charges first, False if CLS discharges first.

run(duration: int, cell_model: ZeroDModel, degradation: DegradationMechanism | None = None, cls_degradation: DegradationMechanism | None = None, ncls_degradation: DegradationMechanism | None = None, crossover: Crossover | None = None) → CyclingResults

Applies the constant voltage (CV) cycling protocol and (optional) degradation/crossover mechanisms to a cell model.

Parameters:

• duration (int) – Simulation time (s).

• cell_model (ZeroDModel) – Defined cell parameters for simulation.

• degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS and NCLS.

• cls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS.

• ncls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to NCLS.

• crossover (Crossover, optional) – Crossover mechanism applied to cell.

Returns:

results – Container of simulation results.

Return type:

CyclingResults

class src.rfbzero.experiment.ConstantCurrentConstantVoltage(voltage_limit_charge: float, voltage_limit_discharge: float, current_cutoff: float | None = None, current_cutoff_charge: float | None = None, current_cutoff_discharge: float | None = None, current: float | None = None, current_charge: float | None = None, current_discharge: float | None = None, charge_first: bool = True)

Provides a constant current constant voltage (CCCV) cycling method which, in the limit of a high current demanded of a cell that it cannot maintain, becomes a constant voltage (CV) cycling method.

Parameters:

• voltage_limit_charge (float) – Voltage above which cell will switch to CV mode, charging (V).

• voltage_limit_discharge (float) – Voltage below which cell will switch to CV mode, discharging (V).

• current_cutoff (float) – Current below which CV charging will switch to CC portion of CCCV discharge (A), and above (the negative of this value) which CV discharging will switch to CC portion of CCCV charge (A).

• current_cutoff_charge (float) – Current below which CV charging will switch to CC portion of CCCV discharge (A).

• current_cutoff_discharge (float) – Current above which CV discharging will switch to CC portion of CCCV charge (A).

• current (float) – Current (A) value used for charging. The negative of this value is used for discharging current.

• current_charge (float) – Desired charging current for CC cycling (A).

• current_discharge (float) – Desired discharging current for CC cycling (A). Input must be a negative value.

• charge_first (bool) – True if CLS charges first, False if CLS discharges first.

run(duration: int, cell_model: ZeroDModel, degradation: DegradationMechanism | None = None, cls_degradation: DegradationMechanism | None = None, ncls_degradation: DegradationMechanism | None = None, crossover: Crossover | None = None) → CyclingResults

Applies the constant current constant voltage (CCCV) cycling protocol and (optional) degradation/crossover mechanisms to a cell model.

Parameters:

• duration (int) – Simulation time (s).

• cell_model (ZeroDModel) – Defined cell parameters for simulation.

• degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS and NCLS.

• cls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to CLS.

• ncls_degradation (DegradationMechanism, optional) – Degradation mechanism applied to NCLS.

• crossover (Crossover, optional) – Crossover mechanism applied to cell.

Returns:

results – Container of simulation results.

Return type:

CyclingResults