general update of .rst files

config/config.default.yaml

@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: CC0-1.0
 
+# docs in 
 version: 0.8.0
 tutorial: false
 
@@ -9,63 +10,51 @@ logging:
   level: INFO
   format: '%(levelname)s:%(name)s:%(message)s'
 
+# docs in 
 run: 
-  name: "" # use this to keep track of runs with different settings
+  name: ""
-  disable_progressbar: false # set to true to disable the progressbar
+  disable_progressbar: false
-  shared_resources: false # set to true to share the default resources across runs
+  shared_resources: false
-  shared_cutouts: true # set to true to share the default cutout(s) across runs
+  shared_cutouts: true
 
-foresight: overnight # options are overnight, myopic, perfect (perfect is not yet implemented)
+# docs in 
-# if you use myopic or perfect foresight, set the investment years in "planning_horizons" below
+foresight: overnight
 
+# docs in 
+# Wildcard docs in 
 scenario: 
   simpl:
   - ''
-  ll:  # allowed transmission line volume expansion, can be any float >= 1.0 with a prefix v|c (today) or "copt"
+  ll:  
-  - v1.0
   - v1.5
-  clusters:  # number of nodes in Europe, any integer between 37 (1 node per country-zone) and several hundred
+  clusters:
   - 37
   - 128
   - 256
   - 512
   - 1024
-  opts: # only relevant for PyPSA-Eur
+  opts: 
   - ''
-  sector_opts: # this is where the main scenario settings are
+  sector_opts:
   - Co2L0-3H-T-H-B-I-A-solar+p3-dist1
-  # to really understand the options here, look in scripts/prepare_sector_network.py
+  planning_horizons:
-  # Co2Lx specifies the CO2 target in x% of the 1990 values; default will give default (5%);
-  # Co2L0p25 will give 25% CO2 emissions; Co2Lm0p05 will give 5% negative emissions
-  # xH is the temporal resolution; 3H is 3-hourly, i.e. one snapshot every 3 hours
-  # single letters are sectors: T for land transport, H for building heating,
-  # B for biomass supply, I for industry, shipping and aviation,
-  # A for agriculture, forestry and fishing
-  # solar+c0.5 reduces the capital cost of solar to 50\% of reference value
-  # solar+p3 multiplies the available installable potential by factor 3
-  # seq400 sets the potential of CO2 sequestration to 400 Mt CO2 per year
-  # dist{n} includes distribution grids with investment cost of n times cost in data/costs.csv
-  # for myopic/perfect foresight cb states the carbon budget in GtCO2 (cumulative
-  # emissions throughout the transition path in the timeframe determined by the
-  # planning_horizons), be:beta decay; ex:exponential decay
-  # cb40ex0 distributes a carbon budget of 40 GtCO2 following an exponential
-  # decay with initial growth rate 0
-  planning_horizons: # investment years for myopic and perfect; for overnight, year of cost assumptions can be different and is defined under 'costs'
-  - 2050
-  # for example, set to
   # - 2020
   # - 2030
   # - 2040
-  # - 2050
+  - 2050
-  # for myopic foresight
 
-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']
+# docs in 
+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']
 
+# docs in 
 snapshots:
   start: "2013-01-01"
   end: "2014-01-01"
-  inclusive: 'left' # include start, not end
+  inclusive: 'left'
 
+# docs in 
 enable:
   prepare_links_p_nom: false
   retrieve_databundle: true
@@ -77,9 +66,7 @@ enable:
   retrieve_natura_raster: true
   custom_busmap: false
 
-# CO2 budget as a fraction of 1990 emissions
+# docs in 
-# this is over-ridden if CO2Lx is set in sector_opts
-# this is also over-ridden if cb is set in sector_opts
 co2_budget:
   2020: 0.701
   2025: 0.524
@@ -89,18 +76,19 @@ co2_budget:
   2045: 0.032
   2050: 0.000
 
+# docs in 
 electricity:
   voltages: [220., 300., 380.]
