ubc-solar-physics 1.0.5__cp313-cp313-macosx_11_0_arm64.whl → 1.7.3__cp313-cp313-macosx_11_0_arm64.whl

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)

physics/models/battery/kalman_filter.py

@@ -0,0 +1,223 @@
+import numpy as np
+from filterpy.kalman import ExtendedKalmanFilter
+from typing import Protocol, runtime_checkable, cast, Callable
+from physics.models.battery import EquivalentCircuitModelConfig
+from numpy.typing import NDArray
+
+
+@runtime_checkable
+class FilteredBatteryModelConfig(Protocol):
+    """
+    A specification for a configuration object which contains the requisite data to specify
+    a `FilteredBatteryModel`.
+    """
+    @property
+    def battery_model_config(self) -> EquivalentCircuitModelConfig:
+        """
+        Configuration of the underlying `EquivalentCircuitModel`.
+        """
+        ...
+
+    @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.
+        """
+        ...
+
+    @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.
+        """
+        ...
+
+    @property
+    def measurement_noise_vector(self) -> NDArray[float]:
+        """
+        A 1x1 vector containing the noise expected in the terminal voltage measurement.
+        """
+        ...
+
+
+class FilteredBatteryModel:
+    """
+    `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.
+    """
+    def __init__(
+            self,
+            battery_config: FilteredBatteryModelConfig,
+            initial_SOC: float = 1.0,
+            initial_Uc: float = 0.0,
+            alpha: float = 0.9
+    ):
+        """
+        :param FilteredBatteryModelConfig battery_config: Contains Kalman filter state estimation configuration and
+            underlying equivalent circuit model configuration.
+        :param float initial_SOC: Initial SOC of the battery, in the range (0, 1].
+        :param float initial_Uc: Initial polarization voltage of the battery in Volts.
+        """
+        # Initial state
+        assert 0.0 <= initial_SOC <= 1.1, "`initial_SOC` must be in (0, 1.1]!"
+
+        self._SOC = initial_SOC     # State of Charge
+        self._Uc = initial_Uc       # Polarization Voltage
+
+        # Load Config data
+        self._Q_total = battery_config.battery_model_config.Q_total
+
+        # These `cast` calls just promise to the type-checker that these will map floats to floats
+        self._U_oc = cast(Callable[[float], float], battery_config.battery_model_config.get_Uoc)
+        self._R_0 = cast(Callable[[float], float], battery_config.battery_model_config.get_R_0)
+        self._R_P = cast(Callable[[float], float], battery_config.battery_model_config.get_R_P)
+        self._C_P = cast(Callable[[float], float], battery_config.battery_model_config.get_C_P)
+
+        self._tau: Callable[[float], float] = lambda soc: self._R_P(soc) * self._C_P(soc)  # Characteristic Time in s
+
+        def central_difference_derivative(func, value, h=1e-6):
+            """
+            Compute the derivative of an arbitrary function `func` at `SOC` using central difference.
+
+            :param func: The function to differentiate.
+            :param value: The point at which to compute the derivative.
+            :param h: Step size for the finite difference.
+            :return: The derivative of the function at `SOC`.
+            """
+            return (func(value + h) - func(value - h)) / (2 * h)
+
+        self._dUoc_dSOC = lambda soc: central_difference_derivative(self._U_oc, np.minimum(1.0, soc))  # dUOC wrt to SOC
+        self._dR0_dSOC = lambda soc: central_difference_derivative(self._R_0, np.minimum(1.0, soc))    # dR0 wrt to SOC
+
+        # Initializing the EKF object
+        self._ekf = ExtendedKalmanFilter(dim_x=2, dim_z=1)
+
+        # State Vector
+        self._ekf.x = np.array([
+            self._SOC,
+            self._Uc]
+        )
+
+        self._ekf.P = battery_config.state_covariance_matrix
+        self._ekf.Q = battery_config.process_noise_matrix
+        self._ekf.R = battery_config.measurement_noise_vector
+
+        assert 0 <= alpha <= 1, "`alpha` should be between 0 and 1!"
+        self._alpha = alpha
+
+        self._filtered_I = 0
+        self._predicted_measurement = 0
+
+    @property
+    def SOC(self) -> float:
+        """
+        Return the current SOC of the battery.
+
+        :return: The current state of charge.
+        """
+        return self._SOC
+
+    @property
+    def Uc(self) -> float:
+        """
+        Return the polarization voltage of the battery.
+
+        :return: The current polarization voltage.
+        """
+        return self._Uc
+
+    @property
+    def Ut(self) -> float:
+        """
+        Return the predicted terminal voltage for the last prediction step.
+
+        :return: The predicted terminal voltage.
+        """
+        return self._predicted_measurement
+
+    def update_filter(self, 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.
+
+        :param float measured_Ut: The actual voltage across the terminals of the battery.
+        :param float current: The current being sourced by the battery.
+        """
+        # Simple low-pass filter to current
+        self._filtered_I = self._alpha * self._filtered_I + (1 - self._alpha) * current
+
+        self._ekf.update(z=measured_Ut, HJacobian=self._measurement_jacobian, Hx=self._measurement_function)
+
+        self._SOC, self._Uc = self._ekf.x
+        self._SOC = np.clip(self._SOC, 0.0, 1.1)
+
+    def predict_state(self, 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.
+
+        :param float current: The current being sourced by the battery.
+            Sign convention is that positive indicates current being drawn.
+        :param float time_step: Time elapsed between this prediction and the last updated state of the filter (seconds).
+        """
+        # Control matrix B (for input current I_k)
+        self._ekf.B = np.array([
+            -time_step / self._Q_total,
+            self._R_P(self._SOC) * (1 - np.exp(-time_step / (self._tau(self._SOC)))),
+        ])
+        self._ekf.F = self._state_jacobian(time_step)
+
+        self._ekf.predict(u=current)
+        self._SOC, self._Uc = self._ekf.x
+
+    def predict_then_update(self, 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.
+
+        :param float measured_Ut: The actual voltage across the terminals of the battery.
+        :param float current: The current being sourced by the battery. Positive indicates current being drawn.
+        :param float time_step: Time elapsed between this prediction and the last updated state of the filter (seconds).
+        """
+        self.predict_state(current, time_step)
+        self.update_filter(measured_Ut, current)
+
+    def _state_jacobian(self, time_step):
+        """
+        Return the state Jacobian matrix for the current time step.
+
+        :param float time_step: Time elapsed between this prediction and the last updated state of the filter (seconds).
+        :return: The state Jacobian matrix.
+        :rtype: np.ndarray
+        """
+        return np.array([[1, 0], [0, np.exp(-time_step / self._tau(self._SOC))]])
+
+    def _measurement_jacobian(self, x):
+        """
+        Return the measurement Jacobian matrix for the current state vector.
+
+        :param list[float, float] x: The state vector [SOC, Uc].
+        :return: The measurement Jacobian matrix.
+        :rtype: np.ndarray
+        """
+        SOC = x[0]
+        dUoc_dSOC = self._dUoc_dSOC(SOC)
+        dR0_dSOC = self._dR0_dSOC(SOC)
+
+        return np.array([[dUoc_dSOC - dR0_dSOC * self._filtered_I, -1]])
+
+    def _measurement_function(self, x) -> float:
+        """
+        Return the measurement function relating terminal voltage to SOC and polarization voltage.
+
+        :param list[float, float] x: The state vector [SOC, Uc].
+        :return: The predicted terminal voltage.
+        """
+        SOC, Uc = x
+        Uoc = self._U_oc(SOC)
+        R0 = self._R_0(SOC)
+        self._predicted_measurement = Uoc - Uc - R0 * self._filtered_I
+
+        return self._predicted_measurement

physics/models/battery.rs

@@ -1 +1 @@
-mod battery;
+pub mod battery;

physics/models/motor/__init__.py

@@ -1,7 +1,9 @@
 from .base_motor import BaseMotor
 from .basic_motor import BasicMotor
+from .advanced_motor import AdvancedMotor
 
 __all__ = [
     "BaseMotor",
-    "BasicMotor"
+    "BasicMotor",
+    "AdvancedMotor",
 ]