Added documentation

matsim.py

@@ -1,3 +1,10 @@
+"""
+EnergySystemsFactory exports energy systems into several formats
+SPDX - License - Identifier: LGPL - 3.0 - or -later
+Copyright © 2022 Concordia CERC group
+Project Coder Ruben Sanchez r_nch@mail.concordia.com
+"""
+
 import math
 import subprocess
 import gzip
@@ -15,6 +22,12 @@ POPULATION_DTD = "http://www.matsim.org/files/dtd/population_v5.dtd"
 
 class Matsim:
   def __init__(self, city, output_file_path):
+    """
+    Constructs a Matsim exporter instance with a city object and an output file path.
+
+    :param city: The city object
+    :param output_file_path: The directory path where all exported files will be stored.
+    """
     self._city = city
     self._output_file_path = output_file_path
 
@@ -24,12 +37,18 @@ class Matsim:
     }
 
   def export(self):
+    """
+    Coordinates the export process for all city data components.
+    """
     self._export_facilities()
     self._export_network()
     self._export_population()
     self._export_config()
 
   def _export_facilities(self):
+    """
+    Exports the city's facilities data to XML and shapefile formats.
+    """
     buildings_shape_data = {
       'id': [],
       'geometry': []
@@ -102,6 +121,9 @@ class Matsim:
     _save_xml(output_file, xml_content, f"<!DOCTYPE facilities SYSTEM \"{FACILITIES_DTD}\">\n", True)
 
   def _export_network(self):
+    """
+    Generates a transportation network file from the city's OpenStreetMap data and buildings shapefile.
+    """
     java_path = "java"
     jar_path = "matsim-network-from-osm.jar"
     command = [
@@ -114,6 +136,9 @@ class Matsim:
     subprocess.run(command)
 
   def _export_population(self):
+    """
+    Generates and exports the city's population data to an XML file.
+    """
     population = etree.Element("population")
     id = 0
 
@@ -191,6 +216,9 @@ class Matsim:
     _save_xml(output_file, xml_content, f"<!DOCTYPE population SYSTEM \"{POPULATION_DTD}\">\n", True)
 
   def _export_config(self):
+    """
+    Creates and exports the simulation configuration settings to an XML file.
+    """
     root = etree.Element('config')
 
     # ======== NETWORK ========= #
@@ -366,6 +394,13 @@ class Matsim:
 
 
 def _add_param(parent, name, value):
+  """
+  Helper function to add a parameter to an XML element.
+
+  :param parent: The parent XML element to which the parameter should be added.
+  :param name: The name of the parameter.
+  :param value: The value of the parameter.
+  """
   etree.SubElement(parent, "param", {
     'name': name,
     'value': value
@@ -373,6 +408,13 @@ def _add_param(parent, name, value):
 
 
 def _add_parameterset(parent, type, parameters):
+  """
+  Helper function to add a set of parameters to an XML element.
+
+  :param parent: The parent XML element to which the parameterset should be added.
+  :param type: The type attribute for the parameterset.
+  :param parameters: A list of tuples, each containing the name and value of a parameter.
+  """
   parameterset = etree.SubElement(parent, "parameterset", {
     'type': type
   })
@@ -381,6 +423,12 @@ def _add_parameterset(parent, type, parameters):
 
 
 def _convert_schedules(building_schedules):
+  """
+  Converts building schedules into a format suitable for facilities.xml.
+
+  :param building_schedules: A list of building schedule objects to be converted.
+  :return: A list of dictionaries, each representing the converted schedule for a building.
+  """
   converted_schedules = []
   opening_hour = 0
   closing_hour = 0
@@ -408,6 +456,14 @@ def _convert_schedules(building_schedules):
 
 
 def _save_xml(output_file, xml_content, xml_dtd=None, zipped=None):
+  """
+  Saves XML content to a file, optionally adding a DOCTYPE declaration and compressing the file.
+
+  :param output_file: The path where the XML file will be saved.
+  :param xml_content: The XML content to be written to the file.
+  :param xml_dtd: An optional DOCTYPE declaration to be included at the beginning of the file.
+  :param zipped: If True, the output file will be compressed using gzip.
+  """
   if zipped is None:
     zipped = False