-  gaslimit: false # global gas usage limit of X MWh_th
+  gaslimit: false
-  co2limit: 7.75e+7 # 0.05 * 3.1e9*0.5
+  co2limit: 7.75e+7
   co2base: 1.487e+9
   agg_p_nom_limits: data/agg_p_nom_minmax.csv
 
-  operational_reserve: # like https://genxproject.github.io/GenX/dev/core/#Reserves
+  operational_reserve:
     activate: false
-    epsilon_load: 0.02 # share of total load
+    epsilon_load: 0.02
-    epsilon_vres: 0.02 # share of total renewable supply
+    epsilon_vres: 0.02
-    contingency: 4000 # fixed capacity in MW
+    contingency: 4000
 
   max_hours:
     battery: 6
@@ -112,7 +100,6 @@ electricity:
     Store: [battery, H2]
     Link: [] # H2 pipeline
 
-  # use pandas query strings here, e.g. Country not in ['Germany']
   powerplants_filter: (DateOut >= 2022 or DateOut != DateOut)
   # use pandas query strings here, e.g. Country in ['Germany']
   custom_powerplants: false
@@ -136,7 +123,7 @@ electricity:
       Onshore: [onwind]
       PV: [solar]
 
-
+# docs in
 atlite:
   default_cutout: europe-2013-era5
   nprocesses: 4
@@ -163,20 +150,16 @@ atlite:
       sarah_dir:
       features: [influx, temperature]
 
-
+# docs in
 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 and assuming 30% fraction of the already restricted
+    capacity_per_sqkm: 3 
-    # area is available for installation of wind generators due to competing land use and likely public
-    # acceptance issues.
     # 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]
@@ -189,13 +172,8 @@ renewable:
     resource:
       method: wind
       turbine: NREL_ReferenceTurbine_5MW_offshore
-    capacity_per_sqkm: 2 # ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 20% fraction of the already restricted
+    capacity_per_sqkm: 2 
-    # area is available for installation of wind generators due to competing land use and likely public
-    # acceptance issues.
     correction_factor: 0.8855
-    # proxy for wake losses
-    # from 10.1016/j.energy.2018.08.153
-    # until done more rigorously in #153
     corine: [44, 255]
     natura: true
     ship_threshold: 400
@@ -209,13 +187,8 @@ renewable:
     resource:
       method: wind
       turbine: NREL_ReferenceTurbine_5MW_offshore
-    capacity_per_sqkm: 2 # ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 20% fraction of the already restricted
+    capacity_per_sqkm: 2
-    # area is available for installation of wind generators due to competing land use and likely public
-    # acceptance issues.
     correction_factor: 0.8855
-    # proxy for wake losses
-    # from 10.1016/j.energy.2018.08.153
-    # until done more rigorously in #153
     corine: [44, 255]
     natura: true
     ship_threshold: 400
@@ -232,14 +205,7 @@ renewable:
       orientation:
         slope: 35.
         azimuth: 180.
-    capacity_per_sqkm: 1.7 # ScholzPhd Tab 4.3.1: 170 MW/km^2 and assuming 1% of the area can be used for solar PV panels
+    capacity_per_sqkm: 1.7
-    # Correction factor 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.
-    # This correction factor of 0.854337 may be in order if using reanalysis data.
-    # for discussion refer to https://github.com/PyPSA/pypsa-eur/pull/304
     # 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
@@ -253,10 +219,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
 
+# docs in
 conventional:
   nuclear:
     p_max_pu: "data/nuclear_p_max_pu.csv" # float of file name
 
+# docs in
 lines:
   types:
     220.: "Al/St 240/40 2-bundle 220.0"
@@ -267,24 +235,28 @@ lines:
   length_factor: 1.25
   under_construction: 'zero' # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity
 
+# docs in
 links:
   p_max_pu: 1.0
   p_nom_max: .inf
   include_tyndp: true
   under_construction: 'zero' # 'zero': set capacity to zero, 'remove': remove, 'keep': with full capacity
 
