twin4build: A python package for Data-driven and Ontology-based modeling and simulation of buildings

twin4build is a python package which aims to provide a flexible and automated framework for dynamic modelling of indoor climate and energy consumption in buildings. It leverages the SAREF core ontology and its extensions SAREF4BLDG and SAREF4SYST.

Its core features include:

• Automated generation of building energy models from semantic models (support for .rdf files is coming soon)
• Automated calibration of building energy models using data-driven methods

This is a work-in-progress library and the functionality is therefore updated regularly. More information on the use of the package, code examples, and detailed documentation is planned for the fall 2024.

Simulation model, including various components such as dampers, valves, spaces, sensors, and meters [1].

Simulation results, showing the predicted indoor temperatures compared to historical setpoint profile for different scenarios [1].

Simulation results, showing the accumulated setpoint violations in Kelvin-hours for different scenarios [1].

Examples and Tutorials

Below are some examples of how to use the package. More examples are coming soon.

Basics of Twin4Build

• Part 1: Connecting components and simulating a model
• Part 2: Modeling and control of indoor CO2 concentration

Automated Model Generation

To be added soon.

Model calibration

• Part 1: Calibration of a space model including temperature, CO2, valve positions, and damper positions

Scenario testing

To be added soon.

Performance monitoring

To be added soon.

Neural Policy Controller

• Part 1: Training a neural policy controller for the space model

Documentation

The documentation can be found online. Below is a code snippet showing the basic functionality of the package.

import twin4build as tb
import twin4build.utils.plot.plot as plot

def fcn(self):
    ##############################################################
    ################## First, define components ##################
    ##############################################################

    #Define a schedule for the damper position
    position_schedule = tb.ScheduleSystem(
            weekDayRulesetDict = {
                "ruleset_default_value": 0,
                "ruleset_start_minute": [0,0,0,0,0,0,0],
                "ruleset_end_minute": [0,0,0,0,0,0,0],
                "ruleset_start_hour": [6,7,8,12,14,16,18],
                "ruleset_end_hour": [7,8,12,14,16,18,22],
                "ruleset_value": [0,0.1,1,0,0,0.5,0.7]}, #35
            add_noise=False,
            saveSimulationResult = self.saveSimulationResult,
            id="Position schedule")

    # Define damper component
    damper = tb.DamperSystem(
        nominalAirFlowRate = Measurement(hasValue=1.6),
        a=5,
        saveSimulationResult=self.saveSimulationResult,
        id="Damper")

    #################################################################
    ################## Add connections to the model #################
    #################################################################
    self.add_connection(position_schedule, damper, 
                        "scheduleValue", "damperPosition")


model = tb.Model(id="example_model", saveSimulationResult=True)
model.load(infer_connections=False, fcn=fcn)

# Create a simulator instance
simulator = tb.Simulator()

# Simulate the model
stepSize = 600 #Seconds
startTime = datetime.datetime(year=2021, month=1, day=10, hour=0, minute=0, second=0)
endTime = datetime.datetime(year=2021, month=1, day=12, hour=0, minute=0, second=0)
simulator.simulate(model,
                    stepSize=stepSize,
                    startTime=startTime,
                    endTime=endTime)

plot.plot_component(simulator, 
                    components_1axis=[("Damper", "airFlowRate")], 
                    components_2axis=[("Damper", "damperPosition")], 
                    ylabel_1axis="Air flow rate", #Optional
                    ylabel_2axis="Damper position", #Optional
                    show=True,
                    nticks=11)

UML diagram of Twin4Build classes.

Installation

Python version	Windows	Ubuntu
3.9
3.10
3.11
3.12

The package can be installed with pip and git using one of the above python versions:

pip install git+https://github.com/JBjoernskov/Twin4Build

Graphviz

Graphviz must be installed separately:

Ubuntu

sudo add-apt-repository universe
sudo apt update
sudo apt install graphviz

Windows

On windows, the winget or choco package managers can be used:

winget install graphviz

choco install graphviz

MacOS

brew install graphviz

Publications

[1] Bjørnskov, J. & Thomsen, A. & Jradi, M. (Submitted 2024). Large-scale field demonstration of an interoperable and ontology-based energy modeling framework for building digital twins. Applied Energy

[2] Bjørnskov, J. & Jradi, M. & Wetter, M. (Submitted 2024). Automated Model Generation and Parameter Estimation of Building Energy Models Using an Ontology-Based Framework. Energy and Buildings

[3] Bjørnskov, J. & Jradi, M. (2023). An Ontology-Based Innovative Energy Modeling Framework for Scalable and Adaptable Building Digital Twins. Energy and Buildings, 292, [113146].

[4] Bjørnskov, J. & Jradi, M. (2023). Implementation and demonstration of an automated energy modeling framework for scalable and adaptable building digital twins based on the SAREF ontology. Building Simulation.

[5] Andersen, A. H. & Bjørnskov, J. & Jradi, M. (2023). Adaptable and Scalable Energy Modeling of Ventilation Systems as Part of Building Digital Twins. In Proceedings of the 18th International IBPSA Building Simulation Conference: BS2023 International Building Performance Simulation Association.

Cite as

@article{OntologyBasedBuildingModelingFramework,
    title = {An ontology-based innovative energy modeling framework for scalable and adaptable building digital twins},
    journal = {Energy and Buildings},
    volume = {292},
    pages = {113146},
    year = {2023},
    issn = {0378-7788},
    doi = {https://doi.org/10.1016/j.enbuild.2023.113146},
    url = {https://www.sciencedirect.com/science/article/pii/S0378778823003766},
    author = {Jakob Bjørnskov and Muhyiddine Jradi},
    keywords = {Digital twin, Data-driven, Building energy model, Building simulation, Ontology, SAREF},
}