Merge pull request #240 from openego/dev

Release 0.7.0

MANIFEST.in

@@ -3,3 +3,4 @@ include LICENSE
 include MANIFEST.in
 include etrago/tools/*.json
 include *.txt
+include etrago/*.json

doc/about.rst

@@ -2,15 +2,17 @@
 About eTraGo
 ============
 
-Optimization of flexibility options for transmission grids based on PyPSA.
+eTraGo stands for **e**\lectric **Tra**\nsmission **G**\rid **o**\ptimization.
 
-A speciality in this context is that transmission grids are described by the
-380, 220 and 110 kV in Germany. Conventionally the 110kV grid is part of the
-distribution grid. The integration of the transmission and 'upper' distribution
-grid is part of eTraGo.
+The python package eTraGo provides optimization strategies of flexibility options 
+for transmission grids based on PyPSA. A peculiarity in this context is that 
+the German transmission grid is described by the 380, 220 and 110 kV voltage levels. 
+Conventionally the 110kV grid is part of the distribution grid. The integration of 
+the transmission and ‘upper’ distribution grid is part of eTraGo.
 
 The focus of optimization are flexibility options with a special focus on
-energy storages and grid expansion measures.
+energy storage and grid expansion measures.
+
 
 
 The open_eGo project
@@ -21,11 +23,76 @@ This software project is part of the research project
 
 The OpenEnergy Platform
 =======================
-With in this project we developted the OpenEnergy Platform which this software
+Within this project we developed the OpenEnergy Platform which this software
 is using in order to get and store the in- and output data. Before you start to
-calculate a registration on the platform is needed. For more see
+calculate a registration on the platform is needed. For more information see
 `openenergy-platform <https://openenergy-platform.org/>`_ and login.
 
+The OpenEnergy platform mainly addresses students, researchers and scientists in 
+the field of energy modelling and analytics as well as interested persons in 
+those fields. The platform provides great tools to make your energy system 
+modelling process transparent. All data of the open_eGo project are stored at
+this platform. 
+`Learn more about the database access <https://oep-data-interface.readthedocs.io>`_.
+
+
+
+
+
+Model overview
+==============
+
+
+
+.. figure:: images/eTraGo_model.png
+   :align: center
+   :scale: 75%
+
+
+eDisGo
+======
+The python package eDisGo provides a toolbox for analysis and optimization
+of distribution grids. It is closely related to the python project Ding0 as this
+project is currently the single data source for eDisGo providing synthetic
+grid data for whole Germany. `Learn more here <http://edisgo.readthedocs.io/>`_.
+
+
+eGo
+===
+
+The python package eGo is a toolbox and application which connects the tool eTraGo
+(optimization of flexibility options at transmission grid level)
+and eDisGo (optimization of distribution grids). All those python
+packages are part of the research project 
+`open_eGo <https://openegoproject.wordpress.com>`_. 
+`Learn more here <http://openego.readthedocs.io/>`_.
+
+
+Dataprocessing
+==============
+
+For the open_eGo project several python packages are developed which are feeded 
+by the input data of the data processing. The Dataprocessing is writen in 
+SQL and Python. `Learn more here <https://data-processing.readthedocs.io/>`_.
+
+ego.io
+======
+
+The ego.io serves as a SQLAlchemy Interface to the OpenEnergy database (oedb). The 
+oedb table ORM objects are defined here and small helpers for io tasks are contained.
+`Learn more here <https://github.com/openego/ego.io>`_.
+
+
+Dingo
+=====
+
+The DIstribution Network GeneratOr (Ding0) is a tool to generate synthetic 
+medium and low voltage power distribution grids based on open 
+(or at least accessible) data. 
+`Learn more here <https://dingo.readthedocs.io/>`_.
+
+
+
 
 LICENSE
 =======

doc/developer_notes.rst

@@ -7,9 +7,19 @@ Developer notes
 Installation for Developers
 ===========================
 
-The best way is to use a virtual environment. see:
 
-Step 2) Clone the source code from github
+.. note::
+      Installation is primarly tested on (Ubuntu like) linux OS.
+
+1. If you like, create a virtual environment (where you like it) and activate it (if you do not use venv start with 2.):
+
+.. code-block:: bash
+
+   $ virtualenv --clear -p python3.5  etrago``
+   $ cd etrago/
+   $ source bin/activate
+
+2. Clone the source code from github
 
 .. code-block::
 
@@ -25,28 +35,3 @@ With your activated environment `cd` to the cloned directory and run:
 This will install all needed packages into your environment.
 Now you should be ready to go.
 
-
-Windows or Mac OSX users
-************************
-
-
-
-- download and install github (https://desktop.github.com)
-
-- open GitHubDesktop and clone eTraGo from open_eGo
-
-- open an anaconda prompt as administrator and run:
-
-   ```
-   pip install -e path/to/Github/Folder/eTraGo
-   ```
-
-   ```
-   pip install pandas == 0.20.3 (version 0.21 is not working!)
-   ```
-
-- to check if everything is installed run:
-
-   ```
-   pip freeze
-   ```

doc/howToUse.rst

@@ -3,30 +3,29 @@
 How to use eTraGo?
 ==================
 
-After you installed eTraGo you can run eTraGo via terminal with
-``$ cd../<your path>/eTrago/etrago/`` and ``python3 appl.py``.
-The program will execute following functions:
+After you installed eTraGo you would typically start optimization runs by
+executing the ‘appl.py’ wich is situated in 
+``./eTrago/etrago/`` (e.g by ``python3 appl.py``).
 
-.. code-block:: python
-
-   # execute etrago function
-    network = etrago(args)
-    # plots
-    # make a line loading plot
-    plot_line_loading(network)
-    # plot stacked sum of nominal power for each generator type and timestep
-    plot_stacked_gen(network, resolution="MW")
-    # plot to show extendable storages
-    storage_distribution(network)
+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. 
+You find the documentation of all defined parameters from the 'args' here:
+:meth:`etrago.appl.etrago`.
 
+The appl.py contains the etrago(args) function which uses the
+defined 'args' dictionary to start the desired calculation.
 
-Overview of setting arguments
-=============================
+Afterwards 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.
 
-The tool eTraGo is using a main python script ‘appl.py’ in which your
-parameters, calculation methods and scenario settings are set in a python
-dictionary called args. The documentation of the program settings can you
-find here: :meth:`etrago.appl.etrago`.
+To save the results you can use an interface to the oedb or write them
+simply to csv files. These functionalites can be specified 
+also in :meth:`etrago.appl.etrago`.
 
 
 .. _Examples:
@@ -38,4 +37,4 @@ Examples and tutorial notebooks
 .. toctree::
    :maxdepth: 7
 
-   OpenMod  <https://github.com/openego/eGo/blob/features/tutorial/ego/examples/tutorials/etrago_OpenMod_Zuerich18.ipynb>
+   OpenMod  <https://github.com/openego/eGo/blob/master/ego/examples/tutorials/etrago_OpenMod_Zuerich18.ipynb>

doc/index.rst

@@ -15,7 +15,7 @@ Welcome to eTraGo's documentation!
              heavy development.
 
 .. toctree::
-   :maxdepth: 7
+   :maxdepth: 2
 
    about
    installation

doc/installation.rst

@@ -1,17 +1,18 @@
 ============
 Installation
 ============
-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:
+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
 
   $ pip3 install eTraGo --process-dependency-links
 
 
 
-
 Using virtual environment
 =========================
 
@@ -29,63 +30,82 @@ Linux and Ubuntu
 ================
 
 The Package eTraGo is tested with Ubuntu 16.04 and 18.04 inside the virtual
-environments of *virtualenv*. The installation is shown above.
+environments of `virtualenv <https://virtualenv.pypa.io/en/stable/>`_.
+The installation is shown above.
 
 
 
 Windows or Mac OSX users
 ========================
 
 For Windows and/or Mac OSX user we highly recommend to install and use Anaconda
-for you Python3 installation. First install anaconda inclusing python 3.x
-version from https://www.anaconda.com/download/ and open an anaconda prompt as
-administrator and run:
+for you Python3 installation. First install anaconda inclusing python 3.5 or
+higher version from https://www.anaconda.com/download/ and open an anaconda
+prompt as administrator and run:
 
 .. code-block:: bash
 
   $ conda install pip
   $ conda config --add channels conda-forge
   $ conda install shapely
+  $ pip3 install eTraGo --process-dependency-links
 
 The full Documentation can be found
-`on this page.<https://docs.anaconda.com/anaconda/install/>`_. We use Anaconda
+`on this page <https://docs.anaconda.com/anaconda/install/>`_ . We use Anaconda
 with an own environment in order to reduze problems with Packages and different
-versions on our system. Learn more about  (`Anacona environments
- <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_).
-
-
-
+versions on our system. Learn more about
+`Anacona <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_
+environments.
 
 
-Setup ego.io
-=============
 
+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/>`_.
 
 
- [oedb]
-
- username = YourOEDBUserName
-
- database = oedb
-
- host = oe2.iws.cs.ovgu.de
+oedialect connection
+--------------------
 
- port = 5432
+.. code-block:: desktop
 
- pw = YourOEDBPassword
+  [oedb]
+  dialect  = oedialect
+  username = <username>
+  database = oedb
+  host     = openenergy-platform.org
+  port     = 80
+  password = <token>
 
- [local]
 
- username = YourLocalUserName
+Local database connection
+-------------------------
 
- database = YourLocalDatabaseName
+.. code-block:: desktop
 
- host = 127.0.0.1
+   [local]
+   username = YourOEDBUserName
+   database = YourLocalDatabaseName
+   host = localhost or 127.0.0.1
+   port = 5433
+   pw = YourLocalPassword
 
- port = 5432
 
- pw = YourLocalPassword
 
+Old developer connection
+-------------------------
 
+.. code-block:: desktop
 
-when you just calculate local or on the oedb you just need this section
+  [oedb]
+  username = YourOEDBUserName
+  database = oedb
+  host = oe2.iws.cs.ovgu.de
+  port = 5432
+  pw = YourOEDBPassword