further improve documentation

doc/configtables/atlite.csv

@@ -1,6 +1,6 @@
 ,Unit,Values,Description
 nprocesses,--,int,"Number of parallel processes in cutout preparation"
-cutouts,--,E,TODO
+cutouts,,,
 -- europe-2013-era5,--,,"Directory to write cutout data to."
 -- -- module,--,"Must be 'era5'","Source of the reanalysis weather dataset. `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_"
 -- -- xs,°,"Float interval within [-180, 180]","Range of longitudes to download weather data for."

doc/configtables/costs.csv

@@ -4,4 +4,5 @@ discountrate,--,float,"Default discount rate if not specified for a technology i
 USD2013_to_EUR2013,--,float,"Exchange rate from USD :math:`_{2013}` to EUR :math:`_{2013}` from `ECB <https://www.ecb.europa.eu/stats/exchange/eurofxref/html/eurofxref-graph-usd.en.html>`_"
 capital_cost,EUR/MW,"Keys should be in the 'technology' column of ``data/costs.csv``. Values can be any float.","For the given technologies, assumptions about their capital investment costs are set to the corresponding value. Optional; overwrites cost assumptions from ``data/costs.csv``."
 marginal_cost,EUR/MWh,"Keys should be in the 'technology' column of ``data/costs.csv``. Values can be any float.","For the given technologies, assumptions about their marginal operating costs are set to the corresponding value. Optional; overwrites cost assumptions from ``data/costs.csv``."
-emission_prices,--,E,TODO
+emission_prices,,,
+-- co2,EUR/t,float,"Exogenous price of carbon-dioxide added to the marginal costs of fossil-fuelled generators according to their carbon intensity."

doc/configtables/plotting.csv

@@ -10,15 +10,6 @@ costs_threshold,bn Euro,float,"Threshold below which technologies will not be sh
 energy_max,TWh,float,"Upper y-axis limit in energy bar plots."
 energy_min,TWh,float,"Lower y-axis limit in energy bar plots."
 energy_threshold,TWh,float,"Threshold below which technologies will not be shown in energy bar plots."
-vre_techs,--,E,TODO
-conv_techs,--,E,TODO
-storage_techs,--,E,TODO
-store_techs,--,E,TODO
-load_carriers,--,E,TODO
-AC_carriers,--,E,TODO
-link_carriers,--,E,TODO
-heat_links,--,E,TODO
-heat_generators,--,E,TODO
-tech_colors,--,E,TODO
-nice_names,--,E,TODO
-nice_names_n,--,E,TODO
+tech_colors,--,"carrier -> HEX colour code","Mapping from network ``carrier`` to a colour (`HEX colour code <https://en.wikipedia.org/wiki/Web_colors#Hex_triplet>`_)."
+nice_names,--,"str -> str","Mapping from network ``carrier`` to a more readable name."
+nice_names_n,--,"str -> str","Same as nice_names, but with linebreaks."

doc/configtables/scenario.csv

@@ -1,6 +1,6 @@
 ,Unit,Values,Description
-sectors,--,{'E'},TODO
-simpl,--,E,TODO
-ll,--,E,TODO
-clusters,--,E,TODO
-opts,--,E,TODO
+sectors,--,"Must be 'elec'","Placeholder for integration of other energy sectors."
+simpl,--,cf. :ref:`simpl`,"List of ``{simpl}`` wildcards to run."
+ll,--,cf. :ref:`ll`,"List of ``{ll}`` wildcards to run."
+clusters,--,cf. :ref:`clusters`,"List of ``{clusters}`` wildcards to run."
+opts,--,cf. :ref:`opts`,"List of ``{opts}`` wildcards to run."

doc/configtables/solving-options.csv

@@ -1,6 +1,6 @@
 ,Unit,Values,Description
 formulation,--,"Any of {'angles', 'kirchhoff', 'cycles', 'ptdf'}","Specifies which variant of linearized power flow formulations to use in the optimisation problem. Recommended is 'kirchhoff'. Explained in `this article <https://arxiv.org/abs/1704.01881>`_."
