ubc-solar-physics 1.7.7__cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

physics/models/battery/basic_battery.py

@@ -0,0 +1,140 @@
+import numpy as np
+from numpy.polynomial import Polynomial
+from physics.models.battery.base_battery import BaseBattery
+
+
+class BasicBattery(BaseBattery):
+    """
+    Class representing the DayBreak battery pack.
+
+    Attributes:
+        max_voltage (float): maximum voltage of the DayBreak battery pack (V)
+        min_voltage (float): minimum voltage of the DayBreak battery pack (V)
+        max_current_capacity (float): nominal capacity of the DayBreak battery pack (Ah)
+        max_energy_capacity (float): nominal energy capacity of the DayBreak battery pack (Wh)
+
+        state_of_charge (float): instantaneous battery state-of-charge (0.00 - 1.00)
+        discharge_capacity (float): instantaneous amount of charge extracted from battery (Ah)
+        voltage (float): instantaneous voltage of the battery (V)
+        stored_energy (float): instantaneous energy stored in the battery (Wh)
+    """
+
+    def __init__(self, state_of_charge, max_voltage, min_voltage, max_current_capacity, max_energy_capacity):
+        """
+
+        Constructor for BasicBattery class.
+
+        :param float state_of_charge: initial battery state of charge
+
+        """
+
+        # ----- DayBreak battery constants -----
+
+        self.max_voltage = max_voltage
+        self.min_voltage = min_voltage
+        self.max_current_capacity = max_current_capacity
+        self.max_energy_capacity = max_energy_capacity
+
+        # ----- DayBreak battery equations -----
+
+        self.calculate_voltage_from_discharge_capacity = calculate_voltage_from_discharge_capacity()
+
+        self.calculate_energy_from_discharge_capacity = calculate_energy_from_discharge_capacity()
+
+        self.calculate_soc_from_discharge_capacity = calculate_soc_from_discharge_capacity(self.max_current_capacity)
+
+        self.calculate_discharge_capacity_from_soc = calculate_discharge_capacity_from_soc(self.max_current_capacity)
+
+        self.calculate_discharge_capacity_from_energy = calculate_discharge_capacity_from_energy()
+
+        # ----- DayBreak battery variables -----
+
+        self.state_of_charge = state_of_charge
+
+        # SOC -> discharge_capacity
+        self.discharge_capacity = self.calculate_discharge_capacity_from_soc(self.state_of_charge)
+
+        # discharge_capacity -> voltage
+        self.voltage = self.calculate_voltage_from_discharge_capacity(self.discharge_capacity)
+
+        # discharge_capacity -> energy
+        self.stored_energy = self.max_energy_capacity - self.calculate_energy_from_discharge_capacity(
+            self.discharge_capacity)
+
+        # ----- DayBreak battery initialisation -----
+
+        super().__init__(self.stored_energy, self.max_current_capacity, self.max_energy_capacity,
+                         self.max_voltage, self.min_voltage, self.voltage, self.state_of_charge)
+
+    def update_array(self, cumulative_energy_array):
+        """
+        Performs energy calculations with NumPy arrays
+
+        :param cumulative_energy_array: a NumPy array containing the cumulative energy changes at each time step
+        experienced by the battery
+
+        :return: soc_array – a NumPy array containing the battery state of charge at each time step
+
+        :return: voltage_array – a NumPy array containing the voltage of the battery at each time step
+
+        :return: stored_energy_array– a NumPy array containing the energy stored in the battery at each time step
+
+        """
+
+        stored_energy_array = np.full_like(cumulative_energy_array, fill_value=self.stored_energy)
+        stored_energy_array += cumulative_energy_array / 3600
+        stored_energy_array = np.clip(stored_energy_array, a_min=0, a_max=self.max_energy_capacity)
+
+        energy_discharged_array = np.full_like(cumulative_energy_array, fill_value=self.max_energy_capacity) - \
+                                  stored_energy_array
+
+        discharge_capacity_array = self.calculate_discharge_capacity_from_energy(energy_discharged_array)
+
+        soc_array = self.calculate_soc_from_discharge_capacity(discharge_capacity_array)
+        voltage_array = self.calculate_voltage_from_discharge_capacity(discharge_capacity_array)
+
+        return soc_array, voltage_array, stored_energy_array
+
+    def get_raw_soc(self, cumulative_energy_array):
+        """
+
+        Return the not truncated (SOC is allowed to go above 100% and below 0%) state of charge.
+
+        :param np.ndarray cumulative_energy_array: a NumPy array containing the cumulative energy changes at each time step
+        experienced by the battery
+
+        :return: a NumPy array containing the battery state of charge at each time step
+        :rtype: np.ndarray
+
+        """
+
+        stored_energy_array = np.full_like(cumulative_energy_array, fill_value=self.stored_energy)
+        stored_energy_array += cumulative_energy_array / 3600
+
+        energy_discharged_array = np.full_like(cumulative_energy_array, fill_value=self.max_energy_capacity) - stored_energy_array
+
+        discharge_capacity_array = self.calculate_discharge_capacity_from_energy(energy_discharged_array)
+
+        soc_array = self.calculate_soc_from_discharge_capacity(discharge_capacity_array)
+
+        return soc_array
+
+
+def calculate_voltage_from_discharge_capacity():
+    return Polynomial([117.6, -0.858896])  # -0.8589x + 117.6
+
+
+def calculate_energy_from_discharge_capacity():
+    return Polynomial([0, 117.6, -0.429448])  # -0.4294x^2 + 117.6x
+
+
+def calculate_soc_from_discharge_capacity(max_current_capacity):
+    return Polynomial([1, -1 / max_current_capacity])
+
+
+def calculate_discharge_capacity_from_soc(max_current_capacity):
+    return Polynomial([max_current_capacity, -max_current_capacity])
+
+
+def calculate_discharge_capacity_from_energy():
+    return lambda x: 136.92 - np.sqrt(18747.06027 - 2.32857 * x)

