ubc-solar-physics 0.1.0__cp311-cp311-macosx_13_0_universal2.whl

physics/__init__.py

@@ -0,0 +1,14 @@
+from .environment import (
+    openweather_environment,
+    solcast_environment,
+    weather_forecasts,
+    gis
+)
+
+from .models import (
+    arrays,
+    battery,
+    lvs,
+    motor,
+    regen
+)

physics/environment/__init__.py

@@ -0,0 +1,33 @@
+from .base_environment import BaseEnvironment
+from .openweather_environment import OpenweatherEnvironment
+from .solcast_environment import SolcastEnvironment
+from .race import (
+    Race,
+    compile_races
+)
+
+from .solar_calculations import (
+    OpenweatherSolarCalculations,
+    SolcastSolarCalculations
+)
+
+from .weather_forecasts import (
+    OpenWeatherForecast,
+    SolcastForecasts,
+)
+
+from .gis import (
+    GIS,
+)
+
+__all__ = [
+    "OpenweatherEnvironment",
+    "SolcastEnvironment",
+    "OpenWeatherForecast",
+    "SolcastForecasts",
+    "SolcastSolarCalculations",
+    "OpenweatherSolarCalculations",
+    "GIS",
+    "Race",
+    "compile_races"
+]

physics/environment/base_environment.py

@@ -0,0 +1,62 @@
+class BaseEnvironment:
+    def __init__(self):
+        self._time_dt = None
+        self._latitude = None
+        self._longitude = None
+        self._wind_speed = None
+        self._wind_direction = None
+
+    @property
+    def time_dt(self):
+        if (value := self._time_dt) is not None:
+            return value
+        else:
+            raise ValueError("time_dt is None!")
+
+    @time_dt.setter
+    def time_dt(self, value):
+        self._time_dt = value
+
+    @property
+    def latitude(self):
+        if (value := self._latitude) is not None:
+            return value
+        else:
+            raise ValueError("latitude is None!")
+
+    @latitude.setter
+    def latitude(self, value):
+        self._latitude = value
+
+    @property
+    def longitude(self):
+        if (value := self._longitude) is not None:
+            return value
+        else:
+            raise ValueError("longitude is None!")
+
+    @longitude.setter
+    def longitude(self, value):
+        self._longitude = value
+
+    @property
+    def wind_speed(self):
+        if (value := self._wind_speed) is not None:
+            return value
+        else:
+            raise ValueError("wind_speed is None!")
+
+    @wind_speed.setter
+    def wind_speed(self, value):
+        self._wind_speed = value
+
+    @property
+    def wind_direction(self):
+        if (value := self._wind_direction) is not None:
+            return value
+        else:
+            raise ValueError("wind_direction is None!")
+
+    @wind_direction.setter
+    def wind_direction(self, value):
+        self._wind_direction = value

physics/environment/environment.rs

@@ -0,0 +1,3 @@
+pub mod gis;
+pub mod solar_calculations;
+pub mod weather_forecasts;

physics/environment/gis/__init__.py

@@ -0,0 +1,7 @@
+from .base_gis import BaseGIS
+from .gis import GIS
+
+__all__ = [
+    "BaseGIS",
+    "GIS"
+]

physics/environment/gis/base_gis.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+import numpy as np
+
+
+class BaseGIS(ABC):
+    @abstractmethod
+    def calculate_closest_gis_indices(self, cumulative_distances) -> np.ndarray:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_path_elevations(self) -> np.ndarray:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_gradients(self, gis_indices) -> np.ndarray:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_time_zones(self, gis_indices) -> np.ndarray:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_path(self) -> np.ndarray:
+        raise NotImplementedError

physics/environment/gis/gis.py

@@ -0,0 +1,374 @@
+import os
+import logging
+import math
+import pathlib
+
+import numpy as np
+import sys
+from tqdm import tqdm
+from xml.dom import minidom
+from typing import TypeAlias, Union
+from haversine import haversine, Unit
+
+from physics.environment.gis.base_gis import BaseGIS
+from physics.environment.race import Race
+
+import core
+
+PathLike: TypeAlias = Union[pathlib.Path, str]
+
+
+class GIS(BaseGIS):
+    def __init__(self, origin_coord, dest_coord, waypoints, race_type, route_directory: PathLike, current_coord=None, hash_key=None):
+        """
+
+        Initialises a GIS (geographic location system) object. This object is responsible for getting the
+        simulation's planned route from the Google Maps API and performing operations on the received data.
+
+        :param origin_coord: NumPy array containing the start coordinate (lat, long) of the planned travel route
+        :param dest_coord: NumPy array containing the end coordinate (lat, long) of the planned travel route
+        :param waypoints: NumPy array containing the route waypoints to travel through during simulation
+        :param race_type: String ("FSGP" or "ASC") stating which race is being simulated
+        :param hash_key: key used to identify cached data as valid for a Simulation model
+
+        """
+        self.current_index = 0
+        self.distance_remainder = 0
+
+        self.origin_coord = origin_coord
+        self.dest_coord = dest_coord
+        self.current_coord = current_coord
+        self.waypoints = waypoints
+        self.race_type = race_type
+
+        # path to file storing the route and elevation NumPy arrays
+        if self.race_type == Race.RaceType.FSGP:
+            route_file = route_directory / "route_data_FSGP.npz"
+        else:
+            route_file = route_directory / "route_data.npz"
+
+        # if the file exists, load path from file
+        if os.path.isfile(route_file):
+            with np.load(route_file) as route_data:
+                if route_data['hash'] == hash_key:
+
+                    print("Previous route save file is being used...\n")
+
+                    print("----- Route save file information -----")
+                    for key in route_data:
+                        print(f"> {key}: {route_data[key].shape}")
+
+                    self.path = route_data['path']
+                    self.launch_point = route_data['path'][0]
+                    self.path_elevations = route_data['elevations']
+                    self.path_time_zones = route_data['time_zones']
+                    self.speed_limits = route_data['speed_limits']
+                    self.num_unique_coords = route_data['num_unique_coords']
+
+                    if current_coord is not None:
+                        if not np.array_equal(current_coord, origin_coord):
+                            logging.warning("Current position is not origin position. Modifying path data.\n")
+
+                            # We need to find the closest coordinate along the path to the vehicle position
+                            current_coord_index = GIS._find_closest_coordinate_index(current_coord, self.path)
+
+                            # All coords before the current coordinate should be discarded
+                            self.path = self.path[current_coord_index:]
+                            self.path_elevations = self.path_elevations[current_coord_index:]
+                            self.path_time_zones = self.path_time_zones[current_coord_index:]
+        else:
+            logging.warning("Route save file does not exist.\n")
+            logging.error("Update API cache by calling CacheAPI.py , Exiting simulation...\n")
+
+            exit()
+
+        self.path_distances = calculate_path_distances(self.path)
+        self.path_length = np.cumsum(calculate_path_distances(self.path[:self.num_unique_coords]))[-1]
+        self.path_gradients = calculate_path_gradients(self.path_elevations, self.path_distances)
+
+    @staticmethod
+    def process_KML_file(route_file):
+        """
+
+        Load the FSGP Track from a KML file exported from a Google Earth project.
+
+        Ensure to follow guidelines enumerated in this directory's `README.md` when creating and
+        loading new route files.
+
+        :return: Array of N coordinates (latitude, longitude) in the shape [N][2].
+        """
+        with open(route_file) as f:
+            data = minidom.parse(f)
+            kml_coordinates = data.getElementsByTagName("coordinates")[0].childNodes[0].data
+            coordinates: np.ndarray = np.array(parse_coordinates_from_kml(kml_coordinates))
+
+            # Google Earth exports coordinates in order longitude, latitude, when we want the opposite
+            return np.roll(coordinates, 1, axis=1)
+
+    def calculate_closest_gis_indices(self, distances):
+        """
+
+        Takes in an array of point distances from starting point, returns a list of
+        self.path indices of coordinates which have a distance from the starting point
+        closest to the point distances.
+
+        :param np.ndarray cumulative_distances: (float[N]) array of distances, where cumulative_distances[x] > cumulative_distances[x-1]
+        :returns: (float[N]) array of indices of path
+        :rtype: np.ndarray
+
+        """
+        return core.closest_gis_indices_loop(distances, self.path_distances)
+
+    @staticmethod
+    def _python_calculate_closest_gis_indices(distances, path_distances):
+        """
+
+        Python implementation of rust core.closest_gis_indices_loop. See parent function for documentation details.
+
+        """
+
+        current_coordinate_index = 0
+        result = []
+
+        with tqdm(total=len(distances), file=sys.stdout, desc="Calculating closest GIS indices") as pbar:
+            distance_travelled = 0
+            for distance in np.nditer(distances):
+                distance_travelled += distance
+
+                while distance_travelled > path_distances[current_coordinate_index]:
+                    distance_travelled -= path_distances[current_coordinate_index]
+                    current_coordinate_index += 1
+
+                    if current_coordinate_index >= len(path_distances) - 1:
+                        current_coordinate_index = len(path_distances) - 1
+
+                result.append(current_coordinate_index)
+                pbar.update(1)
+
+        return np.array(result)
+
+    # ----- Getters -----
+    def get_time_zones(self, gis_indices):
+        """
+
+        Takes in an array of path indices, returns the time zone at each index
+
+        :param np.ndarray gis_indices: (float[N]) array of path indices
+        :returns: (float[N]) array of time zones in seconds
+        :rtype: np.ndarray
+
+        """
+
+        return self.path_time_zones[gis_indices]
+
+    def get_gradients(self, gis_indices):
+        """
+
+        Takes in an array of path indices, returns the road gradient at each index
+
+        :param np.ndarray gis_indices: (float[N]) array of path indices
+        :returns: (float[N]) array of road gradients
+        :rtype np.ndarray:
+
+        """
+
+        return self.path_gradients[gis_indices]
+
+    def get_path(self):
+        """
+        Returns all N coordinates of the path in a NumPy array
+        [N][latitude, longitude]
+
+        :rtype: np.ndarray
+
+        """
+
+        return self.path
+
+    def get_path_elevations(self):
+        """
+
+        Returns all N elevations of the path in a NumPy array
+        [N][elevation]
+
+        :rtype: np.ndarray
+
+        """
+
+        return self.path_elevations
+
+    def get_path_distances(self):
+        """
+
+        Returns all N-1 distances of the path in a NumPy array
+        [N-1][elevation]
+
+        :rtype: np.ndarray
+
+        """
+
+        return self.path_distances
+
+    def get_path_gradients(self):
+        """
+
+        Returns all N-1 gradients of a path in a NumPy array
+        [N-1][gradient]
+
+        :rtype: np.ndarray
+
+        """
+
+        return self.path_gradients
+
+    # ----- Path calculation functions -----
+    def calculate_path_min_max(self):
+        logging.warning(f"Using deprecated function 'calculate_path_min_max()'!")
+        min_lat, min_long = self.path.min(axis=0)
+        max_lat, max_long = self.path.max(axis=0)
+        return [min_long, min_lat, max_long, max_lat]
+
+    def calculate_current_heading_array(self):
+        """
+
+        Calculates the bearing of the vehicle between consecutive points
+        https://www.movable-type.co.uk/scripts/latlong.html
+
+        :returns: array of bearings
+        :rtype: np.ndarray
+
+        """
+        bearing_array = np.zeros(len(self.path))
+
+        for index in range(0, len(self.path) - 1):
+            coord_1 = np.radians(self.path[index])
+            coord_2 = np.radians(self.path[index + 1])
+
+            y = math.sin(coord_2[1] - coord_1[1]) \
+                * math.cos(coord_2[0])
+
+            x = math.cos(coord_1[0]) \
+                * math.sin(coord_2[0]) \
+                - math.sin(coord_1[0]) \
+                * math.cos(coord_2[0]) \
+                * math.cos(coord_2[1] - coord_1[1])
+
+            theta = math.atan2(y, x)
+
+            bearing_array[index] = ((theta * 180) / math.pi + 360) % 360
+
+        bearing_array[-1] = bearing_array[-2]
+
+        return bearing_array
+
+    @staticmethod
+    def _calculate_vector_square_magnitude(vector):
+        """
+
+        Calculate the square magnitude of an input vector. Must be one-dimensional.
+
+        :param np.ndarray vector: NumPy array[N] representing a vector[N]
+        :return: square magnitude of the input vector
+        :rtype: float
+
+        """
+
+        return sum(i ** 2 for i in vector)
+
+    @staticmethod
+    def _find_closest_coordinate_index(current_coord, path):
+        """
+
+        Returns the closest coordinate to current_coord in path
+
+        :param np.ndarray current_coord: A NumPy array[N] representing a N-dimensional vector
+        :param np.ndarray path: A NumPy array[M][N] of M coordinates which should be N-dimensional vectors
+        :returns: index of the closest coordinate.
+        :rtype: int
+
+        """
+
+        to_current_coord_from_path = np.abs(path - current_coord)
+        distances_from_current_coord = np.zeros(len(to_current_coord_from_path))
+        for i in range(len(to_current_coord_from_path)):
+            # As we just need the minimum, using square magnitude will save performance
+            distances_from_current_coord[i] = GIS._calculate_vector_square_magnitude(to_current_coord_from_path[i])
+
+        return distances_from_current_coord.argmin()
+
+
+def calculate_path_distances(coords):
+    """
+
+    Obtain the distance between each coordinate by approximating the spline between them
+    as a straight line, and use the Haversine formula (https://en.wikipedia.org/wiki/Haversine_formula)
+    to calculate distance between coordinates on a sphere.
+
+    :param np.ndarray coords: A NumPy array [n][latitude, longitude]
+    :returns path_distances: a NumPy array [n-1][distances],
+    :rtype: np.ndarray
+
+    """
+
+    coords_offset = np.roll(coords, (1, 1))
+    path_distances = []
+    for u, v in zip(coords, coords_offset):
+        path_distances.append(haversine(u, v, unit=Unit.METERS))
+
+    return np.array(path_distances)
+
+
+def parse_coordinates_from_kml(coords_str: str) -> np.ndarray:
+    """
+
+    Parse a coordinates string from a XML (KML) file into a list of coordinates (2D vectors).
+    Requires coordinates in the format "39.,41.,0  39.,40.,0" which will return [ [39., 41.], [39., 40.] ].
+
+    :param coords_str: coordinates string from a XML (KML) file
+    :return: list of 2D vectors representing coordinates
+    :rtype: np.ndarray
+
+    """
+
+    def parse_coord(pair):
+        coord = pair.split(',')
+        coord.pop()
+        coord = [float(value) for value in coord]
+        return coord
+
+    return list(map(parse_coord, coords_str.split()))
+
+
+def calculate_path_gradients(elevations, distances):
+    """
+
+    Get the approximate gradients of every point on the path.
+
+    Note:
+        - gradient > 0 corresponds to uphill
+        - gradient < 0 corresponds to downhill
+
+    :param np.ndarray elevations: [N][elevations]
+    :param np.ndarray distances: [N-1][distances]
+    :returns gradients: [N-1][gradients]
+    :rtype: np.ndarray
+
+    """
+
+    # subtract every next elevation with the previous elevation to
+    # get the difference in elevation
+    # [1 2 3 4 5]
+    # [5 1 2 3 4] -
+    # -------------
+    #   [1 1 1 1]
+
+    offset = np.roll(elevations, 1)
+    delta_elevations = elevations - offset
+
+    # Divide the difference in elevation to get the gradient
+    # gradient > 0: uphill
+    # gradient < 0: downhill
+    with np.errstate(invalid='ignore'):
+        gradients = delta_elevations / distances
+
+    return np.nan_to_num(gradients, nan=0.)

