add numpydoc to setup and readthedocs.yml and improve documentation text

.readthedocs.yml

@@ -0,0 +1,9 @@
+version: 2
+
+python:
+ version: 3.5
+ install:
+ - method: pip
+ path: .
+ extra_requirements:
+ - docs

doc/components.rst

@@ -56,7 +56,6 @@ has the major functions as methods, such as ``network.lopf()`` and
  :file: ../pypsa/component_attrs/networks.csv
 
 
-
 Sub-Network
 ===========
 
@@ -118,7 +117,7 @@ table, the canonical example being CO2 emissions of the carrier
 relevant for limits on CO2 emissions.
 
 
-(NB: In versions of PyPSA < 0.6.0, this was called Source.)
+.. note:: In versions of PyPSA < 0.6.0, this was called Source.
 
 
 .. csv-table::
@@ -145,8 +144,7 @@ after conversion), "generation capacity" (for limits on total capacity
 expansion of given carriers) and "transmission capacity" (for limits
 on the total expansion of lines and links).
 
-Global constraints were added in PyPSA 0.10.0 and replace the ad hoc
-``network.co2_limit`` attribute.
+.. note:: Global constraints were added in PyPSA 0.10.0 and replace the ad hoc ``network.co2_limit`` attribute.
 
 
 .. csv-table::
@@ -422,12 +420,7 @@ power flow: a bidirectional point-to-point HVDC link, a unidirectional
 lossy HVDC link, a converter between an AC and a DC network, a heat
 pump or resistive heater from an AC/DC bus to a heat bus, etc.
 
-NB: ``Link`` has replaced the ``Converter`` component for linking AC
-with DC buses and the ``TransportLink`` component for providing
-controllable flows between AC buses. If you want to replace
-``Converter`` and ``TransportLink`` components in your old code, use
-the ``Link`` with ``efficiency = 1``, ``marginal_cost = 0``,
-``p_min_pu = -1``, ``p_max_pu = 1`` and ``p_nom* = s_nom*``.
+.. note:: ``Link`` has replaced the ``Converter`` component for linking AC with DC buses and the ``TransportLink`` component for providing controllable flows between AC buses. If you want to replace ``Converter`` and ``TransportLink`` components in your old code, use the ``Link`` with ``efficiency = 1``, ``marginal_cost = 0``, ``p_min_pu = -1``, ``p_max_pu = 1`` and ``p_nom* = s_nom*``.
 
 .. csv-table::
  :header-rows: 1

doc/conf.py

