Update project documentation

constrain/api/workflow.py

@@ -113,11 +113,7 @@ def import_package(self) -> None:
         """Import third party packages based on the "imports" element values of the workflow json.
         E.g.: {
         ...
-        "imports": [
-            "numpy as np",
-            "pandas as pd",
-            "datetime"
-        ],
+        "imports": ["numpy as np","pandas as pd","datetime"],
         ...
         }
         """

docs/source/Acknowledgment.rst

@@ -0,0 +1,3 @@
+Acknowledgement
+================
+**ConStrain** was developed at the Pacific Northwest National Laboratory, and was funded under contract with the U.S. Department of Energy (DOE). It is actively being developed as an open-source project.

docs/source/Code Documentation.rst

@@ -1,6 +1,11 @@
 Code Documentation
 ===================
 
+.. automodule:: api.brick_compliance
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:
 .. automodule:: api.data_processing
     :members:
     :inherited-members:

docs/source/Contributing.rst

@@ -0,0 +1,22 @@
+Contributing
+==============
+Contributions are welcome and greatly appreciated.
+
+Issues
+-------
+Users of **ConStrain** are welcome to open issues to:
+  1. Ask for help
+  2. Report issues with the current code base
+  3. Request new features to be implemented
+
+Pull requests
+--------------
+Pull requests should be submitted through forks and tagged with appropriate available labels. The title and description of the pull request should be legible and clearly describe the proposed changes.
+
+  1. Bug fixes, improvements, and new features
+
+  Bug fixes, improvements and new features should be tied to one or multiple issues. Please open an issue(s) prior to opening a pull request and documenting the proposed change(s) to **ConStrain**. The development team is open to reviewing any proposed changes as long as the changes are explained in detail (using the code review feature of GitHub), and backed with sufficient research. Each pull request addressing bug fixes or improvements needs to include one or more unit tests.
+
+  2. Data
+
+  **ConStrain** uses a data-driven approach meaning that the more data it has access to, the better and the more relevant the curves generated by **ConStrain** will be. The development team welcomes contributions aiming to add data to **ConStrain**'s libraries. New data should be submitted through a pull request. The pull request should include the data in a format that can be used by **ConStrain** (For example, **ConStrain** currently uses performance curves, so no data tables should be submitted). To be included in **ConStrain**, the data should be publicly available, sharable, and accurate (and a reference should be provided for the team's review).

docs/source/License.rst

@@ -0,0 +1,18 @@
+License
+========
+
+This material was prepared as an account of work sponsored by an agency of the United States Government.  Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, 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 tradename, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Governmentor any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
+
+PACIFIC NORTHWEST NATIONAL LABORATORY operated by BATTELLE for the UNITED STATES DEPARTMENT OF ENERGY under Contract DE-AC05-76RL01830
+
+Control Strainer (ConStrain): A Data-driven Control Verification Framework (formally known as ANIMATE) Copyright (c) 2021, Battelle Memorial Institute All rights reserved.
+
+1.	Battelle Memorial Institute (hereinafter Battelle) hereby grants permission to any person or entity lawfully obtaining a copy of this software and associated documentation files (hereinafter “the Software”) to redistribute and use the Software in source and binary forms, with or without modification.  Such person or entity may use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and may permit others to do so, subject to the following conditions:
+
+  - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimers. 
+  - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+  - Other than as used herein, neither the name Battelle Memorial Institute or Battelle may be used in any form whatsoever without the express written consent of Battelle.
+
+2.	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BATTELLE OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

docs/source/Quickstart Guide.rst

