Merge branch 'master' of github.com:FRESNA/PyPSA

LICENSE.txt

@@ -1,5 +1,5 @@
 
-Copyright 2015 Tom Brown (FIAS),....
+Copyright 2015-2016 Tom Brown (FIAS), Jonas Hörsch (FIAS)
 
 This program is free software: you can redistribute it and/or
 modify it under the terms of the GNU General Public License as

README.rst

@@ -4,32 +4,99 @@ Python for Power Systems Analysis
 =================================
 
 
-For load-flow and optimal power flow.
+PyPSA stands for "Python for Power System Analysis".
 
-In future: also dynamical stability.
+PyPSA is a `free software
+<http://www.gnu.org/philosophy/free-sw.en.html>`_ toolbox for
+simulating and optimising modern electric power systems that include
+features such as variable wind and solar generation, storage units and
+mixed alternating and direct current networks.
 
+Documentation can be found in `sphinx
+<http://www.sphinx-doc.org/en/stable/>`_ reStructuredText format in
+`doc <doc/>`_ and as a `website <http://nworbmot.org/energy/pypsa-doc/>`_.
 
-Documentation
--------------
 
-Can be found in pypsa/doc (which uses sphinx), which is also `on the
-web <http://nworbmot.org/energy/pypsa-doc/>`_.
+As of 2016 PyPSA is under heavy development and therefore it
+is recommended to use caution when using it in a production
+environment. Some APIs may change - those liable to be updated are
+listed in the doc/todo.rst.
 
+PyPSA was initially developed by the `Renewable Energy Group
+<https://fias.uni-frankfurt.de/physics/schramm/complex-renewable-energy-networks/>`_
+at `FIAS <https://fias.uni-frankfurt.de/>`_ to carry out simulations
+for the `CoNDyNet project <http://condynet.de/>`_, financed by the
+German Federal Ministry for Education and Research (BMBF).
 
-Licence (GPL3)
---------------
 
-Copyright 2015 Tom Brown (FIAS), Jonas H
+What PyPSA does and does not do (yet)
+=======================================
 
-This program is free software: you can redistribute it and/or
-modify it under the terms of the GNU General Public License as
-published by the Free Software Foundation; either version 3 of the
-License, or (at your option) any later version.
+PyPSA can calculate:
 
-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 for more details.
+* static power flow (using both the full non-linear network equations and
+  the linearised network equations)
+* linear optimal power flow (over several snapshots simultaneously for
+  optimisation of generation and storage dispatch and the capacities
+  of generation, storage and transmission)
 
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see http://www.gnu.org/licenses/ .
+It has models for:
+
+* meshed multiply-connected AC and DC networks, with controllable
+  converters between AC and DC networks
+* conventional dispatchable generators
+* generators with time-varying power availability, such as
+  wind and solar generators
+* storage units with efficiency losses
+
+
+
+Functionality that will definitely by added soon (see also :doc:`todo`):
+
+* Graphical plotting of networks with power flow
+* Better modelling of hydroelectricity
+* 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
+
+Functionality that may be added in the future:
+
+* Unit Commitment using MILP
+* Short-circuit current calculations
+* Dynamic RMS simulations
+* Small signal stability analysis
+* Interactive web-based GUI
+* AC OPF
+* Dynamic EMT simulations
+* Unbalanced load flow
+
+
+
+What PyPSA uses under the hood
+===============================
+
+PyPSA is written and tested with Python 2, but has included Python 3
+forward-compatibility (for e.g. printing and integer division) so that
+minimal effort should be required to run it in Python 3.
+
+It leans heavily on the following Python packages:
+
+* `pandas <http://ipython.org/>`_ for storing data about components and time series
+* numpy and `scipy <http://scipy.org/>`_ for calculations, such as
+  linear algebra and sparse matrix calculations
+* `pyomo <http://www.pyomo.org/>`_ for preparing optimisation problems (currently only linear)
+* networkx for some network calculations (such as discovering connected networks)
+* py.test for unit testing
+
+The optimisation uses pyomo so that it is independent of the preferred
+solver (you can use e.g. the free software GLPK or the commercial
+software Gurobi).
+
+The time-expensive calculations, such as solving sparse linear
+equations, are carried out using the scipy.sparse libraries.
+
+Licence
+==========
+
+PyPSA is released as free software under the `GPLv3
+<http://www.gnu.org/licenses/gpl-3.0.en.html>`_, see `LICENSE.txt
+<LICENSE.txt>`_..

components.py

@@ -210,7 +210,7 @@ class StorageUnit(Generator):
     state_of_charge_initial = Float()
     state_of_charge = Series(default=np.nan)
 
-    #maximum capacity in terms of hours at full output capacity p_nom
+    #maximum state of charge capacity in terms of hours at full output capacity p_nom
     max_hours = Float(1)
 
     #in MW

doc/components.rst

@@ -20,51 +20,120 @@ Sub-Network are determined by calling:
 
 network.determine_network_topology()
 
+
+
 Bus
 =======
 
 Fundamental electrical node of system.
 
