Merge pull request #65 from PyPSA/documentation

Documentation
2019-10-24 16:26:53 +02:00 · 2019-10-24 16:26:53 +02:00 · ca51c172f0
commit ca51c172f0
parent c18d00a9ef 0fef13ee86
125 changed files with 5149 additions and 522 deletions
--- a/.gitignore
+++ b/.gitignore
@ -12,4 +12,8 @@ gurobi.log
 /notebooks
 /data
 /data/links_p_nom.csv
-/cutouts
+/cutouts
 doc/_build
 config.yaml
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@ -0,0 +1,4 @@
 version: 2
 conda:
    environment: environment.docs.yaml
--- a/README.md
+++ b/README.md
@ -1,21 +1,28 @@
 ![Version](https://img.shields.io/github/tag-date/pypsa/pypsa-eur)
 [![Documentation](https://readthedocs.org/projects/pypsa-eur/badge/?version=latest)](https://pypsa-eur.readthedocs.io/en/latest/?badge=latest)
 ![GitHub](https://img.shields.io/github/license/pypsa/pypsa-eur)
 ![Size](https://img.shields.io/github/repo-size/pypsa/pypsa-eur)
 [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.1246852.svg)](https://doi.org/10.5281/zenodo.1246852)
 [![Gitter](https://badges.gitter.im/PyPSA/community.svg)](https://gitter.im/PyPSA/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 # PyPSA-Eur: An Open Optimisation Model of the European Transmission System
 PyPSA-Eur is an open model dataset of the European power system at the
 transmission network level that covers the full ENTSO-E area.
 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.
-![PyPSA-Eur Grid Model](https://raw.githubusercontent.com/PyPSA/pypsa-eur/master/img/pypsa-eur-grid.png)
+The model is described in the [documentation](https://pypsa-eur.readthedocs.io)
-
+and in the paper
 The model is described and partially validated in the paper
 [PyPSA-Eur: An Open Optimisation Model of the European Transmission
 System](https://arxiv.org/abs/1806.01613), 2018,
 [arXiv:1806.01613](https://arxiv.org/abs/1806.01613).
-This repository contains the scripts and some of the data required to
+![PyPSA-Eur Grid Model](doc/img/base.png)
 automatically build the dataset from openly-available sources.
-Already-built versions of the model can be found in the accompanying [Zenodo
+![PyPSA-Eur Grid Model Simplified](doc/img/elec_s_X.png)
 repository](https://zenodo.org/record/1246851).
 The model is designed to be imported into the open toolbox
 [PyPSA](https://github.com/PyPSA/PyPSA) for operational studies as
@ -33,168 +40,7 @@ The dataset consists of:
 - Electrical demand time series from the
  [OPSD project](https://open-power-system-data.org/).
 - Renewable time series based on ERA5 and SARAH, assembled using the [atlite tool](https://github.com/FRESNA/atlite).
- Geographical potentials for wind and solar generators based on land use (CORINE) and excluding nature reserves (Natura2000) are computed with the [vresutils library](https://github.com/FRESNA/vresutils).
+- Geographical potentials for wind and solar generators based on land use (CORINE) and excluding nature reserves (Natura2000) are computed with the [vresutils library](https://github.com/FRESNA/vresutils) and the [glaes library](https://github.com/FZJ-IEK3-VSA/glaes).
-Building the model with the scripts in this repository uses up to 20GB of
+Already-built versions of the model can be found in the accompanying [Zenodo
-memory. Computing optimal investment and operation scenarios requires a strong
+repository](https://zenodo.org/record/1246851).
 interior-point solver compatible with the modelling library
 [PYOMO](https://github.com/Pyomo/pyomo) like Gurobi or CPLEX with up to 100GB of
 memory (for the 356-bus approximation).
 This project is maintained by the [Energy System Modelling
 group](https://www.iai.kit.edu/english/2338.php) at the [Institute for
 Automation and Applied
 Informatics](https://www.iai.kit.edu/english/index.php) at the
 [Karlsruhe Institute of
 Technology](http://www.kit.edu/english/index.php). It is currently
 funded by the [Helmholtz
 Association](https://www.helmholtz.de/en/). Previous versions were
 developed by the [Renewable Energy
 Group](https://fias.uni-frankfurt.de/physics/schramm/renewable-energy-system-and-network-analysis/)
 at [FIAS](https://fias.uni-frankfurt.de/) to carry out simulations for
 the [CoNDyNet project](http://condynet.de/), financed by the [German
 Federal Ministry for Education and Research
 (BMBF)](https://www.bmbf.de/en/index.html) as part of the [Stromnetze
 Research
 Initiative](http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/).
 # Installation
 The steps are demonstrated as shell commands, where the path before the `%` sign denotes the
 directory in which the commands following the `%` should be entered.
 Clone the repository using `git` (**to a directory without any spaces in the path**)
 ```shell
 /some/other/path % cd /some/path/without/spaces
 /some/path/without/spaces % git clone https://github.com/PyPSA/pypsa-eur.git
 ```
 ## Python dependencies
 The python package requirements are curated in the conda [environment.yaml](environment.yaml) file.
 The environment can be installed and activated using
 ```shell
 .../pypsa-eur % conda env create -f environment.yaml
 .../pypsa-eur % conda activate pypsa-eur   # or source activate pypsa-eur on older linux installations
 ```
 **Note that activation is local to the currently open shell! After opening a new terminal window, one needs to reissue the second command!**
 ## Data dependencies
 Not all data dependencies are shipped with the git repository (since git is not suited for handling large changing files). Instead we provide two separate data bundles:
 1. [pypsa-eur-data-bundle.tar.xz](https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/pypsa-eur-data-bundle.tar.xz) contains common GIS datasets like NUTS3 shapes, EEZ shapes, CORINE Landcover, Natura 2000 and also electricity specific summary statistics like historic per country yearly totals of hydro generation, GDP and POP on NUTS3 levels and per-country load time-series. It should be extracted in the `data` subdirectory (so that all files are in the `data/bundle` subdirectory)
 ```shell
 .../pypsa-eur/data % curl -OL "https://vfs.fias.science/d/0a0ca1e2fb/files/?dl=1&p=/pypsa-eur-data-bundle.tar.xz"
 .../pypsa-eur/data % tar xJf pypsa-eur-data-bundle.tar.xz
 ```
 2. [pypsa-eur-cutouts.tar.xz](https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/pypsa-eur-cutouts.tar.xz) are spatiotemporal subsets of the European weather data from the [ECMWF ERA5](https://software.ecmwf.int/wiki/display/CKB/ERA5+data+documentation) reanalysis dataset and the [CMSAF SARAH-2](https://wui.cmsaf.eu/safira/action/viewDoiDetails?acronym=SARAH_V002) solar surface radiation dataset for the year 2013. They have been prepared by and are for use with the [atlite](https://github.com/FRESNA/atlite) tool. You can either generate them yourself using the `build_cutouts` snakemake rule or extract them directly in the `pypsa-eur` directory (extracting the bundle is recommended, since procuring the source weather data files for atlite is not properly documented at the moment):
 ```shell
 .../pypsa-eur % curl -OL "https://vfs.fias.science/d/0a0ca1e2fb/files/?dl=1&p=/pypsa-eur-cutouts.tar.xz"
 .../pypsa-eur % tar xJf pypsa-eur-cutouts.tar.xz
 ```
 3. Optionally, you can download a rasterized version of the NATURA dataset [natura.tiff](https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/natura.tiff&dl=1) and put it into the `resources` sub-directory. If you don't, it will be generated automatically, which takes several hours.
 ```shell
 .../pypsa-eur % curl -L "https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/natura.tiff&dl=1" -o "resources/natura.tiff"
 ```
 4. Optionally, if you want to save disk space, you can delete `data/pypsa-eur-data-bundle.tar.xz` and `pypsa-eur-cutouts.tar.xz` once extracting the bundles is complete. E.g.
 ```shell
 .../pypsa-eur % rm -rf data/pypsa-eur-data-bundle.tar.xz pypsa-eur-cutouts.tar.xz
 ```
 # Script overview
 The model has several configuration options collected in the [config.yaml](config.yaml) file
 located in the root directory.
 ## Model workflow
 The generation of the model is controlled by the workflow management system
 [Snakemake](https://snakemake.bitbucket.io/). In a nutshell, one declares in the
 `Snakefile` for each python script in the `scripts` directory a rule which
 describes which files the scripts consume and produce. `snakemake` then runs the
 scripts in the correct order and is able to track, what parts of the workflow
 have to be regenerated, when a data file or script is updated. For instance,
 with the [Snakefile of pypsa-eur](Snakefile), an invocation to
 ```shell
 snakemake networks/elec_s_128.nc
 ```
 follows the dependency graph
 ![Dependency graph for network elec_s_128](img/dependencies-elec_s_128.png)
 ## Building the network
 In detail this means it has to run the independent scripts,
 - `build_shapes` to generate GeoJSON files with country, exclusive economic zones and nuts3 shapes
 - `build_cutout` to prepare smaller weather data portions from ERA5 for cutout `europe-2013-era5` and SARAH for cutout `europe-2013-sarah`.
 With these and the externally extracted `ENTSO-E online map topology`, it can build the PyPSA basis model
 - `base_network` stored at `networks/base.nc` with all `buses`, HVAC `lines` and HVDC `links`, and in
 - `build_bus_regions` determine the Voronoi cell of each substation.
 Then it hands these over to the scripts for generating renewable and hydro feedin data,
 - `build_hydro_profile` for the hourly hydro energy availability,
 - `build_renewable_potentials` for the landuse/natura2000 constrained installation potentials for PV and wind,
 - `build_renewable_profiles` for the PV and wind hourly capacity factors in each Voronoi cell.
 - `build_powerplants` uses [powerplantmatching](https://github.com/FRESNA/powerplantmatching) to determine today's thermal power plant capacities and then locates the closest substation for each powerplant.
 The central rule `add_electricity` then ties all the different data inputs together to a detailed PyPSA model stored in `networks/elec.nc`, containing:
 - Today's transmission topology and 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 generation capacities (for the technologies listed in the config setting `electricity: conventional_carriers`)
 - Today's load time-series (upsampled according to population and gross domestic product)
 It further adds extendable `generators` and `storage_units` with *zero* capacity for
 - wind and pv installations with today's locational, hourly wind and solar pv capacity factors (but **no** capacities)
 - long-term hydrogen and short-term battery storage units (if listed in `electricity: extendable_carriers`)
 - additional open-cycle gas turbines (if `OCGT` is listed in `electricity: extendable_carriers`)
 The additional rules prepare approximations of the full model, in which generation, storage and transmission capacities can be co-optimized
 - `simplify_network` transforms the transmission grid to a 380 kV-only equivalent network, while
 - `cluster_network` uses a kmeans based clustering technique to partition the network into a certain 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).
 ## Solving the network
 After generating the network it can be solved by using 'solve_all_elec_networks'. This runs the following rules:
 - 'cluster_network'
 - 'prepare_network'
 - 'solve_all_elec_networks'
 - 'solve_network'
 ## Summarising the results and making plots
 The following rule can be used to summarize the results in seperate .csv files:
 ```
 snakemake results/summaries/elec_s_all_lall_Co2L-3H_all
                                      ^ clusters
                                          ^ line volume or cost cap
                                               ^- options
                                                       ^- all countries
 ```
 the line volume/cost cap field can be set to one of the following:
 * `lv1.25` for a particular line volume extension by 25%
 * `lc1.25` for a line cost extension by 25 %
 * `lall` for all evalutated caps
 * `lvall` for all line volume caps
 * `lcall` for all line cost caps
 Replacing '/summaries/' with '/plots/' creates nice colored maps of the results.
 # Solver choice
 Default choice for the solver is Gurobi (freely available under academic license) or CPLEX. If you want to go fully opensource the CBC solver (https://projects.coin-or.org/Cbc) can be used. To install CBC run 'conda install -c conda-forge coincbc'.
 # Hints
 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`.
 The dependency graph shown above was generated using
 ```shell
 snakemake --dag networks/elec_s_128.nc | dot -Tpng > dependency-graph-elec_s_128.png
 ```
 # License
 The code in PyPSA-Eur is released as free software under the
 [GPLv3](http://www.gnu.org/licenses/gpl-3.0.en.html), see
 [LICENSE](LICENSE.txt).
--- a/29
+++ b/29
@ -93,7 +93,7 @@ rule build_bus_regions:
    script: "scripts/build_bus_regions.py"
 rule build_cutout:
-    output: "cutouts/{cutout}"
+    output: directory("cutouts/{cutout}")
    resources: mem=config['atlite'].get('nprocesses', 4) * 1000
    threads: config['atlite'].get('nprocesses', 4)
    benchmark: "benchmarks/build_cutout_{cutout}"
@ -110,7 +110,9 @@ rule build_renewable_profiles:
        base_network="networks/base.nc",
        corine="data/bundle/corine/g250_clc06_V18_5.tif",
        natura="resources/natura.tiff",
-        gebco="data/bundle/GEBCO_2014_2D.nc",
+        gebco=lambda wildcards: ("data/bundle/GEBCO_2014_2D.nc"
                                 if "max_depth" in config["renewable"][wildcards.technology].keys()
                                 else []),
        country_shapes='resources/country_shapes.geojson',
        offshore_shapes='resources/offshore_shapes.geojson',
        regions=lambda wildcards: ("resources/regions_onshore.geojson"
@ -124,15 +126,16 @@ rule build_renewable_profiles:
    # group: 'feedin_preparation'
    script: "scripts/build_renewable_profiles.py"
-rule build_hydro_profile:
+if 'hydro' in config['renewable'].keys():
-    input:
+    rule build_hydro_profile:
-        country_shapes='resources/country_shapes.geojson',
+        input:
-        eia_hydro_generation='data/bundle/EIA_hydro_generation_2000_2014.csv',
+            country_shapes='resources/country_shapes.geojson',
-        cutout="cutouts/" + config["renewable"]['hydro']['cutout']
+            eia_hydro_generation='data/bundle/EIA_hydro_generation_2000_2014.csv',
-    output: 'resources/profile_hydro.nc'
+            cutout="cutouts/" + config["renewable"]['hydro']['cutout']
-    resources: mem=5000
+        output: 'resources/profile_hydro.nc'
-    # group: 'feedin_preparation'
+        resources: mem=5000
-    script: 'scripts/build_hydro_profile.py'
+        # group: 'feedin_preparation'
        script: 'scripts/build_hydro_profile.py'
 rule add_electricity:
    input:
@ -305,7 +308,9 @@ rule build_country_flh:
        base_network="networks/base.nc",
        corine="data/bundle/corine/g250_clc06_V18_5.tif",
        natura="resources/natura.tiff",
-        gebco="data/bundle/GEBCO_2014_2D.nc",
+        gebco=lambda wildcards: ("data/bundle/GEBCO_2014_2D.nc"
                                 if "max_depth" in config["renewable"][wildcards.technology].keys()
                                 else []),
        country_shapes='resources/country_shapes.geojson',
        offshore_shapes='resources/offshore_shapes.geojson',
        pietzker="data/pietzker2014.xlsx",
--- a/config.default.yaml
+++ b/config.default.yaml
@ -4,18 +4,15 @@ logging_level: INFO
 summary_dir: results
 scenario:
-  sectors: [E] # ,E+EV,E+BEV,E+BEV+V2G] # [ E+EV, E+BEV, E+BEV+V2G ]
+  sectors: [E]
  simpl: ['']
-  #ll: ['v1.0', 'v1.09', 'v1.125', 'v1.18', 'v1.25', 'v1.35', 'v1.5', 'v1.7', 'v2.0', 'vopt'] # line limit a 'v' prefix means volume
+  ll: ['copt']
-  ll: ['vopt', 'copt'] #['v1.0', 'v1.125', 'v1.25', 'v1.5', 'v2.0', 'vopt'] # line limit a 'v' prefix means volume
+  clusters: [37, 100]
-  #ll: ['c1.0', 'v1.125', 'v1.25', 'v1.5', 'v2.0', 'vopt'] # line limit a 'v' prefix means volume
+  opts: [Co2L-3H]
  clusters: [37, 45, 64, 90, 128, 181, 256, 362, 512] # (2**np.r_[5.5:9:.5]).astype(int)
  opts: [Co2L-3H] #, LC-FL, LC-T, Ep-T, Co2L-T]
 countries: ['AL', 'AT', 'BA', 'BE', 'BG', 'CH', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GB', 'GR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'ME', 'MK', 'NL', 'NO', 'PL', 'PT', 'RO', 'RS', 'SE', 'SI', 'SK'] 
 snapshots:
  # arguments to pd.date_range
  start: "2013-01-01"
  end: "2014-01-01"
  closed: 'left' # end is not inclusive
@ -31,18 +28,13 @@ electricity:
  extendable_carriers:
    Generator: [OCGT]
-    StorageUnit: [battery, H2] # [CAES]
+    StorageUnit: [battery, H2]
  max_hours:
    battery: 6
    H2: 168
-  # estimate_renewable_capacities_from_capacity_stats:
+  conventional_carriers: [] # [nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass]
  #   # Wind is the Fueltype in ppm.data.Capacity_stats, onwind, offwind-{ac,dc} the carrier in PyPSA-Eur
  #   Wind: [onwind, offwind-ac, offwind-dc]
  #   Solar: [solar]
  conventional_carriers: [] # nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass]
 atlite:
  nprocesses: 4
@ -65,15 +57,11 @@ renewable:
    resource:
      method: wind
      turbine: Vestas_V112_3MW
-    # ScholzPhd Tab 4.3.1: 10MW/km^2
+    capacity_per_sqkm: 3 # ScholzPhd Tab 4.3.1: 10MW/km^2
    capacity_per_sqkm: 3
    # correction_factor: 0.93
    corine:
-      #The selection of CORINE Land Cover [1] types that are allowed for wind and solar are based on [2] p.42 / p.28
+      # Scholz, Y. (2012). Renewable energy based electricity supply at low costs:
-      #
+      #  development of the REMix model and application for Europe. ( p.42 / p.28)
      #[1] https://www.eea.europa.eu/ds_resolveuid/C9RK15EA06
      #
      #[2] Scholz, Y. (2012). Renewable energy based electricity supply at low costs: development of the REMix model and application for Europe.
      grid_codes: [12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
                   24, 25, 26, 27, 28, 29, 31, 32]
      distance: 1000
@ -91,7 +79,7 @@ renewable:
    corine: [44, 255]
    natura: true
    max_depth: 50
-    max_shore_distance: 80000
+    max_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
  offwind-dc:
@ -105,7 +93,7 @@ renewable:
    corine: [44, 255]
    natura: true
    max_depth: 50
-    min_shore_distance: 80000
+    min_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
  solar:
@ -116,16 +104,13 @@ renewable:
      orientation:
        slope: 35.
        azimuth: 180.
-    # ScholzPhd Tab 4.3.1: 170 MW/km^2
+    capacity_per_sqkm: 1.7 # ScholzPhd Tab 4.3.1: 170 MW/km^2
    capacity_per_sqkm: 1.7
    correction_factor: 0.854337
    # Determined by comparing uncorrected area-weighted full-load hours to those
    # published in Supplementary Data to
    # Pietzcker, Robert Carl, et al. "Using the sun to decarbonize the power
    # sector: The economic potential of photovoltaics and concentrating solar
    # power." Applied Energy 135 (2014): 704-720.
-    # Comparison is shown in resources/country_flh_aggregated_solar.csv
+    correction_factor: 0.854337
    corine: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
             14, 15, 16, 17, 18, 19, 20, 26, 31, 32]
    natura: true
@ -138,12 +123,12 @@ renewable:
    hydro_max_hours: "energy_capacity_totals_by_country" # one of energy_capacity_totals_by_country,
                                                         # estimate_by_large_installations or a float
    clip_min_inflow: 1.0
 lines:
  types:
    220.: "Al/St 240/40 2-bundle 220.0"
    300.: "Al/St 240/40 3-bundle 300.0"
    380.: "Al/St 240/40 4-bundle 380.0"
  s_max_pu: 0.7
  length_factor: 1.25
  under_construction: 'zero' # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity
@ -163,35 +148,27 @@ load:
 costs:
  year: 2030
-
+  discountrate: 0.07 # From a Lion Hirth paper, also reflects average of Noothout et al 2016
-  # From a Lion Hirth paper, also reflects average of Noothout et al 2016
+  USD2013_to_EUR2013: 0.7532 # [EUR/USD] ECB: https://www.ecb.europa.eu/stats/exchange/eurofxref/html/eurofxref-graph-usd.en.html
-  discountrate: 0.07
+  marginal_cost:
  # [EUR/USD] ECB: https://www.ecb.europa.eu/stats/exchange/eurofxref/html/eurofxref-graph-usd.en.html # noqa: E501
  USD2013_to_EUR2013: 0.7532
  # Marginal and capital costs can be overwritten
  # capital_cost:
  #   Wind: Bla
  marginal_cost: # 
    solar: 0.01
    onwind: 0.015
    offwind: 0.015
    hydro: 0.
    H2: 0.
    battery: 0.
-
+  emission_prices: # only used with the option Ep
  emission_prices: # only used with the option Ep (emission prices)
    co2: 0.
 solving:
  options:
    formulation: kirchhoff
-    #load_shedding: true
+    load_shedding: false
    noisy_costs: true
    min_iterations: 3
    max_iterations: 5
    #nhours: 10
    clip_p_max_pu: 0.01
    #nhours: 10
  solver:
    name: gurobi
    threads: 4
@ -216,28 +193,21 @@ plotting:
    boundaries: [-10.2, 29, 35,  72]
    p_nom:
      bus_size_factor: 5.e+4
-      linewidth_factor: 3.e+3 # 1.e+3  #3.e+3
+      linewidth_factor: 3.e+3
  costs_max: 800
  costs_threshold: 1
  energy_max: 15000.
  energy_min: -10000.
  energy_threshold: 50.
  vre_techs: ["onwind", "offwind-ac", "offwind-dc", "solar", "ror"]
  conv_techs: ["OCGT", "CCGT", "Nuclear", "Coal"]
  storage_techs: ["hydro+PHS", "battery", "H2"]
-  # store_techs: ["Li ion", "water tanks"]
+  load_carriers: ["AC load"]
  load_carriers: ["AC load"] #, "heat load", "Li ion load"]
  AC_carriers: ["AC line", "AC transformer"]
  link_carriers: ["DC line", "Converter AC-DC"] 
  heat_links: ["heat pump", "resistive heater", "CHP heat", "CHP electric",
               "gas boiler", "central heat pump", "central resistive heater", "central CHP heat",
               "central CHP electric", "central gas boiler"]
  heat_generators: ["gas boiler", "central gas boiler", "solar thermal collector", "central solar thermal collector"]
  tech_colors:
    "onwind" : "#235ebc"
    "onshore wind" : "#235ebc"
@ -332,22 +302,24 @@ plotting:
    "HVDC links" : "#8a1caf"
    "DC-DC" : "#8a1caf"
    "DC link" : "#8a1caf"
    # _helpers.load_network requirements
  nice_names:
-    # OCGT: "Gas"
+    OCGT: "Open-Cycle Gas"
-    # OCGT marginal: "Gas (marginal)"
+    CCGT: "Combined-Cycle Gas"
-    offwind: "offshore wind"
+    offwind-ac: "Offshore Wind (AC)"
-    onwind: "onshore wind"
+    offwind-dc: "Offshore Wind (DC)"
-    battery: "Battery storage"
+    onwind: "Onshore Wind"
    battery: "Battery Storage"
    H2: "Hydrogen Storage"
    lines: "Transmission lines"
    AC line: "AC lines"
    AC-AC: "DC lines"
    ror: "Run of river"
  nice_names_n:
-    offwind: "offshore\nwind"
+    OCGT: "Open-Cycle\nGas"
-    onwind: "onshore\nwind"
+    CCGT: "Combined-Cycle\nGas"
-    # OCGT: "Gas"
+    offwind-ac: "Offshore\nWind (AC)"
-    H2: "Hydrogen\nstorage"
+    offwind-dc: "Offshore\nWind (DC)"
-    # OCGT marginal: "Gas (marginal)"
+    onwind: "Onshore\nWind"
-    lines: "transmission\nlines"
+    battery: "Battery\nStorage"
-    ror: "run of river"
+    H2: "Hydrogen\nStorage"
    lines: "Transmission\nlines"
    ror: "Run of\nriver"
--- a/config.tutorial.yaml
+++ b/config.tutorial.yaml
@ -0,0 +1,311 @@
 version: 0.1
 logging_level: INFO
 summary_dir: results
 scenario:
  sectors: [E]
  simpl: ['']
  ll: ['copt']
  clusters: [2,6]
  opts: [Co2L-24H]
 countries: ['DE'] 
 snapshots:
  start: "2013-03-01"
  end: "2014-04-01"
  closed: 'left' # end is not inclusive
 enable:
  powerplantmatching: false
  prepare_links_p_nom: false
 electricity:
  voltages: [220., 300., 380.]
  co2limit: 100.e+6
  extendable_carriers:
    Generator: [OCGT]
    StorageUnit: [battery, H2]
  max_hours:
    battery: 6
    H2: 168
  conventional_carriers: [coal, CCGT] # [nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass]
 atlite:
  nprocesses: 4
  cutouts:
    europe-2013-era5:
      module: era5
      xs: [4., 15.]
      ys: [56., 46.]
      months: [3, 3]
      years: [2013, 2013]
 renewable:
  onwind:
    cutout: europe-2013-era5
    resource:
      method: wind
      turbine: Vestas_V112_3MW
    capacity_per_sqkm: 3 # ScholzPhd Tab 4.3.1: 10MW/km^2
    # correction_factor: 0.93
    corine:
      # Scholz, Y. (2012). Renewable energy based electricity supply at low costs:
      #  development of the REMix model and application for Europe. ( p.42 / p.28)
      grid_codes: [12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23,
                   24, 25, 26, 27, 28, 29, 31, 32]
      distance: 1000
      distance_grid_codes: [1, 2, 3, 4, 5, 6]
    natura: true
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
  offwind-ac:
    cutout: europe-2013-era5
    resource:
      method: wind
      turbine: NREL_ReferenceTurbine_5MW_offshore
    capacity_per_sqkm: 3
    # correction_factor: 0.93
    corine: [44, 255]
    natura: true
    max_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
  offwind-dc:
    cutout: europe-2013-era5
    resource:
      method: wind
      turbine: NREL_ReferenceTurbine_5MW_offshore
    # ScholzPhd Tab 4.3.1: 10MW/km^2
    capacity_per_sqkm: 3
    # correction_factor: 0.93
    corine: [44, 255]
    natura: true
    min_shore_distance: 30000
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
  solar:
    cutout: europe-2013-era5
    resource:
      method: pv
      panel: CSi
      orientation:
        slope: 35.
        azimuth: 180.
    capacity_per_sqkm: 1.7 # ScholzPhd Tab 4.3.1: 170 MW/km^2
    # Determined by comparing uncorrected area-weighted full-load hours to those
    # published in Supplementary Data to
    # Pietzcker, Robert Carl, et al. "Using the sun to decarbonize the power
    # sector: The economic potential of photovoltaics and concentrating solar
    # power." Applied Energy 135 (2014): 704-720.
    correction_factor: 0.854337
    corine: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13,
             14, 15, 16, 17, 18, 19, 20, 26, 31, 32]
    natura: true
    potential: simple # or conservative
    clip_p_max_pu: 1.e-2
 lines:
  types:
    220.: "Al/St 240/40 2-bundle 220.0"
    300.: "Al/St 240/40 3-bundle 300.0"
    380.: "Al/St 240/40 4-bundle 380.0"
  s_max_pu: 0.7
  length_factor: 1.25
  under_construction: 'zero' # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity
 links:
  p_max_pu: 1.0
  include_tyndp: true
  under_construction: 'zero' # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity
 transformers:
  x: 0.1
  s_nom: 2000.
  type: ''
 load:
  scaling_factor: 1.0
 costs:
  year: 2030
  discountrate: 0.07 # From a Lion Hirth paper, also reflects average of Noothout et al 2016
  USD2013_to_EUR2013: 0.7532 # [EUR/USD] ECB: https://www.ecb.europa.eu/stats/exchange/eurofxref/html/eurofxref-graph-usd.en.html
  marginal_cost:
    solar: 0.01
    onwind: 0.015
    offwind: 0.015
    H2: 0.
    battery: 0.
  emission_prices: # only used with the option Ep
    co2: 0.
 solving:
  options:
    formulation: kirchhoff
    load_shedding: false
    noisy_costs: true
    min_iterations: 1
    max_iterations: 1
    clip_p_max_pu: 0.01
    #nhours: 10
  solver:
    name: ipopt
  # solver:
    # name: gurobi
    # threads: 4
    # method: 2 # barrier
    # crossover: 0
    # BarConvTol: 1.e-5
    # FeasibilityTol: 1.e-6
    # AggFill: 0
    # PreDual: 0
    # GURO_PAR_BARDENSETHRESH: 200
  # solver:
  #   name: cplex
  #   threads: 4
  #   lpmethod: 4 # barrier
  #   solutiontype: 2 # non basic solution, ie no crossover
  #   barrier_convergetol: 1.e-5
  #   feasopt_tolerance: 1.e-6
 plotting:
  map:
    figsize: [7, 7]
    boundaries: [-10.2, 29, 35,  72]
    p_nom:
      bus_size_factor: 5.e+4
      linewidth_factor: 3.e+3
  costs_max: 800
  costs_threshold: 1
  energy_max: 15000.
  energy_min: -10000.
  energy_threshold: 50.
  vre_techs: ["onwind", "offwind-ac", "offwind-dc", "solar", "ror"]
  conv_techs: ["OCGT", "CCGT", "Nuclear", "Coal"]
  storage_techs: ["hydro+PHS", "battery", "H2"]
  load_carriers: ["AC load"]
  AC_carriers: ["AC line", "AC transformer"]
  link_carriers: ["DC line", "Converter AC-DC"] 
  tech_colors:
    "onwind" : "#235ebc"
    "onshore wind" : "#235ebc"
    'offwind' : "#6895dd"
    'offwind-ac' : "#6895dd"
    'offshore wind' : "#6895dd"
    'offshore wind ac' : "#6895dd"
    'offwind-dc' : "#74c6f2"
    'offshore wind dc' : "#74c6f2"
    "hydro" : "#08ad97"
    "hydro+PHS" : "#08ad97"
    "PHS" : "#08ad97"
    "hydro reservoir" : "#08ad97"
    'hydroelectricity' : '#08ad97'
    "ror" : "#4adbc8"
    "run of river" : "#4adbc8"
    'solar' : "#f9d002"
    'solar PV' : "#f9d002"
    'solar thermal' : '#ffef60'
    'biomass' : '#0c6013'
    'solid biomass' : '#06540d'
    'biogas' : '#23932d'
    'waste' : '#68896b'
    'geothermal' : '#ba91b1'
    "OCGT" : "#d35050"
    "OCGT marginal" : "#d35050"
    "OCGT-heat" : "#d35050"
    "gas boiler" : "#d35050"
    "gas boilers" : "#d35050"
    "gas boiler marginal" : "#d35050"
    "gas-to-power/heat" : "#d35050"
    "gas" : "#d35050"
    "natural gas" : "#d35050"
    "CCGT" : "#b20101"
    "CCGT marginal" : "#b20101"
    "Nuclear" : "#ff9000"
    "Nuclear marginal" : "#ff9000"
    "nuclear" : "#ff9000"
    "coal" : "#707070"
    "Coal" : "#707070"
    "Coal marginal" : "#707070"
    "lignite" : "#9e5a01"
    "Lignite" : "#9e5a01"
    "Lignite marginal" : "#9e5a01"
    "Oil" : "#262626"
    "oil" : "#262626"
    "H2" : "#ea048a"
    "hydrogen storage" : "#ea048a"
    "Sabatier" : "#a31597"
    "methanation" : "#a31597"
    "helmeth" : "#a31597"
    "DAC" : "#d284ff"
    "co2 stored" : "#e5e5e5"
    "CO2 sequestration" : "#e5e5e5" 
    "battery" : "#b8ea04"
    "battery storage" : "#b8ea04"
    "Li ion" : "#b8ea04"
    "BEV charger" : "#e2ff7c"
    "V2G" : "#7a9618"
    "transport fuel cell" : "#e884be"
    "retrofitting" : "#e0d6a8"
    "building retrofitting" : "#e0d6a8"
    "heat pumps" : "#ff9768" 
    "heat pump" : "#ff9768"
    "air heat pump" : "#ffbea0"
    "ground heat pump" : "#ff7a3d"
    "power-to-heat" : "#a59e7c"
    "power-to-gas" : "#db8585"
    "power-to-liquid" : "#a9acd1"
    "Fischer-Tropsch" : "#a9acd1"
    "resistive heater" : "#aa4925"
    "water tanks" : "#401f75"
    "hot water storage" : "#401f75"
    "hot water charging" : "#351c5e"
    "hot water discharging" : "#683ab2"
    "CHP" : "#d80a56"
    "CHP heat" : "#d80a56"
    "CHP electric" : "#d80a56"
    "district heating" : "#93864b"
    "Ambient" : "#262626"
    "Electric load" : "#f9d002"
    "electricity" : "#f9d002"
    "Heat load" : "#d35050"
    "heat" : "#d35050"
    "Transport load" : "#235ebc"
    "transport" : "#235ebc"
    "lines" : "#70af1d"
    "transmission lines" : "#70af1d"
    "AC-AC" : "#70af1d"
    "AC line" : "#70af1d"
    "links" : "#8a1caf"
    "HVDC links" : "#8a1caf"
    "DC-DC" : "#8a1caf"
    "DC link" : "#8a1caf"
  nice_names:
    OCGT: "Open-Cycle Gas"
    CCGT: "Combined-Cycle Gas"
    offwind-ac: "Offshore Wind (AC)"
    offwind-dc: "Offshore Wind (DC)"
    onwind: "Onshore Wind"
    battery: "Battery Storage"
    H2: "Hydrogen Storage"
    lines: "Transmission lines"
    ror: "Run of river"
  nice_names_n:
    OCGT: "Open-Cycle\nGas"
    CCGT: "Combined-Cycle\nGas"
    offwind-ac: "Offshore\nWind (AC)"
    offwind-dc: "Offshore\nWind (DC)"
    onwind: "Onshore\nWind"
    battery: "Battery\nStorage"
    H2: "Hydrogen\nStorage"
    lines: "Transmission\nlines"
    ror: "Run of\nriver"
--- a/doc/Makefile
+++ b/doc/Makefile
@ -0,0 +1,192 @@
 # Makefile for Sphinx documentation
 #
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
 endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
 	@echo "  json       to make JSON files"
 	@echo "  htmlhelp   to make HTML files and a HTML help project"
 	@echo "  qthelp     to make HTML files and a qthelp project"
 	@echo "  applehelp  to make an Apple Help Book"
 	@echo "  devhelp    to make HTML files and a Devhelp project"
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
 	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 	@echo "  xml        to make Docutils-native XML files"
 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 clean:
 	rm -rf $(BUILDDIR)/*
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 singlehtml:
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
 	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PyPSA.qhcp"
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyPSA.qhc"
 applehelp:
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
 	@echo
 	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
 	@echo "N.B. You won't be able to view it unless you put it in" \
 	      "~/Library/Documentation/Help or install it in your application" \
 	      "bundle."
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
 	@echo "# mkdir -p $$HOME/.local/share/devhelp/PyPSA"
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyPSA"
 	@echo "# devhelp"
 epub:
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 latexpdfja:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 man:
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
 	@echo "Run \`make' in that directory to run these through makeinfo" \
 	      "(use \`make info' here to do that automatically)."
 info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo "Running Texinfo files through makeinfo..."
 	make -C $(BUILDDIR)/texinfo info
 	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 gettext:
 	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 coverage:
 	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
 	@echo "Testing of coverage in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/coverage/python.txt."
 xml:
 	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
 	@echo
 	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
 pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
--- a/doc/_static/theme_overrides.css
+++ b/doc/_static/theme_overrides.css
@ -0,0 +1,19 @@
 /* override table width restrictions */
@media screen and (min-width: 767px) {
    .wy-table-responsive table td {
       /* !important prevents the common CSS stylesheets from overriding
          this as on RTD they are loaded after this stylesheet */
       white-space: normal !important;
       /* background: #eeeeee !important; */
    }
    .wy-table-responsive {
       max-width: 100%;
       overflow: visible !important;
    }
    .wy-nav-content {
        max-width: 910px !important;
    }
 }
--- a/doc/conf.py
+++ b/doc/conf.py
@ -0,0 +1,321 @@
 # -*- coding: utf-8 -*-
 #
 # PyPSA documentation build configuration file, created by
 # sphinx-quickstart on Tue Jan  5 10:04:42 2016.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 import sys
 import os
 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('../scripts'))
 # -- General configuration ------------------------------------------------
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
    #'sphinx.ext.autodoc',
    #'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',
    'sphinx.ext.napoleon',
    'sphinx.ext.graphviz',
    #'sphinx.ext.pngmath',
    #'sphinxcontrib.tikz',
    #'rinoh.frontend.sphinx',
    'sphinx.ext.imgconverter', # for SVG conversion
 ]
 autodoc_default_flags = ['members']
 autosummary_generate = True
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 # The master toctree document.
 master_doc = 'index'
 # General information about the project.
 project = u'PyPSA-Eur'
 copyright = u'2017-2019 Jonas Hoersch (KIT, FIAS), Fabian Hofmann (FIAS), David Schlachtberger (FIAS), Tom Brown (KIT, FIAS); 2019 Fabian Neumann (KIT)'
 author = u'Jonas Hoersch (KIT, FIAS), Fabian Hofmann (FIAS), David Schlachtberger (FIAS), Tom Brown (KIT, FIAS), Fabian Neumann (KIT)'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
 version = u'0.1.0'
 # The full version, including alpha/beta/rc tags.
 release = u'0.1.0'
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 # -- Options for HTML output ----------------------------------------------
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'sphinx_rtd_theme'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
    'display_version': True,
    'sticky_navigation': True,
 }
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #html_logo = None
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 #html_favicon = None
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 html_context = {
    'css_files': [
        '_static/theme_overrides.css',  # override wide tables in RTD theme
        ],
 }
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 #html_extra_path = []
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 # If false, no module index is generated.
 #html_domain_indices = True
 # If false, no index is generated.
 #html_use_index = True
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 # Language to be used for generating the HTML full-text search index.
 # Sphinx supports the following languages:
 #   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
 #   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
 #html_search_language = 'en'
 # A dictionary with options for the search language support, empty by default.
 # Now only 'ja' uses this config value
 #html_search_options = {'type': 'default'}
 # The name of a javascript file (relative to the configuration directory) that
 # implements a search results scorer. If empty, the default will be used.
 #html_search_scorer = 'scorer.js'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'PyPSAEurdoc'
 # -- Options for LaTeX output ---------------------------------------------
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
 # Latex figure (float) alignment
 #'figure_align': 'htbp',
 }
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
  (master_doc, 'PyPSA-Eur.tex', u'PyPSA-Eur Documentation',
   u'author', 'manual'),
 ]
 #Added for rinoh http://www.mos6581.org/rinohtype/quickstart.html
 rinoh_documents = [(master_doc,            # top-level file (index.rst)
                    'PyPSA-Eur',           # output (target.pdf)
                    'PyPSA-Eur Documentation',   # document title
                    'author')]   # document author
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 # If true, show page references after internal links.
 #latex_show_pagerefs = False
 # If true, show URL addresses after external links.
 #latex_show_urls = False
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 # If false, no module index is generated.
 #latex_domain_indices = True
 # -- Options for manual page output ---------------------------------------
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
    (master_doc, 'pypsa-eur', u'PyPSA-Eur Documentation',
     [author], 1)
 ]
 # If true, show URL addresses after external links.
 #man_show_urls = False
 # -- Options for Texinfo output -------------------------------------------
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
  (master_doc, 'PyPSA-Eur', u'PyPSA-Eur Documentation',
   author, 'PyPSA-Eur', 'One line description of project.',
   'Miscellaneous'),
 ]
 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
 # If false, no module index is generated.
 #texinfo_domain_indices = True
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}
--- a/doc/configtables/atlite.csv
+++ b/doc/configtables/atlite.csv
@ -0,0 +1,8 @@
 ,Unit,Values,Description
 nprocesses,--,int,"Number of parallel processes in cutout preparation"
 cutouts,,,
 -- {name},--,"Convention is to name cutouts like ``<region>-<year>-<source>`` (e.g. ``europe-2013-era5``).","Directory to write cutout data to. The user may specify multiple cutouts under configuration ``atlite: cutouts:``. Reference is used in configuration ``renewable: {technology}: cutout:``"
 -- -- module,--,"One of {'era5','sarah'}","Source of the reanalysis weather dataset (e.g. `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_ or `SARAH-2 <https://wui.cmsaf.eu/safira/action/viewDoiDetails?acronym=SARAH_V002>`_)"
 -- -- xs,°,"Float interval within [-180, 180]","Range of longitudes to download weather data for."
 -- -- ys,°,"Float interval within [-90, 90]","Range of latitudes to download weather data for."
 -- -- years,--,"Integer interval within [1979,2018]","Range of years to download weather data for."
--- a/doc/configtables/costs.csv
+++ b/doc/configtables/costs.csv
@ -0,0 +1,8 @@
 ,Unit,Values,Description
 year,--,"YYYY; e.g. '2030'","Year for which to retrieve cost assumptions of ``data/costs.csv``."
 discountrate,--,float,"Default discount rate if not specified for a technology in ``data/costs.csv``."
 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,,,
 -- co2,EUR/t,float,"Exogenous price of carbon-dioxide added to the marginal costs of fossil-fuelled generators according to their carbon intensity."
--- a/doc/configtables/electricity.csv
+++ b/doc/configtables/electricity.csv
@ -0,0 +1,10 @@
 ,Unit,Values,Description
 voltages,kV,"Any subset of {220., 300., 380.}","Voltage levels to consider when"
 co2limit,:math:`t_{CO_2-eq}/a`,float,"Cap on total annual system carbon dioxide emissions"
 extendable_carriers,,,
 -- Generator,--,"Any subset  of {'OCGT','CCGT'}","Places extendable conventional power plants (OCGT and/or CCGT) where gas power plants are located today without capacity limits."
 -- StorageUnit,--,"Any subset of {'battery','H2'}","Places extendable storage units (battery and/or hydrogen) at every node/bus without capacity limits."
 max_hours,,,
 -- battery,h,float,"Maximum state of charge capacity of the battery in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>`_."
 -- H2,h,float,"Maximum state of charge capacity of the hydrogen storage in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>`_."
 conventional_carriers,--,"Any subset of {nuclear, oil, OCGT, CCGT, coal, lignite, geothermal, biomass}","List of conventional power plants to include in the model from ``resources/powerplants.csv``."
--- a/doc/configtables/hydro.csv
+++ b/doc/configtables/hydro.csv
@ -0,0 +1,6 @@
 ,Unit,Values,Description
 cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the relevant weather data ist stored."
 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,MW,float,"To avoid too small values in the inflow time series, values below this threshold are set to zero."
--- a/doc/configtables/licenses.csv
+++ b/doc/configtables/licenses.csv
@ -0,0 +1,14 @@
 "Files","BY","NC","SA","Mark Changes",Detail
 "corine/*","x",,,"x",https://land.copernicus.eu/pan-european/corine-land-cover/clc-2012?tab=metadata
 "eez/*","x","x","x",,http://www.marineregions.org/disclaimer.php
 "natura/*","x",,,,https://www.eea.europa.eu/data-and-maps/data/natura-10#tab-metadata
 "naturalearth/*",,,,,http://www.naturalearthdata.com/about/terms-of-use/
 "NUTS_2013 _60M_SH/*","x","x",,"x",https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units
 "cantons.csv","x",,"x",,https://en.wikipedia.org/wiki/Data_codes_for_Switzerland
 "EIA_hydro_generation _2000_2014.csv","x",,,,https://www.eia.gov/about/copyrights_reuse.php
 "GEBCO_2014_2D.nc","x",,,,https://www.gebco.net/data_and_products/gridded_bathymetry_data/documents/gebco_2014_historic.pdf
 "hydro_capacities.csv","x",,,,
 "je-e-21.03.02.xls","x","x",,,https://www.bfs.admin.ch/bfs/en/home/fso/swiss-federal-statistical-office/terms-of-use.html
 "nama_10r_3 gdp.tsv.gz","x",,,"x",https://ec.europa.eu/eurostat/about/policies/copyright
 "nama_10r_3 popgdp.tsv.gz","x",,,"x",https://ec.europa.eu/eurostat/about/policies/copyright
 "time_series_60min _singleindex_filtered.csv","x",,,,https://data.open-power-system-data.org/time_series/2019-06-05/README.md
--- a/doc/configtables/lines.csv
+++ b/doc/configtables/lines.csv
@ -0,0 +1,5 @@
 ,Unit,Values,Description
 types,--,"Values should specify a `line type in PyPSA <https://pypsa.readthedocs.io/en/latest/components.html#line-types>`_. Keys should specify the corresponding voltage level (e.g. 220., 300. and 380. kV)","Specifies line types to assume for the different voltage levels of the ENTSO-E grid extraction. Should normally handle voltage levels 220, 300, and 380 kV"
 s_max_pu,--,"Value in [0.,1.]","Correction factor for line capacities (``s_nom``) to approximate :math:`N-1` security and reserve capacity for reactive power flows"
 length_factor,--,float,"Correction factor to account for the fact that buses are *not* connected by lines through air-line distance."
 under_construction,--,"One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': keep with full capacity}","Specifies how to handle lines which are currently under construction."
--- a/doc/configtables/links.csv
+++ b/doc/configtables/links.csv
@ -0,0 +1,4 @@
 ,Unit,Values,Description
 p_max_pu,--,"Value in [0.,1.]","Correction factor for link capacities ``p_nom``."
 include_tyndp,bool,"{'true', 'false'}","Specifies whether to add HVDC link projects from the `TYNDP 2018 <https://tyndp.entsoe.eu/tyndp2018/projects/>`_ which are at least in permitting."
 under_construction,--,"One of {'zero': set capacity to zero, 'remove': remove completely, 'keep': keep with full capacity}","Specifies how to handle lines which are currently under construction."
--- a/doc/configtables/load.csv
+++ b/doc/configtables/load.csv
@ -0,0 +1,2 @@
 ,Unit,Values,Description
 scaling_factor,--,float,"Global correction factor for the load time series."
--- a/doc/configtables/offwind-ac.csv
+++ b/doc/configtables/offwind-ac.csv
@ -0,0 +1,12 @@
 ,Unit,Values,Description
 cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored."
 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,:math:`MW/km^2`,float,"Allowable density of wind turbine placement."
 corine,--,"Any *realistic* 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 AC-connected offshore wind turbine 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``."
 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'}","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."
--- a/doc/configtables/offwind-dc.csv
+++ b/doc/configtables/offwind-dc.csv
@ -0,0 +1,12 @@
 ,Unit,Values,Description
 cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored."
 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,:math:`MW/km^2`,float,"Allowable density of wind turbine placement."
 corine,--,"Any *realistic* 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 AC-connected offshore wind turbine 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``."
 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'}","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."
--- a/doc/configtables/onwind.csv
+++ b/doc/configtables/onwind.csv
@ -0,0 +1,13 @@
 ,Unit,Values,Description
 cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-era5') or reference an existing folder in the directory ``cutouts``. Source module must be ERA5.","Specifies the directory where the relevant weather data ist stored."
 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,: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'}","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."
--- a/doc/configtables/opts.csv
+++ b/doc/configtables/opts.csv
@ -0,0 +1,6 @@
 Trigger, Description, Definition, Status
 ``Co2L``, Add an overall carbon-dioxide emissions limit configured in ``electricity: co2limit``, ``prepare_network``: `add_co2limit() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L19>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L154>`_, In active use
 ``nH``; i.e. ``2H``-``6H``, Resample the time-resolution by averaging over every ``n`` snapshots, ``prepare_network``: `average_every_nhours() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L110>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L146>`_), In active use
 ``Ep``, Add cost for a carbon-dioxide price configured in ``costs: emission_prices: co2`` to ``marginal_cost`` of generators, ``prepare_network``: `add_emission_prices() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L24>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L158>`_, Broken
 ``BAU``, Add a per-``carrier`` minimal overall capacity; i.e. at least ``40GW`` of ``OCGT`` in Europe; configured in ``electricity: BAU_mincapacities``, ``solve_network``: `add_opts_constraints() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/solve_network.py#L66>`_, Untested
 ``SAFE``, Add a capacity reserve margin of a certain fraction above the peak demand to which renewable generators and storage do *not* contribute. Ignores network., ``solve_network`` `add_opts_constraints() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/solve_network.py#L73>`_, Untested
--- a/doc/configtables/plotting.csv
+++ b/doc/configtables/plotting.csv
@ -0,0 +1,15 @@
 ,Unit,Values,Description
 map,,,
 -- figsize,--,"[width, height]; e.g. [7,7]","Figure size in inches."
 -- boundaries,°,"[x1,x2,y1,y2]","Boundaries of the map plots in degrees latitude (y) and longitude (x)"
 -- p_nom,,,
 -- -- bus_size_factor,--,float,"Factor by which values determining bus sizes are scaled to fit well in the plot."
 -- -- linewidth_factor,--,float,"Factor by which values determining bus sizes are scaled to fit well in the plot."
 costs_max,bn Euro,float,"Upper y-axis limit in cost bar plots."
 costs_threshold,bn Euro,float,"Threshold below which technologies will not be shown in cost bar plots."
 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."
 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."
--- a/doc/configtables/scenario.csv
+++ b/doc/configtables/scenario.csv
@ -0,0 +1,6 @@
 ,Unit,Values,Description
 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."
--- a/doc/configtables/snapshots.csv
+++ b/doc/configtables/snapshots.csv
@ -0,0 +1,4 @@
 ,Unit,Values,Description
 start,--,"str or datetime-like; e.g. YYYY-MM-DD","Left bound of date range"
 end,--,"str or datetime-like; e.g. YYYY-MM-DD","Right bound of date range"
 closed,--,"One of {None, ‘left’, ‘right’}","Make the time interval closed to the ``left``, ``right``, or both sides ``None``."
--- a/doc/configtables/solar.csv
+++ b/doc/configtables/solar.csv
@ -0,0 +1,14 @@
 ,Unit,Values,Description
 cutout,--,"Should be a folder listed in the configuration ``atlite: cutouts:`` (e.g. 'europe-2013-era5') or reference an existing folder in the directory ``cutouts``. Source module can be ERA5 or SARAH-2.","Specifies the directory where the relevant weather data ist stored that is specified at ``atlite/cutouts`` configuration. Both ``sarah`` and ``era5`` work."
 resource,,,
 -- method,--,"Must be 'pv'","A superordinate technology type."
 -- panel,--,"One of {'Csi', 'CdTe', 'KANENA'} as defined in `atlite <https://github.com/PyPSA/atlite/tree/master/atlite/resources/solarpanel>`_","Specifies the solar panel technology and its characteristic attributes."
 -- orientation,,,
 -- -- slope,°,"Realistically any angle in [0., 90.]","Specifies the tilt angle (or slope) of the solar panel. A slope of zero corresponds to the face of the panel aiming directly overhead. A positive tilt angle steers the panel towards the equator."
 -- -- azimuth,°,"Any angle in [0., 360.]","Specifies the `azimuth <https://en.wikipedia.org/wiki/Azimuth>`_ orientation of the solar panel. South corresponds to 180.°."
 capacity_per_sqkm,:math:`MW/km^2`,float,"Allowable density of solar panel placement."
 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'}","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."
--- a/doc/configtables/solving-options.csv
+++ b/doc/configtables/solving-options.csv
@ -0,0 +1,8 @@
 ,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,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."
 nhours,--,int,"Specifies the :math:`n` first snapshots to take into account. Must be less than the total number of snapshots. Rather recommended only for debugging."
 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."
--- a/doc/configtables/solving-solver.csv
+++ b/doc/configtables/solving-solver.csv
@ -0,0 +1,3 @@
 ,Unit,Values,Description
 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."
--- a/doc/configtables/toplevel.csv
+++ b/doc/configtables/toplevel.csv
@ -0,0 +1,8 @@
 ,Unit,Values,Description
 version,--,0.1,"Version of PyPSA-Eur"
 logging_level,--,"Any of {'INFO', 'WARNING', 'ERROR'}","Restrict console outputs to all infos, warning or errors only"
 summary_dir,--,"e.g. 'results'","Directory into which results are written."
 countries,--,"Subset of {'AL', 'AT', 'BA', 'BE', 'BG', 'CH', 'CZ', 'DE', 'DK', 'EE', 'ES', 'FI', 'FR', 'GB', 'GR', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'ME', 'MK', 'NL', 'NO', 'PL', 'PT', 'RO', 'RS', 'SE', 'SI', 'SK'}","European countries defined by their `Two-letter country codes (ISO 3166-1) <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_ which should be included in the energy system model."
 enable,,,
 -- powerplantmatching,bool,"{true, false}","Switch to retrieve currently existing conventional power plant capacities matched from multiple sources by using `powerplantmatching <https://www.github.com/FRESNA/powerplantmatching>`_."
 -- prepare_links_p_nom,bool,"{true, false}","Switch to retrieve current HVDC projects from `Wikipedia <https://en.wikipedia.org/wiki/List_of_HVDC_projects>`_"
--- a/doc/configtables/transformers.csv
+++ b/doc/configtables/transformers.csv
@ -0,0 +1,4 @@
 ,Unit,Values,Description
 x,p.u.,float,"Series reactance (per unit, using ``s_nom`` as base power of the transformer. Overwritten if ``type`` is specified."
 s_nom,MVA,float,"Limit of apparent power which can pass through branch. Overwritten if ``type`` is specified."
 type,--,"A `transformer type in PyPSA <https://pypsa.readthedocs.io/en/latest/components.html#transformer-types>`_.","Specifies transformer types to assume for the transformers of the ENTSO-E grid extraction."
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@ -0,0 +1,283 @@
 .. _config:
 ##########################################
 Configuration
 ##########################################
 PyPSA-Eur has several configuration options which are documented in this section and are collected in a ``config.yaml`` file located in the root directory. Users should copy the provided default configuration (``config.default.yaml``) and amend their own modifications and assumptions in the user-specific configuration file (``config.yaml``); confer installation instructions at :ref:`defaultconfig`.
 .. _toplevel_cf:
 Top-level configuration
 =======================
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 1-5,13
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/toplevel.csv
 .. _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.default.yaml
   :language: yaml
   :lines: 6-11
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/scenario.csv
 .. _snapshots_cf:
 ``snapshots``
 =============
 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.default.yaml
   :language: yaml
   :lines: 15-18
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/snapshots.csv
 .. _electricity_cf:
 ``electricity``
 ===============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 24-36
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/electricity.csv
 .. warning::
    Carriers in ``conventional_carriers`` must not also be in ``extendable_carriers``.
 .. _atlite_cf:
 ``atlite``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 38-51
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/atlite.csv
 .. _renewable_cf:
 ``renewable``
 =============
 ``onwind``
 ----------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 53-70
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/onwind.csv
 ``offwind-ac``
 --------------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 53,71-83
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/offwind-ac.csv
 ``offwind-dc``
 ---------------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 53,84-97
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/offwind-dc.csv
 ``solar``
 ---------------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 53,98-117
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/solar.csv
 ``hydro``
 ---------------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 53,118-124
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/hydro.csv
 .. _lines_cf:
 ``lines``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 126-133
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/lines.csv
 .. _links_cf:
 ``links``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 135-138
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/links.csv
 .. _transformers_cf:
 ``transformers``
 ================
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 140-143
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/transformers.csv
 .. _load_cf:
 ``load``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 145-146
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/load.csv
 .. _costs_cf:
 ``costs``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 148-160
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/costs.csv
 .. 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_cf:
 ``solving``
 =============
 ``options``
 -----------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 162-170
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/solving-options.csv
 ``solver``
 ----------
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 162,171-187
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/solving-solver.csv
 .. _plotting_cf:
 ``plotting``
 =============
 .. literalinclude:: ../config.default.yaml
   :language: yaml
   :lines: 189-323
 .. csv-table::
   :header-rows: 1
   :widths: 25,7,22,30
   :file: configtables/plotting.csv
--- a/doc/contributing.rst
+++ b/doc/contributing.rst
@ -0,0 +1,10 @@
 #######################
 Contributing
 #######################
 We strongly welcome anyone interested in contributing to this project,
 be it with new ideas, suggestions, by filing bug reports or contributing code.
 You are invited to submit pull requests and file 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>`_.
--- a/doc/costs.rst
+++ b/doc/costs.rst
@ -0,0 +1,45 @@
 ##################
 Cost Assumptions
 ##################
 The database of cost assumptions is stored in ``data/costs.csv``.
 It includes cost assumptions for all included technologies for specific
 years from various sources, namely for
 - discount rate,
 - lifetime,
 - investment (CAPEX),
 - fixed operation and maintenance (FOM),
 - variable operation and maintenance (VOM),
 - fuel costs,
 - efficiency, and
 - carbon-dioxide intensity.
 The given overnight capital costs are annualised to net present costs
 with a discount rate of :math:`r` over the economic lifetime :math:`n` using the annuity factor
 .. math::
    a = \frac{1-(1+r)^{-n}}{r}.
 Based on the parameters above the ``marginal_cost`` and ``capital_cost`` of the system components are calculated.
 Modifying Cost Assumptions
 ==========================
 Some cost assumptions (e.g. marginal cost and capital cost) can be directly overwritten in the ``config.yaml`` (cf. Section  :ref:`costs_cf`  in :ref:`config`).
 To change cost assumptions in more detail, modify 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``.
 Default Cost Assumptions
 ========================
 .. csv-table::
   :header-rows: 1
   :widths: 10,3,5,4,6,8
   :file: ../data/costs.csv
--- a/doc/dconf/user
+++ b/doc/dconf/user
--- a/doc/img/base.png
+++ b/doc/img/base.png
--- a/doc/img/corine.png
+++ b/doc/img/corine.png
--- a/doc/img/countries.png
+++ b/doc/img/countries.png
--- a/doc/img/country_shapes.png
+++ b/doc/img/country_shapes.png
--- a/doc/img/distance_hist.png
+++ b/doc/img/distance_hist.png
--- a/doc/img/eez.png
+++ b/doc/img/eez.png
--- a/doc/img/elec.png
+++ b/doc/img/elec.png
--- a/doc/img/elec_s.png
+++ b/doc/img/elec_s.png
--- a/doc/img/elec_s_X.png
+++ b/doc/img/elec_s_X.png
--- a/doc/img/era5.png
+++ b/doc/img/era5.png
--- a/doc/img/europe_shape.png
+++ b/doc/img/europe_shape.png
--- a/doc/img/gebco_2019_grid_image.jpg
+++ b/doc/img/gebco_2019_grid_image.jpg
--- a/doc/img/hydrocapacities.png
+++ b/doc/img/hydrocapacities.png
--- a/doc/img/hydrogeneration.png
+++ b/doc/img/hydrogeneration.png
--- a/doc/img/inflow-box.png
+++ b/doc/img/inflow-box.png
--- a/doc/img/inflow-ts.png
+++ b/doc/img/inflow-ts.png
--- a/doc/img/load-box.png
+++ b/doc/img/load-box.png
--- a/doc/img/load-ts.png
+++ b/doc/img/load-ts.png
--- a/doc/img/natura.png
+++ b/doc/img/natura.png
--- a/doc/img/nuts3.png
+++ b/doc/img/nuts3.png
--- a/doc/img/nuts3_shapes.png
+++ b/doc/img/nuts3_shapes.png
--- a/doc/img/offshore_shapes.png
+++ b/doc/img/offshore_shapes.png
--- a/doc/img/p_nom_max_hist.png
+++ b/doc/img/p_nom_max_hist.png
--- a/doc/img/potential_heatmap.png
+++ b/doc/img/potential_heatmap.png
--- a/doc/img/powerplantmatching.png
+++ b/doc/img/powerplantmatching.png
--- a/doc/img/profile_ts.png
+++ b/doc/img/profile_ts.png
--- a/doc/img/pypsa-eur-grid.png
+++ b/doc/img/pypsa-eur-grid.png
--- a/doc/img/regions_offshore.png
+++ b/doc/img/regions_offshore.png
--- a/doc/img/regions_offshore_elec_s.png
+++ b/doc/img/regions_offshore_elec_s.png
--- a/doc/img/regions_offshore_elec_s_X.png
+++ b/doc/img/regions_offshore_elec_s_X.png
--- a/doc/img/regions_onshore.png
+++ b/doc/img/regions_onshore.png
--- a/doc/img/regions_onshore_elec_s.png
+++ b/doc/img/regions_onshore_elec_s.png
--- a/doc/img/regions_onshore_elec_s_X.png
+++ b/doc/img/regions_onshore_elec_s_X.png
--- a/doc/img/results.png
+++ b/doc/img/results.png
--- a/doc/img/sarah.png
+++ b/doc/img/sarah.png
--- a/doc/img/scenarios.png
+++ b/doc/img/scenarios.png
--- a/doc/img/tech-colors.png
+++ b/doc/img/tech-colors.png
--- a/doc/img/underwater_hist.png
+++ b/doc/img/underwater_hist.png
--- a/doc/img/workflow.png
+++ b/doc/img/workflow.png
--- a/doc/index.rst
+++ b/doc/index.rst
@ -0,0 +1,161 @@
 PyPSA-Eur: An Open Optimisation Model of the European Transmission System
 =========================================================================
 .. image:: https://img.shields.io/github/tag-date/pypsa/pypsa-eur
    :alt: GitHub tag
 .. image:: https://readthedocs.org/projects/pypsa-eur/badge/?version=latest
    :target: https://pypsa-eur.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 .. image:: https://img.shields.io/github/license/pypsa/pypsa-eur
    :alt: GitHub
 .. image:: https://img.shields.io/github/repo-size/pypsa/pypsa-eur
    :alt: GitHub repo size
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1246852.svg
    :target: https://doi.org/10.5281/zenodo.1246852
 .. image:: https://badges.gitter.im/PyPSA/community.svg
    :target: https://gitter.im/PyPSA/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
    :alt: Chat on Gitter
 PyPSA-Eur is an open model dataset of the European power system at the
 transmission network level that covers the full ENTSO-E area.
 It contains alternating current lines at and above 220 kV voltage level and all high voltage direct current lines, substations, an open database of conventional power plants, time series for electrical demand and variable renewable generator availability, and geographic potentials for the expansion of wind and solar power.
 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.
 This project is maintained by the `Energy System Modelling group <https://www.iai.kit.edu/english/2338.php>`_ at the `Institute for Automation and Applied Informatics <https://www.iai.kit.edu/english/index.php>`_ at the `Karlsruhe Institute of Technology <http://www.kit.edu/english/index.php>`_. The group is funded by the `Helmholtz Association <https://www.helmholtz.de/en/>`_ until 2024. Previous versions were developed by the `Renewable Energy Group <https://fias.uni-frankfurt.de/physics/schramm/renewable-energy-system-and-network-analysis/>`_ at `FIAS <https://fias.uni-frankfurt.de/>`_ to carry out simulations for the `CoNDyNet project <http://condynet.de/>`_, financed by the `German Federal Ministry for Education and Research (BMBF) <https://www.bmbf.de/en/index.html>`_ as part of the `Stromnetze Research Initiative <http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/>`_.
 Documentation
 =============
 **Getting Started**
 * :doc:`introduction`
 * :doc:`installation`
 * :doc:`tutorial`
 .. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Getting Started
   introduction
   installation
   tutorial
 **Configuration**
 * :doc:`wildcards`
 * :doc:`configuration`
 * :doc:`costs`
 .. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Configuration
   wildcards
   configuration
   costs
 **Rules Overview**
 * :doc:`preparation`
 * :doc:`simplification`
 * :doc:`solving`
 * :doc:`plotting`
 .. toctree::
   :hidden:
   :maxdepth: 1
   :caption: Rules Overview
   preparation
   simplification
   solving
   plotting
 **References**
 * :doc:`release_notes`
 * :doc:`limitations`
 * :doc:`contributing`
 .. toctree::
   :hidden:
   :maxdepth: 1
   :caption: References
   release_notes
   limitations
   contributing
 Learning Energy System Modelling
 ================================
 If you are (relatively) new to energy system modelling and optimisation
 and plan to use PyPSA-Eur, the following resources are *one way* to get started
 in addition to reading this documentation.
 - Documentation of `PyPSA <https://pypsa.readthedocs.io>`_, the package for
  simulating and optimising modern power systems which PyPSA-Eur uses under the hood.
 - Course on `Energy System Modelling <https://nworbmot.org/courses/esm-2019/>`_,
  Karlsruhe Institute of Technology (KIT), `Dr. Tom Brown <https://nworbmot.org>`_
 Citing PyPSA-Eur
 ================
 If you use PyPSA-Eur for your research, we would appreciate it if you would cite the following paper:
 - Jonas Hörsch, Fabian Hofmann, David Schlachtberger, and Tom Brown. `PyPSA-Eur: An open optimisation model of the European transmission system <https://arxiv.org/abs/1806.01613>`_. Energy Strategy Reviews, 22:207-215, 2018. `arXiv:1806.01613 <https://arxiv.org/abs/1806.01613>`_, `doi:10.1016/j.esr.2018.08.012 <https://doi.org/10.1016/j.esr.2018.08.012>`_.
 Please use the following BibTeX: ::
    @article{PyPSAEur,
        author = "Jonas Hoersch and Fabian Hofmann and David Schlachtberger and Tom Brown",
        title = "PyPSA-Eur: An open optimisation model of the European transmission system",
        journal = "Energy Strategy Reviews",
        volume = "22",
        pages = "207 - 215",
        year = "2018",
        issn = "2211-467X",
        doi = "10.1016/j.esr.2018.08.012",
        eprint = "1806.01613"
    }
 If you want to cite a specific PyPSA-Eur version, each release of PyPSA-Eur is stored on Zenodo with a release-specific DOI.
 This can be found linked from the overall PyPSA-Eur Zenodo DOI:
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1246852.svg
   :target: https://doi.org/10.5281/zenodo.1246852
 Licence
 =======
 The code in PyPSA-Eur is released as free software under the `GPLv3
 <http://www.gnu.org/licenses/gpl-3.0.en.html>`_, see
 `LICENSE <https://github.com/PyPSA/pypsa-eur/blob/master/LICENSE.txt>`_.
 However, different licenses and terms of use apply to the various input data, which are summarised below.
 More details are included in 
 `the description of the data bundles on zenodo <https://zenodo.org/record/3517935#.XbGeXvzRZGo>`_.
 .. csv-table::
   :header-rows: 1
   :file: configtables/licenses.csv
 * *BY: Attribute Source*
 * *NC: Non-Commercial Use Only*
 * *SA: Share Alike*
--- a/doc/installation.rst
+++ b/doc/installation.rst
@ -0,0 +1,159 @@
 .. _installation:
 ##########################################
 Installation
 ##########################################
 The subsequently described installation steps are demonstrated as shell commands, where the path before the ``%`` sign denotes the
 directory in which the commands following the ``%`` should be entered.
 Clone the Repository
 ====================
 First of all, clone the `PyPSA-Eur repository <https://github.com/PyPSA/pypsa-eur>`_ using the version control system ``git``.
 The path to the directory into which the ``git repository`` is cloned, must **not** have any spaces!
 .. code:: bash
    /some/other/path % cd /some/path/without/spaces
    /some/path/without/spaces % git clone https://github.com/PyPSA/pypsa-eur.git
 .. note::
    If you do not have ``git`` installed, follow installation instructions `here <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
 .. _deps:
 Install Python Dependencies
 ===============================
 PyPSA-Eur relies on a set of other Python packages to function.
 We recommend using the package manager and environment management system ``conda`` to install them.
 Install `miniconda <https://docs.conda.io/en/latest/miniconda.html>`_, which is a mini version of `Anaconda <https://www.anaconda.com/>`_ that includes only ``conda`` and its dependencies or make sure ``conda`` is already installed on your system.
 For instructions for your operating system follow the ``conda`` `installation guide <https://docs.conda.io/projects/conda/en/latest/user-guide/install/>`_.
 The python package requirements are curated in the `environment.yaml <https://github.com/PyPSA/pypsa-eur/blob/master/environment.yaml>`_ file.
 The environment can be installed and activated using
 .. code:: bash
    .../pypsa-eur % conda env create -f environment.yaml
    .../pypsa-eur % conda activate pypsa-eur
 .. note::
    Note that activation is local to the currently open shell!
    After opening a new terminal window, one needs to reissue the second command! 
 .. _data:
 Download Data Dependencies
 ==============================
 Not all data dependencies are shipped with the git repository,
 since git is not suited for handling large changing files.
 Instead we provide separate data bundles which can be obtained
 using the described shell commands or by downloading and
 extracting them manually in the locations outlined below.
 .. note::
    The :ref:`tutorial` uses smaller data bundles than required for the full model.
    To start with the tutorial, substitute with the links below using the following alternatives:
    .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3517921.svg
        :target: https://doi.org/10.5281/zenodo.3517921
    .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3518020.svg
        :target: https://doi.org/10.5281/zenodo.3518020
    - **Data Bundle:** ``https://zenodo.org/record/3517921/files/pypsa-eur-tutorial-data-bundle.tar.xz`` (197 MB)
    - **Cutouts:** ``https://zenodo.org/record/3518020/files/pypsa-eur-tutorial-cutouts.tar.xz`` (19 MB)
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3517935.svg
   :target: https://doi.org/10.5281/zenodo.3517935
 1. **Data Bundle:** `pypsa-eur-data-bundle.tar.xz <https://zenodo.org/record/3517935/files/pypsa-eur-data-bundle.tar.xz>`_ (1.4 GB) contains common GIS datasets like NUTS3 shapes, EEZ shapes, CORINE Landcover, Natura 2000 and also electricity specific summary statistics like historic per country yearly totals of hydro generation, GDP and POP on NUTS3 levels and per-country load time-series. It should be extracted in the ``data`` sub-directory, such that all files of the bundle are stored in the ``data/bundle`` subdirectory)
 .. code:: bash
    .../pypsa-eur/data % curl -OL "https://zenodo.org/record/3517935/files/pypsa-eur-data-bundle.tar.xz"
    .../pypsa-eur/data % tar xJf pypsa-eur-data-bundle.tar.xz
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3517949.svg
   :target: https://doi.org/10.5281/zenodo.3517949
 2. **Cutouts:** `pypsa-eur-cutouts.tar.xz <https://zenodo.org/record/3517949/files/pypsa-eur-cutouts.tar.xz>`_ (3.9 GB) are spatiotemporal subsets of the European weather data from the `ECMWF ERA5 <https://software.ecmwf.int/wiki/display/CKB/ERA5+data+documentation>`_ reanalysis dataset and the `CMSAF SARAH-2 <https://wui.cmsaf.eu/safira/action/viewDoiDetails?acronym=SARAH_V002>`_ solar surface radiation dataset for the year 2013. They have been prepared by and are for use with the `atlite <https://github.com/PyPSA/atlite>`_ tool. You can either generate them yourself using the ``build_cutouts`` rule or extract them directly into the ``pypsa-eur`` directory. To download cutouts yourself you need to `set up the CDS API <https://cds.climate.copernicus.eu/api-how-to>`_. For more details read the `atlite documentation <https://atlite.readthedocs.io>`_. For beginners, extracting the bundle is recommended:
 .. code:: bash
    .../pypsa-eur % curl -OL "https://zenodo.org/record/3517949/files/pypsa-eur-cutouts.tar.xz"
    .../pypsa-eur % tar xJf pypsa-eur-cutouts.tar.xz
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3518215.svg
   :target: https://doi.org/10.5281/zenodo.3518215
 3. **Natura:** Optionally, you can download a rasterized version of the NATURA dataset `natura.tiff <https://zenodo.org/record/3518215/files/natura.tiff>`_ and put it into the ``resources`` sub-directory. If you don't, it will be generated automatically, which is a time-consuming process.
 .. code:: bash
    .../pypsa-eur % curl -L "https://zenodo.org/record/3518215/files/natura.tiff" -o "resources/natura.tiff"
 4. **Remove Archives:** Optionally, if you want to save disk space, you can delete ``data/pypsa-eur-data-bundle.tar.xz`` and ``pypsa-eur-cutouts.tar.xz`` once extracting the bundles is complete. E.g.
 .. code:: bash
    .../pypsa-eur % rm -rf data/pypsa-eur-data-bundle.tar.xz pypsa-eur-cutouts.tar.xz
 Install a Solver
 ================
 PyPSA passes the PyPSA-Eur network model to an external solver for performing a total annual system cost minimization with optimal power flow.
 PyPSA is known to work with the free software
 - `Ipopt <https://coin-or.github.io/Ipopt/INSTALL.html>`_
 - `Cbc <https://projects.coin-or.org/Cbc#DownloadandInstall>`_
 - `GLPK <https://www.gnu.org/software/glpk/>`_ (`WinGLKP <http://winglpk.sourceforge.net/>`_)
 and the non-free, commercial software (for which free academic licenses are available)
 - `Gurobi <https://www.gurobi.com/documentation/8.1/remoteservices/installation.html>`_
 - `CPLEX <https://www.ibm.com/products/ilog-cplex-optimization-studio>`_
 and any other solver that works with the underlying modelling framework `Pyomo <http://www.pyomo.org/>`_. For installation instructions of these solvers for your operating system, follow the links above.
 .. seealso::
    `Getting a solver in the PyPSA documentation <https://pypsa.readthedocs.io/en/latest/installation.html#getting-a-solver-for-linear-optimisation>`_
 .. note::
    Commercial solvers such as Gurobi and CPLEX currently significantly outperform open-source solvers for large-scale problems.
    It might be the case that you can only retrieve solutions by using a commercial solver.
 .. _defaultconfig:
 Set Up the Default Configuration
 ================================
 PyPSA-Eur has several configuration options that must be specified in a ``config.yaml`` file located in the root directory.
 An example configuration ``config.default.yaml`` is maintained in the repository. 
 More details on the configuration options are in :ref:`config`.
 Before first use, create a ``config.yaml`` by copying the example.
 .. code:: bash
    .../pypsa-eur % cp config.default.yaml config.yaml
 Users are advised to regularly check their own ``config.yaml`` against changes in the ``config.default.yaml``
 when pulling a new version from the remote repository.
 .. Using PyPSA-Eur with Docker Images
 .. ==================================
 .. If docker. Optional.
 .. To run on cloud computing.
 .. Gurobi license - floating token server - license must not be tied to a particular machine
 .. Provide ``Dockerfile``.
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@ -0,0 +1,56 @@
 .. _intro:
 ##########################################
 Introduction
 ##########################################
 Workflow
 =========
 The generation of the model is controlled by the workflow management system
 `Snakemake <https://snakemake.bitbucket.io/>`_.
 In a nutshell, the ``Snakefile`` declares for each python script in the ``scripts`` directory a rule which describes which files the scripts consume and produce (their corresponding input and output files).
 The ``snakemake`` tool then runs the scripts in the correct order according to the rules' input/output dependencies.
 Moreover, it is able to track, what parts of the workflow have to be regenerated, when a data file or a script is modified/updated.
 For instance an invocation to
 .. code:: bash
    .../pypsa-eur % snakemake networks/elec_s_128.nc
 follows this dependency graph:
 .. image:: img/workflow.png
 The **blocks** represent the individual rules which are required to create the file ``networks/elec_s_128.nc``. The **arrows** indicate the outputs from preceding rules which a particular rule takes as input data.
 .. note::
    The dependency graph shown above was generated using
    ``snakemake --dag networks/elec_s_128.nc | dot -Tpng > workflow.png``
 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``.
 Scenarios, Configuration and 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 also has several further configuration options collected in the ``config.yaml`` file
 located in the root directory, which that are not part of the scenarios. **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
 ===================
 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.
--- a/doc/limitations.rst
+++ b/doc/limitations.rst
@ -0,0 +1,54 @@
 ##########################################
 Limitations
 ##########################################
 While the benefit of an openly available, functional and partially validated
 model of the European transmission system is high, many approximations have
 been made due to missing data.
 The limitations of the dataset are listed below,
 both as a warning to the user and as an encouragement to assist in
 improving the approximations.
 - **Network topology:**
  The grid data is based on a map of the ENTSO-E area that is known
  to contain small distortions to improve readability. Since the exact impedances
  of the lines are unknown, approximations based on line lengths and standard
  line parameters were made that ignore specific conductoring choices for
  particular lines. There is no openly available data on busbar configurations, switch
  locations, transformers or reactive power compensation assets.
 - **Distribution networks:**
  Using Voronoi cells to aggregate load and generator data to transmission
  network substations ignores the topology of the underlying distribution network,
  meaning that assets may be connected to the wrong substation.
 - **Power Demand:**
  Assumptions
  have been made about the distribution of load in each country proportional to
  population and GDP that may not reflect local circumstances.
  Openly available
  data on load time series may not correspond to the true vertical load and is
  not spatially disaggregated; assuming, as we have done, that the load time series
  shape is the same at each node within each country ignores local differences.
 - **Currently installed renewable capacities:** 
  Information on existing wind, solar and small hydro, geothermal, marine and
  biomass power plants are excluded from the dataset because of a lack of data
  availability in many countries. Approximate distributions of wind and solar
  plants in each country can be generated that are proportional to the capacity
  factor at each location.
 - **Hydro-electric power plants:**
  The database of hydro-electric power plants does not include plant-specific
  energy storage information, so that blanket values based on country storage
  totals have been used. Inflow time series are based on country-wide approximations,
  ignoring local topography and basin drainage; in principle a full
  hydrological model should be used.
 - **International interactions:**
  Border connections and power flows to Russia,
  Belarus, Ukraine, Turkey and Morocco have not been taken into account;
  islands which are not connected to the main European system, such as Malta,
  Crete and Cyprus, are also excluded from the model.
--- a/doc/make.bat
+++ b/doc/make.bat
@ -0,0 +1,263 @@
@ECHO OFF
 REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 if "%1" == "" goto help
 if "%1" == "help" (
 	:help
 	echo.Please use `make ^<target^>` where ^<target^> is one of
 	echo.  html       to make standalone HTML files
 	echo.  dirhtml    to make HTML files named index.html in directories
 	echo.  singlehtml to make a single large HTML file
 	echo.  pickle     to make pickle files
 	echo.  json       to make JSON files
 	echo.  htmlhelp   to make HTML files and a HTML help project
 	echo.  qthelp     to make HTML files and a qthelp project
 	echo.  devhelp    to make HTML files and a Devhelp project
 	echo.  epub       to make an epub
 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 	echo.  text       to make text files
 	echo.  man        to make manual pages
 	echo.  texinfo    to make Texinfo files
 	echo.  gettext    to make PO message catalogs
 	echo.  changes    to make an overview over all changed/added/deprecated items
 	echo.  xml        to make Docutils-native XML files
 	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
 	echo.  linkcheck  to check all external links for integrity
 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	echo.  coverage   to run coverage check of the documentation if enabled
 	goto end
 )
 if "%1" == "clean" (
 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
 	del /q /s %BUILDDIR%\*
 	goto end
 )
 REM Check if sphinx-build is available and fallback to Python version if any
 %SPHINXBUILD% 1>NUL 2>NUL
 if errorlevel 9009 goto sphinx_python
 goto sphinx_ok
 :sphinx_python
 set SPHINXBUILD=python -m sphinx.__init__
 %SPHINXBUILD% 2> nul
 if errorlevel 9009 (
 	echo.
 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
 	echo.installed, then set the SPHINXBUILD environment variable to point
 	echo.to the full path of the 'sphinx-build' executable. Alternatively you
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
 	echo.http://sphinx-doc.org/
 	exit /b 1
 )
 :sphinx_ok
 if "%1" == "html" (
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
 	goto end
 )
 if "%1" == "dirhtml" (
 	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
 	goto end
 )
 if "%1" == "singlehtml" (
 	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
 	goto end
 )
 if "%1" == "pickle" (
 	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the pickle files.
 	goto end
 )
 if "%1" == "json" (
 	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the JSON files.
 	goto end
 )
 if "%1" == "htmlhelp" (
 	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run HTML Help Workshop with the ^
 .hhp project file in %BUILDDIR%/htmlhelp.
 	goto end
 )
 if "%1" == "qthelp" (
 	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
 	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PyPSA.qhcp
 	echo.To view the help file:
 	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyPSA.ghc
 	goto end
 )
 if "%1" == "devhelp" (
 	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished.
 	goto end
 )
 if "%1" == "epub" (
 	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The epub file is in %BUILDDIR%/epub.
 	goto end
 )
 if "%1" == "latex" (
 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
 	goto end
 )
 if "%1" == "latexpdf" (
 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
 	cd %BUILDDIR%/latex
 	make all-pdf
 	cd %~dp0
 	echo.
 	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
 	goto end
 )
 if "%1" == "latexpdfja" (
 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
 	cd %BUILDDIR%/latex
 	make all-pdf-ja
 	cd %~dp0
 	echo.
 	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
 	goto end
 )
 if "%1" == "text" (
 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The text files are in %BUILDDIR%/text.
 	goto end
 )
 if "%1" == "man" (
 	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The manual pages are in %BUILDDIR%/man.
 	goto end
 )
 if "%1" == "texinfo" (
 	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
 	goto end
 )
 if "%1" == "gettext" (
 	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
 	goto end
 )
 if "%1" == "changes" (
 	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.The overview file is in %BUILDDIR%/changes.
 	goto end
 )
 if "%1" == "linkcheck" (
 	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Link check complete; look for any errors in the above output ^
 or in %BUILDDIR%/linkcheck/output.txt.
 	goto end
 )
 if "%1" == "doctest" (
 	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Testing of doctests in the sources finished, look at the ^
 results in %BUILDDIR%/doctest/output.txt.
 	goto end
 )
 if "%1" == "coverage" (
 	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Testing of coverage in the sources finished, look at the ^
 results in %BUILDDIR%/coverage/python.txt.
 	goto end
 )
 if "%1" == "xml" (
 	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The XML files are in %BUILDDIR%/xml.
 	goto end
 )
 if "%1" == "pseudoxml" (
 	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
 	goto end
 )
 :end
--- a/doc/plotting.rst
+++ b/doc/plotting.rst
@ -0,0 +1,171 @@
 ##########################################
 Plotting and Summary
 ##########################################
 .. warning:: The corresponding code is currently under revision and has only minimal documentation.
 .. _flh:
 Rule ``build_country_flh``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.31 0.6 0.85",
            fillcolor=gray,
            label=build_country_flh,
            style=filled];
        1	 [color="0.06 0.6 0.85",
            label=base_network];
        1 -> 0;
        2	 [color="0.42 0.6 0.85",
            label=build_natura_raster];
        2 -> 0;
        3	 [color="0.58 0.6 0.85",
            label=build_shapes];
        3 -> 0;
        4	 [color="0.14 0.6 0.85",
            label=build_cutout];
        4 -> 0;
    }
 |
 .. automodule:: build_country_flh
 .. _plot_potentials:
 Rule ``plot_p_nom_max``
 ==========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.42 0.6 0.85",
            fillcolor=gray,
            label=plot_p_nom_max,
            style=filled];
        1	 [color="0.58 0.6 0.85",
            label=cluster_network];
        1 -> 0;
    }
 |
 .. automodule:: plot_p_nom_max
 .. _summary:
 Rule ``make_summary``
 ========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.47 0.6 0.85",
            fillcolor=gray,
            label=make_summary,
            style=filled];
        1	 [color="0.11 0.6 0.85",
            label=solve_network];
        1 -> 0;
    }
 |
 .. automodule:: make_summary
 .. _summary_plot:
 Rule ``plot_summary``
 ========================
 .. graphviz::
    :align: center
 |
 .. automodule:: plot_summary
 .. _map_plot:
 Rule ``plot_network``
 ========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.00 0.6 0.85",
            fillcolor=gray,
            label=plot_network,
            style=filled];
        1	 [color="0.50 0.6 0.85",
            label=solve_network];
        1 -> 0;
    }
 |
 .. automodule:: plot_network
 .. image:: img/tech-colors.png
    :align: center
--- a/doc/preparation.rst
+++ b/doc/preparation.rst
@ -0,0 +1,38 @@
 ##########################################
 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:
 - :mod:`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.
 - :mod:`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:
 - :mod:`base_network` builds and stores the base network with all buses, HVAC lines and HVDC links, while
 - :mod:`build_bus_regions` determines `Voronoi cells <https://en.wikipedia.org/wiki/Voronoi_diagram>`_ for all substations.
 Then the process continues by calculating conventional power plant capacities, potentials, and per-unit availability time series for variable renewable energy carriers and hydro power plants with the following rules:
 - :mod:`build_powerplants` for today's thermal power plant capacities using `powerplantmatching <https://github.com/FRESNA/powerplantmatching>`_ allocating these to the closest substation for each powerplant,
 - :mod:`build_renewable_profiles` for the hourly capacity factors and installation potentials constrained by land-use in each substation's Voronoi cell for PV, onshore and offshore wind, and
 - :mod:`build_hydro_profile` for the hourly per-unit hydro power availability time series.
 The central rule :mod:`add_electricity` then ties all the different data inputs
 together into a detailed PyPSA network stored in ``networks/elec.nc``.
 .. toctree::
   :caption: Overview
   preparation/build_shapes
   preparation/build_cutout
   preparation/prepare_links_p_nom
   preparation/base_network
   preparation/build_bus_regions
   preparation/build_natura_raster
   preparation/build_powerplants
   preparation/build_renewable_profiles
   preparation/build_hydro_profile
   preparation/add_electricity
--- a/doc/preparation/add_electricity.rst
+++ b/doc/preparation/add_electricity.rst
@ -0,0 +1,52 @@
 .. _electricity:
 Rule ``add_electricity``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        3	 [color="0.25 0.6 0.85",
            label=simplify_network];
        4	 [color="0.50 0.6 0.85",
            fillcolor=gray,
            label=add_electricity,
            style=filled];
        4 -> 3;
        5	 [color="0.36 0.6 0.85",
            label=build_bus_regions];
        5 -> 4;
        6	 [color="0.58 0.6 0.85",
            label=base_network];
        6 -> 4;
        7	 [color="0.31 0.6 0.85",
            label=build_powerplants];
        7 -> 4;
        8	 [color="0.28 0.6 0.85",
            label=build_shapes];
        8 -> 4;
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        9 -> 4;
        10	 [color="0.44 0.6 0.85",
            label=build_hydro_profile];
        10 -> 4;
    }
 |
 .. automodule:: add_electricity
--- a/doc/preparation/base_network.rst
+++ b/doc/preparation/base_network.rst
@ -0,0 +1,49 @@
 .. _base:
 Rule ``base_network``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        4	 [color="0.50 0.6 0.85",
            label=add_electricity];
        5	 [color="0.36 0.6 0.85",
            label=build_bus_regions];
        6	 [color="0.58 0.6 0.85",
            fillcolor=gray,
            label=base_network,
            style=filled];
        6 -> 4;
        6 -> 5;
        7	 [color="0.31 0.6 0.85",
            label=build_powerplants];
        6 -> 7;
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        6 -> 9;
        8	 [color="0.28 0.6 0.85",
            label=build_shapes];
        8 -> 6;
        11	 [color="0.03 0.6 0.85",
            label=prepare_links_p_nom];
        11 -> 6;
    }
 |
 .. automodule:: base_network
--- a/doc/preparation/build_bus_regions.rst
+++ b/doc/preparation/build_bus_regions.rst
@ -0,0 +1,46 @@
 .. _busregions:
 Rule ``build_bus_regions``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        3	 [color="0.25 0.6 0.85",
            label=simplify_network];
        4	 [color="0.50 0.6 0.85",
            label=add_electricity];
        5	 [color="0.36 0.6 0.85",
            fillcolor=gray,
            label=build_bus_regions,
            style=filled];
        5 -> 3;
        5 -> 4;
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        5 -> 9;
        6	 [color="0.58 0.6 0.85",
            label=base_network];
        6 -> 5;
        8	 [color="0.28 0.6 0.85",
            label=build_shapes];
        8 -> 5;
    }
 |
 .. automodule:: build_bus_regions
--- a/doc/preparation/build_cutout.rst
+++ b/doc/preparation/build_cutout.rst
@ -0,0 +1,37 @@
 .. _cutout:
 Rule ``build_cutout``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        10	 [color="0.44 0.6 0.85",
            label=build_hydro_profile];
        13	 [color="0.17 0.6 0.85",
            fillcolor=gray,
            label=build_cutout,
            style=filled];
        13 -> 9;
        13 -> 10;
    }
 |
 .. automodule:: build_cutout
--- a/doc/preparation/build_hydro_profile.rst
+++ b/doc/preparation/build_hydro_profile.rst
@ -0,0 +1,40 @@
 .. _hydroprofiles:
 Rule ``build_hydro_profile``
 ===============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        4	 [color="0.61 0.6 0.85",
            label=add_electricity];
        8	 [color="0.00 0.6 0.85",
            label=build_shapes];
        10	 [color="0.11 0.6 0.85",
            fillcolor=gray,
            label=build_hydro_profile,
            style=filled];
        8 -> 10;
        10 -> 4;
        13	 [color="0.56 0.6 0.85",
            label=build_cutout];
        13 -> 10;
    }
 |
 .. automodule:: build_hydro_profile
--- a/doc/preparation/build_natura_raster.rst
+++ b/doc/preparation/build_natura_raster.rst
@ -0,0 +1,34 @@
 .. _natura:
 Rule ``build_natura_raster``
 ===============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        12	 [color="0.31 0.6 0.85",
            fillcolor=gray,
            label=build_natura_raster,
            style=filled];
        12 -> 9;
    }
 |
 .. automodule:: build_natura_raster
--- a/doc/preparation/build_powerplants.rst
+++ b/doc/preparation/build_powerplants.rst
@ -0,0 +1,37 @@
 .. _powerplants:
 Rule ``build_powerplants``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        4	 [color="0.61 0.6 0.85",
            label=add_electricity];
        6	 [color="0.17 0.6 0.85",
            label=base_network];
        7	 [color="0.58 0.6 0.85",
            fillcolor=gray,
            label=build_powerplants,
            style=filled];
        6 -> 7;
        7 -> 4;
    }
 |
 .. automodule:: build_powerplants
--- a/doc/preparation/build_renewable_profiles.rst
+++ b/doc/preparation/build_renewable_profiles.rst
@ -0,0 +1,49 @@
 .. _renewableprofiles:
 Rule ``build_renewable_profiles``
 ====================================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        4	 [color="0.61 0.6 0.85",
            label=add_electricity];
        5	 [color="0.19 0.6 0.85",
            label=build_bus_regions];
        9	 [color="0.22 0.6 0.85",
            fillcolor=gray,
            label=build_renewable_profiles,
            style=filled];
        5 -> 9;
        9 -> 4;
        6	 [color="0.17 0.6 0.85",
            label=base_network];
        6 -> 9;
        8	 [color="0.00 0.6 0.85",
            label=build_shapes];
        8 -> 9;
        12	 [color="0.31 0.6 0.85",
            label=build_natura_raster];
        12 -> 9;
        13	 [color="0.56 0.6 0.85",
            label=build_cutout];
        13 -> 9;
    }
 |
 .. automodule:: build_renewable_profiles
--- a/doc/preparation/build_shapes.rst
+++ b/doc/preparation/build_shapes.rst
@ -0,0 +1,46 @@
 .. _shapes:
 Rule ``build_shapes``
 =============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        4	 [color="0.61 0.6 0.85",
            label=add_electricity];
        5	 [color="0.19 0.6 0.85",
            label=build_bus_regions];
        6	 [color="0.17 0.6 0.85",
            label=base_network];
        8	 [color="0.00 0.6 0.85",
            fillcolor=gray,
            label=build_shapes,
            style=filled];
        8 -> 4;
        8 -> 5;
        8 -> 6;
        9	 [color="0.22 0.6 0.85",
            label=build_renewable_profiles];
        8 -> 9;
        10	 [color="0.11 0.6 0.85",
            label=build_hydro_profile];
        8 -> 10;
    }
 |
 .. automodule:: build_shapes
--- a/doc/preparation/prepare_links_p_nom.rst
+++ b/doc/preparation/prepare_links_p_nom.rst
@ -0,0 +1,34 @@
 .. _links:
 Rule ``prepare_links_p_nom``
 ===============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        6	 [color="0.17 0.6 0.85",
            label=base_network];
        11	 [color="0.39 0.6 0.85",
            fillcolor=gray,
            label=prepare_links_p_nom,
            style=filled];
        11 -> 6;
    }
 |
 .. automodule:: prepare_links_p_nom
--- a/doc/references.bib
+++ b/doc/references.bib
@ -0,0 +1,115 @@
@article{PyPSAEur,
        author = "Jonas Hoersch and Fabian Hofmann and David Schlachtberger and Tom Brown",
        title = "PyPSA-Eur: An open optimisation model of the European transmission system",
        journal = "Energy Strategy Reviews",
        volume = "22",
        pages = "207 - 215",
        year = "2018",
        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}
 }
--- a/doc/release_notes.rst
+++ b/doc/release_notes.rst
@ -0,0 +1,10 @@
 ##########################################
 Release Notes
 ##########################################
 PyPSA-Eur 0.1.0 (DATE)
 ======================
 This is the first release of PyPSA-Eur. It now features:
 * Documentation on installation, workflows and configuration settings.
--- a/doc/simplification.rst
+++ b/doc/simplification.rst
@ -0,0 +1,21 @@
 ##########################################
 Simplifying Networks
 ##########################################
 The simplification ``snakemake`` rules prepare **approximations** of the full model, for which it is computationally viable to co-optimize generation, storage and transmission capacities.
 - :mod:`simplify_network` transforms the transmission grid to a 380 kV only equivalent network, while
 - :mod:`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
 - 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>`_.
 .. toctree::
   :caption: Overview
   simplification/simplify_network
   simplification/cluster_network
   simplification/prepare_network
--- a/doc/simplification/cluster_network.rst
+++ b/doc/simplification/cluster_network.rst
@ -0,0 +1,38 @@
 .. _cluster:
 Rule ``cluster_network``
 ===========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        1	 [color="0.50 0.6 0.85",
            label=prepare_network];
        2	 [color="0.36 0.6 0.85",
            fillcolor=gray,
            label=cluster_network,
            style=filled];
        2 -> 1;
        3	 [color="0.14 0.6 0.85",
            label=simplify_network];
        3 -> 2;
    }
 |
 .. automodule:: cluster_network
--- a/doc/simplification/prepare_network.rst
+++ b/doc/simplification/prepare_network.rst
@ -0,0 +1,37 @@
 .. _prepare:
 Rule ``prepare_network``
 ===========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.53 0.6 0.85",
            label=solve_network];
        1	 [color="0.50 0.6 0.85",
            fillcolor=gray,
            label=prepare_network,
            style=filled];
        1 -> 0;
        2	 [color="0.36 0.6 0.85",
            label=cluster_network];
        2 -> 1;
    }
 |
 .. automodule:: prepare_network
--- a/doc/simplification/simplify_network.rst
+++ b/doc/simplification/simplify_network.rst
@ -0,0 +1,40 @@
 .. _simplify:
 Rule ``simplify_network``
 ============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        2	 [color="0.36 0.6 0.85",
            label=cluster_network];
        3	 [color="0.14 0.6 0.85",
            fillcolor=gray,
            label=simplify_network,
            style=filled];
        3 -> 2;
        4	 [color="0.61 0.6 0.85",
            label=add_electricity];
        4 -> 3;
        5	 [color="0.19 0.6 0.85",
            label=build_bus_regions];
        5 -> 3;
    }
 |
 .. automodule:: simplify_network
--- a/doc/solving.rst
+++ b/doc/solving.rst
@ -0,0 +1,12 @@
 ##########################################
 Solving Networks
 ##########################################
 After generating and simplifying the networks they can be solved through the rule :mod:`solve_network`  by using the collection rule :mod:`solve_all_elec_networks`. Moreover, networks can be solved for another focus with the derivative rules :mod:`solve_network`  by using the collection rule :mod:`trace_solve_network` to log changes during iterations and :mod:`solve_network`  by using the collection rule :mod:`solve_operations_network` for dispatch-only analyses on an already solved network.
 .. toctree::
   :caption: Overview
   solving/solve_network
   solving/trace_solve_network
   solving/solve_operations_network
--- a/doc/solving/solve_network.rst
+++ b/doc/solving/solve_network.rst
@ -0,0 +1,34 @@
 .. _solve:
 Rule ``solve_network``
 =========================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="3,3"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.64 0.6 0.85",
            fillcolor=gray,
            label=solve_network,
            style=filled];
        1	 [color="0.33 0.6 0.85",
            label=prepare_network];
        1 -> 0;
    }
 |
 .. automodule:: solve_network