physics/environment/gis/gis.rs

@@ -0,0 +1,25 @@
+use chrono::{Datelike, NaiveDateTime, Timelike};
+use numpy::ndarray::{s, Array, Array2, ArrayViewD, ArrayViewMut2, ArrayViewMut3, Axis};
+
+pub fn rust_closest_gis_indices_loop(
+    distances: ArrayViewD<'_, f64>,
+    path_distances: ArrayViewD<'_, f64>,
+) -> Vec<i64> {
+    let mut current_coord_index: usize = 0;
+    let mut distance_travelled: f64 = 0.0;
+    let mut result: Vec<i64> = Vec::with_capacity(distances.len());
+
+    for &distance in distances {
+        distance_travelled += distance;
+
+        while distance_travelled > path_distances[current_coord_index] {
+            distance_travelled -= path_distances[current_coord_index];
+            current_coord_index += 1;
+        }
+
+        current_coord_index = std::cmp::min(current_coord_index, path_distances.len() - 1);
+        result.push(current_coord_index as i64);
+    }
+
+    result
+}

physics/environment/gis.rs

@@ -0,0 +1 @@
+pub mod gis;

physics/environment/openweather_environment.py

@@ -0,0 +1,18 @@
+from physics.environment.base_environment import BaseEnvironment
+
+
+class OpenweatherEnvironment(BaseEnvironment):
+    def __init__(self):
+        super().__init__()
+        self._cloud_cover = None
+
+    @property
+    def cloud_cover(self):
+        if (value := self._cloud_cover) is not None:
+            return value
+        else:
+            raise ValueError("cloud cover is None!")
+
+    @cloud_cover.setter
+    def cloud_cover(self, value):
+        self._cloud_cover = value

