Feature/usability: Allow input of precalculated time series and different SAM SI modules

CHANGELOG.md

@@ -30,6 +30,7 @@ Here is a template for new release sections
 - Add info on energy systems consisting of more than one node in RTD section "scope and limitations" (#293)
 - Added description of the implementation of the stratified thermal storage in pvcompare with a description of the possibilities modeling it (#291)
 - Dokumentation: Update on 'basic_usage', 'parameter description' and 'model assumptions' (#302)
+- Usability: allow the user to provide their own weather data, demand time series, pv time series and SAM SI modules (#317)
 
 ### Changed
 - The inlet temperatures of the heat pump and the stratified thermal storage have been revised in the pvcompare input parameters, adapting them in order to fit typical temperatures of the heating system. Also the pvcompare input parameters of the stratified thermal storage have been revised (#272)

docs/basic_usage.rst

@@ -12,6 +12,15 @@ Run a simulation
 You can easily run a simulation by executing one of the examples in `examples/ <https://github.com/greco-project/pvcompare/tree/master/examples>`_.
 There are three examples, one that accounts only for the electricity sector, one for sector coupling using heat pumps and one example covering heat demand with a gas plant as a reference scenario for the one with heat pumps.
 
+Here's an example energy system graph of a sector coupled scenario of the simulation provided in ``examples/run_pvcompare_example_sector_coupling.py``.
+
+.. figure:: ./images/basic_usage_energy_system_graph.png
+    :width: 100%
+    :alt: energy system graph.
+    :align: center
+
+    Energy system graph of an examplary sector coupled energy system.
+
 If you want to set up your own scenario, you need to insert input files into the directory first. How to do this is described in the next paragraph :ref:`define_params`.
 Afterwards you can run a simulation by running the file `run_pvcompare.py <https://github.com/greco-project/pvcompare/blob/master/run_pvcompare.py>`_ in the parent folder of *pvcompare*.
 In order to run a simulation you need to at least define the following parameters:
@@ -77,11 +86,62 @@ install the *cdsapi* package. `This page <https://cds.climate.copernicus.eu/api-
 
 Two example weather years for Berlin, Germany, 2017 and Madrid, Spain, 2017 are already added to ``data/static_inputs``.
 
-**Provide your own weather data**
+Provide your own input time series
+==================================
+
+*pvcompare* provides functionalities to automatically download weather data ad well as calculate demand and pv time series.
+If you want to use your own input time series, you
+can do so by defining them in the :py:func:`~.main.apply_pvcompare` function. The followning section gives you an overwiew
+on how to provide your time series.
+
+**Weather data**
+
+In oder to provide your own weather data, you need to insert the path
+to your weather file to the parameter ``add_weather_data`` in the :py:func:`~.main.apply_pvcompare` function. The file
+should contain an hourly time series in *csv* format with the columns: [time, latitude, longitude
+,ghi, dni, dhi, wind_speed, temp_air, precipitable_water].
+
+You can also download ERA5 data yourself. `oemof feedinlib <https://feedinlib.readthedocs.io/en/releases-0.1.0/load_era5_weather_data.html>`_ provides a jupyter notebook with instructions on how to download data for a single coordinate or a region.
+
+**Demand time series**
+
+In order to add your own heat and/or electricity time series add the path to the file to ``add_electricity_demand`` or ``add_heat_demand``
+in :py:func:`~.main.apply_pvcompare`. Note that the respective demand is only considered, if a column "Electricity demand" or "Heat demand"
+exists in ``data/user_inputs/mvs_inputs/csv_elements/energyConsumption.csv``.
+The demand time series should be given as an hourly time series in kW.
+
+**PV time series**
+
+You can add your own PV time series by defining ``add_pv_timeseries`` in :py:func:`~.main.apply_pvcompare`.
+Instead of just providing the path to the file, you need to define a dictionary with additional information
+on the PV module you are considering, in order to allow the calculation of the area potential for your module.
+The dictionary should be given as follows:
+    {"PV1" : ["filename": >path_to_time_series< , "module_size": >module_size in m²<,
+    "module_peak_power": >peak power of the module in kWp<, "surface_type": >surface_type for PV installation<],
+    "PV2" : [...], ...}
+You can add more than one module time series by defining more PV-keys.
+The PV time series itself needs to be be an normalized hourly time series in kW/kWp
+(normalized by the peak power of the module). The surface_types can be one of: [
+"flat_roof", "gable_roof", "south_facade", "east_facade", "west_facade"].
+
+Note that you need to add more specific PV parameters of your module (name, costs, lifetime etc.) in
+``user_inputs/mvs_inputs/csv_elements/energyProduction.csv``. The columns in ``energyProduction.csv``
+should be named "PV"+ key (e.g. "PV SI1") if your key is "SI1".
+
+When providing your own time series, ``overwrite_pv_parameters`` in :py:func:`~.main.apply_pvcompare` should be
+set to false. When ``add_pv_timeseries`` is used, the ``pv_setup.csv`` is disregarded.
+
+**Add a different SI module**
 
-As an alternative `oemof feedinlib <https://feedinlib.readthedocs.io/en/releases-0.1.0/load_era5_weather_data.html>`_ provides a jupyter notebook with instructions on how to download data for a single coordinate or a region.
+By default, the module "Aleo_Solar_S59y280" is loaded from `cec module <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_ database.
+But you can add another module from sandia or cec `libraries <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_.
 
+To do so, you need to define the parameter ``add_sam_si_module`` in :py:func:`~.main.apply_pvcompare`.
+You should define a dictionary with the library ("CECMod"  or "SandiaMod") as key and module name as value.
+E.g. {"cecmod":"Canadian_Solar_Inc__CS5P_220M"}.
 
+Note that the SI module is only considered if a module with the technology "SI" is provided in
+``user_inputs/mvs_inputs/pvcompare_inputs/pv_setup.csv``
 
 
 Add a sensitivy to your simulations

docs/model_assumptions.rst

@@ -98,6 +98,7 @@ unique models were developed for the CPV and PeroSi technologies. The next
 sections will provide a detailed description of the different modeling
 approaches.
 
+.. _si:
 1. SI
 -----
 The silicone module parameters are loaded from `cec module <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_ database. The module

pvcompare/demand.py

@@ -55,6 +55,8 @@ def calculate_load_profiles(
     static_inputs_directory=None,
     user_inputs_pvcompare_directory=None,
     user_inputs_mvs_directory=None,
+    add_electricity_demand=None,
+    add_heat_demand=None,
 ):
     """
     Calculates electricity and heat load profiles and saves them to csv.
@@ -81,6 +83,12 @@ def calculate_load_profiles(
         Default: None.
     user_inputs_mvs_directory : str or None
         Path to mvs input directory. If None: DEFAULT_USER_INPUTS_MVS_DIRECTORY. Default: None.
+    add_electricity_demand: str
+        Path to precalculated hourly electricity demand time series for one year (or the same period
+        of a precalculated PV timeseries)
+    add_heat_demand: str
+        Path to precalculated hourly heat demand time series for one year (or the same period
+        of a precalculated PV timeseries)
 
     Returns
     ------
@@ -105,28 +113,66 @@ def calculate_load_profiles(
     for column in energyConsumption:
         if column != "unit":
             if energyConsumption.at["energyVector", column] == "Heat":
-                calculate_heat_demand(
-                    country=country,
-                    lat=lat,
-                    lon=lon,
-                    storeys=storeys,
-                    year=year,
-                    weather=weather,
-                    static_inputs_directory=static_inputs_directory,
-                    user_inputs_pvcompare_directory=user_inputs_pvcompare_directory,
-                    user_inputs_mvs_directory=user_inputs_mvs_directory,
-                    column=column,
-                )
+
+                if add_heat_demand is not None:
+                    # check if file exists
+                    if os.path.isfile(add_heat_demand):
+                        # save the file name of the time series
+                        # mvs_inputs/elements/csv/energyProduction.csv
+                        check_inputs.add_file_name_to_energy_consumption_file(
+                            column=column,
+                            ts_filename=add_heat_demand,
+                            user_inputs_mvs_directory=user_inputs_mvs_directory,
+                        )
+                    else:
+                        logging.warning(
+                            "The heat demand time series"
+                            " you have entered does not exist. It is"
+                            " thus calculated according to the default"
+                            " method of pvcompare."
+                        )
+                else:
+                    calculate_heat_demand(
+                        country=country,
+                        lat=lat,
+                        lon=lon,
+                        storeys=storeys,
+                        year=year,
+                        weather=weather,
+                        static_inputs_directory=static_inputs_directory,
+                        user_inputs_pvcompare_directory=user_inputs_pvcompare_directory,
+                        user_inputs_mvs_directory=user_inputs_mvs_directory,
+                        column=column,
+                    )
             elif energyConsumption.at["energyVector", column] == "Electricity":
-                calculate_power_demand(
-                    country=country,
-                    storeys=storeys,
-                    year=year,
-                    static_inputs_directory=static_inputs_directory,
-                    user_inputs_pvcompare_directory=user_inputs_pvcompare_directory,
-                    user_inputs_mvs_directory=user_inputs_mvs_directory,
-                    column=column,
-                )
+
+                if add_electricity_demand is not None:
+
+                    if os.path.isfile(add_electricity_demand):
+                        # save the file name of the time series
+                        # mvs_inputs/elements/csv/energyProduction.csv
+                        check_inputs.add_file_name_to_energy_consumption_file(
+                            column=column,
+                            ts_filename=add_electricity_demand,
+                            user_inputs_mvs_directory=user_inputs_mvs_directory,
+                        )
+                    else:
+                        logging.warning(
+                            "The electricity demand time series"
+                            " you have entered does not exist. It is"
+                            " thus calculated according to the default"
+                            " method of pvcompare."
+                        )
+                else:
+                    calculate_power_demand(
+                        country=country,
+                        storeys=storeys,
+                        year=year,
+                        static_inputs_directory=static_inputs_directory,
+                        user_inputs_pvcompare_directory=user_inputs_pvcompare_directory,
+                        user_inputs_mvs_directory=user_inputs_mvs_directory,
+                        column=column,
+                    )
             else:
                 logging.warning(
                     "the given energyVector in energyConsumption.csv "
@@ -300,7 +346,7 @@ def calculate_power_demand(
     filename = os.path.join(timeseries_directory, el_demand_csv)
     shifted_elec_demand.to_csv(filename, index=False)
 
-    # save the file name of the time series and the nominal value to
+    # save the file name of the time series
     # mvs_inputs/elements/csv/energyProduction.csv
     check_inputs.add_file_name_to_energy_consumption_file(
         column=column,
@@ -502,7 +548,7 @@ def calculate_heat_demand(
     filename = os.path.join(timeseries_directory, h_demand_csv)
 
     shifted_heat_demand.to_csv(filename, index=False)
-    # save the file name of the time series and the nominal value to
+    # save the file name of the time series
     # mvs_inputs/elements/csv/energyProduction.csv
     check_inputs.add_file_name_to_energy_consumption_file(
         column=column,