Merge pull request #3 from iSOLveIT/master

Updated documentation and doctsrings in package files
romainsacchi · Jun 19, 2023 · 099374e · 099374e
2 parents b9ffcc8 + 20aa74a
commit 099374e
Show file tree

Hide file tree

Showing 68 changed files with 1,237 additions and 1,423 deletions.
diff --git a/carculator_truck/__init__.py b/carculator_truck/__init__.py
@@ -9,7 +9,7 @@
 
 """
 
-_all_ = (
+__all__ = (
     "TruckInputParameters",
     "fill_xarray_from_input_parameters",
     "TruckModel",

diff --git a/carculator_truck/driving_cycles.py b/carculator_truck/driving_cycles.py
@@ -3,6 +3,13 @@
 
 
 def get_driving_cycle(size: list, name: str) -> np.ndarray:
+    """
+    Get driving cycle.
+
+    :param size: List of vehicle sizes.
+    :param name: The name of the driving cycle.
+    :return: :meth:`ndarray` object
+    """
     return get_standard_driving_cycle_and_gradient(
         vehicle_type="truck",
         vehicle_sizes=size,
@@ -11,6 +18,13 @@ def get_driving_cycle(size: list, name: str) -> np.ndarray:
 
 
 def get_road_gradient(size: list, name: str) -> np.ndarray:
+    """
+    Get road gradient data.
+
+    :param size: List of vehicle sizes.
+    :param name: The name of the driving cycle.
+    :return: :meth:`ndarray` object
+    """
     return get_standard_driving_cycle_and_gradient(
         vehicle_type="truck",
         vehicle_sizes=size,

diff --git a/carculator_truck/inventory.py b/carculator_truck/inventory.py
@@ -24,7 +24,7 @@ def fill_in_A_matrix(self):
         Fill-in the A matrix. Does not return anything. Modifies in place.
         Shape of the A matrix (values, products, activities).
 
-        :param array: :attr:`array` from :class:`CarModel` class
+        :attr:`array` from :class:`CarModel` class
         """
 
         # Glider/Frame

diff --git a/carculator_truck/model.py b/carculator_truck/model.py
@@ -29,7 +29,7 @@ class TruckModel(VehicleModel):
     This class represents the entirety of the vehicles considered, with useful attributes, such as an array that stores
     all the vehicles parameters.
 
-    :ivar array: multi-dimensional numpy-like array that contains parameters' value(s)
+    :ivar array: multidimensional numpy-like array that contains parameters' value(s)
     :vartype array: xarray.DataArray
     :ivar mappings: Dictionary with names correspondence
     :vartype mappings: dict
@@ -44,18 +44,16 @@ def set_all(self, electric_utility_factor: float = None):
         efficiency of the vehicle, costs, etc.
 
         :meth:`set_component_masses()`, :meth:`set_vehicle_masses()` and :meth:`set_power_parameters()` and
-         :meth:`set_energy_stored_properties` relate to one another.
+        :meth:`set_energy_stored_properties` relate to one another.
         `powertrain_mass` depends on `power`, `curb_mass` is affected by changes in `powertrain_mass`,
-        `combustion engine mass`, `electric engine mass`. `energy battery mass` is influenced
-        by the `curb mass` but also
+        `combustion engine mass`, `electric engine mass`. `energy battery mass` is influencedby the `curb mass` but also
         by the `target range` the truck has. `power` is also varying with `curb_mass`.
 
         The current solution is to loop through the methods until the change in payload between
-        two iterations is
-        inferior to 0.1%. It is then assumed that the trucks are correctly sized.
-
-        :returns: Does not return anything. Modifies ``self.array`` in place.
+        two iterations is inferior to 0.1%. It is then assumed that the trucks are correctly sized.
 
+        :param electric_utility_factor: the share of km driven in battery-depleting mode over the required range autonomy
+        :return: Does not return anything. Modifies ``self.array`` in place.
         """
 
         diff = 1.0
@@ -173,7 +171,6 @@ def adjust_cost(self):
         """
         This method adjusts costs of energy storage over time, to correct for the overly optimistic linear
         interpolation between years.