physics/models/battery/battery.rs

@@ -0,0 +1,102 @@
+use std::f64;
+use numpy::ndarray::{ArrayView1};
+
+fn get_lookup_index(soc: f64, quantization_step: f64, num_indices: usize, min_soc: f64) -> usize {
+    // Apply the same formula as in Python
+    let index = ((soc - min_soc) / quantization_step).floor() as usize;
+
+    // Clamp the index to be between 0 and num_indices - 1
+    index.min(num_indices - 1)  // equivalent to max(0, min(num_indices - 1, index))
+}
+
+/// Evaluate a polynomial given coefficients and an input value (x)
+fn evaluate_lookup(lookup: &[f64], quantization_step: f64, value: f64, min_soc: f64) -> f64 {
+    let index = get_lookup_index(value, quantization_step, lookup.len(), min_soc);
+    lookup[index]
+}
+
+/// Evolve the battery state for a single step
+fn battery_evolve(
+    current: f64,                  // Amperes
+    tick: f64,                     // Seconds
+    state_of_charge: f64,          // Dimensionless, 0 < SOC < 1
+    polarization_potential: f64,   // Volts
+    polarization_resistance: f64,  // Ohms
+    internal_resistance: f64,      // Ohms
+    open_circuit_voltage: f64,     // Volts
+    time_constant: f64,            // Seconds
+    nominal_charge_capacity: f64,  // Nominal charge capacity (Coulombs)
+) -> (f64, f64, f64) {
+    // Update state of charge and polarization potential
+    let new_state_of_charge: f64 = state_of_charge + (current * tick / nominal_charge_capacity);
+    let new_polarization_potential: f64 = f64::exp(-tick / time_constant) * polarization_potential
+        + current * polarization_resistance * (1.0 - f64::exp(-tick / time_constant));
+    let terminal_voltage: f64 = open_circuit_voltage + new_polarization_potential
+        + (current * internal_resistance); // Terminal voltage
+
+    (new_state_of_charge, new_polarization_potential, terminal_voltage)
+}
+
+// Update battery state, using either energy or current draw
+pub fn update_battery_state(
+    energy_or_current_array: ArrayView1<'_, f64>,  // Power (W*s) or current (Amperes)
+    tick: f64,                                     // Seconds
+    initial_state_of_charge: f64,                  // dimensionless, 0 < SOC < 1
+    initial_polarization_potential: f64,           // Volts
+    internal_resistance_lookup: ArrayView1<'_, f64>,// Coefficients for internal resistance
+    open_circuit_voltage_lookup: ArrayView1<'_, f64>, // Coefficients for open-circuit voltage
+    polarization_resistance_lookup: ArrayView1<'_, f64>, // Coefficients for polarization resistance
+    capacitance_lookup: ArrayView1<'_, f64>,        // Coefficients for polarization capacitance
+    nominal_charge_capacity: f64,                   // Coulombs
+    is_energy_input: bool,                          // Whether the input is power or current,
+    quantization_step: f64,                         // The quantization step size of SOC for lookup tables
+    min_soc: f64,
+
+) -> (Vec<f64>, Vec<f64>) {
+    let mut state_of_charge: f64 = initial_state_of_charge;
+    let mut polarization_potential: f64 = initial_polarization_potential;
+    let mut soc_array: Vec<f64> = Vec::with_capacity(energy_or_current_array.len());
+    let mut voltage_array: Vec<f64> = Vec::with_capacity(energy_or_current_array.len());
+
+    for &input in energy_or_current_array.iter() {
+        // Interpolate values from coefficient
+        let open_circuit_voltage = evaluate_lookup(open_circuit_voltage_lookup.as_slice().unwrap(), quantization_step, state_of_charge, min_soc);
+        let internal_resistance = evaluate_lookup(internal_resistance_lookup.as_slice().unwrap(), quantization_step, state_of_charge, min_soc);
+        let polarization_resistance = evaluate_lookup(polarization_resistance_lookup.as_slice().unwrap(), quantization_step, state_of_charge, min_soc);
+        let capacitance = evaluate_lookup(capacitance_lookup.as_slice().unwrap(), quantization_step, state_of_charge, min_soc);
+        let time_constant = polarization_resistance * capacitance;
+
+        // Calculate current from power or use the current directly
+        let current: f64 = if is_energy_input {
+            // Use the last voltage to calculate current, or an absurdly large number if it is the
+            // first, because we don't know voltage yet, so we will have a very small initial
+            // current, no matter what. We shouldn't be starting to simulate when the battery is
+            // in an active state anyway, so this should be an alright compromise.
+            input / (tick * voltage_array.last().unwrap_or(&10000.0)) // I = (E / dt) / V
+        } else {
+            input // Current is directly given in the current input array
+        };
+
+        let (new_state_of_charge, new_polarization_potential, terminal_voltage) = battery_evolve(
+            current,
+            tick,
+            state_of_charge,
+            polarization_potential,
+            polarization_resistance,
+            internal_resistance,
+            open_circuit_voltage,
+            time_constant,
+            nominal_charge_capacity,
+        );
+
+        // Update state for the next iteration
+        state_of_charge = new_state_of_charge;
+        polarization_potential = new_polarization_potential;
+
+        // Store results
+        soc_array.push(new_state_of_charge);
+        voltage_array.push(terminal_voltage);
+    }
+
+    (soc_array, voltage_array)
+}