@@ -0,0 +1,266 @@
+Quickstart Guide
+=================
+
+.. role:: python(code)
+   :language: python
+.. role:: json(code)
+   :language: JSON
+.. role:: bash(code)
+   :language: bash
+
+This guide provides a quick overview of how to get started with **ConStrain**. Verifications of building system control related timeseries using **ConStrain** can either be done by using **ConStrain** as a Python library or by using a **ConStrain** workflow.
+
+Installing **ConStrain**
+-------------------------
+**ConStrain** can be installed from PyPI by running the following command.
+
+.. sourcecode:: bash
+
+   pip install constrain
+
+Using **ConStrain** as a library
+---------------------------------
+
+First, let's import the package.
+
+.. sourcecode:: python
+
+    import constrain as cs
+
+**ConStrain** includes an :python:`Examples` module which contains sample data and examples of verifications. Information about eac example can be obtained by running the following command. A dictionary is returned which shows information about each example. 
+
+.. sourcecode:: python
+
+    # Load examples
+    examples = cs.Examples()
+
+    # Get the data
+    data = examples.info
+
+Let's proceed with :python:`example_1` which according to its description aims to:
+
+ *Perform verification of ASHRAE Guideline 36-2021 sequence of operation on a dataset generated through the simulation of an AHU in Modelica. The verifications include the following: supply temperature reset, outdoor air damper psition for relief damper/fan, and return air damper psition for relief damper/fan*.
+
+.. sourcecode:: python
+
+    # Get the data
+    data = examples.data("example_1")
+
+    # Loading the verification cases
+    cases = cs.api.VerificationCase(json_case_path=examples.verifications("example_1"))
+
+Here, :python:`data` is a :python:`pandas.DataFrame` which contains the timeseries for the verification, and :python:`cases` is a **ConStrain** :meth:`api.verification_case.VerificationCase` that contains all the information needed to perform a verification. To see the case information in a readable format (dictionary), run :python:`cases.case_suite`. Outside of examples, data for verifications can be directly loaded as :python:`pandas.DataFrame` and pre-processed using the functions in :meth:`api.data_processing` of **ConStrain**.
+
+Next, we want to validate :python:`cases` by calling :meth:`api.verification_case.VerificationCase.validate` to make sure that the verification structure is correct.
+
+.. sourcecode:: python
+
+    cases.validate()
+
+Then, we'll want to instantiate a verification and configure it, and run the verifications.
+
+.. sourcecode:: python
+
+    verif = cs.api.Verification(verifications=cases)
+    verif.configure(output_path = "./",
+                    lib_items_path = examples.library(),
+                    plot_option = "all-expand",
+                    fig_size = (10, 5),
+                    num_threads = 1,
+                    preprocessed_data = data)
+    verif.run()
+
+Finally, we can create summary report. A summary report for all verification will be created which will show the status of each verification
+
+.. sourcecode:: python
+
+    reporting = cs.api.Reporting(verification_json= "./*_md.json",
+                                result_md_name = "report_summary.md",
+                                report_format = "markdown")
+
+    reporting.report_multiple_cases()
+
+Using **ConStrain** workflows
+------------------------------
+
+A workflow is a group of instructions that define an end-to-end verification, from data parsing and manipulation to running the verfication(s) and reporting the results. Workflows are defined using the JSON file format so once they have been established they can be re-used easily without making significant modifications. Workflows rely on **ConStrain**'s APIs.
+
+Below is shown a valid workflow. Let's look at its structure.
+
+- :json:`"workflow_name"`: Name of the workflow
+- :json:`"meta"`: Metadata about the workflow
+- :json:`"imports"`: Python package import needed to run the workflow
+- :json:`"states"`: Sequential steps to follow to perform the verification; :json:`"states"` can either be :json:`"MethodCall"` which represent a method call to one of **ConStrain**'s APIs or a :json:`"Choice"` which can be used to help define alternative steps in a workflow based on the result (referred to as payloads in a workflow).
+
+.. sourcecode:: JSON
+
+    {
+      "workflow_name": "G36 Demo workflow",
+      "meta": {
+        "author": "ConStrain Team",
+        "date": "06/29/2023",
+        "version": "1.0",
+        "description": "Demo workflow to showcase G36 verification item development"
+      },
+      "imports": [
+        "numpy as np",
+        "pandas as pd"
+      ],
+      "states": {
+        "load data": {
+          "Type": "MethodCall",
+          "MethodCall": "DataProcessing",
+          "Parameters": {
+            "data_path": "./demo/G36_demo/data/G36_Modelica_Jan.csv",
+            "data_source": "EnergyPlus"
+          },
+          "Payloads": {
+            "data_processing_obj": "$",
+            "data": "$.data"
+          },
+          "Start": "True",
+          "Next": "load verification cases"
+        },
+        "load verification cases": {
+          "Type": "MethodCall",
+          "MethodCall": "VerificationCase",
+          "Parameters": {
+            "json_case_path": "./demo/G36_demo/data/G36_library_verification_cases.json"
+          },
+          "Payloads": {
+            "verification_case_obj": "$",
+            "original_case_keys": "$.case_suite.keys()"
+          },
+          "Next": "check original case length"
+        },
+        "check original case length": {
+          "Type": "Choice",
+          "Choices": [
+            {
+              "Value": "len(Payloads['original_case_keys']) == 3",
+              "Equals": "True",
+              "Next": "validate cases"
+            }
+          ],
+          "Default": "Report Error in workflow"
+        },
+        "validate cases": {
+          "Type": "Choice",
+          "Choices": [
+            {
+              "Value": "Payloads['verification_case_obj'].validate()",
+              "Equals": "True",
+              "Next": "setup verification"
+            }
+          ],
+          "Default": "Report Error in workflow"
+        },
+        "setup verification": {
+          "Type": "MethodCall",
+          "MethodCall": "Verification",
+          "Parameters": {
+            "verifications": "Payloads['verification_case_obj']"
+          },
+          "Payloads": {
+            "verification_obj": "$"
+          },
+          "Next": "configure verification runner"
+        },
+        "configure verification runner": {
+          "Type": "MethodCall",
+          "MethodCall": "Payloads['verification_obj'].configure",
+          "Parameters": {
+            "output_path": "./demo/G36_demo",
+            "lib_items_path": "./schema/library.json",
+            "plot_option": "+x None",
+            "fig_size": "+x (6, 5)",
+            "num_threads": 1,
+            "preprocessed_data": "Payloads['data']"
+          },
+          "Payloads": {},
+          "Next": "run verification"
+        },
+        "run verification": {
+          "Type": "MethodCall",
+          "MethodCall": "Payloads['verification_obj'].run",
+          "Parameters": {},
+          "Payloads": {
+            "verification_return": "$"
+          },
+          "Next": "check results"
+        },
+        "check results": {
+          "Type": "MethodCall",
+          "MethodCall": "glob.glob",
+          "Parameters": [
+            "./demo/G36_demo/*_md.json"
+          ],
+          "Payloads": {
+            "length_of_mdjson": "len($)"
+          },
+          "Next": "check number of result files"
+        },
+        "check number of result files": {
+          "Type": "Choice",
+          "Choices": [
+            {
+              "Value": "Payloads['length_of_mdjson']",
+              "Equals": "3",
+              "Next": "reporting_object_instantiation"
+            }
+          ],
+          "Default": "Report Error in workflow"
+        },
+        "reporting_object_instantiation": {
+          "Type": "MethodCall",
+          "MethodCall": "Reporting",
+          "Parameters": {
+            "verification_json": "./demo/G36_demo/*_md.json",
+            "result_md_name": "report_summary.md",
+            "report_format": "markdown"
+          },
+          "Payloads": {
+            "reporting_obj": "$"
+          },
+          "Next": "report_cases"
+        },
+        "report_cases": {
+          "Type": "MethodCall",
+          "MethodCall": "Payloads['reporting_obj'].report_multiple_cases",
+          "Parameters": {},
+          "Payloads": {},
+          "Next": "Success"
+        },
+        "Success": {
+          "Type": "MethodCall",
+          "MethodCall": "print",
+          "Parameters": [
+            "Congratulations! the demo workflow is executed with expected results and no error!"
+          ],
+          "End": "True"
+        },
+        "Report Error in workflow": {
+          "Type": "MethodCall",
+          "MethodCall": "logging.error",
+          "Parameters": [
+            "Something is wrong in the workflow execution"
+          ],
+          "End": "True"
+        }
+      }
+    }
+
+Running a workflow can be done as follows.
+
+.. sourcecode:: python
+
+    import constrain as cs
+
+    workflow_file = "./demo/G36_demo/G36_demo_workflow.json"
+    workflow = cs.Workflow(workflow=workflow_file)
+    workflow.run_workflow(verbose=True)
+
+Using **ConStrain**'s graphical user interface (GUI)
+-----------------------------------------------------
+
+Workflow can be pretty complex and difficult to fully visualise from JSON files. **ConStrain** includes a GUI to help user create, edit, and picture workflows. If **ConStrain** has been installed, the GUI can be run by just running :bash:`constrain` in a command prompt or terminal.

