Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

ConStrain

A data-driven knowledge-integrated framework that automatically verifies that building system controls function as intended.
https://github.com/pnnl/constrain

Category: Consumption
Sub Category: Buildings and Heating

Keywords

bms building commissioning data hvac simulation verification

Last synced: about 24 hours ago
JSON representation

Repository metadata

Control Strainer (ConStrain) is a data-driven knowledge-integrated framework that automatically verifies that building system controls function as intended.

README.md

Control Strainer (ConStrain): A Data-driven Control Verification Framework (formally known as ANIMATE)

Unit tests status: Tests

Background and Motivation

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 cut commercial building energy consumption by approximately 29% - equivalent to 4-5 Quads, or 4-5% of the energy consumed in the United States. Driven by the significant control-related energy-saving potential, commercial building energy codes (such as ASHRAE 90.1) have progressed with many control-related addenda. For example, from the publication of 90.1-2004 to 90.1-2016 (four code cycles), 30% of the new requirements are related to building control (with most of them focused on HVAC system control).

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 (Cx) scope. The current control verification is often manually conducted, which is time-consuming, ad-hoc, incomplete, and error-prone.

What is ConStrain?

ConStrain is a data-driven knowledge-integrated framework that automatically verifies that controls function as intended. The figure below shows an overview of ConStrain and how it can be used. ConStrain was born out of the need of automating the verification of time-series data describing the behavior of building components, especially the control functions.

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.

While the development of ConStrain was motivated by use cases with building energy modeling (BEM), it is now evolved for more application scenarios towards real building control verification.

Overview of ConStrain

Who shall be interested in this framework?

  • Cx agent – reduce effort and cost, while increasing rigor.
  • Building operator – implement Continuous Commissioning (CCx) to avoid performance drift.
  • 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.

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

Publications

Referencing

If you wish to cite ConStrain in academic work please use: Lei, X., Lerond, J., Jung, Y. J., & Chen, Y. (2025). ConStrain (Version 0.6.0) [Computer software]. https://github.com/pnnl/ConStrain

Citation (CITATION.cff)

cff-version: 1.2.0
title: ConStrain
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - given-names: Xuechen
    family-names: Lei
    email: [email protected]
    affiliation: Pacific Northwest National Laboratory
    orcid: 'https://orcid.org/0000-0003-3310-9750'
  - given-names: Jeremy
    family-names: Lerond
    email: [email protected]
    affiliation: Pacific Northwest National Laboratory
    orcid: 'https://orcid.org/0000-0002-1630-6886'
  - given-names: Yun Joon
    family-names: Jung
    orcid: 'https://orcid.org/0000-0003-1311-8932'
    affiliation: Pacific Northwest National Laboratory
    email: [email protected]
  - given-names: Yan
    family-names: Chen
    email: [email protected]
    affiliation: Pacific Northwest National Laboratory
    orcid: 'https://orcid.org/0000-0002-2988-9136'
identifiers:
  - type: url
    value: 'https://github.com/github/ConStrain'
repository-code: 'https://github.com/github/ConStrain'
url: 'https://pnnl.github.io/ConStrain/'
abstract: >-
  Control Strainer (ConStrain): A Data-driven Control
  Performance Verification Framework (formally known as
  ANIMATE)
license: BSD-2-Clause
commit: 7f1798889b07e02cd126549e1c8ae5b1c89f24cd
version: 0.6.0
date-released: '2024-09-30'

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 8 days ago

Total Commits: 758
Total Committers: 9
Avg Commits per committer: 84.222
Development Distribution Score (DDS): 0.682

Commits in past year: 195
Committers in past year: 6
Avg Commits per committer in past year: 32.5
Development Distribution Score (DDS) in past year: 0.61

Name Email Commits
Xuechen (Jerry) Lei x****i@p****v 241
yunjoonjung y****g@p****v 221
Lerond, Jeremy j****d@p****v 216
FanFeng f****6@g****m 44
Julian Slane j****y@p****v 22
Jeremy Lerond l****3@c****l 5
Jeremy Lerond l****3@c****v 5
Yan Chen y****n@p****v 3
Jeremy Lerond l****3@c****v 1

Committer domains:

Issue and Pull Request metadata

Last synced: 2 days ago

Total issues: 20
Total pull requests: 73
Average time to close issues: about 1 month
Average time to close pull requests: 29 days
Total issue authors: 4
Total pull request authors: 5
Average comments per issue: 0.05
Average comments per pull request: 0.51
Merged pull request: 59
Bot issues: 0
Bot pull requests: 0

Past year issues: 14
Past year pull requests: 37
Past year average time to close issues: N/A
Past year average time to close pull requests: 20 days
Past year issue authors: 4
Past year pull request authors: 4
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.32
Past year merged pull request: 29
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pnnl/constrain

Top Issue Authors

  • lymereJ (12)
  • yunjoonjung-PNNL (4)
  • leijerry888 (3)
  • wehuang16 (1)

Top Pull Request Authors

  • lymereJ (26)
  • leijerry888 (18)
  • yunjoonjung-PNNL (15)
  • jslane-h (12)
  • Fan-Feng (2)

Top Issue Labels

  • bug (2)

Top Pull Request Labels

  • DO NOT MERGE (2)
  • enhancement (1)

Dependencies

.github/workflows/docs.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • peaceiris/actions-gh-pages v3 composite
.github/workflows/unit_tests.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • actions/upload-artifact v3 composite
requirements.txt pypi
  • eppy *
  • fuzzywuzzy *
  • matplotlib *
  • pandas *
  • scikit-learn *
  • scipy *
  • seaborn *
  • tqdm *
  • uuid *
setup.py pypi
  • eppy *
  • fuzzywuzzy *
  • matplotlib *
  • numpy *
  • pandas *
  • scikit-learn *
  • scipy *
  • seaborn *
  • tqdm *

Score: 5.598421958998375