remove trialed sphinx-bibtex and describe wildcards

doc/conf.py

@@ -36,7 +36,6 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
-    'sphinxcontrib.bibtex',
     #'sphinx.ext.pngmath',
     #'sphinxcontrib.tikz',
     #'rinoh.frontend.sphinx',

doc/index.rst

@@ -101,10 +101,9 @@ Documentation
 Citing PyPSA-Eur
 ================
 
-If you use PyPSA-Eur for your research, we would appreciate it if you would cite the following paper :cite:`PyPSAEur`:
+If you use PyPSA-Eur for your research, we would appreciate it if you would cite the following paper:
 
-.. bibliography:: references.bib
+- 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>`_.
-    :cited:
 
 Please use the following BibTeX: ::
 
@@ -129,10 +128,6 @@ 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
 
-Publications using/citing PyPSA-Eur
-===================================
-
-.. bibliography:: references.bib
 
 Licence
 =======

doc/introduction.rst

@@ -36,7 +36,7 @@ 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 has several configuration options collected in the ``config.yaml`` file
+The model also has several further configuration options collected in the ``config.yaml`` file
 located in the root directory. **All options are explained in detail in** :ref:`config`.
 
 Folder Structure

doc/plotting.rst

@@ -2,31 +2,20 @@
 Plotting and Summary
 ##########################################
 
+.. warning:: The corresponding code is currently under revision and has only minimal documentation.
+
+.. _plot_potentials:
+
+Plot Potentials
+===============
+
+.. automodule:: plot_p_nom_max
+
 .. _summary:
 
 Make Summary
 ============
 
-.. todo:: move to ``make_summary`` autodoc
-
-The following rule can be used to summarize the results in seperate .csv files:
-
-.. code::
-    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.
-
 .. automodule:: make_summary
 
 .. _summary_plot:

doc/wildcards.rst

@@ -6,40 +6,62 @@ Wildcards
 
 Detailed explanations of how wildcards work in ``snakemake`` can be found in the `relevant section of the documentation <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#wildcards>`_.
 
+.. _network:
+
+The ``{network}`` wildcard
+==========================
+
+The ``{network}`` wildcard specifies the considered energy sector(s)
+and, as currently only ``elec`` (for electricity) is included,
+it currently represents rather a placeholder wildcard to facilitate
+future extensions including multiple energy sectors at once.
+
 .. _simpl:
 
-The ``simpl`` wildcard
+The ``{simpl}`` wildcard
-======================
+========================
 
-.. _ll:
+The ``{simpl}`` wildcard specifies number of buses a detailed network model should be pre-clustered to in the rule ``simplify_network`` (before ``cluster_network``).
 
-The ``ll`` wildcard
+.. seealso::
-===================
+    :mod:`simplify_network`
 
 .. _clusters:
 
-The ``clusters`` wildcard
+The ``{clusters}`` wildcard
-=========================
+===========================
 
-.. todo:: explain placing `m` behind number of clusters: only moving instead of aggregating the generators to the clustered buses
+The ``{clusters}`` wildcard specifies the number of buses a detailed network model should be reduced to in the rule ``cluster_network``.
-
-.. warning::
 The number of clusters must be lower than the total number of nodes
-    and higher than the number of countries. A country counts twice if
+and higher than the number of countries. However, a country counts twice if
-    it has two asynchronous subnetworks (e.g. Denmark).
+it has two asynchronous subnetworks (e.g. Denmark or Italy).
 
-.. _network:
+If an `m` is placed behind the number of clusters (e.g. ``100m``), generators are only moved to the clustered buses but not aggregated by carrier; i.e. the clustered bus may have more than one e.g. wind generator.
 
-The ``network`` wildcard
+.. seealso::
-========================
+    :mod:`cluster_network`
 
+.. _ll:
+
+The ``{ll}`` wildcard
+=====================
+
+``v`` (volume) or ``c`` (cost)
+
+``opt`` or a float bigger than one (e.g. 1.25)
+
+.. seealso::
+    :mod:`prepare_network`
 
 .. _opts:
 
-The ``opts`` wildcard
+The ``{opts}`` wildcard
-=====================
+=======================
 