docs/source/Statement of Need.rst

@@ -0,0 +1,6 @@
+Statement of Need
+==================
+
+Advances in building control have shown significant potential for improving building energy performance and decarbonization. Studies show that designs utilizing optimized controls that are properly tuned could reduce commercial building energy consumption. Driven by the significant control-related energy-saving potential, commercial building energy codes (such as ASHRAE Standard 90.1) have progressed with many control-related addenda.
+
+However, one of the challenges to realizing those savings is the correct implementation of such advanced control strategies and regularly verifying their actual operational performance. A field study found that only 50% of systems observed have their control system correctly configured to meet the energy codes requirement, and control-related compliance verification is typically not included in the commissioning scope. Current control verification is often conducted manually, which is time-consuming, ad-hoc, incomplete, and error-prone.

docs/source/conf.py

@@ -25,9 +25,9 @@
 author = "Pacific Northwest National Laboratory"
 
 # The short X.Y version
-version = "0.1.0"
+version = "0.4.0"
 # The full version, including alpha/beta/rc tags
-release = "0.1.0"
+release = "0.4.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -214,7 +214,7 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {"<name>": ("https://docs.python.org/", None)}
 
 # -- Options for todo extension ----------------------------------------------
 

docs/source/index.rst

@@ -3,7 +3,16 @@ Documentation for ConStrain
 
 **Version**: |release|
 
+**ConStrain** is a data-driven knowledge-integrated framework that automatically verifies that controls function as intended. **ConStrain** is designed around three key features: building control knowledge integration, analytics, and automation. The framework includes three major components: a control verification algorithm library (rule-based, procedure-based, and AI-based), an automated preparation process and verification case generation, a standardized performance evaluation and reporting process.
+
+Applications of **ConStrain** include verifications of the implementation of control-related building energy code requirements (e.g., ASHRAE Standard 90.1) and sequences of operation (e.g., ASHRAE Guideline 36) using either data generated from building energy simulations and/or actual building monitoring system trend data.
+
 .. toctree::
    :maxdepth: 1
 
-   Code Documentation
+   Statement of Need
+   Quickstart Guide
+   Code Documentation
+   Contributing
+   License
+   Acknowledgment