add input/output descriptions (WIP)

doc/configtables/hydro.csv

@@ -3,4 +3,4 @@ cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the releva
 carriers,--,"Any subset of {'ror', 'PHS', 'hydro'}","Specifies the types of hydro power plants to build per-unit availability time series for. 'ror' stands for run-of-river plants, 'PHS' represents pumped-hydro storage, and 'hydro' stands for hydroelectric dams."
 PHS_max_hours,h,float,"Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>`_."
 hydro_max_hours,h,"Any of {float, 'energy_capacity_totals_by_country', 'estimate_by_large_installations'}","Maximum state of charge capacity of the pumped-hydro storage (PHS) in terms of hours at full output capacity ``p_nom`` or heuristically determined. Cf. `PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>`_."
-clip_min_inflow,??,float,"To avoid too small values in the inflow time series, values below this threshold are set to zero."
+clip_min_inflow,MW,float,"To avoid too small values in the inflow time series, values below this threshold are set to zero."

doc/configtables/offwind-ac.csv

@@ -8,5 +8,5 @@ corine,--,"Any *realistic* subset of the `CORINE Land Cover code list <http://ww
 natura,bool,"{true, false}","Switch to exclude `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas. Area is excluded if ``true``."
 max_depth,m,float,"Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential."
 min_shore_distance,m,float,"Minimum distance to the shore below which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential."
-potential,--,"One of {'simple', 'conservative'}",TODO
+potential,--,"One of {'simple', 'conservative'}","Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`"
 clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero."

doc/configtables/offwind-dc.csv

@@ -8,5 +8,5 @@ corine,--,"Any *realistic* subset of the `CORINE Land Cover code list <http://ww
 natura,bool,"{true, false}","Switch to exclude `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas. Area is excluded if ``true``."
 max_depth,m,float,"Maximum sea water depth at which wind turbines can be build. Maritime areas with deeper waters are excluded in the process of calculating the AC-connected offshore wind potential."
 min_shore_distance,m,float,"Minimum distance to the shore below which wind turbines cannot be build. Such areas close to the shore are excluded in the process of calculating the AC-connected offshore wind potential."
-potential,--,"One of {'simple', 'conservative'}",TODO
+potential,--,"One of {'simple', 'conservative'}","Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`"
 clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero."

doc/configtables/onwind.csv

@@ -3,11 +3,11 @@ cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the releva
 resource,,,
 -- method,--,"Must be 'wind'","A superordinate technology type."
 -- turbine,--,"One of turbine types included in `atlite <https://github.com/PyPSA/atlite/tree/master/atlite/resources/windturbine>`_","Specifies the turbine type and its characteristic power curve."
-capacity_per_sqkm,MW/km2,float,"Allowable density of wind turbine placement."
+capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of wind turbine placement."
 corine,,,
 -- grid_codes,--,"Any subset of the `CORINE Land Cover code list <http://www.eea.europa.eu/data-and-maps/data/corine-land-cover-2006-raster-1/corine-land-cover-classes-and/clc_legend.csv/at_download/file>`_","Specifies areas according to CORINE Land Cover codes which are generally eligible for wind turbine placement."
 -- distance,m,float,"Distance to keep from areas specified in ``distance_grid_codes``"
 -- distance_grid_codes,--,"Any subset of the `CORINE Land Cover code list <http://www.eea.europa.eu/data-and-maps/data/corine-land-cover-2006-raster-1/corine-land-cover-classes-and/clc_legend.csv/at_download/file>`_","Specifies areas according to CORINE Land Cover codes to which wind turbines must maintain a distance specified in the setting ``distance``."
 natura,bool,"{true, false}","Switch to exclude `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas. Area is excluded if ``true``."
-potential,--,"One of {'simple', 'conservative'}","TODO"
+potential,--,"One of {'simple', 'conservative'}","Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`"
 clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero."

doc/configtables/solar.csv

@@ -10,5 +10,5 @@ capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of solar panel placem
 correction_factor,--,float,"A correction factor for the capacity factor (availability) time series."
 corine,--,"Any subset of the `CORINE Land Cover code list <http://www.eea.europa.eu/data-and-maps/data/corine-land-cover-2006-raster-1/corine-land-cover-classes-and/clc_legend.csv/at_download/file>`_","Specifies areas according to CORINE Land Cover codes which are generally eligible for solar panel placement."
 natura,bool,"{true, false}","Switch to exclude `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas. Area is excluded if ``true``."
-potential,--,"One of {'simple', 'conservative'}",TODO
+potential,--,"One of {'simple', 'conservative'}","Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`"
 clip_p_max_pu,p.u.,float,"To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero."

doc/configuration.rst

