From 4d3d898430fcc9128ccfc13d48d0391d8dd9ffb5 Mon Sep 17 00:00:00 2001 From: Fabian Neumann Date: Mon, 12 Aug 2019 23:48:16 +0200 Subject: [PATCH] remove trialed sphinx-bibtex and describe wildcards --- doc/conf.py | 1 - doc/index.rst | 9 +-- doc/introduction.rst | 2 +- doc/plotting.rst | 31 +++----- doc/wildcards.rst | 118 ++++++++++++++++++++-------- scripts/build_hydro_profile.py | 7 ++ scripts/build_renewable_profiles.py | 16 ++-- scripts/cluster_network.py | 24 ++++-- scripts/make_summary.py | 19 +++++ scripts/solve_network.py | 2 +- scripts/solve_operations_network.py | 4 +- scripts/trace_solve_network.py | 2 +- 12 files changed, 153 insertions(+), 82 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 5db4634c..0bbee5d3 100644 --- a/doc/conf.py +++ b/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', diff --git a/doc/index.rst b/doc/index.rst index 63e202f6..1abce97f 100644 --- a/doc/index.rst +++ b/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 - :cited: +- Jonas Hörsch, Fabian Hofmann, David Schlachtberger, and Tom Brown. `PyPSA-Eur: An open optimisation model of the European transmission system `_. Energy Strategy Reviews, 22:207-215, 2018. `arXiv:1806.01613 `_, `doi:10.1016/j.esr.2018.08.012 `_. 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 ======= diff --git a/doc/introduction.rst b/doc/introduction.rst index 130b4f1b..0ac2d27a 100644 --- a/doc/introduction.rst +++ b/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 `_ of ``snakemake``. Wildcards allow to generalise a rule to produce all files that follow a `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 diff --git a/doc/plotting.rst b/doc/plotting.rst index bdf5bf00..be030a75 100644 --- a/doc/plotting.rst +++ b/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: @@ -44,4 +33,4 @@ Plot Network .. automodule:: plot_network .. image:: img/tech-colors.png - :align: center + :align: center \ No newline at end of file diff --git a/doc/wildcards.rst b/doc/wildcards.rst index 08759c21..7aab130c 100644 --- a/doc/wildcards.rst +++ b/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 `_. +.. _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``. +The number of clusters must be lower than the total number of nodes +and higher than the number of countries. However, a country counts twice if +it has two asynchronous subnetworks (e.g. Denmark or Italy). -.. 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 - it has two asynchronous subnetworks (e.g. Denmark). +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. -.. _network: +.. seealso:: + :mod:`cluster_network` -The ``network`` wildcard -======================== +.. _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. - -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: +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 +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` \ No newline at end of file diff --git a/scripts/build_hydro_profile.py b/scripts/build_hydro_profile.py index 9d027b98..16c88ae5 100644 --- a/scripts/build_hydro_profile.py +++ b/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 ----------- diff --git a/scripts/build_renewable_profiles.py b/scripts/build_renewable_profiles.py index 8b576727..179408ab 100644 --- a/scripts/build_renewable_profiles.py +++ b/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 -*installable capacity* (based on land-use), the *available generation time -series* (based on weather data) and the *average distance from the node* for +"""Calculates for each network node the +(i) installable capacity (based on land-use), (ii) the available generation time +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 -grid connection which is under water*. +PV generators. 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`. @@ -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 =================== ========== ========================================================= diff --git a/scripts/cluster_network.py b/scripts/cluster_network.py index b6d1dfd6..04e5702a 100644 --- a/scripts/cluster_network.py +++ b/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 `_ do not work reliably with multiple voltage levels and transformers. + No, the network clustering methods in the PyPSA module + `pypsa.networkclustering `_ + do not work reliably with multiple voltage levels and transformers. .. tip:: The rule ``cluster_all_networks`` runs diff --git a/scripts/make_summary.py b/scripts/make_summary.py index 98ae6b86..64b1f446 100644 --- a/scripts/make_summary.py +++ b/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 diff --git a/scripts/solve_network.py b/scripts/solve_network.py index 34bc2977..06b4bf0b 100644 --- a/scripts/solve_network.py +++ b/scripts/solve_network.py @@ -22,7 +22,7 @@ Relevant Settings max_iterations: solver: name: - {solveroptions}: + (solveroptions): (plotting:) (conv_techs:) diff --git a/scripts/solve_operations_network.py b/scripts/solve_operations_network.py index 14acf192..13ca5c69 100644 --- a/scripts/solve_operations_network.py +++ b/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 ------- diff --git a/scripts/trace_solve_network.py b/scripts/trace_solve_network.py index 0300fc75..286dc2e8 100644 --- a/scripts/trace_solve_network.py +++ b/scripts/trace_solve_network.py @@ -19,7 +19,7 @@ Relevant Settings max_iterations: solver: name: - {solveroptions}: + (solveroptions): Inputs ------