+# docs in
 transformers:
   x: 0.1
   s_nom: 2000.
   type: ''
 
+# docs in
 load:
-  power_statistics: true # only for files from <2019; set false in order to get ENTSOE transparency data
+  power_statistics: true
-  interpolate_limit: 3 # data gaps up until this size are interpolated linearly
+  interpolate_limit: 3
-  time_shift_for_large_gaps: 1w # data gaps up until this size are copied by copying from
+  time_shift_for_large_gaps: 1w
   manual_adjustments: true # false
   scaling_factor: 1.0
 
+# TODO: PyPSA-Eur merge issue in prepare_sector_network.py
 # regulate what components with which carriers are kept from PyPSA-Eur;
 # some technologies are removed because they are implemented differently
 # (e.g. battery or H2 storage) or have different year-dependent costs
@@ -305,12 +277,14 @@ pypsa_eur:
   - hydro
   Store: []
 
+# docs in
 energy:
   energy_totals_year: 2011
   base_emissions_year: 1990
   eurostat_report_year: 2016
   emissions: CO2 # "CO2" or "All greenhouse gases - (CO2 equivalent)"
 
+# docs in
 biomass:
   year: 2030
   scenario: ENS_Med
@@ -336,13 +310,14 @@ biomass:
     - Manure solid, liquid
     - Sludge
 
-
+# docs in
 solar_thermal:
   clearsky_model: simple  # should be "simple" or "enhanced"?
   orientation:
     slope: 45.
     azimuth: 180.
 
+# docs under construction in
 # only relevant for foresight = myopic or perfect
 existing_capacities:
   grouping_years_power: [1980, 1985, 1990, 1995, 2000, 2005, 2010, 2015, 2020, 2025, 2030]
@@ -354,7 +329,7 @@ existing_capacities:
   - oil
   - uranium
 
-
+# docs under construction in
 sector:
   district_heating:
     potential: 0.6  # maximum fraction of urban demand which can be supplied by district heating
@@ -515,6 +490,7 @@ sector:
   biomass_to_liquid: false
   biosng: false
 
+# docs under construction in
 industry:
   St_primary_fraction:  # fraction of steel produced via primary route versus secondary route (scrap+EAF); today fraction is 0.6
     2020: 0.6
@@ -568,6 +544,7 @@ industry:
   # DECHEMA (2017): https://dechema.de/dechema_media/Downloads/Positionspapiere/Technology_study_Low_carbon_energy_and_feedstock_for_the_European_chemical_industry-p-20002750.pdf
   # Material Economics (2019): https://materialeconomics.com/latest-updates/industrial-transformation-2050
 
+# docs in
 costs:
   year: 2030
   version: v0.5.0
@@ -594,14 +571,15 @@ costs:
     fuel cell: 0.
     battery: 0.
     battery inverter: 0.
-  emission_prices: # in currency per tonne emission, only used with the option Ep
+  emission_prices:
     co2: 0.
 
+# docs in
 clustering:
   simplify_network:
-    to_substations: false # network is simplified to nodes with positive or negative power injection (i.e. substations or offwind connections)
+    to_substations: false
     algorithm: kmeans # choose from: [hac, kmeans]
-    feature: solar+onwind-time # only for hac. choose from: [solar+onwind-time, solar+onwind-cap, solar-time, solar-cap, solar+offwind-cap] etc.
+    feature: solar+onwind-time
     exclude_carriers: []
     remove_stubs: true
     remove_stubs_across_borders: true
@@ -611,7 +589,7 @@ clustering:
     exclude_carriers: []
   aggregation_strategies:
     generators:
-      p_nom_max: sum # use "min" for more conservative assumptions
+      p_nom_max: sum
       p_nom_min: sum
       p_min_pu: mean
       marginal_cost: mean
@@ -620,6 +598,7 @@ clustering:
       ramp_limit_down: max
       efficiency: mean
 