+
+One-Ports: Generators, Storage Units, Loads, Shunt Impedances
+============================================================
+
+These components share the property that they all connect to a single
+bus.
+
+They have attributes:
+
+
++------------+------------+-----------+---------------------------------------+
+| Name       | Type       | Unit      |Description                            |
++============+============+===========+=======================================+
+|    bus     |   string   |           |name of bus                            |
+|            |            |           |to which                               |
+|            |            |           |one-port is                            |
+|            |            |           |attached                               |
+|            |            |           |                                       |
++------------+------------+-----------+---------------------------------------+
+|  p         |series      |MW         | active power (as calculated by PyPSA) |
++------------+------------+-----------+---------------------------------------+
+| q          |series      |MVar       |reactive power (as calculated by PyPSA |
++------------+------------+-----------+---------------------------------------+
+
+
+
 Generator
-============
+---------
+
+Can have generator.dispatch in ["variable","flexible"], which dictates
+how they behave in the OPF.
+
+"flexible" generators can dispatch
+anywhere between gen.p_nom*(gen.p_nom_min_pu_fixed) and
+gen.p_nom*(gen.p_nom_max_pu_fixed) at all times.
+
+"variable" generators have time series gen.p_max_pu which dictates the
+active power availability for each snapshot.
+
+
+
+
++------------+------------+-----------+---------------------------------------+
+| Name       | Type       | Unit      |Description                            |
++============+============+===========+=======================================+
+| dispatch   |   string   |must be    |Controllability of active power        |
+|            |            |"flexible" |dispatch                               |
+|            |            |or         |                                       |
+|            |            |"variable" |                                       |
+|            |            |           |                                       |
++------------+------------+-----------+---------------------------------------+
+| control    |string      |must be    |        P,Q,V control strategy         |
+|            |            |"PQ", "PV" |                                       |
+|            |            |or "Slack" |                                       |
++------------+------------+-----------+---------------------------------------+
+| p_set      |series      |MW         |active power set point (for PF)        |
+|            |            |           |                                       |
++------------+------------+-----------+---------------------------------------+
+| q_set      |series      |MVar       |reactive power set point (for PF)      |
+|            |            |           |                                       |
++------------+------------+-----------+---------------------------------------+
+
 
-Can have  generator.dispatch in ["variable","flexible"]
 
 Storage Unit
-============
+------------
 
 Has a time-varying state of charge and various efficiencies.
 
 Load
-======
+-----
 
 PQ load.
 
 Shunt Impedance
-======
+---------------
 
 Has voltage-dependent admittance.
 
 
+Branches: Lines, Transformers, Converters, Transport Links
+===========================================================
+
+Have bus0 and bus1 to which they attached.
+
+Power flow at bus recorded in p0, p1, q0, q1.
+
+
 
 Line
-=====
+------
 
 A transmission line connected line.bus0 to line.bus1. Can be DC or AC.
 
 
 Transformer
-==========
+------------
 
 Converts from one AC voltage level to another.
 
 Converter
-==========
+----------
 
 Converts AC to DC power.
 
 Transport Link
-==============
+--------------
 
 Like a controllable point-to-point HVDC connector; equivalent to
 converter-(DC line)-converter.

doc/optimal_power_flow.rst

@@ -8,11 +8,17 @@ See pypsa.opf.
 Linear Optimal Power Flow
 =========================
 
-network.lopf(snapshots)
+network.lopf(snapshots,solver_name)
+
+where snapshots is an iterable of snapshots and solver_name is a
+string, e.g. "gurobi" or "glpk".
 
 The linear OPF module can optimises the dispatch of generation and storage
 and the capacities of generation, storage and transmission.
 
+The optimisation currently uses continuous variables. MILP unit commitment may be
+added in the future.
+
 The objective function is the total system cost for the snapshots
 optimised.
 
@@ -24,14 +30,23 @@ Each transmission asset has a capital cost.
 Each generation and storage asset has a capital cost and a marginal cost.
 
 
+WARNING: If the transmission capacity is changed in passive networks,
+then the impedance will also change (i.e. if parallel lines are
+installed). This is NOT reflected in the LOPF, so the network
+equations may no longer be valid. Note also that all the expansion is
+continuous.
+
+
 Optimising dispatch only: a market model
 ----------------------------------------
 
 Capacity optimisation can be turned off so that only the dispatch is
-optimised, like an electricity market model. For simplified
-transmission representation using NTCs, there is a TransportLink
-component which does controllable power flow like a transport model
-(and can also represent a point-to-point HVDC link).
+optimised, like an electricity market model.
+
+For simplified transmission representation using Net Transfer
+Capacities (NTCs), there is a TransportLink component which does
+controllable power flow like a transport model (and can also represent
+a point-to-point HVDC link).
 
 
 
@@ -40,8 +55,8 @@ Optimising total annual system costs
 
 To minimise annual system costs for meeting an inelastic electrical
 load, capital costs for transmission and generation should be set to
-the discounted annualised investment costs in e.g. EUR/MW/a, marginal
-costs for dispatch to e.g. EUR/MWh and the weightings chosen such that
+the annualised investment costs in e.g. EUR/MW/a, marginal costs for
+dispatch to e.g. EUR/MWh and the weightings chosen such that
 
 
 .. math::