@@ -31,6 +31,7 @@
 # ones.
 extensions = [
  'sphinx.ext.autodoc',
+ 'sphinx.ext.autosummary',
  'sphinx.ext.intersphinx',
  'sphinx.ext.todo',
  'sphinx.ext.mathjax',

doc/design.rst

@@ -166,7 +166,69 @@ Per unit values of voltage and impedance are used internally for
 network calculations. It is assumed internally that the base power is
 1 MVA. The base voltage depends on the component.
 
-See also :ref:`unit-conventions`.
+.. _unit-conventions:
+
+Unit Conventions
+=================
+
+The units for physical quantities are chosen for easy user input.
+
+The units follow the general rules:
+
+Power: MW/MVA/MVar (unless per unit of nominal power,
+e.g. generator.p_max_pu for variable generators is per unit of
+generator.p_nom)
+
+Time: h
+
+Energy: MWh
+
+Voltage: kV phase-phase for bus.v_nom; per unit for v_mag_pu, v_mag_pu_set, v_mag_pu_min etc.
+
+Angles: radians, except transformer.phase_shift which is in degrees for easy input
+
+Impedance: Ohm, except transformers which are pu, using transformer.s_nom for the base power
+
+CO2-equivalent emissions: tonnes of CO2-equivalent per MWh_thermal of energy carrier
+
+
+Sign Conventions
+================
+
+
+The sign convention in PyPSA follows other major software packages,
+such as MATPOWER, PYPOWER and DIgSILENT PowerFactory.
+
+* The power (p,q) of generators or storage units is positive if the
+ asset is injecting power into the bus, negative if withdrawing power
+ from bus.
+* The power (p,q) of loads is positive if withdrawing power from bus, negative if injecting power into bus.
+* The power (p0,q0) at bus0 of a branch is positive if the branch is
+ withdrawing power from bus0, i.e. bus0 is injecting into branch
+* Similarly the power (p1,q1) at bus1 of a branch is positive if the
+ branch is withdrawing power from bus1, negative if the branch is
+ injecting into bus1
+* If p0 > 0 and p1 < 0 for a branch then active power flows from bus0
+ to bus1; p0+p1 > 0 is the active power losses for this direction of
+ power flow.
+
+AC/DC Terminology
+=================
+
+AC stands for Alternating Current and DC stands for Direct Current.
+
+Some people refer to the linearised power flow equations for AC
+networks as "DC load flow" for historical reasons, but we find this
+confusing when there are actual direct current elements in the network
+(which also have a linearised power flow, which would then be DC DC load
+flow).
+
+Therefore for us AC means AC and DC means DC. We distinguish between
+the full non-linear network equations (with no approximations) and the
+linearised network equations (with certain approximations to make the
+equations linear).
+
+All equations are listed in the section :doc:`power_flow`.
 
 
 Set points are stored separately from actual dispatch points

doc/import_export.rst

@@ -18,7 +18,7 @@ Then run ``network.import_from_csv_folder(csv_folder_name)``.
 
 .. autofunction:: pypsa.io.import_from_csv_folder
 
-Note that is is NOT necessary to add every single column, only those where values differ from the defaults listed in :doc:`components`. All empty values/columns are filled with the defaults.
+.. note:: Note that is is NOT necessary to add every single column, only those where values differ from the defaults listed in :doc:`components`. All empty values/columns are filled with the defaults.
 
 
 .. _export-csv:

doc/index.rst

@@ -6,7 +6,32 @@
 Welcome to PyPSA's documentation!
 =================================
 
-Contents:
+PyPSA stands for "Python for Power System Analysis". It is pronounced "pipes-ah".
+
+PyPSA is a `free software
+<https://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, 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 <https://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 <https://condynet.de/>`_, financed by the
+`German Federal Ministry for Education and Research (BMBF) <https://www.bmbf.de/en/index.html>`_ as part of the `Stromnetze Research Initiative <https://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/>`_.
+
+
+Contents
+========
 
 .. toctree::
  :maxdepth: 2
@@ -17,12 +42,12 @@ Contents:
  quick_start
  design
  components
+ network_methods
  import_export
  power_flow
  optimal_power_flow
  contingency_analysis
  plotting
- conventions
  examples
  troubleshooting
  unit_testing

doc/installation.rst

@@ -41,6 +41,12 @@ and there are similar packages for other GNU/Linux distributions.
 For Windows there is `WinGLPK <https://winglpk.sourceforge.net/>`_. For
 Mac OS X `brew <https://brew.sh/>`_ is your friend.
 
+Installing PyPSA with conda
+===========================
+
+If you are using ``conda`` you can simply install PyPSA with::
+
+ conda install pypsa
 
 Installing PyPSA with pip
 =========================
@@ -53,7 +59,8 @@ If you're feeling adventurous, you can also install the latest master branch fro
 
  pip install git+https://github.com/PyPSA/PyPSA.git
 
-"Manual" installation with setuptools
+
+Manual installation with setuptools
 =====================================
 
 PyPSA relies on the following packages which are not contained in a
@@ -64,6 +71,7 @@ standard Python installation:
 * pandas
 * networkx
 * pyomo
+* cartopy
 
 It is recommended to use PyPSA with the following additional packages:
 
@@ -110,7 +118,7 @@ Upgrade all packages to the latest versions
 ===========================================
 
 PyPSA is only tested with the latest stable versions of all the
-dependent packages (pandas, pyomo, networkx, etc.). Therefore it is
+dependent packages. Therefore it is
 very important that you upgrade these packages; otherwise PyPSA may
 not work.
 

doc/introduction.rst

@@ -181,7 +181,7 @@ It leans heavily on the following Python packages:
 
 The optimisation uses pyomo so that it is independent of the preferred
 solver. You can use e.g. the free solver `GLPK <https://www.gnu.org/software/glpk/>`_ or the commercial
-solver `Gurobi <https://www.gurobi.com/>`_) for which free academic licenses are available.
+solver `Gurobi <https://www.gurobi.com/>`_ for which free academic licenses are available.
 
 The time-expensive calculations, such as solving sparse linear
 equations, are carried out using the `scipy.sparse <https://docs.scipy.org/doc/scipy/reference/sparse.html>`_ libraries.

doc/network_methods.rst

@@ -0,0 +1,16 @@
+######################
+Network Methods
+######################
+
+Network
+-------
+
+.. autoclass:: pypsa.Network
+ :members:
+
+
+Sub-Network
+-----------
+
+.. autoclass:: pypsa.SubNetwork
+ :members: