wip on installation and introduction

doc/index.rst

@@ -1,6 +1,21 @@
 PyPSA-Eur: An Open Optimisation Model of the European Transmission System
 =========================================================================
 
+TODO: insert badges
+
+PyPSA-Eur is an open model dataset of the European power system at the
+transmission network level that covers the full ENTSO-E area.
+
+It contains alternating current lines at and above 220 kV voltage level and all high voltage direct current lines, substations, an open database of conventional power plants, time series for electrical demand and variable renewable generator availability, and geographic potentials for the expansion of wind and solar power.
+
+The model is suitable both for operational studies and generation and transmission expansion planning studies. The continental scope and highly resolved spatial scale enables a proper description of the long-range smoothing effects for renewable power generation and their varying resource availability.
+
+The restriction to freely available and open data encourages the open exchange of model data developments and eases the comparison of model results. It provides a full, automated software pipeline to assemble the load-flow-ready model from the original datasets, which enables easy replacement and improvement of the individual parts.
+
+PyPSA-Eur is designed to be imported into the open toolbox `PyPSA <https://www.pypsa.org>`_ for which `documentation <>`_ is available as well.
+
+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 <http://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 <http://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 <http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/>`_.
+
 Documentation
 =============
 
@@ -50,6 +65,37 @@ Documentation
    contributing
 
 
+Citing PyPSA-Eur
+================
+
+If you use PyPSA-Eur for your research, we would appreciate it if you would cite the following paper:
+
+- J. Hörsch, F. Hofmann, D. Schlachtberger, T. Brown, `PyPSA-Eur: An Open Optimisation Model of the European Transmission System <https://arxiv.org/abs/1806.01613>`_, 2018, Energy Strategy Reviews, Volume 22, November 2018, Pages 207-215, `10.1016/j.esr.2018.08.012 <https://doi.org/10.1016/j.esr.2018.08.012>`_, `arXiv:1806.01613 <https://arxiv.org/abs/1806.01613>`_
+
+Please use the following BibTeX: ::
+
+    @article{PyPSAEur,
+        author = "Jonas H\"orsch and Fabian Hofmann and David Schlachtberger and Tom Brown",
+        title = "PyPSA-Eur: An open optimisation model of the European transmission system",
+        journal = "Energy Strategy Reviews",
+        volume = "22",
+        pages = "207 - 215",
+        year = "2018",
+        issn = "2211-467X",
+        doi = "10.1016/j.esr.2018.08.012",
+        url = "https://doi.org/10.1016/j.esr.2018.08.012",
+        eprint = "1806.01613"
+    }
+
+
+TODO: actually add versions to zenodo
+
+If you want to cite a specific PyPSA-Eur version, each release of PyPSA-Eur is stored on Zenodo with a release-specific DOI.
+This can be found linked from the overall PyPSA-Eur Zenodo DOI:
+
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1246852.svg
+   :target: https://doi.org/10.5281/zenodo.1246852
+
 Licence
 =======
 

doc/installation.rst

@@ -2,8 +2,79 @@
 Installation
 ##########################################
 
-Section A
+TODO: install via bash installation script
-=========
 
-Section B
+.. note:: 
-=========
+    The steps are demonstrated as shell commands, where the path before the ``%`` sign denotes the
+    directory in which the commands following the ``%`` should be entered.
+
+Clone the Repository
+====================
+
+Clone the PyPSA-Eur repository using ``git``
+
+.. code:: bash
+
+    /some/other/path % cd /some/path/without/spaces
+
+    /some/path/without/spaces % git clone https://github.com/PyPSA/pypsa-eur.git
+
+.. note::
+    The path to the directory into which the ``git repository`` is cloned, 
+    must not have any spaces.
+
+
+Install Python Dependencies
+===============================
+
+TODO: conda link
+
+The python package requirements are curated in the conda `environment.yaml <https://github.com/PyPSA/pypsa-eur/blob/master/environment.yaml>`_ file.
+The environment can be installed and activated using
+
+.. code:: bash
+
+    .../pypsa-eur % conda env create -f environment.yaml
+
+    .../pypsa-eur % conda activate pypsa-eur
+
+.. note::
+    Note that activation is local to the currently open shell!
+    After opening a new terminal window,
+    one needs to reissue the second command! 
+
+
+Download Data Dependencies
+==============================
+
+Not all data dependencies are shipped with the git repository, since git is not suited for handling large changing files. Instead we provide separate data bundles:
+
+1. **Data Bundle:** `pypsa-eur-data-bundle.tar.xz <https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/pypsa-eur-data-bundle.tar.xz>`_ contains common GIS datasets like NUTS3 shapes, EEZ shapes, CORINE Landcover, Natura 2000 and also electricity specific summary statistics like historic per country yearly totals of hydro generation, GDP and POP on NUTS3 levels and per-country load time-series. It should be extracted in the ``data`` sub-directory, such that all files of the bundle are stored in the ``data/bundle`` subdirectory)
+
+.. code:: bash
+
+    .../pypsa-eur/data % curl -OL "https://vfs.fias.science/d/0a0ca1e2fb/files/?dl=1&p=/pypsa-eur-data-bundle.tar.xz"
+
+    .../pypsa-eur/data % tar xJf pypsa-eur-data-bundle.tar.xz
+
+
+2. **Cutouts:** `pypsa-eur-cutouts.tar.xz <https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/pypsa-eur-cutouts.tar.xz>`_ are spatiotemporal subsets of the European weather data from the `ECMWF ERA5 <https://software.ecmwf.int/wiki/display/CKB/ERA5+data+documentation>`_ reanalysis dataset and the `CMSAF SARAH-2 <https://wui.cmsaf.eu/safira/action/viewDoiDetails?acronym=SARAH_V002>`_ solar surface radiation dataset for the year 2013. They have been prepared by and are for use with the `atlite <https://github.com/PyPSA/atlite>`_ tool. You can either generate them yourself using the ``build_cutouts`` rule or extract them directly into the ``pypsa-eur`` directory. Extracting the bundle is recommended, since procuring the source weather data files for ``atlite`` is not properly documented at the moment:
+
+.. code:: bash
+
+    .../pypsa-eur % curl -OL "https://vfs.fias.science/d/0a0ca1e2fb/files/?dl=1&p=/pypsa-eur-cutouts.tar.xz"
+
+    .../pypsa-eur % tar xJf pypsa-eur-cutouts.tar.xz
+
+3. **Natura:** Optionally, you can download a rasterized version of the NATURA dataset `natura.tiff <https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/natura.tiff&dl=1>`_ and put it into the ``resources`` sub-directory. If you don't, it will be generated automatically, which is a time-consuming process.
+
+.. code:: bash
+
+    .../pypsa-eur % curl -L "https://vfs.fias.science/d/0a0ca1e2fb/files/?p=/natura.tiff&dl=1" -o "resources/natura.tiff"
+
+
+4. **Remove Archives:** Optionally, if you want to save disk space, you can delete ``data/pypsa-eur-data-bundle.tar.xz`` and ``pypsa-eur-cutouts.tar.xz`` once extracting the bundles is complete. E.g.
+
+.. code:: bash
+
+    .../pypsa-eur % rm -rf data/pypsa-eur-data-bundle.tar.xz pypsa-eur-cutouts.tar.xz

doc/plotting.rst

@@ -10,3 +10,7 @@ Plot Summary
 
 Plot Network
 ============
+
+
+.. image:: img/tech-colors.png
+    :align: center