+# docs in
 solving:
   #tmpdir: "path/to/tmp"
   options:
@@ -693,7 +672,7 @@ solving:
 
   mem: 30000 #memory in MB; 20 GB enough for 50+B+I+H2; 100 GB for 181+B+I+H2
 
-
+# docs in
 plotting:
   map:
     boundaries: [-11, 30, 34, 71]

doc/configtables/co2_budget.csv

@@ -0,0 +1,2 @@
+,Unit,Values,Description
+co2_budget,--,Dictionary with planning horizons as keys.,CO2 budget as a fraction of 1990 emissions. Overwritten if ``CO2Lx`` or ``cb`` are set in ``{sector_opts}`` wildcard"doc/configtables/othertoplevel.csv

doc/configtables/countries.csv

@@ -0,0 +1,2 @@
+ ,Unit,Values,Description
+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."

doc/configtables/foresight.csv

@@ -0,0 +1,2 @@
+,Unit,Values,Description
+foresight,string,"{overnight, myopic, perfect}","See :ref:`Foresight Options` for detail explanations."

doc/configtables/toplevel.csv

@@ -4,7 +4,3 @@ tutorial,bool,"{true, false}","Switch to retrieve the tutorial data set instead
 logging,,,
 -- level,--,"Any of {'INFO', 'WARNING', 'ERROR'}","Restrict console outputs to all infos, warning or errors only"
 -- format,--,"","Custom format for log messages. See `LogRecord <https://docs.python.org/3/library/logging.html#logging.LogRecord>`_ attributes."
-foresight,string,"{overnight, myopic, perfect}","Defaults to overnight scenarios."
-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."
-focus_weights,--,"Keys should be two-digit country codes (e.g. DE) and values should range between 0 and 1","Ratio of total clusters for particular countries. the remaining weight is distributed according to mean load. An example: ``focus_weights: 'DE': 0.6 'FR': 0.2``."
-co2_budget,--,"Dictionary with planning horizons as keys.","CO2 budget as a fraction of 1990 emissions. Overwritten if ``CO2Lx`` or ``cb`` are set in ``{sector_opts}`` wildcard"

doc/configuration.rst

@@ -18,7 +18,8 @@ Top-level configuration
 
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
-   :lines: 5-11,18-19,62,80-90
+   :start-at: version:
+   :end-before: # docs
 
 
 .. csv-table::
@@ -26,7 +27,7 @@ Top-level configuration
    :widths: 25,7,22,30
    :file: configtables/toplevel.csv
 
-.. _scenario:
+.. _run_cf:
 
 ``run``
 =======
@@ -40,13 +41,34 @@ The ``run`` section is used for running and storing scenarios with different con
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: run:
-   :end-before: foresight:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
    :widths: 25,7,22,30
    :file: configtables/run.csv
 
+.. _foresight_cf:
+
+``foresight``
+=============
+
+.. literalinclude:: ../config/config.default.yaml
+   :language: yaml
+   :start-at: foresight:
+   :end-at: foresight:
+
+.. csv-table::
+   :header-rows: 1
+   :widths: 25,7,22,30
+   :file: configtables/foresight.csv
+
+.. note::
+    if you use myopic or perfect foresight, The investment years in 
+    :ref:`planning_horizons` in scenario has to be set.
+
+.. _scenario:
+
 ``scenario``
 ============
 
@@ -79,13 +101,28 @@ An exemplary dependency graph (starting from the simplification rules) then look
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: scenario:
-   :end-before: countries:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
    :widths: 25,7,22,30
    :file: configtables/scenario.csv
 
+.. _countries:
+
+``countries``
+=============
+
+.. literalinclude:: ../config/config.default.yaml
+   :language: yaml
+   :start-at: countries:
+   :end-before: # docs
+
+.. csv-table::
+   :header-rows: 1
+   :widths: 25,7,22,30
+   :file: configtables/countries.csv
+
 .. _snapshots_cf:
 
 ``snapshots``