-load_shedding,--,E,TODO
+load_shedding,bool,"{'true','false'}","Add generators with a prohibitively high marginal cost to simulate load shedding and avoid problem infeasibilities."
 noisy_costs,bool,"{'true','false'}","Add random noise to marginal cost of generators by :math:`\mathcal{U}(0.009,0,011)` and capital cost of lines and links by :math:`\mathcal{U}(0.09,0,11)`."
 min_iterations,--,int,"Minimum number of solving iterations in between which resistance and reactence (``x/r``) are updated for branches according to ``s_nom_opt`` of the previous run."
 max_iterations,--,int,"Maximum number of solving iterations in between which resistance and reactence (``x/r``) are updated for branches according to ``s_nom_opt`` of the previous run."

doc/configtables/solving-solver.csv

@@ -1,3 +1,3 @@
 ,Unit,Values,Description
-name,--,{'E'},TODO
-opts,--,E,TODO
+name,--,"One of {'gurobi', 'cplex', 'cbc', 'glpk', 'ipopt'}; potentially more possible","Solver to use for optimisation problems in the workflow; e.g. clustering and linear optimal power flow."
+opts,--,"Parameter list for `Gurobi <https://www.gurobi.com/documentation/8.1/refman/parameters.html>`_ and `CPLEX <https://www.ibm.com/support/knowledgecenter/SSSA5P_12.5.1/ilog.odms.cplex.help/CPLEX/Parameters/topics/introListAlpha.html>`_","Solver specific parameter settings."

doc/configuration.rst

@@ -1,3 +1,5 @@
+.. _config:
+
 ##########################################
 Configuration
 ##########################################
@@ -16,9 +18,28 @@ Top-level configuration
    :widths: 25,7,22,30
    :file: configtables/toplevel.csv
 
+.. _scenario:
 
-Wildcards and ``scenario``
-==========================
+``scenario``
+============
+
+It is common conduct to analyse energy system optimisation models for **multiple scenarios** for a variety of reasons,
+e.g. assessing their sensitivity towards changing the temporal and/or geographical resolution or investigating how
+investment changes as more ambitious greenhouse-gas emission reduction targets are applied.
+
+The ``scenario`` section is an extraordinary section of the config file
+that is strongly connected to the :ref:`wildcards` and is designed to
+facilitate running multiple scenarios through a single command 
+
+.. code:: bash
+    
+    snakemake solve_all_elec_networks
+
+For each wildcard, a **list of values** is provided. The rule ``solve_all_elec_networks`` will trigger the rules for creating ``results/networks/elec_s{simpl}_{clusters}_l{ll}_{opts}.nc`` for **all combinations** of the provided wildcard values as defined by Python's `itertools.product(...) <https://docs.python.org/2/library/itertools.html#itertools.product>`_ function that snakemake's `expand(...) function <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#targets>`_ uses.
+
+An exemplary dependency graph (starting from the simplification rules) then looks like this:
+
+.. image:: img/scenarios.png
 
 .. literalinclude:: ../config.yaml
    :language: yaml
@@ -28,13 +49,11 @@ Wildcards and ``scenario``
    :header-rows: 1
    :widths: 25,7,22,30
    :file: configtables/scenario.csv
-   
-.. image:: img/scenarios.png
 
 ``snapshots``
 =============
 
-Arguments to `pandas.date_range <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html>`_
+Specifies the temporal range to build an energy system model for as arguments to `pandas.date_range <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html>`_
 
 .. literalinclude:: ../config.yaml
    :language: yaml

doc/examples.rst

@@ -1,3 +1,5 @@
+.. _examples:
+
 ########
 Examples
 ########

doc/index.rst

@@ -28,6 +28,8 @@ It contains alternating current lines at and above 220 kV voltage level and all
 
 The model is suitable both for operational studies and generation and transmission expansion planning studies. The continental scope and highly resolved spatial scale enables a proper description of the long-range smoothing effects for renewable power generation and their varying resource availability.
 
+.. image:: img/base.png
+
 The restriction to freely available and open data encourages the open exchange of model data developments and eases the comparison of model results. It provides a full, automated software pipeline to assemble the load-flow-ready model from the original datasets, which enables easy replacement and improvement of the individual parts.
 
 PyPSA-Eur is designed to be imported into the open toolbox `PyPSA <https://www.pypsa.org>`_ for which `documentation <https://pypsa.org/doc>`_ is available as well.

