Updated docs for 2.2 release

energy-modelling-toolkit · Oct 15, 2017 · c19c438 · c19c438
1 parent d6bad0e
commit c19c438
Show file tree

Hide file tree

Showing 8 changed files with 149 additions and 113 deletions.
diff --git a/DispaSET/__init__.py b/DispaSET/__init__.py
@@ -1,7 +1,7 @@
 import logging.config
 import os
 
-__version__ = "2.2dev"
+__version__ = "2.2.0"
 
 # Logging: # TODO: Parametrize in dispacli or external config
 _LOGCONFIG = {

diff --git a/Docs/conf.py b/Docs/conf.py
@@ -57,9 +57,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.2dev'
+version = '2.2'
 # The full version, including alpha/beta/rc tags.
-release = '2.2dev'
+release = '2.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/Docs/figures/cli.png b/Docs/figures/cli.png
diff --git a/Docs/figures/report2.jpg b/Docs/figures/report2.jpg
diff --git a/Docs/index.rst b/Docs/index.rst
@@ -3,32 +3,43 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Dispa-SET's documentation!
-=====================================
-:Organization:  `Joint Research Centre`_, 
-		`Institute of Energy and Transport`_,
-                Energy Technology Policy Outlook Unit
-:Version: |version|
-:Date: |today|
+The Dispa-SET model
+===================
+
+The Dispa-SET model is an open-source unit commitment and optimal dispatch model focused on the balancing and flexibility problems in European grids. Its pre and post-processing tools are written in Python and the main solver can be called via GAMS or via PYOMO. The selected Mixed-Integer Linear Programming (MILP) solver is CPLEX.
+
+Dispa-SET is mainly developed within the Joint Research Centre of the EU Commission, in close collaboration with the University of Liège (Belgium).
+
+Model description and philosophy
+--------------------------------
+A comprehensive description of the model is available in the 2017 JRC technical report: `Modelling Future EU Power Systems Under High Shares of Renewables`_.
+
+.. image:: figures/report2.jpg
+
+Downloading Dispa-SET
+---------------------
+The public version of Dispa-SET can be downloaded from its github repository (using the Clone or Download button on the right side of the screen):
+https://github.com/squoilin/Dispa-SET
+
+Documentation
+-------------
+The model documentation is available by running sphinx in the Docs folder of the project or by consulting the online documentation. This documentation corresponds to the latest available public version of Dispa-SET: 
+http://www.dispaset.eu/latest/index.html
+
+Main contributors:
+
+* Sylvain Quoilin (Main Developper) 
+
+* Konstantinos Kavvadias  
+
+* Andreas Zucker 
 
-The Dispa-SET model is a unit commitment and dispatch model developed within the “Joint Research Centre” and focused on the balancing and flexibility problems in European grids [1]_. It is written in GAMS an Python (Pyomo) and uses csv files for input data handling. The optimisation is defined as a Linear Programming (LP) or Mixed-Integer Linear Programming (MILP) problem, depending on the desired level of accuracy and complexity. 
 
-
-
-Libraries used
---------------
-
-* `pyomo`_ Optimization object library, interface to LP solver (e.g. CPLEX)
-* `pandas`_ for input and result data handling 
-* `matplotlib`_ for plotting
-* `GAMS_api`_ for the communication with GAMS
-
-
 Contents
 --------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 1
 
    overview
    workflow
@@ -46,24 +57,5 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-References
-----------
-.. [1] Quoilin, S., Hidalgo Gonzalez, I., & Zucker, A. (2017). Modelling Future EU Power Systems Under High Shares of Renewables: The Dispa-SET 2.1 open-source model. Publications Office of the European Union.  
-
-.. _matplotlib: http://matplotlib.org
-.. _pandas: http://pandas.pydata.org
-.. _pyomo: http://www.pyomo.org/
-.. _GAMS_api: http://www.gams.com/help/index.jsp?topic=%2Fgams.doc%2Fapis%2Findex.html
-.. _Institute of Energy and Transport: https://ec.europa.eu/jrc/en/institutes/iet
-.. _Joint Research Centre: https://ec.europa.eu/jrc/en
-
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
 
+.. _Modelling Future EU Power Systems Under High Shares of Renewables: https://ec.europa.eu/jrc/en/publication/eur-scientific-and-technical-research-reports/modelling-future-eu-power-systems-under-high-shares-renewables-dispa-set-21-open-source
diff --git a/Docs/overview.rst b/Docs/overview.rst
@@ -2,7 +2,16 @@
 
 Overview
 ========
-The model is expressed as a MILP problem. Continuous variables include the individual unit dispatched power, the shedded load and the curtailed power generation. The binary variables are the commitment status of each unit. The main model features can be summarized as follows:
+
+:Organization:  `Joint Research Centre`_, 
+		`Institute of Energy and Transport`_,
+                Energy Technology Policy Outlook Unit
+:Version: |version|
+:Date: |today|
+
+The Dispa-SET model is mainly developed within the “Joint Research Centre” of the European Commission and focused on the balancing and flexibility problems in European grids [1]_. 
+
+It is written in GAMS an Python (Pyomo) and uses csv files for input data handling. The optimisation is defined as a Linear Programming (LP) or Mixed-Integer Linear Programming (MILP) problem, depending on the desired level of accuracy and complexity. Continuous variables include the individual unit dispatched power, the shedded load and the curtailed power generation. The binary variables are the commitment status of each unit. The main model features can be summarized as follows:
 
 
 Features
@@ -20,9 +29,20 @@ Features
 - Multi-nodes with capacity constraints on the lines (congestion)
 - Constraints on the targets for renewables and/or CO2 emissions
 - Yearly schedules for the outages (forced and planned) of each units
+- CHP power plants and thermal storage
 
 The demand is assumed to be inelastic to the price signal. The MILP objective function is therefore the total generation cost over the optimization period. 
 
+
+Libraries used
+--------------
+
+* `pyomo`_ Optimization object library, interface to LP solver (e.g. CPLEX)
+* `pandas`_ for input and result data handling 
+* `matplotlib`_ for plotting
+* `GAMS_api`_ for the communication with GAMS
+
+
 Ongoing developments
 --------------------
 The Dispa-SET project is relatively recent, and a number of improvements will be brought to the project in a close future:
@@ -45,14 +65,23 @@ can be redistributed and/or modified under the terms of this license.
 
 Main Developers
 ---------------
-- Sylvain Quoilin (European Commission, Institute for Energy and Transport)
-- Ignacio Hidalgo (European Commission, Institute for Energy and Transport)
+- Sylvain Quoilin (University of Liège)
 - Andreas Zucker (European Commission, Institute for Energy and Transport)
 - Konstantinos Kavvadias (European Commission, Institute for Energy and Transport)
 
 References
 ----------
+.. [1] Quoilin, S., Hidalgo Gonzalez, I., & Zucker, A. (2017). Modelling Future EU Power Systems Under High Shares of Renewables: The Dispa-SET 2.1 open-source models. Publications Office of the European Union.  
+.. [2] Hidalgo González, I., Quoilin, S., & Zucker, A. (2014). Dispa-SET 2.0: unit commitment and power dispatch model (EUR 27015 EN). Petten, Netherlands: European Commission. 
+.. [3] Quoilin, S., Nijs, W., Hidalgo, I., & Thiel, C. (2015). Evaluation of simplified flexibility evaluation tools using a unit commitment model. IEEE Digital Library. 
+.. [4] Quoilin, S., Gonzalez Vazquez, I., Zucker, A., & Thiel, C. (2014). Available technical flexibility for balancing variable renewable energy sources: case study in Belgium. Proceedings of the 9th Conference on Sustainable Development of Energy, Water and Environment Systems. 
+
+.. _matplotlib: http://matplotlib.org
+.. _pandas: http://pandas.pydata.org
+.. _pyomo: http://www.pyomo.org/
+.. _GAMS_api: http://www.gams.com/help/index.jsp?topic=%2Fgams.doc%2Fapis%2Findex.html
+.. _Institute of Energy and Transport: https://ec.europa.eu/jrc/en/institutes/iet
+.. _Joint Research Centre: https://ec.europa.eu/jrc/en
+
+
 
-.. [1] Hidalgo González, I., Quoilin, S., & Zucker, A. (2014). Dispa-SET 2.0: unit commitment and power dispatch model (EUR 27015 EN). Petten, Netherlands: European Commission. 
-.. [2] Quoilin, S., Nijs, W., Hidalgo, I., & Thiel, C. (2015). Evaluation of simplified flexibility evaluation tools using a unit commitment model. IEEE Digital Library. 
-.. [3] Quoilin, S., Gonzalez Vazquez, I., Zucker, A., & Thiel, C. (2014). Available technical flexibility for balancing variable renewable energy sources: case study in Belgium. Proceedings of the 9th Conference on Sustainable Development of Energy, Water and Environment Systems. 
diff --git a/Docs/workflow.rst b/Docs/workflow.rst
@@ -10,8 +10,9 @@ Prerequisites
 Install Python 2.7, with full scientific stack. The Anaconda_ distribution is recommended since it comprises all the required packages. If Anaconda is not used, the following libraries and their dependencies should be installed manually: 
 
 * numpy
-* pandas 
+* pandas (> v0.18.1)
 * matplotlib 
+* xlrd
 * pickle
 
 
@@ -42,112 +43,130 @@ Using Dispa-SET with PYOMO:
 * Install a solver and add it to the PATH environment variable (e.g. if cplex is installed, the "cplex" command should be callable from any command prompt).
 
 
-Run the pre-processing tool
----------------------------
+Step-by-step example of a Dispa-SET run
+---------------------------------------
+This section describes the pre-processing and the solving phases of a Dispa-SET run. Three equivalent methods are described in the next sections:
 
-1. Check the configuration file
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Dispa-SET runs are defined in dedicated excel configuration files stored in the "ConfigFiles" folder. The configuration file "ConfigTest.xlsx" has be setup for testing purposes. It generates a 10-days optimisation using data relative to the Dutch power system. 
+* Using the command line interface
 
-2. Pre-processing using the command line interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Using the Dispa-SET API
+
+* Using GAMS
+
+
+1. Using the command line interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dispa-SET can be run from the command line. To that aim, open a terminal window and change de directory to the Dispa-SET root folder. 
+
+.. image:: figures/cli.png
+
+
+1.1. Check the configuration file
+"""""""""""""""""""""""""""""""""
+Dispa-SET runs are defined in dedicated excel configuration files stored in the "ConfigFiles" folder. The configuration file "ConfigTest.xlsx" is provided for testing purposes. It generates a 10-days optimisation using data relative a fictitious power system composed of two zones Z1 and Z2. 
+
+1.2. Pre-processing
+"""""""""""""""""""
 From the command line, specify the configuration file to be used as an argument, the solver (Pyomo or GAMS) and the actions to be performed. Within the "Dispa-SET" folder, run::
 
 	python dispacli.py -c ./ConfigFiles/ConfigTest.xlsx build
 
 NB: The command line interface dispacli.py is designed to run with the Python interpreter, which should be the one selected. It might present some problems when run in Ipython.
 
-NB2: the pre-processing can also be run directly using the DispaSET API, as describe in the last section of this page.
-
-3. Check the simulation environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+1.3. Check the simulation environment
+"""""""""""""""""""""""""""""""""""""
 The simulation environment folder is defined in the configuration file. In the test example it is set to "Simulations/simulation_test". The simulation inputs are written in three different formats: excel (34 excel files), Python (Inputs.p) and GAMS (Inputs.gdx). 
 
 
-Run the optimisation
---------------------
+1.4. Run the optimisation
+"""""""""""""""""""""""""
+Using the GAMS api, the simulation can be started directly from the main DispaSet python file after the pre-processing phase. From the "Dispa-SET" folder, run::
 
-The optimisation can be run directly from the simulation environment folder generated by the pre-processing tool. Different options are available for that purpose:
+	python dispacli.py -g -c ./ConfigFiles/ConfigTest.xlsx simulate
 
-Using the GAMS user interface:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-From the simulation folder (defined in the config file), the Dispa-SET model can be run following the instruction below: 
+This generates the simulation environment, runs the optimisation, and stores the results in the same folder. Note that this can only work is the simulation has been pre-processed before (step 1.2). It is possible to combine the pre-processing and simulation step in one command::
 
-1. Through the UCM.gpr project file, open the UCM.h.gmx model file.
-2. Run the model in GAMS.
+	python dispacli.py -g -c ./ConfigFiles/ConfigTest.xlsx build simulate	
 
-The result file is written in the gdx format and stored in the Simulation folder, together with all input files.
+The same action can be performed using the PYOMO solver. In that case, the "-g" argument must be changed into "-p"::
 
-Using the GAMS command line:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-GAMS can also be run from the command line (this is the only option for the Linux version).
+	python dispacli.py -p -c ./ConfigFiles/ConfigTest.xlsx build simulate
 
-1. Make sure that the gams binary is in the system PATH
-2. From the simulation environment folder, run::
 
-	gams UCM_h.gms
+2. Using the Dispa-SET API.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The steps to run a model can be also performed directly in python, by importing the Dispa-SET library. An example file ("build_and_run.py") is available in the "scripts/" folder.
+After checking the configuration file "ConfigTest.xlsx" (in the "ConfigFiles" folder). Run the following python commands: 
 
-From Dispa-SET, using GAMS or PYOMO:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Using the GAMS api, the simulation can be started directly from the main DispaSet python file after the pre-processing phase. From the "Dispa-SET" folder, run::
+2.1 Import Dispa-SET::
 
-	python dispacli.py -g -c ./ConfigFiles/ConfigTest.xlsx build simulate
+	import DispaSET as ds
 
-This generates the simulation environment, runs the optimisation, and stores the results in the same folder. 
+2.2 Load the configuration file::
+	
+	config = ds.load_config_excel('ConfigFiles/ConfigTest.xlsx')
 
-The same action can be performed using the PYOMO solver. In that case, the "-g" argument must be changed into "-p"::
+2.3 Build the simulation environment (Folder that contains the input data and the simulation files required for the solver)::
 
-	python dispacli.py -p -c ./ConfigFiles/ConfigTest.xlsx build simulate
+	SimData = ds.build_simulation(config)
 
+2.4a Solve using PYOMO::
 
-Postprocessing
---------------
-Various functions and tools are provided within the PostProcessing.py file to load, analyse and plot the siimulation results. The use of these functions is illustrated into the the "Read_results_notebook.ipynb"  Notebook, which can be run by changing the path to the simulation folder. The type of results provided by the post-processing is illustrated hereunder.
+	r = ds.solve_pyomo(config['SimulationDirectory'])
 
-The power dispatch can be plotted for each simulated zone. In this plot, the units are aggregated by fuel type. The power consumed by storage units and the exportations are indicated as negative values. 
+2.4b Solve using GAMS::
 
-.. image:: figures/results_dispatch.png
+	r = ds.solve_GAMS(config['SimulationDirectory'], config['GAMS_folder'])
 
-It is also interesting to display the results at the unit level to gain deeper insights regarding the dispatch. In that case, a plot is generated, showing the commitment status of all units in a zone at each timestep. Both the dispatch plot and the commitment plot can be called using the CountryPlots function. 
+A more detailed description of the Dispa-SET functions in available in the API section.
 
-.. image:: figures/results_rug.png
 
-Some aggregated statistics on the simulations results can also be obtained, including the number of hours of congestion in each interconnection line, the yearly energy balances for each zone, the amount of lost load, etc.
+3. Using GAMS
+^^^^^^^^^^^^^
 
-.. image:: figures/result_analysis.png
+It is sometimes useful to run the dispa-SET directly in GAMS (e.g. for debugging purposes). In that case, the pre-processing must be run first (steps 1.2 or 2.1, 2.2 and 2.3) and the gams file generated in the simulation folder can be used to run the optimization. 
 
-The yearly energy balance per fuel or per technology is also useful to compare the energy mix in each zone. This can be plotted using the EnergyBarPlot function, with the following results:
+Using the GAMS graphical user interface:
+""""""""""""""""""""""""""""""""""""""""
+From the simulation folder (defined in the config file), the Dispa-SET model can be run following the instruction below: 
 
-.. image:: figures/results_balance.png
+1. Open the UCM.gpr project file in GAMS
+2. From GAMS, open the UCM_h.gmx model file
+3. Run the model in GAMS.
 
+The result file is written in the gdx format and stored in the Simulation folder, together with all input files.
 
-Using the Dispa-SET API
------------------------
+Using the GAMS command line:
+""""""""""""""""""""""""""""
+GAMS can also be run from the command line (this is the only option for the Linux version).
 
-The various actions described above can be performed directly in python, by importing the Dispa-SET library. An example file ("build_and_run.py") is available in the "scripts/" folder. The successive steps are:
+1. Make sure that the gams binary is in the system PATH
+2. From the simulation environment folder, run::
 
-Import Dispa-SET::
+	gams UCM_h.gms
 
-	import DispaSET as ds
 
-Load the configuration file::
-	
-	config = ds.load_config_excel('ConfigFiles/ConfigTest.xlsx')
+Postprocessing
+--------------
+Various functions and tools are provided within the PostProcessing.py file to load, analyse and plot the siimulation results. The use of these functions is illustrated into the the "Read_results_notebook.ipynb"  Notebook or in the "read_results.py" script, which can be run by changing the path to the simulation folder. The type of results provided by the post-processing is illustrated hereunder.
 
-Build the simulation environment::
+The power dispatch can be plotted for each simulated zone. In this plot, the units are aggregated by fuel type. The power consumed by storage units and the exportations are indicated as negative values. 
 
-	SimData = ds.build_simulation(config)
+.. image:: figures/results_dispatch.png
 
-Solve using PYOMO::
+It is also interesting to display the results at the unit level to gain deeper insights regarding the dispatch. In that case, a plot is generated, showing the commitment status of all units in a zone at each timestep. Both the dispatch plot and the commitment plot can be called using the CountryPlots function. 
 
-	r = ds.solve_pyomo(config['SimulationDirectory'])
+.. image:: figures/results_rug.png
 
-Solve using GAMS::
+Some aggregated statistics on the simulations results can also be obtained, including the number of hours of congestion in each interconnection line, the yearly energy balances for each zone, the amount of lost load, etc.
 
-	r = ds.solve_GAMS(config['SimulationDirectory'], config['GAMS_folder'])
+.. image:: figures/result_analysis.png
 
-A more detailed description of the Dispa-SET functions in available in the API section.
+The yearly energy balance per fuel or per technology is also useful to compare the energy mix in each zone. This can be plotted using the EnergyBarPlot function, with the following results:
+
+.. image:: figures/results_balance.png
 
 
 

diff --git a/requirements.txt b/requirements.txt
@@ -1,15 +1,11 @@
 click==6.7
 docutils==0.12
 h5py==2.6.0
-ipython==4.1.2
-ipython-genutils==0.1.0
-ipywidgets==4.1.1
 matplotlib==1.5.1
 numpy==1.11.1
 pandas==0.18.1
 pytz==2016.6.1
 Sphinx==1.3.5
 sphinx-rtd-theme==0.1.9
-spyder==2.3.8
 xlrd==0.9.4