Add a summary sentence for each rule taken from scripts

doc/preparation.rst

@@ -8,36 +8,54 @@ Preparing Networks
 Build Shapes
 =============================
 
-Build Natura Raster
-=============================
+.. automodule:: build_shapes
 
 Build Cutout
 =============================
 
+.. automodule:: build_cutout
+
 Prepare HVDC Links
 =============================
 
-Base Networks
+.. automodule:: prepare_links_p_nom
+
+Base Network
 =============================
 
+.. automodule:: base_network
+
 Build Bus Regions
 =============================
 
+.. automodule:: build_bus_regions
+
 Build Country Full Load Hours
 =============================
 
+.. automodule:: build_country_flh
+
 Build Hydro Profile
 =============================
 
-Build Renewabe Profiles
+.. automodule:: build_hydro_profile
+
+Build Natura Raster
 =============================
 
-Build Renewable Potentials
-=============================
+.. automodule:: build_natura_raster
+
+Build Renewable Profiles
+========================
+
+.. automodule:: build_renewable_profiles
 
 Build Power Plants
 =============================
 
+.. automodule:: build_powerplants
+
 Add Electricity
 =============================
 
+.. automodule:: add_electricity

scripts/add_electricity.py

@@ -1,4 +1,7 @@
 # coding: utf-8
+"""
+Adds electrical generators and storage units to base network
+"""
 
 import logging
 logger = logging.getLogger(__name__)

scripts/base_network.py

@@ -1,4 +1,7 @@
 # coding: utf-8
+"""
+Creates the network topology from ENTSO-E map extracts as a PyPSA network
+"""
 
 import yaml
 import pandas as pd

scripts/build_bus_regions.py

@@ -1,3 +1,7 @@
+"""
+Creates onshore and offshore Voronoi shapes for each bus
+"""
+
 import os
 from operator import attrgetter
 
@@ -7,6 +11,10 @@ import geopandas as gpd
 from vresutils.graph import voronoi_partition_pts
 
 import pypsa
+import logging
+
+if __name__ == "__main__":
+    logging.basicConfig(level=snakemake.config["logging_level"])
 
     countries = snakemake.config['countries']
 

scripts/build_country_flh.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python
+"""
+Create csv files and plots for comparing per country full load hours of renewable time-series
+"""
 
 import os
 import atlite

scripts/build_cutout.py

@@ -1,8 +1,12 @@
+"""
+Create cutouts configured in `atlite` config section
+"""
 import os
 import atlite
 import logging
 logger = logging.getLogger(__name__)
 
+if __name__ == "__main__":
     logging.basicConfig(level=snakemake.config['logging_level'])
 
     cutout_params = snakemake.config['atlite']['cutouts'][snakemake.wildcards.cutout]

scripts/build_hydro_profile.py

@@ -1,4 +1,11 @@
 #!/usr/bin/env python
+"""
+Build hydroelectric inflow time-series for each country
+
+See also
+--------
+build_renewable_profiles
+"""
 
 import os
 import atlite
@@ -6,8 +13,10 @@ import pandas as pd
 import geopandas as gpd
 from vresutils import hydro as vhydro
 import logging