@@ -159,6 +159,8 @@ Arguments to `pandas.date_range <https://pandas.pydata.org/pandas-docs/stable/re
 .. note::
     To change cost assumptions in more detail (i.e. other than ``marginal_cost`` and ``capital_cost``), consider modifying cost assumptions directly in ``data/costs.csv`` as this is not yet supported through the config file.
 
+    You can also build multiple different cost databases. Make a renamed copy of ``data/costs.csv`` (e.g. ``data/costs-optimistic.csv``) and set the variable ``COSTS=data/costs-optimistic.csv`` in the ``Snakefile``.
+
 ``solving``
 =============
 

doc/contributing.rst

@@ -2,7 +2,9 @@
 Contributing
 #######################
 
+We strongly welcome anyone interested in contributing to this project,
+be it with new ideas, suggestions, by filing bug reports or contributing code.
 
-We strongly welcome anyone interested in contributing to this project.
+You are invited to submit pull requests and file issues to the `GitHub repository <https://github.com/PyPSA/PyPSA-Eur>`_.
 
-Submit pull requests / issues to the `github repository <https://github.com/PyPSA/PyPSA-Eur>`_.
+If you are unfamiliar with pull requests, the GitHub help pages have a nice `guide <https://help.github.com/en/articles/about-pull-requests>`_.

doc/introduction.rst

@@ -39,6 +39,9 @@ Modification
 The model has several configuration options collected in the ``config.yaml`` file
 located in the root directory.
 
+Folder Structure
+================
+
 System Requirements
 ===================
 

doc/plotting.rst

@@ -2,6 +2,8 @@
 Plotting and Summary
 ##########################################
 
+.. _summary:
+
 Make Summary
 ============
 
@@ -27,11 +29,15 @@ Replacing '/summaries/' with '/plots/' creates nice colored maps of the results.
 
 .. automodule:: make_summary
 
+.. _summary_plot:
+
 Plot Summary
 ============
 
 .. automodule:: plot_summary
 
+.. _map_plot:
+
 Plot Network
 ============
 

doc/preparation.rst

@@ -4,10 +4,10 @@ Preparing Networks
 
 The preparation process of the PyPSA-Eur energy system model consists of a group of ``snakemake`` rules which are briefly outlined and explained in detail in the sections below:
 
-- ``build_shapes`` to generate GeoJSON files with shapes of the countries, exclusive economic zones and `NUTS3 <https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics>`_ areas.
+- ``build_shapes`` generates GeoJSON files with shapes of the countries, exclusive economic zones and `NUTS3 <https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics>`_ areas.
-- ``build_cutout`` to prepare smaller weather data portions from `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_ for cutout ``europe-2013-era5`` and SARAH for cutout ``europe-2013-sarah``.
+- ``build_cutout`` prepares smaller weather data portions from `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_ for cutout ``europe-2013-era5`` and SARAH for cutout ``europe-2013-sarah``.
 
-With these and the externally extracted ENTSO-E online map topology (``data/entsoegridkit``), it can build a base ``PyPSA`` network with the following rules:
+With these and the externally extracted ENTSO-E online map topology (``data/entsoegridkit``), it can build a base PyPSA network with the following rules:
 
 - ``base_network`` builds and stores the base network with all buses, HVAC lines and HVDC links, while
 - ``build_bus_regions`` determines `Voronoi cells <https://en.wikipedia.org/wiki/Voronoi_diagram>`_ for all substations.
@@ -19,73 +19,80 @@ Then the process continues by calculating conventional power plant capacities, p
 - ``build_renewable_profiles`` for the hourly capacity factors in each substation's Voronoi cell for PV, onshore and offshore wind, and
 - ``build_hydro_profile`` for the hourly per-unit hydro power availability time series.
 
-The central rule ``add_electricity`` then ties all the different data inputs together into a detailed `PyPSA` network stored in ``networks/elec.nc`` containing
+The central rule ``add_electricity`` then ties all the different data inputs together into a detailed PyPSA network stored in ``networks/elec.nc``.
 
-.. todo:: probably move parts into ``add_electricity`` docstring
+.. _shapes:
-
-- today's transmission topology and transfer capacities (optionally including lines which are under construction according to the config settings ``lines: under_construction`` and ``links: under_construction``),
-- today's thermal and hydro power generation capacities (for the technologies listed in the config setting ``electricity: conventional_carriers``), and
-- today's load time-series (upsampled in a top-down approach according to population and gross domestic product)
-
-It further adds extendable ``generators`` and ``storage_units`` with **zero** capacity for
-
-- photovoltaic, onshore and offshore wind installations with today's locational, hourly wind and solar pv capacity factors (but **no** current capacities)
-- long-term hydrogen and short-term battery storage units (if listed in the config setting ``electricity: extendable_carriers``)
-- additional open- and combined-cycle gas turbines (if ``OCGT`` and/or ``CCGT`` is listed in the config setting ``electricity: extendable_carriers``)
-
-.. each rule description should have a list of parameters
-.. from the config.yaml that affect this rule.
 
 Build Shapes
 =============================
 
 .. automodule:: build_shapes
 
