Directory-specific documentation update (#100)

* Displays documentation

* Solar documentation

* SOC quick update

* Routemodel update, ? around speedlimits

* Optimization documentation

* Auxloss documentation and refactor imports

* Motor torque documentation

* Dynamics documentation

* Add other files from data_retrieval

Author: e-wai

auxloss/README.md

@@ -1,20 +1,10 @@
-A directory for the car's model for all the auxiliary energy losses of the car, as well as data on the subject
-
-## AuxPowerConsumption
-AuxPowerConsumption class contains `__init__` and two methods, `calculate_instantaneous_power` and `calculate_energy_usage`. 
+# Auxloss
 
-### `__init__(self, power_budget)`
-+ Accepts a csv file (power budget).
-+ Reads and stores information about typical and max power usage, etc. of the various components into a dictionary called  `power_consumptions`. Keys are component names, values are dictionaries with column names as values. Any empty keys are discarded.
-+ Headers expected: "Component", "Max Power (W)", "Typical Power (W)"
-+ Assumes Front and Rear Power infomration stored first. It skips past the first line (which is expected to contain title Front Power Distribution Board) to get the column headers from second line. Reads up until AUX Current Draw and AUX Current Protection title is reached.
+A directory for the car's model for all the auxiliary energy losses of the car, as well as data on the subject
 
-### `calculate_instantaneous_power(self, components_used)`
-+ Accepts a dictionary with a single key, "components", and a list of strings and tuples. 
-+ Strings are component names. If not in tuple, assumes it is using typical power.
-+ Tuples should contain component name and percentage of max. power used: eg. `("Fan", 30)`. Assumes that percentage is provided, not in decimal form. 
-+ Returns sum of power usage by each component
+## In this directory
 
-### `calculate_energy_usage(self, components_used, time_in_seconds)`
-+ Accepts a dictionary and time (s) that power is used. See calculate_instantaneous_power above for more information about dictionary.
-+ Returns energy = power * time
++ `tests` directory
++ `aux_power_consumption.py`: Class for auxiliary losses, based on power budget CSV
++ `auxsystem.py`: Class for initial version of auxiliary loss, not based on power budget
++ `MSXIV Power Budget.csv`: From hardware, CSV representing non-motor energy usage

auxloss/__init__.py

@@ -2,6 +2,15 @@
 
 class AuxPowerConsumption:
     def __init__(self, power_budget):
+        """
+        Initializes AuxPowerConsumption object based on given power budget.
+
+        Reads and stores information about typical and max power usage, etc. of the various components into a dictionary called  `power_consumptions`. Keys are component names, values are dictionaries with column names as values. Any empty keys are discarded.
+
+        :param power_budget: Path to power budget CSV file. 
+            Headers expected: "Component", "Max Power (W)", "Typical Power (W)"
+        """
+
         self.power_consumptions = {}
 
         with open(power_budget, "r") as file:            
@@ -23,15 +32,43 @@ def __init__(self, power_budget):
                 self.power_consumptions[row["Component"]] = {k:v for k,v in row.items()}
 
     def calculate_instantaneous_power(self, components_used):
+        """
+        Calculates instantaneous power from auxiliary losses in power budget
+
+        :param components_used: dictionary with a single key, "components", and a list of  components to consider. This list includes strings and/or (string, float) tuples, where string is component name and optional float specifies percentage of typical power used (30% -> 30, not decimal). If float not specified, assumes typical power. Any components not recognized are ignored.
+            Example:
+                {
+                    "components": [("Horn", 100), ("Fan", 50), "Telemetry"]
+                }
+
+        :return: float, sum of power usage by each component
+        """
+
         current_power = 0
         for component in components_used["components"]:
             if type(component) is tuple:
+                if component[0] not in self.power_consumptions:
+                    print("{} is not a recognized component.".format(component[0]))
+                    continue
+
                 # assumes that percentage is provided (%, not decimal)
                 current_power += float(self.power_consumptions[component[0]]["Max Power (W)"]) * component[1] * 0.01
             else:
+                if component not in self.power_consumptions:
+                    print("{} is not a recognized component.".format(component))
+                    continue
+
                 current_power += float(self.power_consumptions[component]["Typical Power (W)"])
 
         return current_power
 
     def calculate_energy_usage(self, components, time_in_seconds):
-        return self.calculate_instantaneous_power(components) * time_in_seconds
+        """
+        Calculates energy usage from instantaneous auxiliary losses in power budget
+
+        :param components: dictionary, see `calculate_instantaneous_power(self, components_used)`
+        :param time_in_seconds: float, time (s) that power is used
+        
+        :return: float, energy = power * time
+        """
+        return self.calculate_instantaneous_power(components) * time_in_seconds

auxloss/aux_power_consumption.py

@@ -1,14 +1,17 @@
 import sys
 import os.path
-sys.path.append(os.path.join(sys.path[0], '../../'))
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
 import csv
 import pytest
 import mock
-import auxloss
 
-budget_file = os.path.join(sys.path[0], '../', 'MSXIV Power Budget.csv')
+from aux_power_consumption import AuxPowerConsumption
+
+budget_file = os.path.join(os.path.dirname(__file__), '..', 'MSXIV Power Budget.csv')
+
 global auxpc
-auxpc = auxloss.aux_power_consumption.AuxPowerConsumption(budget_file)
+auxpc = AuxPowerConsumption(budget_file)
 
 def test_expected_components_stored_as_keys():
     with open(budget_file, "r") as file:
@@ -28,15 +31,14 @@ def test_expected_components_stored_as_keys():
         assert(component in auxpc.power_consumptions)
 
     for key in auxpc.power_consumptions:
-        print(key)
         assert(key in column_names)
 
 def test_expected_headers_stored():
-    for key, value in auxpc.power_consumptions.items():
-        assert("Max Power (W)" in value and "Typical Power (W)" in value)
+    for headers in auxpc.power_consumptions.values():
+        assert("Max Power (W)" in headers and "Typical Power (W)" in headers)
 
 def test_calculate_instantaneous_power_string_names_only():
-    assert(auxpc.calculate_instantaneous_power({"components": ["Center Console"]}) == 4.4)
+    assert(auxpc.calculate_instantaneous_power({"components": ['Center Console']}) == 4.4)
     assert(auxpc.calculate_instantaneous_power({"components": ["Horn", "Motor Interface", "Solar Master"]}) == 0 + 2.4 + 4.0)
 
 def test_calculate_instantaneous_power_tuples_only():
@@ -52,16 +54,21 @@ def test_calculate_instantaneous_power_unexpected_input_format():
         assert(auxpc.calculate_instantaneous_power("test"))
         assert(auxpc.calculate_instantaneous_power({"test2": ["hello"]}))
 
+def test_calculate_instantaneous_power_ignores_unknown_components():
+    assert(auxpc.calculate_instantaneous_power({"components": [("Horn", 10), "Center Console", "Some random unknown"]}) == 6.21 + 4.4)
+    assert(auxpc.calculate_instantaneous_power({"components": [("Horn", 100), ("Fan", 50), "Telemetry", ("Unknowns", 200)]}) == 62.1 + 3 * 0.5 + 4.5)
+    assert(auxpc.calculate_instantaneous_power({"components": [("Unknowns", 200), "Winnie the Pooh", ("Caillou", 2)]}) == 0)
+
 def test_calculate_energy_usage_zero_power():
-    with mock.patch('auxloss.aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=0):
+    with mock.patch('aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=0):
         assert(auxpc.calculate_energy_usage({"components":[]}, 10) == 0)
 
 def test_calculate_energy_usage_zero_time():
-    with mock.patch('auxloss.aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=1.0):
+    with mock.patch('aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=1.0):
         assert(auxpc.calculate_energy_usage("test", 0) == 0)
 
 def test_calculate_energy_usage():
-    with mock.patch('auxloss.aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=1.0):
+    with mock.patch('aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=1.0):
         assert(auxpc.calculate_energy_usage("test", 100) == 100)
-    with mock.patch('auxloss.aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=14.5):
-        assert(round(auxpc.calculate_energy_usage("test", 87), 3) == round(87 * 14.5, 3))
+    with mock.patch('aux_power_consumption.AuxPowerConsumption.calculate_instantaneous_power', return_value=14.5):
+        assert(round(auxpc.calculate_energy_usage("test", 87), 3) == round(87 * 14.5, 3))

auxloss/tests/test_aux_power_consumption.py

@@ -24,7 +24,6 @@
 print(distances)
 
 plt.plot([d / 1000 for d in distances], elevations)
-# plt.grid(b=True)
 plt.title("Draft ASC 2021 route")
 plt.xlabel("Distance travelled (km)")
 plt.ylabel("Current elevation")

displays/ASC2021_route.py

@@ -1,16 +1,9 @@
-Directory for generate graphs to visualize SOC and velocity profiles.
+# Displays
 
-## SOC_velocity_graph.py
-Methods to generate graph of state of charge and speed against time travelled. See https://www.mdpi.com/2071-1050/9/10/1576/htm for reference for the curve generated.
+Directory for generate graphs that visualize information about car and race data.
 
-### `calculate_SOC_values(v_profile, e_profile, distance, initial_soc, min_speed=None, max_speed=None)`
-+ Instantiates Car object (from car_model.py) and ColoumbCounter object (from SoCEstimation.py) object to energy_used calculation and monitoring SOC levels.
-+ Accepts v_profile, e_profile following parameter specifications in energy_used method. distance is a list of distances that we travel each speed in v_profile. initial_soc is a decimal representing the initial battery state (ie. 1 means fully charged). Accepts min_speed and max_speed with default values of None; this specifies the parameters for Car object initialization.
-+ Returns array of state of charges, starting with initial_soc, and state of charge at the end of each interval of velocity.
-+ Find energy used between each velocity/elevation interval and add to array. Last point is energy_used maintaining the last given velocity for the given distance.
+## In this directory
 
-### `generate_SOC_graph(v_profile, e_profile, distance, initial_soc=1)`
-+ Same parameters as above. Default value for initial_soc is fully charged, 1.
-+ Produces graph; x-axis is distance travelled, starting at 0 and distances over each interval. 
-+ Left y-axis is velocity step function in red; right-axis is state of charge of battery in blue.
-+ Since step function is wanted where velocity is shown over the following interval, step function "post" mode is used, and added a point at beginning of v_profile before graphing to be 0.
++ `tests` directory
++ `SOC_velocity_graph.py`: Methods to graph of SOC and speed against distance travelled. See https://www.mdpi.com/2071-1050/9/10/1576/htm for reference for the curve generated.
++ `ASC2021_route.py`: Script to graph preliminary details (elevations vs. distance travelled) on the ASC 2021 route, the Santa Fe trail.

displays/README.md

@@ -6,7 +6,25 @@
 from optimization.car_model import Car
 from soc.soc_deprecated.SoCEstimation import CoulombCounter
 
-def calculate_SOC_values(v_profile, e_profile, distance, initial_soc, min_speed=None, max_speed=None):
+def calculate_SOC_values(v_profile, e_profile, distances, initial_soc, min_speed=None, max_speed=None):
+    """
+    Calculates state of charge (SOC) array, representing SOC points during race specified by parameters
+
+    :param v_profile: list of velocities that car travels (m/s)
+    :param e_profile: list of elevations that car travels (m)
+    :param distances: list of distances, specifying distance that 
+        each speed in v_profile is travelled (m)
+    :param initial_soc: float representing the initial battery state 
+        (where 1 means fully charged, 0 is empty)
+    :param min_speed: float representing minimum speed car must travel (m/s),
+        defaults to None (no min)
+    :param max_speed: float representing maximum speed car must travel (m/s), 
+        defaults to None (no max)
+
+    :return: list of state of charges, starting with initial_soc, 
+        and SOC at the end of each interval of velocity.
+    """
+
     if min_speed is not None and max_speed is not None:
         car_model = Car(speed_min_ms=min_speed, speed_max_ms=max_speed)
     elif min_speed is not None:
@@ -18,30 +36,45 @@ def calculate_SOC_values(v_profile, e_profile, distance, initial_soc, min_speed=
 
     soc_est = CoulombCounter()
 
-    soc_intervals = [initial_soc]
+    soc_points = [initial_soc]
     soc_est.set_SoC(initial_soc)
 
     for i in range(len(v_profile) - 1):
-        energy_used = car_model.energy_used(v_profile[i: i + 2], e_profile[i: i + 2], distance[i: i + 1])
-        #in SoC calculation, wanted units is W = Js^-1, cancelled out in function's conversion so using 1 
-        soc_est.discharge(energy_used / 1, 1, True)
-        soc_intervals.append(soc_est.get_soc())
+        # Find energy used within each velocity/elevation interval
+        energy_used = car_model.energy_used(v_profile[i: i + 2], e_profile[i: i + 2], distances[i: i + 1])
+        # in `discharge`, method parameter units is W = Js^-1, but energy_used is in J
+        # assume time span of 1s, conversion cancels out
+        soc_est.discharge(power_W=energy_used / 1, time_S=1, dirOUT=True)
+        soc_points.append(soc_est.get_soc())
 
     # last point: maintaining velocity for last given distance
     last_point_velocities = [v_profile[-1], v_profile[-1]]
     last_elevation = [e_profile[-1], e_profile[-1]]
-    last_energy_used = car_model.energy_used(last_point_velocities, last_elevation, distance[-1])
+    last_energy_used = car_model.energy_used(last_point_velocities, last_elevation, distances[-1])
     soc_est.discharge(last_energy_used / 1, 1, True)
-    soc_intervals.append(soc_est.get_soc())
+    soc_points.append(soc_est.get_soc())
+
+    return soc_points
+
+def generate_SOC_graph(v_profile, e_profile, distances, initial_soc=1):
+    """
+    Graphs velocity and state of charge (SOC) vs. distance travelled for some race defined by parameters. 
 
-    return soc_intervals
+    These parameters reflect those in energy_used from car_model.py
+    :param v_profile: list of speeds that car travels (m/s)
+    :param e_profile: list of elevations that car travels (m)
+    :param distances: list of distances, specifying distance that 
+        each speed in v_profile is travelled (m)
+    :param initial_soc: float representing the initial battery state 
+        (where 1 means fully charged, 0 is empty). Default is 1.
+    """
 
-def generate_SOC_graph(v_profile, e_profile, distance, initial_soc=1):
-    x_axis = [0]
-    for interval_distance in distance:
-        x_axis.append(x_axis[len(x_axis) - 1] + interval_distance)
+    # start race at 0m travelled
+    distance_travelled = [0]
+    for interval_distance in distances:
+        distance_travelled.append(distance_travelled[len(distance_travelled) - 1] + interval_distance)
 
-    soc_values = calculate_SOC_values(v_profile, e_profile, distance, initial_soc)
+    soc_values = calculate_SOC_values(v_profile, e_profile, distances, initial_soc)
     soc_percentages = [soc * 100 for soc in soc_values]
 
     # for purpose of graphing velocities as step, start at 0
@@ -54,16 +87,16 @@ def generate_SOC_graph(v_profile, e_profile, distance, initial_soc=1):
     ax1.set_ylabel('Velocity (m/s)')
     ax1.yaxis.label.set_color(color)
     ax1.spines['left'].set_color(color)
-    ax1.step(x_axis, v_profile, where='pre', color=color)
+    ax1.step(distance_travelled, v_profile, where='pre', color=color)
 
     ax2 = ax1.twinx()
 
     color = 'tab:blue'
     ax2.set_ylabel('State of Charge (%)')
     ax2.yaxis.label.set_color(color)
     ax2.spines['right'].set_color(color)
-    ax2.plot(x_axis, soc_percentages, color=color)
+    ax2.plot(distance_travelled, soc_percentages, color=color)
 
     plt.title('State of Charge vs. Velocity Graph')
     fig.tight_layout()
-    plt.show()
+    plt.show()

displays/SOC_velocity_graph.py

@@ -1 +1,21 @@
+# Dynamics
+
 A directory for all the car's dynamics modelling and data
+
+## In this directory
+
++ `tests` directory
++ `CdACrrCalculator.py`: Extract aero drag and rolling resistance coefficients
++ `parserolldowndata.py`: Method to produce cleaned dataframe from CSV rolldown
+
+### `motor_efficiency` module
+
++ `motor_efficiency.py`: Class to generate and graph motor efficiency curves based on test data
++ `HIData.csv`: Test data CSV for high coil, see [mechanical Confluence](https://uwmidsun.atlassian.net/wiki/spaces/MECH/pages/1628012551/Interpreting+the+Graphs+From+Nomura)
++ `LOData.csv`: Test data CSV for low coil, see [mechanical Confluence](https://uwmidsun.atlassian.net/wiki/spaces/MECH/pages/1628012551/Interpreting+the+Graphs+From+Nomura)
+
+### `rolldowndata` module
+
++ `canlog`: Directory of canlog data CSVs
++ `rolldown`: Scripts for cleaning and processing rolldown CSV data
++ `test.csv`: Sample rolldown CSV

dynamics/README.md

@@ -1,11 +1,12 @@
 import pandas as pd
-"""
-Input: Csv as generated by the test data
-Output: Cleaned DataFrame for usage in rolldownconverter.py
-"""
 
 
 def clean(file, windspeed=0):
+    """
+    :param file: Csv as generated by the test data
+    
+    :return: Cleaned DataFrame for usage in rolldownconverter.py
+    """
     data = pd.read_csv(file)
     if "test.csv" in file or 'canlog' in file:
         # Calculate the average measured velocity

dynamics/parserolldowndata.py

@@ -0,0 +1,9 @@
+# Motor Torque Calculation
+
+Directory for determining motor torque throughout a race and associated graphs.
+
+## In this directory
+
++ `tests` directory
++ `alt_gain.py`: Class for version of car model and script for determining motor torque necessary throughout a given route
++ Assorted graphs for ASC and WSC