Merge pull request #262 from openego/release-0.7.1

Release 0.7.1

README.rst

@@ -17,34 +17,52 @@ energy storages. Grid expansion measures are not part of this tool and will be
 instead part of 'eGo' https://github.com/openego/eGo
 
 
-Setup
-=========================
+Installation
+============
+eTraGo is designed as a Python package therefore it is mandatory to have
+`Python 3 <https://www.python.org/downloads/.>`_ installed. If you have a
+working Python3 environment, use pypi to install the latest eTraGo version.
+We highly recommend you to use a virtual environment. Use following pip
+command in order to install eTraGo:
 
+.. code-block:: bash
 
-Create a virtualenvironment (where you like it) and activate it:
+  $ pip3 install eTraGo --process-dependency-links
 
-.. code-block::
+Installation for Developers
+===========================
 
-   $ virtualenv venv --clear -p python3.5
-   $ source venv/bin/activate
-   $ cd venv
-
-Clone the source code from github
+Clone the source code from github:
 
 .. code-block::
 
    $ git clone https://github.com/openego/eTraGo
 
+You can checkout to the dev branch and create new feature branches.
+For the correct work-flow, please mind the 
+`Dreissen Branching Model <https://nvie.com/posts/a-successful-git-branching-model/>`_
 
-With your activated environment `cd` to the cloned directory and run:
+Use the pip -e to install eTraGo directly from the cloned repository:
 
 .. code-block::
 
-   $ pip3 install -e eTraGo --process-dependency-links
+   $ pip3 install -e /path/to/eTraGo/ --process-dependency-links
+
+Using a virtual environment
+===========================
+
+Before installing eTraGo, 
+you create a virtual environment (where you like it) and activate it:
+
+.. code-block:: bash
+
+   $ virtualenv venv --clear -p python3.5
+   $ source venv/bin/activate
+   $ cd venv
 
+Inside your activated virtual environment you can 
+install eTraGo with the pip command, as previously explained.
 
-This will install all needed packages into your environment. Now you should be
-ready to go.
 
 Copyleft
 =========================

doc/api/etrago.cluster.rst

@@ -1,14 +1,6 @@
 etrago\.cluster package
 =======================
 
-Module contents
----------------
-
-.. automodule:: etrago.cluster
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 Submodules
 ----------
 
@@ -28,4 +20,11 @@ etrago\.cluster\.snapshot module
     :undoc-members:
     :show-inheritance:
 
+Module contents
+---------------
+
+.. automodule:: etrago.cluster
+    :members:
+    :undoc-members:
+    :show-inheritance:
 

doc/developer_notes.rst

@@ -18,20 +18,21 @@ Installation for Developers
    $ virtualenv --clear -p python3.5  etrago``
    $ cd etrago/
    $ source bin/activate
+   
+2. Clone the source code from github:
 
-2. Clone the source code from github
-
-.. code-block::
+.. code-block:: bash
 
    $ git clone https://github.com/openego/eTraGo
-   $ git checkout dev
 
-With your activated environment `cd` to the cloned directory and run:
+You can checkout to the dev branch and create new feature branches.
+For the correct work-flow, please mind the 
+`Dreissen Branching Model <https://nvie.com/posts/a-successful-git-branching-model/>`_
 
-.. code-block::
+3. Use the pip -e to install eTraGo directly from the cloned repository:
+
+.. code-block:: bash
 
-   $ pip3 install -e eTraGo/ --process-dependency-links
+   $ pip3 install -e /path/to/eTraGo/ --process-dependency-links
 
-This will install all needed packages into your environment.
-Now you should be ready to go.
 

doc/howToUse.rst

@@ -4,21 +4,43 @@ How to use eTraGo?
 ==================
 
 After you installed eTraGo you would typically start optimization runs by
-executing the ‘appl.py’ wich is situated in 
+executing the ‘appl.py’ which is situated in 
 ``./eTrago/etrago/`` (e.g by ``python3 appl.py``).
 
