Update documentation

.github/workflows/sample_constrain_run.py

@@ -31,7 +31,7 @@
     response = requests.get(url)
     data = json.loads(response.content)
 
-    # 2- Change data path
+    # 2 - Change data path
     data["states"]["load data"]["Parameters"]["data_path"] = str(
         Path(__file__).parent.parent.parent
         / "constrain/demo/G36_demo/data/G36_Modelica_Jan.csv"

README.md

@@ -27,14 +27,12 @@ While the development of ConStrain was motivated by use cases with building ener
 - Authority having jurisdiction (AHJ) – achieve better compliance rates for control provisions in code.
 - Mechanical engineer/energy modeler – ensure that chosen systems and their controls will comply with code.
 - Energy code/control guideline developer – identify ambiguity in code languages.
-- BEM software developer – identify control related issues in simulation engine.
+- BEM users and software developer – identify control related issues in simulation engine.
 
 # Current Version of _ConStrain_?
 
 The current version of ConStrain includes the framework implementation, a preliminary development and implementation of the verification library (based on ASHRAE 90.1-2016 control related requirement), and the test cases of verification algorithms using prototype building models. The current list of implemented verification algorithms includes supply air temperature control, economizer high limit, integrated economizer control, zone temperature control (dead band), zone temperature control (setback), hot water temperature reset, chilled water temperature reset, etc.
 
-A newly released API helps users to use ConStrain more easily. An API workflow demo is provided at `demo/api_demo` and `test/api/test_workflow.py`
-
 See the Publications section for more information and example of uses of the framework.
 
 ## Get Started

constrain/api/brick_compliance.py

@@ -1,3 +1,9 @@
+"""
+brick_compliance.py
+====================================
+Brick Compliance API
+"""
+
 import ast
 import copy
 import json

constrain/api/reporting.py

@@ -23,7 +23,7 @@ def __init__(
     ) -> None:
         """
         Args:
-            verification_json (str, optional): Path to the result json files after verifications to be loaded for reporting. It can be one JSON file or wildcard for multiple JSON files (e.g., *_md.json).
+            verification_json (str, optional): Path to the result json files after verifications to be loaded for reporting. It can be one JSON file or wildcard for multiple JSON files (e.g., \*_md.json).
             result_md_name (str, optional): Name of the report summary markdown to be saved. All md reports will be created in the same directory as the verification result json files.
             report_format (str, optional): File format to be output. For now, only `markdown` format  is available. More formats (e.g., html, pdf, csv, etc.) will be added in future releases.
         """

constrain/api/verification.py

@@ -72,7 +72,7 @@ def configure(
             time_series_csv_export_name_prefix (str, optional): CSV file name prefix for saving a complete data csv file with verification result flags. Defaults to None, which will not save any time series data archives.
             lib_items_path (str, optional): User provided verification item json path (include name of the file with extension).
             lib_classes_py_file (str, optional): User provided verification item python classes file.
-            plot_option (str, optional): Type of plots to include. It should either be all-compact, all-expand, day-compact, or day-expand. It can also be None, which will plot all types. Default to None.
+            plot_option (str, optional): Type of plots to include. It should either be all-compact (all variables are plotted into one single plot), all-expand (individual plots for each variables), day-compact (all variables are plotted into one single plot and only cover one day), or day-expand (individual plots for each variables and only cover one day). It can also be None, which will plot all types. Default to None.
             fig_size (tuple, optional): Tuple of integers (length, height) describing the size of the figure to plot. Defaults to (6.4, 4.8).
             num_threads (int, optional): Number of threads to run verifications in parallel. Defaults to 1.
             preprocessed_data (pd.DataFrame, optional): Pre-processed data stored in the data frame. Default to None.

constrain/checklib.py

@@ -1,4 +1,6 @@
 """
+checklib.py
+====================================
 This file containing the high level interface for implementing verification item classes in library.py
 """
 

constrain/demo/G36_demo/data/G36_library_verification_cases.json

@@ -45,7 +45,8 @@
                     "position_damper_air_outdoor_min": "min_oa_p",
                     "position_damper_air_outdoor_max": "max_oa_p",
                     "flag_economizer_limit": "economizer_high_limit_reached"
-                }
+                },
+                "parameters": {}
             },
             "verification_class": "G36OutdoorAirDamperPositionForReliefDamperOrFan"
         },

constrain/schema/library.json

@@ -534,11 +534,11 @@
             "mode_operation": "System operation mode",
             "temperature_air_outdoor": "Outdoor air temperature",
             "temperature_air_supply_max": "Maximum supply air temperature setpoint based on requests",
