Feature/pypsa 13 fork

.travis.yml

@@ -0,0 +1,44 @@
+# Modified from
+# https://github.com/calliope-project/calliope/blob/master/.travis.yml
+
+language: python
+sudo: false # Use container-based infrastructure
+
+matrix:
+  include:
+    - env:
+      - PYTHON_VERSION="2.7"
+    - env:
+      - PYTHON_VERSION="3.6"
+
+before_install:
+  - if [[ "$PYTHON_VERSION" == "2.7" ]]; then
+      wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh -O miniconda.sh;
+    else
+      wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
+    fi
+  - bash miniconda.sh -b -p $HOME/miniconda
+  - export PATH="$HOME/miniconda/bin:$PATH"
+  - hash -r
+  - conda config --set always_yes yes --set changeps1 no
+  - conda update -q conda
+  # Useful for debugging any issues with conda
+  - conda info -a
+
+install:
+  - conda create -q -n pypsa python=$PYTHON_VERSION
+  - conda env update -q -n pypsa --file=requirements.yml
+  - conda env update -q -n pypsa --file=requirements_dev.yml
+  - source activate pypsa
+  # - conda install -q -c conda-forge python-coveralls # don't install on appveyor
+  - pip install --no-cache-dir .
+
+# before_script:  # configure a headless display to test plot generation
+#   - "export DISPLAY=:99.0"
+#   - "sh -e /etc/init.d/xvfb start"
+#   - sleep 3  # give xvfb some time to start
+
+script: "make test"
+
+# after_success:
+#   - coveralls

MANIFEST.in