doc/introduction.rst

@@ -31,17 +31,25 @@ The **blocks** represent the individual rules which are required to create the f
 
 For the use of ``snakemake``, it makes sense to familiarize oneself quickly with its `basic tutorial <https://snakemake.readthedocs.io/en/stable/tutorial/basics.html>`_ and then read carefully through the section `Executing Snakemake <https://snakemake.readthedocs.io/en/stable/executable.html>`_, noting the arguments ``-n``, ``-r``, but also ``--dag``, ``-R`` and ``-t``.
 
-Modification
-============
+Scenarios, Configuration and Modification
+=========================================
 
-.. todo:: wildcards modification
+It is easy to run PyPSA-Eur for multiple scenarios using the `wildcards feature <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#wildcards>`_ of ``snakemake``. Wildcards allow to generalise a rule to produce all files that follow a `regular expression <https://en.wikipedia.org/wiki/Regular_expression>`_ pattern, which e.g. defines one particular scenario. One can think of a wildcard as a parameter that shows up in the input/output file names and thereby determines which rules to run, what data to retrieve and what files to produce. **Details are explained in** :ref:`wildcards` **and** :ref:`scenario`.
 
 The model has several configuration options collected in the ``config.yaml`` file
-located in the root directory.
+located in the root directory. **All options are explained in detail in** :ref:`config`.
 
 Folder Structure
 ================
 
+- ``data``: Includes input data that is not produced by any ``snakemake`` rule.
+- ``scripts``: Includes all the Python scripts executed by the ``snakemake`` rules.
+- ``resources``: Stores intermediate results of the workflow which can be picked up again by subsequent rules.
+- ``networks``: Stores intermediate, unsolved stages of the PyPSA network that describes the energy system model.
+- ``results``: Stores the solved PyPSA network data, summary files and plots.
+- ``benchmarks``: Stores ``snakemake`` benchmarks.
+- ``logs``: Stores log files about solving, including the solver output, console output and the output of a memory logger.
+
 System Requirements
 ===================
 

doc/simplification.rst

@@ -10,9 +10,8 @@ The simplification ``snakemake`` rules prepare **approximations** of the full mo
 - ``cluster_network`` uses a `k-means <https://en.wikipedia.org/wiki/K-means_clustering>`_ based clustering technique to partition the network into a given number of zones and then reduce the network to a representation with one bus per zone.
 
 The simplification and clustering steps are described in detail in the paper
-[The role of spatial scale in joint optimisations of generation and transmission for European highly renewable scenarios](https://arxiv.org/abs/1705.07617), 2017, [arXiv:1705.07617](https://arxiv.org/abs/1705.07617), [doi:10.1109/EEM.2017.7982024](https://doi.org/10.1109/EEM.2017.7982024).
 
-.. bibliography:: references.bib
+- Jonas Hörsch and Tom Brown. `The role of spatial scale in joint optimisations of generation and transmission for European highly renewable scenarios <https://arxiv.org/abs/1705.07617>`_), *14th International Conference on the European Energy Market*, 2017. `arXiv:1705.07617 <https://arxiv.org/abs/1705.07617>`_, `doi:10.1109/EEM.2017.7982024 <https://doi.org/10.1109/EEM.2017.7982024>`_.
 
 .. _simplify:
 

doc/solving.rst

@@ -2,7 +2,7 @@
 Solving Networks
 ##########################################
 
-After generating all networks they can be solved through the rule ``solve_network``  by using the collection rule ``solve_all_elec_networks``.
+After generating and simplifying the networks they can be solved through the rule ``solve_network``  by using the collection rule ``solve_all_elec_networks``. Moreover, networks can be solved for another focus with the derivative rules ``trace_solve_network`` to log changes during iterations and ``solve_operations_network`` for dispatch-only analyses on an already solved network.
 
 .. _solve:
 

doc/wildcards.rst

