ubc-solar-physics 1.0.3__cp39-cp39-win32.whl

physics/models/battery/basic_battery.py

@@ -0,0 +1,141 @@
+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.rs

@@ -0,0 +1 @@
+mod battery;

physics/models/constants.py

@@ -0,0 +1,23 @@
+# Radius of the Earth (m)
+EARTH_RADIUS = 6371009
+
+# Acceleration caused by gravity (m/s^2)
+ACCELERATION_G = 9.81
+
+# Density of Air at 15C and 101kPa (kg/m^3)
+AIR_DENSITY = 1.225
+
+# Maximum number of waypoints that can be given to generate route data
+MAX_WAYPOINTS = 10
+
+# Solar Irradiance (W/m^2)
+SOLAR_IRRADIANCE = 1353
+
+# As we currently have a limited number of API calls(60) every minute with the
+# current Weather API, we must shrink the dataset significantly. As the
+# OpenWeatherAPI models have a resolution of between 2.5 - 70 km, we will
+# go for a resolution of 25km. Assuming we travel at 100km/h for 12 hours,
+# 1200 kilometres/25 = 48 API calls
+# As the Google Maps API has a resolution of around 40m between points,
+# for ASC, we must cull at 625:1 (because 25,000m / 40m = 625)
+REDUCTION_FACTOR = 625

physics/models/lvs/__init__.py

@@ -0,0 +1,7 @@
+from .base_lvs import BaseLVS
+from .basic_lvs import BasicLVS
+
+__all__ = [
+    "BaseLVS",
+    "BasicLVS"
+]

physics/models/lvs/base_lvs.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+
+class BaseLVS(ABC):
+    def __init__(self, consumed_energy):
+        super().__init__()

physics/models/lvs/basic_lvs.py

@@ -0,0 +1,18 @@
+from physics.models.lvs.base_lvs import BaseLVS
+
+
+class BasicLVS(BaseLVS):
+
+    def __init__(self, consumed_energy, lvs_current, lvs_voltage):
+        super().__init__(consumed_energy)
+        self.lvs_current = lvs_current
+        self.lvs_voltage = lvs_voltage
+
+    def get_consumed_energy(self, tick):
+        """
+            Get the energy consumption of the Low Voltage System (current * voltage * time)
+
+            :param tick - (int) tick time passed
+            :returns: consumed_energy - (number) value of energy consumed
+        """
+        return self.lvs_current * self.lvs_voltage * tick

physics/models/lvs.rs

@@ -0,0 +1 @@
+mod lvs;

physics/models/motor/__init__.py

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

physics/models/motor/base_motor.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+
+class BaseMotor(ABC):
+    def __init__(self):
+        super().__init__()

physics/models/motor/basic_motor.py