-
         """
 
         n_iterations = self.array.shape[-1]
@@ -279,7 +276,6 @@ def set_battery_chemistry(self):
     def override_range(self):
         """
         Set storage size or range for each powertrain.
-        :return:
         """
 
         target_ranges = {
@@ -322,7 +318,6 @@ def calculate_ttw_energy(self):
         auxiliary services as well as to move the vehicle.
         The sum is stored under the parameter label "TtW energy"
         in :attr:`self.array`.
-
         """
 
         self.energy = self.ecm.motive_energy_per_km(
@@ -405,7 +400,7 @@ def calculate_ttw_energy(self):
 
     def set_battery_fuel_cell_replacements(self):
         """
-        This methods calculates the number of replacement batteries needed
+        These methods calculates the number of replacement batteries needed
         to match the vehicle lifetime. Given the chemistry used,
         the cycle life is known. Given the lifetime kilometers and
         the kilometers per charge, the number of charge cycles can be inferred.
@@ -415,7 +410,6 @@ def set_battery_fuel_cell_replacements(self):
         Also, the number of replacement is rounded up.
         This means that the entirety of the battery replacement is allocated
         to the vehicle (and not to its potential second life).
-
         """
         # Number of replacement of battery is rounded *up*
 
@@ -464,13 +458,11 @@ def set_vehicle_masses(self):
         """
         Define ``curb mass``, ``driving mass``, and ``cargo mass``.
 
-            * `curb mass <https://en.wikipedia.org/wiki/Curb_weight>`__ is the mass of the vehicle and fuel, without people or cargo.
-            * ``cargo mass`` is the mass of the cargo and passengers.
-            * ``driving mass`` is the ``curb mass`` plus ``cargo mass``.
-
-        .. note::
-            driving mass = cargo mass + driving mass
+        * `curb mass <https://en.wikipedia.org/wiki/Curb_weight>`__ is the mass of the vehicle and fuel, without people or cargo.
+        * ``cargo mass`` is the mass of the cargo and passengers.
+        * ``driving mass`` is the ``curb mass`` plus ``cargo mass``.
 
+        .. note:: driving mass = cargo mass + driving mass
         """
 
         # Base components, common to all powertrains
@@ -546,11 +538,8 @@ def set_component_masses(self):
 
     def set_electric_utility_factor(self, uf: float = None) -> None:
         """
-        The electric utility factor
-        is the share of km driven in battery-depleting mode
-        over the required range autonomy.
-        Scania's PHEV tractor can drive 60 km in electric mode
-        :return:
+        The electric utility factor is the share of km driven in battery-depleting mode
+        over the required range autonomy. Scania's PHEV tractor can drive 60 km in electric mode
         """
         if "PHEV-e" in self.array.coords["powertrain"].values:
             range = (
@@ -581,9 +570,7 @@ def set_electric_utility_factor(self, uf: float = None) -> None:
     def set_energy_stored_properties(self):
         """
         First, fuel mass is defined. It is dependent on the range required.
-        Then batteries are sized, depending on the range
-        required and the energy consumption.
-        :return:
+        Then batteries are sized, depending on the range required and the energy consumption.
         """
 
         _ = lambda x: np.where(x == 0, 1, x)
@@ -848,13 +835,13 @@ def set_costs(self):
 
     def calculate_cost_impacts(self, sensitivity=False, scope=None):
         """
-        This method returns an array with cost values per vehicle-km, sub-divided into the following groups:
+        This method returns an array with cost values per vehicle-km, subdivided into the following groups:
 
-            * Purchase
-            * Maintentance
-            * Component replacement
-            * Energy
-            * Total cost of ownership
+        * Purchase
+        * Maintenance
+        * Component replacement
+        * Energy
+        * Total cost of ownership
 
         :return: A xarray array with cost information per vehicle-km
         :rtype: xarray.core.dataarray.DataArray

diff --git a/docs/_static/img/energy_model.png b/docs/_static/img/energy_model.png
diff --git a/docs/_static/img/hybrid_efficiency.png b/docs/_static/img/hybrid_efficiency.png
diff --git a/docs/media/image68.jpg → docs/_static/img/image1.jpg b/docs/media/image68.jpg → docs/_static/img/image1.jpg
diff --git a/docs/media/image79.png → docs/_static/img/image10.png b/docs/media/image79.png → docs/_static/img/image10.png
diff --git a/docs/_static/img/image11.png b/docs/_static/img/image11.png
diff --git a/docs/_static/img/image12.png b/docs/_static/img/image12.png
diff --git a/docs/media/image61.png → docs/_static/img/image13.png b/docs/media/image61.png → docs/_static/img/image13.png
diff --git a/docs/media/image83.png → docs/_static/img/image14.png b/docs/media/image83.png → docs/_static/img/image14.png
diff --git a/docs/_static/img/image15.png b/docs/_static/img/image15.png
diff --git a/docs/_static/img/image16.png b/docs/_static/img/image16.png
diff --git a/docs/_static/img/image17.png b/docs/_static/img/image17.png
diff --git a/docs/_static/img/image18.png b/docs/_static/img/image18.png
diff --git a/docs/_static/img/image19.png b/docs/_static/img/image19.png
diff --git a/docs/media/image69.jpg → docs/_static/img/image2.jpg b/docs/media/image69.jpg → docs/_static/img/image2.jpg
diff --git a/docs/_static/img/image20.png b/docs/_static/img/image20.png
diff --git a/docs/_static/img/image21.png b/docs/_static/img/image21.png
diff --git a/docs/_static/img/image22.png b/docs/_static/img/image22.png
diff --git a/docs/_static/img/image23.png b/docs/_static/img/image23.png
diff --git a/docs/media/image75.png → docs/_static/img/image24.png b/docs/media/image75.png → docs/_static/img/image24.png
diff --git a/docs/_static/img/image3.png b/docs/_static/img/image3.png
diff --git a/docs/_static/img/image4.png b/docs/_static/img/image4.png
diff --git a/docs/media/image72.jpg → docs/_static/img/image5.jpg b/docs/media/image72.jpg → docs/_static/img/image5.jpg
diff --git a/docs/media/image73.jpg → docs/_static/img/image6.jpg b/docs/media/image73.jpg → docs/_static/img/image6.jpg
diff --git a/docs/media/image74.jpg → docs/_static/img/image7.jpg b/docs/media/image74.jpg → docs/_static/img/image7.jpg
diff --git a/docs/_static/img/image8.png b/docs/_static/img/image8.png
diff --git a/docs/_static/img/image9.png b/docs/_static/img/image9.png
diff --git a/docs/media/image_cng_tanks.png → docs/_static/img/image_cng_tanks.png b/docs/media/image_cng_tanks.png → docs/_static/img/image_cng_tanks.png
diff --git a/docs/media/image_eff_fitting_1.png → docs/_static/img/image_eff_fitting_1.png b/docs/media/image_eff_fitting_1.png → docs/_static/img/image_eff_fitting_1.png
diff --git a/docs/media/image_eff_fitting_2.png → docs/_static/img/image_eff_fitting_2.png b/docs/media/image_eff_fitting_2.png → docs/_static/img/image_eff_fitting_2.png
diff --git a/docs/media/image_engine_downsizing.png → docs/_static/img/image_engine_downsizing.png b/docs/media/image_engine_downsizing.png → docs/_static/img/image_engine_downsizing.png
diff --git a/docs/media/image_noise_1.png → docs/_static/img/image_noise_1.png b/docs/media/image_noise_1.png → docs/_static/img/image_noise_1.png
diff --git a/docs/media/image_noise_2.png → docs/_static/img/image_noise_2.png b/docs/media/image_noise_2.png → docs/_static/img/image_noise_2.png
diff --git a/docs/media/image_sulfur_countries.png → docs/_static/img/image_sulfur_countries.png b/docs/media/image_sulfur_countries.png → docs/_static/img/image_sulfur_countries.png
diff --git a/docs/media/image_truck_resistance.png → docs/_static/img/image_truck_resistance.png b/docs/media/image_truck_resistance.png → docs/_static/img/image_truck_resistance.png
diff --git a/docs/_static/img/vecto_validation.png b/docs/_static/img/vecto_validation.png
diff --git a/docs/_static/resources/examples.zip b/docs/_static/resources/examples.zip
diff --git a/docs/annexes.rst b/docs/annexes.rst
@@ -114,3 +114,5 @@ used to calibrate ``carculator_truck`` are shown in the table below.
 +------------------+--------+---------+------------+----------------------------+-------------------------------+-------------------+-------------------------+-------------------------+--------------------------------------+
 | Class 8 Aero     | DayCab | PHEV-d  | 40         | 510                        | 280                           | 510               | 55%                     |                         |                                      |
 +------------------+--------+---------+------------+----------------------------+-------------------------------+-------------------+-------------------------+-------------------------+--------------------------------------+
+
+
diff --git a/docs/api.rst b/docs/api.rst
@@ -12,7 +12,7 @@ Truck Input Parameter
 Array
 -----
 
-.. automodule:: carculator_truck.array
+.. automodule:: carculator_utils.array
     :members:
 
 Driving cycle
@@ -24,25 +24,25 @@ Driving cycle
 Energy consumption
 ------------------
 
-.. automodule:: carculator_truck.energy_consumption
+.. automodule:: carculator_utils.energy_consumption
     :members:
 
-Car Model
----------
+Truck Model
+-----------
 
 .. automodule:: carculator_truck.model
     :members:
 
 Noise Model
 -----------
 
-.. automodule:: carculator_truck.noise_emissions
+.. automodule:: carculator_utils.noise_emissions
     :members:
 
 Hot pollutants emissions
 ------------------------
 
-.. automodule:: carculator_truck.hot_emissions
+.. automodule:: carculator_utils.hot_emissions
     :members:
 
 Inventory calculation
@@ -54,7 +54,7 @@ Inventory calculation
 Inventory export
 ----------------
 
-.. automodule:: carculator_truck.export
+.. automodule:: carculator_utils.export
     :members:
 
 Background systems

diff --git a/docs/conf.py b/docs/conf.py
@@ -14,7 +14,7 @@
 import sys
 
 # sys.path.insert(0, os.path.abspath('C:\Users\sacchi_r\Documents\GitHub\coarse\coarse'))
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.append(os.path.abspath(".."))
 
 
 # -- Project information -----------------------------------------------------
@@ -24,7 +24,7 @@
 author = "Romain Sacchi"
 
 # The full version, including alpha/beta/rc tags
-release = "0.3.8"
+release = "0.3.9"
 
 
 # -- General configuration ---------------------------------------------------
@@ -36,7 +36,6 @@
     "sphinx.ext.autodoc",
     "sphinxcontrib.bibtex",
     "sphinx_copybutton",
-    "sphinx_design",
     "sphinx_immaterial",
 ]
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -3,8 +3,8 @@
 
 .. _intro:
 
-Welcome to Carculator truck’s documentation
-===========================================
+Carculator Truck
+================
 
 ``carculator_truck`` is a parameterized model that allows to generate and characterize life cycle inventories for different
 truck configurations, according to selected:

diff --git a/docs/media/image70.png b/docs/media/image70.png
diff --git a/docs/media/image71.png b/docs/media/image71.png
diff --git a/docs/media/image76.png b/docs/media/image76.png
diff --git a/docs/media/image77.png b/docs/media/image77.png
diff --git a/docs/media/image78.png b/docs/media/image78.png
diff --git a/docs/media/image80.png b/docs/media/image80.png
diff --git a/docs/media/image81.png b/docs/media/image81.png
diff --git a/docs/media/image82.png b/docs/media/image82.png
diff --git a/docs/media/image84.png b/docs/media/image84.png
diff --git a/docs/media/image85.png b/docs/media/image85.png
diff --git a/docs/media/image86.png b/docs/media/image86.png
diff --git a/docs/media/image87.png b/docs/media/image87.png
diff --git a/docs/media/image88.png b/docs/media/image88.png
diff --git a/docs/media/image89.png b/docs/media/image89.png
diff --git a/docs/media/image90.png b/docs/media/image90.png
diff --git a/docs/media/image91.png b/docs/media/image91.png
diff --git a/docs/media/image92.png b/docs/media/image92.png