+.. _cutout:
+
 Build Cutout
 =============================
 
 .. automodule:: build_cutout
 
+.. _links:
+
 Prepare HVDC Links
 =============================
 
 .. automodule:: prepare_links_p_nom
 
+.. _base:
+
 Base Network
 =============================
 
 .. automodule:: base_network
 
+.. _busregions:
+
 Build Bus Regions
 =============================
 
 .. automodule:: build_bus_regions
 
-Build Country Full Load Hours
+.. _natura:
-=============================
-
-.. automodule:: build_country_flh
-
-Build Hydro Profile
-=============================
-
-.. automodule:: build_hydro_profile
 
 Build Natura Raster
 =============================
 
 .. automodule:: build_natura_raster
 
-Build Renewable Profiles
+.. _flh:
-========================
 
-.. automodule:: build_renewable_profiles
+Build Country Full Load Hours
+=============================
+
+.. automodule:: build_country_flh
+
+.. _powerplants:
 
 Build Power Plants
 =============================
 
 .. automodule:: build_powerplants
 
+.. _renewableprofiles:
+
+Build Renewable Profiles
+========================
+
+.. automodule:: build_renewable_profiles
+
+.. _hydroprofiles:
+
+Build Hydro Profile
+=============================
+
+.. automodule:: build_hydro_profile
+
+.. _electricity:
+
 Add Electricity
 =============================
 

doc/references.bib

@@ -8,4 +8,108 @@
         issn = "2211-467X",
         doi = "10.1016/j.esr.2018.08.012",
         eprint = "1806.01613"
