Merge pull request #70 from lbl-srg/issue69_tagEdits

Closes #69.

.gitignore

@@ -7,6 +7,14 @@
 unittests/outputs/*.png
 unittests/outputs/*.log
 
+# Unit testing resources
+#########################
+unittests/resources/**/*.so
+unittests/resources/**/*.h
+unittests/resources/**/*.o
+unittests/resources/**/*.xml
+unittests/resources/**/*.txt
+
 # Ignore Dymola output, log and temporary files (in alphabetical order)
 #######################################################################
 *.bak-mo

README.md

@@ -6,10 +6,16 @@ This is the development site for MPCPy, the python-based open-source platform fo
 MPCPy is a python package that facilitates the testing and implementation of occupant-integrated model predictive control (MPC) for building systems.  The package focuses on the use of data-driven, simplified physical or statistical models to predict building performance and optimize control.  Four main modules contain object classes to import data, interact with real or emulated systems, estimate and validate data-driven models, and optimize control input.
 
 ## Third Party Software
-While MPCPy provides an integration platform, it relies on free, open-source, third-party software packages for model implementation, simulators, parameter estimation algorithms, and optimization solvers.  This includes python packages for scripting and data manipulation as well as other more comprehensive software packages for specific purposes.  In particular, modeling and optimization for physical systems rely heavily on the Modelica language specification (https://www.modelica.org/) and FMI standard (http://fmi-standard.org/) in order to leverage model library and tool development on these standards occurring elsewhere within the building and other industries.
+While MPCPy provides an integration platform, it relies on free, open-source, third-party software packages for model implementation, simulators, parameter estimation algorithms, and optimization solvers.  This includes python packages for scripting and data manipulation as well as other more comprehensive software packages for specific purposes.  In particular, modeling and optimization for physical systems rely on the Modelica language specification (https://www.modelica.org/) and FMI standard (http://fmi-standard.org/) in order to leverage model library and tool development on these standards occurring elsewhere within the building and other industries.
 
 ## Getting Started
-For installation instructions and an introductory tutorial, see Section 2 of the [User Guide](https://github.com/lbl-srg/MPCPy/tree/master/doc/userGuide).
+**Users** can download here.
+
+**Developers** can ``> git clone https://github.com/lbl-srg/MPCPy.git``.
+
+Then, follow the installation instructions and introductory tutorial in Section 2 of the [User Guide](https://github.com/lbl-srg/MPCPy/tree/master/doc/userGuide), located in /doc/userGuide.
+
+MPCPy uses Python 2.7 and has been tested on Ubuntu 16.04.
 
 ## Contributing
 If you are interested in contributing to this project:
@@ -25,4 +31,4 @@ MPCPy is available under the following open-source [license](https://github.com/
 ## Cite
 To cite MPCPy, please use:
 
-Blum, D. H. and Wetter, M. “MPCPy: An Open-Source Software Platform for Model Predictive Control in Buildings.” Proceedings of the 15th Conference of International Building Performance Simulation, Aug 7 – 9, 2017. San Francisco, CA, Accepted.
+Blum, D. H. and Wetter, M. “MPCPy: An Open-Source Software Platform for Model Predictive Control in Buildings.” Proceedings of the 15th Conference of International Building Performance Simulation, Aug 7 – 9, 2017. San Francisco, CA.

doc/userGuide/source/conf.py

@@ -57,7 +57,7 @@
 # The short X.Y version.
 #version = u'0.1'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1'
+release = u'0.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/userGuide/source/gettingStarted.rst

@@ -6,17 +6,29 @@ To get started with MPCPy, first follow the installation instructions below.  Th
 Installation Instructions For Linux (Ubuntu 16.04 LTS)
 ------------------------------------------------------
 
-1. Install Python Packages
-
-    - matplotlib 2.0.2
-    - numpy 1.13.1
-    - pandas 0.20.3
-    - python-dateutil 2.6.1
-    - pytz 2017.2
-    - scikit-learn 0.18.2
-    - tzwhere 2.3
-    - sphinx 1.6.3
-    - numpydoc 0.7.0
+1. Install Python packages:
+
+    - MPCPy uses Python 2.7.
+
+    - using pip, install the following packages:
+
+	    matplotlib >= 2.0.2
+
+	    numpy >= 1.13.1
+
+	    pandas >= 0.20.3
+
+	    python-dateutil >= 2.6.1
+
+	    pytz >= 2017.2
+
+	    scikit-learn >= 0.18.2
+
+	    sphinx >= 1.6.3
+
+	    numpydoc >= 0.7.0
+
+	    tzwhere **=** 2.3
 
 2. Install libgeos-dev with command:
 

doc/userGuide/source/introduction.rst

@@ -24,7 +24,7 @@ Three other modules provide additional, mainly internal, functionality to MPCPy:
 
 Third-Party Software
 --------------------
-While MPCPy provides an integration platform, it relies on free, open-source, third-party software packages for model implementation, simulators, parameter estimation algorithms, and optimization solvers.  This includes python packages for scripting and data manipulation as well as other more comprehensive software packages for specific purposes.  In particular, modeling and optimization for physical systems rely heavily on the Modelica language specification (https://www.modelica.org/) and FMI standard (http://fmi-standard.org/) in order to leverage model library and tool development on these standards occurring elsewhere within the building and other industries.  Two examples of these third-party tools are:
+While MPCPy provides an integration platform, it relies on free, open-source, third-party software packages for model implementation, simulators, parameter estimation algorithms, and optimization solvers.  This includes python packages for scripting and data manipulation as well as other more comprehensive software packages for specific purposes.  In particular, modeling and optimization for physical systems rely on the Modelica language specification (https://www.modelica.org/) and FMI standard (http://fmi-standard.org/) in order to leverage model library and tool development on these standards occurring elsewhere within the building and other industries.  Two examples of these third-party tools are:
 
 - **JModelica.org** (http://jmodelica.org/) is used for simulation of FMUs, compiling FMUs from Modelica models, parameter estimation of Modelica models, and control optimization using Modelica models.
 - **EstimationPy** (http://lbl-srg.github.io/EstimationPy/) is used for implementing the Unscented Kalman Filter for parameter estimation of FMU models.
@@ -39,5 +39,5 @@ Cite
 ----
 To cite MPCPy, please use:
 
-Blum, D. H. and Wetter, M. “MPCPy: An Open-Source Software Platform for Model Predictive Control in Buildings.” Proceedings of the 15th Conference of International Building Performance Simulation, Aug 7 – 9, 2017. San Francisco, CA, Accepted.
+Blum, D. H. and Wetter, M. “MPCPy: An Open-Source Software Platform for Model Predictive Control in Buildings.” Proceedings of the 15th Conference of International Building Performance Simulation, Aug 7 – 9, 2017. San Francisco, CA.
 

doc/userGuide/tutorial/introductory.py

@@ -3,7 +3,8 @@
 
 This tutorial will introduce the basic concepts and workflow of mpcpy.
 By the end, we will train a simple model based on emulated data, and use 
-the model to optimize the control signal of the system.
+the model to optimize the control signal of the system.  All required data
+files for this tutorial are located in doc/userGuide/tutorial.
 
 The model is a simple RC model of zone thermal response to ambient temperature
 and a singal heat input.  It is written in Modelica:
@@ -437,7 +438,11 @@
 data of the model object and updates their timeseries data with the optimal 
 solution for the time period specified.  Note that other than the constraints, 
 the exogenous data within the model object is used, and the control interval
-is assumed to be the same as the measurement sampling rate of the model.
+is assumed to be the same as the measurement sampling rate of the model. Use
+the ``get_optimization_options()`` and ``set_optimization_options()`` to see
+and change the options for the optimization solver; for instance number
+of control points, maximum iteration number, tolerance, or maximum CPU time.
+See the documentation for these functions for more information.
 
 >>> opt_problem.optimize('1/2/2017', '1/3/2017') # doctest: +ELLIPSIS
 -etc-
@@ -472,4 +477,8 @@
 if __name__ == "__main__":
     import doctest
     doctest.ELLIPSIS_MARKER = '-etc-'
-    doctest.testmod()
+    (n_fails, n_tests) = doctest.testmod()
+    if n_fails:
+        print('\nTutorial finished with {0} fails.'.format(n_fails));
+    else:
+        print('\nTutorial finished OK.')