Merge pull request #325 from greco-project/release/v0.0.3

Release/v0.0.3

.github/workflows/main.yml

@@ -3,12 +3,14 @@
 name: CI
 
 # Controls when the action will run. # Triggers the workflow on push or pull request
-# events; push events only for dev and master branch
+# events; push events only for dev, master and release branches
 on:
   push:
     branches:
       - dev
       - master
+      - release
+      - 'release-*'
 
   pull_request:
 
@@ -31,7 +33,7 @@ jobs:
         uses: actions/checkout@v2
 
       - name: Set env for dev branch
-        if: endsWith(github.ref, '/develop')
+        if: endsWith(github.ref, '/dev')
         run: |
           echo "EXECUTE_TESTS_ON=dev" >> $GITHUB_ENV
           
@@ -40,6 +42,11 @@ jobs:
         run: |
           echo "EXECUTE_TESTS_ON=master" >> $GITHUB_ENV
 
+      - name: Set env for release branches
+        if: contains(github.ref, 'release')
+        run: |
+          echo "EXECUTE_TESTS_ON=master" >> $GITHUB_ENV
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:
@@ -62,10 +69,6 @@ jobs:
           pip install wheel
           pip install .[dev]
 
-      - name: Lint with black
-        run: |
-          black --check . --exclude docs/
-
       - name: Test with pytest
         run: |
           coverage run -m pytest tests/
@@ -80,3 +83,7 @@ jobs:
         env:
           COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COVERALLS_SERVICE_NAME: github
+
+      - name: Lint with black
+        run: |
+          black --check . --exclude docs/

CHANGELOG.md

@@ -19,38 +19,57 @@ Here is a template for new release sections
 -
 ```
 
-## [0.0.3] - 2021-04-22
+## [0.0.3] - 2021-05-29
 
 ### Added
+- General description of module is added for `main.py`. (#303)
 - Add config file for RTD `readthedocs.yml` (#276)
 - 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)
 - 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)
+- Add gas bus to `energyBusses.csv` in  `tests/data/user_inputs/mvs_inputs_sector_coupling/csv_elements` (#314)
 
 ### Changed
+- Description for multiple functions in the modules `area_potential`, `check_inputs`, `demand`, `cpv/apply_cpvlib_StaticHybridSystem`, `heat_pump_and_chiller`, `main`, `plots` were updated and corrected. (#303)
+- "Year for which power demand time series is calculated" is set between 2008-2018. (#303)
 - 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)
 - Tests have been added which check if the examples of pvcompare run with exit code 0 (#284)
 - Move docs requirements from `docs/docs_requirements.txt ` to `setup.py` - now installed e.g. by `pip install -e .[dev, docs]` (#276)
 - Move coverage badge of `coveralls.io` from deprecated to valid section in `README.rst` (#289)
 - Update code documentation in RTD: add missing functions and modules and delete outdated ones (#287)
 - Update RTD's section `Electricity and heat demand modeling` and `Heat pump and thermal storage modelling` in `model_assumptions.rst` (#291)
+- The parameters `inflow_direction` and `outflow_direction` of the gas plant have been changed from `Heat bus` to `Gas bus` in `energyProviders.csv` (#299)
+- The parameter `energyVector` of the gas plant has been changed from `Heat` to `Gas` in `energyProviders.csv` (#299)
+- All parameters in `fixcost.csv` have been set to zero except for the lifetime, which has been set to one for all in order to avoid ZeroDivisionError (#299)
+- Corrected description of installation requirements in contributing.md (#306)
+- Changed order of checks in github actions workflow - linting with black is last check now, to prevent failing due to black before pytest are run. (#298)
+- Renamed "GRECO Results" section in RTD to "Selected results of the GRECO project" (#316)
+- Minor changes and corrections in RTD (#316)
+
 
 ### Removed
--
+- Remove lines that add gas bus in `test_raiseError_temperature_match_hp()` as this is not needed anymore (#314)
+- Delete `if __name__ == "__main__"` statements of modules (#323)
+- Remove `greco_technologies` from `setup.py` (#323)
 
 ### Fixed
 - fix PV costs parameters and PSI lifetime (#273)
 - fix number of houses to 20 (8 flats per storey makes 40 flats per house with 5 storeys, makes 800 in total (and 480 for 3 storeys)) (#273)
 - Test coverage is now automatically checked with github actions and [coveralls](https://coveralls.io/github/greco-project/pvcompare) (#283)
+- In github actions workflow, add release branches to push events and correct name of `dev` branch (#305)
+- In github actions workflow, set `EXECUTE_TEST_ON` to `"master"` for release branches (#305)
 
 # Hot fixes
 - Hot fix: install MVS with option `[report]` to install missing packages (#270)
 - Hot fix: remove build for python 3.6 from `main.yml` github actions workflow (#270)
 - Hot fix: correct parameter `overwrite_grid_parameters` in `run_pvcompare.py` (#294)
+- Hot fix: Move `test_examples.py` to `examples` directory to make tests work in CI and add `__init__.py` to `examples` (#298)
+- Hot fix: Fix installation of MVS packages: now installed without extra requirement `report`. `psutil` and `kaleido` installed separately instead (#325)
 
 ## [0.0.2] - 2021-03-24
 

CONTRIBUTING.md

@@ -3,20 +3,19 @@
 ### Prerequisites
 
 - [Git](https://git-scm.com/)
-- Clone https://github.com/greco-project/pvcompare.git or `[email protected]:greco-project/pvcompare.git` (SSH) and install the cloned repository using pip with the developer extras:
+- Clone https://github.com/greco-project/pvcompare.git or `[email protected]:greco-project/pvcompare.git` (SSH) and install the cloned repository using pip with the developer and documentation extras:
 
 ```bash
 cd pvcompare
