updating README and docs for 0.5 release

README.md

@@ -12,7 +12,8 @@ URBS is a [linear programming](https://en.wikipedia.org/wiki/Linear_programming)
   * It finds the minimum cost energy system to satisfy given demand timeseries for possibly multiple commodities (e.g. electricity).
   * By default, operates on hourly-spaced timesteps (configurable).
   * Thanks to [Pandas](https://pandas.pydata.org), complex data analysis is easy.
-  * The model itself is quite small thanks to relying on the [Coopr](https://software.sandia.gov/trac/coopr)/[Pyomo](https://software.sandia.gov/trac/coopr/wiki/Pyomo) and includes reporting and plotting functionality.
+  * The model itself is quite small thanks to relying on the [Pyomo](http://www.pyomo.org/)
+  * The small codebase includes reporting and plotting functionality.
 
 ## Screenshots
 
@@ -24,17 +25,17 @@ URBS is a [linear programming](https://en.wikipedia.org/wiki/Linear_programming)
 
 ### Windows
 
-There are 2 ways to get all required packages under Windows. I recommend using the Python distribution Anaconda. If you don't want to use it or already have an existing Python 2.7 (sorry, 3.x is not yet supported) installation, you can also download the required packages one by one.
+There are 2 ways to get all required packages under Windows. I recommend using the Python distribution Anaconda. If you don't want to use it or already have an existing Python (version 3 **recommended**, 2.7 is supported as well) installation, you can also download the required packages one by one.
 
 #### Anaconda (recommended)
 
-  1. **[Anaconda (Python 2.7)](http://continuum.io/downloads)**. Choose the 64-bit installer if possible.
+  1. **[Anaconda (Python 3.5)](http://continuum.io/downloads)**. Choose the 64-bit installer if possible.
        1. During the installation procedure, keep both checkboxes "modify PATH" and "register Python" selected!
-  2. **Coopr/Pyomo**
+  2. **Pyomo**
        1. Launch a new command prompt (Win+R, type "cmd", Enter)
-       2. Type `pip install pyomo`, hit Enter. (As of 2016, Pyomo 3 is still supported, but upgrading to Pyomo 4 is now recommended, as Pyomo 3 support will be dropped with future updates.) 
+       2. Type `pip3 install pyomo`, hit Enter. (Pyomo 3, i.e. `coopr.pyomo`, is still supported, but will be dropped with the next release.)
   3. **GLPK**
-       1. Download the latest version (e.g. GLPK-4.55) of [WinGLPK](http://sourceforge.net/projects/winglpk/files/winglpk/)
+       1. Download the latest version (e.g. GLPK-4.57) of [WinGLPK](http://sourceforge.net/projects/winglpk/files/winglpk/)
        2. Extract the contents to a folder, e.g. `C:\GLPK`
        3. Add the subfolder `w64` to your system path, e.g. `C:\GLPK\w64` ([how](http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx)).
 
@@ -44,30 +45,30 @@ Continue at [Get Started](#get-started).
 
 For all packages, best take the latest release or release candidate version. Both 32 bit and 64 bit versions work, though 64 bit is recommended.
 
-  1. **[Python 2.7](https://python.org/download)**. Python 3 support is not possible yet, but planned once all used packages support it.
-  2. **[pip](https://pip.pypa.io/en/latest/installing.html)**.The Python package manager. It allows to install many Python packages with a simple command. 
-      1. After installation, add `C:\Python27\Scripts` to environment variable "Path" ([how](http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx)), so that the `pip` command becomes available on the command prompt.
-  3. **IPython**: execute `pip install ipython` in a command prompt.
-  4. **SciPy stack:** These require binary installers, made available and maintained by [C. Gohlke](http://www.lfd.uci.edu/~gohlke/pythonlibs/). *How to select the correct file:* Download the newest stable version of each package, whose filename suffix matches both "bitness" (32 bit or 64 bit) and Python version (i.e. 2.7).  
+  1. **[Python 3.5](https://python.org/download)**. Python 2.7 is also supported.
+  2. **[pip3](https://pip.pypa.io/en/latest/installing.html)**.The Python package manager. It allows to install many Python packages with a simple command. 
+      1. After installation, add `C:\Python35\Scripts` to environment variable "Path" ([how](http://geekswithblogs.net/renso/archive/2009/10/21/how-to-set-the-windows-path-in-windows-7.aspx)), so that the `pip3` command becomes available on the command prompt.
+  3. **IPython**: execute `pip3 install ipython3` in a command prompt.
+  4. **SciPy stack:** These require binary installers, made available and maintained by [C. Gohlke](http://www.lfd.uci.edu/~gohlke/pythonlibs/). *How to select the correct file:* Download the newest stable version of each package, whose filename suffix matches both "bitness" (32 bit or 64 bit) and Python version (i.e. 3.5).  
       1. [NumPy](http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy)
       2. [SciPy](http://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy)
       3. [matplotlib](http://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib), requires [dateutil](http://www.lfd.uci.edu/~gohlke/pythonlibs/#python-dateutil), [pytz](http://www.lfd.uci.edu/~gohlke/pythonlibs/#pytz), [pyparsing](http://www.lfd.uci.edu/~gohlke/pythonlibs/#pyparsing) and [six](http://www.lfd.uci.edu/~gohlke/pythonlibs/#six). 
-      4. As a test, you can try start `ipython` and have a MATLAB-style command line with plotting capabilities. If you receive message about "ipython could not be found", check if the `C:\Python27\Scripts` is added to the "Path" system variable as described in step 2.i. above.
+      4. As a test, you can try start `ipython3` and have a MATLAB-style command line with plotting capabilities. If you receive message about "ipython could not be found", check if the `C:\Python35\Scripts` is added to the "Path" system variable as described in step 2.i. above.
   5. **[pandas](https://pypi.python.org/pypi/pandas#downloads)**: its [Series](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#series) and [DataFrame](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe) are used for representing all model input and output. Its capabilities are exploited to write short analysis scripts in `runme.py` and `comp.py`, as well as in the functions `urbs.plot` and `urbs.report`.
-  6. **Pyomo**: execute `pip install pyomo` in a command prompt.
+  6. **Pyomo**: execute `pip3 install pyomo` in a command prompt.
   7. **Solver**: [GLPK](http://winglpk.sourceforge.net/). 
       1. Simply unzip the latest version somewhere, e.g. `C:\GLPK`. 
       2. Then add the subdirectory `w64`, which contains `glpsol.exe`, to the system path (like in step 2.i.), so that the `glpsol` command is available on the command prompt.
-  8. **Excel** reading/writing: `pip install xlrd xlwt openpyxl==1.8.6`
+  8. **Excel** reading/writing: `pip3 install xlrd xlwt openpyxl`
 
 Continue at [Get Started](#get-started).
 
 ### Linux
 
 Use your Linux distribution's package manager to get all the packages listed in the Windows installation section. Below is the installation procedure for Ubuntu & Debian. Other distributions might have slightly different package names or differing procedures to get the individual packages to run:
 
-  - **Everything** except Coopr & Excel I/O `sudo apt-get install python python-pip python-numpy python-scipy python-matplotlib ipython ipython-notebook python-pandas python-sympy python-nose glpk-utils`
-  - **Coopr & Excel I/O** `sudo pip install coopr xlwt xlrd openpyxl==1.8.6`
+  1. **Python and base packages**: `sudo apt-get install python3 python3-pip python3-numpy python3-scipy python3-matplotlib python3-ipython python3-notebook python3-sympy glpk-utils`
+  2. **Up-to-date Python packages**: `sudo pip3 install pandas pyomo xlwt xlrd openpyxl`
 
 Continue at [Get Started](#get-started).
 
@@ -80,21 +81,21 @@ Then, in a directory of your choice, clone this repository and execute the runme
 
     git clone https://github.com/tum-ens/urbs.git
     cd urbs
-    python runme.py
+    python3 runme.py
 
 About a minute later, the subfolder `result` should contain plots and summary spreadsheets for multiple optimised energy supply scenarios, whose definitions are contained in the run script (watch out for `def scenario` lines). To get a graphical and tabular summary over all scenarios, execute
 
-    python comp.py
+    python3 comp.py
 
-and look at the new files `result/mimo-example-20150401/comp.xlsx` and `result/mimo-example-20150401/comp.png` for a quick comparison. This script parses the summary spreadsheets for all scenarios.
+and look at the new files `result/mimo-example-20160101T1234/comp.xlsx` and `result/mimo-example-20160101T1234/comp.png` for a quick comparison. This script parses the summary spreadsheets for all scenarios.
 
 ## Next steps
 
   1. Head over to the tutorial at http://urbs.readthedocs.org, which goes through runme.py step by step. 
   2. Read the source code of `runme.py` and `comp.py`. 
   3. Quickly scan through `urbs.py`, read docstrings.
   4. Try adding/modifying scenarios in `runme.py` and see their effect on results.
-  5. Fire up IPython (`ipython`) and run the scripts from there using the run command: `run runme` and `run comp`. Then use `whos` and inspect the workspace afterwards (`whos`). See what you can do (analyses, plotting) with the DataFrames. Take the `urbs.get_constants`, `urbs.get_timeseries` and `urbs.plot` functions as inspriation and the [Pandas docs](http://pandas.pydata.org/pandas-docs/stable/) as reference.
+  5. Fire up IPython (`ipython3`) and run the scripts from there using the run command: `run runme` and `run comp`. Then use `whos` and inspect the workspace afterwards (`whos`). See what you can do (analyses, plotting) with the DataFrames. Take the `urbs.get_constants`, `urbs.get_timeseries` and `urbs.plot` functions as inspriation and the [Pandas docs](http://pandas.pydata.org/pandas-docs/stable/) as reference.
 
 ## Further reading
 

doc/conf.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
 
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
 extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
@@ -10,9 +14,9 @@
 master_doc = 'index'
 
 project = u'urbs'
-copyright = u'2014, tum-ens'
-version = '0.4'
-release = '0.4'
+copyright = u'2014-2016, tum-ens'
+version = '0.5'
+release = '0.5'
 
 exclude_patterns = ['_build']
 #pygments_style = 'sphinx'
@@ -64,7 +68,7 @@
 epub_title = u'urbs'
 epub_author = u'tum-ens'
 epub_publisher = u'tum-ens'
-epub_copyright = u'2014, tum-ens'
+epub_copyright = u'2014-2016, tum-ens'
 
 epub_exclude_files = ['search.html']
 

doc/index.rst

@@ -14,10 +14,10 @@ urbs: A linear optimisation model for distributed energy systems
 :Version: |version|
 :Date: |today|
 :Copyright:
+  The model code is licensed under the `GNU General Public License 3.0
+  <http://www.gnu.org/licenses/gpl-3.0>`_.
   This documentation is licensed under a `Creative Commons Attribution 4.0 
-  International`__ license.
-
-.. __: http://creativecommons.org/licenses/by/4.0/
+  International <http://creativecommons.org/licenses/by/4.0/>`_ license.
 
 
 Contents
@@ -51,14 +51,32 @@ Features
   for possibly multiple commodities (e.g. electricity).
 * By default, operates on hourly-spaced timesteps (configurable).
 * Thanks to `pandas`_, complex data analysis code is short and extensible.
-* The model itself is quite small thanks to relying on the `Coopr`_/`Pyomo`_
-  packages.
+* The model itself is quite small thanks to relying on the `Pyomo`_
+  package.
 * urbs includes reporting and plotting functions for rapid scenario 
   development.
 
 Changes
 -------
 
+2016-02-16 Version 0.5
+^^^^^^^^^^^^^^^^^^^^^^
+
+* Support for Python 3 added
+* Support for Pyomo 4 added, while maintaining Pyomo 3 support. Upgrading to
+  Pyomo 4 is advised, as support while be dropped with the next release to
+  support new features.
+* New feature: maximal power gradient for conversion processes
+* Documentation: :doc:`buyselldoc` long explanation for `Buy` and `Sell` 
+  commodity types
+* Documentation: :doc:`mathdoc` full listing of sets, parameter, variables,
+  objective function and constraints in mathematical notation and textual
+  expanation
+* Documentation: updated installation notes in `README.md`_
+* Plotting: automatic sorting of time series by variance makes it easier to
+  read stacked plots with many technologies  
+
+
 2015-07-29 Version 0.4
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -105,17 +123,16 @@ scenarios:
 Dependencies
 ------------
 
-* `coopr`_ interface to optimisation solvers (CPLEX, GLPK, Gurobi, ...).
-  At least one supported solver by coopr must be installed.
+* `pyomo`_ for model equations and as the interface to optimisation solvers 
+  (CPLEX, GLPK, Gurobi, ...). At least one supported solver must be installed.
 * `matplotlib`_ for plotting
 * `pandas`_ for input and result data handling, report generation 
-* `pyomo`_ for the model equations
 
 
-.. _coopr: https://software.sandia.gov/trac/coopr
 .. _Institute for Renewable and Sustainable Energy Systems: http://www.ens.ei.tum.de/
 .. _matplotlib: http://matplotlib.org
 .. _pandas: http://pandas.pydata.org
-.. _pyomo: https://software.sandia.gov/trac/coopr/wiki/Pyomo
+.. _pyomo: http://www.pyomo.org
+.. _readme.md: https://github.com/tum-ens/urbs/blob/master/README.md
 .. _urbs: https://github.com/tum-ens/urbs