physics/models/battery/battery_config.py

@@ -0,0 +1,107 @@
+import tomli as tomllib
+import pathlib
+from scipy import optimize
+import numpy as np
+from physics.models.battery import SOCDependent
+from typing import cast
+from numpy.typing import NDArray
+
+
+class BatteryModelConfig:
+    """
+    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].
+    """
+    def __init__(self, R_0_data, Soc_data, R_P_data, C_P_data, Uoc_data, Q_total):
+        # ----- Initialize Parameters -----
+        def quintic_polynomial(x, x0, x1, x2, x3, x4, x5, x6, x7):
+            return np.polyval(np.array([x0, x1, x2, x3, x4, x5, x6, x7]), x)
+
+        self._U_oc_coefficients, _ = optimize.curve_fit(quintic_polynomial, Soc_data, Uoc_data)
+        self._R_0_coefficients, _ = optimize.curve_fit(quintic_polynomial, Soc_data, R_0_data)
+        self._C_P_coefficients, _ = optimize.curve_fit(quintic_polynomial, Soc_data, C_P_data)
+        self._R_P_coefficients, _ = optimize.curve_fit(quintic_polynomial, Soc_data, R_P_data)
+
+        # Casts are just for the type-checker to know that np.polyval will work as SOCDependent
+        self._U_oc: SOCDependent = cast(SOCDependent, lambda soc: np.polyval(self._U_oc_coefficients, soc))  # V
+        self._R_0: SOCDependent = cast(SOCDependent, lambda soc: np.polyval(self._R_0_coefficients, soc))    # Ohms
+        self._R_P: SOCDependent = cast(SOCDependent, lambda soc: np.polyval(self._R_P_coefficients, soc))    # Ohms
+        self._C_P: SOCDependent = cast(SOCDependent, lambda soc: np.polyval(self._C_P_coefficients, soc))    # Farads
+
+        self._Q_total = Q_total
+
+    @property
+    def get_Uoc(self) -> SOCDependent:
+        return self._U_oc
+
+    @property
+    def get_R_0(self) -> SOCDependent:
+        return self._R_0
+
+    @property
+    def get_R_P(self) -> SOCDependent:
+        return self._R_P
+
+    @property
+    def get_C_P(self) -> SOCDependent:
+        return self._C_P
+
+    @property
+    def Q_total(self) -> float:
+        return self._Q_total
+
+
+class KalmanFilterConfig:
+    def __init__(
+            self,
+            battery_model_config: BatteryModelConfig,
+            process_noise_matrix: NDArray,
+            state_covariance_matrix: NDArray,
+            measurement_noise_vector: NDArray
+    ):
+        self._battery_model_config = battery_model_config
+        self._process_noise_matrix = process_noise_matrix
+        self._state_covariance_matrix = state_covariance_matrix
+        self._measurement_noise_vector = measurement_noise_vector
+
+    @property
+    def battery_model_config(self) -> BatteryModelConfig:
+        """
+        Configuration of the underlying `EquivalentCircuitModel`.
+        """
+        return self._battery_model_config
+
+    @property
+    def process_noise_matrix(self) -> NDArray[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.
+        """
+        return self._process_noise_matrix
+
+    @property
+    def state_covariance_matrix(self) -> NDArray[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.
+        """
+        return self._state_covariance_matrix
+
+    @property
+    def measurement_noise_vector(self) -> NDArray[float]:
+        """
+        A 1x1 vector containing the noise expected in the terminal voltage measurement.
+        """
+        return self._measurement_noise_vector
+
+
+def load_battery_config(absolute_path: str | pathlib.Path) -> BatteryModelConfig:
+    # Build the full path to the config file
+    full_path = pathlib.Path(absolute_path)
+    with open(full_path, 'rb') as f:
+        data = tomllib.load(f)
+    return BatteryModelConfig(**data)

physics/models/battery/battery_config.toml

@@ -0,0 +1,6 @@
+R_0_data = [0.17953765302439662, 0.15580951404728172, 0.14176929930784543, 0.11043950958574644, 0.13930042505446938, 0.1552885289394773, 0.044070982259896085, 0.2208806896239539, 0.15116267852908616, 0.6553961767519164]
+R_P_data = [0.04153180244191346, 0.10674683402208612, 0.061085424180509884, 0.0781407642082238, 0.05537901113775878, 0.09732054673529467, 0.07662520885708152, 0.09799857401036915, 0.42622740149661487, 0.2718418915736874]
+C_P_data = [14824.398495212006, 1587.5971318119796, 341.1064063616048, 1243.182413110655, 619.5791066439332, 2252.7885790042164, 954.5884882581622, 515.7219779825028, 431.10892633451135, 195.14394897766627]
+Uoc_data = [131.88002282453857, 129.4574321366064, 125.5750277614186, 121.99586066440303, 118.69893412178982, 115.71854177322408, 111.99025635444923, 108.29354777060836, 98.23397960300946, 95.24125831782388]
+Q_total = 151000.0
+Soc_data = [1.0000113624123392, 0.8815263722745977, 0.7671918526292492, 0.6206071038045673, 0.4911613638651783, 0.3606311083423134, 0.23687514228021178, 0.12073345089992571, 0.01456057818183809, 0.0070648691224265425]

physics/models/battery/battery_model.py

@@ -0,0 +1,226 @@
+import numpy as np
+import physics_rs
+from typing import Callable, TypeAlias, Protocol, runtime_checkable, Optional, cast
+from numpy.typing import NDArray
+
+
+SOCDependent: TypeAlias = Callable[[float | NDArray[float]], float | NDArray[float]]
+
+
+@runtime_checkable
+class EquivalentCircuitModelConfig(Protocol):
+    """
+    A specification for a configuration object which contains the requisite data to specify
+    a `EquivalentCircuitBatteryModel`.
+    """
+
+    @property
+    def get_Uoc(self) -> SOCDependent:
+        """
+        A map from an SOC to Uoc (open-circuit voltage).
+        Should be compatible with non-vectorized and vectorized calls: float -> float or NDArray -> NDArray
+        """
+        ...
+
+    @property
+    def get_R_0(self) -> SOCDependent:
+        """
+        A map from an SOC to R_0 (internal resistance).
+        Should be compatible with non-vectorized and vectorized calls: float -> float or NDArray -> NDArray
+        """
+        ...
+
+    @property
+    def get_R_P(self) -> SOCDependent:
+        """
+        A map from an SOC to R_P (polarization resistance).
+        Should be compatible with non-vectorized and vectorized calls: float -> float or NDArray -> NDArray
+        """
+        ...
+
+    @property
+    def get_C_P(self) -> SOCDependent:
+        """
+        A map from an SOC to C_P (polarization capacitance).
+        Should be compatible with non-vectorized and vectorized calls: float -> float or NDArray -> NDArray
+        """
+        ...
+
+    @property
+    def Q_total(self) -> float:
+        """
+        The total charge capacity of the battery pack, in Coulombs.
+        """
+        ...
+
+
+class EquivalentCircuitBatteryModel:
+    """
+    A first-order Thevenin equivalent model of a lithium-ion battery pack
+    """
+
+    def __init__(self, battery_config: EquivalentCircuitModelConfig, state_of_charge: float = 1.0):
+        """
+        Constructor for the EquivalentCircuitBatteryModel class.
+
+        :param BatteryModelConfig battery_config: Configuration object containing the battery's parameters and data.
+        :param float state_of_charge: Initial state of charge of the battery (default is 1.0, fully charged).
+        """
+
+        # We initialize the active components as uncharged
+        self._U_P = 0.0  # V
+        self._U_L = 0.0  # V
+        self._state_of_charge = state_of_charge
+        self._nominal_charge_capacity = battery_config.Q_total
+
+        # Now, the config contains methods to map SOC to each respective parameter.
+        # We can't efficiently pass these functions to compiled libraries.
+        # Instead, we will pre-compute the parameters as a function of SOC
+        # to create fine lookup tables as a portable substitute for runtime computation.
+
+        # Things are going to get a tiny bit messy here, so we will go through this carefully.
+        # I'll write what each resulting map achieves below each code block.
+
+        # Firstly, we're going to discretize SOC by making a range of SOC values in the range [-0.05, 1.1], because
+        # sometimes we are marginally outside the range (0.0, 1.0].
+        # We will quantize at about 4 digits of precision, so ~10,000 values
+        self._min_soc = -0.05
+        self._max_soc = 1.1
+        self._num_indices = int((self._max_soc - self._min_soc) * 10000)
+        SOC_values = np.linspace(self._min_soc, self._max_soc, self._num_indices, dtype=float)
+        # maps: (discrete index) -> (SOC)
+
+        # Now, we're going to create a map from an arbitrary SOC, to the index of the closest SOC
+        # value in our quantized SOC range (`SOC_values`)
+        self._quantization_step: float = (self._max_soc - self._min_soc) / self._num_indices
+        self._soc_to_index = lambda _soc: int(
+            max(0, min(self._num_indices - 1, (_soc - self._min_soc) // self._quantization_step))
+        )
+        # maps: (SOC) -> (discrete index)
+
+        # Now, calculate the value of each parameter for each discrete SOC value using the injected `get_` functions
+        self._U_oc_lookup: NDArray[float] = battery_config.get_Uoc(SOC_values)
+        self._R_0_lookup: NDArray[float] = battery_config.get_R_0(SOC_values)
+        self._R_P_lookup: NDArray[float] = battery_config.get_R_P(SOC_values)
+        self._C_P_lookup: NDArray[float] = battery_config.get_C_P(SOC_values)
+        # maps: (discrete index) -> (parameter)
+
+        # Finally, combine the above maps to create a map from an arbitrary SOC to each battery parameter, using
+        # the discrete lookup tables
+        # These `cast` calls just promise to the type-checker that these will map floats to floats
+        self._U_oc = cast(Callable[[float], float], lambda SOC: self._U_oc_lookup[self._soc_to_index(SOC)])
+        self._R_0 = cast(Callable[[float], float], lambda SOC: self._R_0_lookup[self._soc_to_index(SOC)])
+        self._R_P = cast(Callable[[float], float], lambda SOC: self._R_P_lookup[self._soc_to_index(SOC)])
+        self._C_P = cast(Callable[[float], float], lambda SOC: self._C_P_lookup[self._soc_to_index(SOC)])
+        # maps: ((SOC) -> (discrete index)) -> ((discrete index) -> (parameter))  |==>  (SOC) -> (parameter)
+
+        self._tau: Callable[[float], float] = lambda soc: self._R_P(soc) * self._C_P(soc)  # Characteristic Time in s
+
+    def update_array(
+            self,
+            tick: float,
+            delta_energy_array: Optional[NDArray] = None,
+            current_array: Optional[NDArray] = None,
+            use_compiled: bool = True
+    ) -> tuple[NDArray, NDArray]:
+        """
+        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.
+
+        :param NDArray delta_energy_array: Array of energy changes (J) at each time step.
+        :param float tick: Time interval for each step (seconds).
+        :param NDArray current_array: Array of current draw (positive sign convention) in Amperes at each time step.
+        :param bool use_compiled: If `True`, use compiled binaries for calculations.
+            Disable for better debugging.
+        :return: 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.
+        :rtype: tuple[NDArray, NDArray]
+        """
+        if (delta_energy_array is None) == (current_array is None):  # Enforce that only one should be provided
+            raise ValueError("Exactly one of `delta_energy_array` or `current_array` "
+                             "must be provided, not both or neither.")
+
+        energy_or_current = delta_energy_array if delta_energy_array is not None else current_array
+
+        if use_compiled:
+            return physics_rs.update_battery_state(
+                energy_or_current,
+                tick,
+                self._state_of_charge,
+                self._U_P,
+                self._R_0_lookup,
+                self._U_oc_lookup,
+                self._R_P_lookup,
+                self._C_P_lookup,
+                self._nominal_charge_capacity,
+                current_array is None,  # Pass to the library if `energy_or_current` is current or power,
+                self._quantization_step,
+                self._min_soc
+            )
+
+        else:
+            return self._update_array_py(energy_or_current, tick, current_array is None)
+
+    def _update_array_py(self, energy_or_current, tick, is_power):
+        """
+        Perform energy calculations using Python (fallback method if Rust is disabled).
+
+        :param NDArray energy_or_current: Array of energy changes (J) at each time step.
+        :param float tick: Time interval for each step (seconds).
+
+        :return: A tuple containing arrays for state-of-charge and voltage.
+        """
+        soc = np.empty_like(energy_or_current, dtype=float)
+        voltage = np.empty_like(energy_or_current, dtype=float)
+
+        for (i, value) in enumerate(energy_or_current):
+            if is_power:
+                # Use the last voltage to calculate current, or an absurdly large number if it is the first,
+                # because we don't know voltage yet.
+                # We will have a very small initial current, no matter what.
+                # We shouldn't be starting to simulate when the battery is in an active state anyway,
+                # so this should be an alright compromise.
+                last_terminal_voltage = voltage[i - 1] if i - 1 >= 0 else 10000
+
+                current: float = value / (tick * last_terminal_voltage)
+            else:
+                current = value
+
+            self._evolve(current, tick)
+            soc[i] = self._state_of_charge
+            voltage[i] = self._U_L
+
+        return soc, voltage
+
+    def _evolve(self, current: float, tick: float) -> None:
+        """
+        Update the battery state given the current and time elapsed.
+
+        :param float current: Current applied to the battery (A).
+            Positive for charging, negative for discharging.
+        :param float tick: Time interval over which the power is applied (seconds).
+        """
+        soc = self._state_of_charge  # State of Charge (dimensionless, 0 < soc < 1)
+        U_P = self._U_P  # Polarization Potential (V)
+        R_P = self._R_P(soc)  # Polarization Resistance (Ohms)
+        U_oc = self._U_oc(soc)  # Open-Circuit Potential (V)
+        R_0 = self._R_0(soc)  # Ohmic Resistance (Ohms)
+        Q = self._nominal_charge_capacity  # Nominal Charge Capacity (C)
+        tau = self._tau(soc)  # Time constant (s)
+
+        new_soc = soc + (current * tick / Q)
+        new_U_P = np.exp(-tick / tau) * U_P + current * R_P * (1 - np.exp(-tick / tau))
+
+        self._state_of_charge = new_soc
+        self._U_P = new_U_P
+        self._U_L = U_oc + new_U_P + (current * R_0)