configuration table descriptions

doc/conf.py

@@ -19,7 +19,7 @@ import shlex
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../scripts'))
 
 # -- General configuration ------------------------------------------------
 
@@ -35,7 +35,7 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
-    #'sphinx.ext.napoleon',
+    'sphinx.ext.napoleon',
     #'sphinx.ext.pngmath',
     #'sphinxcontrib.tikz',
     #'rinoh.frontend.sphinx',

doc/configtables/atlite.csv

@@ -0,0 +1,13 @@
+,Unit,Values,Description
+nprocesses,--,{'E'},TODO
+cutouts,--,E,TODO
+-- europe-2013-era5,--,E,TODO
+-- -- module,--,E,TODO
+-- -- xs,--,E,TODO
+-- -- ys,--,E,TODO
+-- -- years,--,E,TODO
+-- europe-2013-sarah,--,E,TODO
+-- -- module,--,E,TODO
+-- -- xs,--,E,TODO
+-- -- ys,--,E,TODO
+-- -- years,--,E,TODO

doc/configtables/costs.csv

@@ -0,0 +1,7 @@
+,Unit,Values,Description
+year,--,{'E'},TODO
+discountrate,--,E,TODO
+USD2013_to_EUR2013,--,E,TODO
+capital_cost,--,E,TODO
+marginal_cost,--,E,TODO
+emission_prices,--,E,TODO

doc/configtables/electricity.csv

@@ -0,0 +1,10 @@
+,Unit,Values,Description
+voltages,--,{'E'},TODO
+co2limit,--,E,TODO
+extendable_carriers,--,E,TODO
+-- Generator,--,E,TODO
+-- StorageUnit,--,E,TODO
+max_hours,--,E,TODO
+-- battery,--,E,TODO
+-- H2,--,E,TODO
+conventional_carriers,--,E,TODO

doc/configtables/hydro.csv

@@ -0,0 +1,6 @@
+,Unit,Values,Description
+cutout,--,{'E'},TODO
+carriers,--,E,TODO
+PHS_max_hours,--,E,TODO
+hydro_max_hours,--,E,TODO
+clip_min_inflow,--,E,TODO

doc/configtables/lines.csv

@@ -0,0 +1,9 @@
+,Unit,Values,Description
+types,--,{'E'},TODO
+-- 220.,--,E,TODO
+-- 300.,--,E,TODO
+-- 380.,--,E,TODO
+s_max_pu,--,E,TODO
+length_factor,--,E,TODO
+length_factor,--,E,TODO
+under_construction,--,E,TODO

doc/configtables/links.csv

@@ -0,0 +1,4 @@
+,Unit,Values,Description
+p_max_pu,--,{'E'},TODO
+include_tyndp,--,E,TODO
+under_construction,--,E,TODO

doc/configtables/load.csv

@@ -0,0 +1,2 @@
+,Unit,Values,Description
+scaling_factor,--,{'E'},TODO

doc/configtables/offwind-ac.csv

@@ -0,0 +1,12 @@
+,Unit,Values,Description
+cutout,--,{'E'},TODO
+resource,--,E,TODO
+-- method,--,E,TODO
+-- turbine,--,E,TODO
+capacity_per_sqkm,--,E,TODO
+corine,--,E,TODO
+natura,--,E,TODO
+max_depth,--,E,TODO
+min_shore_distance,--,E,TODO
+potential,--,E,TODO
+clip_p_max_pu,--,E,TODO

doc/configtables/offwind-dc.csv

@@ -0,0 +1,12 @@
+,Unit,Values,Description
+cutout,--,{'E'},TODO
+resource,--,E,TODO
+-- method,--,E,TODO
+-- turbine,--,E,TODO
+capacity_per_sqkm,--,E,TODO
+corine,--,E,TODO
+natura,--,E,TODO
+max_depth,--,E,TODO
+min_shore_distance,--,E,TODO
+potential,--,E,TODO
+clip_p_max_pu,--,E,TODO

doc/configtables/onwind.csv

@@ -0,0 +1,13 @@
+,Unit,Values,Description
+cutout,--,{'E'},TODO
+resource,--,E,TODO
+-- method,--,E,TODO
+-- turbine,--,E,TODO
+capacity_per_sqkm,--,E,TODO
+corine,--,E,TODO
+-- grid_codes,--,E,TODO
+-- distance,--,E,TODO
+-- distance_grid_codes,--,E,TODO
+natura,--,E,TODO
+potential,--,E,TODO
+clip_p_max_pu,--,E,TODO

doc/configtables/plotting.csv

@@ -0,0 +1,24 @@
+,Unit,Values,Description
+map,--,{'E'},TODO
+-- figsize,--,E,TODO
+-- boundaries,--,E,TODO
+-- p_nom,--,E,TODO
+-- -- bus_size_factor,--,E,TODO
+-- -- linewidth_factor,--,E,TODO
+costs_max,--,E,TODO
+costs_threshold,--,E,TODO
+energy_max,--,E,TODO
+energy_min,--,E,TODO
+energy_threshold,--,E,TODO
+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

doc/configtables/scenario.csv

@@ -0,0 +1,6 @@
+,Unit,Values,Description
+sectors,--,{'E'},TODO
+simpl,--,E,TODO
+ll,--,E,TODO
+clusters,--,E,TODO
+opts,--,E,TODO

doc/configtables/snapshots.csv

@@ -0,0 +1,4 @@
+,Unit,Values,Description
+start,--,{'E'},TODO
+end,--,E,TODO
+closed,--,E,TODO

doc/configtables/solar.csv

