ubc-solar-physics 1.6.0__cp312-cp312-win_amd64.whl → 1.7.0__cp312-cp312-win_amd64.whl

physics/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.6.0'
-__version_tuple__ = version_tuple = (1, 6, 0)
+__version__ = version = '1.7.0'
+__version_tuple__ = version_tuple = (1, 7, 0)

physics/environment/gis/gis.py

@@ -1,6 +1,6 @@
 import logging
 import math
-import core
+import physics_rs
 import numpy as np
 import sys
 
@@ -81,7 +81,7 @@ class GIS(BaseGIS):
         :rtype: np.ndarray
 
         """
-        return core.closest_gis_indices_loop(distances, self.path_distances)
+        return physics_rs.closest_gis_indices_loop(distances, self.path_distances)
 
     def calculate_driving_speeds(
             self,
@@ -108,7 +108,7 @@ class GIS(BaseGIS):
         :return: A simulation-time array of driving speeds in m/s, or an error if there weren't enough
             laps provided to fill the entire simulation time.
         """
-        return core.get_driving_speeds(
+        return physics_rs.get_driving_speeds(
             np.array(average_lap_speeds).astype(np.float64),
             simulation_dt,
             np.array(driving_allowed).astype(bool),
@@ -120,7 +120,7 @@ class GIS(BaseGIS):
     def _python_calculate_closest_gis_indices(distances, path_distances):
         """
 
-        Python implementation of rust core.closest_gis_indices_loop. See parent function for documentation details.
+        Python implementation of use_compiled core.closest_gis_indices_loop. See parent function for documentation details.
 
         """
 

physics/environment/meteorology/clouded_meteorology.py

@@ -2,7 +2,7 @@ from physics.environment.meteorology.base_meteorology import BaseMeteorology
 from physics.environment.gis.gis import calculate_path_distances
 import numpy as np
 from numba import jit
-import core
+import physics_rs
 from typing import Optional
 import datetime
 
@@ -70,7 +70,7 @@ class CloudedMeteorology(BaseMeteorology):
         # contains the average distance between two consecutive elements in the cumulative_weather_path_distances array
         average_distances = np.abs(np.diff(cumulative_weather_path_distances) / 2)
 
-        return core.closest_weather_indices_loop(cumulative_distances, average_distances)
+        return physics_rs.closest_weather_indices_loop(cumulative_distances, average_distances)
 
     def temporally_localize(self, unix_timestamps, start_time, tick) -> None:
         """
@@ -96,7 +96,7 @@ class CloudedMeteorology(BaseMeteorology):
         :rtype: np.ndarray
 
         """
-        weather_data = core.weather_in_time(unix_timestamps.astype(np.int64), self._weather_indices.astype(np.int64), self._weather_forecast, 4)
+        weather_data = physics_rs.weather_in_time(unix_timestamps.astype(np.int64), self._weather_indices.astype(np.int64), self._weather_forecast, 4)
         # roll_by_tick = int(3600 / tick) * (24 + start_hour - hour_from_unix_timestamp(weather_data[0, 2]))
         # weather_data = np.roll(weather_data, -roll_by_tick, 0)
 
@@ -124,7 +124,7 @@ class CloudedMeteorology(BaseMeteorology):
         :rtype: np.ndarray
 
         """
-        day_of_year, local_time = core.calculate_array_ghi_times(local_times)
+        day_of_year, local_time = physics_rs.calculate_array_ghi_times(local_times)
 
         ghi = self._calculate_GHI(coords[:, 0], coords[:, 1], time_zones,
                                   day_of_year, local_time, elevations, self._cloud_cover)

physics/environment/meteorology/irradiant_meteorology.py

@@ -1,7 +1,7 @@
 from physics.environment.meteorology.base_meteorology import BaseMeteorology
 from physics.environment.gis.gis import calculate_path_distances
 import numpy as np
-import core
+import physics_rs
 from typing import Optional
 
 
@@ -11,6 +11,7 @@ class IrradiantMeteorology(BaseMeteorology):
     solar irradiance data, but not cloud cover.
 
     """
+
     def __init__(self, race, weather_forecasts):
         self._race = race
         self._raw_weather_data = weather_forecasts
@@ -53,7 +54,7 @@ class IrradiantMeteorology(BaseMeteorology):
         # contains the average distance between two consecutive elements in the cumulative_weather_path_distances array
         average_distances = np.abs(np.diff(cumulative_weather_path_distances) / 2)
 
-        self._weather_indices = core.closest_weather_indices_loop(cumulative_distances, average_distances)
+        self._weather_indices = physics_rs.closest_weather_indices_loop(cumulative_distances, average_distances)
 
     def temporally_localize(self, unix_timestamps, start_time, tick) -> None:
         """
@@ -76,8 +77,9 @@ class IrradiantMeteorology(BaseMeteorology):
         :returns: a SolcastEnvironment object with time_dt, latitude, longitude, wind_speed, wind_direction, and ghi.
         :rtype: SolcastEnvironment
         """
-        forecasts_array = core.weather_in_time(unix_timestamps.astype(np.int64), self._weather_indices.astype(np.int64),
-                                               self._raw_weather_data, 0)
+        forecasts_array = physics_rs.weather_in_time(unix_timestamps.astype(np.int64),
+                                                     self._weather_indices.astype(np.int64),
+                                                     self._raw_weather_data, 0)
 
         self._time_dt = forecasts_array[:, 0]
         self._latitude = forecasts_array[:, 1]
@@ -103,5 +105,3 @@ class IrradiantMeteorology(BaseMeteorology):
 
         """
         return self.solar_irradiance
-
-

physics/lib.rs

@@ -1,5 +1,5 @@
 use numpy::ndarray::ArrayViewD;
-use numpy::{PyArray, PyArrayDyn, PyReadwriteArrayDyn, PyReadonlyArray1, PyArray1};
+use numpy::{PyArray, PyArrayDyn, PyReadwriteArrayDyn, PyReadwriteArray1, PyReadonlyArray1, PyArray1};
 use pyo3::prelude::*;
 use pyo3::types::PyModule;
 
@@ -7,7 +7,7 @@ pub mod environment;
 pub mod models;
 use crate::environment::gis::gis::{rust_closest_gis_indices_loop, get_driving_speeds};
 use crate::environment::meteorology::meteorology::{rust_calculate_array_ghi_times, rust_closest_weather_indices_loop, rust_weather_in_time};
-use crate::models::battery::battery::update_battery_array;
+use crate::models::battery::battery::update_battery_state;
 
 fn constrain_speeds(speed_limits: ArrayViewD<f64>,  speeds: ArrayViewD<f64>, tick: i32) -> Vec<f64> {
     let mut distance: f64 = 0.0;
@@ -25,7 +25,7 @@ fn constrain_speeds(speed_limits: ArrayViewD<f64>,  speeds: ArrayViewD<f64>, tic
 
 /// A Python module implemented in Rust. The name of this function is the Rust module name!
 #[pymodule]
-#[pyo3(name = "core")]
+#[pyo3(name = "physics_rs")]
 fn rust_simulation(_py: Python, m: &PyModule) -> PyResult<()> {
     #[pyfn(m)]
         #[pyo3(name = "constrain_speeds")]
@@ -95,35 +95,43 @@ fn rust_simulation(_py: Python, m: &PyModule) -> PyResult<()> {
     }
 
     #[pyfn(m)]
-    #[pyo3(name = "update_battery_array")]
-    fn update_battery_array_py<'py>(
+    #[pyo3(name = "update_battery_state")]
+    fn update_battery_state_py<'py>(
         py: Python<'py>,
-        python_delta_energy_array: PyReadwriteArrayDyn<'py, f64>,
+        python_energy_or_current_array: PyReadwriteArray1<'py, f64>,
         time_step: f64,
         initial_state_of_charge: f64,
         initial_polarization_potential: f64,
-        polarization_resistance: f64,
-        python_internal_resistance_coeffs: PyReadwriteArrayDyn<'py, f64>,
-        python_open_circuit_voltage_coeffs: PyReadwriteArrayDyn<'py, f64>,
-        time_constant: f64,
+        python_internal_resistance_lookup: PyReadwriteArray1<'py, f64>,
+        python_open_circuit_voltage_lookup: PyReadwriteArray1<'py, f64>,
+        python_polarization_resistance_lookup: PyReadwriteArray1<'py, f64>,
+        python_polarization_capacitance_lookup: PyReadwriteArray1<'py, f64>,
         nominal_charge_capacity: f64,
-    ) -> (&'py PyArrayDyn<f64>, &'py PyArrayDyn<f64>) {
-        let delta_energy_array = python_delta_energy_array.as_array();
-        let internal_resistance_coeffs = python_internal_resistance_coeffs.as_array();
-        let open_circuit_voltage_coeffs = python_open_circuit_voltage_coeffs.as_array();
-        let (soc_array, voltage_array): (Vec<f64>, Vec<f64>) = update_battery_array(
-            delta_energy_array,
+        is_power: bool,
+        quantization_step: f64,
+        min_soc: f64,
+    ) -> (&'py PyArray1<f64>, &'py PyArray1<f64>) {
+        let energy_or_current_array = python_energy_or_current_array.as_array();
+        let internal_resistance_lookup = python_internal_resistance_lookup.as_array();
+        let open_circuit_voltage_lookup = python_open_circuit_voltage_lookup.as_array();
+        let polarization_resistance_lookup = python_polarization_resistance_lookup.as_array();
+        let polarization_capacitance_lookup = python_polarization_capacitance_lookup.as_array();
+        let (soc_array, voltage_array): (Vec<f64>, Vec<f64>) = update_battery_state(
+            energy_or_current_array,
             time_step,
             initial_state_of_charge,
             initial_polarization_potential,
-            polarization_resistance,
-            internal_resistance_coeffs,
-            open_circuit_voltage_coeffs,
-            time_constant,
+            internal_resistance_lookup,
+            open_circuit_voltage_lookup,
+            polarization_resistance_lookup,
+            polarization_capacitance_lookup,
             nominal_charge_capacity,
+            is_power,
+            quantization_step,
+            min_soc
         );
-        let py_soc_array = PyArray::from_vec(py, soc_array).to_dyn();
-        let py_voltage_array = PyArray::from_vec(py, voltage_array).to_dyn();
+        let py_soc_array = PyArray::from_vec(py, soc_array);
+        let py_voltage_array = PyArray::from_vec(py, voltage_array);
         (py_soc_array, py_voltage_array)
     }
 

physics/models/battery/__init__.py

@@ -1,14 +1,18 @@
 from .base_battery import BaseBattery
 from .basic_battery import BasicBattery
-from .battery_model import BatteryModel
-from .kalman_filter import EKF_SOC
-from .battery_config import BatteryModelConfig, load_battery_config
+from .battery_model import EquivalentCircuitBatteryModel, EquivalentCircuitModelConfig, SOCDependent
+from .kalman_filter import FilteredBatteryModel, FilteredBatteryModelConfig
+from .battery_config import BatteryModelConfig, load_battery_config, KalmanFilterConfig
 
 __all__ = [
     "BaseBattery",
     "BasicBattery",
-    "BatteryModel",
-    "EKF_SOC",
+    "EquivalentCircuitBatteryModel",
+    "FilteredBatteryModel",
     "BatteryModelConfig",
-    "load_battery_config"
+    "load_battery_config",
+    "EquivalentCircuitModelConfig",
+    "FilteredBatteryModelConfig",
+    "KalmanFilterConfig",
+    "SOCDependent"
 ]

physics/models/battery/battery.rs

@@ -1,14 +1,23 @@
 use std::f64;
-use numpy::ndarray::ArrayViewD;
+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_polynomial(coefficients: &[f64], x: f64) -> f64 {
-    coefficients.iter().fold(0.0, |acc, &coeff| acc * x + coeff)
+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(
-    power: f64,                    // Watts
+    current: f64,                  // Amperes
     tick: f64,                     // Seconds
     state_of_charge: f64,          // Dimensionless, 0 < SOC < 1
     polarization_potential: f64,   // Volts
@@ -18,9 +27,6 @@ fn battery_evolve(
     time_constant: f64,            // Seconds
     nominal_charge_capacity: f64,  // Nominal charge capacity (Coulombs)
 ) -> (f64, f64, f64) {
-    // Compute current (I) based on power input/output
-    let current: f64 = power / (open_circuit_voltage + polarization_potential + internal_resistance);
-
     // 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
@@ -31,29 +37,48 @@ fn battery_evolve(
     (new_state_of_charge, new_polarization_potential, terminal_voltage)
 }
 
-pub fn update_battery_array(
-    delta_energy_array: ArrayViewD<'_, f64>,            // W*s
-    tick: f64,                                          // Seconds
-    initial_state_of_charge: f64,                       // dimensionless, 0 < SOC < 1
-    initial_polarization_potential: f64,                // Volts
-    polarization_resistance: f64,                       // Ohms
-    internal_resistance_coeffs: ArrayViewD<'_, f64>,    // Coefficients for internal resistance
-    open_circuit_voltage_coeffs: ArrayViewD<'_, f64>,   // Coefficients for open-circuit voltage
-    time_constant: f64,                                 // Seconds 
-    nominal_charge_capacity: f64,                       // Coulombs
+// 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 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(delta_energy_array.len());
-    let mut voltage_array: Vec<f64> = Vec::with_capacity(delta_energy_array.len());
+    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 &power in delta_energy_array.iter() {
+    for &input in energy_or_current_array.iter() {
         // Interpolate values from coefficient
-        let open_circuit_voltage: f64 = evaluate_polynomial(open_circuit_voltage_coeffs.as_slice().unwrap(), state_of_charge);
-        let internal_resistance: f64 = evaluate_polynomial(internal_resistance_coeffs.as_slice().unwrap(), state_of_charge);
+        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(
-            power,
+            current,
             tick,
             state_of_charge,
             polarization_potential,
@@ -75,4 +100,3 @@ pub fn update_battery_array(
 
     (soc_array, voltage_array)
 }
-

physics/models/battery/battery_config.py

@@ -1,22 +1,107 @@
-import tomli
-from pydantic import BaseModel
-from typing import List
-import os
+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(BaseModel):
-    R_0_data: List[float]
-    R_P: float
-    C_P: float
-    Q_total: float
-    SOC_data: List[float]
-    Uoc_data: List[float]
-    max_current_capacity: float
-    max_energy_capacity: float
-
-def load_battery_config(absolute_path: str) -> BatteryModelConfig:
+
+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 = tomli.load(f)
-    return BatteryModelConfig.model_validate(data)
+        data = tomllib.load(f)
+    return BatteryModelConfig(**data)

physics/models/battery/battery_config.toml

@@ -1,8 +1,6 @@
-R_0_data = [0.002564, 0.002541, 0.002541, 0.002558, 0.002549, 0.002574, 0.002596, 0.002626, 0.002676, 0.002789]
-R_P = 0.000530
-C_P = 14646         
-Q_total = 259200
-SOC_data = [0.0752, 0.1705, 0.2677, 0.366, 0.4654, 0.5666, 0.6701, 0.7767, 0.8865, 1.0]
-Uoc_data = [3.481, 3.557, 3.597, 3.623, 3.660, 3.750, 3.846, 3.946, 4.056, 4.183]
-max_current_capacity = 40
-max_energy_capacity = 500
+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]