Merge pull request #9 from pnnl/Brick_compliance

Brick Compliance API

demo/brick_demo/brick_demo_workflow_runner.py

@@ -0,0 +1,11 @@
+import sys
+import warnings
+
+sys.path.append("./src")
+
+from api import Workflow
+
+warnings.simplefilter(action="ignore", category=FutureWarning)
+warnings.simplefilter(action="ignore", category=ResourceWarning)
+workflow = Workflow(workflow="./demo/brick_demo/brick_workflow.json")
+workflow.run_workflow(verbose=True)

demo/brick_demo/brick_workflow.json

@@ -0,0 +1,124 @@
+{
+    "workflow_name": "Brick workflow",
+    "meta": {
+        "author": "Constrain Team",
+        "date": "08/21/2023",
+        "version": "1.0",
+        "description": "Demo workflow to showcase core brick API functionalities"
+    },
+    "imports": ["numpy as np", "pandas as pd", "datetime", "glob"],
+    "states": {
+        "instantiate BrickCompliance object": {
+            "Type": "MethodCall",
+            "MethodCall": "BrickCompliance",
+            "Parameters": {
+                "brick_schema_path": "./resources/brick/Brick.ttl",
+                "brick_instance_path": "./resources/brick/brick_instance.ttl"
+            },
+            "Payloads": {"BrickCompliance_obj": "$"},
+            "Start": "True",
+            "Next": "query datapoints"
+        },
+        "query datapoints": {
+            "Type": "MethodCall",
+            "MethodCall": "Payloads['BrickCompliance_obj'].query_verification_case_datapoints",
+            "Parameters": {
+                "verification_item_lib_name": "ZoneTempControl",
+                "energyplus_naming_assembly": false,
+						    "default_verification_case_values": "{'run_simulation': False, 'simulation_IO': {'idf': 'EnergyPlus_data', 'idd': './resources/Energy+V9_0_1.idd', 'weather': './weather/USA_GA_Atlanta-Hartsfield.Jackson.Intl.AP.722190_TMY3.epw', 'output': './demo/brick_demo/brick_dataset/data_file.csv', 'ep_path': 'C:\\\\\\\\EnergyPlusV9-0-1\\\\\\\\energyplus.exe'}, 'expected_result': 'pass', 'parameters': {}}"},
+            "Payloads": {"query_result": "$"},
+            "Next": "instantiate verification case"
+			  },
+        "instantiate verification case": {
+            "Type": "MethodCall",
+            "MethodCall": "VerificationCase",
+            "Parameters": {},
+            "Payloads": {"verification_case_obj": "$"},
+            "Next": "save query result"
+        },
+        "save query result": {
+            "Type": "MethodCall",
+            "MethodCall": "Payloads['verification_case_obj'].save_verification_cases_to_json",
+            "Parameters": {
+                "json_path": "./demo/brick_demo/brick_dataset/query_result.json",
+                "cases": "Payloads['query_result']"
+            },
+            "Payloads": {},
+            "Next": "load verification cases"
+        },
+        "load verification cases": {
+            "Type": "MethodCall",
+            "MethodCall": "VerificationCase",
+            "Parameters": {
+                "json_case_path": "./demo/brick_demo/brick_dataset/query_result.json"
+            },
+            "Payloads": {"verification_case_obj": "$"},
+            "Next": "load timeseries data"
+        },
+        "load timeseries data": {
+            "Type": "MethodCall",
+            "MethodCall": "DataProcessing",
+            "Parameters": {
+                "data_path": "./demo/brick_demo/brick_dataset/data_file.csv",
+                "data_source": "EnergyPlus"
+            },
+            "Payloads": {"data_processing_obj": "$", "data": "$.data"},
+            "Next": "setup verification"
+        },
+        "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/brick_demo/brick_dataset",
+                "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": "reporting_object_instantiation"
+        },
+        "reporting_object_instantiation": {
+            "Type": "MethodCall",
+            "MethodCall": "Reporting",
+            "Parameters": {
+                "verification_json": "./demo/brick_demo/brick_dataset/*_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!"
+            ],
+            "Payloads": {},
+            "End": "True"
+        }
+    }
+}