-pip install -r requirements.txt
-pip install -e .[dev]
+pip install -e .[dev, docs]
 ```
 
 ### Philosophy
 
 Development of a feature for this repository should be aligned with the workflow described 
 by [Vincent Driessen](https://nvie.com/posts/a-successful-git-branching-model/).
 
-Here is the minimal procedure you should follow : 
+Here is the minimal procedure you should follow: 
 
 #### Step 1: Create an issue.
 
@@ -79,10 +78,10 @@ Once you are satisfied with your PR you should ask someone to review it. Before
 ## Documentation on Readthedocs
 
 The documentation of pvcompare is compiled with the content of the folder "docs". 
-You need to install the requirements:
+Make sure you have installed the documentation extras:
 
 ```bash
-pip install -r docs/docs_requirements.txt
+pip install -e .[docs]
 ```
 
 After editing, build the documentation locally by running

README.rst

@@ -30,9 +30,9 @@ easily be enhanced to analyse other conversion technologies.
 
 The functionalities include
 
-* calculation of an area potential for PV on roof-tops and façades 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 façades incl. different technologies,
+* calculation of an area potential for PV on rooftops and façades based on building parameters,
+* calculation of heat and electricity demand time series for a specific amount of people living in these buildings,
+* calculation of PV feed-in time series for a set of PV installations on rooftops 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 (`CPV <https://pvcompare.readthedocs.io/en/latest/model_assumptions.html#cpv>`_) and
@@ -77,7 +77,7 @@ To install *pvcompare* follow these steps:
 Examples and basic usage
 ========================
 The basic usage of *pvcompare* is explained in the documentation in section `Basic usage of pvcompare <https://pvcompare.readthedocs.io/en/latest/basic_usage.html>`_.
-
+Examples are provided on github in the directory `examples/ <https://github.com/greco-project/pvcompare/tree/master/examples>`_.
 
 Contributing
 ============

docs/basic_usage.rst

@@ -9,38 +9,96 @@ Basic usage of pvcompare
 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.