@@ -96,7 +133,7 @@ Specifies the temporal range to build an energy system model for as arguments to
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: snapshots:
-   :end-before: enable:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -113,13 +150,32 @@ Switches for some rules and optional features.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: enable:
-   :end-before: co2_budget:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
    :widths: 25,7,22,30
    :file: configtables/enable.csv
 
+.. _CO2_budget_cf:
+
+``co2 budget``
+==============
+
+.. literalinclude:: ../config/config.default.yaml
+   :language: yaml
+   :start-at: co2_budget:
+   :end-before: # docs
+
+.. csv-table::
+   :header-rows: 1
+   :widths: 25,7,22,30
+   :file: configtables/co2_budget.csv
+
+.. note::
+    this parameter is over-ridden if ``CO2Lx`` or ``cb`` is set in 
+    sector_opts.
+
 .. _electricity_cf:
 
 ``electricity``
@@ -128,7 +184,7 @@ Switches for some rules and optional features.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: electricity:
-   :end-before: atlite:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -145,7 +201,7 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: atlite:
-   :end-before: renewable:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -170,6 +226,15 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia
    :widths: 25,7,22,30
    :file: configtables/onwind.csv
 
+.. note::
+   Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 30% fraction of the already restricted
+   area is available for installation of wind generators due to competing land use and likely public
+   acceptance issues.
+
+.. note::
+   The default choice for corine ``grid_codes`` was based on Scholz, Y. (2012). Renewable energy based electricity supply at low costs
+   development of the REMix model and application for Europe. ( p.42 / p.28)
+
 ``offwind-ac``
 --------------
 
@@ -183,6 +248,16 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia
    :widths: 25,7,22,30
    :file: configtables/offwind-ac.csv
 
+.. note::
+   Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 10MW/km^2 and assuming 20% fraction of the already restricted
+   area is available for installation of wind generators due to competing land use and likely public
+   acceptance issues.
+
+.. note::
+   Notes on ``correction_factor``. Correction due to proxy for wake losses
+   from 10.1016/j.energy.2018.08.153
+   until done more rigorously in #153
+
 ``offwind-dc``
 ---------------
 
@@ -196,6 +271,10 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia
    :widths: 25,7,22,30
    :file: configtables/offwind-dc.csv
 
+.. note::
+   both ``offwind-ac`` and ``offwind-dc`` have the same assumption on 
+   ``capacity_per_sqkm`` and ``correction_factor``.
+
 ``solar``
 ---------------
 
@@ -209,13 +288,22 @@ Define and specify the ``atlite.Cutout`` used for calculating renewable potentia
    :widths: 25,7,22,30
    :file: configtables/solar.csv
 
+.. note::
+   Notes on ``capacity_per_sqkm``. ScholzPhd Tab 4.3.1: 170 MW/km^2 and assuming 1% of the area can be used for solar PV panels.
+   Correction factor 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.
+   This correction factor of 0.854337 may be in order if using reanalysis data.
+   for discussion refer to this <issue https://github.com/PyPSA/pypsa-eur/issues/285>
+
 ``hydro``
 ---------------
 
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at:   hydro:
-   :end-before: conventional:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -237,7 +325,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at:   conventional:
-   :end-before: lines:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -250,7 +338,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: lines:
-   :end-before: links:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -265,7 +353,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: links:
-   :end-before: transformers:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -280,7 +368,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: transformers:
-   :end-before: load:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
@@ -295,45 +383,13 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-after:   type:
-   :end-at:   scaling_factor:
+   :end-before: # docs
 
 .. csv-table::
    :header-rows: 1
    :widths: 25,7,22,30
    :file: configtables/load.csv
 
