JOSS paper submission

.github/workflows/draft-pdf.yml

@@ -0,0 +1,24 @@
+name: Draft PDF
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: ./docs/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: ./docs/paper.pdf

docs/paper.bib

@@ -0,0 +1,102 @@
+@inproceedings{bs2023_1660,
+  doi       = {10.26868/25222708.2023.1660},
+  url       = {https://publications.ibpsa.org/conference/paper/?id=bs2023_1660},
+  year      = {2023},
+  month     = {September},
+  publisher = {IBPSA},
+  author    = {Chen, Yan and Wetter, Michael and Lei, Xuechen and Lerond, Jeremy and Prakash, Anand K. and Jung, Yun Joon and Ehrlich, Paul and Vrabie, Draguna},
+  title     = {Control Performance Verification -- The Hidden Opportunity of Ensuring High Performance of Building Control System},
+  booktitle = {Proceedings of Building Simulation 2023: 18th Conference of IBPSA},
+  volume    = {18},
+  address   = {Shanghai, China},
+  series    = {Building Simulation},
+  pages     = {3848--3855},
+  issn      = {2522-2708}
+}
+
+@inproceedings{lei2023ashrae,
+  author    = {Lei, Xuechen and Lerond, Jeremy and Jung, Yun Joon and Chen, Yan},
+  title     = {Development of an Application Programming Interface for a Building Systems Control Performance Verification Framework},
+  booktitle = {2023 ASHRAE Annual Conference},
+  year      = {2023},
+  doi       = {10.63044/s23lei50},
+  url       = {https://doi.org/10.63044/s23lei50}
+}
+
+@inproceedings{bs2021_30725,
+  doi       = {10.26868/25222708.2021.30725},
+  url       = {https://publications.ibpsa.org/conference/paper/?id=bs2021_30725},
+  year      = {2021},
+  month     = {September},
+  publisher = {IBPSA},
+  author    = {Chen, Yan and Lerond, Jeremy and Lei, Xuechen and Rosenberg, Michael and Vrabie, Draguna},
+  title     = {A knowledge-based framework for building model performance verification},
+  booktitle = {Proceedings of Building Simulation 2021: 17th Conference of IBPSA},
+  volume    = {17},
+  isbn      = {978-1-7750520-2-9},
+  address   = {Bruges, Belgium},
+  series    = {Building Simulation},
+  pages     = {1943--1950},
+  issn      = {2522-2708}
+}
+
+@article{lei2021,
+  author  = {Lei, Xuechen and Chen, Yan and Berg\'{e}s, Mario and Akinci, Burcu},
+  title   = {Formalized control logic fault definition with ontological reasoning for air handling units},
+  journal = {Automation in Construction},
+  volume  = {129},
+  pages   = {103781},
+  year    = {2021},
+  issn    = {0926-5805},
+  doi     = {10.1016/j.autcon.2021.103781}
+}
+
+@misc{tspr,
+    title={TSPR Washington State Analysis Tool 2024.1.0},
+    author={{Pacific Northwest National Laboratory}},
+    howpublished={\url{https://energycode.pnl.gov/HVACSystemPerformance/}},
+    year={2024},
+    note={Accessed: 2024-04-044}
+}
+
+@techreport{impa_ctrl,
+    author       = {Fernandez, Nicholas E.P. and Katipamula, Srinivas and Wang, Weimin and Xie, YuLong and Zhao, Mingjie and Corbin, Charles D.},
+    title        = {Impacts of Commercial Building Controls on Energy Savings and Peak Load Reduction},
+    institution  = {Pacific Northwest National Lab. (PNNL), Richland, WA (United States)},
+    annote       = {Commercial buildings in the United States use about 18 Quadrillion British thermal units (Quads) of primary energy annually . Studies have shown that as much as 30% of building energy consumption can be avoided by using more accurate sensing, using existing controls better, and deploying advanced controls; hence, the motivation for the work described in this report. Studies also have shown that 10% to 20% of the commercial building peak load can be temporarily managed/curtailed to provide grid services. Although many studies have indicated significant potential for reducing the energy consumption in commercial buildings, very few have documented the actual savings. The studies that did so only provided savings at the whole building level, which makes it difficult to assess the savings potential of each individual measure deployed.},
+    doi          = {10.2172/1400347},
+    url          = {https://www.osti.gov/biblio/1400347},
+    place        = {United States},
+    year         = {2017},
+    month        = {05}}
+}
+
+@misc{os,
+    author       = {Ball, Brian and Long, Nicholas and Macumber, Dan and Benne, Kyle and Robertson, Joe and Weaver, Evan and Turner, Jason and Swindler, Alex and Hale, Elaine and DeGraw, Jason and others},
+    title        = {OPENSTUDIO® [SWR-07-40]},
+    annote       = {OpenStudio® is a cross-platform (Windows, Mac, and Linux) collection of software tools to support whole building energy modeling using EnergyPlus and advanced daylight analysis using Radiance. OpenStudio is an open source (LGPL) project to facilitate community development, extension, and private sector adoption. OpenStudio includes graphical interfaces along with a Software Development Kit (SDK). In addition to the graphical interface, OpenStudio allows building researchers and software developers to quickly get started through its multiple entry levels, including access through C++, Ruby, and C#. Users can leverage the Ruby interface to create OpenStudio Measures that can be easily shared and applied to OpenStudio Models. OPENSTUDIO® IS A REGISTERED TRADEMARK OF ALLIANCE FOR SUSTAINABLE ENERGY, LLC, THE MANAGER AND OPERATOR OF THE NATIONAL RENEWABLE ENERGY LABORATORY.},
+    doi          = {10.11578/dc.20171025.1817},
+    url          = {https://www.osti.gov/biblio/code-4561},
+    place        = {United States},
+    year         = {2016},
+    month        = {08},
+    note={Accessed: 2024-04-04}
+}
+
+@misc{osm,
+    title={OpenStudio SDK User Docs: Getting Started - About Measures},
+    author={{National Renewable Energy Laboratory, Argonne National Laboratory, Lawrence Berkeley National Laboratory, Oak Ridge National Laboratory, Pacific Northwest National Laboratory}},
+    howpublished={\url{https://nrel.github.io/OpenStudio-user-documentation/getting_started/about_measures/}},
+    year={2024},
+    note={Accessed: 2024-05-28}
+}
+
+@inproceedings{brick,
+  author = {Balaji, Bharathan and Bhattacharya, Arka and Fierro, Gabe and Gao, Jie and Gluck, Josh and Hong, Deokwoo and Johansen, Aslak and Koh, Jihyun and Ploennigs, Joern and Agarwal, Yuvraj and Whitehouse, Kamin and Taneja, Jayant},
+  title = {Brick: Metadata Schema for Portable Smart Building Applications},
+  booktitle = {Proceedings of the 3rd ACM International Conference on Systems for Energy-Efficient Built Environments},
+  year = {2016},
+  pages = {41--50},
+  publisher = {ACM},
+  doi = {10.1145/2993422.2993577}
+}

docs/paper.md

@@ -0,0 +1,75 @@
+---
+title: 'Control Strainer (ConStrain): a data-driven control verification framework'
+tags:
+  - python
+  - energy
+  - building
+  - control
+  - simulation
+  - hvac
+authors:
+  - name: Xuechen Lei
+    orcid: 0000-0003-3310-9750
+    affiliation: 1
+  - name: Jérémy Lerond
+    orcid: 0000-0002-1630-6886
+    affiliation: 1
+  - name: Yun Joon Jung
+    orcid: 0000-0003-1311-8932
+    affiliation: 1
+  - name: Julian Slane-Holloway
+    orcid: 0009-0008-9572-9123
+    affiliation: 1
+  - name: Fan Feng[^1]
+    orcid: 0000-0002-6230-0063
+    affiliation: 1
+  - name: Yan Chen
+    orcid: 0000-0002-2988-9136
+    affiliation: 1
+
+affiliations:
+ - name: Pacific Northwest National Laboratory, Richland, WA, USA
+   index: 1
+date: 28 May 2024
+bibliography: paper.bib
+---
+
+[^1]: Fan Feng contributed to this work while affiliated with Pacific Northwest National Laboratory (PNNL). He is no longer affiliated with PNNL at the time of publication.
+
+# Summary
+
+The Control Strainer, or `ConStrain`, is a Python-based framework that can be used by energy modelers, building engineers, and researchers to conduct consistent and automated verification of building system controls using either timeseries data generated from whole-building energy simulations or from actual building automation system (BAS) trend data. `ConStrain` is made of two distinct components: an expandable control verification algorithms library, and a consistent performance evaluation and reporting workflow framework. At its roots, `ConStrain`'s verification library was developed with the verification of control related building energy code requirements in mind, but it is built such that its library is expandable and can cover user-customized control verifications.
+
+# Statement of need
+
+Advances in building control have shown significant potential for reducing the cost of utility bills and improving building energy performance. Studies show that designs utilizing optimized controls that are properly tuned could cut commercial building energy consumption by approximately 29% - equivalent to 4-5 Quads, or 4-5% of the energy consumed in the United States [@impa_ctrl]. 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 [@lei2021]. A field study found that only 50% of systems observed have their control system correctly configured, and control-related compliance verification is typically not currently included in the commissioning scope.
+
+`ConStrain` focuses on formalizing and automating verification of HVAC controls by analyzing sensor and actuator data streams from building control systems [@bs2021_30725].
+
+`ConStrain` is an open-source library and a Python application programming interface (API) for analyzing building automation system (BAS) data streams for adherence to an operational specification, which can correspond to the building and building owner's needs [@lei2023ashrae]. Note that this API, in its current form, provides a software interface for other Python programs, not a web REST API service.
+
+`ConStrain` is also incorporating semantic modeling capabilities to enable automated configuration and deployment of verification [@bs2023_1660].
+
+`ConStrain` can be used as a standalone tool and can also be integrated into established workflows of third-party tools and practices. For instance, `ConStrain` has been successfully integrated as part of the continuous integration software development process of whole-building energy simulation-based software tool (e.g., Washington State's Total System Performance Ratio Analysis Tool [@tspr]) to make sure that software code contributions as well as simulation software updates do not have unexpected impacts on the simulated performance of building system controls. Moreover, a set of `OpenStudio` [@os] measures [@osm] have also been developed to enable building energy modelers using `OpenStudio` to have access to perform verification on their models with minimal configurations required.
+
+Currently, `ConStrain` requires each verification case to provide inputs in the same units as the expected data points defined for its verification item. Automatic unit conversion is not in the core workflow of `ConStrain`, so inputs shall be converted to the required units before being passed to `ConStrain`.
+
+## Comparison with existing tools and industry practices
+
+In current industry practices, HVAC control verification is often conducted manually by commissioning agents or facilities teams, or through proprietary trend data analytics solutions integrated into BAS. These tools, while valuable for fault detection and system monitoring, are generally vendor-specific, offer limited transparency, and are not purpose-built to ensure that control strategies intended to deliver energy savings are functioning as intended in actual operation.
+
+`ConStrain` distinguishes itself by offering:
+
+- A growing library of modular, reusable control logic verification tests
+- A flexible and local API for custom verification logic and report generation
+- Integration with semantic models [@brick] to enable automated verification case setup
+- Compatibility with both simulated and real BAS data sources
+- Seamless use in simulation and CI pipelines (e.g., OpenStudio [@os], TSPR [@tspr])
+
+These capabilities enable `ConStrain` to bridge the gap between simulation-based design intent and real-world implementation, supporting code compliance, model-based commissioning, and continuous performance verification.
+
+# Acknowledgements
+
+`ConStrain` is developed at the Pacific Northwest National Laboratory and is funded by the U.S. Department of Energy (DOE) under Contract DE-AC05-76RL01830. It is actively being developed as an open-source project.
+
+# References