@@ -0,0 +1,174 @@
+import math
+import numpy as np
+
+from physics.models.motor.base_motor import BaseMotor
+from physics.models.constants import ACCELERATION_G, AIR_DENSITY
+
+
+class BasicMotor(BaseMotor):
+    def __init__(self, vehicle_mass, road_friction, tire_radius, vehicle_frontal_area, drag_coefficient):
+        super().__init__()
+
+        # Instantaneous voltage supplied by the battery to the motor controller
+        self.dc_v = 0
+
+        # Instantaneous current supplied by the battery to the motor controller
+        self.dc_i = 0
+
+        self.input_power = 0
+        self.vehicle_mass = vehicle_mass
+        self.acceleration_g = ACCELERATION_G
+        self.road_friction = road_friction
+        self.tire_radius = tire_radius
+
+        self.air_density = AIR_DENSITY
+        self.vehicle_frontal_area = vehicle_frontal_area
+        self.drag_coefficient = drag_coefficient
+
+        self.friction_force = (self.vehicle_mass * self.acceleration_g * self.road_friction)
+
+        self.e_mc = 0.98  # motor controller efficiency, subject to change
+        self.e_m = 0.9  # motor efficiency, subject to change
+
+        # print("torque experienced by motor: {} Nm".format(self.constant_torque))
+
+    @staticmethod
+    def calculate_motor_efficiency(motor_angular_speed, motor_output_energy, tick):
+        """
+
+        Calculates a NumPy array of motor efficiency from NumPy array of operating angular speeds and NumPy array
+            of output power. Based on data obtained from NGM SC-M150 Datasheet and modelling done in MATLAB
+
+        r squared value: 0.873
+
+        :param np.ndarray motor_angular_speed: (float[N]) angular speed motor operates in rad/s
+        :param np.ndarray motor_output_energy: (float[N]) energy motor outputs to the wheel in J
+        :param float tick: length of 1 update cycle in seconds
+        :returns e_m: (float[N]) efficiency of the motor
+        :rtype: np.ndarray
+
+        """
+
+        # Power = Energy / Time
+        motor_output_power = motor_output_energy * tick
+        rads_rpm_conversion_factor = 30 / math.pi
+
+        revolutions_per_minute = motor_angular_speed * rads_rpm_conversion_factor
+
+        e_m = calculate_motor_efficiency(motor_output_power, revolutions_per_minute)
+
+        e_m[e_m < 0.7382] = 0.7382
+        e_m[e_m > 1] = 1
+
+        return e_m
+
+    @staticmethod
+    def calculate_motor_controller_efficiency(motor_angular_speed, motor_output_energy, tick):
+        """
+
+        Calculates a NumPy array of motor controller efficiency from NumPy array of operating angular speeds and
+        NumPy array of output power. Based on data obtained from the WaveSculptor Motor Controller Datasheet efficiency
+        curve for a 90 V DC Bus and modelling done in MATLAB.
+
+        r squared value: 0.7431
+
+        :param np.ndarray motor_angular_speed: (float[N]) angular speed motor operates in rad/s
+        :param np.ndarray motor_output_energy: (float[N]) energy motor outputs to the wheel in J
+        :param float tick: length of 1 update cycle in seconds
+        :returns e_mc (float[N]) efficiency of the motor controller
+        :rtype: np.ndarray
+
+        """
+
+        # Ignore nan warning. Set nan value to 0
+        np.seterr(divide='ignore', invalid='ignore')
+
+        # Power = Energy / Time
+        motor_output_power = motor_output_energy / tick
+
+        # Torque = Power / Angular Speed
+        motor_torque_array = np.nan_to_num(motor_output_power / motor_angular_speed)
+
+        np.seterr(divide='warn', invalid='warn')
+
+        e_mc = calculate_motor_controller_efficiency(motor_angular_speed, motor_torque_array)
+
+        e_mc[e_mc < 0.9] = 0.9
+        e_mc[e_mc > 1] = 1
+
+        return e_mc
+
+    def calculate_energy_in(self, required_speed_kmh, gradients, wind_speeds, tick):
+        """
+
+        Create a function which takes in array of elevation, array of wind speed, required
+            speed, returns the consumed energy.
+
+        :param np.ndarray required_speed_kmh: (float[N]) required speed array in km/h
+        :param np.ndarray gradients: (float[N]) gradient at parts of the road
+        :param np.ndarray wind_speeds: (float[N]) speeds of wind in m/s, where > 0 means against the direction of the vehicle
+        :param float tick: length of 1 update cycle in seconds
+        :returns: (float[N]) energy expended by the motor at every tick
+        :rtype: np.ndarray
+
+        """
+        required_speed_ms = required_speed_kmh / 3.6
+
+        acceleration_ms2 = np.clip(np.gradient(required_speed_ms), a_min=0, a_max=None)
+        acceleration_force = acceleration_ms2 * self.vehicle_mass
+
+        required_angular_speed_rads = required_speed_ms / self.tire_radius
+
+        drag_forces = 0.5 * self.air_density * (
+                (required_speed_ms + wind_speeds) ** 2) * self.drag_coefficient * self.vehicle_frontal_area
+
+        angles = np.arctan(gradients)
+        g_forces = self.vehicle_mass * self.acceleration_g * np.sin(angles)
+
+        road_friction_array = self.road_friction * self.vehicle_mass * self.acceleration_g * np.cos(angles)
+
+        net_force = road_friction_array + drag_forces + g_forces + acceleration_force
+
+        motor_output_energies = required_angular_speed_rads * net_force * self.tire_radius * tick
+        motor_output_energies = np.clip(motor_output_energies, a_min=0, a_max=None)
+
+        e_m = self.calculate_motor_efficiency(required_angular_speed_rads, motor_output_energies, tick)
+        e_mc = self.calculate_motor_controller_efficiency(required_angular_speed_rads, motor_output_energies, tick)
+
+        motor_controller_input_energies = motor_output_energies / (e_m * e_mc)
+
+        # Filter out and replace negative energy consumption as 0
+        motor_controller_input_energies = np.where(motor_controller_input_energies > 0,
+                                                   motor_controller_input_energies, 0)
+
+        return motor_controller_input_energies
+
+    def __str__(self):
+        return (f"Tire radius: {self.tire_radius}m\n"
+                f"Rolling resistance coefficient: {self.road_friction}\n"
+                f"Vehicle mass: {self.vehicle_mass}kg\n"
+                f"Acceleration of gravity: {self.acceleration_g}m/s^2\n"
+                f"Motor controller efficiency: {self.e_mc}%\n"
+                f"Motor efficiency: {self.e_m}%\n")
+
+
+def calculate_motor_efficiency(motor_output_power, revolutions_per_minute):
+    return 0.7382 - (6.281e-5 * motor_output_power) + (6.708e-4 * revolutions_per_minute) \
+        - (2.89e-8 * motor_output_power ** 2) + (2.416e-7 * motor_output_power * revolutions_per_minute) \
+        - (8.672e-7 * revolutions_per_minute ** 2) + (5.653e-12 * motor_output_power ** 3) \
+        - (1.74e-11 * motor_output_power ** 2 * revolutions_per_minute) \
+        - (7.322e-11 * motor_output_power * revolutions_per_minute ** 2) \
+        + (3.263e-10 * revolutions_per_minute ** 3)
+
+
+def calculate_motor_controller_efficiency(motor_angular_speed, motor_torque_array):
+    return 0.7694 + (0.007818 * motor_angular_speed) + (0.007043 * motor_torque_array) \
+        - (1.658e-4 * motor_angular_speed ** 2) - (1.806e-5 * motor_torque_array * motor_angular_speed) \
+        - (1.909e-4 * motor_torque_array ** 2) + (1.602e-6 * motor_angular_speed ** 3) \
+        + (4.236e-7 * motor_angular_speed ** 2 * motor_torque_array) \
+        - (2.306e-7 * motor_angular_speed * motor_torque_array ** 2) \
+        + (2.122e-06 * motor_torque_array ** 3) - (5.701e-09 * motor_angular_speed ** 4) \
+        - (2.054e-9 * motor_angular_speed ** 3 * motor_torque_array) \
+        - (3.126e-10 * motor_angular_speed ** 2 * motor_torque_array ** 2) \
+        + (1.708e-09 * motor_angular_speed * motor_torque_array ** 3) \
+        - (8.094e-09 * motor_torque_array ** 4)