@@ -0,0 +1,14 @@
+,Unit,Values,Description
+cutout,--,{'E'},TODO
+resource,--,E,TODO
+-- method,--,E,TODO
+-- panel,--,E,TODO
+-- orientation,--,E,TODO
+-- -- slope,--,E,TODO
+-- -- azimuth,--,E,TODO
+capacity_per_sqkm,--,E,TODO
+correction_factor,--,E,TODO
+corine,--,E,TODO
+natura,--,E,TODO
+potential,--,E,TODO
+clip_p_max_pu,--,E,TODO

doc/configtables/solving-options.csv

@@ -0,0 +1,8 @@
+,Unit,Values,Description
+formulation,--,{'E'},TODO
+load_shedding,--,E,TODO
+noisy_costs,--,E,TODO
+min_iterations,--,E,TODO
+max_iterations,--,E,TODO
+nhours,--,E,TODO
+clip_p_max_pu,--,E,TODO

doc/configtables/solving-solver.csv

@@ -0,0 +1,3 @@
+,Unit,Values,Description
+name,--,{'E'},TODO
+opts,--,E,TODO

doc/configtables/toplevel.csv

@@ -0,0 +1,8 @@
+,Unit,Values,Description
+version,--,{'E'},TODO
+logging_level,--,E,TODO
+summary_dir,--,E,TODO
+countries,--,E,TODO
+enable,--,E,TODO
+-- powerplantmatching,--,{'E'},TODO
+-- prepare_links_p_nom,--,E,TODO

doc/configtables/transformers.csv

@@ -0,0 +1,4 @@
+,Unit,Values,Description
+x,--,{'E'},TODO
+s_nom,--,E,TODO
+type,--,E,TODO

doc/configuration.rst

@@ -2,8 +2,175 @@
 Configuration
 ##########################################
 
-Section A
+Single-level entries
-=========
+====================
 
-Section B
+.. literalinclude:: ../config.yaml
-=========
+   :language: yaml
+   :lines: 1-5,15
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/toplevel.csv
+
+Wildcards and ``scenario``
+==========================
+
+.. literalinclude:: ../config.yaml
+   :language: yaml
+   :lines: 6-13
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/scenario.csv
+   
+
+
+``snapshots``
+=============
+
+.. literalinclude:: ../config.yaml
+   :language: yaml
+   :lines: 17-21
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/snapshots.csv
+
+
+``electricity``
+===============
+
+.. literalinclude:: ../config.yaml
+   :language: yaml
+   :lines: 27-44
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/electricity.csv
+
+``atlite``
+=============
+
+.. literalinclude:: ../config.yaml
+   :language: yaml
+   :lines: 46-59
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/atlite.csv
+
+``renewable``
+=============
+
+``onwind``
+----------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/onwind.csv
+
+``offwind-ac``
+--------------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/offwind-ac.csv
+
+``offwind-dc``
+---------------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/offwind-dc.csv
+
+``solar``
+---------------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/solar.csv
+
+``hydro``
+---------------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/hydro.csv
+
+``lines``
+=============
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/lines.csv
+
+``links``
+=============
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/links.csv
+
+``transformers``
+================
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/transformers.csv
+
+``load``
+=============
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/load.csv
+
+``costs``
+=============
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/costs.csv
+
+``solving``
+=============
+
+``options``
+-----------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/solving-options.csv
+
+``solver``
+----------
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/solving-solver.csv
+
+``plotting``
+=============
+
+.. csv-table::
+   :header-rows: 1
+   :align: left
+   :file: configtables/plotting.csv

doc/installation.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 ##########################################
 Installation
 ##########################################
@@ -23,6 +25,7 @@ Clone the PyPSA-Eur repository using ``git``
     The path to the directory into which the ``git repository`` is cloned, 
     must not have any spaces.
 
+.. _deps:
 
 Install Python Dependencies
 ===============================
@@ -43,6 +46,7 @@ The environment can be installed and activated using
     After opening a new terminal window,
     one needs to reissue the second command! 
 
+.. _data:
 
 Download Data Dependencies
 ==============================

doc/introduction.rst

@@ -1,3 +1,5 @@
+.. _intro:
+
 ##########################################
  Introduction
 ##########################################
@@ -7,3 +9,8 @@ Section A
 
 Section B
 =========
+
+System Requirements
+===================
+
+Building the model with the scripts in this repository uses up to 20 GB of memory. Computing optimal investment and operation scenarios requires a strong interior-point solver compatible with the modelling library `Pyomo <https://www.pyomo.org>`_ like `Gurobi <http://www.gurobi.com/>`_ or `CPLEX <https://www.ibm.com/analytics/cplex-optimizer>`_ with up to 100 GB of memory.

doc/plotting.rst

@@ -5,6 +5,8 @@ Plotting and Summary
 Make Summary
 ============
 
+.. automodule:: make_summary
+
 Plot Summary
 ============
 

doc/simplification.rst

@@ -1,3 +1,5 @@
+
+
 ##########################################
 Simplifying Networks
 ##########################################
@@ -5,8 +7,45 @@ Simplifying Networks
 Simplify Network
 ================
 
+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.
+
+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.
+
+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.
+
+
 Cluster Network
 ===============
 
+The rule cluster_network instead clusters the network to a given number of buses.
+
+    -Why is this cluster function used?
+    -Why the user can set a number behind the elec_sXXX for simplification?
+
+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.
+
+Well, let me provide a use-case where this makes sense:
+
+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.
+
+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.
+
+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.
+
+
 Prepare Network
 ===============

scripts/make_summary.py

@@ -1,3 +1,16 @@
+"""
+Test module description
+
+Examples
+--------
+Test example
+`Example <http://www.example.com>`_
+
+:ref:`Installation <installation>`
+
+``code``
+"""
+
 import os
 from six import iteritems
 from itertools import product