-The ‘appl.py’ is used as a simple user interface. Here
-parameters, calculation methods and scenario settings are set in a python
-dictionary called 'args'. It is crucial to understand these parameters.
-For example some of them contradict the usage of others. 
+eTraGo doesn't have a graphical user interface, 
+the ‘appl.py’ is used as a simple user interface which can be edited with 
+the preferred python-editor.
+Here parameters, calculation methods and scenario settings are set in a python
+dictionary called 'args'. 
+To run the desired calculation, it is crucial to understand these parameters. 
+In addition, some of them contradict the usage of others. 
 You find the documentation of all defined parameters from the 'args' here:
-:meth:`etrago.appl.etrago`.
+:func:`etrago.appl.etrago`.
 
-The appl.py contains the etrago(args) function which uses the
+Alternatively, the 'args' dictionary can be edited in a json-file.
+Then the path to the json-file has to be defined in the function
+:meth:`etrago.tools.utilities.get_args_setting`. Once a path is given
+and the get_args_setting() within the `'appl.py' <https://github.com/openego/eTraGo/blob/37a91c92fd9eafc31bd0679334c906ac571a2b18/etrago/appl.py#L144>`_
+is executed the 'args' dictionary within the 'appl.py' is ignored
+and replaced by the 'args' of the json-file.
+
+The appl.py contains the :func:`etrago.appl.etrago` function which uses the
 defined 'args' dictionary to start the desired calculation.
 
-Afterwards a PyPSA network will contain all results. You can use
-several plotting functions from the :meth:`etrago.tools.plot` in order
+To improve the performance of the optimization of the selected solver, 
+you might want to use solver options (part of 'args'). For gurobi
+the most used ones are described 
+`here <https://github.com/openego/eTraGo/issues/213>`_.
+
+Moreover, if you want to change parameters apart from the options which
+are provided by the 'args' you can change the default values of 
+the arguments used in the functions which are executed by the 
+:meth:`etrago.appl.etrago` function.
+Lastly, for more specific or extensive changes you are highly invited
+to write code and add new functionalities.
+
+Once the calculation has finished a PyPSA network will contain all results. 
+You can use several plotting functions from the :meth:`etrago.tools.plot` in order
 to visualize the results. For example 
 the :meth:`etrago.tools.plot.plot_line_loading` plots
 the relative line loading in % of all AC lines and DC links of the network.

doc/index.rst

@@ -11,8 +11,8 @@ Welcome to eTraGo's documentation!
    :align: right
    :scale: 80%
 
-.. warning:: Note, eTraGo and especially its documentation is still in
-             heavy development.
+.. warning:: Note, eTraGo and its documentation is in
+             continuous development.
 
 .. toctree::
    :maxdepth: 2

doc/installation.rst

@@ -13,18 +13,21 @@ command in order to install eTraGo:
 
 
 
-Using virtual environment
-=========================
+Using a virtual environment
+===========================
+
 
-Firstly, you create a virtual environment (where you like it) and activate it:
+Before installing eTraGo, 
+you create a virtual environment (where you like it) and activate it:
 
 .. code-block:: bash
 
    $ virtualenv venv --clear -p python3.5
    $ source venv/bin/activate
    $ cd venv
 
-Inside your virtual environment you can install eTraGo with the pip command.
+Inside your activated virtual environment you can 
+install eTraGo with the pip command, as previously explained.
 
 Linux and Ubuntu
 ================
@@ -61,13 +64,34 @@ environments.
 
 Setup database connection
 =========================
