Merge pull request #3 from iSOLveIT/master

Restructure documentation website

.gitignore

@@ -131,3 +131,4 @@ venv.bak/
 
 # IntelliJ
 /out/
+.idea/

README.md

@@ -1,7 +1,7 @@
 # ``carculator_bus``
 
 <p align="center">
-  <img style="height:130px;" src="https://github.com/romainsacchi/coarse/raw/master/docs/mediumsmall.png">
+  <img style="height:130px;" src="docs/_static/img/mediumsmall.png">
 </p>
 
 <p align="center">
@@ -23,20 +23,23 @@ See [the documentation](https://carculator_bus.readthedocs.io/en/latest/index.ht
 
 ## How to install?
 
-For the latest version, using conda::
+For the latest version, using conda:
 
-    conda install -c romainsacchi carculator_bus
+```bash
+conda install -c romainsacchi carculator_bus
+```
 
-or for a stable release, from Pypi::
+or for a stable release, from Pypi:
 
-    pip install carculator_bus
-
-
-No extensive documentation right now, but check out the examples notebook.
+```bash
+pip install carculator_bus
+```
+
+No extensive documentation right now, but check out the examples' notebook.
 
 ## How to use it?
 
-See the notebook with [examples](https://github.com/romainsacchi/carculator_bus/blob/master/examples/buses.ipynb).
+See the notebook with [examples](examples/buses.ipynb).
 
 ## Support
 
@@ -49,8 +52,8 @@ Do not hesitate to contact the development team at [carculator@psi.ch](mailto:ca
 
 ## Contributing
 
-See [contributing](https://github.com/romainsacchi/carculator_bus/blob/master/CONTRIBUTING.md).
+See [contributing](CONTRIBUTING.md).
 
 ## License
 
-[BSD-3-Clause](https://github.com/romainsacchi/carculator_bus/blob/master/LICENSE). Copyright 2020 Paul Scherrer Institut.
+[BSD-3-Clause](LICENSE). Copyright 2020 Paul Scherrer Institut.

carculator_bus/__init__.py

@@ -9,7 +9,7 @@
 
 """
 
-_all_ = (
+__all__ = (
     "BusInputParameters",
     "fill_xarray_from_input_parameters",
     "BusModel",

carculator_bus/background_systems.py

@@ -8,12 +8,12 @@
 def get_sulfur_content_in_fuel():
     """
     Retrieve sulfur content per kg of petrol and diesel.
-    For CH, DE, FR, AU and SE, the concentration values come from HBEFA 4.1, from 1909 to 2020 (extrapolated to 2050).
+    For CH, DE, FR, AU and SE, the concentration values come from
+    `HBEFA 4.1 <https://www.hbefa.net/e/index.html>`_, from 1909 to 2020 (extrapolated to 2050).
 
-    For the other countries, values come from
-    Miller, J. D., & Jin, L. (2019). Global progress toward soot-free diesel vehicles in 2019.
-    International Council on Clean Transportation.
-    https://www.theicct.org/publications/global-progress-toward-soot-free-diesel-vehicles-2019
+    For the other countries, values come from the report by Miller, J. D., & Jin, L. (2019) titled
+    `Global progress toward soot-free diesel vehicles in 2019 <https://www.theicct.org/publications/global-progress-toward-soot-free-diesel-vehicles-2019>`_.
+    on the International Council on Clean Transportation website.
 
     There is an assumption made: countries that have high-sulfur content fuels (above 50 ppm in 2019) are assumed to
     improve over time to reach 50 ppm by 2050.
@@ -47,7 +47,7 @@ def get_sulfur_content_in_fuel():
 
 def get_biofuel_share():
     """
-    Retrieve shares of biofuel consumption from REMIND and shape them into an xarray.
+    Retrieve shares of biofuel consumption from REMIND and shape them into a xarray.
 
     :return: An axarray with 'country' and 'year' as dimensions
     :rtype: xarray.core.dataarray.DataArray
@@ -79,15 +79,16 @@ def get_biofuel_share():
 
 def get_electricity_mix():
     """
-    Retrieve electricity mixes and shape them into an xarray.
+    Retrieve electricity mixes and shape them into a xarray.
+
     Source:
-        * for European countries (`EU Reference Scenario 2016 <https://ec.europa.eu/energy/en/data-analysis/energy-modelling/eu-reference-scenario-2016>`_),
-        * for African countries (`TEMBA <http://www.osemosys.org/temba.html>`_ model)
-        * and for other countries (`IEA World Energy outlook 2017 <https://www.iea.org/reports/world-energy-outlook-2017>`_)
+
+    * for European countries (`EU Reference Scenario 2016 <https://ec.europa.eu/energy/en/data-analysis/energy-modelling/eu-reference-scenario-2016>`_),
+    * for African countries (`TEMBA <http://www.osemosys.org/temba.html>`_ model)
+    * and for other countries (`IEA World Energy outlook 2017 <https://www.iea.org/reports/world-energy-outlook-2017>`_)
 
     :returns: An axarray with 'country' and 'year' as dimensions
     :rtype: xarray.core.dataarray.DataArray
-
     """
     filename = "electricity_mixes.csv"
     filepath = DATA_DIR / filename
@@ -119,7 +120,6 @@ def get_region_mapping():
 
     :returns: dictionary
     :rtype: dict
-
     """
     filename = "region_mapping.csv"
     filepath = DATA_DIR / filename
@@ -146,7 +146,6 @@ def get_electricity_losses():
 
     :returns: dictionary
     :rtype: dict
-
     """
     filename = "cumulative_electricity_losses.csv"
     filepath = DATA_DIR / filename
@@ -169,9 +168,9 @@ class BackgroundSystemModel:
     """
     Retrieve and build dictionaries that contain important information to model in the background system:
 
-        * gross electricity production mixes from nearly all countries in the world, from 2015 to 2050.
-        * cumulative electricity transformation/transmission/distribution losses from high voltage to medium and low voltage.
-        * share of biomass-derived fuel in the total consumption of liquid fuel in the transport sector. Source: REMIND.
+    * gross electricity production mixes from nearly all countries in the world, from 2015 to 2050.
+    * cumulative electricity transformation/transmission/distribution losses from high voltage to medium and low voltage.
+    * share of biomass-derived fuel in the total consumption of liquid fuel in the transport sector. Source: REMIND.
     """
 
     def __init__(self):

carculator_bus/driving_cycles.py

@@ -3,6 +3,12 @@
 
 
 def get_driving_cycle(size: list) -> np.ndarray:
+    """
+    Get driving cycle.
+
+    :param size: List of vehicle sizes.
+    :returns: :meth:`ndarray` object
+    """
     return get_standard_driving_cycle_and_gradient(
         vehicle_type="bus",
         vehicle_sizes=size,
@@ -11,6 +17,12 @@ def get_driving_cycle(size: list) -> np.ndarray:
 
 
 def get_road_gradient(size: list) -> np.ndarray:
+    """
+    Get road gradient data.
+
+    :param size: List of vehicle sizes.
+    :returns: :meth:`ndarray` object
+    """
     return get_standard_driving_cycle_and_gradient(
         vehicle_type="bus",
         vehicle_sizes=size,

carculator_bus/inventory.py

@@ -1,5 +1,6 @@
 """
-inventory.py contains Inventory which provides all methods to solve inventories.
+inventory.py contains the InventoryBus subclass which inherits from the Inventory class
+that provides all methods to solve inventories.
 """
 
 import numpy as np
@@ -14,17 +15,15 @@
 
 class InventoryBus(Inventory):
     """
-    Build and solve the inventory for results
-    characterization and inventory export
-
+    Build and solve the inventory for results characterization and inventory export
     """
 
     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
         """
 
         # Assembly

carculator_bus/model.py

@@ -50,19 +50,20 @@ def set_all(self):
         of the car, costs, etc.
 
         :meth:`set_component_masses()`, :meth:`set_car_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
-        by the `daily distance` the truck has. `power` is also varying with `curb_mass`.
+        `combustion engine mass`, `electric engine mass`. `energy battery mass` is influenced by the `curb mass`
+        but also by the `daily distance` the truck has. `power` is also varying with `curb_mass`.
 
         The current solution is to loop through the methods until either:
+
         * the change in curb mass between two iterations is inferior to 2%.
         * or the number of vehicles with a solution has been stable for the last 3 iterations
         * and that there has been at least 7 iterations
+
         It is then assumed that the buses are correctly sized.
 
         :returns: Does not return anything. Modifies ``self.array`` in place.
-
         """
 
         diff = 1
@@ -405,7 +406,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]
@@ -502,7 +502,6 @@ def calculate_ttw_energy(self):
         """
         This method calculates the energy required to operate auxiliary services as well
         as to move the car. The sum is stored under the parameter label "TtW energy" in :attr:`self.array`.
-
         """
         self.energy = self.ecm.motive_energy_per_km(
             driving_mass=self["driving mass"],
@@ -609,7 +608,7 @@ def calculate_ttw_energy(self):
 
     def set_battery_fuel_cell_replacements(self):
         """
-        This methods calculates the number of replacement batteries needed
+        These methods calculate 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.
@@ -668,12 +667,11 @@ def set_vehicle_masses(self):
         """
         Define ``curb mass``, ``driving mass``, and ``total cargo mass``.
 
-            * `curb mass <https://en.wikipedia.org/wiki/Curb_weight>`__ is the mass of the vehicle and fuel, without people or cargo.
-            * ``total cargo mass`` is the mass of the cargo and passengers.
-            * ``driving mass`` is the ``curb mass`` plus ``total cargo mass``.
+        * `curb mass <https://en.wikipedia.org/wiki/Curb_weight>`__ is the mass of the vehicle and fuel, without people or cargo.
+        * ``total cargo mass`` is the mass of the cargo and passengers.
+        * ``driving mass`` is the ``curb mass`` plus ``total cargo mass``.
 
-        .. note::
-            driving mass = total cargo mass + driving mass
+        .. note:: driving mass = total cargo mass + driving mass
 
         """
 
@@ -1370,11 +1368,11 @@ 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:
 
-            * Purchase
-            * Maintentance
-            * Component replacement
-            * Energy
-            * Total cost of ownership
+        * Purchase
+        * Maintenance
+        * Component replacement
+        * Energy
+        * Total cost of ownership
 
         :return: a_matrix xarray array with cost information per vehicle-km
         :rtype: xarray.core.dataarray.DataArray

docs/_static/css/custom.css

@@ -0,0 +1,65 @@
+body,
+input {
+    font-size: 16px !important;
+    font-weight: 400;
+    line-height: 1.5 !important;
+}
+
+.md-typeset, .md-nav, .md-typeset table:not([class]) {
+    font-size: 16px !important;
+    line-height: 1.4 !important;
+}
+
+.md-typeset table.data:not(.plain) td {
+	padding: .7031em 1.15em!important;
+}
+
+h1, h2, h3 {
+    font-weight: 500 !important;
+    line-height: 1.4 !important;
+}
+
+h1:not([class="md-search-result__title"]) {
+    font-size: 34px !important;
+    margin-bottom: 15px !important;
+}
+
+h2 {
+    font-size: 24px !important;
+    margin-bottom: 10px !important;
+}
+
+h3 {
+    font-size: 18px !important;
+    margin-bottom: 10px !important;
+}
+
+.underline {
+    text-decoration: underline;
+}
+
+tbody tr td {
+    font-size: medium !important;
+}
+
+table tbody tr {
+    background-color: transparent !important;
+}
+
+table tbody tr:hover {
+    background-color: rgb(147 147 147 / 10%) !important;
+    box-shadow: 0 .05rem 0 var(--md-default-bg-color) inset !important;
+}
+
+/*Remove READTHEDOCS version badge*/
+.injected {
+    display: none !important;
+}
+
+.md-typeset pre {
+    overflow-x: auto;
+}
+
+.md-header__button.md-logo :is(img, png) {
+    height: 2rem !important;
+}

docs/_static/tables/table_1.csv

@@ -0,0 +1,16 @@
+,"unit","Midibus, 9m","Single deck, city bus, 13m","Single deck, city bus, 18m","Double deck, city bus, 13m","Single deck, coach, 13m","Double deck, coach, 13m",Source
+Lifetime,year,14,"14 (20 for BEV-motion)","14 (20 for BEV-motion)",14,14,14,"Derived from the MOFIS vehicles registry :cite:`ct-1003`, a similar value used by :cite:`ct-1012` for buses"
+Annual kilometers,km,50’000,50’000,50’000,50’000,50’000,50’000,":cite:`ct-1130`"
+Lifetime,km,700’000,"(1’000’000,700’000 for BEV- motion)","(1’000’000,700’000 for BEV- motion)",700’000,700’000,700’000,Calculated from the two rows above.
+Average length,meter,9,13,18,13,13,13,Manufacturer s’ data.
+Number of axles,unit,2,2,3 (1 driven),3 (1 driven),2,3 (1 driven),
+Axles load distribution,% of the total load,"60% back, 40% front","60% back, 40% front","60% back, 20% middle, 20% front","60% back, 20% middle, 20% front","60% back, 40% front","60% back, 20% middle, 20% front",":cite:`ct-1024`"
+Rolling resistance coefficient,"unitless, per tire","0.0055","0.0055","0.0055","0.0055","0.0055","0.0055",
+Number of tires per axle,unit,"2 per non-driven axle, 4 per driven axle",,,,,,":cite:`ct-1024`"
+85% of tire load capacity,N,20’850,,,,,,
+Frontal area,square meter,"6.06","8.07","8.07","9.45","8.07","9.45",Calculated from manufacturer s’ data.
+Passengers capacity,unit,34,64,150,83,55,70,Manufacturer s’ data.
+Passengers occupancy,unit,5,10,19,13,21,26,Inferred from Mobitool factors v.2.1 values
+Load factor,,0.16,0.16,0.13,0.16,0.38,0.38,Calculated from the two rows above.
+Average passenger mass,kilogram,75,,,,,,Standard assumption
+Passenger luggage mass,kilogram,17,,,,,,":cite:`ct-1078`"

docs/_static/tables/table_2.csv

@@ -0,0 +1,9 @@
+,,City,,,Source,Comment
+powertrain,unit,BEV-opp,BEV-depot,BEV-motion,,
+Operation time per shift (in motion),hours,12,6,6,"Based on statistics from :cite:`ct-1036`",As shown above.
+Distance per shift,km,310,~155,~155,,
+Number of trips per shift,unit,8,5,8,,Calculated.
+Average speed,km/h,26,26,26,"VECTO :cite:`ct-1024`",Given by the driving cycle.
+Distance per trip,km,40,40,40,,Given by the driving cycle.
+Charging opportunity per trip,unit,1,\-,\-,,Assumed.
+Share of trip distance with catenary,ratio,\-,\-,0.4 - 0.7,"Based on :cite:`ct-1069` but further adjusted to match the battery sizes observed on the market.",

docs/_static/tables/table_3.csv

@@ -0,0 +1,9 @@
+,"EV charger, level 3, plug-in","EV charger, level 3, with pantograph",Catenary system
+Bus type,BEV-depot,BEV-opp,BEV-motion
+Power [kW],200,450,48
+Efficiency [%],95,90,95
+Source for efficiency,":cite:`ct-1011`",,":cite:`ct-1079`"
+Lifetime [years],24,24,40
+Number of buses allocated per charging system,2,10,60
+Source for inventories,":cite:`ct-1001, ct-1056`",,":cite:`ct-1079`"
+Comment,Assumed lifetime of 24 years. It is up-scaled to a 200 kW Level-3 charger by scaling the charger component up based on a mass of 1’290 kg given by AAB's 200 kW bus charger.,"The total mass is from AAB's 450 kW pantograph charger (1340 kg x 3) plus the charging interface (500 kg). But the material composition is extrapolated from the Level-2 charger :cite:`ct-1056`.",