-logger = logging.getLogger(__name__)
-logger.setLevel(level=snakemake.config['logging_level'])
+
+
+if __name__ == "__main__":
+    logger.basicConfig(level=snakemake.config['logging_level'])
 
     config = snakemake.config['renewable']['hydro']
     cutout = atlite.Cutout(config['cutout'],

scripts/build_natura_raster.py

@@ -1,3 +1,7 @@
+"""
+Rasters the vector data of the NATURA2000 data onto all cutout regions
+"""
+
 import numpy as np
 import atlite
 from osgeo import gdal
@@ -10,6 +14,7 @@ def determine_cutout_xXyY(cutout_name):
     dy = (Y - y) / (cutout.shape[0] - 1)
     return [x - dx/2., X + dx/2., y - dy/2., Y + dy/2.]
 
+if __name__ == "__main__":
     cutout_names = np.unique([res['cutout'] for res in snakemake.config['renewable'].values()])
     xs, Xs, ys, Ys = zip(*(determine_cutout_xXyY(cutout) for cutout in cutout_names))
     xXyY = min(xs), max(Xs), min(ys), max(Ys)

scripts/build_powerplants.py

@@ -1,4 +1,7 @@
 # coding: utf-8
+"""
+Get conventional powerplants from `powerplantmatching`, assign to buses and create csv file
+"""
 
 import logging
 import numpy as np

scripts/build_renewable_profiles.py

@@ -1,4 +1,79 @@
 #!/usr/bin/env python
+"""
+Summary
+-------
+The script ``build_renewable_profiles.py`` calculates for each node several geographical properties:
+
+  1. the installable capacity (based on land-use)
+  2. the available generation time series (based on weather data) and
+  3. the average distance from the node for onshore wind, AC-connected offshore wind, DC-connected offshore wind and solar PV generators.
+  4. In addition for offshore wind it calculates the fraction of the grid connection which is under water.
+
+.. note:: Hydroelectric profiles are built in script :mod:`build_hydro_profiles`.
+
+Relevant settings
+-----------------
+
+config.renewable (describes the parameters for onwind, offwind-ac, offwind-dc
+and solar)
+config.snapshots (describes the time dimensions of the selection of snapshots)
+
+Inputs
+------
+
+base_network
+land-use shapes
+region shapes for onshore, offshore and countries
+cutout
+
+Outputs
+-------
+
+profile_{tech}.nc for tech in [onwind,offwind-ac,offwind-dc,solar]
+
+profile_{tech}.nc contains five common fields:
+
+profile (bus x time) - the per unit hourly availability factors for each node
+weight (bus) - the sum of the layout weighting for each node
+p_nom_max (bus) - the maximal installable capacity at the node (in MW)
+potential (y,x) - the layout of generator units at cutout grid cells inside the
+voronoi cell (maximal installable capacity at each grid cell multiplied by the
+capacity factor)
+average_distance (bus) - the average distance of units in the voronoi cell to
+the grid node (in km)
+
+for offshore we also have:
+
+underwater_fraction (bus) - the fraction of the average connection distance
+which is under water
+
+Long description:
+
+First the script computes how much of the technology can be installed at each
+cutout grid cell and each node using the library `GLAES
+<https://github.com/FZJ-IEK3-VSA/glaes>`_. This uses the CORINE land use data,
+Natura2000 nature reserves and GEBCO for bathymetry.
+
+To compute the layout of generators in each node's voronoi cell, the installable
+potential in each grid cell is multiplied with the capacity factor at each grid
+cell (since we assume more generators are installed at cells with a higher
+capacity factor).
+
+This layout is then used to compute the generation availability time series from
+the atlite cutout.
+
+Two methods are available to compute the maximal installable potential for the
+node (`p_nom_max`): `simple` and `conservative`:
+
+`simple` adds up the installable potentials of the individual grid cells (if the
+model comes close to this limit, then the time series may slightly overestimate
+production since we assumed the geographical distribution is proportional to
+capacity factor).
+
+`conservative` assertains the nodal limit by increasing capacities proportional
+to the layout until the limit of an individual grid cell is reached.
+
+"""
 
 import matplotlib.pyplot as plt
 

scripts/build_shapes.py

@@ -1,3 +1,7 @@
+"""
+Create GIS shape files for countries on-shore and off-shore, europe and nuts3 regions
+"""
+
 import os
 import numpy as np
 from operator import attrgetter

scripts/cluster_network.py

@@ -1,4 +1,7 @@
 # coding: utf-8
+"""
+Create networks clustered to `cluster` number of zones with aggregated buses, generators and transmission corridors
+"""
 
 import pandas as pd
 idx = pd.IndexSlice
@@ -243,5 +246,3 @@ if __name__ == "__main__":
             store.put(attr, getattr(clustering, attr), format="table", index=False)
 
     cluster_regions((clustering.busmap,))
-
-

scripts/make_summary.py

@@ -1,14 +1,5 @@
 """
-Test module description
-
-Examples
---------
-Test example
-`Example <http://www.example.com>`_
-
-:ref:`Installation <installation>`
-
-``code``
+Create summaries of aggregated energy and costs as csv files
 """
 
 import os

scripts/plot_network.py

@@ -1,3 +1,14 @@
+"""
+Plot map with pie charts and cost box plots
+"""
+
+# Dirty work-around so that sphinx can import this module and get the
+# doc-string should be refactored in the style of the other scripts, ideally
+# several functions for the different plots
+if __name__ != "__main__":
+    import sys
+    sys.exit(0)
+
 if 'snakemake' not in globals():
     from vresutils.snakemake import MockSnakemake, Dict
     from snakemake.rules import expand

scripts/plot_p_nom_max.py

@@ -1,3 +1,7 @@
+"""
+Plot renewable installation potentials per capacity factor
+"""
+
 import pypsa
 import pandas as pd
 import matplotlib.pyplot as plt

scripts/plot_summary.py

@@ -1,3 +1,7 @@
+"""
+Plot energy and cost summaries for several solved networks
+"""
+
 import os
 import pandas as pd
 import matplotlib.pyplot as plt

scripts/prepare_links_p_nom.py

@@ -1,8 +1,12 @@
 #!/usr/bin/env python
+"""
+Extract capacities for HVDC links from wikipedia
+"""
 
 import pandas as pd
 import numpy as np
 
+if __name__ == "__main__":
     links_p_nom = pd.read_html('https://en.wikipedia.org/wiki/List_of_HVDC_projects', header=0, match="SwePol")[0]
 
     def extract_coordinates(s):
@@ -15,6 +19,7 @@ def extract_coordinates(s):
 
     m_b = links_p_nom["Power (MW)"].str.contains('x').fillna(False)
     def multiply(s): return s.str[0].astype(float) * s.str[1].astype(float)
+
     links_p_nom.loc[m_b, "Power (MW)"] = links_p_nom.loc[m_b, "Power (MW)"].str.split('x').pipe(multiply)
     links_p_nom["Power (MW)"] = links_p_nom["Power (MW)"].str.extract("[-/]?([\d.]+)", expand=False).astype(float)
 
@@ -22,4 +27,3 @@ links_p_nom['x1'], links_p_nom['y1'] = extract_coordinates(links_p_nom['Converte
     links_p_nom['x2'], links_p_nom['y2'] = extract_coordinates(links_p_nom['Converterstation 2'])
 
     links_p_nom.dropna(subset=['x1', 'y1', 'x2', 'y2']).to_csv(snakemake.output[0], index=False)
-

scripts/prepare_network.py

@@ -1,4 +1,7 @@
 # coding: utf-8
+"""
+Prepare PyPSA network for solving according to `opts`-wildcard
+"""
 
 import logging
 logger = logging.getLogger(__name__)

scripts/simplify_network.py

@@ -1,4 +1,8 @@
 # coding: utf-8
+"""Bring electrical transmission network to a single 380kV voltage layer,
+remove network dead-ends, and reduce multi-hop linear HVDC connections to a
+single link
+"""
 
 import pandas as pd
 idx = pd.IndexSlice

scripts/solve_network.py

@@ -1,3 +1,7 @@
+"""
+Solve networks iteratively linear optimal power flow, while updating reactances
+"""
+
 import numpy as np
 import pandas as pd
 import logging

scripts/solve_operations_network.py

@@ -1,3 +1,8 @@
+"""
+Solve linear optimal dispatch in hourly resolution with capacities of previous
+capacity expansion
+"""
+
 import pypsa
 import numpy as np
 import re

scripts/trace_solve_network.py

@@ -1,3 +1,8 @@
+"""
+Iteratively solves expansion problem like solve_network, but additionally
+records intermediate branch capacity steps and values of the objective
+"""
+
 import numpy as np
 import pandas as pd
 import logging