+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.
+
+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:
+
+- latitude: float
+- longitude: float
+- year: int
+- storeys: int
+- country: str
+- scenario_name: str
 
 .. _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.
+*pvcompare* provides you with templates and default parameters for your simulations. You can find three basic scenarios (for the electricity sector, sector coupled system and a reference for the sector coupled system) in ``examples/example_user_inputs/``.
+A full description of the parameters and default values can be found in the section :ref:`parameters`.
+However, you can also define your own energy system, choose different parameters and/or change the settings.
 
-Please refer to `Simulating with the MVS <https://multi-vector-simulator.readthedocs.io/en/latest/simulating_with_the_mvs.html>`_ to learn
-how to work with the input csv files and how to provide your own time series. In *pvcompare* these files are by default stored in the directory
-``data/mvs_inputs``. You can define another input directory by providing the parameter ``mvs_input_directory`` to the :py:func:`~.main` and :py:func:`~.apply_mvs` functions.
+You can configure your own scenario by defining the parameters in ``data/user_inputs``. It contains two subfolders ``mvs_inputs`` for all MVS parameters and ``pvcompare_inputs`` for *pvcompare* inputs parameters. You can define a different input directory by providing the parameters ``user_inputs_mvs_directory`` and ``user_inputs_pvcompare_directory`` to the :py:func:`~.apply_pvcompare` and :py:func:`~.apply_mvs` functions.
 Please note that *pvcompare* only works with csv files but not with `json files <https://multi-vector-simulator.readthedocs.io/en/latest/simulating_with_the_mvs.html#json-file-mvs-config-json>`_.
 
-Further parameters are stored in the ``data/inputs`` directory. You can adapt this directory by providing the parameter ``input_directory`` to the :py:func:`~.main` and :py:func:`~.apply_mvs` functions.
-Especially interesting for adapting your simulations will be:
+Because the ``data/user_inputs`` folder is an individual working directory, it is left empty in the initial state of *pvcompare*. The user is required to fill in the specific input files that fit to the according energy system setup.
+The directory ``data/user_inputs_collection`` contains a collection of all kinds of possible asset definitions that have been used within the GRECO Project. Users are welcome to copy specific parts
+from this collection folder into the ``data/user_inputs`` files. It is also possible to define new MVS assets (e.g. different power plants, storages or energy providers, transformers etc.). Please see the `MVS documentation on simulating with the MVS <https://multi-vector-simulator.readthedocs.io/en/latest/simulating_with_the_mvs.html>`_ for more information.
+When setting up your input files, make sure that your individual input folder contains *all* available files. Even though you can change the values of the parameters, the files themselves, their naming and structure cannot be changed.
+
+There are three input folders  (one for each example) in the ``examples/example_user_inputs/`` directory that resemble specific scenario setups for
+sector coupled and electricity sector scenarios. For a start we recommend to study the example input files and then set up your own input files accordingly by adding (or removing) components from the ``data/user_inputs_collection`` directory.
+
+The following list gives an overview over all user input files. See section :ref:`parameters` for more information.
+
+**pvcompare_inputs**
 
 - ``pv_setup.csv``: Definition of PV assets (technology, tilt angle, azimuth angle, roof-top or facade installation)