physics/environment/race.py

@@ -0,0 +1,89 @@
+"""
+This class collects the constants that are related to a specific competition.
+"""
+import pathlib
+
+import numpy as np
+import pickle
+import enum
+import json
+import os
+
+
+class Race:
+    class RaceType(enum.Enum):
+        ASC = "ASC"
+        FSGP = "FSGP"
+
+        def __str__(self):
+            match self.value:
+                case "ASC":
+                    return "ASC"
+                case "FSGP":
+                    return "FSGP"
+
+        def __reduce__(self):
+            return self.__class__, (self.name,)
+
+        def __contains__(self, item):
+            return item == "ASC" or item == "FSGP"
+
+        def __repr__(self):
+            return str(self)
+
+    ASC = RaceType.ASC
+    FSGP = RaceType.FSGP
+
+    def __init__(self, race_type: RaceType, race_constants: dict):
+        self.race_type = race_type
+
+        self.days = race_constants["days"]
+        self.tiling = race_constants["tiling"]
+        self.date = (race_constants["start_year"], race_constants["start_month"], race_constants["start_day"])
+
+        self.race_duration = len(self.days) * 24 * 60 * 60  # Duration (s)
+        self.driving_boolean = self.make_time_boolean("driving")
+        self.charging_boolean = self.make_time_boolean("charging")
+
+    def __str__(self):
+        return str(self.race_type)
+
+    def write(self, race_directory: pathlib.Path):
+        with open(race_directory / f"{str(self.race_type)}.pkl", 'wb') as outfile:
+            pickle.dump(self, outfile, protocol=pickle.HIGHEST_PROTOCOL)
+
+    def make_time_boolean(self, boolean_type: str):
+        boolean: np.ndarray = np.empty(self.race_duration, dtype=np.int8)
+        DAY_LENGTH: int = 24 * 60 * 60  # Length of a day in seconds
+
+        for tick in range(len(boolean)):
+            day: int = tick // DAY_LENGTH    # Integer division to determine how many days have passed
+            time_of_day = tick % DAY_LENGTH  # Time of day in seconds where 0 is midnight and 43200 is noon
+            begin, end = self.days[str(day)][boolean_type]
+
+            # If the time of day is between the beginning and end, then the boolean is True, else False
+            boolean[tick] = begin <= time_of_day < end
+
+        return boolean
+
+
+def load_race(race_type: Race.RaceType, race_directory: pathlib.Path) -> Race:
+    with open(race_directory / f"{str(race_type)}.pkl", 'rb') as infile:
+        return pickle.load(infile)
+
+
+def compile_races(config_directory: pathlib.Path, race_directory: pathlib.Path):
+    fsgp_config_path = os.path.join(config_directory, f"settings_FSGP.json")
+    asc_config_path = os.path.join(config_directory, f"settings_ASC.json")
+
+    with open(fsgp_config_path) as f:
+        fsgp_race_constants = json.load(f)
+
+    with open(asc_config_path) as f:
+        asc_race_constants = json.load(f)
+
+    fsgp = Race(Race.FSGP, fsgp_race_constants)
+    fsgp.write(race_directory)
+
+    asc = Race(Race.ASC, asc_race_constants)
+    asc.write(race_directory)