-The ``opts`` wildcard triggers optional constraints, which are activated in either ``prepare_network`` or the ``solve_network`` step. It may hold multiple triggers separated by ``-``, i.e. ``Co2L-3H`` contains the ``Co2L`` trigger and the ``3H`` switch. There are currently:
+The ``{opts}`` wildcard triggers optional constraints, which are activated in either
+``prepare_network`` or the ``solve_network`` step.
+It may hold multiple triggers separated by ``-``, i.e. ``Co2L-3H`` contains the
+``Co2L`` trigger and the ``3H`` switch. There are currently:
 
 
 .. csv-table::
@@ -47,37 +69,69 @@ The ``opts`` wildcard triggers optional constraints, which are activated in eith
    :widths: 10,20,10,10
    :file: configtables/opts.csv
 
+.. seealso::
+    :mod:`prepare_network`, :mod:`solve_network`
 
 .. _country:
 
-The ``country`` wildcard
+The ``{country}`` wildcard
-========================
+==========================
 
-The rules ``make_summary`` (generating summaries of all or a subselection of the solved networks) and ``plot_p_nom_max`` (for plotting the cumulative generation potentials for renewable technologies) can be narrowed to individual countries using the ``country`` wildcard.
+The rules ``make_summary`` and ``plot_summary`` (generating summaries of all or a subselection
-
+of the solved networks) as well as ``plot_p_nom_max`` (for plotting the cumulative
-If ``country = all``, then the rule acts on the network for all countries defined in ``config.yaml``. If otherwise ``country = DE`` or another country code, then the network is narrowed to buses of this country for the rule. For example to get a summary of the energy generated in Germany (in the solution for Europe) use:
+generation potentials for renewable technologies) can be narrowed to
+individual countries using the ``{country}`` wildcard.
 
+If ``country = all``, then the rule acts on the network for all countries
+defined in ``config.yaml``. If otherwise ``country = DE`` or another 2-letter
+country code, then the network is narrowed to buses of this country
+for the rule. For example to get a summary of the energy generated
+in Germany (in the solution for Europe) use:
 
 .. code:: bash
 
     snakemake results/summaries/elec_s_all_lall_Co2L-3H_DE
 
-.. _cutout:
+.. seealso::
+    :mod:`make_summary`, :mod:`plot_summary`, :mod:`plot_p_nom_max`
 
-The ``cutout`` wildcard
+.. _cutout_wc:
-=======================
+
+The ``{cutout}`` wildcard
+=========================
+
+.. seealso::
+    :mod:`build_cutout`
 
 .. _technology:
 
-The ``technology`` wildcard
+The ``{technology}`` wildcard
-===========================
+=============================
+
+.. seealso::
+    :mod:`build_renewable_profiles`, :mod:`plot_p_nom_max`, :mod:`build_country_flh`
 
 .. _attr:
 
-The ``attr`` wildcard
+The ``{attr}`` wildcard
-=====================
+=======================
+
+The ``{attr}`` wildcard specifies which attribute are used for size representations of network components on a map plot produced by the rule ``plot_network``. While it might be extended in the future, ``{attr}`` currently only supports plotting of ``p_nom``.
+
+.. seealso::
+    :mod:`plot_network`
 
 .. _ext:
 
-The ``ext`` wildcard
+The ``{ext}`` wildcard
-====================
+======================
+
+The ``{ext}`` wildcard specifies the file type of the figures the rule ``plot_network``, ``plot_summary``, and ``plot_p_nom_max`` produce. Typical examples are ``pdf`` and ``png``. The list of supported file formats depends on the used backend. To query the supported file types on your system, issue:
+
+.. code:: python
+
+    import matplotlib.pyplot as plt
+    plt.gcf().canvas.get_supported_filetypes()
+
+.. seealso::
+    :mod:`plot_network`, :mod:`plot_summary`, :mod:`plot_p_nom_max`

scripts/build_hydro_profile.py

@@ -30,6 +30,13 @@ Outputs
 
 - ``resources/profile_hydro.nc``:
 
+    ===================  ================  =========================================================
+    Field                Dimensions        Description
+    ===================  ================  =========================================================
+    inflow               countries, time   Inflow to the state of charge (in MW),
+                                           e.g. due to river inflow in hydro reservoir.
+    ===================  ================  =========================================================
+
 Description
 -----------
 

scripts/build_renewable_profiles.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python
-"""The script build_renewable_profiles.py calculates for each network node the
+"""Calculates for each network node the
-*installable capacity* (based on land-use), the *available generation time
+(i) installable capacity (based on land-use), (ii) the available generation time
-series* (based on weather data) and the *average distance from the node* for
+series (based on weather data), and (iii) the average distance from the node for
 onshore wind, AC-connected offshore wind, DC-connected offshore wind and solar
