Battery#

class physics.models.battery.BasicBattery(state_of_charge, max_voltage, min_voltage, max_current_capacity, max_energy_capacity)#

Bases: BaseBattery

Class representing the DayBreak battery pack.

max_voltage#

maximum voltage of the DayBreak battery pack (V)

Type:

float

min_voltage#

minimum voltage of the DayBreak battery pack (V)

Type:

float

max_current_capacity#

nominal capacity of the DayBreak battery pack (Ah)

Type:

float

max_energy_capacity#

nominal energy capacity of the DayBreak battery pack (Wh)

Type:

float

state_of_charge#

instantaneous battery state-of-charge (0.00 - 1.00)

Type:

float

discharge_capacity#

instantaneous amount of charge extracted from battery (Ah)

Type:

float

voltage#

instantaneous voltage of the battery (V)

Type:

float

stored_energy#

instantaneous energy stored in the battery (Wh)

Type:

float

get_raw_soc(cumulative_energy_array)#

Return the not truncated (SOC is allowed to go above 100% and below 0%) state of charge.

Parameters:

cumulative_energy_array (np.ndarray) – a NumPy array containing the cumulative energy changes at each time step

experienced by the battery

Returns:

a NumPy array containing the battery state of charge at each time step

Return type:

np.ndarray

update_array(cumulative_energy_array)#

Performs energy calculations with NumPy arrays

Parameters:

cumulative_energy_array – a NumPy array containing the cumulative energy changes at each time step

experienced by the battery

Returns:

soc_array – a NumPy array containing the battery state of charge at each time step

Returns:

voltage_array – a NumPy array containing the voltage of the battery at each time step

Returns:

stored_energy_array– a NumPy array containing the energy stored in the battery at each time step

class physics.models.battery.BaseBattery(initial_energy, max_current_capacity, max_energy_capacity, max_voltage, min_voltage, voltage, state_of_charge)#

Bases: ABC

class physics.models.battery.BatteryModelConfig(R_0_data, Soc_data, R_P_data, C_P_data, Uoc_data, Q_total)#

Bases: object

A concrete implementation of the EquivalentCircuitModelConfig protocol.

This implementation fits values of U_oc, R_0, R_P, and C_P at various state-of-charge (SOC) values to a seventh degree polynomial to generate a smooth function mapping SOC to each battery parameter.

For example, R_0 = R_0_data[i] when Soc = Soc_data[i].

property Q_total: float#
property get_C_P: Callable[[float | ndarray[Any, dtype[float]]], float | ndarray[Any, dtype[float]]]#
property get_R_0: Callable[[float | ndarray[Any, dtype[float]]], float | ndarray[Any, dtype[float]]]#
property get_R_P: Callable[[float | ndarray[Any, dtype[float]]], float | ndarray[Any, dtype[float]]]#
property get_Uoc: Callable[[float | ndarray[Any, dtype[float]]], float | ndarray[Any, dtype[float]]]#
class physics.models.battery.KalmanFilterConfig(battery_model_config: BatteryModelConfig, process_noise_matrix: ndarray[Any, dtype[_ScalarType_co]], state_covariance_matrix: ndarray[Any, dtype[_ScalarType_co]], measurement_noise_vector: ndarray[Any, dtype[_ScalarType_co]])#

Bases: object

property battery_model_config: BatteryModelConfig#

Configuration of the underlying EquivalentCircuitModel.

property measurement_noise_vector: ndarray[Any, dtype[float]]#

A 1x1 vector containing the noise expected in the terminal voltage measurement.

property process_noise_matrix: ndarray[Any, dtype[float]]#

A 2x2 matrix containing the process noise covariance matrix where [0, 0] is the SOC evolution noise and [1, 1] is the polarization potential evolution noise.

property state_covariance_matrix: ndarray[Any, dtype[float]]#

A 2x2 matrix containing the state covariance matrix where [0, 0] is the SOC covariance noise and [1, 1] is the polarization potential covariance.

class physics.models.battery.EquivalentCircuitBatteryModel(battery_config: EquivalentCircuitModelConfig, state_of_charge: float = 1.0)#

Bases: object

A first-order Thevenin equivalent model of a lithium-ion battery pack

update_array(tick: float, delta_energy_array: ndarray[Any, dtype[_ScalarType_co]] | None = None, current_array: ndarray[Any, dtype[_ScalarType_co]] | None = None, use_compiled: bool = True) → tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]#

Compute the battery’s state of charge and terminal voltage over time in response to a time series of energy/current draw from a load.

Only ONE of current_array or delta_energy_array should be provided.

Notes

If both current and power are known, current should be provided. The model implementation requires current for calculations, so it must be derived from power if power was provided. Computing current from power relies on voltage, which is a model output, and therefore the derived current could be less accurate.

Parameters:

  • delta_energy_array (NDArray) – Array of energy changes (J) at each time step.

  • tick (float) – Time interval for each step (seconds).

  • current_array (NDArray) – Array of current draw (positive sign convention) in Amperes at each time step.

  • use_compiled (bool) – If True, use compiled binaries for calculations. Disable for better debugging.

Returns:

A tuple containing arrays for state-of-charge and terminal voltage.

Raises:

ValueError – If BOTH or NEITHER of current_array or delta_energy_array are provided.

Return type:

tuple[NDArray, NDArray]

class physics.models.battery.FilteredBatteryModel(battery_config: FilteredBatteryModelConfig, initial_SOC: float = 1.0, initial_Uc: float = 0.0, alpha: float = 0.9)#

Bases: object

FilteredBatteryModel is a first-order Thevenin equivalent model of a lithium-ion battery packed, wrapped in a Kalman filter which uses voltage measurements with model predictions.

property SOC: float#

Return the current SOC of the battery.

Returns:

The current state of charge.

property Uc: float#

Return the polarization voltage of the battery.

Returns:

The current polarization voltage.

property Ut: float#

Return the predicted terminal voltage for the last prediction step.

Returns:

The predicted terminal voltage.

predict_state(current, time_step)#

Predict the next evolution of the state vector (SOC, Uc). This function should be called before updating the filter in a typical predict-update workflow.

Parameters:

  • current (float) – The current being sourced by the battery. Sign convention is that positive indicates current being drawn.

  • time_step (float) – Time elapsed between this prediction and the last updated state of the filter (seconds).

predict_then_update(measured_Ut: float, current: float, time_step: float)#

Predict the next evolution of the state vector (SOC, Uc), then update the filter based on this prediction and a measurement. Abstracts the full predict-update workflow of the EKF.

Parameters:

  • measured_Ut (float) – The actual voltage across the terminals of the battery.

  • current (float) – The current being sourced by the battery. Positive indicates current being drawn.

  • time_step (float) – Time elapsed between this prediction and the last updated state of the filter (seconds).

update_filter(measured_Ut, current)#

Update the filter based on a new measurement and the predicted state. This function should be called after predict_state in a typical predict-update workflow.

Parameters:

  • measured_Ut (float) – The actual voltage across the terminals of the battery.

  • current (float) – The current being sourced by the battery.

On this page
Show Source