Merge pull request #73 from openego/dev

Release merge

.gitignore

@@ -8,4 +8,5 @@ ego/scenario_setting.json
 ego/noise_values.csv
 .idea/
 noise_values.csv
-
+*.pkl
+.ipynb_checkpoints

MANIFEST.in

@@ -0,0 +1,10 @@
+include README.rst
+include LICENSE
+include *txt
+include MANIFEST.in
+include *.json
+include *.rst
+include *.csv
+include ego/scenario_setting.json
+include ego/data/*.csv
+include ego/tools/*.json

README.rst

@@ -1,15 +1,22 @@
-.. image:: https://readthedocs.org/projects/openego/badge/?version=latest
-    :target: http://openego.readthedocs.io/en/latest/?badge=latest
-    :alt: Documentation Status
+|readthedocs| |badge_githubstars|
+
 
 .. image:: https://openegoproject.files.wordpress.com/2017/02/open_ego_logo_breit.png?w=400
+   :align: right
+   :scale: 100%
 
-eGo
-======
+*A cross-grid-level electricity grid and storage optimization tool*
+| `openegoproject.wordpress.com <https://openegoproject.wordpress.com/>`_
 
-Integrated optimization of flexibility options and grid extension measures for power grids based on eTraGo and eDisGo.
 
-A speciality in this context is that transmission grids are described by the 380, 220 and 110 kV in Germany. The integration of the transmission grid (via eTraGo) and distribution grid (via eDisGo) is part of eGo.
+eGo
+===
+
+Integrated optimization of flexibility options and grid extension measures
+for power grids based on `eTraGo <http://eTraGo.readthedocs.io/>`_ and
+`eDisGo <http://edisgo.readthedocs.io/>`_. The Documentation of the eGo tool 
+can be found on 
+`openego.readthedocs.io <https://openego.readthedocs.io/en/dev/>`_ .
 
 .. contents::
 
@@ -20,15 +27,39 @@ Create a virtualenvironment (where you like it) and activate it:
 
 .. code-block::
 
-   $ virtualenv eGo --clear -p python3.5
+   $ virtualenv venv --clear -p python3.5
    $ source venv/bin/activate
+   $ cd venv
+   $ pip3 install -e git+https://github.com/openego/eGo@dev#egg=eGo --process-dependency-links
+
 
-   $ pip3 install -e git+https://github.com/openego/eGo@dev#egg=eGo --process-dependency-links --allow-all-external
+LICENSE
+=======
+© Europa-Universität Flensburg,
+© Flensburg University of Applied Sciences,
+  Centre for Sustainable Energy Systems
+© DLR Institute for Networked Energy Systems,
+© Reiner-Lemoine-Institute"
 
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
 
-Copyleft
-========
+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 Affero General Public License for more
+details.
 
-Code licensed under "GNU Affero General Public License Version 3 (AGPL-3.0)"
-It is a collaborative work with several copyright owner:
-Cite as "eGo" © Flensburg University of Applied Sciences, Centre for Sustainable Energy Systems © Europa-Universität Flensburg, Centre for Sustainable Energy Systems © DLR Institute for Networked Energy Systems, © Reiner-Lemoine-Institute"
+You should have received a copy of the GNU General Public License along with
+this program. If not, see https://www.gnu.org/licenses/.
+
+
+
+.. |badge_githubstars| image:: https://img.shields.io/github/stars/openego/eGo.svg?style=flat-square&label=github%20stars
+    :target: https://github.com/openego/eGo/
+    :alt: GitHub stars
+
+.. |readthedocs| image:: https://readthedocs.org/projects/openego/badge/?version=latest
+    :target: http://openego.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status

doc/_static/ribbons.html

@@ -0,0 +1 @@
+<a href="https://github.com/openego/eGo" class="github-corner" aria-label="View source on Github"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#64CEAA; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path></svg></a><style>.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}</style>

doc/api.rst

@@ -1,8 +1,8 @@
 .. make doc-string generated documentation appear here
 
 .. toctree::
-   :maxdepth: 7
+   :maxdepth: 4
    :glob:
-   :titlesonly:
+
 
    API <api/modules>

doc/api/ego.tools.rst

@@ -4,24 +4,40 @@ ego\.tools package
 Submodules
 ----------
 
-ego\.tools\.economics module
-----------------------------
+ego\.tools\.economics
+---------------------
 
 .. automodule:: ego.tools.economics
     :members:
     :undoc-members:
     :show-inheritance:
 
-ego\.tools\.io module
----------------------
+ego\.tools\.edisgo_integration
+------------------------------
+
+.. automodule:: ego.tools.edisgo_integration
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+ego\.tools\.io
+--------------
 
 .. automodule:: ego.tools.io
     :members:
     :undoc-members:
     :show-inheritance:
 
-ego\.tools\.plots module
-------------------------
+ego\.tools\.mv_cluster
+----------------------
+
+.. automodule:: ego.tools.mv_cluster
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+ego\.tools\.plots
+-----------------
 
 .. automodule:: ego.tools.plots
     :members:
@@ -34,8 +50,8 @@ ego\.tools\.results
 .. automodule:: ego.tools.results
     :members:
     :undoc-members:
-    :show-inheritance:        
-    
+    :show-inheritance:
+
 
 ego\.tools\.specs
 -----------------
@@ -45,12 +61,18 @@ ego\.tools\.specs
     :undoc-members:
     :show-inheritance:
 
-ego\.tools\.utilities module
-----------------------------
+ego\.tools\.storages
+--------------------
 
-.. automodule:: ego.tools.utilities
+.. automodule:: ego.tools.storages
     :members:
     :undoc-members:
     :show-inheritance:
 
+ego\.tools\.utilities
+---------------------
 
+.. automodule:: ego.tools.utilities
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/api/modules.rst

@@ -1,7 +1,93 @@
+===
 ego
 ===
 
+
+
+Overview of modules
+===================
+
+
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 7
+
+   ego.tools
+
+scenario_settings.json
+======================
+
+With the ``scenario_settings.json`` file you set up your calcualtion. 
+The file can be found on 
+`github <https://github.com/openego/eGo/blob/master/ego/scenario_setting.json>`_.
+
+.. json:object:: scenario_setting.json
+
+   This file contains all input settings for the eGo tool.
+
+   :property global: Global settings that are valid for both eTraGo and eDisGo
+   :proptype global: :json:object:`global`
+   :property eTraGo: eTraGo settings, only valid for eTraGo run
+   :proptype eTraGo: :json:object:`eTraGo`
+   :property eDisGo: eDisGo settings, only valid for eDisGo runs
+   :proptype eDisGo: :json:object:`eDisGo`
+
+
+.. json:object:: global
+   
+   :property bool eTraGo: Decide if you want to run the eTraGo tool (HV/EHV grid optimization).
+   :property bool eDisGo: Decide if you want to run the eDisGo tool (MV grid optimiztaion).
+   :property string db: Name of your database (e.g.``''oedb''``).
+   :property bool recover: If ``true``, (previously calculated) eTraGo results are queried from your database (instead of performing a new run).
+   :property int result_id: ID of the (previeously calculated) eTraGo results that are queried if **recover** is set ``true``.
+   :property string gridversion: Version of the *open_eGo* input data-sets (e.g. ``''v0.4.2''``) 
+
 
-   ego
+.. json:object:: eTraGo
+
+   This section of :json:object:`scenario_setting.json` contains all input parameters for the eTraGo tool. A description of the parameters can be found `here. <https://etrago.readthedocs.io/en/dev/api/etrago.html#module-etrago.appl>`_
+
+   Please note that some parameters are already included in :json:object:`global`
+
+
+.. json:object:: eDisGo
+
+   This section of :json:object:`scenario_setting.json` contains all input parameters for the eDisGo tool and the Clustering of MV grids.
+
+   :property string ding0_files: Relative path to the MV grid files (created by `ding0 <https://readthedocs.org/projects/dingo/>`_) (e.g. ``''data/MV_grids/20180713110719''``)
+   :property string choice_mode: Mode that eGo uses to chose MV grids out of the files in **ding0_files** (e.g. ``''manual''``, ``''cluster''`` or ``''all''``). If ``''manual''`` is chosen, the parameter **manual_grids** must contain a list of the desired grids. If ``''cluster''`` is chosen, **no_grids** must specify the desired number of clusters. If ``''all''`` is chosen, all MV grids from **ding0_files** are calculated.
+   :property list manual_grids: List of MV grid ID's (*open_eGo* HV/MV substation ID's)
+   :property int no_grids: Number of MV grid clusters (from all files in **ding0_files**, a specified number of representative clusters is calculated)
+
+
+
+ego_main.py
+===========
+
+This is the application file for the tool eGo. The application eGo calculates
+the distribution and transmission grids of eTraGo and eDisGo.
+
+.. note:: Note, the data source of eGo relies on
+          the Open Energy Database. - The registration for the public
+          accessible API can be found on
+          `openenergy-platform.org/login <http://openenergy-platform.org/login/>`_.
+
+Run the ``ego_main.py`` file with:
+
+.. code-block:: bash
+
+   >>> python3 ego_main.py
+   >>> ...
+   >>> INFO:ego:Start calculation
+   >>> ...
+
+The eGo App works like:
+
+.. code-block:: python
+
+  >>> from ego.tools.io import eGo
+  >>> ego = eGo(jsonpath='scenario_setting.json')
+  >>> ego.etrago_line_loading()
+  >>> print(ego.etrago.storage_costs)
+  >>> ...
+  >>> INFO:ego:Start calculation
+  >>> ...