greco-project · SabineHaas · Dec 8, 2020 · Dec 3, 2020 · Dec 3, 2020 · Dec 3, 2020
diff --git a/README.rst b/README.rst
@@ -2,10 +2,10 @@
 
 
 Introduction
-=============
+============
 
 *pvcompare* is a model that compares the benefits of different PV technologies in a specified energy system by running
-an oemof simulation. This model concentrates on the integration of PV technologies into local energy systems but could
+an energy system optimization. This model concentrates on the integration of PV technologies into local energy systems but could
 easily be enhanced to analyse other conversion technologies.
 
 The functionalities include
@@ -18,13 +18,18 @@ The functionalities include
     * a specific concentrator-PV module, and
     * a module of silicon-perovskite cells,
 
-* calulation of temperature dependent COPs or respectively EERs for heat pumps and chillers,
-* preparation of data and input files for the energy system simulation with `MVS <https://github.com/rl-institut/multi-vector-simulator>`_,
+* calculation of temperature dependent COPs or respectively EERs for heat pumps and chillers,
+* 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.
 
+The model is being developed within the scope of the H2020 project `GRECO <https://www.greco-project.eu/>`_.
+The energy system optimization is based on the `oemof-solph <https://oemof-solph.readthedocs.io/en/latest/>`_ python package,
+which *pvcompare* calls via the `Multi-Vector Simulator (MVS)  <https://github.com/rl-institut/multi-vector-simulator>`_, a
+tool for assessing and optimizing Local Energy Systems (LES).
+
 Documentation
-==============
+=============
 
 The full documentation can be found at `readthedocs <http://pvcompare.readthedocs.org>`_.
 
@@ -50,11 +55,12 @@ To install *pvcompare* follow these steps:
 - For the optimization you need to install a solver. Your can download the open source `cbc-solver <https://projects.coin-or.org/Cbc>`_ from https://ampl.com/dl/open/cbc/ . Please follow the installation `steps <https://oemof-solph.readthedocs.io/en/latest/readme.html#installing-a-solver>`_ in the oemof installation instructions. You also find information about other solvers there.
 
 Examples and basic usage
-=========================
-
+========================
+The basic usage of *pvcompare* is explained in section `Basic usage of pvcompare <https://github.com/greco-project/pvcompare/blob/dev/CONTRIBUTING.md>`_. TODO adapt link
+You can look into the section `Selected scenarios and results <https://github.com/greco-project/pvcompare/blob/dev/CONTRIBUTING.md>`_ for examples of simulations with *pvcompare*. TODO adapt link
 
 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>`_.

diff --git a/docs/about.rst b/docs/about.rst
@@ -0,0 +1,28 @@
+
+.. _about:
+
+About pvcompare
+~~~~~~~~~~~~~~~
+*pvcompare* is a model that compares the benefits of different PV technologies in a specified energy system by running
+an energy system optimization. This model concentrates on the integration of PV technologies into local energy systems but could
+easily be enhanced to analyse other conversion technologies.
+
+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,
+
+    * 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,
+
+* calculation of temperature dependent COPs or respectively EERs for heat pumps and chillers,
+* 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.
+
+The model is being developed within the scope of the H2020 project `GRECO <https://www.greco-project.eu/>`_.
+The energy system optimization is based on the `oemof-solph <https://oemof-solph.readthedocs.io/en/latest/>`_ python package,
+which *pvcompare* calls via the `Multi-Vector Simulator (MVS)  <https://github.com/rl-institut/multi-vector-simulator>`_, a
+tool for assessing and optimizing Local Energy Systems (LES).
diff --git a/docs/basic_usage.rst b/docs/basic_usage.rst
@@ -1,10 +1,21 @@
-========================
+
+.. _basic_usage:
+
 Basic usage of pvcompare