@@ -1,27 +1,41 @@
+.. _wildcards:
+
 #########
 Wildcards
 #########
 
 Detailed explanations of how wildcards work in ``snakemake`` can be found in the `relevant section of the documentation <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#wildcards>`_.
 
+.. _simpl:
+
 The ``simpl`` wildcard
 ======================
 
+.. _ll:
+
 The ``ll`` wildcard
 ===================
 
+.. _clusters:
+
 The ``clusters`` wildcard
 =========================
 
+.. todo:: explain placing `m` behind number of clusters: only moving instead of aggregating the generators to the clustered buses
+
 .. 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).
 
+.. _network:
+
 The ``network`` wildcard
 ========================
 
 
+.. _opts:
+
 The ``opts`` wildcard
 =====================
 
@@ -34,6 +48,8 @@ The ``opts`` wildcard triggers optional constraints, which are activated in eith
    :file: configtables/opts.csv
 
 
+.. _country:
+
 The ``country`` wildcard
 ========================
 
@@ -46,14 +62,22 @@ If ``country = all``, then the rule acts on the network for all countries define
 
     snakemake results/summaries/elec_s_all_lall_Co2L-3H_DE
 
+.. _cutout:
+
 The ``cutout`` wildcard
 =======================
 
+.. _technology:
+
 The ``technology`` wildcard
 ===========================
 
+.. _attr:
+
 The ``attr`` wildcard
 =====================
 
+.. _ext:
+
 The ``ext`` wildcard
 ====================

scripts/add_electricity.py

@@ -39,10 +39,21 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/costs.csv``:
-- ``data/bundle/hydro_capacities.csv``:
-- ``data/geth2015_hydro_capacities.csv``:
-- ``data/bundle/time_series_60min_singleindex_filtered.csv``:
+- ``data/costs.csv``: The database of cost assumptions for all included technologies for specific years from various sources; e.g. discount rate, lifetime, investment (CAPEX), fixed operation and maintenance (FOM), variable operation and maintenance (VOM), fuel costs, efficiency, carbon-dioxide intensity.
+- ``data/bundle/hydro_capacities.csv``: Hydropower plant store/discharge power capacities, energy storage capacity, and average hourly inflow by country.
+
+    .. image:: img/hydrocapacities.png
+        :scale: 34 %
+
+- ``data/geth2015_hydro_capacities.csv``: alternative to capacities above; NOT CURRENTLY USED!
+- ``data/bundle/time_series_60min_singleindex_filtered.csv``: Hourly per-country load profiles since 2010 from the `ENTSO-E statistical database <https://www.entsoe.eu/data/power-stats/hourly_load/>`_
+
+    .. image:: img/load-box.png
+        :scale: 33 %
+
+    .. image:: img/load-ts.png
+        :scale: 33 %
+
 - ``resources/regions_onshore.geojson``: confer :ref:`busregions`
 - ``resources/nuts3_shapes.geojson``: confer :ref:`shapes`
 - ``resources/powerplants.csv``: confer :ref:`powerplants`
@@ -60,14 +71,16 @@ Outputs
 Description
 -----------
 
+The rule ``add_electricity`` ties all the different data inputs from the preceding rules together into a detailed PyPSA network that is stored in ``networks/elec.nc``. It includes:
+
 - 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``)