@@ -1,3 +1,5 @@
 include pypsa/component_attrs/*.csv
 include pypsa/standard_types/*.csv
 include pypsa/components.csv
+include README.rst LICENSE.txt
+include requirements.yml

Makefile

@@ -0,0 +1,15 @@
+.PHONY : test sdist upload clean dist
+
+test :
+	pytest --cov pypsa --cov-report term-missing
+
+sdist :
+	python setup.py sdist
+
+upload :
+	twine upload dist/*
+
+clean :
+	rm dist/*
+
+dist : sdist upload clean

README.rst

@@ -1,3 +1,7 @@
+|badge_travis| |badge_pypi| |badge_license|
+
+-----
+
 ################################
 Python for Power System Analysis
 ################################
@@ -16,18 +20,18 @@ PyPSA is a `free software
 <http://www.gnu.org/philosophy/free-sw.en.html>`_ toolbox for
 simulating and optimising modern power systems that include features
 such as conventional generators with unit commitment, variable wind
-and solar generation, storage units, sector coupling and mixed
-alternating and direct current networks. PyPSA is designed to scale
-well with large networks and long time series.
-
-As of 2017 PyPSA is under heavy development and therefore it is
-recommended to use caution when using it in a production environment.
-Some APIs may change - the changes in each PyPSA version are listed in
-the `doc/release_notes.rst <doc/reslease_notes.rst>`_.
-
-
-
-PyPSA was initially developed by the `Renewable Energy Group
+and solar generation, storage units, coupling to other energy sectors,
+and mixed alternating and direct current networks. PyPSA is designed
+to scale well with large networks and long time series.
+
+This project is maintained by the `Energy System Modelling
+group <https://www.iai.kit.edu/english/2338.php>`_ at the `Institute for
+Automation and Applied
+Informatics <https://www.iai.kit.edu/english/index.php>`_ at the
+`Karlsruhe Institute of
+Technology <http://www.kit.edu/english/index.php>`_. The group is funded by the
+`Helmholtz Association <https://www.helmholtz.de/en/>`_ until 2024.
+Previous versions were developed by the `Renewable Energy Group
 <https://fias.uni-frankfurt.de/physics/schramm/renewable-energy-system-and-network-analysis/>`_
 at `FIAS <https://fias.uni-frankfurt.de/>`_ to carry out simulations
 for the `CoNDyNet project <http://condynet.de/>`_, financed by the
@@ -57,14 +61,15 @@ PyPSA can calculate:
 
 * static power flow (using both the full non-linear network equations and
   the linearised network equations)
-* linear optimal power flow (optimisation of power plant and storage
-  dispatch within network constraints, using the linear network
-  equations, over several snapshots)
+* linear optimal power flow (least-cost optimisation of power plant
+  and storage dispatch within network constraints, using the linear
+  network equations, over several snapshots)
 * security-constrained linear optimal power flow
-* total electricity system investment optimisation (using linear
-  network equations, over several snapshots simultaneously for
-  optimisation of generation and storage dispatch and investment in
-  the capacities of generation, storage and transmission)
+* total electricity/energy system least-cost investment optimisation
+  (using linear network equations, over several snapshots
+  simultaneously for optimisation of generation and storage dispatch
+  and investment in the capacities of generation, storage,
+  transmission and other infrastructure)
 
 It has models for:
 
@@ -80,31 +85,29 @@ It has models for:
 * basic components out of which more complicated assets can be built,
   such as Combined Heat and Power (CHP) units, heat pumps, resistive
   Power-to-Heat (P2H), Power-to-Gas (P2G), battery electric vehicles
-  (BEVs), etc.; each of these is demonstrated in the `examples
+  (BEVs), Fischer-Tropsch, direct air capture (DAC), etc.; each of
+  these is demonstrated in the `examples
   <http://www.pypsa.org/examples/>`_
 
 
-Functionality that will definitely be added soon:
+Functionality that may be added in the future:
 
 * Multi-year investment optimisation
-* Simple RMS simulations with the swing equation
 * Distributed active power slack
-* Non-linear power flow solution using `analytic continuation
-  <https://en.wikipedia.org/wiki/Holomorphic_embedding_load_flow_method>`_
-  in the complex plane following `GridCal
-  <https://github.com/SanPen/GridCal>`_
-
-Functionality that may be added in the future:
-
-* Short-circuit current calculations
-* Dynamic RMS simulations
-* Small signal stability analysis
 * Interactive web-based GUI with SVG
 * OPF with the full non-linear network equations
-* Dynamic EMT simulations
-* Unbalanced load flow
 * Port to `Julia <http://julialang.org/>`_
 
+Other complementary libraries:
+
+* `pandapower <https://github.com/e2nIEE/pandapower>`_ for more
+  detailed modelling of distribution grids, short-circuit
+  calculations, unbalanced load flow and more
+* `PowerDynamics.jl
+  <https://github.com/JuliaEnergy/PowerDynamics.jl>`_ for dynamic
+  modelling of power grids at time scales where differential equations are relevant
+
+
 
 Example scripts as Jupyter notebooks
 ====================================
@@ -117,7 +120,12 @@ available as Python scripts in `examples/ <examples/>`_.
 Screenshots
 ===========
 
-The showcase for PyPSA is the `SciGRID example
+Results from a PyPSA simulation can be converted into an interactive
+online animation using `PyPSA-animation
+<https://github.com/PyPSA/PyPSA-animation>`_, see the `PyPSA-Eur-30
+example <https://www.pypsa.org/animations/pypsa-eur-30/>`_.
+
+Another showcase for PyPSA is the `SciGRID example
 <https://pypsa.org/examples/scigrid-lopf-then-pf-plotly.html>`_ which
 demonstrates interactive plots generated with the `plotly
 <https://plot.ly/python/>`_ library.
@@ -147,7 +155,7 @@ What PyPSA uses under the hood
 ===============================
 
 PyPSA is written and tested to be compatible with both Python 2.7 and
-Python 3.5.
+Python 3.6.
 
 It leans heavily on the following Python packages:
 
@@ -183,12 +191,31 @@ Citing PyPSA
 
 
 If you use PyPSA for your research, we would appreciate it if you
-would cite the following preprint paper (which has not yet been
-through peer review):
+would cite the following paper:
 
 * T. Brown, J. Hörsch, D. Schlachtberger, `PyPSA: Python for Power
-  System Analysis <https://arxiv.org/abs/1707.09913>`_, 2017,
-  `preprint arXiv:1707.09913 <https://arxiv.org/abs/1707.09913>`_
+  System Analysis <https://arxiv.org/abs/1707.09913>`_, 2018,
+  `Journal of Open Research Software
+  <https://openresearchsoftware.metajnl.com/>`_, 6(1),
+  `arXiv:1707.09913 <https://arxiv.org/abs/1707.09913>`_,
+  `DOI:10.5334/jors.188 <https://doi.org/10.5334/jors.188>`_
+
+
+Please use the following BibTeX: ::
+
+   @article{PyPSA,
+      author = {T. Brown and J. H\"orsch and D. Schlachtberger},
+      title = {{PyPSA: Python for Power System Analysis}},
+      journal = {Journal of Open Research Software},
+      volume = {6},
+      issue = {1},
+      number = {4},
+      year = {2018},
+      eprint = {1707.09913},
+      url = {https://doi.org/10.5334/jors.188},
+      doi = {10.5334/jors.188}
+   }
+
 
 If you want to cite a specific PyPSA version, each release of PyPSA is
 stored on `Zenodo <https://zenodo.org/>`_ with a release-specific DOI.
@@ -201,8 +228,8 @@ This can be found linked from the overall PyPSA Zenodo DOI:
 Licence
 =======
 
-Copyright 2015-2017 Tom Brown (FIAS), Jonas Hörsch (FIAS), David
-Schlachtberger (FIAS)
+Copyright 2015-2019 Tom Brown (KIT, FIAS), Jonas Hörsch (KIT, FIAS),
+David Schlachtberger (FIAS)
 
 This program is free software: you can redistribute it and/or
 modify it under the terms of the GNU General Public License as
@@ -213,3 +240,17 @@ This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 `GNU General Public License <LICENSE.txt>`_ for more details.
+
+.. |link-latest-doi| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.786605.svg
+.. _link-latest-doi: https://doi.org/10.5281/zenodo.786605
+
+.. |badge_pypi| image:: https://img.shields.io/pypi/v/pypsa.svg
+    :target: https://pypi.python.org/pypi/pypsa
+    :alt: PyPI version
+
+.. |badge_license| image:: https://img.shields.io/pypi/l/pypsa.svg
+    :target: #license
+
+.. |badge_travis| image:: https://img.shields.io/travis/PyPSA/PyPSA/master.svg
+    :target: https://travis-ci.org/PyPSA/PyPSA
+    :alt: Build status on Linux

doc/comparable_software.rst

@@ -2,7 +2,7 @@
 Comparable Software
 #######################
 
-The `PyPSA preprint paper <https://arxiv.org/abs/1707.09913>`_
+The `PyPSA paper <https://arxiv.org/abs/1707.09913>`_
 contains a discussion of PyPSA's features compared to other software
 tools and a functionality comparison in Table III.
 

doc/components.rst

@@ -434,10 +434,48 @@ the ``Link`` with ``efficiency = 1``, ``marginal_cost = 0``,
    :file: ../pypsa/component_attrs/links.csv
 
 
+.. _components-links-multiple-outputs:
+
+Link with multiple outputs or inputs
+------------------------------------
+
+Links can also be defined with multiple outputs in fixed ratio to the
+power in the single input by defining new columns ``bus2``, ``bus3``,
+etc. (``bus`` followed by an integer) in ``network.links`` along with
+associated columns for the efficiencies ``efficiency2``,
+``efficiency3``, etc. The different outputs are then proportional to
+the input according to the efficiency; see :ref:`opf-links` for how
+these are used in the LOPF and the `example of a CHP with a fixed
+power-heat ratio
+<https://www.pypsa.org/examples/chp-fixed-heat-power-ratio.html>`_.
+
+To define the new columns ``bus2``, ``efficiency2``, ``bus3``,
+``efficiency3``, etc. in ``network.links`` you need to override the
+standard component attributes by passing ``pypsa.Network()`` an
+``override_component_attrs`` argument. See the section
+:ref:`custom_components` and the `example of a CHP with a fixed
+power-heat ratio
+<https://www.pypsa.org/examples/chp-fixed-heat-power-ratio.html>`_.
+
+
+If the column ``bus2`` exists, values in the column are not compulsory
+for all links; if the link has no 2nd output, simply leave it empty
+``network.links.at["my_link","bus2"] = ""``.
+
+For links with multiple inputs in fixed ratio to a single output,
+simply reverse the flow in a link with one input and multiple outputs
+by setting ``my_link.p_max_pu = 0`` and ``my_link.p_min_pu = -1``.
+
+For multiple inputs to multiple outputs, connect a multi-to-single
+link to a single-to-multi link with an auxiliary bus in the middle.
+
+
 Groups of Components
 ====================
 
-In the code components are grouped according to their properties.
+In the code components are grouped according to their properties in
+sets such as ``network.one_port_components`` and
+``network.branch_components``.
 
 One-ports share the property that they all connect to a single bus,
 i.e. generators, loads, storage units, etc.. They share the attributes
@@ -453,3 +491,31 @@ nodal power imbalances, i.e. lines and transformers.
 
 Controllable branches are branches whose power flow can be controlled
 by e.g. the LOPF optimisation, i.e. links.
+
+
+.. _custom_components:
+
+Custom Components
+=================
+
+If you want to define your own components and override the standard
+functionality of PyPSA, you can easily override the standard
+components by passing pypsa.Network() the arguments
+``override_components`` and ``override_component_attrs``.
+
+For this network, these will replace the standard definitions in
+``pypsa.components.components`` and
+``pypsa.components.component_attrs``, which correspond to the
+repository CSV files ``pypsa/components.csv`` and
+``pypsa/component_attrs/*.csv``.
+
+``components`` is a pandas.DataFrame with the component ``name``,
+``list_name`` and ``description``. ``component_attrs`` is a
+pypsa.descriptors.Dict of pandas.DataFrame with the attribute
+properties for each component.  Just follow the formatting for the
+standard components.
+
+There are examples for defining new components in the git repository
+in ``examples/new_components/``, including an example of
+overriding e.g. ``network.lopf()`` for functionality for
+combined-heat-and-power (CHP) plants.

doc/conf.py

@@ -55,17 +55,17 @@
 
 # General information about the project.
 project = u'PyPSA'
-copyright = u'2016-2017 Tom Brown (FIAS), Jonas Hoersch (FIAS), David Schlachtberger (FIAS)'
-author = u'Tom Brown (FIAS), Jonas Hoersch (FIAS), David Schlachtberger (FIAS)'
+copyright = u'2015-2019 Tom Brown (KIT, FIAS), Jonas Hoersch (KIT, FIAS), David Schlachtberger (FIAS)'
+author = u'Tom Brown (KIT, FIAS), Jonas Hoersch (KIT, FIAS), David Schlachtberger (FIAS)'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'0.11'
+version = u'0.13'
 # The full version, including alpha/beta/rc tags.
-release = u'0.11.0'
+release = u'0.13.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/design.rst

@@ -14,8 +14,8 @@ Python 3.5.
 Network object is the overall container
 =======================================
 
-The ``pypsa.components.Network`` is an overall container for all
-network components; components cannot exist without a network.
+The ``pypsa.Network`` is an overall container for all network
+components; components cannot exist without a network.
 
 It is also the object on which calculations, such as power flow and
 optimal power flow, are performed.
@@ -24,9 +24,8 @@ optimal power flow, are performed.
 Buses are the fundamental nodes
 ===============================
 
-The ``pypsa.components.Bus`` is the fundamental node to which all
-loads, generators, storage units, lines, transformers and links
-attach.
+The bus is the fundamental node to which all loads, generators,
+storage units, lines, transformers and links attach.
 
 You can have as many components attached to a bus as you want.