design/brick_compliance_doc.md

@@ -0,0 +1,42 @@
+### Brick API documentation
+
+`Class BrickQueryCompliance`   
+
+- `__init__(`_brick_schema_path: str_`, `_brick_instance_path: str_`)`    
+Instantiate a `BrickQueryCompliance` class object and load specified brick schema and brick instance.   
+    - **Parameters**  
+        - **brick_schema_path**: `str` path to a brick schema to be used for query. The default location is `./resources/brick/Brick.ttl`.   
+        - **brick_instance_path**: `str` path to a brick instance to be used for query. For now, only `.ttl` format is accepted.    
+        - **query_statement_path**: `str` path to the query statements. The default path is `./resources/brick/query_statement.yml`.       
+        - **datapoint_name_conversion_path**: `str` path to the datapoint conversion name saving yaml file. The default path is `./resources/brick/verification_datapoint_info.yml`.  
+        - - **perform_reasoning**: `bool` argument whether reasoning is performed to the given instance. The default boolean value is False.  
+
+- `validate_brick_instance()`   
+Validate a brick instance against the brick schema.   
+    - **Parameters**  
+        - **brick_schema_path_str**: `str` path to the brick schema to be used for validation.  
+    - **Returns**: i) `bool` whether the validation passes/fails, ii) `str` message from the validation process.       
+
+- `get_applicable_verification_lib_items(`_verification_item_lib_name_:list_`)`    
+Get applicable control verification library items among the `verification_item_lib_name` list from the given brick instance.        
+    - **Parameters**  
+        - **verification_item_lib_name**: `list` of `str` including verification item names to be tested. If empty list is provided, all the available verification library items are tested. 
+    - **Returns**: `list` of `str` including available verification library item names from a brick instance.  
+
+- `query_verification_case_datapoints(`_verification_item_lib_name: [str, list[str]]_`, `_energyplus_naming_assembly:bool = False_`, `_default_verification_case_values: dict = None_`)`  
+Query datapoints required for given verification item lib.
+    - **Parameters**  
+        - **verification_item_lib_name**: `str` or `list` of `str` verification item library to be quried. If only one verification item library is quried, one `str` argument type is paased. If multiple verification item libraries are queried, `list` of `str` argument type is passed.    
+        - **energyplus_naming_assembly**: `bool` (default: False) whether to convert the queried datapoints' name to EnergyPlus style variable name.   
+        - **default_verification_case_values**: `dict` that has default key values. ("no", "run_simulation", "idf", "idd", "weather", "output", "ep_path", "expected_result", "parameters",) keys must exist.  
+    - **Returns**: `list` of `dict`(s), queried results in verification case format. The return dict only includes `datapoints_source` and `verification_class` keys.    
+
+- `query_with_customized_statement(`_custom_query_statement: str_`, `_energyplus_naming_assembly:bool = False_`, `_*verification_item_lib_name: str_`, `_default_verification_case_values: dict = None_`)`  
+Query datapoints with a customized query statement. When implemented, the quality check of the `query_statement` is done by checking whether the number of queried variables are the same as the required number of data points in the verification library item.  
+    - **Parameters**  
+        - **custom_query_statement**: `str` query statement written from users.     
+        - **verification_item_lib_name**: `str` verification library item of the `query_statement`.  
+         - **energyplus_naming_assembly**: `bool` (default: True) whether to convert the queried datapoints' name to EnergyPlus style variable name. 
+         - **default_verification_case_values**: `dict` that has default key values. ("no", "run_simulation", "idf", "idd", "weather", "output", "ep_path", "expected_result", "parameters",) keys must exist. 
+    - **Returns**: `list` of `dict` of queried result in the verification case format. `str` message from the `query_statement`'s quality check result.    
+

requirements.txt

@@ -1,3 +1,4 @@
+brickschema
 matplotlib
 seaborn
 pandas
@@ -6,4 +7,6 @@ fuzzywuzzy
 scikit-learn
 scipy
 tqdm
-uuid
+uuid
+PyYAML
+pydash