+- photovoltaic, onshore and AC- as well as DC-connected offshore wind installations with today's locational, hourly wind and solar capacity factors (but **no** current capacities),
+- long-term hydrogen and short-term battery storage units (if listed in the config setting ``electricity: extendable_carriers``), and
 - additional open- and combined-cycle gas turbines (if ``OCGT`` and/or ``CCGT`` is listed in the config setting ``electricity: extendable_carriers``)
 """
 

scripts/base_network.py

@@ -32,10 +32,10 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/entsoegridkit``:
-- ``data/parameter_corrections.yaml``:
+- ``data/entsoegridkit``:  Extract from the geographical vector data of the online `ENTSO-E Interactive Map <https://www.entsoe.eu/data/map/>`_ by the `GridKit <https://github.com/pypsa/gridkit>`_ toolkit. 
+- ``data/parameter_corrections.yaml``: Corrections for ``data/entsoegridkit``
 - ``data/links_p_nom.csv``: confer :ref:`links`
-- ``data/links_tyndp.csv``:
+- ``data/links_tyndp.csv``: List of projects in the `TYNDP 2018 <https://tyndp.entsoe.eu/tyndp2018/>`_ that are at least *in permitting* with fields for start- and endpoint (names and coordinates), length, capacity, construction status, and project reference ID.
 - ``resources/country_shapes.geojson``: confer :ref:`shapes`
 - ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
 - ``resources/europe_shape.geojson``: confer :ref:`shapes`

scripts/build_country_flh.py

@@ -18,12 +18,18 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/bundle/corine/g250_clc06_V18_5.tif``:
+- ``data/bundle/corine/g250_clc06_V18_5.tif``: `CORINE Land Cover (CLC) <https://land.copernicus.eu/pan-european/corine-land-cover>`_ inventory on `44 classes <https://wiki.openstreetmap.org/wiki/Corine_Land_Cover#Tagging>`_ of land use (e.g. forests, arable land, industrial, urban areas).
 
     .. image:: img/corine.png
         :scale: 33 %
 
-- ``data/bundle/GEBCO_2014_2D.nc``:
+- ``data/bundle/GEBCO_2014_2D.nc``:  A `bathymetric <https://en.wikipedia.org/wiki/Bathymetry>`_ data set with a global terrain model for ocean and land at 15 arc-second intervals by the `General Bathymetric Chart of the Oceans (GEBCO) <https://www.gebco.net/data_and_products/gridded_bathymetry_data/>`_.
+
+    .. image:: img/gebco_2019_grid_image.jpg
+        :scale: 50 %
+
+    **Source:** `GEBCO <https://www.gebco.net/data_and_products/images/gebco_2019_grid_image.jpg>`_
+
 - ``data/pietzker2014.xlsx``: NOT IN DATA BUNDLE!
 - ``resources/natura.tiff``: confer :ref:`natura`
 - ``resources/country_shapes.geojson``: confer :ref:`shapes`

scripts/build_hydro_profile.py

@@ -17,7 +17,11 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/bundle/EIA_hydro_generation_2000_2014.csv``:
+- ``data/bundle/EIA_hydro_generation_2000_2014.csv``: Hydroelectricity net generation per country and year (`EIA <https://www.eia.gov/beta/international/data/browser/#/?pa=000000000000000000000000000000g&c=1028i008006gg6168g80a4k000e0ag00gg0004g800ho00g8&ct=0&ug=8&tl_id=2-A&vs=INTL.33-12-ALB-BKWH.A&cy=2014&vo=0&v=H&start=2000&end=2016>`_)
+
+    .. image:: img/hydrogeneration.png
+        :scale: 33 %
+
 - ``resources/country_shapes.geojson``: confer :ref:`shapes`
 - ``"cutouts/" + config["renewable"]['hydro']['cutout']``: confer :ref:`cutout`
 
@@ -30,7 +34,7 @@ Description
 -----------
 
 .. seealso::
-    build_renewable_profiles
+    :mod:`build_renewable_profiles`
 """
 
 import os

scripts/build_natura_raster.py

@@ -13,7 +13,7 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/bundle/natura/Natura2000_end2015.shp``:
+- ``data/bundle/natura/Natura2000_end2015.shp``: `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas.
 
     .. image:: img/natura.png
         :scale: 33 %
@@ -21,7 +21,7 @@ Inputs
 Outputs
 -------
 
-- ``resources/natura.tiff``:
+- ``resources/natura.tiff``: Rasterized version of `Natura 2000 <https://en.wikipedia.org/wiki/Natura_2000>`_ natural protection areas to reduce computation times.
 
     .. image:: img/natura.png
         :scale: 33 %

scripts/build_powerplants.py

@@ -18,7 +18,12 @@ Inputs
 Outputs
 -------
 
