add cutout related descriptions and figures

doc/configtables/atlite.csv

@@ -1,13 +1,8 @@
 ,Unit,Values,Description
 nprocesses,--,int,"Number of parallel processes in cutout preparation"
 cutouts,,,
--- europe-2013-era5,--,,"Directory to write cutout data to."
+-- {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,--,"Must be 'era5'","Source of the reanalysis weather dataset. `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_"
+-- -- 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."
--- europe-2013-sarah,--,,"Directory to write cutout data to."
--- -- module,--,"Must be 'sarah'","Source of the surface solar radiation dataset. `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 [1983,2015]","Range of years to download weather data for."

doc/configtables/offwind-ac.csv

@@ -1,5 +1,5 @@
 ,Unit,Values,Description
-cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the relevant weather data ist stored."
+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."

doc/configtables/offwind-dc.csv

@@ -1,5 +1,5 @@
 ,Unit,Values,Description
-cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the relevant weather data ist stored."
+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."

doc/configtables/onwind.csv

@@ -1,5 +1,5 @@
 ,Unit,Values,Description
-cutout,--,"Must be 'europe-2013-era5'","Specifies the directory where the relevant weather data ist stored."
+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."

doc/configtables/solar.csv

@@ -1,5 +1,5 @@
 ,Unit,Values,Description
-cutout,--,"One of {'europe-2013-era5', 'europe-2013-sarah'}","Specifies the directory where the relevant weather data ist stored that is specified at ``atlite/cutouts`` configuration. Both ``sarah`` and ``era5`` work."
+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."

doc/preparation.rst

@@ -2,12 +2,14 @@
 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:
+The preparation process of the PyPSA-Eur energy system model consists of a group of ``snakemake``
+rules which are briefly outlined and explained in detail in the sections below:
 
 - ``build_shapes`` generates GeoJSON files with shapes of the countries, exclusive economic zones and `NUTS3 <https://en.wikipedia.org/wiki/Nomenclature_of_Territorial_Units_for_Statistics>`_ areas.
 - ``build_cutout`` prepares smaller weather data portions from `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_ for cutout ``europe-2013-era5`` and SARAH for cutout ``europe-2013-sarah``.
 
-With these and the externally extracted ENTSO-E online map topology (``data/entsoegridkit``), it can build a base PyPSA network with the following rules:
+With these and the externally extracted ENTSO-E online map topology
+(``data/entsoegridkit``), it can build a base PyPSA network with the following rules:
 
 - ``base_network`` builds and stores the base network with all buses, HVAC lines and HVDC links, while
 - ``build_bus_regions`` determines `Voronoi cells <https://en.wikipedia.org/wiki/Voronoi_diagram>`_ for all substations.
@@ -19,7 +21,8 @@ Then the process continues by calculating conventional power plant capacities, p
 - ``build_renewable_profiles`` for the hourly capacity factors in each substation's Voronoi cell for PV, onshore and offshore wind, and
 - ``build_hydro_profile`` for the hourly per-unit hydro power availability time series.
 
-The central rule ``add_electricity`` then ties all the different data inputs together into a detailed PyPSA network stored in ``networks/elec.nc``.
+The central rule ``add_electricity`` then ties all the different data inputs
+together into a detailed PyPSA network stored in ``networks/elec.nc``.
 
 .. _shapes:
 

scripts/build_cutout.py

@@ -23,7 +23,58 @@ Inputs
 Outputs
 -------
 
-- ``cutouts/{cutout}``:
+- ``cutouts/{cutout}``: weather data from either the `ERA5 <https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5>`_
+  reanalysis weather dataset or `SARAH-2 <https://wui.cmsaf.eu/safira/action/viewProduktSearch>`_
+  satellite-based historic weather data with the following structure:
+
+**ERA5 cutout:**
+
+    ===================  ==========  ==========  =========================================================
+    Field                Dimensions  Unit        Description
+    ===================  ==========  ==========  =========================================================
+    pressure             time, y, x  Pa          Surface pressure
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    temperature          time, y, x  K           Air temperature 2 meters above the surface.
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    soil temperature     time, y, x  K           Soil temperature between 1 meters and 3 meters
+                                                 depth (layer 4).
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    influx_toa           time, y, x  Wm**-2      Top of Earth's atmosphere TOA incident solar radiation
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    influx_direct        time, y, x  Wm**-2      Total sky direct solar radiation at surface
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    runoff               time, y, x  m           `Runoff <https://en.wikipedia.org/wiki/Surface_runoff>`_
+                                                 (volume per area)
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    roughness            y, x        m           Forecast surface roughness
+                                                 (`roughness length <https://en.wikipedia.org/wiki/Roughness_length>`_)
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    height               y, x        m           Surface elevation above sea level
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    albedo               time, y, x  --          `Albedo <https://en.wikipedia.org/wiki/Albedo>`_
+                                                 measure of diffuse reflection of solar radiation.
+                                                 Calculated from relation between surface solar radiation
+                                                 downwards (Jm**-2) and surface net solar radiation
+                                                 (Jm**-2). Takes values between 0 and 1.
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    influx_diffuse       time, y, x  Wm**-2      Diffuse solar radiation at surface.
+                                                 Surface solar radiation downwards minus
+                                                 direct solar radiation.
+    -------------------  ----------  ----------  ---------------------------------------------------------
+    wnd100m              time, y, x  ms**-1      Wind speeds at 100 meters (regardless of direction)
+    ===================  ==========  ==========  =========================================================
+
+    .. image:: img/era5.png
+        :scale: 40 %    
+    
+A **SARAH-2 cutout** can be used to amend the fields ``temperature``, ``influx_toa``, ``influx_direct``, ``albedo``,
+``influx_diffuse`` of ERA5 using satellite-based radiation observations.
+    
+    .. image:: img/sarah.png
+        :scale: 40 %
+
+.. seealso::
+    For details on the weather data read the `atlite documentation <https://atlite.readthedocs.io/en/latest/>`_.
 
 Description
 -----------

scripts/build_hydro_profile.py

@@ -41,6 +41,12 @@ Outputs
                                            e.g. due to river inflow in hydro reservoir.
     ===================  ================  =========================================================
 
+    .. image:: img/inflow-ts.png
+        :scale: 33 %
+    
+    .. image:: img/inflow-box.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/build_renewable_profiles.py

@@ -72,7 +72,7 @@ Outputs
     ===================  ==========  =========================================================
     profile              bus, time   the per unit hourly availability factors for each node
     -------------------  ----------  ---------------------------------------------------------
-    weight               bus         sum of the layougt weighting for each node
+    weight               bus         sum of the layout weighting for each node
     -------------------  ----------  ---------------------------------------------------------
     p_nom_max            bus         maximal installable capacity at the node (in MW)
     -------------------  ----------  ---------------------------------------------------------
@@ -87,6 +87,31 @@ Outputs
                                      under water (only for offshore)
     ===================  ==========  =========================================================
 
+    - **profile**
+
+    .. image:: img/profile_ts.png
+        :scale: 33 %
+    
+    - **p_nom_max**
+
+    .. image:: img/p_nom_max_hist.png
+        :scale: 33 %
+    
+    - **potential**
+
+    .. image:: img/potential_heatmap.png
+        :scale: 33 %
+    
+    - **average_distance**
+    
+    .. image:: img/distance_hist.png
+        :scale: 33 %
+    
+    - **underwater_fraction**
+    
+    .. image:: img/underwater_hist.png
+        :scale: 33 %
+
 Description
 -----------
 

scripts/build_shapes.py

@@ -53,7 +53,7 @@ Outputs
     .. image:: img/europe_shape.png
         :scale: 33 %
         
-- ``resources/nuts3_shapes.geojson``: NUTS3 shapes out of country selection
+- ``resources/nuts3_shapes.geojson``: NUTS3 shapes out of country selection including population and GDP data.
         
     .. image:: img/nuts3_shapes.png
         :scale: 33 %

scripts/prepare_network.py

@@ -1,6 +1,6 @@
 # coding: utf-8
 """
-Prepare PyPSA network for solving according to ``{opts}`` wildcard.
+Prepare PyPSA network for solving according to the ``{opts}`` wildcard (:ref:`opts`).
 
 Relevant Settings
 -----------------