Merge pull request #155 from greco-project/docs/enhancing_documentation

Enhance documentation, add small fixes and information
greco-project · Dec 8, 2020 · 16acbdc · 16acbdc
2 parents 6eaadc4 + 8a9e077
commit 16acbdc
Show file tree

Hide file tree

Showing 16 changed files with 147 additions and 126 deletions.
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, such as:
+
+    * 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/getting_started_add_ons.rst b/docs/getting_started_add_ons.rst
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.