physics/models/motor.rs

@@ -0,0 +1 @@
+mod motor;

physics/models/regen/__init__.py

@@ -0,0 +1,7 @@
+from .base_regen import BaseRegen
+from .basic_regen import BasicRegen
+
+__all__ = [
+    "BasicRegen",
+    "BaseRegen"
+]

physics/models/regen/base_regen.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+
+class BaseRegen(ABC):
+    def __init__(self):
+        super().__init__()

physics/models/regen/basic_regen.py

@@ -0,0 +1,39 @@
+from physics.models.regen import BaseRegen
+import numpy as np
+
+
+class BasicRegen(BaseRegen):
+    GRAVITY = 9.81
+    EFFICIENCY = 0.5  # currently set to 50% but best case scenario is 60-70%
+
+    def __init__(self, vehicle_mass):
+        super().__init__()
+        self.min_decel_mag = 0
+        self.vehicle_mass = vehicle_mass
+        self.kmh_to_mps = 0.278
+
+    def calculate_produced_energy(self, speed_kmh, gis_route_elevations, min_regen_speed, max_power):
+        """
+        Returns a numpy array containing the energy produced by regen
+        during each tick of the race based on the change in energy in that tick
+        :param speed_kmh: an array containing the speeds at each tick
+        :param gis_route_elevations: an array containing elevations on the route at each tick
+        """
+        # get the changes of energy from tick i to tick i + 1
+        speed_ms = speed_kmh / 3.6  # Convert to m/s from km/h
+        delta_kinetic_energy = np.diff((1 / 2) * self.vehicle_mass * pow(speed_ms, 2), append=[0])
+        delta_potential_energy = np.diff(self.vehicle_mass * self.GRAVITY * gis_route_elevations, append=[0])
+
+        # get the total change in energy at each tick
+        delta_energy = delta_kinetic_energy + delta_potential_energy
+
+        # create regen energy produced array
+        # if delta_energy is negative, we regen that energy back at the set efficiency rate; else 0 energy regen
+        produced_energy = np.where(delta_energy < 0, abs(delta_energy) * self.EFFICIENCY, 0)
+
+        # Regen does not occur below a certain speed
+        produced_energy = np.where(speed_ms >= min_regen_speed, produced_energy, 0)
+
+        # Regen power is capped by current limitations
+
+        return np.clip(produced_energy, a_min=0, a_max=max_power)

physics/models/regen.rs

@@ -0,0 +1 @@
+mod regen;

physics/models.rs

@@ -0,0 +1,5 @@
+mod arrays;
+mod battery;
+mod lvs;
+mod motor;
+mod regen;