-.. _costs_cf:
-
-``costs``
-=============
-
-.. literalinclude:: ../config/config.default.yaml
-   :language: yaml
-   :start-at: costs:
-   :end-before: clustering:
-
-.. csv-table::
-   :header-rows: 1
-   :widths: 25,7,22,30
-   :file: configtables/costs.csv
-
-
-.. _clustering_cf:
-
-``clustering``
-==============
-
-.. literalinclude:: ../config/config.default.yaml
-   :language: yaml
-   :start-at: clustering:
-   :end-before: solving:
-
-.. csv-table::
-   :header-rows: 1
-   :widths: 25,7,22,30
-   :file: configtables/clustering.csv
-
-
 .. _energy_cf:
 
 ``energy``
@@ -348,7 +404,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: energy:
-   :end-before: biomass:
+   :end-before: # docs
 
 
 .. _biomass_cf:
@@ -365,7 +421,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: biomass:
-   :end-before: solar_thermal:
+   :end-before: # docs
 
 .. _solar_thermal_cf:
 
@@ -381,7 +437,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: solar_thermal:
-   :end-before: existing_capacities:
+   :end-before: # docs
 
 .. _existing_capacities_cf:
 
@@ -397,7 +453,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: existing_capacities:
-   :end-before: sector:
+   :end-before: # docs
 
 .. _sector_cf:
 
@@ -413,7 +469,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: sector:
-   :end-before: industry:
+   :end-before: # docs
 
 .. _industry_cf:
 
@@ -429,7 +485,49 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: industry:
-   :end-before: costs:
+   :end-before: # docs
+
+.. _costs_cf:
+
+``costs``
+=============
+
+.. literalinclude:: ../config/config.default.yaml
+   :language: yaml
+   :start-at: costs:
+   :end-before: # docs
+
+.. csv-table::
+   :header-rows: 1
+   :widths: 25,7,22,30
+   :file: configtables/costs.csv
+
+.. note:: 
+   ``rooftop_share:`` are based on the potentials, assuming  
+   (0.1 kW/m2 and 10 m2/person)
+
+.. _clustering_cf:
+
+``clustering``
+==============
+
+.. literalinclude:: ../config/config.default.yaml
+   :language: yaml
+   :start-at: clustering:
+   :end-before: # docs
+
+.. csv-table::
+   :header-rows: 1
+   :widths: 25,7,22,30
+   :file: configtables/clustering.csv
+
+.. note:: 
+   ``feature:`` in ``simplify_network:`` 
+   are only relevant if ``hac`` were chosen in ``algorithm``.
+
+.. tip:: 
+   use ``min`` in ``p_nom_max:`` for more `
+   conservative assumptions.
 
 .. _solving_cf:
 
@@ -439,12 +537,7 @@ overwrite the existing values.
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: solving:
-   :end-before: plotting:
+   :end-before: # docs
-
-.. csv-table::
-   :header-rows: 1
-   :widths: 25,7,22,30
-   :file: configtables/solving.csv
 
 .. csv-table::
    :header-rows: 1

doc/costs.rst

@@ -12,7 +12,7 @@ The database of cost assumptions is retrieved from the repository
 saved to a file ``data/costs_{year}.csv``. The ``config/config.yaml`` provides options
 to choose a reference year and use a specific version of the repository.
 
-.. literalinclude:: ../config.default.yaml
+.. literalinclude:: ../config/config.default.yaml
    :language: yaml
    :start-at: costs:
    :end-at:   version:

doc/foresight.rst

@@ -87,8 +87,12 @@ evolve with the myopic approach:
   vehicle-to-grid services.
 
 - The annual biomass potential (default year and scenario for which potential is
-  taken is 2030, defined `here
+  taken is 2030, as defined in config)
-  <https://github.com/PyPSA/pypsa-eur-sec/blob/413254e241fb37f55b41caba7264644805ad8e97/config.default.yaml#L109>`_)
+
+.. literalinclude:: ../config/test/config.myopic.yaml
+   :language: yaml
+   :start-at: biomass:
+   :end-at: year:
 
 
 Configuration
@@ -108,7 +112,7 @@ optimized. For a myopic optimization, this is equivalent to the investment year.
 To set the investment years which are sequentially simulated for the myopic
 investment planning, select for example:
 