-    }
+    }
+
+@article{brown2019sectoral,
+  title={Sectoral Interactions as Carbon Dioxide Emissions Approach Zero in a Highly-Renewable European Energy System},
+  author={Brown, Tom and Sch{\"a}fer, Mirko and Greiner, Martin},
+  journal={Energies},
+  volume={12},
+  number={6},
+  pages={1032},
+  year={2019},
+  publisher={Multidisciplinary Digital Publishing Institute}
+}
+
+@article{neumann2019heuristics,
+  title={Heuristics for Transmission Expansion Planning in Low-Carbon Energy System Models},
+  author={Neumann, Fabian and Brown, Tom},
+  journal={arXiv preprint arXiv:1907.10548},
+  year={2019}
+}
+
+@article{weber2019counter,
+  title={Counter-intuitive behaviour of energy system models under CO2 caps and prices},
+  author={Weber, Juliane and Heinrichs, Heidi Ursula and Gillessen, Bastian and Schumann, Diana and H{\"o}rsch, Jonas and Brown, Tom and Witthaut, Dirk},
+  journal={Energy},
+  volume={170},
+  pages={22--30},
+  year={2019},
+  publisher={Elsevier}
+}
+
+@phdthesis{horsch2018spatial,
+  title={Spatial Scaling in Renewable Energy Networks},
+  author={H{\"o}rsch, Jonas},
+  year={2018},
+  school={Johann Wolfgang Goethe-Universit{\"a}t Frankfurt am Main}
+}
+
+@inproceedings{tranberg2018flow,
+  title={Flow-based analysis of storage usage in a low-carbon European electricity scenario},
+  author={Tranberg, Bo and Sch{\"a}fer, Mirko and Brown, Tom and H{\"o}rsch, Jonas and Greiner, Martin},
+  booktitle={2018 15th International Conference on the European Energy Market (EEM)},
+  pages={1--5},
+  year={2018},
+  organization={IEEE}
+}
+
+@article{pagnier2018disturbance,
+  title={Disturbance propagation, inertia location and slow modes in large-scale high voltage power grids},
+  author={Pagnier, Laurent and Jacquod, Philippe},
+  journal={arXiv preprint arXiv:1810.04982},
+  year={2018}
+}
+
+@article{victoria2019role,
+  title={The role of storage technologies throughout the decarbonisation of the sector-coupled European energy system},
+  author={Victoria, Marta and Zhu, Kun and Brown, Tom and Andresen, Gorm B and Greiner, Martin},
+  journal={arXiv preprint arXiv:1906.06936},
+  year={2019}
+}
+
+@article{brownasynergies,
+  title={Synergies of sector coupling and transmission extension in a cost-optimised, highly renewable European energy system},
+  author={Browna, T and Schlachtbergera, D and Kiesa, A and Schramma, S and Greinerb, M}
+}
+
+@article{gardumi2019representation,
+  title={Representation of Balancing Options for Variable Renewables in Long-Term Energy System Models: An Application to OSeMOSYS},
+  author={Gardumi, Francesco and Welsch, Manuel and Howells, Mark and Colombo, Emanuela},
+  journal={Energies},
+  volume={12},
+  number={12},
+  pages={2366},
+  year={2019},
+  publisher={Multidisciplinary Digital Publishing Institute}
+}
+
+@article{zhu2019impact,
+  title={Impact of CO2 prices on the design of a highly decarbonised coupled electricity and heating system in Europe},
+  author={Zhu, Kun and Victoria, Marta and Brown, Tom and Andresen, Gorm B and Greiner, Martin},
+  journal={Applied energy},
+  volume={236},
+  pages={622--634},
+  year={2019},
+  publisher={Elsevier}
+}
+
+@article{schlott2018impact,
+  title={The impact of climate change on a cost-optimal highly renewable European electricity network},
+  author={Schlott, Markus and Kies, Alexander and Brown, Tom and Schramm, Stefan and Greiner, Martin},
+  journal={Applied energy},
+  volume={230},
+  pages={1645--1659},
+  year={2018},
+  publisher={Elsevier}
+}
+
+@article{gotzens2019performing,
+  title={Performing energy modelling exercises in a transparent way-The issue of data quality in power plant databases},
+  author={Gotzens, Fabian and Heinrichs, Heidi and H{\"o}rsch, Jonas and Hofmann, Fabian},
+  journal={Energy Strategy Reviews},
+  volume={23},
+  pages={1--12},
+  year={2019},
+  publisher={Elsevier}
+}

doc/release_notes.rst

@@ -2,8 +2,9 @@
 Release Notes
 ##########################################
 
-Section A
+PyPSA-Eur 0.1.0 (DATE)
-=========
+======================
 
-Section B
+This is the first release of PyPSA-Eur. It now features:
-=========
+
+* Documentation on installation, workflows and configuration settings.

doc/simplification.rst

@@ -14,16 +14,22 @@ The simplification and clustering steps are described in detail in the paper
 
 .. bibliography:: references.bib
 
+.. _simplify:
+
 Simplify Network
 ================
 
 .. automodule:: simplify_network
 
+.. _cluster:
+
 Cluster Network
 ===============
 
 .. automodule:: cluster_network
 
+.. _prepare:
+
 Prepare Network
 ===============
 

doc/solving.rst

@@ -4,16 +4,22 @@ Solving Networks
 
 After generating all networks they can be solved through the rule ``solve_network``  by using the collection rule ``solve_all_elec_networks``.
 
+.. _solve:
+
 Solve Network
 =============
 
 .. automodule:: solve_network
 
+.. _trace_solve:
+
 Trace Solve Network
 ===================
 
 .. automodule:: trace_solve_network
 
+.. _solve_operations:
+
 Solve Operations Network
 ========================
 

doc/wildcards.rst

@@ -13,6 +13,11 @@ The ``ll`` wildcard
 The ``clusters`` wildcard
 =========================
 
+.. warning::
+    The number of clusters must be lower than the total number of nodes
+    and higher than the number of countries. A country counts twice if
+    it has two asynchronous subnetworks (e.g. Denmark).
+
 The ``network`` wildcard
 ========================
 

scripts/add_electricity.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 """
-Adds electrical generators and storage units to base network
+Adds electrical generators and storage units to a base network.
 
 Relevant Settings
 -----------------
@@ -39,12 +39,36 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/costs.csv``:
+- ``data/bundle/hydro_capacities.csv``:
+- ``data/geth2015_hydro_capacities.csv``:
+- ``data/bundle/time_series_60min_singleindex_filtered.csv``:
+- ``resources/regions_onshore.geojson``: confer :ref:`busregions`
+- ``resources/nuts3_shapes.geojson``: confer :ref:`shapes`
+- ``resources/powerplants.csv``: confer :ref:`powerplants`
+- ``resources/profile_{}.nc``: all technologies in ``config["renewables"].keys()``, confer :ref:`renewableprofiles`.
+- ``networks/base.nc``: confer :ref:`base`
+
 Outputs
 -------
 
+- ``networks/elec.nc``:
+
+    .. image:: img/elec.png
+            :scale: 33 %
+
 Description
 -----------
 
+- today's transmission topology and transfer capacities (optionally including lines which are under construction according to the config settings ``lines: under_construction`` and ``links: under_construction``),
+- today's thermal and hydro power generation capacities (for the technologies listed in the config setting ``electricity: conventional_carriers``), and
+- today's load time-series (upsampled in a top-down approach according to population and gross domestic product)
+
+It further adds extendable ``generators`` and ``storage_units`` with **zero** capacity for
+
+- photovoltaic, onshore and offshore wind installations with today's locational, hourly wind and solar pv capacity factors (but **no** current capacities)
+- long-term hydrogen and short-term battery storage units (if listed in the config setting ``electricity: extendable_carriers``)
+- additional open- and combined-cycle gas turbines (if ``OCGT`` and/or ``CCGT`` is listed in the config setting ``electricity: extendable_carriers``)
 """
 
 import logging

scripts/base_network.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 """
-Creates the network topology from ENTSO-E map extracts as a PyPSA network
+Creates the network topology from the ENTSO-E map extracts as a PyPSA network.
 
 Relevant Settings
 -----------------
@@ -32,9 +32,22 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/entsoegridkit``:
+- ``data/parameter_corrections.yaml``:
+- ``data/links_p_nom.csv``: confer :ref:`links`
+- ``data/links_tyndp.csv``:
+- ``resources/country_shapes.geojson``: confer :ref:`shapes`
+- ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
+- ``resources/europe_shape.geojson``: confer :ref:`shapes`
+
 Outputs
 -------
 
+- ``networks/base.nc``
+
+    .. image:: img/base.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/build_bus_regions.py

@@ -1,5 +1,5 @@
 """
-Creates onshore and offshore Voronoi shapes for each bus
+Creates Voronoi shapes for each bus representing both onshore and offshore regions.
 
 Relevant Settings
 -----------------
@@ -12,9 +12,23 @@ Relevant Settings
 Inputs
 ------
 
+- ``resources/country_shapes.geojson``: confer :ref:`shapes`
+- ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
+- ``networks/base.nc``: confer :ref:`base`
+
 Outputs
 -------
 
+- ``resources/regions_onshore.geojson``:
+
+    .. image:: img/regions_onshore.png
+        :scale: 33 %
+
+- ``resources/regions_offshore.geojson``:
+
+    .. image:: img/regions_offshore.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/build_country_flh.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 """
-Create csv files and plots for comparing per country full load hours of renewable time-series
+Create ``.csv`` files and plots for comparing per country full load hours of renewable time series.
 
 Relevant Settings
 -----------------
@@ -18,9 +18,30 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/bundle/corine/g250_clc06_V18_5.tif``:
+
+    .. image:: img/corine.png
+        :scale: 33 %
+
+- ``data/bundle/GEBCO_2014_2D.nc``:
+- ``data/pietzker2014.xlsx``: NOT IN DATA BUNDLE!
+- ``resources/natura.tiff``: confer :ref:`natura`
+- ``resources/country_shapes.geojson``: confer :ref:`shapes`
+- ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
+- ``resources/regions_onshore.geojson``: (if not offshore wind), confer :ref:`busregions`
+- ``resources/regions_offshore.geojson``: (if offshore wind), :ref:`busregions`
+- ``"cutouts/" + config["renewable"][{technology}]['cutout']``: :ref:`cutout`
+- ``networks/base.nc``: :ref:`base`
+
 Outputs
 -------
 
+- ``resources/country_flh_area_{technology}.csv``:
+- ``resources/country_flh_aggregated_{technology}.csv``:
+- ``resources/country_flh_uncorrected_{technology}.csv``:
+- ``resources/country_flh_{technology}.pdf``:
+- ``resources/country_exclusion_{technology}``:
+
 Description
 -----------
 

scripts/build_cutout.py

@@ -1,5 +1,5 @@
 """
-Create cutouts configured in `atlite` config section
+Create cutouts with `atlite <https://atlite.readthedocs.io/en/latest/>`_.
 
 Relevant Settings
 -----------------
@@ -14,9 +14,13 @@ Relevant Settings
 Inputs
 ------
 
+*None*
+
 Outputs
 -------
 
+- ``cutouts/{cutout}``:
+
 Description
 -----------
 

scripts/build_hydro_profile.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 """
-Build hydroelectric inflow time-series for each country
+Build hydroelectric inflow time-series for each country.
 
 Relevant Settings
 -----------------
@@ -17,9 +17,15 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/bundle/EIA_hydro_generation_2000_2014.csv``:
+- ``resources/country_shapes.geojson``: confer :ref:`shapes`
+- ``"cutouts/" + config["renewable"]['hydro']['cutout']``: confer :ref:`cutout`
+
 Outputs
 -------
 
+- ``resources/profile_hydro.nc``:
+
 Description
 -----------
 

scripts/build_natura_raster.py

@@ -1,5 +1,5 @@
 """
-Rasters the vector data of the NATURA2000 data onto all cutout regions
+Rasters the vector data of the `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas onto all cutout regions.
 
 Relevant Settings
 -----------------
@@ -13,9 +13,19 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/bundle/natura/Natura2000_end2015.shp``:
+
+    .. image:: img/natura.png
+        :scale: 33 %
+
 Outputs
 -------
 
+- ``resources/natura.tiff``:
+
+    .. image:: img/natura.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/build_powerplants.py

@@ -1,18 +1,25 @@
 # coding: utf-8
 """
-Get conventional powerplants from `powerplantmatching`, assign to buses and create csv file
+Retrieves conventional powerplant capacities and locations from `powerplantmatching <https://github.com/FRESNA/powerplantmatching>`_, assigns these to buses and creates a ``.csv`` file.
 
 Relevant Settings
 -----------------
 
-*None*
+.. code:: yaml
+
+    enable:
+        powerplantmatching:
 
 Inputs
 ------
 
+- ``networks/base.nc``: confer :ref:`base`.
+
 Outputs
 -------
 
+- ``resource/powerplants.csv``
+
 Description
 -----------
 

scripts/build_renewable_profiles.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python
 """
-The script ``build_renewable_profiles.py`` calculates for each node several geographical properties:
+Calculates for each node several geographical properties:
 
-  1. the installable capacity (based on land-use)
+  1. the installable capacity (based on land-use),
-  2. the available generation time series (based on weather data) and
+  2. the available generation time series (based on weather data),
-  3. the average distance from the node for onshore wind, AC-connected offshore wind, DC-connected offshore wind and solar PV generators.
+  3. the average distance from the node for onshore wind, AC-connected offshore wind, DC-connected offshore wind and solar PV generators, and
-  4. In addition for offshore wind it calculates the fraction of the grid connection which is under water.
+  4. the fraction of the grid connection which is under water for offshore wind turbines.
 
 .. note:: Hydroelectric profiles are built in script :mod:`build_hydro_profiles`.
 
@@ -36,39 +36,33 @@ Relevant settings
             clip_p_max_pu:
             resource:
 
-
-config.renewable (describes the parameters for onwind, offwind-ac, offwind-dc
-and solar)
-config.snapshots (describes the time dimensions of the selection of snapshots)
-
 Inputs
 ------
 
-base_network
+- ``data/bundle/corine/g250_clc06_V18_5.tif``:
-land-use shapes
+- ``data/bundle/GEBCO_2014_2D.nc``:
-region shapes for onshore, offshore and countries
+- ``resources/natura.tiff``: confer :ref:`natura`
-cutout
+- ``resources/country_shapes.geojson``: confer :ref:`shapes`
+- ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
+- ``resources/regions_onshore.geojson``: (if not offshore wind), confer :ref:`busregions`
+- ``resources/regions_offshore.geojson``: (if offshore wind), :ref:`busregions`
+- ``"cutouts/" + config["renewable"][{technology}]['cutout']``: :ref:`cutout`
+- ``networks/base.nc``: :ref:`base`
 
 Outputs
 -------
 
-profile_{tech}.nc for tech in [onwind,offwind-ac,offwind-dc,solar]
+- ``resources/profile_{technology}.nc``:
 
-profile_{tech}.nc contains five common fields:
+    The files have the fields *(dimensions)*:
 
-profile (bus x time) - the per unit hourly availability factors for each node
+    - ``profile`` *(bus, time)*: the per unit hourly availability factors for each node
-weight (bus) - the sum of the layout weighting for each node
+    - ``weight`` *(bus)*: the sum of the layout weighting for each node
-p_nom_max (bus) - the maximal installable capacity at the node (in MW)
+    - ``p_nom_max`` *(bus)*: the maximal installable capacity at the node (in MW)
-potential (y,x) - the layout of generator units at cutout grid cells inside the
+    - ``potential`` *(y, x)*: the layout of generator units at cutout grid cells inside the voronoi cell (maximal installable capacity at each grid cell multiplied by the capacity factor)
-voronoi cell (maximal installable capacity at each grid cell multiplied by the
+    - ``average_distance`` *(bus)*: the average distance of units in the voronoi cell to the grid node (in km)
-capacity factor)
-average_distance (bus) - the average distance of units in the voronoi cell to
-the grid node (in km)
 
-for offshore we also have:
+    - ``underwater_fraction`` *(bus)* [offshore only]: the fraction of the average connection distance which is under water
-
-underwater_fraction (bus) - the fraction of the average connection distance
-which is under water
 
 Description:
 -----------------

scripts/build_shapes.py

@@ -1,5 +1,5 @@
 """
-Create GIS shape files for countries on-shore and off-shore, europe and nuts3 regions
+Creates GIS shape files of the countries, exclusive economic zones and `NUTS3 <https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics>`_ areas.
 
 Relevant Settings
 -----------------
@@ -11,9 +11,49 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/bundle/naturalearth/ne_10m_admin_0_countries.shp``: World country shapes
+
+    .. image:: img/countries.png
+        :scale: 33 %
+
+- ``data/bundle/eez/World_EEZ_v8_2014.shp``: World `exclusive economic zones <https://en.wikipedia.org/wiki/Exclusive_economic_zone>`_ (EEZ)
+
+    .. image:: img/eez.png
+        :scale: 33 %
+
+- ``data/bundle/NUTS_2013_60M_SH/data/NUTS_RG_60M_2013.shp``: Europe NUTS3 regions
+
+    .. image:: img/nuts3.png
+        :scale: 33 %
+
+- ``data/bundle/nama_10r_3popgdp.tsv.gz``: Average annual population by NUTS3 region (`eurostat <http://appsso.eurostat.ec.europa.eu/nui/show.do?dataset=nama_10r_3popgdp&lang=en>`_)
+- ``data/bundle/nama_10r_3gdp.tsv.gz``: Gross domestic product (GDP) by NUTS 3 regions (`eurostat <http://appsso.eurostat.ec.europa.eu/nui/show.do?dataset=nama_10r_3gdp&lang=en>`_)
+- ``data/bundle/ch_cantons.csv``: Mapping between Swiss Cantons and NUTS3 regions
+- ``data/bundle/je-e-21.03.02.xls``: Population and GDP data per Canton (`BFS - Swiss Federal Statistical Office <https://www.bfs.admin.ch/bfs/en/home/news/whats-new.assetdetail.7786557.html>`_ )
+
 Outputs
 -------
 
+- ``resources/country_shapes.geojson``: country shapes out of country selection
+
+    .. image:: img/country_shapes.png
+        :scale: 33 %
+
+- ``resources/offshore_shapes.geojson``: EEZ shapes out of country selection
+
+    .. image:: img/offshore_shapes.png
+        :scale: 33 %
+
+- ``resources/europe_shape.geojson``: Shape of Europe including countries and EEZ
+
+    .. image:: img/europe_shape.png
+        :scale: 33 %
+        
+- ``resources/nuts3_shapes.geojson``: NUTS3 shapes out of country selection
+        
+    .. image:: img/nuts3_shapes.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/cluster_network.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 """
-Create networks clustered to `cluster` number of zones with aggregated buses, generators and transmission corridors
+Creates networks clustered to ``{cluster}`` number of zones with aggregated buses, generators and transmission corridors.
 
 Relevant Settings
 -----------------
@@ -21,9 +21,19 @@ Relevant Settings
 Inputs
 ------
 
+- ``resources/regions_onshore_{network}_s{simpl}.geojson``: confer :ref:`simplify`
+- ``resources/regions_offshore_{network}_s{simpl}.geojson``: confer :ref:`simplify`
+- ``resources/clustermaps_{network}_s{simpl}.h5``: confer :ref:`simplify`
+- ``networks/{network}_s{simpl}.nc``: confer :ref:`simplify`
+
 Outputs
 -------
 
+- ``resources/regions_onshore_{network}_s{simpl}_{clusters}.geojson``:
+- ``resources/regions_offshore_{network}_s{simpl}_{clusters}.geojson``:
+- ``resources/clustermaps_{network}_s{simpl}_{clusters}.h5``:
+- ``networks/{network}_s{simpl}_{clusters}.nc``:
+
 Description
 -----------
 
@@ -52,6 +62,11 @@ Why are you asking three times the same question?
 
 No, the network clustering methods in PyPSA's networkclustering module don't work reliably with multiple voltage levels and transformers. If it is somehow necessary for you we could include switches to make Step 2 and 3 optional as well. But that's about it.
 
+.. tip::
+    The rule ``cluster_all_networks`` runs
+    for all ``scenario`` s in the configuration file 
+    the rule ``cluster_network``.
+
 """
 
 import pandas as pd

scripts/make_summary.py

@@ -1,5 +1,5 @@
 """
-Create summaries of aggregated energy and costs as csv files
+Creates summaries of aggregated energy and costs as ``.csv`` files.
 
 Relevant Settings
 -----------------

scripts/plot_network.py

@@ -1,5 +1,5 @@
 """
-Plot map with pie charts and cost box plots
+Plots map with pie charts and cost box bar charts.
 
 Relevant Settings
 -----------------

scripts/plot_p_nom_max.py

@@ -1,5 +1,5 @@
 """
-Plot renewable installation potentials per capacity factor
+Plots renewable installation potentials per capacity factor.
 
 Relevant Settings
 -----------------

scripts/plot_summary.py

@@ -1,5 +1,5 @@
 """
-Plot energy and cost summaries for several solved networks
+Plots energy and cost summaries for solved networks.
 
 Relevant Settings
 -----------------

scripts/prepare_links_p_nom.py

@@ -1,21 +1,30 @@
 #!/usr/bin/env python
 """
-Extract capacities for HVDC links from wikipedia
+Extracts capacities of HVDC links from `Wikipedia <https://en.wikipedia.org/wiki/List_of_HVDC_projects>`_.
 
 Relevant Settings
 -----------------
 
-*None*
+.. code:: yaml
+
+    enable:
+        prepare_links_p_nom:
 
 Inputs
 ------
 
+*None*
+
 Outputs
 -------
 
+- ``data/links_p_nom.csv``: A plain download of https://en.wikipedia.org/wiki/List_of_HVDC_projects#Europe plus extracted coordinates.
+
 Description
 -----------
 
+*None*
+
 """
 
 import pandas as pd

scripts/prepare_network.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 """
-Prepare PyPSA network for solving according to `opts`-wildcard
+Prepare PyPSA network for solving according to ``{opts}`` wildcard.
 
 Relevant Settings
 -----------------
@@ -21,12 +21,22 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/costs.csv``:
+- ``networks/{network}_s{simpl}_{clusters}.nc``: confer :ref:`cluster`
+
 Outputs
 -------
 
+- ``networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``:
+
 Description
 -----------
 
+.. tip::
+    The rule ``prepare_all_networks`` runs
+    for all ``scenario`` s in the configuration file
+    the rule ``prepare_network``.
+
 """
 
 import logging

scripts/simplify_network.py

@@ -1,7 +1,8 @@
 # coding: utf-8
-"""Bring electrical transmission network to a single 380kV voltage layer,
+"""
-remove network dead-ends, and reduce multi-hop linear HVDC connections to a
+Lifts electrical transmission network to a single 380 kV voltage layer,
-single link
+removes dead-ends of the network,
+and reduces multi-hop HVDC connections to a single link.
 
 Relevant Settings
 -----------------
@@ -34,9 +35,22 @@ Relevant Settings
 Inputs
 ------
 
+- ``data/costs.csv``:
+- ``resources/regions_onshore.geojson``: confer :ref:`busregions`
+- ``resources/regions_offshore.geojson``: confer :ref:`busregions`
+- ``networks/{network}.nc``: confer :ref:`electricity`
+
 Outputs
 -------
 
+- ``resources/regions_onshore_{network}_s{simpl}.geojson``:
+- ``resources/regions_offshore_{network}_s{simpl}.geojson``:
+- ``resources/clustermaps_{network}_s{simpl}.h5``:
+- ``networks/{network}_s{simpl}.nc``:
+
+    .. image:: img/elec_s.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/solve_network.py

@@ -1,5 +1,5 @@
 """
-Solve networks iteratively linear optimal power flow, while updating reactances
+Solves linear optimal power flow for a network iteratively while updating reactances.
 
 Relevant Settings
 -----------------
@@ -30,12 +30,24 @@ Relevant Settings
 Inputs
 ------
 
+- ``networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: confer :ref:`prepare`
+
 Outputs
 -------
 
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``:
+- ``logs/{network}_s{simpl}_{clusters}_l{ll}_{opts}_solver.log``:
+- ``logs/{network}_s{simpl}_{clusters}_l{ll}_{opts}_python.log``:
+- ``logs/{network}_s{simpl}_{clusters}_l{ll}_{opts}_memory.log``:
+
 Description
 -----------
 
+.. tip::
+    The rule ``solve_all_networks`` runs
+    for all ``scenario`` s in the configuration file 
+    the rule ``solve_network``.
+
 """
 
 import numpy as np

scripts/solve_operations_network.py

@@ -1,6 +1,6 @@
 """
-Solve linear optimal dispatch in hourly resolution with capacities of previous
+Solves linear optimal dispatch in hourly resolution
-capacity expansion
+using the capacities of previous capacity expansion in rule ``solve_network``.
 
 Relevant Settings
 -----------------
@@ -24,9 +24,17 @@ Relevant Settings
 Inputs
 ------
 
+- ``networks/{network}_s{simpl}_{clusters}.nc``: confer :ref:`cluster`
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: confer :ref:`solver`
+
 Outputs
 -------
 
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}_op.nc``:
+- ``logs/solve_operations_network/{network}_s{simpl}_{clusters}_l{ll}_{opts}_op_solver.log``:
+- ``logs/solve_operations_network/{network}_s{simpl}_{clusters}_l{ll}_{opts}_op_python.log``:
+- ``logs/solve_operations_network/{network}_s{simpl}_{clusters}_l{ll}_{opts}_op_memory.log``:
+
 Description
 -----------
 

scripts/trace_solve_network.py

@@ -1,6 +1,6 @@
 """
-Iteratively solves expansion problem like solve_network, but additionally
+Iteratively solves expansion problem like the rule ``solve_network``, but additionally
-records intermediate branch capacity steps and values of the objective
+records intermediate branch capacity steps and values of the objective function.
 
 Relevant Settings
 -----------------
@@ -24,9 +24,14 @@ Relevant Settings
 Inputs
 ------
 
+- ``networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: confer :ref:`prepare`
+
 Outputs
 -------
 
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}_trace.nc``:
+- ``logs/{network}_s{simpl}_{clusters}_l{ll}_{opts}_python_trace.log``:
+
 Description
 -----------