-			"temperature_air_outdoor_supply_max": "Maximum outdoor air temperature for linear SAT reset",
+            "temperature_air_outdoor_supply_max": "Maximum outdoor air temperature for linear SAT reset",
             "temperature_air_outdoor_supply_min": "Minimum outdoor air temperature for linear SAT reset",
             "temperature_air_supply_setpoint_cool_min": "Minimum cooling supply air temperature setpoint",
             "temperature_air_supply_setpoint_cool_max": "Maximum cooling supply air temperature setpoint",
-			"temperature_air_supply_setpoint": "Supply air temperature setpoint"
+            "temperature_air_supply_setpoint": "Supply air temperature setpoint"
         },
         "description_verification_type": "procedure-based",
         "assertions_type": "pass",
@@ -776,7 +776,7 @@
             "output_coil_cooling": "AHU cooling coil heat transfer rate",
             "position_damper_air_return_max": "Maximum return air damper position",
             "position_damper_air_return": "Return air damper position",
-			"position_damper_air_relief": "Relief air damper position"
+            "position_damper_air_relief": "Relief air damper position"
         },
         "description_verification_type": "procedure-based",
         "assertions_type": "pass",
@@ -1556,7 +1556,7 @@
             "end"
         ]
     },
-	"VAVMinimumTurndownDuringReheatPressureReset": {
+    "VAVMinimumTurndownDuringReheatPressureReset": {
         "library_item_id": 69,
         "description_brief": "When a VAV box is in reheat mode, the ratio of VAV airflow rate to VAV max airflow rate must not be greater than the min design turndown ratio and the pressure setpoint must remain the same",
         "description_index": [
@@ -1577,11 +1577,11 @@
             "     Untested",
             "  if flow_volumetric_air_max > 0.0 and flow_volumetric_air_vav / flow_volumetric_air_max > ratio_turndown_min:",
             "    if pressure_static_setpoint_prev is None:",
-			"        Untested",
-			"    elif abs(pressure_static_setpoint - pressure_static_setpoint_prev) > 0:",
-			"        Untested",
-			"    else:",
-			"        fail",
+            "        Untested",
+            "    elif abs(pressure_static_setpoint - pressure_static_setpoint_prev) > 0:",
+            "        Untested",
+            "    else:",
+            "        fail",
             "  else:",
             "     pass",
             "else: ",
@@ -1613,19 +1613,19 @@
             "    pass",
             "  else: ",
             "    fail",
-			"  end",
+            "  end",
             "end"
         ]
     },
-	"ChilledWaterPlantSizingWholePlant": {
+    "ChilledWaterPlantSizingWholePlant": {
         "library_item_id": 71,
         "description_brief": "",
         "description_index": [
             "N/A"
         ],
         "description_datapoints": {
             "load_plant_water_chilled": "Chilled water plant load",
-			"temperature_air_outdoor": "Outdoor air temperature",
+            "temperature_air_outdoor": "Outdoor air temperature",
             "capacity_nominal_plant_water_chilled": "Nominal capacity of the chilled water plant",
             "temperature_drybulb_day_design_cooling": "Cooling design day drybulb temperature",
             "factor_oversizing": "Oversizing factor"
@@ -1642,15 +1642,15 @@
             "    return 'Untested'"
         ]
     },
-	"ChilledWaterPlantSizingMultipleChillers": {
+    "ChilledWaterPlantSizingMultipleChillers": {
         "library_item_id": 72,
         "description_brief": "",
         "description_index": [
             "N/A"
         ],
         "description_datapoints": {
             "status_chiller": "Chiller Status",
-            "load_plant_water_chilled": "Chilled water plant load"		
+            "load_plant_water_chilled": "Chilled water plant load"
         },
         "description_verification_type": "procedure-based",
         "assertions_type": "pass",
@@ -1679,7 +1679,7 @@
             "end"
         ]
     },
-	"ChilledWaterPlantSizingChillerMaxLoading": {
+    "ChilledWaterPlantSizingChillerMaxLoading": {
         "library_item_id": 73,
         "description_brief": "",
         "description_index": [
@@ -1701,15 +1701,15 @@
             "  end"
         ]
     },
-	"ChilledWaterPlantSizingChillerShortCycling": {
+    "ChilledWaterPlantSizingChillerShortCycling": {
         "library_item_id": 74,
         "description_brief": "",
         "description_index": [
             "N/A"
         ],
         "description_datapoints": {
             "status_chiller": "Chiller status",
-            "cycles_number_maximum": "Maximum allowed number of cycles per hour"		
+            "cycles_number_maximum": "Maximum allowed number of cycles per hour"
         },
         "description_verification_type": "rule-based",
         "assertions_type": "pass",