-- ``resource/powerplants.csv``
+- ``resource/powerplants.csv``: A list of conventional power plants (i.e. neither wind nor solar) with fields for name, fuel type, technology, country, capacity in MW, duration, commissioning year, retrofit year, latitude, longitude, and dam information as documented in the `powerplantmatching README <https://github.com/FRESNA/powerplantmatching/blob/master/README.md>`_; additionally it includes information on the closest substation/bus in ``networks/base.nc``.
+
+    .. image:: img/powerplantmatching.png
+        :scale: 30 %
+
+    **Source:** `powerplantmatching on GitHub <https://github.com/FRESNA/powerplantmatching>`_
 
 Description
 -----------

scripts/build_renewable_profiles.py

@@ -39,8 +39,18 @@ Relevant settings
 Inputs
 ------
 
-- ``data/bundle/corine/g250_clc06_V18_5.tif``:
-- ``data/bundle/GEBCO_2014_2D.nc``:
+- ``data/bundle/corine/g250_clc06_V18_5.tif``: `CORINE Land Cover (CLC) <https://land.copernicus.eu/pan-european/corine-land-cover>`_ inventory on `44 classes <https://wiki.openstreetmap.org/wiki/Corine_Land_Cover#Tagging>`_ of land use (e.g. forests, arable land, industrial, urban areas).
+
+    .. image:: img/corine.png
+        :scale: 33 %
+
+- ``data/bundle/GEBCO_2014_2D.nc``: A `bathymetric <https://en.wikipedia.org/wiki/Bathymetry>`_ data set with a global terrain model for ocean and land at 15 arc-second intervals by the `General Bathymetric Chart of the Oceans (GEBCO) <https://www.gebco.net/data_and_products/gridded_bathymetry_data/>`_.
+
+    .. image:: img/gebco_2019_grid_image.jpg
+        :scale: 50 %
+
+    **Source:** `GEBCO <https://www.gebco.net/data_and_products/images/gebco_2019_grid_image.jpg>`_
+    
 - ``resources/natura.tiff``: confer :ref:`natura`
 - ``resources/country_shapes.geojson``: confer :ref:`shapes`
 - ``resources/offshore_shapes.geojson``: confer :ref:`shapes`
@@ -68,29 +78,24 @@ Description:
 -----------------
 
 First the script computes how much of the technology can be installed at each
-cutout grid cell and each node using the library `GLAES
-<https://github.com/FZJ-IEK3-VSA/glaes>`_. This uses the CORINE land use data,
-Natura2000 nature reserves and GEBCO for bathymetry.
+cutout grid cell and each node using the `GLAES
+<https://github.com/FZJ-IEK3-VSA/glaes>`_ library. This uses the CORINE land use data,
+Natura2000 nature reserves and GEBCO bathymetry data.
 
-To compute the layout of generators in each node's voronoi cell, the installable
+To compute the layout of generators in each node's `Voronoi cell <https://en.wikipedia.org/wiki/Voronoi_diagram>`_, the installable
 potential in each grid cell is multiplied with the capacity factor at each grid
-cell (since we assume more generators are installed at cells with a higher
-capacity factor).
+cell. This is done since we assume more generators are installed at cells with a higher
+capacity factor.
 
 This layout is then used to compute the generation availability time series from
-the atlite cutout.
+the weather data cutout from ``atlite``.
 
 Two methods are available to compute the maximal installable potential for the
-node (`p_nom_max`): `simple` and `conservative`:
+node (`p_nom_max`): ``simple`` and ``conservative``:
 
-`simple` adds up the installable potentials of the individual grid cells (if the
-model comes close to this limit, then the time series may slightly overestimate
-production since we assumed the geographical distribution is proportional to
-capacity factor).
-
-`conservative` assertains the nodal limit by increasing capacities proportional
-to the layout until the limit of an individual grid cell is reached.
+- ``simple`` adds up the installable potentials of the individual grid cells. If the model comes close to this limit, then the time series may slightly overestimate production since it is assumed the geographical distribution is proportional to capacity factor.
 
