Merge pull request #65 from lbl-srg/issue35_docs

Closes #35.

.gitignore

@@ -29,6 +29,13 @@ stat
 status
 stop
 
+# Tutorial
+##########
+doc/userGuide/tutorial/*.txt
+doc/userGuide/tutorial/*.fmu
+doc/userGuide/tutorial/*.mop
+doc/userGuide/tutorial/*.png
+
 # UserGuide Build
 #########################
 doc/userGuide/build

README.md

@@ -1,18 +1,28 @@
-# MPCPy
+![](doc/userGuide/source/images/logo.png)
+
 This is the development site for MPCPy, the python-based open-source platform for model predictive control in buildings.
 
-## Description
-MPCPy facilitates the testing and implementation of Model Predictive Control (MPC) for building systems.  The software package focuses on the use of data-driven simplified physical or statistical models to predict building performance and optimize control.  Python modules and classes exist for importing data, interacting with a real or emulated system, estimating and validating data-driven models, and optimizing control inputs.  Contributions of new methods for any of these features are welcome.
+## General
+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.
 
 ## Getting Started
-For installation, see Section 2 of the [User Guide](https://github.com/lbl-srg/MPCPy/tree/master/doc/userGuide).
+For installation instructions and an introductory tutorial, see Section 2 of the [User Guide](https://github.com/lbl-srg/MPCPy/tree/master/doc/userGuide).
+
+## Contributing
+If you are interested in contributing to this project:
+
+- You are welcome to report any issues in [Issues](https://github.com/lbl-srg/MPCPy/issues).
+- You are welcome to make a contribution by following the steps outlined on the [Contribution Workflow](https://github.com/lbl-srg/MPCPy/wiki/Contribution-Workflow) page.
 
-Then, take a look at the ipython notebook examples in the ``examples`` directory.
+Research has shown that MPC can address emerging control challenges faced by buildings.  However, there exists no standard practice or methods for implementing MPC in buildings.  Implementation is defined here as model structure, complexity, and training methods, data resolution and amount, optimization problem structure and algorithm, and transfer of optimal control solution to real building control.  In fact, different applications likely require different implementations.  Therefore, we aim for MPCPy to be flexible enough to accommodate different and new approaches to MPC in buildings as research approaches a consensus on best-practice methods.
 
 ## License
 MPCPy is available under the following open-source [license](https://github.com/lbl-srg/MPCPy/blob/master/license.txt).
 
-## Development and Contribution
-You are welcome to report any issues in [Issues](https://github.com/lbl-srg/MPCPy/issues).
+## Cite
+To cite MPCPy, please use:
 
-You are welcome make a contribution by following the steps outlined on the [Contribution Workflow](https://github.com/lbl-srg/MPCPy/wiki/Contribution-Workflow) page.
+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.

bin/runUnitTests.py

@@ -2,15 +2,16 @@
 """
 Run the unit tests for mpcpy.
 
-by David Blum
 """
 import unittest
+import doctest
 import argparse
 import inspect
 import importlib
 import tempfile
 import os
 import shutil
+from doc.userGuide.tutorial import introductory
 
 # Change working directory to temporary
 cwd = os.getcwd(); 
@@ -41,35 +42,51 @@
                 'test_exodata', \
                 'test_systems', \
                 'test_models', \
-                'test_optimization'];
+                'test_optimization', \
+                'test_tutorial'];
     classes = [];
 
 # Load Tests
 print('Loading tests...'); 
 suite = unittest.TestSuite();
 for module in modules:
-    module_name = 'unittests.' + module;
-    test_module = importlib.import_module(module_name);
-    # Find all test classes in module, select if test class is specified
-    module_classes = [];
-    if not classes:
-        for name, obj in inspect.getmembers(test_module):       
-            if inspect.isclass(obj):
-                module_classes.append(obj);             
-    else:
-        for name, obj in inspect.getmembers(test_module):       
-            if inspect.isclass(obj) and name in classes:
-                module_classes.append(obj);        
-    # Add test classes to suite
-    for obj in module_classes:
-        suite.addTests(unittest.TestLoader().loadTestsFromTestCase(obj));
+    if module != 'test_tutorial':
+        module_name = 'unittests.' + module;
+        test_module = importlib.import_module(module_name);
+        # Find all test classes in module, select if test class is specified
+        module_classes = [];
+        if not classes:
+            for name, obj in inspect.getmembers(test_module):       
+                if inspect.isclass(obj):
+                    module_classes.append(obj);             
+        else:
+            for name, obj in inspect.getmembers(test_module):       
+                if inspect.isclass(obj) and name in classes:
+                    module_classes.append(obj);        
+        # Add test classes to suite
+        for obj in module_classes:
+            suite.addTests(unittest.TestLoader().loadTestsFromTestCase(obj));
 
 # Report number of tests found
-print('{} tests found.'.format(suite.countTestCases()));
-# Run test suite
-print('Running tests...'); 
-unittest.TextTestRunner(verbosity = 1).run(suite);
+n_tests = suite.countTestCases();
+print('{} unit tests found.'.format(n_tests));
+if n_tests:
+    # Run test suite
+    print('Running unit tests...'); 
+    unittest.TextTestRunner(verbosity = 1).run(suite);
 
 # Delete temporary directory and change working directory back to original
 shutil.rmtree(tempdir, ignore_errors=True)
 os.chdir(cwd);
+
+# Run tutorial doctest
+#---------------------
+
+if 'test_tutorial' in modules:
+    print('\n\nRunning tutorial doctests...')
+    doctest.ELLIPSIS_MARKER = '-etc-'
+    os.chdir(os.path.dirname(introductory.__file__))
+    suite_tut = unittest.TestSuite();
+    suite_tut.addTests(doctest.DocTestSuite(introductory))
+    unittest.TextTestRunner(verbosity = 1).run(suite_tut);
+    os.chdir(cwd)

doc/README.md

@@ -4,11 +4,11 @@ Compile the user guide by running from the command line:
     > cd userGuide
     > make latex
 
-The user guide will be created as a PDF in the resulting build directory.
+The user guide will be created as a PDF in the resulting ``userGuide/build`` directory.
 
 
 
 ## UML Diagrams ##
-UML diagrams of MPCPy may be generated using the code in [PlantUMLs.txt](https://github.com/lbl-srg/MPCPy/blob/master/doc/PlantUMLs.txt).  The UML diagram for a single module is defined between the lines @startuml and @enduml, inclusive.  
+UML diagrams of MPCPy may be generated using the code in [PlantUMLs.txt](https://github.com/lbl-srg/MPCPy/blob/master/doc/uml/PlantUMLs.txt).  The UML diagram for a single module is defined between the lines @startuml and @enduml, inclusive.  
 
 Copy and paste the specific code section into the online PlantUML [image generator](http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000) and click "submit."

doc/__init__.py

@@ -0,0 +1 @@
+#

doc/PlantUMLs.txt → doc/uml/PlantUMLs.txt

@@ -4,36 +4,52 @@ abstract Variable
 abstract DisplayUnit
 abstract Temperature
 abstract Power
+abstract OtherQuantity
 
 Variable <|-- Static
 Variable <|-- Timeseries
 
 Variable *-- DisplayUnit  
 DisplayUnit <|-- Temperature
 DisplayUnit <|-- Power
+DisplayUnit <|-- OtherQuantity
 Temperature <|-- K
 Temperature <|-- degC
 Temperature <|-- degF
 Temperature <|-- degR
+Power <|-- PowerDisplayUnit
+OtherQuantity <|-- OtherDisplayUnit
 @enduml
 
 ExoData
 @startuml
 abstract Type
 abstract Weather
 abstract Internal
+abstract Control
+abstract OtherInput
+abstract Parameter
 abstract Constraint
+abstract Price
 
 Type <|-- Weather
 Type <|-- Internal
+Type <|-- Control
+Type <|-- OtherInput
+Type <|-- Parameter
 Type <|-- Constraint
+Type <|-- Price
 
 Weather <|-- WeatherFromEPW
 Weather <|-- WeatherFromCSV
 Internal <|-- InternalFromCSV
 Internal <|-- InternalFromOccupancyModel
-Constraint <|-- Constraint FromCSV
-Constraint <|-- Constraint FromOccupancyModel
+Control <|-- ControlFromCSV
+OtherInput <|-- OtherInputFromCSV
+Parameter <|-- ParameterFromCSV
+Constraint <|-- ConstraintFromCSV
+Constraint <|-- ConstraintFromOccupancyModel
+Price <|-- PriceFromCSV
 @enduml
 
 
@@ -58,17 +74,6 @@ abstract Estimate
 abstract Validate
 abstract OccupancyMethod
 
-Model : estimate()
-Model : validate()
-Model : simulate()
-
-Modelica : _simulate()
-Estimate : _estimate()
-Validate : _validate()
-OccupancyMethod : _estimate()
-OccupancyMethod : _validate()
-OccupancyMethod : _simulate()
-
 Model <|-- Modelica
 Model <|-- Occupancy
 Modelica *-- Estimate
@@ -95,4 +100,4 @@ Package<|-- JModelica
 Problem <|-- ParameterEstimate
 Problem <|-- EnergyMin
 Problem <|-- EnergyCostMin
-@enduml
+@enduml

doc/userGuide/__init__.py

@@ -0,0 +1 @@
+#

doc/userGuide/source/acknowledgements.rst

@@ -0,0 +1,13 @@
+Acknowledgments
+===============
+
+This research was supported by the Assistant Secretary for Energy Efficiency and Renewable Energy, Office of Building Technologies of the U.S. Department of Energy, under Contract No. DE-AC02-05CH11231.
+
+This work is funded by the U.S.-China Clean Energy Research Center (CERC) 2.0 on Building Energy Efficiency (BEE).
+
+Thank you to all who have provided guidance on the development of this program.  The following people have contributed directly to the development of this program (in alphabetical order):
+
+- Krzysztof Arendt, University of Southern Denmark
+- David H. Blum, Lawrence Berkeley National Laboratory
+- Ruoxi Jia, University of California, Berkeley
+- Michael Wetter, Lawrence Berkeley National Laboratory

doc/userGuide/source/conf.py

@@ -29,7 +29,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc','sphinx.ext.autosummary','sphinx.ext.doctest','sphinx.ext.todo','sphinx.ext.mathjax','numpydoc']
-#numpydoc_show_class_members = False
+numpydoc_show_class_members = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -47,8 +47,8 @@
 
 # General information about the project.
 project = u'MPCPy User Guide'
-copyright = u'2017, David H. Blum'
-author = u'David H. Blum'
+copyright = u'2017, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy).  All rights reserved.'
+author = u'Lawrence Berkeley National Laboratory'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -223,7 +223,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'MPCPyUserGuide.tex', u'MPCPy User Guide',
-     u'David H. Blum', 'manual'),
+     u'Lawrence Berkeley National Laboratory', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

doc/userGuide/source/disclaimers.rst

@@ -0,0 +1,17 @@
+Disclaimers
+===========
+
+This document was prepared as an account of work sponsored by the United States
+Government. While this document is believed to contain correct information, neither the
+United States Government nor any agency thereof, nor The Regents of the University of
+California, nor any of their employees, makes any warranty, express or implied, or assumes
+any legal responsibility for the accuracy, completeness, or usefulness of any information,
+apparatus, product, or process disclosed, or represents that its use would not infringe
+privately owned rights. Reference herein to any specific commercial product, process, or
+service by its trade name, trademark, manufacturer, or otherwise, does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by the United States
+Government or any agency thereof, or The Regents of the University of California. The
+views and opinions of authors expressed herein do not necessarily state or reflect those of the
+United States Government or any agency thereof or The Regents of the University of
+California.
+