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.

Core Classes and Functionality

Twin4Build provides several top-level classes for building, simulating, translating, calibrating, and optimizing building energy models:

• Model:
  The main container for your building system, components, and their connections. Use this class to assemble your digital twin from reusable components.

• Simulator:
  Runs time-based simulations of your Model, producing time series outputs for all components. Handles the simulation loop and time stepping.

• Translator:
  Automatically generates a Model from a semantic model (ontology-based building description). Enables ontology-driven, automated model creation.

• Estimator:
  Performs parameter estimation (calibration) for your Model using measured data. Supports both least-squares and PyTorch-based optimization.

• Optimizer:
  Optimizes building operation by adjusting setpoints or control variables to minimize objectives or satisfy constraints, using gradient-based methods.

All classes are accessible via the main package import:

import twin4build as tb

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

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,
            id="Position schedule")

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

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


model = tb.Model(id="example_model")
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. (2025). Large-scale field demonstration of an interoperable and ontology-based energy modeling framework for building digital twins. Applied Energy, 387, [125597]

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

[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},
}