+- ``conservative`` assertains the nodal limit by increasing capacities proportional to the layout until the limit of an individual grid cell is reached.
 """
 
 import matplotlib.pyplot as plt

scripts/cluster_network.py

@@ -30,37 +30,39 @@ Outputs
 -------
 
 - ``resources/regions_onshore_{network}_s{simpl}_{clusters}.geojson``:
+
+    .. image:: img/regions_onshore_elec_s_X.png
+        :scale: 33 %
+
 - ``resources/regions_offshore_{network}_s{simpl}_{clusters}.geojson``:
-- ``resources/clustermaps_{network}_s{simpl}_{clusters}.h5``:
-- ``networks/{network}_s{simpl}_{clusters}.nc``:
+
+    .. image:: img/regions_offshore_elec_s_X.png
+        :scale: 33 %
+
+- ``resources/clustermaps_{network}_s{simpl}_{clusters}.h5``: Mapping of buses and lines from ``networks/elec_s{simpl}.nc`` to ``networks/elec_s{simpl}_{clusters}.nc``; has keys ['/busmap', '/busmap_s', '/linemap', '/linemap_negative', '/linemap_positive']
+- ``networks/{network}_s{simpl}_{clusters}.nc``: 
+
+    .. image:: img/elec_s_X.png
+        :scale: 40  %
 
 Description
 -----------
 
-The rule cluster_network instead clusters the network to a given number of buses.
+.. note::
 
-    -Why is this cluster function used?
-    -Why the user can set a number behind the elec_sXXX for simplification?
+    **Why is clustering used both in** ``simplify_network`` **and** ``cluster_network`` **?**
+    
+        Consider for example a network ``networks/elec_s100_50.nc`` in which ``simplify_network`` clusters the network to 100 buses and in a second step ``cluster_network``` reduces it down to 50 buses.
 
-As you found out for yourself, elec_s100_50.nc for example is a network in which simplify_network clusters the network to 100 buses and in a second step cluster_network reduces it down to 50 buses.
+        In preliminary tests, it turns out, that the principal effect of changing spatial resolution is actually only partially due to the transmission network. It is more important to differentiate between wind generators with higher capacity factors from those with lower capacity factors, i.e. to have a higher spatial resolution in the renewable generation than in the number of buses.
 
-Well, let me provide a use-case where this makes sense:
+        The two-step clustering allows to study this effect by looking at networks like ``networks/elec_s100_50m.nc``. Note the additional ``m`` in the ``{cluster}`` wildcard). So in the example network there are still up to 100 different wind generators.
 
-In preliminary tests, it turns out, that the principal effect of changing spatial resolution is actually only partially due to the transmission network. It is more important to differentiate between wind generators with higher capacity factors from those with lower capacity factors, ie to have a higher spatial resolution in the renewable generation than in the number of buses.
+        In combination these two features allow you to study the spatial resolution of the transmission network separately from the spatial resolution of renewable generators.
 
-This two-step clustering can take advantage of that fact (and allows to study it)
-by looking at networks like networks/elec_s100_50m.nc (note the additional m in the cluster wildcard). For this example simplify_network clusters to 100 buses and then cluster_network clusters to 50m buses, which means 50 buses for the network topology but only moving instead of aggregating the generators to the clustered buses. So in this network you still have up to 100 different wind generators, 2 at each bus on average.
+    **Is it possible to run the model without the** ``simplify_network`` **rule?**
 
-In combination these two features allow you to study the spatial resolution of the transmission network separately from the spatial resolution of renewable generators. Beware: There is no clear evidence telling you what is a good representation of the full model. These options are under active study.
-
-    Why we have a cluster function inside of the simplification method?
-
-Why are you asking three times the same question?
-
-    Is it possible to run the model without the simplification method / rule?
-    I tryed to run the snakemake without the s for simplification.
-
-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.
+        No, the network clustering methods in the PyPSA module `pypsa.networkclustering <https://github.com/PyPSA/PyPSA/blob/master/pypsa/networkclustering.py>`_ do not work reliably with multiple voltage levels and transformers.
 
 .. tip::
     The rule ``cluster_all_networks`` runs

scripts/prepare_network.py

@@ -21,13 +21,13 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/costs.csv``:
+- ``data/costs.csv``: The database of cost assumptions for all included technologies for specific years from various sources; e.g. discount rate, lifetime, investment (CAPEX), fixed operation and maintenance (FOM), variable operation and maintenance (VOM), fuel costs, efficiency, carbon-dioxide intensity.
 - ``networks/{network}_s{simpl}_{clusters}.nc``: confer :ref:`cluster`
 
 Outputs
 -------
 
-- ``networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``:
+- ``networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: Complete PyPSA network that will be handed to the ``solve_network`` rule.
 
 Description
 -----------

scripts/simplify_network.py

@@ -35,7 +35,7 @@ Relevant Settings
 Inputs
 ------
 
-- ``data/costs.csv``:
+- ``data/costs.csv``: The database of cost assumptions for all included technologies for specific years from various sources; e.g. discount rate, lifetime, investment (CAPEX), fixed operation and maintenance (FOM), variable operation and maintenance (VOM), fuel costs, efficiency, carbon-dioxide intensity.
 - ``resources/regions_onshore.geojson``: confer :ref:`busregions`
 - ``resources/regions_offshore.geojson``: confer :ref:`busregions`
 - ``networks/{network}.nc``: confer :ref:`electricity`
@@ -44,8 +44,16 @@ Outputs
 -------
 
 - ``resources/regions_onshore_{network}_s{simpl}.geojson``:
+
+    .. image:: img/regions_onshore_elec_s.png
+            :scale: 33 %
+
 - ``resources/regions_offshore_{network}_s{simpl}.geojson``:
-- ``resources/clustermaps_{network}_s{simpl}.h5``:
+
+    .. image:: img/regions_offshore_elec_s  .png
+            :scale: 33 %
+
+- ``resources/clustermaps_{network}_s{simpl}.h5``: Mapping of buses from ``networks/elec.nc`` to ``networks/elec_s{simpl}.nc``; has keys ['/busmap_s']
 - ``networks/{network}_s{simpl}.nc``:
 
     .. image:: img/elec_s.png
@@ -54,15 +62,15 @@ Outputs
 Description
 -----------
 
-The rule simplify_network does up to four things:
+The rule ``simplify_network`` does up to four things:
 
 1. Create an equivalent transmission network in which all voltage levels are mapped to the 380 kV level by the function ``simplify_network(...)``.
 
-2. DC only sub-networks that are connected at only two buses to the AC network are reduced to a single representative link by the function ``simplify_links(...)``. The components attached to buses in between are moved to the nearest endpoint. The grid connection cost of offshore wind generators are added to the captial costs of the generator.
+2. DC only sub-networks that are connected at only two buses to the AC network are reduced to a single representative link in the function ``simplify_links(...)``. The components attached to buses in between are moved to the nearest endpoint. The grid connection cost of offshore wind generators are added to the captial costs of the generator.
 
-3. Stub lines and links, i.e. dead-ends of the network, are sequentially removed from the network by the function ``remove_stubs(...)``. Components are moved along.
+3. Stub lines and links, i.e. dead-ends of the network, are sequentially removed from the network in the function ``remove_stubs(...)``. Components are moved along.
 
-4. If a number was provided after the s (as in elec_s500_...), the network is clustered to this number of clusters with the routines from the cluster_network rule by the function cluster. This step is usually skipped.
+4. Optionally, if an integer were provided for the wildcard ``{simpl}`` (e.g. ``networks/elec_s500.nc``), the network is clustered to this number of clusters with the routines from the ``cluster_network`` rule with the function ``cluster_network.cluster(...)``. This step is usually skipped!
 """
 
 import pandas as pd

scripts/solve_network.py

@@ -35,10 +35,7 @@ Inputs
 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``:
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: Solved PyPSA network including optimisation results
 
 Description
 -----------

scripts/solve_operations_network.py

@@ -30,10 +30,7 @@ Inputs
 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``:
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}_op.nc``: Solved PyPSA network for optimal dispatch including optimisation results
 
 Description
 -----------

scripts/trace_solve_network.py

@@ -29,8 +29,7 @@ Inputs
 Outputs
 -------
 
-- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}_trace.nc``:
-- ``logs/{network}_s{simpl}_{clusters}_l{ll}_{opts}_python_trace.log``:
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}_trace.nc``: Solved PyPSA network including optimisation results (with trace)
 
 Description
 -----------