--- a/doc/solving/solve_operations_network.rst
+++ b/doc/solving/solve_operations_network.rst
@ -0,0 +1,37 @@
 .. _solve_operations:
 Rule ``solve_operations_network``
 ====================================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.06 0.6 0.85",
            fillcolor=gray,
            label=solve_operations_network,
            style=filled];
        1	 [color="0.00 0.6 0.85",
            label=cluster_network];
        1 -> 0;
        2	 [color="0.19 0.6 0.85",
            label=solve_network];
        2 -> 0;
    }
 |
 .. automodule:: solve_operations_network
--- a/doc/solving/trace_solve_network.rst
+++ b/doc/solving/trace_solve_network.rst
@ -0,0 +1,34 @@
 .. _trace_solve:
 Rule ``trace_solve_network``
 ===============================
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph [bgcolor=white,
            margin=0,
            size="8,5"
        ];
        node [fontname=sans,
            fontsize=10,
            penwidth=2,
            shape=box,
            style=rounded
        ];
        edge [color=grey,
            penwidth=2
        ];
        0	 [color="0.17 0.6 0.85",
            fillcolor=gray,
            label=trace_solve_network,
            style=filled];
        1	 [color="0.58 0.6 0.85",
            label=prepare_network];
        1 -> 0;
    }
 |
 .. automodule:: trace_solve_network
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@ -0,0 +1,288 @@
 .. _tutorial:
 #####################
 Tutorial
 #####################
 Before getting started with **PyPSA-Eur** it makes sense to be familiar
 with its general modelling framework `PyPSA <https://pypsa.readthedocs.io>`_.
 Running the tutorial requires limited computational resources compared to the full model,
 which allows the user to explore most of its functionalities on a local machine.
 It takes approximately five minutes to complete and
 requires 3 GB of memory along with 1 GB free disk space.
 The tutorial will cover examples on how to
 - configure and customise the PyPSA-Eur model and
 - run the ``snakemake`` workflow step by step from network creation to the solved network.
 If not yet completed, follow the :ref:`installation` steps but
 substitute the links for the **data bundle** and the **cutouts** with the following lightweight alternatives:
    .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3517921.svg
      :target: https://doi.org/10.5281/zenodo.3517921
    .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3518020.svg
      :target: https://doi.org/10.5281/zenodo.3518020
    - **Data Bundle:** ``https://zenodo.org/record/3517921/files/pypsa-eur-tutorial-data-bundle.tar.xz`` (197 MB)
    - **Cutouts:** ``https://zenodo.org/record/3518020/files/pypsa-eur-tutorial-cutouts.tar.xz`` (19 MB)
 The configuration of the tutorial is included in the ``config.tutorial.yaml``.
 To run the tutorial, use this as your configuration file ``config.yaml``.
 .. code:: bash
    .../pypsa-eur % cp config.tutorial.yaml config.yaml
 How to customise PyPSA-Eur?
 ===========================
 The model can be adapted to only include selected countries (e.g. Germany) instead of all European countries to limit the spatial scope.
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 13
 Likewise, the example's temporal scope can be restricted (e.g. to a single month).
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 15-18
 It is also possible to allow less or more carbon-dioxide emissions. Here, we limit the emissions of Germany 100 Megatonnes per year.
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 26
 PyPSA-Eur also includes a database of existing conventional powerplants.
 We can select which types of powerplants we like to be included with fixed capacities:
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 36
 To accurately model the temporal and spatial availability of renewables such as wind and solar energy, we rely on historical weather data.
 It is advisable to adapt the required range of coordinates to the selection of countries.
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 38-47
 We can also decide which weather data source should be used to calculate potentials and capacity factor time-series for each carrier.
 For example, we may want to use the ERA-5 dataset for solar and not the default SARAH-2 dataset.
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 48,91-92
 Finally, it is possible to pick a solver. For instance, this tutorial uses the open-source solvers CBC and Ipopt and does not rely
 on the commercial solvers Gurobi or CPLEX (for which free academic licenses are available).
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 156-157
 .. note::
    To run the tutorial, either install CBC and Ipopt (see instructions for :ref:`installation`).
    Alternatively, choose another installed solver in the ``config.yaml`` at ``solving: solver:``.
 Note, that we only note major changes to the provided default configuration that is comprehensibly documented in :ref:`config`.
 There are many more configuration options beyond what is adapted for the tutorial!
 How to use the ``snakemake`` rules?
 ===================================
 Open a terminal, go into the PyPSA-Eur directory, and activate the ``pypsa-eur`` environment with
 .. code:: bash
    .../pypsa-eur % conda activate pypsa-eur
 Let's say based on the modifications above we would like to solve a very simplified model
 clustered down to 6 buses and every 24 hours aggregated to one snapshot. The command
 .. code:: bash
    .../pypsa-eur % snakemake results/networks/elec_s_6_lcopt_Co2L-24H.
 orders ``snakemake`` to run the script ``solve_network`` that produces the solved network and stores it in ``.../pypsa-eur/results/networks`` with the name ``elec_s_6_lcopt_Co2L-24H.nc``:
 .. code::
    rule solve_network:
        input: "networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc"
        output: "results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc"
        [...]
        script: "scripts/solve_network.py"
 This triggers a workflow of multiple preceding jobs that depend on each rule's inputs and outputs:
 .. graphviz::
    :align: center
    digraph snakemake_dag {
        graph[bgcolor=white, margin=0];
        node[shape=box, style=rounded, fontname=sans, fontsize=10, penwidth=2];
        edge[penwidth=2, color=grey];
        0[label = "solve_network", color = "0.10 0.6 0.85", style="rounded"];
        1[label = "prepare_network\nll: copt\nopts: Co2L-24H", color = "0.13 0.6 0.85", style="rounded"];
        2[label = "cluster_network\nclusters: 6", color = "0.51 0.6 0.85", style="rounded"];
        3[label = "simplify_network\nnetwork: elec\nsimpl: ", color = "0.00 0.6 0.85", style="rounded"];
        4[label = "add_electricity", color = "0.60 0.6 0.85", style="rounded"];
        5[label = "build_bus_regions", color = "0.19 0.6 0.85", style="rounded"];
        6[label = "base_network", color = "0.38 0.6 0.85", style="rounded"];
        7[label = "build_shapes", color = "0.03 0.6 0.85", style="rounded"];
        8[label = "build_renewable_profiles\ntechnology: onwind", color = "0.48 0.6 0.85", style="rounded"];
        9[label = "build_renewable_profiles\ntechnology: offwind-ac", color = "0.48 0.6 0.85", style="rounded"];
        10[label = "build_renewable_profiles\ntechnology: offwind-dc", color = "0.48 0.6 0.85", style="rounded"];
        11[label = "build_renewable_profiles\ntechnology: solar", color = "0.48 0.6 0.85", style="rounded"];
        12[label = "build_cutout\ncutout: europe-2013-era5", color = "0.35 0.6 0.85", style="rounded,dashed"];
        1 -> 0
        2 -> 1
        3 -> 2
        4 -> 3
        5 -> 3
        6 -> 4
        5 -> 4
        7 -> 4
        8 -> 4
        9 -> 4
        10 -> 4
        11 -> 4
        7 -> 5
        6 -> 5
        7 -> 6
        6 -> 8
        7 -> 8
        5 -> 8
        12 -> 8
        6 -> 9
        7 -> 9
        5 -> 9
        12 -> 9
        6 -> 10
        7 -> 10
        5 -> 10
        12 -> 10
        6 -> 11
        7 -> 11
        5 -> 11
        12 -> 11
    } 
 |
 In the terminal, this will show up as a list of jobs to be run:
 .. code:: bash
    Building DAG of jobs...
    Using shell: /bin/bash
    Provided cores: 1
    Rules claiming more threads will be scaled down.
    Unlimited resources: mem
    Job counts:
        count	jobs
        1	add_electricity
        1	base_network
        1	build_bus_regions
        4	build_renewable_profiles
        1	build_shapes
        1	cluster_network
        1	prepare_network
        1	simplify_network
        1	solve_network
        12
 ``snakemake`` then runs these jobs in the correct order.
 A job (here ``simplify_network``) will display its attributes and normally some logs in the terminal:
 .. code:: bash
    [<DATETIME>]
    rule simplify_network:
        input: networks/elec.nc, data/costs.csv, resources/regions_onshore.geojson, resources/regions_offshore.geojson
        output: networks/elec_s.nc, resources/regions_onshore_elec_s.geojson, resources/regions_offshore_elec_s.geojson, resources/clustermaps_elec_s.h5
        jobid: 3
        benchmark: benchmarks/simplify_network/elec_s
        wildcards: network=elec, simpl=
        resources: mem=4000
    INFO:pypsa.io:Imported network elec.nc has buses, carriers, generators, lines, links, loads, storage_units, transformers
    INFO:__main__:Mapping all network lines onto a single 380kV layer
    INFO:__main__:Simplifying connected link components
    INFO:__main__:Removing stubs
    INFO:__main__:Displacing offwind-ac generator(s) and adding connection costs to capital_costs: 20128 Eur/MW/a for `5718 offwind-ac` 
    INFO:__main__:Displacing offwind-dc generator(s) and adding connection costs to capital_costs: 14994 Eur/MW/a for `5718 offwind-dc`, 26939 Eur/MW/a for `5724 offwind-dc`, 29621 Eur/MW/a for `5725 offwind-dc` 
    INFO:pypsa.io:Exported network elec_s.nc has lines, carriers, links, storage_units, loads, buses, generators
    [<DATETIME>]
    Finished job 3.
    9 of 12 steps (75%) done
 Once the whole worktree is finished, it should show state so in the terminal:
 .. code:: bash
    Finished job 0.
    12 of 12 steps (100%) done
    Complete log: /home/XXXX/pypsa-eur/.snakemake/log/20XX-XX-XXTXX.snakemake.log
    snakemake results/networks/elec_s_6_lcopt_Co2L-24H.nc  519,84s user 34,26s system 242% cpu 3:48,83 total
 You will notice that many intermediate stages are saved, namely the outputs of each individual ``snakemake`` rule.
 You can produce any output file occuring in the ``Snakefile`` by running
 .. code:: bash
    .../pypsa-eur % snakemake <output file>
 For example, you can explore the evolution of the PyPSA networks by running
 #. ``.../pypsa-eur % snakemake networks/base.nc``
 #. ``.../pypsa-eur % snakemake networks/elec.nc``
 #. ``.../pypsa-eur % snakemake networks/elec_s.nc``
 #. ``.../pypsa-eur % snakemake networks/elec_s_6.nc``
 #. ``.../pypsa-eur % snakemake networks/elec_s_6_lcopt_Co2L-24H.nc``
 There's a special rule: If you simply run
 .. code:: bash
    .../pypsa-eur % snakemake
 the wildcards given in ``scenario`` in the configuration file ``config.yaml`` are used:
 .. literalinclude:: ../config.tutorial.yaml
   :language: yaml
   :lines: 6-11
 In this example we would not only solve a 6-node model of Germany but also a 2-node model.
 How to analyse solved networks?
 ===============================
 The solved networks can be analysed just like any other PyPSA network (e.g. in Jupyter Notebooks).
 .. code:: python
    import pypsa
    network = pypsa.Network("results/networks/elec_s_6_lcopt_Co2L-24H.nc")
    ...
 For inspiration, read the `examples section in the PyPSA documentation <https://pypsa.readthedocs.io/en/latest/examples.html>`_.
 .. note::
    There are rules for summaries and plotting available in the repository of PyPSA-Eur.
    They are currently under revision and therefore not yet documented. 
--- a/Show More
+++ b/Show More
		`@ -0,0 +1,2 @@`
							`,Unit,Values,Description`
							`scaling_factor,--,float,"Global correction factor for the load time series."`