version 0.3 push; documentation

doc/api.rst

@@ -43,11 +43,13 @@ Create model
   :return dict data: urbs input dict 
 
   The spreadsheet must contain 6 sheets labelled 'Commodity', 'Process', 
-  'Transmission', 'Storage', 'SupIm', and 'Demand'.
+  'Transmission', 'Storage', 'SupIm', and 'Demand'. It can contain a 7th sheet
+  called 'Hacks'. If present
+
+  Refer to the `mimo-example.xlsx` file for exemplary documentation of the 
+  table contents and definitions of all attributes by selecting the column
+  titles. 
 
-  Refer to `data-example.xlsx` for exemplary documentation of the table
-  contents. 
-
 
 .. function:: create_model(data, timesteps)
 
@@ -59,7 +61,24 @@ Create model
 
   Timestep numbers must match those of the demand and supim timeseries. 
 
+
+.. function:: add_hacks(model, hacks)
+
+  Is called by :func:`create_model` to add special elements, e.g. constraints,
+  to the model. Each hack, if present, can trigger the creation of additional
+  sets, parameters, variables or constraints. Refer to the code of this
+  function to see which hacks exists and what they do.
+
+  As of v0.3, only one hack exists: if a line "Global CO2 limit" exists in the
+  hacks DataFrame, its value is used as a global upper limit for a constraint
+  that limits the annual creation of the commodity "CO2".
+
+  :param model: urbs model object (not instance!)
+  :param hacks: a DataFrame of hacks  
+
+  :return model: the modified urbs model object
 
+
 Report & plotting
 ^^^^^^^^^^^^^^^^^
 
@@ -205,7 +224,7 @@ Helper functions
 
 .. data:: COLORS
 
-  Dictionary of commodity and site colors. Colors are stored as `(r,g,b)`
+  Dictionary of process and site colors. Colors are stored as `(r,g,b)`
   tuples in range `0-255`. To retrieve a color in a form usable with 
   matplotlib, used the helper function :func:`to_color`.
 

doc/conf.py

@@ -11,8 +11,8 @@
 
 project = u'urbs'
 copyright = u'2014, tum-ens'
-version = '0.2'
-release = '0.2'
+version = '0.3'
+release = '0.3'
 
 exclude_patterns = ['_build']
 #pygments_style = 'sphinx'

doc/index.rst

@@ -2,6 +2,8 @@
    sphinx-quickstart on Wed Sep 10 11:43:04 2014.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
+   
+.. module:: urbs
 
 urbs: A linear optimisation model for distributed energy systems
 ================================================================
@@ -26,16 +28,31 @@ Features
 * 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.
-* urbs includes reporting and plotting functionality.
+* urbs includes reporting and plotting functions for rapid scenario 
+  development.
+
+Changes
+-------
+
+Changes from version 0.2 to 0.3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Processes now support multiple inputs and multiple output commodities.
+* As a consequence :func:`plot` now plots commodity balance by processes, not 
+  input commodities, as this would be underspecified.
+* URBS now supports input files with only a single site; simply delete all
+  entries from the 'Transmission' spreadsheet and only use a single site name 
+  throughout your input.
+* Moved hard-coded 'Global CO2 limit' constraint to dedicated "Hacks"
+  spreadsheet, while the constraint is :func:`add_hacks`.
+* The main file ``urbs.py``  has
 
 Overview
 --------
 
 urbs consists of several **model entities**. These are commodities, processes,
 transmission and storage. Demand and intermittent commodity supply through are 
-modelled through time series datasets. If this sound incomprehensible, just
-read on! :-)
-
+modelled through time series datasets.
 
 Commodity
 ^^^^^^^^^