Improve documentation

CHANGELOG.md

@@ -23,6 +23,10 @@ Here is a template for new release sections
 
 ### Added
 - Tests have been added which check if the examples of pvcompare run with exit code 0 (#284)
+- Added basic model assumptions to RTD and introduced section "local energy system" in Model assumptions in RTD (#286)
+- Added headings in `parameters.rst` to make references of these sections possible in RTD (#286)
+- Improved "scope and limitations" section of RTD with additional information and corrections (#286)
+
 ### 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)
 - Improved "how to release" section in `contributing.md` with insights from last release (#275)

README.rst

@@ -32,13 +32,14 @@ The functionalities include
 
 * calculation of an area potential for PV on roof-tops and facades based on building parameters,
 * calculation of heat and electricity demand profiles for a specific amount of people living in these buildings,
-* calculation of PV feed-in time series for a set of PV installations on roof-tops and facades incl. different technologies,
+* calculation of PV feed-in time series for a set of PV installations on roof-tops and façades incl. different technologies,
 
     * all technologies in the database of `pvlib <https://pvlib-python.readthedocs.io/en/stable/index.html>`_,
-    * a specific concentrator-PV module, and
-    * a module of silicon-perovskite cells,
+    * a specific concentrator-PV module (see :ref:`cpv`) and
+    * a module of silicon-perovskite cells (see :ref:`psi`),
 
 * calculation of temperature dependent COPs or respectively EERs for heat pumps and chillers,
+* download and formatting of `ERA5 weather data <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_ (global reanalysis data set),
 * preparation of data and input files for the energy system optimization,
 * a sensitivity analysis for input parameters and
 * visualisations for the comparison of different technologies.
@@ -58,7 +59,7 @@ Installation
 
 To install *pvcompare* follow these steps:
 
-- Clone *pvcompare* and navigate to the directory ``\pvcompare`` containing the ``setup.py`` and ``requirements.txt``:
+- Clone *pvcompare* and navigate to the directory ``\pvcompare`` containing the ``setup.py``:
 
 ::
 
@@ -83,4 +84,4 @@ Contributing
 
 We are warmly welcoming all who want to contribute to *pvcompare*.
 Please read our `Contributing Guidelines <https://github.com/greco-project/pvcompare/blob/dev/CONTRIBUTING.md>`_.
-
+You can also get in contact by writing an `issue on github <https://github.com/greco-project/pvcompare/issues/new/choose>`_.

docs/model_assumptions.rst

@@ -4,65 +4,77 @@
 Model assumptions
 ~~~~~~~~~~~~~~~~~
 
+The energy system optimization is a linear optimization that minimizes the costs of the
+energy system. Depending on the input parameters single components or all components of
+the energy system underlie an investment optimization. Certain constraints like a maximum
+installed capacity, a maximum amount of greenhouse gas / CO2 emissions or the requirement
+of forming a net zero energy (NZE) *community*, if applied, have to be met.
+Check out the `model equations <https://multi-vector-simulator.readthedocs.io/en/v0.5.5/Model_Equations.html#>`_
+and `model assumptions <https://multi-vector-simulator.readthedocs.io/en/v0.5.5/Model_Assumptions.html#>`_ of MVS for detailed information.
+
+.. _local_energy_system:
+
+Local energy sytem
+==================
+
 .. _building_assumptions:
 
 Building assumptions
-====================
+--------------------
 
-The demand profiles that are introduced in the next sections are based on so called
-standard load profiles. These standard load profiles are generated for around 500-1000
-Household, therefore the curve is flattened and cannot be compares to the load curve of
-a single household. This is why the *pvcompare* simulations are based on *NZE communities*
-reather than a single *NZE building*. As a consequence all simulations are run over a
-number of 400 identical buildings. In order to interpret the simulation results for
-a single building, the total demand / production can be devided by 400. (TODO: is this correct??)
+The analyzed local energy system is assumed to belong to an urban neighbourhood with a specific
+number of buildings. A minimum amount of buildings is required when using the functionalities
+for calculating demand profiles of *pvcompare*, which are introdcued in :ref:`demand`. They are based on standard load
+profiles that are generated for around 500-1000 households. These load profiles are therefore flattened compared to load profiles of
+single households.
+The amount of buildings, households per storey, number of people per household and further parameters
+can be adjusted in the inputs file :ref:`building_parameters`; the default is a number of 20 buildings.
 
 In general we assume an urban environment that allows high solar exposure without shading
 from surrounding buildings or trees.
 
 The stardard building is constructed with defined building parameters, such as
 
-* length south facade
-* length eastwest facade
+* length south façade
+* length eastwest façade
 * total storey area
 * hight of storey
 * population per storey
 
-All building parameters are contained in 'data/static_inputs/building_parameters.csv'.
-The construction of the buidling, as well as the available facades for PV usage
+The construction of the buidling, as well as the available façades for PV usage
 are based on the research of `Hachem, 2014 <https://www.sciencedirect.com/science/article/abs/pii/S0306261913009112>`_.
 
 The default building parameters are based on the following assumptions that have
 been adopted from `Hachem, 2014 <https://www.sciencedirect.com/science/article/abs/pii/S0306261913009112>`_:
-
-Each storey (with a total area of 1232 m²) is defided into 8 flats, each 120 m². The rest of the
+Each storey (with a total area of 1232m²) is divided into 8 flats of 120m² each. The rest of the
 storey area is used for hallway and staircases etc. Each of the 8 flats is inhabited
 by 4 people, meaning in average 30m² per person (it is assumed that a NZE building
 is operated efficiently). Therefore the number of persons per storey is set to 32.
 
+All building parameters can be adjusted in the inputs file :ref:`building_parameters`.
 
 Exploitation for PV Installation
 --------------------------------
 
 It is assumed that PV systems can cover "50% of the south façade
 area, starting from the third floor up, and 80% of the east and west
 façades." (`Hachem, 2014 <https://www.sciencedirect.com/science/article/abs/pii/S0306261913009112>`_.)
-The facades of the first two floors are discarded for PV installation because of
+The façades of the first two floors are discarded for PV installation because of
 shading.
 
 It is possible to simulate a gable roof as well as a flat roof. For the gable roof it
 is assumed that only the south facing area is used for PV installations. Assuming
 an elevation of 45°, the gable roof area facing south equals 70% of the total floor area.
 
 For a flat roof area available to PV installations is assumed to be 40% of the
-total floor area, due to shading between the modules (see `Energieatlas <https://energieatlas.berlin.de/Energieatlas_Be/Docs/Datendokumentation-Solarkataster_BLN.pdf>`_.
+total floor area, due to shading between the modules (see `Energieatlas <https://energieatlas.berlin.de/Energieatlas_Be/Docs/Datendokumentation-Solarkataster_BLN.pdf>`_).
 
 Maximum Capacity
 ----------------
 With the help of the calculated available area for PV exploitation, the maximum
 capacity can be calculated. The maximum capacity, given in
 the unit of kWp, depends on the size and the efficiency of the specific PV technology.
-It serves as a limit for the investment optimization with MVS.
+It serves as a limit (constraint) for the investment optimization.
 It is calculated as follows:
 
 .. math::
@@ -100,6 +112,8 @@ conditions the following methods are selected from `modelchain object <https://p
 - temperature_model="sapm"
 - losses_model="pvwatts"
 
+.. _cpv:
+
 2. CPV
 ------
 
@@ -203,8 +217,9 @@ week measurement in Madrid in May 2019. The Data can be found in
 `Zenodo <https://zenodo.org/record/3346823#.X46UDZpCT0o>`_ ,
 whereas the performance testing of the test module is described in `Askins, et al. (2019) <https://zenodo.org/record/3349781#.X46UFZpCT0o>`_.
 
+.. _psi:
 
-2. PeroSi
+3. PeroSi
 ---------
 The perovskite-silicon cell is a high-efficiency cell that is still in its
 test phase. Because perovskite is a material that is easily accessible many
@@ -520,4 +535,4 @@ To model a water or brine source chiller, you can either
         mode,technology,quality_grade,temp_high,temp_low,factor_icing,temp_threshold_icing
         chiller,water-water,0.3,25,15,None,None
 
-    (In this example with constant outlet temperature **temp_high**)
+    (In this example with constant outlet temperature **temp_high**)

docs/parameters.rst

@@ -18,7 +18,8 @@ relevant parameters of *MVS* can be found in the `documentation of MVS <https://
 The values used by default in *pvcompare* for the above parameters in each CSV, are detailed below.
 Some parameters can be calculated automatically by *pvcompare* and do not need to be filled it by hand. These parameters are marked with * *auto_calc*.
 
-* project_data.csv
+project_data.csv
+----------------
     1. **country**: str, Spain (the country in which the project is located), * *auto_calc*
     2. **label**: str, project_data
     3. **latitude**: str, 45.641603 * *auto_calc*
@@ -27,14 +28,16 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     6. **project_name**: str, net zero energy community
     7. **scenario_description**: str, Simulation of scenario scenario_name
 
-* economic_data.csv
+economic_data.csv
+-----------------
     1. **curency**: str, EUR (stands for euro; can be replaced by SEK, if the system is located in Sweden, for instance).
     2. **discount_factor**: factor, 0.06 (most recent data is from 2018, as documented by this market `survey <https://www.grantthornton.co.uk/insights/renewable-energy-discount-rate-survey-2018/>`_.
     3. **label**: str, economic_data
     4. **project_duration**: year, 1 (number of years)
     5. **tax**: factor, 0 (this feature has not been implemented yet, as per MVS documentation)
 
-* simulation_settings.csv
+simulation_settings.csv
+-----------------------
     1. **evaluated_period**: days, 365 (number of days),  * *auto_calc*
     2. **label**: str, simulation_settings
     3. **output_lp_file**: bool, False
@@ -45,7 +48,8 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     8. **display_nx_graph**: bool, False
     9. **store_nx_graph**: bool ,True
 
-* fixcost.csv
+fixcost.csv
+-----------
     +----------------------+-------------------+----------------------------------+------------------+-----------------------+
     |                      |        Unit       |        distribution_grid         | engineering      |       operation       |
     +======================+===================+==================================+==================+=======================+
@@ -63,7 +67,8 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     +----------------------+-------------------+----------------------------------+------------------+-----------------------+
     |  **dispatch_price**  |    currency/kWh   |                0                 |         0        |           0           |
     +----------------------+-------------------+----------------------------------+------------------+-----------------------+
-* energyConsumption.csv
+energyConsumption.csv
+---------------------
     1. **dsm**: str, False (dsm stands for Demand Side Management. This feature has not been implement in MVS as of now.)
     2. **file_name**: str, electricity_load.csv
     3. **label**: str, Households
@@ -73,7 +78,8 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     7. **inflow_direction**: str, Electricity
     8. **unit**: str, kW
 
-* energyConversion.csv
+energyConversion.csv
+--------------------
     1. **age_installed**: year, 0 (for all components such as charge controllers, inverters, heat pumps, gas boilers)
     2. **development_costs**: currency, 0 (for all components)
     3. **specific_costs**: currency/kW
@@ -156,7 +162,8 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     14. **type_oemof**: str, transformer (same for all the components)
     15. **unit**: str, kW (applies to all the components)
 
-* energyProduction.csv:
+energyProduction.csv
+--------------------
     1. **age_installed**: year, 0 (for all the components)
     2. **development_costs**: currency, 0 (**TO BE DECIDED**)
     3. **specific_costs**: currency/unit, (**TO BE DECIDED**)
@@ -181,7 +188,9 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     13. **type_oemof**: str, source (for all of the components)
     14. **unit**: str, kWp (for all of the components)
     15. **energyVector**: str, Electricity (for all of the components)
-* energyProviders.csv:
+
+energyProviders.csv
+-------------------
     1. **energy_price**: currency/kWh,
         a. **Electricity grid**: 0.24  * *auto_calc* (0.24 €/kWh is the average household electricity price of Spain for 2019S1. Obtained from `Eurostat <https://ec.europa.eu/eurostat/statistics-explained/images/d/d9/Electricity_prices%2C_first_semester_of_2017-2019_%28EUR_per_kWh%29.png>`_.)
         b. **Gas plant**: 0.0598 * *auto_calc* (0,0598 €/kWh for Germany and 0.072 €/kWh for Spain (2019 / 2020) - Values read in depending on location obtained from `Eurostat's statistic of gas prices <https://ec.europa.eu/eurostat/databrowser/view/ten00118/default/table?lang=en>`_)
@@ -205,15 +214,19 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
     11. **emission factor**: kgCO2eq/kWh
         a. **Electricity grid**: 0.338
         b. **Gas plant**: 0.2 (Obtained from `Quaschning 06/2015 <https://www.volker-quaschning.de/datserv/CO2-spez/index_e.php>`_.)
-* energyStorage.csv:
+
+energyStorage.csv
+-----------------
     1. **inflow_direction**: str, ESS Li-Ion
     2. **label**: str, ESS Li-Ion
     3. **optimizeCap**: bool, True
     4. **outflow_direction**: str, ESS Li-Ion
     5. **type_oemof**: str, storage
     6. **storage_filename**: str, storage_01.csv
     7. **energyVector**: str, Electricity
-* storage_01.csv:
+
+storage_01.csv
+--------------
     1. **age_installed**: year, 0 (for all components)
     2. **development_costs**: currency, 0 (for all components)
     3. **specific_costs**: currency/unit
@@ -254,7 +267,8 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
 
         b. **input power** and **output power**: kW
 
-* storage_02.csv:
+storage_02.csv
+--------------
     1. **age_installed**: year, 0 (for all components of the stratified thermal storage)
     2. **development_costs**: currency, 0 (for all components of the stratified thermal storage)
     3. **specific_costs**: currency/unit
@@ -315,15 +329,21 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
 In order to run *pvcompare*, a number of input parameters are needed; many of which are stored in csv files with default values in ``pvcompare/pvcompare/inputs/``.
 The following list will give a brief introduction into the description of the csv files and the source of the given default parameters.
 
-* pv_setup.csv:
+.. _pv_setup:
+
+pv_setup.csv
+------------
     *The pv_setup.csv defines the number of facades that are covered with pv-modules.*
 
     1. **surface_type**: str, optional values are "flat_roof", "gable_roof", "south_facade", "east_facade" and "west_facade"
     2. **surface_azimuth**: integer, between -180 and 180, where 180 is facing south, 90 is facing east and -90 is facing west
     3. **surface_tilt**: integer, between 0 and 90, where 90 represents a vertical module and 0 a horizontal.
     4. **technology**: str, optional values are "si" for a silicone module, "cpv" for concentrator photovoltaics and "psi" for a perovskite silicone module
 
-* building_parameters:
+.. _building_parameters:
+
+building_parameters.csv
+-----------------------
     *Parameters that describe the characteristics of the building that should be considered in the simulation. The default values are taken from [1].*
 
     1. **number of storeys**: int
@@ -343,7 +363,8 @@ The following list will give a brief introduction into the description of the cs
     15. **filename_residential_electricity_demand**: str, name of the csv file that contains the total residential electricity demand for EU countries in different years [2] *
     16. **filename_country_population**: str, name of the csv file that contains population for EU countries in different years [2] *
 
-* heat_pumps_and_chillers:
+heat_pumps_and_chillers.csv
+---------------------------
     *Parameters that describe characteristics of the heat pumps and chillers in the simulated energy system.*
     *Values below assumed for each heat pump technology from research and comparison of three models, each of a different manufacturer.*
     *For each technology the quality grade has been calculated from the mean quality grade of the three models.*
@@ -368,7 +389,8 @@ The following list will give a brief introduction into the description of the cs
     5. **factor_icing**: float or None, COP reduction caused by icing, only for `mode` 'heat_pump', default: None
     6. **temp_threshold_icing**: float or None, Temperature below which icing occurs, only for `mode` 'heat_pump', default: None
 
-* stratified_thermal_storage.csv:
+stratified_thermal_storage.csv
+------------------------------
     *Parameters that describe characteristics of the stratified thermal storage in the simulated energy system.*
     *The parameters have been set on the example of the stratified thermal storage TH 1000 of Schindler+Hofmann GmbH &  Co. KG*
 
@@ -382,7 +404,8 @@ The following list will give a brief introduction into the description of the cs
     8. **alpha_inside**: 4.3 (Calculated with calculations in [6]), W/(m2*K)
     9. **alpha_outside** 3.17 (Calculated with calculations in [6]), W/(m2*K)
 
-* list_of_workalendar:
+list_of_workalendar_countries.csv
+---------------------------------
     *list of countries for which a python.workalendar [3] exists with the column name "country".*