-.. literalinclude:: ../test/config.myopic.yaml
+.. literalinclude:: ../config/test/config.myopic.yaml
    :language: yaml
    :start-at:   planning_horizons:
    :end-before: countries:
@@ -203,6 +207,7 @@ The myopic code solves the network for the time steps included in
    network comprises additional generator, storage, and link capacities with
    p_nom_extendable=True. The non-solved network is saved in
    ``results/run_name/networks/prenetworks-brownfield``.
+
 The base year is the first element in ``planning_horizons``. Step 1 is
 implemented with the rule add_baseyear for the base year and with the rule
 add_brownfield for the remaining planning_horizons.

doc/preparation.rst

@@ -89,7 +89,7 @@ Rule ``build_powerplants``
 .. _electricity_demand:
 
 Rule ``build_electricity_demand``
-=============================
+==================================
 
 
 .. automodule:: build_electricity_demand

doc/tutorial.rst

@@ -43,21 +43,21 @@ How to configure runs?
 
 The model can be adapted to only include selected countries (e.g. Belgium) instead of all European countries to limit the spatial scope.
 
-.. literalinclude:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: countries:
    :end-before: snapshots:
 
 Likewise, the example's temporal scope can be restricted (e.g. to a single week).
 
-.. literalinclude:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: snapshots:
    :end-before: electricity:
 
 It is also possible to allow less or more carbon-dioxide emissions. Here, we limit the emissions of Belgium to 100 Mt per year.
 
-.. literalinclude:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: electricity:
    :end-before: extendable_carriers:
@@ -65,7 +65,7 @@ It is also possible to allow less or more carbon-dioxide emissions. Here, we lim
 PyPSA-Eur also includes a database of existing conventional powerplants.
 We can select which types of existing powerplants we like to be extendable:
 
-.. literalinclude:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: extendable_carriers:
    :end-before: renewable_carriers:
@@ -74,7 +74,7 @@ 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:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: atlite:
    :end-before: renewable:
@@ -83,7 +83,7 @@ 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:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: solar:
    :end-at: cutout:
@@ -91,7 +91,7 @@ want to use the ERA-5 dataset for solar and not the default SARAH-2 dataset.
 Finally, it is possible to pick a solver. For instance, this tutorial uses the
 open-source solver GLPK.
 
-.. literalinclude:: ../test/config.electricity.yaml
+.. literalinclude:: ../config/test/config.electricity.yaml
    :language: yaml
    :start-at: solver:
    :end-before: plotting:

doc/wildcards.rst

@@ -117,6 +117,23 @@ The ``{sector_opts}`` wildcard
 
 .. warning::
     More comprehensive documentation for this wildcard will be added soon.
+    To really understand the options here, look in scripts/prepare_sector_network.py
+
+  # Co2Lx specifies the CO2 target in x% of the 1990 values; default will give default (5%);
+  # Co2L0p25 will give 25% CO2 emissions; Co2Lm0p05 will give 5% negative emissions
+  # xH is the temporal resolution; 3H is 3-hourly, i.e. one snapshot every 3 hours
+  # single letters are sectors: T for land transport, H for building heating,
+  # B for biomass supply, I for industry, shipping and aviation,
+  # A for agriculture, forestry and fishing
+  # solar+c0.5 reduces the capital cost of solar to 50\% of reference value
+  # solar+p3 multiplies the available installable potential by factor 3
+  # seq400 sets the potential of CO2 sequestration to 400 Mt CO2 per year
+  # dist{n} includes distribution grids with investment cost of n times cost in data/costs.csv
+  # for myopic/perfect foresight cb states the carbon budget in GtCO2 (cumulative
+  # emissions throughout the transition path in the timeframe determined by the
+  # planning_horizons), be:beta decay; ex:exponential decay
+  # cb40ex0 distributes a carbon budget of 40 GtCO2 following an exponential
+  # decay with initial growth rate 0
 
 The ``{sector_opts}`` wildcard is only used for sector-coupling studies.