-The package ``ego.io`` gives you a python SQL-Alchemy representations of
-the _OpenEnergy-Database_  (oedb) and access to it by using the
-`oedialect <https://github.com/openego/oedialect>`_ a SQL-Alchemy binding
-Python package for the REST-API used by the OpenEnergy Platform (OEP). Your API
-access / login data will be saved in the folder ``.egoio`` in the file
-``config.ini``. You can create a new account on
-`openenergy-platform.org/login <http://openenergy-platform.org/login/>`_.
+The package `ego.io <https://github.com/openego/ego.io>`_ will be installed
+automatically when eTraGo is installed. The ``egoio``
+gives you python SQL-Alchemy representations of
+the `OpenEnergy-Database(oedb) <https://openenergy-platform.org/dataedit/>`_ 
+and access to it by using the
+`oedialect <https://github.com/openego/oedialect>`_, which is a SQL-Alchemy binding
+Python package for the REST-API used by the OpenEnergy Platform (OEP).
+
+In order to connect eTraGo via the oedialect with the oedb you
+have to create an account at
+`openenergy-platform.org/login <http://openenergy-platform.org/login/>`_. 
+You can name the `'db' <https://github.com/openego/eTraGo/blob/42a8629e966c866af2d228d49fb7234a6cc38cfe/etrago/appl.py#L105>`_
+argument of the 'args' of the :func:`etrago.appl.etrago`
+as you wish. Once the :func:`etrago.appl.etrago` is executed you will be asked 
+to enter how you want to connect to which database. If you want to use 
+the oedialect enter the following connection parameter. For <username> and
+<token> you have to take your credentials which you obtained by registering
+at `openenergy-platform.org/login <http://openenergy-platform.org/login/>`_.
+
+Your API access / login data will be saved in the folder ``.egoio`` in the file
+``config.ini``. Consequently, in the config.ini you can also change 
+your connection parameters or add new ones.
+In the following you can see how the config.ini looks like when you use the
+oedialect, a local postgresql database or the old psycopg2 developer connection.
+
+Once you have created a connection (which is saved in the config.ini) you do not have
+to enter the connection parameter again. The software will take the connection parameter
+which corresponds to the entry at the `'db' <https://github.com/openego/eTraGo/blob/42a8629e966c866af2d228d49fb7234a6cc38cfe/etrago/appl.py#L105>`_ argument.
 
 
 oedialect connection

doc/theoretical_background.rst

@@ -110,7 +110,7 @@ optimization problem, whereby the possible extension is unlimited. With respect
 to the different voltage levels and lengths MVA-specific costs are considered
 in the linear optimization of the power flow. Besides, several planned grid
 expansion scenarios from the German grid development plan can be considered as
-possible additional power lines.
+possible additional power lines by using the 'scn_extension' argument.
 
 
 Miscellaneous Features
@@ -122,9 +122,11 @@ marginal costs of each generator in order to prevent an optima plateau. The
 specific solver options depend on the applied solver like for example Gurobi,
 CPLEX or GLPK. Considering reproducibility, the 'load_cluster' argument
 enables to load a former calculated clustered network. Besides,
-'line_grouping' provides a grouping of lines which connect the same buses and
-the 'branch_capacity_factor' adds a factor to adapt all line capacities. The
-'load_shedding' argument is used for debugging complex grids in order to avoid
+'line_grouping' provides a grouping of lines which connect the same buses.
+The 'branch_capacity_factor' adds a factor to adapt all line capacities in order
+to consider (n-1) security. Because the average number of HV systems is much
+smaller than the one of eHV lines, you can choose factors for 'HV' and 'eHV'.
+The 'load_shedding' argument is used for debugging complex grids in order to avoid
 infeasibilities. It introduces a very expensive generator at each bus to meet 
 the demand. When optimizing storage units and grid expansion without limiting
 constraints, the need for load shedding should not be existent. The

doc/whatsnew.rst

@@ -8,6 +8,7 @@ These are new features and improvements of note in each release.
     :local:
     :backlinks: top
 
+.. include:: whatsnew/v0_7_1.rst
 .. include:: whatsnew/v0_7_0.rst
 .. include:: whatsnew/v0_6_1.rst
 .. include:: whatsnew/v0_6.rst

doc/whatsnew/v0_7_1.rst

@@ -0,0 +1,18 @@
+Release 0.7.1 (October 25, 2018)
+++++++++++++++++++++++++++++
+A minor release adding new options for additional constraints, modelling assumptions and plotting.
+
+Added features
+--------------
+
+* Two extra functionalities were introduced in order to apply constraints concerning a minimal share of renewable energy and a global upper bound for grid expansion. You can activate these functions in the 'args' of the etrago() function.
+* The branch_capacity_factor can now be defined separately for the high and extra high voltage level in order to address the (n-1) criteria more accurately.
+* There are some more plotting functions e.g. plotting the state-of-charge and dispatch of storage units.
+* Storage capacities in foreign countries can easily be be optimized.
+* By default the maximum expansion of each line and transformer is set to four times its original capacity. Being an argument of the extendable() function it can be easily adjusted.
+* k-means clustered results can now also be exported to the oedb.
+
+
+
+
+