-========================
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _run_simulation:
+
+Run a simulation
+================
+
+You can easily run a simulation with *pvcompare* by running the file TODO (adjust after decision in #164).
+More information to follow.
 
----------------------------------------
-Definition of components and parameters
----------------------------------------
+.. _define_params:
+
+Define your own components and parameters
+=========================================
 
 *pvcompare* provides you with templates and default parameters for your simulations. However, you can also define your own energy system, choose different parameters and/or change the settings.
 
@@ -20,15 +31,16 @@ Especially interesting for adapting your simulations will be:
 - ``building_parameters.csv``: Definition of characteristics of the building type that should be considered in the simulation.
 - ``heat_pumps_and_chillers.csv``: Definition of characteristics of the heat pumps and chillers in the simulated energy system.
 
-A full description of the parameters can be found in the section :ref:`_parameters`.
+A full description of the parameters can be found in the section :ref:`parameters`.
+
 
---------------------------
 Download ERA5 weather data
---------------------------
+==========================
 Info follows, see #68.
 
-----------------------
-Sensitivity with loops
-----------------------
+
+
+Add a sensitivy to your simulations
+===================================
 
 Here follows a description of how to use the :py:func:`~.automated_loop` functionality.
diff --git a/docs/code.rst b/docs/code.rst
@@ -1,8 +1,9 @@
 .. currentmodule:: pvcompare
 
-==================
+.. _code:
+
 Code documentation
-==================
+~~~~~~~~~~~~~~~~~~
 
 .. _main:
 
@@ -147,6 +148,7 @@ Functions for plotting mvs results.
 
 .. autosummary::
     :toctree: temp/
+
     plots.plot_all_flows
     plots.plot_kpi_loop
 

diff --git a/docs/demand.rst b/docs/demand.rst
@@ -0,0 +1,5 @@
+
+.. _demand:
+
+Electricity and heat demand modeling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/examples.rst b/docs/examples.rst
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -2,30 +2,8 @@
 Getting started
 ==================
 
-Introduction
-=============
-
-*pvcompare* is a model that compares the benefits of different PV technologies in a specified energy system by running
-an oemof simulation. This model concentrates on the integration of PV technologies into local energy systems but could
-easily be enhanced to analyse other conversion technologies.
-
-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,
-
-    * 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,
-
-* calulation of temperature dependent COPs or respectively EERs for heat pumps and chillers,
-* preparation of data and input files for the energy system simulation with `MVS <https://github.com/rl-institut/multi-vector-simulator>`_,
-* a sensitivity analysis for input parameters and
-* visualisations for the comparison of different technologies.
-
 Documentation
-==============
+=============
 
 The full documentation can be found at `readthedocs <http://pvcompare.readthedocs.org>`_.
 
@@ -51,11 +29,12 @@ To install *pvcompare* follow these steps:
 - For the optimization you need to install a solver. Your can download the open source `cbc-solver <https://projects.coin-or.org/Cbc>`_ from https://ampl.com/dl/open/cbc/ . Please follow the installation `steps <https://oemof-solph.readthedocs.io/en/latest/readme.html#installing-a-solver>`_ in the oemof installation instructions. You also find information about other solvers there.
 
 Examples and basic usage
-=========================
-
+========================
+The basic usage of *pvcompare* is explained in section :ref:`basic_usage`.
+You can look into the section :ref:`scenarios-results` for examples of simulations with *pvcompare*.
 
 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>`_.
diff --git a/docs/heat_sector.rst b/docs/heat_sector.rst
@@ -0,0 +1,4 @@
+.. _heat-sector:
+
+Heat pump and thermal storage modeling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,20 +3,27 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to the PvCompare documentation!
-=======================================
+.. _welcome:
 
-Contents:
+Welcome to the documentation of pvcompare!
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+*pvcompare* is a model for comparing the benefits of different PV technologies in a specified local energy system in different energy supply scenarios.
 
 .. toctree::
    :maxdepth: 2
    :glob:
 
+   about
    getting_started
    basic_usage
+   model_assumptions
    pv_feedin
-   examples
+   demand
+   heat_sector
    parameters
+   simulation_outputs
+   scope_limits
+   scenarios_and_results
    code
 
 

diff --git a/docs/model_assumptions.rst b/docs/model_assumptions.rst
@@ -0,0 +1,5 @@
+
+.. _modelassumptions:
+
+Model assumptions
+~~~~~~~~~~~~~~~~~
diff --git a/docs/parameters.rst b/docs/parameters.rst
@@ -1,16 +1,16 @@
-=========================================================
-Parameters of pvcompare: Definitions and Default Values
-=========================================================
 .. _parameters:
 
+Parameters of pvcompare: Definitions and Default Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Within the ``pvcompare/pvcompare/data/`` directory, two separate categories of inputs can be observed.
 
 1. *MVS* parameters (found in the CSVs within the ``data/mvs_inputs/csv_elements/`` directory)
 2. *pvcompare*-specific parameters (found in the CSVs within the ``data/inputs`` directory)
 
-------------------
+
 1. MVS Parameters
-------------------
+=================
 
 As *pvcompare* makes use of the `Multi-vector Simulation (MVS) <https://github.com/rl-institut/mvs_eland>`_ tool, the definitions of all the
 relevant parameters of *MVS* can be found in the `documentation of MVS <https://mvs-eland.readthedocs.io/en/latest/MVS_parameters.html>`_.
@@ -190,9 +190,9 @@ Some parameters can be calculated automatically by *pvcompare* and do not need t
 
         b. **input power** and **output power**: kW
 
----------------------------------
+
 2. pvcompare-specific parameters
----------------------------------
+================================
 
 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.

diff --git a/docs/pv_feedin.rst b/docs/pv_feedin.rst
@@ -1,6 +1,8 @@
-=========================================================
+
+.. _pv-feedin:
+
 PV feedin - Modeling of different PV Technologies
-=========================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *pvcompare* provides the possibility to calculate feed-in time series for the
 following PV technologies under real world conditions:
 
@@ -13,9 +15,8 @@ unique models were developed for the CPV and PeroSi technologies. The next
 sections will provide a detailed description of the different modeling
 approaches.
 
-------------------
 1. SI
-------------------
+=====
 The silicone module parameters are loaded from `cec module <https://github.com/NREL/SAM/tree/develop/deploy/libraries>`_ database. The module
 selected by default is the "Aleo_Solar_S59y280" module with a 17% efficiency.
 But any other module can be selected.
@@ -29,10 +30,8 @@ conditions the following methods are selected from `modelchain object <https://p
 - temperature_model="sapm"
 - losses_model="pvwatts"
 
-
--------
 2. CPV
--------
+======
 
 The CPV technology that is used in the *pvcompare* simulations is a hybrid
 micro-Concentrator module with integrated planar tracking and diffuse light
@@ -73,7 +72,7 @@ Modeling the hybrid system
 --------------------------
 The model of the cpv technology is outsourced from *pvcompare* and can be found in the
 `cpvlib <https://github.com/isi-ies-group/cpvlib>`_ repository. *pvcompare*
-contains the wrapper function :py:func:`~.create_cpv_time_series`.
+contains the wrapper function :py:func:`~pvcompare.cpv.apply_cpvlib_StaticHybridSystem.create_cpv_time_series`.
 
 In order to model the dependencies of AOI, temperature and spectrum of the cpv
 module, the model follows an approach of `[Gerstmeier, 2011] <https://www.researchgate.net/publication/234976094_Validation_of_the_PVSyst_Performance_Model_for_the_Concentrix_CPV_Technology>`_
@@ -116,8 +115,8 @@ are then multiplied with the output power of the single diode functions. They
 function as temperature and air mass corrections due to spectral and temperature
 losses.
 
-Flatplate submodule
--------------------
+Flat plate submodule
+--------------------
 
 For AOI < 60° only the diffuse irradiance reaches the flat plate module:
 GII (global inclined irradiance) - DII (direct inclined irradiance).
@@ -127,17 +126,16 @@ input irradiance. No module connection is assumed, so CPV and flat plate output
 power are added up as in a four terminal cell.
 
 
-Measurement Data:
------------------
+Measurement Data
+----------------
 The Utilization factors were derived from outdoor measurement data of a three
 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>`_.
 
 
-------------------
 2. 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
 researchers around the world are investigating the potential of single junction
@@ -224,10 +222,8 @@ taken into account.
 5. In order to get the module output the cell outputs are added up.
 
 
-
-----------------
 3. Normalization
-----------------
+================
 
 For the energy system optimization normalized time series are needed, which can
 then be scaled to the optimal installation size of the system.

diff --git a/docs/scenarios_and_results.rst b/docs/scenarios_and_results.rst
@@ -0,0 +1,7 @@
+
+.. _scenarios-results:
+
+Selected scenarios and results
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here we will publish selected scenarios that we simulated for the H2020 Project GRECO and their results, which will also serve as examples.