ubc_solar_physics-1.0.3.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 UBC Solar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ubc_solar_physics-1.0.3.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.1
+Name: ubc-solar-physics
+Version: 1.0.3
+Summary: UBC Solar's Simulation Environment
+Author: Fisher Xue, Mihir Nimgade, Chris Chang, David Widjaja, Justin Hua, Ilya Veksler, Renu Rajamagesh, Ritchie Xia, Erik Langille, Chris Aung, Nicolas Ric, Ishaan Trivedi, Jason Liang, Felix Toft, Mack Wilson, Jonah Lee, Tamzeed Quazi, Joshua Riefman
+Author-email: UBC Solar <strategy@ubcsolar.com>
+Maintainer: Renu Rajamagmesh, Felix Toft, Mack Wilson, Jonah Lee, Tamzeed Quazi
+Maintainer-email: UBC Solar <strategy@ubcsolar.com>, Joshua Riefman <joshuariefman@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 UBC Solar
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://ubcsolar.com
+Project-URL: Repository, https://github.com/UBC-Solar/physics
+Project-URL: Documentation, https://ubc-solar-physics.readthedocs.io/en/latest/
+Keywords: car,simulation,solar
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Natural Language :: English
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: backports.tarfile ==1.2.0
+Requires-Dist: certifi ==2024.7.4
+Requires-Dist: charset-normalizer ==3.3.2
+Requires-Dist: dill ==0.3.8
+Requires-Dist: haversine ==2.8.1
+Requires-Dist: idna ==3.7
+Requires-Dist: importlib-metadata ==8.2.0
+Requires-Dist: jaraco.classes ==3.4.0
+Requires-Dist: jaraco.context ==5.3.0
+Requires-Dist: jaraco.functools ==4.0.2
+Requires-Dist: keyring ==25.3.0
+Requires-Dist: llvmlite ==0.43.0
+Requires-Dist: markdown-it-py ==3.0.0
+Requires-Dist: maturin ==1.7.0
+Requires-Dist: mdurl ==0.1.2
+Requires-Dist: more-itertools ==10.4.0
+Requires-Dist: nh3 ==0.2.18
+Requires-Dist: numba ==0.60.0
+Requires-Dist: numpy ==2.0.1
+Requires-Dist: pkginfo ==1.10.0
+Requires-Dist: Pygments ==2.18.0
+Requires-Dist: readme-renderer ==44.0
+Requires-Dist: requests ==2.32.3
+Requires-Dist: requests-toolbelt ==1.0.0
+Requires-Dist: rfc3986 ==2.0.0
+Requires-Dist: rich ==13.7.1
+Requires-Dist: tqdm ==4.66.5
+Requires-Dist: urllib3 ==2.2.2
+Requires-Dist: zipp ==3.20.0
+
+# UBC Solar Physics
+
+<!-- marker-index-start -->
+
+[![Documentation Status](https://readthedocs.org/projects/ubc-solar-physics/badge/?version=latest)](https://ubc-solar-physics.readthedocs.io/en/latest/?badge=latest)
+
+UBC Solar's physics and environment models for simulating our groundbreaking solar cars.
+
+The API is currently unstable, and backwards compatibility may not be maintained. 
+
+## Requirements
+
+Versions indicated are recommended
+
+* Git [^1]
+* Python >=3.9 [^2]
+* Rustc >=1.79.0 [^3]
+* Cargo >=1.79.0 [^4]
+
+## Installation
+
+First, clone this repository.
+
+```bash
+git clone https://github.com/UBC-Solar/physics.git
+```
+Then, create and activate a virtual environment.
+Next, install dependencies in editable mode.
+
+```bash
+pip3 install -e .
+```
+
+## Getting Started
+
+Example of calculating solar arrays produced energy
+
+```python
+from physics.models.arrays import BasicArray
+import numpy as np
+
+efficiency = 0.25  # 25.0% efficient
+panel_size = 4.0   # 4.0m^2 of panels
+tick = 1.0         # 1.0s interval
+
+arrays = BasicArray(panel_efficiency=efficiency, panel_size=panel_size)
+
+irradiance = np.full([5], 400.0)  # 10 seconds of 400.0W/m^2 irradiance
+
+solar_power_produced = arrays.calculate_produced_energy(solar_irradiance=irradiance, tick=tick)
+
+assert np.array_equal(solar_power_produced, np.array([400.0, 400.0, 400.0, 400.0, 400.0]))
+```
+
+## Appendix
+
+[^1]: use `git --version` to verify version
+
+[^2]: use `python3 --version` to verify version
+
+[^3]: use `rustc --version` to verify version
+
+[^4]: use `cargo --version` to verify version
+
+<!-- marker-index-end -->