-PV generators. In addition for offshore wind it calculates the *fraction of the
+PV generators. In addition for offshore wind it calculates the fraction of the
-grid connection which is under water*.
+grid connection which is under water.
 
 .. note:: Hydroelectric profiles are built in script :mod:`build_hydro_profiles`.
 
@@ -35,11 +35,6 @@ Relevant settings
             clip_p_max_pu:
             resource:
 
-`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
 ------
 
@@ -66,7 +61,6 @@ Inputs
 Outputs
 -------
 
-<<<<<<< HEAD
 - ``resources/profile_{technology}.nc`` with the following structure
 
     ===================  ==========  =========================================================

scripts/cluster_network.py

@@ -52,17 +52,31 @@ Description
 
     **Why is clustering used both in** ``simplify_network`` **and** ``cluster_network`` **?**
     
-        Consider for example a network ``networks/elec_s100_50.nc`` in which ``simplify_network`` clusters the network to 100 buses and in a second step ``cluster_network``` reduces it down to 50 buses.
+        Consider for example a network ``networks/elec_s100_50.nc`` in which
+        ``simplify_network`` clusters the network to 100 buses and in a second
+        step ``cluster_network``` reduces it down to 50 buses.
 
-        In preliminary tests, it turns out, that the principal effect of changing spatial resolution is actually only partially due to the transmission network. It is more important to differentiate between wind generators with higher capacity factors from those with lower capacity factors, i.e. to have a higher spatial resolution in the renewable generation than in the number of buses.
+        In preliminary tests, it turns out, that the principal effect of
+        changing spatial resolution is actually only partially due to the
+        transmission network. It is more important to differentiate between
+        wind generators with higher capacity factors from those with lower
+        capacity factors, i.e. to have a higher spatial resolution in the
+        renewable generation than in the number of buses.
 
-        The two-step clustering allows to study this effect by looking at networks like ``networks/elec_s100_50m.nc``. Note the additional ``m`` in the ``{cluster}`` wildcard). So in the example network there are still up to 100 different wind generators.
+        The two-step clustering allows to study this effect by looking at
+        networks like ``networks/elec_s100_50m.nc``. Note the additional
+        ``m`` in the ``{cluster}`` wildcard. So in the example network
+        there are still up to 100 different wind generators.
 
-        In combination these two features allow you to study the spatial resolution of the transmission network separately from the spatial resolution of renewable generators.
+        In combination these two features allow you to study the spatial
+        resolution of the transmission network separately from the
+        spatial resolution of renewable generators.
 
     **Is it possible to run the model without the** ``simplify_network`` **rule?**
 
-        No, the network clustering methods in the PyPSA module `pypsa.networkclustering <https://github.com/PyPSA/PyPSA/blob/master/pypsa/networkclustering.py>`_ do not work reliably with multiple voltage levels and transformers.
+        No, the network clustering methods in the PyPSA module
+        `pypsa.networkclustering <https://github.com/PyPSA/PyPSA/blob/master/pypsa/networkclustering.py>`_
+        do not work reliably with multiple voltage levels and transformers.
 
 .. tip::
     The rule ``cluster_all_networks`` runs

scripts/make_summary.py

@@ -24,6 +24,25 @@ Outputs
 Description
 -----------
 
+The following rule can be used to summarize the results in seperate .csv files:
+
+.. code::
+
+    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.
+
 """
 
 import os

scripts/solve_network.py

@@ -22,7 +22,7 @@ Relevant Settings
             max_iterations:
         solver:
             name:
-            {solveroptions}:
+            (solveroptions):
 
     (plotting:)
         (conv_techs:)

scripts/solve_operations_network.py

@@ -19,13 +19,13 @@ Relevant Settings
             max_iterations:
         solver:
             name:
-            {solveroptions}:
+            (solveroptions):
 
 Inputs
 ------
 
 - ``networks/{network}_s{simpl}_{clusters}.nc``: confer :ref:`cluster`
-- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: confer :ref:`solver`
+- ``results/networks/{network}_s{simpl}_{clusters}_l{ll}_{opts}.nc``: confer :ref:`solve    `
 
 Outputs
 -------

scripts/trace_solve_network.py

@@ -19,7 +19,7 @@ Relevant Settings
             max_iterations:
         solver:
             name:
-            {solveroptions}:
+            (solveroptions):
 
 Inputs
 ------