-- ``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.
+- ``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 pump and chiller for the calculation of the COP/EER
+- ``stratified_thermal_storage.csv``: Definition of characteristics of the stratified thermal energy storage for the calculation of thermal energy losses from the storage to the environment
+
+**mvs_inputs/csv_elements**
+
+- ``constraints.csv``: List of contraints that should be activated for the energy system optimization (such as Net Zero Energy (NZE) constraint)
+- ``economic_data.csv``: General information about the simulation (currency, project duration, discount factor)
+- ``energyBusses.csv``: Definition of connecting busses (e.g. one electricty and one heat bus in a sector coupled scenario)
+- ``energyConsumption.csv``: Definition of the energy demand (e.g. electricity demand and/or heat demand with the filename of the demand time series)
+- ``energyConversion.csv``: Definition of transformers (e.g. solar inverter, charge controller, heat pumps etc.)
+- ``energyProduction.csv``: Definition of local generation (e.g. one or more PV plants with the maximal installable capacity and costs)
+- ``energyProviders.csv``: Definition of the energy Provider (e.g. a DSO or a gas plant in the reference sector coupled scenario)
+- ``energyStorage.csv``: Definition of storages (Li-Ion battery or thermal energy storage (TES) with the filename of the csv file that contains more precise information of each storage (e.g. ``storage_01.csv`` or ``storage_02.csv``))
+- ``fixcost.csv``: Definition of general fix costs of the project (disregarded by default)
+- ``project_data.csv``: Definition of the location and name of the simulation
+- ``simulation_settings.csv``: Definition of the year and the duration of the simulation (e.g. one year or less)
+- ``storage_**.csv``: Definition of more precise storage parameters (as an addition to ``energyStorage.csv``)
 
-A full description of the parameters can be found in the section :ref:`parameters`.
 
 
 Download ERA5 weather data
 ==========================
-Info follows, see #68.
+When running a simulation, *pvcompare* automatically downloads the ERA5 weather data from `Climate Data Store (CDS) <https://cds.climate.copernicus.eu/>`_ and stores it locally in ``data/static_inputs``, unless the
+file already exists. In order to enable this download you first need to create an account at the `CDS <https://cds.climate.copernicus.eu/user/login?destination=%2F%23!%2Fhome>`_ and
+install the *cdsapi* package. `This page <https://cds.climate.copernicus.eu/api-how-to>`_ provides information about the installation. When using the API for a large amount of data (e.g. a year for one location) the request gets queued and the download might take a while.
+
+Two example weather years for Berlin, Germany, 2017 and Madrid, Spain, 2017 are already added to ``data/static_inputs``.
+
+**Provide your own weather data**
+
+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.
+
 
 
 
 Add a sensitivy to your simulations
 ===================================
 
-Here follows a description of how to use the :py:func:`~.automated_loop` functionality.
+If you want to add a sensitivity to your simulation by varying one parameter, you can use the :py:func:`~.analysis.loop_mvs` or :py:func:`~.analysis.loop_pvcompare` functionality, depending
+on whether the parameter you want to vary is a *pvcompare* or a *MVS* parameter.
+
+The following *pvcompare* parameters can be varied:
+
+- location (country, lat, lon)
+- year (e.g. 2018)
+- storeys (number of storeys of the buildings)
+- technology (PV technologies: si, cpv or psi)
+- hp_temp (upper bound temperature of the heat pump (external outlet temperature at the condenser))
+
+Further, all *MVS* parameters can be varied by specifying the csv file, the column name and the parameter name to be changed in :py:func:`~.analysis.loop_mvs` .
+Please note that in each sensitivity analysis only *one* parameter can be varied.
+
+For more information see :py:func:`~.analysis.loop_mvs` and :py:func:`~.analysis.loop_pvcompare`.

docs/code.rst

@@ -99,20 +99,20 @@ Specific functions for calculating the feed-in time series of the perovskite-sil
 .. _heat_pumps_chillers:
 
 Heat pumps and chillers
------------------------
+=======================
 
 Functions for implementing a sector-coupled system (electricity, heat) and for calculating the COPs/EERs of heat pumps and chillers.
 
 .. autosummary::
     :toctree: temp/
 
-    heat_pump_and_chiller.add_sector_coupling
     heat_pump_and_chiller.calculate_cops_and_eers
+    heat_pump_and_chiller.add_sector_coupling
 
 .. _thermal_storage:
 
 Stratified thermal storage
---------------------------
+==========================
 
 Functions for calculating thermal losses of a stratified thermal storage and for adding it to the energy system.