AixLib: an open-source Modelica library for compound building energy systems from component to district level with automated quality management

Abstract

Open-source modelling libraries facilitate the standardization and harmonization of model development. In the context of building energy systems, Modelica is a suitable modelling language as it is equation-based and object-oriented. As an outcome of the IBPSA project 1 cooperation, four open-source modelling libraries have been successfully deployed which all share the core library Modelica IBPSA. One of them is the AixLib modelling library. AixLib supports different modelling depths ranging from component to district level and covers all relevant domains in the context of building energy systems. To ensure high-quality simulations, continuous integration has been successfully added to automatically compare simulation results with existing validation data. This paper presents AixLib's key features, scope, and associated tools. We present three use cases that highlight the broad application range of AixLib models. Furthermore, an overview of relevant research and industry projects is provided. Finally, we give an outlook on future development goals.

Keywords:

• Modelica
• modelling library
• continuous integration
• building energy system
• HVAC

1. Introduction

Over the last decades, simulative investigations have been successfully applied to improve the design and operation of building energy systems and can therefore contribute to reduce ${\mathrm{CO}}_2$ emissions in the building sector (Attia et al. 2012; Crawley et al. 2008a; Harish and Kumar 2016; Loonen et al. 2019). The basis for simulative investigations form high quality models. In this context, a multitude of modelling libraries has been successfully introduced. They differ in various aspects, such as their modelling language and principles, structure, level of detail, and scope.

In recent years, open-source modelling has become more popular among the scientific community leading to the existence of a great variety of modelling libraries for building energy systems. In addition, a good selection of scientific work has been published in the modelling language Modelica, resulting in an increase of Modelica-related studies by a factor of 18 between 1999 and 2019 (intentionally excluding pandemic-driven years 2020 to 2022 since it is considered a non-representative period) (Analyze Search Results). The same trends accelerated the development of open-source modelling libraries for Modelica models. At the time of research, the Modelica Association lists 105 open-source libraries (Modelica Association 2022). Among these, twelve libraries focus on building performance simulation or related aspects (Andresen et al. 2015; Bachmann et al. 2021; de Coninck et al. 2014; Jorissen, Reynders, et al. 2018; Leitner et al. 2019; Nytsch-Geusen et al. 2013; Plessis et al. 2014; G. F. Schneider et al. 2017; Wetter et al. 2019, 2014; Zimmer 2020).

This paper aims at presenting one of these libraries, called AixLib. AixLib is a Modelica modelling library for building performance simulations and is continuously being developed at the Rheinisch-Westfälische Technische Hochschule (RWTH) Aachen University, E.ON Energy Research Center, Institute for Energy Efficient Buildings and Indoor Climate in Aachen, Germany. The name originates from the French translation of Aachen as Aix-la-Chapelle.

We give an introduction to the library by answering the following questions:

1. What is the context of AixLib?

2. Why Modelica?

3. Which other relevant Modelica libraries exist?

4. Who is the target user?

5. Upon which principles is the library being developed?

6. What are the library's main application fields?

1.1. What is the context of AixLib?

As an outcome of the IEA EBC Annex 60 (Wetter et al. 2014) and Project 1 (Wetter et al. 2019) organized and partially funded by the International Building Performance Simulation Association (IBPSA), four open-source modelling libraries have been successfully published. Each individual library is managed by one of the Project 1 contributors. The libraries are Modelica Buildings¹ by the Lawrence Berkeley National Laboratory (LBNL) (USA) (Wetter et al. 2014), the BuildingSystems² by the University of the Arts (UdK) Berlin (Germany) (Nytsch-Geusen et al. 2013), the IDEAS³ by the Katholieke Universiteit (KU) Leuven (Belgium) (Jorissen, Reynders, et al. 2018), and the AixLib⁴ by the RWTH Aachen University (Germany) (Müller, Lauster, et al. 2016). As a joint effort, the libaries share a core library called Modelica IBPSA⁵ as well as the core principles, which we present in Section 1.5.

1.2. Why Modelica?

Modelica is an object-oriented, equation-based modelling language. It has been originally developed for complex systems that are described by coupling differential, algebraic, and discrete equations (Mattson and Elmqvist 1997). Building energy systems are categorized as such systems, which is why Modelica is perfectly suited for their modelling. Following Wetter et al.'s definition (Wetter 2009), we differentiate the modelling approaches discussed in this paper from the more traditional simulation programs. According to the authors (Wetter 2009), these traditional building simulation programs are based on imperative languages like, e.g., C/C++ or FORTRAN. Exemplary programs basing on such languages are EnergyPlus (Crawley et al. 2001) and DOE-2 (Winkelmann et al. 1993). These programs, i.e., their underlying languages, follow the idea that program developers include sequences of code assigning values to variables in a predefined order (Wetter 2009). Consequently, code for processing physical behaviour, data management, and numerical methods are mixed (Wetter 2009). Limitations of these modelling approaches lie, among others, in the following aspects (Radosevic et al. 2006; Wetter 2009; Wetter and Wright 2004):

• impeded code maintenance caused by the mix of code,

• a more difficult use of optimization methods due to nested solvers for components models causing numerical noise,

• a hampered co-simulation of models from other disciplines due to the missing separation of physical model description, data management, and solvers,

• often already implemented idealized component controls impeding detailed control system assessments, and

• rarely modelling the HVAC system dynamics for control-focused investigations.

These limitations motivated the choice of Modelica as modelling language for AixLib. Even though, the initial year of publication of Modelica is 1997, its ideas and principles trace back to the 1970s. In his dissertation, Elmqvist introduced a model language he refers to as DYMOLA, which is designed for ‘continuous dynamical systems’ (Elmqvist 1978). He highlights that both differential and algebraic equations can be introduced as true equations, meaning in their ‘original form’, and that these equations do not need to be transferred to typical assignment statements (Elmqvist 1978). In addition, Elmqvist developed this language from the perspective of an engineer aiming at simplifying connections mechanisms, i.e., the link between subsystems. Those are just some of DYMOLA's relevant features, shaping and motivating the development of Modelica. Modelica is the outcome of the ESPRIT project ‘Simulation in Europe Basic Research Working Group (SiE-WG)’ that started in October 1996 (Vangheluwe et al. 1996). In (Vangheluwe et al. 1996), the authors describe the main gap that Modelica is bridging by the following statement: ‘The main purpose is to make it easy to exchange models and model libraries and to allow for the end user to benefit from the advances in object-oriented modelling methodology’. This gap was successfully closed making Modelica a language for various domains that base on differential-algebraic equations (DAE) and can also incorporate discontinuities.

The object-oriented nature of Modelica is key for a modular model structure (Baldwin and Clark 2000) and is especially suitable for building performance simulations. In building energy systems, different domains are targeted (thermal, mechanical, electrical, hydraulic, ventilation, control) which becomes even more important in the context of the energy transition and the necessity of sector coupling. In addition, even though each building is different, we find repetitive subsystems. Object-oriented modelling supports more efficient modelling of such applications.

Even though Modelica is a well-suited modelling language for building energy systems, there are plenty of other relevant tools and languages. The following list shows exemplary modelling languages, libraries or simulation tools for building performance simulations. It is based on two review studies (in alphabetical order) (Crawley et al. 2008b; Harish and Kumar 2016): DesignBuilder (DesignBuilder Software Ltd 2023), DOE-2 (Hirsch 2016), EnergyPlus (Crawley et al. 2001), eQUEST (Hirsch 2016), ESP-r (Energy Systems Research Unit 2018), Facility Energy Decision System (FEDS) (Pacific Nothwest National Laboratory 2023), HEED (University of California 2023), IDA ICE (EQUA Simulation AB 2023), Matlab/Simulink (MathWorks 2023), and TRNSYS (Thermal Energy System Specialists 2019). The list contains selected commercially available and software distributed free of charge as well as user interfaces and their simulation engines, respectively. For example, we list both DesignBuilder and EnergyPlus even though the former is a user interface for the latter. Hence, EnergyPlus is a simulation engine but it can also be used for simulations without any interface. The same concept applies to DOE-2 and eQUEST. Still, these interfaces tremendously facilitate the work with such simulation engines. This is why we list them separately. In the context of this study, we focus on open-source software whose license is freely available since this facilitates implementations in both research and practice. Yet, we highlight that software whose licenses are commercially available like DesignBuilder, FEDS, IDA ICE, Matlab/Simulink, and TRNSYS are popular in both the scientific community and in practice despite not being open-source or license-free (Crawley et al. 2008b; Harish and Kumar 2016). The interested reader is referred to Harish and Kumar (2016), Crawley et al. (2008b) for a more detailed comparison of the listed and additional programs. When exluding the commercially licensed software, the list is reduced to ESP-r, DOE-2 and eQuest, HEED, and EnergyPlus. ESP-r is described as a ‘general purpose tool’ (Harish and Kumar 2016). Its strengths lie in building physics models but it also covers HVAC and electrical system models (Beausoleil-Morrison et al. 2014). Despite its wide scope, it requires a high level of expertise. This is especially true when it comes to implementing new HVAC models (Beausoleil-Morrison et al. 2014). Consequently, ESP-r has mainly been used in academia or by specialized experts up to now (Harish and Kumar 2016). Since the present study focuses on libraries covering all relevant domains and that are suitable for both beginners and experts, we exclude it from the subsequent analysis. Apart from that, despite its simplicity and, hence, user-friendliness, HEED mainly aims at the early design process. Consequently, it is not intended to support detailed operational analyses or coupled building performance simulations. Since the remaining simulation tools, namely DOE-2 and EnergyPlus are based on imperative languages, whose disadvantages have been pointed out above, we highlight the necessity of open-source, free software for building performance simulations. Modelica-based libraries can address this gap.

1.3. Which other relevant Modelica libraries exist?

As described in Section 1.1, AixLib is part of a joint work of four libraries which share the same core library. However, it is noteworthy that more open-source Modelica-based libraries exist. In a previous study (Wüllhorst, Maier, et al. 2022), the authors provide a detailed comparison of 12 open-source Modelica-based libraries. They qualitatively evaluate the libraries regarding the existence of models or packages for the domains hydraulic systems, ventilation, control, electrical, and building envelope. In addition, they assess the libraries' focus on coupled system simulations, their modularity, their parameterization effort, as well as the maintenance status. Based on the qualitative rating, AixLib's focus on fluid-based, especially hydraulic, components and subsystems as well as its good representation of models for ventilation, control, and the building envelope are highlighted. Furthermore, AixLib proves to be well maintained, to offer a good level of modularity and parameterization effort, and to enable simulations on system level. However, it becomes clear that, e.g., the Modelica Buildings library offers a better representation of building envelope models. Here, we like to highlight the provided interface to EnergyPlus (Wetter et al. 2021). Apart from that, the IDEAS and BuildingSystems library both provide more advanced models for electrical components such as photovoltaic systems and battery energy storage systems. In addition to the joint library development, other valuable modelling libraries exist that are also analysed by Wüllhorst, Maier, et al. (2022). The other assessed libraries are BuildingSysPro (Plessis et al. 2014), FastBuildings (de Coninck et al. 2014), ThermofluidStream (Zimmer 2020), dhcSim (Bachmann et al. 2021), DisHeatLib (Leitner et al. 2019), TransiEnt (Andresen et al. 2015), and BuildingControlLib (G. F. Schneider et al. 2017). While each of these open-source libraries is a valuable contribution to the scientific community, none of these libraries covers all relevant domains for building performance simulations. For instance, the BuildingControlLib contains a vast collection of control-related models and the DisHeatLib covers simulations on district level. Nonetheless, libraries covering all domains and, hence, facilitating the coupling of subsystems, are necessary. In addition, some libraries seem not to be maintained anymore. Consequently, the continuous enhancement and maintenance of the AixLib as well as the other Project 1-related libraries is a relevant contribution to research and practice. Nevertheless, it is noteworthy that the listed libraries can and should be used in conjunction with each other rather than only exclusively to exploit the quality of each individual library.

1.4. Who is the target user?

Even though AixLib addresses both industry and academia, the latter form the main target group. AixLib models derive from research and industrial projects as well as student theses and work. In addition, AixLib models are also used in academic teaching. Here, the graphical user interfaces of Modelica simulation environments tremendously facilitate the models' comprehensiveness and applicability. In addition, the object-oriented nature of Modelica supports rapid model generation, which is a requirement for the aforementioned target groups. From a researcher's perspective, AixLib facilitates fast knowledge exchange and harmonization of work. Apart from that, companies dealing with system modelling have already successfully used AixLib models. Among them are the German start-up heatbeat⁶ and the German company TLK Energy⁷. Despite Modelica's huge potential, the building sector is known to be a slowly adopting one. Digitization is the sector's declared aim, however, the process is slow compared to, e.g., the process industry (Domahidi et al. 2014). This is partially caused by missing know-how and the fact that each building is individual impeding the development of transferable models (Killian and Kozek 2016; Prívara et al. 2013). Consequently, the overall modelling process is time-consuming.

1.5. Upon which principles is the library developed?

We define the following general aspects as important features of a modelling library for holistic building energy systems and subsequently show how AixLib realizes these characteristics:

1. Modular model structure

2. Models for beginners and experts

3. Models cover all relevant domains

4. Adaptive modelling depth based on model aim

5. Model quality assurance

The first two characteristics (1) and (2) motivate the choice of Modelica as modelling language which is further explained in Section 1.2. Modularity also requires a standardized model structure and interfaces, which are discussed in more detail in Section 2.1. In addition, the enabling of equations similar to the actual physical principles as well as the graphical modelling increase comprehensiveness and motivate collaborative work while reducing the hurdle for beginners. The latter supports AixLib's use in academic teaching.

In addition to the previous features, sector coupling, poses further requirements on a modelling library for building energy systems. More specifically, the traditional focus on thermal and fluid-based energy systems in the context of HVAC systems is outdated and a need for compound system simulations arises. Consequently, models should not only cover the traditional HVAC-related domains such as fluid, ventilation and building envelope modelling but also include electrical and mechanical models as well as combined system models motivating requirement (3).

Furthermore, the challenges in the transition of the global energy systems demand different scales. While some scientists need highly accurate component-focused models to improve their efficiency or investigate different control strategies in detail, system modelling up to district level has become more and more important over the last decade. The latter focus, however, rather requires computationally efficient models with a reduced modelling depth and, hence, accuracy. These investigations require an adaptable level of detail since there is a trade-off between accuracy on the one hand and computational costs on the other hand. Therefore, a holistic modelling library should contain models of different levels of detail resulting in requirement (4).

Finally yet equally important, model validation is a crucial part of model development. We therefore listed quality assurance as essential characteristic (5).

1.6. What are the library's main application fields?

Several application fields for AixLib models exist, which we describe in the following. In Section 3, we present and discuss three exemplary fields in more detail and give an overview of related research projects that rely on AixLib models.

• Easy to implement building energy system or component models

  Building energy systems are highly dynamic and complex systems. Consequently, their modelling is challenging. Aixlib as well as the other modelling libraries emerging from Project 1 (Wetter 2019 and Wetter et al. 2019) help to reduce the complexity by unified interfaces, reduced parameterization, as well as simplified modelling approaches mostly following the gray-box principles. In addition, AixLib mainly introduces component-specific parameter records to enable user-friendly parameterization. This application field is exemplarily demonstrated in Wüllhorst, Maier, et al. (2022), Kümpel et al. (2022), Wüllhorst et al. (2021), Kremer et al. (2021).

• Supporting the design of building energy systems

  The sizing and operation of building energy system is a well-researched topic in the scientific community. Component sizing and selection in practice rather focus on static rules and expert-based decisions (Vering et al. 2021), while in scientific literature, they are often optimized based on simplified models. Dynamic simulations can support optimization-based approaches by computing a more realistic system behaviour. In addition, thermal load profiles generated from low- or high-order building envelope models are suitable to provide realistic boundary conditions for subsequent system design for both researchers and practitioners. AixLib supports these decisions by providing associated tools that automatically generate building models. For more information, about tools that interface with AixLib, we refer to Section 2.4. Examples of how simulation-based models support system design using AixLib models are given in Vering et al. (2021).

• Test ground and training data for control strategies

  To investigate different control strategies, simulation models serve as pre-tests before actual implementation in the real building. The realistic assessment of control strategies requires a detailed representation of both the building and HVAC dynamics (Wetter 2009). AixLib provides such models. Kümpel et al. (2021), Stoffel et al. (2021), Rätz et al. (2020) use AixLib models as a substitute for the actual building, while (T. Schreiber et al. 2020) generate training data for their reinforcement-learning-based controllers.

• Digital Twin concepts

  Digital twins have gained popularity in scientific research and target a realistic simulative representation of the actual plant behaviour. To decrease model errors, digital twins are often combined with calibration tools. For AixLib models, automatic calibration methods have been successfully developed further supporting their use as digital twins (see Section 2.4 and Vering et al. 2019, 2022).

• Design and control of district energy systems

  Simulations of district energy systems require computationally efficient models. In addition, the modelling focus is shifted from the building itself to the distribution system. AixLib models are suitable to support the simulative assessment for the design and control of district energy systems, which is demonstrated in more detail in Mans et al. (2019), Blacha et al. (2019), Lauster et al. (2014) and in Section 3.

• Hardware-in-the-loop models

  The representation of the building envelope in an experimental setup is challenging. Hardware-in-the-loop setups close this gap by coupling real hardware (e.g. the generation and distribution system) with a simulated system response (e.g. the building envelope). AixLib models like the high-order building model have been successfully used in this context (Mehrfeld et al. 2020).

1.7. Scope of work

Following the general motivation, the rest of this paper aims at presenting AixLib by giving an overview of its key features as well as its structure, scope, and associated tools.

We describe AixLib's structure in Section 2.1 and how the 5 distinct characteristics of modelling libraries are realized in Section 2.2. Furthermore, we specifically introduce our model quality management process, namely a Continuous Integration (CI) approach in Sction 2.3. Following this, we give an overview of associated open-source tools and interfaces, which are based on or use AixLib models Section 2.4. To better understand, how AixLib models can be applied, we present three different use cases in Section 3 and present research projects of various fields using AixLib models in Section 3.5. Limitations of the presented approaches and the library are discussed in Section 4. Finally, we conclude our study in Section 5 and give insights on future development goals in Section 6.

2. Implementation: library structure, features, and associated tools

The following section introduces the general library structure (see Section 2.1.1), a detailed overview of AixLib's packages (see Section 2.1.2), and its main characteristics and features (see Section 2.2). In addition, we present our automated model quality tool chain using CI (see Section 2.3) and associated tools working with or based on AixLib in Section 2.4.

2.1. Library structure

The following section focuses on AixLib's general package structure. Subsequently, we present selected models of AixLib to better outline the library's scope.

2.1.1. General library organization

At the time of publishing, AixLib consists of 12 different functional model packages, which consist of further sub-packages and models. The packages are categorized regarding their domain or subsystem type. AixLib's package structure for the top three package levels is depicted in Figure 1. As described in the previous section, all of the IBPSA Modelica libraries share the same core library and are extended by further models reflecting the respective institutes' research focus. Consequently, we will describe the general library structure containing both IBPSA-based and purely AixLib-based models first and will subsequently focus on the additional models of AixLib.

Figure 1. AixLib package structure comprising twelve packages.

Each package ideally contains a package with Example models as well as one with Validation tests. Except for the models in the two above-mentioned packages, models cannot be simulated under realistic boundary conditions without setting up a test model and connecting them to the necessary boundary models. In contrast, the Example and Validation package are all marked with a green triangle to indicate executable simulation models. Furthermore, potential BaseClasses are implemented in the lowest package level. Base classes are smaller block models, functions, or partial models, which form the basis of the respective package and are often inherited from. This structure is motivated by an aspired high level of modularity.

As an exception, the Obsolete package contains models, which the community does not maintain anymore. The package structure reflects the year in which the models were classified as obsolete. Still, we decided to include the Obsolete package as some of the models are being actively used by some projects, students, and developers.

2.1.2. Detailed description of packages

The library's structure is partially based on the modelling framework for building energy systems in general as depicted in Figure 2. Within the package structure, we separate physical modelling from the system's external influences. The boundary conditions, such as weather and user behaviour, as well as the controllers are examples of such external influences. By separating them from the actual physical system, we achieve a higher degree of modularity and more simplified parameterization. However, we highlight that AixLib provides interfaces to couple the physical models with their external boundary conditions and that both are included in the library. Their separation aims at increasing clarity and at a higher degree of modularity. The physical system itself is further divided into subsystems to facilitate model development and, again, increase modularity. Following the structure illustrated in Figure 2, we separate the HVAC components from the actual building envelope. The former comprise the energy conversion, storage, distribution, and transfer system on the one hand, and the mechanical ventilation on the other hand. The latter is a thermal representation of the actual building envelope. It can consequently be treated separately from the mostly fluid-based heating and cooling supply. Thermal connectors enable the coupling of both subsystems. Another demand that needs to be covered derives from domestic hot water (DHW). In the considered system setup, DHW is introduced as a separated subsystem, which is potentially connected to the residual HVAC subsystems via fluid connections. Apart from that, electrical components such as photovoltaic power plants are, again, separated from the HVAC and building envelope models. Electrical connections or real interfaces enable an exchange between the electrical subsystems and the HVAC and building envelope. This simplification is justified as the building energy system libraries' focus lies in the HVAC components and building envelope models and interactions between the electrical system and the former can often be neglected. Detailed assessments of the electrical system of building energy systems is (not yet) the focus of the AixLib but their consideration becomes more important in the context of sector coupling. We like to highlight at this point that the presented structure only gives orientation when working with AixLib models. In many cases, only a component or subsystem of the holistic framework is needed for the simulative assessment at hand. Yet, the library offers the possibility of compound, coupled building energy systems. Following these ideas, AixLib's structure includes a package Boundary conditions, containing models for, e.g. weather data or internal gains by users, lights, and devices. While the WeatherData model as well as the SolarGeometry, SkyTemperature, and SolarIrradiation packages derive from the IBPSA-core library, the Airflow, GroundTemperature, and InternalGains packages were added by AixLib developers. Introducing the boundary conditions as separate packages increases the modularity and facilitates their use for other models. For example, internal gains profiles need to be adapted depending on the building envelope model type or are also relevant to calculate electricity demands. The second package by order is the Controls package containing different control models in the context of building energy systems. In addition to the IBPSA-related models, AixLib provides application-specific control models to facilitate system modelling and simulation. For example, the package includes exemplary control models for air-handling units (AHU), ventilation, or heat pumps.

Figure 2. Structure of a building performance simulation. Connections with input/output causality contain arrows. Thermal and electrical connectors are depicted using squares. Fluid ports for water and air are bidirectional in Modelica. Nevertheless, we indicate the design direction (inflow / outflow).

Unlike the other libraries, AixLib models adopt the concept of component records. These records are collected in the DataBase package containing typical component parameters. By often basing on typical manufacturer data, the records facilitate model parameterization and show already implemented examples.

As domain-overarching simulations are key in innovative building performance simulations, an Electrical package is included in the library. It contains models of induction machines and photovoltaic systems. Since the model variety is still limited, future model development will focus on implementing more building-related electrical components such as batteries.

The Fluid package is one of the library's core packages. While many models originate from the IBPSA library, AixLib enhances the existing ones by, e.g. detailed chiller and heat pump models, and a solar thermal plant model. In addition, detailed and simplified storage models were added. It is noteworty that the AixLib development team also supports model deployment in the core library. Consequently, some models that were initially only part of the AixLib were moved to the core library so that all derivative libraries can use them.

All medium models are collected in the Media package. Here, the conventional mediums in building energy systems like water, air, and glycol-water-mixture derive from the core library. AixLib developers added further mediums, which are common in refrigeration cycles like R290 or R134a as well as a model for incompressible air.

To realize the features targeting a modular model structure and beginners and experts as model users, a Systems package has been introduced. This package addresses the difficulty of aggregating components into a fully robust system simulation by providing ready to use subsystems. These subsystems are highly modular facilitating their quick adaptation to different use cases. For example, the package HydraulicModules contains typical modules, reoccurring in buildings (Kümpel et al. 2022).

Furthermore, the package ThermalZones comprises two modelling approaches for the building envelope: a high- and a reduced-order modelling approach. The former enables the detailed assessment of buildings while the latter derives from the core library and aims at simplified and fast building envelope assessments. Again, we like to highlight that the AixLib development team did indeed support the model development for the reduced-order model, too, but focused on direct core library development in this case. Finally, the packages Utilities and Types contain auxiliary models for transformations as well as helpful functions.

2.2. Characteristics and main features

In Section 1, we define five important features that a modelling library should address. In this section, we demonstrate in what way AixLib realizes these features.

(1) Modular model structure has been identified as a favourable characteristic. In addition to the use of the Modelica language promoting modular modelling, AixLib enables modularity through mainly standardized interfaces, parameterization, variable and parameter naming, and model architecture. Some of these standardizations derive from IBPSA guidelines. Taking the Fluid package as an example, all models use the fluid ports of the Modelica Standard Library as interfaces (Modelica.Fluid.Interfaces). They enable quasi one-dimensional flows in piping networks for incompressible and compressible as well as one- or multiple-phase fluids. To facilitate the interaction of different submodels using the fluid ports, the Modelica-IBPSA library introduced nominal mass flow rates and pressure drops to standardize and facilitate the pressure and flow calculations. This concept is adopted by AixLib as well. In addition to the use of standardized parameter sets, the use of base data records facilitates the coupling of AixLib models. The package AixLib.DataBase contains these records, which on the one hand standardize the parameterization and on the other hand contain examples of relevant manufacturer data. Relying on manufacturer data to parameterize models is a unique approach among the Modelica-based modelling libraries. For early design stage decisions, this data might not be available. For this reason, we provide exemplary data records and some models work with general design parameters instead of specific records.

These features also support that AixLib is eligible for both beginners and experts in the field of building performance simulations, which we define as feature number (2). Both complex model formulations and system architecture can decrease the models' comprehensibility. The former is addressed by a deliberate implementation of models with different levels of detail and the gray-box principle. For example, the package AixLib.Fluid.HeatPumps includes a simplified heat pump model based on the Carnot efficiency and an already integrated internal supply temperature control. Additionally, the package includes a more detailed heat pump model, which is presented in Section 3.2. Regarding the latter, an additional package with already implemented fluid-based subsystems has been introduced (AixLib.Systems). Here, e.g. a selection of typical hydraulic circuits is integrated in the form of hydraulic modules (Kümpel et al. 2022). The authors describe how to reduce the required number of parameters by applying appropriate assumptions, which finally facilitates the systems' simulative assessment. Furthermore, two different modelling scheme for building envelope models are considered to address the challenge of developing such models due to their high complexity. These schemes are a high- and reduced-order model. The former is a detailed approach in which each zone is modelled with their actual thermal connection to the adjacent zones. The latter, on the other hand, aggregates zones according to their usage and neglects their detailed thermal connection. To simplify the parameterization of the reduced-order models, AixLib has an interface to TEASER (Remmen et al. 2018), which provides automatically parameterization and data enrichment based on archetypes. Reduced-order models tremendously facilitate the modelling process, especially when simulating on district level.

As feature (3), we identify that all domains, which are relevant for building performance simulations, should be included in a holistic modelling library. As described in Section 1, many valuable modelling libraries exist specializing on a specific domain or system type. For example, the FastBuildings aims at providing low-order and gray-box models of buildings for model predictive control applications (de Coninck et al. 2014). Moreover, the modelling library ThermoFluidStream focuses on models for complex thermofluid and refrigeration systems (Zimmer 2020). AixLib and the residual IBPSA-related libraries, however, aim to provide models for holistic building performance simulations. Consequently, AixLib targets to cover all relevant domains. To achieve this, AixLib provides models for the building envelope (AixLib.ThermalZones), electrical (AixLib.Electrical), and airflow (AixLib.Airflow), in addition to the Fluid package presented earlier. Furthermore, already implemented control strategies and subsystems in AixLib.Controls enable robust system simulations.

In addition to the previous characteristics, feature (4) addresses the consideration of the adaptive modelling depths based on the model's aim. We account for this feature by including models of different levels of detail. As described above, the package AixLib.ThermalZones covers two popular approaches to model the building envelope: the high- and a reduced-order modelling approach. Müller, Lauster, et al. (2016) present both approaches in detail and show that high order models are suitable for detailed, coupled building performance simulations, while reduced order models are more suited for large scale district simulations or early planning phase (Jansen et al. 2022). To demonstrate the different modelling depths using AixLib, we include both building model types in Section 3.2 and Section 3.3.

Finally, quality assurance is regarded as a key feature of modelling libraries. Here, we like to highlight that open-source modelling promotes a higher level of quality due to higher transparency. Furthermore, AixLib features both example and validation packages. The latter mainly contain field test or experimental data which are discussed in more depth in Section 2.3. These packages ensure that the models are used in the intended way and that changes in the code do not affect the validated outputs. Obviously, this does not apply if the models' outputs are intended to change due to faulty behaviour. In addition, we adopted the well-known process of CI to enable automatic quality checks.

2.3. Model quality management

To ensure the quality of AixLib and its models, different types of checks and tests are implemented. To automate the procedures of checking and testing, CI based on GitLab CI is used by mirroring the open GitHub repository of AixLib to RWTH Aachen University's own GitLab Server. Figure 3 illustrates the relevant stages of the CI. The order of the stages is realized in such a way that fast stages and those that can cause a change in the branch (e.g. HTML check) are executed at the beginning, while time-consuming ones are performed at the end. This prevents that time-consuming simulations are performed first and fast checks fail subsequently.

1. The first stage is an HTML-check, which validates and corrects the HTML-code inside the annotation section of each model. Any errors are corrected via an automatically created new branch. The user can subsequently review and merge the branch independently.

2. The Style-Check performs quality checks for each model using the Model Management Library of Dymola (DASSAULT SYSTEMES). Currently, we allow this stage to fail for existing models, while new models will need to fulfill the requirements. In the future, checks will also cover existing models. The following three stages are performed for all packages separately for easier error tracking.

3. The Check stage triggers the Modelica Check function for all models. Any syntactic or logical errors (e.g. a singularity of the system of equations) will cause this stage to fail.

4. Simulate performs a simulation for all example models. These are tracked based on the extended Modelica.Icons.Example icon model. Any unsuccessful simulation will cause this stage to fail.

5. Regressiontest is the final stage that uses reference results to verify that the simulation results of adapted models are in line with the already existing results. The regressions are performed using the BuildingsPy library⁸ (Wetter 2019).

6. Failed regression tests will trigger the preparation of dynamic plots and the deployment of an additional GitLab page, which will display the new and existing, i.e., reference, results based on Google Charts⁹.

Figure 3. The seven stages of AixLib's continuous integration.

As AixLib is based on the Modelica-IBPSA library¹⁰ an automated merge of the IBPSA library into the AixLib library is integrated as well. A branch called ‘IBPSA Merge’ triggers this process. In addition, all IBPSA models are excluded from the above-described checks based on a whitelist as they are maintained and verified in the Modelica-IBPSA library.

To simplify the work with the CI and to reduce the hurdle of creating regression tests, the option of communication via commit messages has been implemented. For example, messages can trigger the generation of new reference results for existing models. In addition, the CI automatically generates reference results for models with existing ‘simulate and plot’ scripts. The high degree of automation and the comprehensive control routines of this setup enable collaborative work with developers of different background and expertise. This is particularly important for the development of the AixLib, since many students work on it as part of their thesis and only learn Modelica in the course of their work. It further allows ensuring quality even in the fluctuating environment of a research institute across several generations of Ph.D. candidates.

In addition to the automated checking and testing, the quality of AixLib is ensured be verifying and validating the implemented simulation models. Judkoff and Neymark define three different validation types: analytical verification, empirical validation and intermodel comparisons (Judkoff and Neymark 2006).

AixLib follows these guidelines by implementing example and validation models which in turn are tested in the CI. The following example serves to demonstrate how AixLib implements the different types of validation for the building envelope side of building performance simulations. For this case, analytical verification is provided through single component examples, which verify the correct implementation of heat transfer through walls, windows and doors (e.g. in AixLib.ThermalZones.HighOrder.Components.Examples). Empirical validation is exemplary carried out by two building simulation models for a warehouse and a twin house building in AixLib.ThermalZones.HighOrder.Validation.

EmpiricalValidation. The models compare measurement data with simulation model results (Xanthopoulou et al. 2021). Intermodel comparisons are done by modelling the test cases provided in ASHRAE Standard 140 and include the existing comparison data into simulate and plot scripts for the high order and reduced order simulation models (Lauster et al. 2017; Xanthopoulou et al. 2021) (see AixLib.ThermalZones.HighOrder.Validation.ASHRAE140 and AixLib.ThermalZones.ReducedOrder.Validation.ASHRAE140). In addition to the building envelope, AixLib provides further validation for HVAC and equipment, as well. Two examples are the empirical validation of the enthalpy exchanger models in AixLib.Fluid.MassExchangers.

MembraneBasedEnthalpyExchangers.Validation (Kremer et al. 2019) as well as the empirical validation of the photovoltaic system model (Maier et al. 2021). The enthalpy exchanger model is validated based on 23 experimental investigations in the laboratory with different volume flow rates. The comparison of simulation results and measurement data shows that the simulation model is able to predict the enthalpy exchanger's operation and the resulting temperature and humidity within an acceptable deviation margin. The photovoltaic model has been validated by using measurement data from the National Institute of Standards and Technology (NIST). Again, the simulation model can predict the photovoltaic system's output accurately.

2.4. Associated open-source tools and interfaces for AixLib

In connection with the AixLib, various tools have been developed that use the AixLib models or enable the semi-automated generation of simulation models. The tools are listed in Table 1 and can be distinguished into two categories. The first ones are generative tools, which use automatic processes to generate Modelica models based on the AixLib library. For example, TEASER (Remmen et al. 2018) is used to create parametric building energy performance simulation models for buildings and districts. Bim2sim (Jansen et al. 2021) is a tool that can generate building energy performance simulation models as well as simulation models for energy systems and plant engineering. The basis in both cases is a Building Information Modelling (BIM) model. The generated models are based on models of the AixLib, too. The second category is automation and post-processing tools. Ebcpy (Wüllhorst, Storek, et al. 2022) provides functions to automate parametric studies by providing a simulation API running simulations directly with Dymola or via FMUs. Furthermore, it provides functions for the analysis and evaluation of time series and a connection for optimization. AixCaliBuHa (Wüllhorst, Storek, et al. 2022) allows the execution of sensitivity analyses and model calibration based on measured data. All mentioned tools are developed in Python since their execution in Modelica is either burdensome or not possible.

Table 1. Associated tools using or based on the AixLib library.

Toolname	Generative	Automation & Postprocessing
TEASER${}^{\mathrm{a}}$	X
uesgraphs${}^{\mathrm{b}}$	X
bim2sim${}^{\mathrm{c}}$	X
ebcpy${}^{\mathrm{d}}$		X
AixCaliBuHa${}^{\mathrm{e}}$		X

${}^{\mathrm{a}}$https://github.com/RWTH-EBC/TEASER

${}^{\mathrm{b}}$https://github.com/RWTH-EBC/uesgraphs

${}^{\mathrm{c}}$https://github.com/BIM2SIM/bim2sim

${}^{\mathrm{d}}$https://github.com/RWTH-EBC/ebcpy

${}^{\mathrm{e}}$https://github.com/RWTH-EBC/AixCaliBuHA

3. Applications

In Section 2.2, we describe in which way AixLib realizes the favourable features of modelling libraries as explained in Section 1. In this section, these aspects are demonstrated based on 3 exemplary use cases. The use cases aim at providing examples of how to work with AixLib models. They range from detailed component level models and a complex coupled building and heat pump system to the simulation study of a district heating system. In addition, an example of the interaction with one of the supplementary open-source tools is given.

3.1. Use case 1: control development and testing of air-handling units

The energy efficient operation of building energy systems requires optimal control strategies. The AixLib library offers dynamic models of different building energy systems that can be used to develop and tune control algorithms before implementing them in the real system. For this reason, Kümpel et al. (2022) developed hydronic models for AHUs which are combined to a generic modular AHU model. They calibrated the hydronic models to experimental data and used the models for controller testing and tuning.

3.1.1. Description of use case

In this use case, we introduce a combined system consisting of the mentioned modular AHU model and a thermal zone (see Figure 4). The components of the AHU are selectable by check boxes and drop down menus in the parameter list. In the considered use case, the AHU consists of a preheater, a heat recovery system, a cooler, a reheater, and a steam humidifier. Consequently, the modular model is configured to inherit the modules of these sub-components. The hydronic circuits of the heat exchangers are mixing circuits consisting of a pump and a mixing valve each. All sensor data and actuator signals are included in an expandable connector. Thus, there is only one connection needed to connect a controller with the AHU. Furthermore, the thermal zone model represents an office zone with an occupancy profile according to the swiss guideline SIA 2024 (Schweizerischer Ingenieur-und Architektenverein 2006). Here, we use standardized weather scenarios, namely the test reference year (TRY) weather data of Germany's Meteorological Services, from the city of Aachen, Germany. The use case is accessible to use, inspect and modify in the AixLib library (see: https://github.com/RWTH-EBC/AixLib, path: AixLib.Systems.ModularAHU.Examples.DemandControlledAHU). Since the use case is open-source in AixLib, we do not elaborate on the algorithms of the individual models here. For more detailed information, we also refer to Kümpel et al. (2022), Lauster et al. (2014). The scope of the use case is to show the influence of demand controlled ventilation (DCV) on the control quality of the AHU's temperature control. The DCV strategy is based on CO₂ concentration in the zone that is directly linked to the presence of persons. Hence, the supply air volume flow is controlled to fulfill the requirements regarding indoor air quality and reducing the air change rate at the same time. For this purpose, we use a cascade controller that adjusts this setpoint for the volume flow rate in the primary controller. The secondary controller controls the pressure increase over the supply and extract air fans based on the setpoint volume flow rate. Additionally, PI controllers manipulate the supply air temperature by adjusting the water's inlet temperature by controlling the mixing valve position in the hydronic circuits of the preheater, cooler, and reheater. An additional PI controller manipulates the steam mass flow rate to control the humidity. Both temperature and humidity are controlled to reach constant supply air conditions of ${20}^{\circ }\mathrm{C}$ and 40% relative humidity. We refer to Kümpel et al. (2022) for detailed information on parameter tuning methods and experimental validation using the hydronic models of the presented AHU. Additionally, we simulate a controller with constant supply air volume flow to compare different control approaches.

Figure 4. The air-handling unit use case with Modelica-specific icons. The system boundaries (e.g. exhaust air, outdoor air, etc.) set predefined input values for the system like the inlet temperatures and pressures. The controller and weather data are external boundary conditions which are connected via signal busses. The building model and the air-handling unit are connected using fluid ports.

3.1.2. Exemplary results

Figure 5 shows the supply air temperature, the valve setpoint of the heater, the air volume flow rate and the CO₂ concentration of the zone for one exemplary winter day, comparing constant volume flow and DCV. We observe that the supply air temperature in the case of the DCV oscillates while the constant volume flow control leads to a nearly constant supply air temperature of ${20}^{\circ }\mathrm{C}$. The oscillations of the DCV are due to the changes of the air volume flow rate which leads to different heating loads and thus to fast control action of the valve position of the heater. Moreover, the heating power of the DCV is lower compared to the fixed volume flow control as the lower valve position of the reheater indicates. With the information derived from the system model used in this case study, it is possible to test a control strategy and dynamic interactions of different control loops in detail. Further, the tuning of the PI controllers could be improved in order to reduce the control oscillation. Thus, the AixLib library enables the analysis and performance prediction of more complex control strategies without carrying out cost-intensive experiments.

Figure 5. Exemplary results for the air-handling unit use case.

This use case further demonstrates how control strategies can be tested by using pre-defined systems implemented in the AixLib. The system can be easily extended by adding further thermal zones and duct systems such as applying heat and cold generation and distribution models for the hydronic coils. In this way, the testing and optimization of complex control strategies for building energy systems can be realized easily.

3.2. Use case 2: coupled building and HVAC simulation

The design and control of all-electric heating systems requires the consideration of several interdependencies, such as the system's inertia, thermal comfort, and power consumption. Design and control are intertwined. To account for this interaction, coupled dynamic simulations, i.e., simulations coupling the building envelope and the HVAC system models, are suitable. The AixLib presents component models to compose a coupled building and HVAC simulation. Thus, we highlight the design and control aspects of an all-electric retrofit heat pump system in the following use case.

3.2.1. Description of use case

The coupled simulation model consists of a heat pump, a thermal energy storage, eight radiators, and a building envelope with 11 rooms, of which 8 rooms are heated. Figure 6 depicts the system layout. One task for such a system is to size the thermal energy storage and set the heat pump's control parameters. In this use case, a typical PI controller adjusts the heat pump compressor speed to follow the set temperature of the upper storage layer. A linear heating curve determines this set temperature according to the current outdoor air temperature. As the storage size influences the inertia, we postulate the necessity for integrated sizing of the storage volume V (design) and PI parameters (control, proportional gain k, integral gain $T_{\mathrm{I}}$). For the integrated optimization of design and control, we deploy a full factorial design. Table 2 lists the factors and levels.

Figure 6. Coupled building energy system layout of use case 2 with a hydronic heat pump system.

As the use case is only a proof of concept, we simulate it over the course of two days. The first day ensures the initialization of thermal masses. The second day provides information about the electricity consumption of the heat pump $W_{\mathrm{el}}$, and the average control quality in all rooms $\mathrm{\Delta }{T}_{\mathrm{Comfort}}$ on a winter day. The building model in use has a nominal heating load of 5.8 kW at a nominal outdoor air temperature of $-{12}^{\circ }\mathrm{C}$ according to European standard EN 12831 (German Institute for Standardization 2017).

Table 2. Factors and levels of the full factorial design in use case 2.

Factor	V in l	k	$T_{\mathrm{I}}$ in s
Min	100	0.01	10
Max	1900	0.2	300
Number of levels	10	5	5

The study is conducted using one of the associated tools called ebcpy (Wüllhorst, Storek, et al. 2022), which enables multiprocessing and straightforward visualization of results (Wüllhorst, Storek, et al. 2022). The Resources folder in the AixLib contains the Python script used to conduct and analyse this use case.

3.2.2. Exemplary results

Figure 7 depicts the results of this use case. Both room temperatures of the thermal zones with different setpoints and result metrics ($W_{\mathrm{el}}$ and $\mathrm{\Delta }{T}_{\mathrm{Comfort}}$) are given. Overall, $W_{\mathrm{el}}$ ranges from 72 kWh to 110 kWh. For $\mathrm{\Delta }{T}_{\mathrm{Comfort}}$, values range between 169 kh and 206 kh. In the following, we highlight four different parameter combinations.

Figure 7. Room temperatures for rooms with different temperature setpoints for four combinations (a-d) of storage volume $V_{\mathrm{Sto}}$ and PI parameters ($k_{\mathrm{HP}}$ and $T_{\mathrm{I},\mathrm{HP}}$).

Figure 8. GIS illustration of Shamrockpark district for third use case.

In case (a), the maximal electrical power demand is obtained. However, realizing a discomfort of 175 Kh, this case shows 4.1% lower control quality compared to the best case (b).

Assuming the same storage volume and proportional gain, but lowering the integral gain in case (b), $W_{\mathrm{el}}$ decreases by 17% compared to the worst case. At the same time, we achieve the highest control quality. Comparing the hobby room temperatures, this difference becomes apparent. Case (b) results in a near-optimal control deviation, while case (a) takes longer to reach the setpoint and longer to converge to the setpoint after the initial overshoot. Looking at smaller storage volumes, we highlight two further aspects.

First, both cases (c) and (d) reach the setpoints faster, especially for the highest setpoint in the bath. With similar control values as in case (a), case (c) shows a reduction of 18.6% in $W_{\mathrm{el}}$ compared to the worst case, but the overall lowest control performance. Finally, the influence of the proportional gain is notable by means of case (d). With the smallest storage and a $k_{\mathrm{P},\mathrm{HP}}$ of 0.01, case (d) achieves the lowest electricity demand. At the same time, the control quality is only 9.5% lower compared to the best case (b). However, control performance could be improved by optimizing the PI values of the thermostatic valves, as the living and bathroom temperatures oscillate.

This proof of concept shows several interdependencies, which have to be taken into account, when designing and controlling a building energy system. The AixLib enables detailed analyses and optimization of both the design and control domains. In addition, it enables detailed analyses of coupled HVAC and building envelope models as demonstrated for this use case.

3.3. Use case 3: thermal demand simulation of district heating system

The third use case describes another application area of the AixLib, covering large-scale system simulation of urban energy systems. This includes, on the one hand, the determination of dynamic demand profiles for heating and cooling of urban districts. On the other hand, it covers the modelling and simulation of central supply structures such as thermal networks, central energy supply units, and the technical equipment rooms of individual buildings. Using a simplified building model, the so-called reduced-order model, representing a substitute model using resistances (R) and capacities (C), thermal simulations can be realized for large building stocks of urban districts. The use of archetypes, containing statistical data of the historical building stock, allows a fast parametrization for specific buildings types by specifying minimal information, such as building use, age of construction as well as floor area and height. The transfer to specific building models is done via the open-source python tool TEASER (Remmen et al. 2018), which calculates values of resistances and capacities based on the building information and uses them for model parameterization (also see Section 2.4).

3.3.1. Description of use case

The use case presented here shows the application of the AixLib for the planning and investigation of the operational behaviour of 5th generation district heating and cooling networks. This is illustrated by the example of the Shamrockpark in Herne, Germany, which is also part of the research project TransUrban.NRW (Blacha et al. 2019). The area of the site is approximately 100,000 ${\mathrm{m}}^2$, on which a number of new buildings are being constructed alongside existing buildings. This creates a mixed-use district with 24 residential buildings, office buildings, a hotel, and data centres. The district is supplied with heat and cold by a heating network of the 5th generation, Figure 9 shows the representation of the district heating network in a geographic information system (GIS). Heating and cooling are supplied at constant temperatures of ${12}^{\circ }\mathrm{C}$ in the cold pipe and ${22}^{\circ }\mathrm{C}$ in the warm pipe. Decentralized heat pumps raise the temperature to the required level of the specific consumer. The modelling of the individual components and the resulting structure of the system model are described in more detail in Blacha et al. (2019); Mans et al. (2019). Figure 9 shows a Modelica graphics view of the northern part of the district heating network model.

Figure 9. Modelica graphics view on northern part of Shamrockpark district. For better visualization the southern part is not illustrated. However, the same modelling principles apply.

3.3.2. Exemplary results

As described in the previous section, we use the Python tool TEASER to parameterize a whole district and simulate the heating and cooling demands using a reduced-order model. Figure 10 shows the aggregated heating and cooling demands over the course of a year in a 1-hour resolution. While the heating demand reflects the expected heating behaviour with almost no heating demand over the summer and higher heating demands in the winter months, we observe a steady cooling demand during winter. This is primarily caused by the data centre resulting in a high demand overlap coefficient (Wirtz et al. 2020) and enabling significant balancing effects between the individual prosumers. The presented tool chain supports practitioners and researchers in, e.g. optimizing the district's energy supply system design as well as its operation. This becomes even more important since interactions on district level are too complex to be dealt with by applying rule-of-thumbs or normative standards. Here, the demand's temporal resolution is especially important. In a subsequent step, the thermal demands are taken as inputs for a simulation of the energy supply and distribution system. Figure 11 illustrates the exemplary results of the central energy supply. The energy supply system is modelled using AixLib's pipe, boiler, and chiller models. In this case the waste heat is used to cover the heat demand, the boiler is only used in maintenance periods as a back up system. The balancing effects due to simultaneous heating and cooling demands can be identified from the comparison between the demands shown in Figure 10 and the central energy supply shown in Figure 11.

All in all, this use case highlights the need for simulations on district level taking a 5th generation called Shamrockpark in Germany as an example. The use of reduced-order modelling approaches is suitable for large-scale simulation of districts as it is a good compromise between accuracy and computational costs. We defined this feature as essential library characteristic no. (4) (see Section 1).

Figure 10. Annual performance simulation of thermal demands of the whole Shamrockpark district in Germany.

Figure 11. The energy supply structure to meet heating and cooling demands.

3.4. Computational performance evaluation

In addition to the accuracy of the presented use cases, the library's aim is to provide real-time capable models. Fast models facilitate model application in practice. To evaluate the computational performance, all use cases were executed on the same machine.¹¹ To assess computation time, the simulations were carried out ten times. A comparison reveals that deviations are negligible. As a solver, Dassl was used with a step size of 900 s.

Table 3 lists relevant statistics of the three use cases. All three cases are large system models with 11,456 up to 49,168 equations. It is worth highlighting that these large equation systems are solved jointly and with a variable step size solver (see Section 1.2). Different controller settings (e.g., like in use case 2a to 2d) influence the number of state events and, hence, the step size and computational time. Overall, a real-time factor, the ratio of simulation to computational time, ranges between 1395 for the largest and 10390 for the smallest model. The selected annual simulations of large systems result in long simulation times. While considerable research effort has already been spent in boosting the simulation performances of such systems, we like to hightlight that the selected use cases were not tuned accordingly. Thus, we assume a potential reduction in computation time when following guidelines such as Jorissen et al. (2015), Jorissen, Wetter, et al. (2018). Nonetheless, the evaluation proves that AixLib models are suitable to investigate complex systems in a reasonable time.

Table 3. Computation time, simulation time, number of model equations, number of state events, and the real-time factor for the three use cases. Use case 2 includes the four cases highlighted in Figure 7.

Use case	Computation time	Simulation time	Number of state events	Number of equations	Real-time factor
1	58.2 s	7 d	51	11456	10390
2a	18.1 s	2 d	25	25136	9547
2b	19.2 s	2 d	25	25136	9016
2c	22.4 s	2 d	45	25136	7711
2d	21.6 s	2 d	23	25136	7992
3	6.3 h	365 d	45402	49168	1395

3.5. AixLib in practice: project overview

In addition to the various applications that AixLib can be used for, its models commonly form an important base for research and industry projects and inhere real-world applications. To get a better understanding, how AixLib models can be applied by both researchers and practitioners to real-world problems, we include a selection of research projects in which AixLib models were successfully applied in Table 4. We like to highlight at this point that we only include an excerpt of all relevant projects to prove AixLib's wide range of applications. In addition, only research projects were added with the most relevant reference. Yet, AixLib models have so far been used in more research projects as well as more studies accompanying these projects. Based on Scopus document search, AixLib has been part of approximately 150 research studies (Scopus 2022).

Table 4. Excerpt from research projects succesfully applying AixLib models.

		Relevant components								Scale			Building type
Name	Description/aim	HP	B	Ch	AHU	TES	CTES	Bui	HN	dis	BES	C	R	NR	Ref. no.	Rel. citat.
AGENT	Agent-based model predictive control							x			x			x	03ET1495	Storek et al. (2022)
BIM2Sim and BIM2Praxis	Semi-automatic creation of dynamic simulation models based on BIM	x	x	x	x	x	x	x			x			x	03ET1562	Jansen et al. (2021)
Digital Twin	Digital twin for heat pump	x										x	x		03EN1022	Vering et al. (2022)
dECOnhealth	Demand controlled ventilation in hospitals				x			x			x			x	03ET1568	Rätz et al. (2020)
EESchwimm	Analysis of energy efficiency measures for swimming facilities using dynamic simulation		x		x	x		x			x			x	03EN1004	Kühn et al. (2022)
EnModuS	Influence of reduced air change rates in retail buildings on indoor air quality and energy consumption				x			x			x			x	03ET1502	Finkbeiner et al. (2021)
FUBIC: All-electricity	Demand calculation and digital twin for optimal control of laboratory and office building	x			x	x	x	x			x			x	03EN3026	Henn et al. (2022)
LivingRoadmap	Development of an energy supply concept with model predictive control based on a modernization roadmap		x	x				x	x	x				x	03ET1352	Wetter et al. (2019)
Moisture Recovery Systems	Potential analysis of enthalpy exchangers in air-handling units				x			x				x		x	25EWN	Kremer et al. (2019)
OOM4ABDO	Topology detection of sensor networks and fault detection in air-handling units	x	x			x					x			x	03SBE0006	Stinner et al. (2022)
TransUrban.NRW	Digital twin of four city districts for design and control optimization	x		x		x		x	x	x	x		x	x	03EWR020	Blacha et al. (2019)
Urban Energy Lab 4.0	Realistic emulation of future city concepts in a highly interconnected infrastructure	x						x			x		x	x	EFRE-0500029	Streblow (2022)
ZUGABE	Future hydraulic networks and their standardization in buildings	x	x	x	x	x	x	x			x	x	x	x	03ET1298	Kümpel et al. (2022)

Notes: The research projects differ regarding their aim, the components assessed, and the level of detail. The following abbreviations apply: HP:=Heat pump, B:=Boiler,Ch:=Chiller, AHU:=Air-handling unit, TES:=Thermal energy storage, CTES:=Cold thermal energy storage, Bui:=Building, HN:=Thermal network dis:=District, BES:=Building energy system, C:=Component, R:=Residential, NR:=Non-residential, Ref.No.=Reference Number of funding source, Rel. citat.:=Relevant citation.

We distinguish the use of AixLib models regarding the components focused on (e.g. heat pumps, boilers, chillers, AHUs, thermal energy storages, cold thermal energy storages, etc.), the project's level of detail (district, building, component) as well as building types assessed (residential, non-residential). While most of the projects focus on the overall building energy system, some projects investigate selected components in more depth. For example, the Digital Twin project (Vering et al. 2022) improves modelling of heat pumps while the Moisture Recovery Systems project investigates different measures to recover moisture in ventilation systems. In contrast to these detailed assessments, three of the selected projects investigate whole districts. While one of the use cases, namely the Shamrockpark district which is the research object of the project TransUrban.NRW, has already been discussed in detail in the previous section (use case 3), there are also other districts that rely on AixLib models. As an additional example, we chose the project LivingRoadmap which is a living lab, further enhancing model validation in practice. In these projects, the district energy system's design and operation are optimized using mathematical optimization. Simulative assessments serve as instruments for pre-analyses of the optimization results. Here, a compromise between model accuracy and modelling depth had to be found to account for the multitude of subsystem in the whole district.

Among the projects focusing on the individual building energy system, AGENT and dECOnhealth are control-oriented projects. Within the project AGENT, agent-based building automation strategies are investigated and the infrastructure requirements are evaluated. Additionally, advanced control strategies like (distributed) model predictive control are tested. Additionally, dECOnhealth aims to improve building energy performance by demand-controlled ventilation. Consequently, the used models need to present the system's operational behaviour in an accurate way (also compare use case 1 in Section 3.1). Apart from that, the project BIM2Sim and BIM2Practice (original German title BIM2Praxis) investigates a generic approach to automatically generate Modelica- and AixLib-based models from BIM data. This approach is also maintained as one of the associated tools from AixLib further enhancing sector coupling and a holistic building planning process (see Section 2.4).

Residential and office buildings are the most common research objects in the building performance simulation domain. Nonetheless, it is the residual, more rare building types which also need energetic assessments and model validation, respectively. The projects EESchwimm, dECOnhealth, and FUBIC are all examples of such research objects. While in EESchwimm, the aim is the energy analysis of swimming pools, the dECOnhealth project focuses on hospitals. FUBIC, in contrast, investigates a laboratory and office building.

To summarize the main findings of this chapter, we proved that AixLib is suitable for a wide range of building performance simulation use cases. In addition to the three use cases, each differing regarding its level of detail, aspired accuracy, components assessed, and boundary conditions, we additionally gave 14 exemplary research projects that are based on and enhance AixLib models. It is the continuous work and investigations by all involved researchers that improve the library's quality and scope.

4. Limitations

AixLib is a modelling library targeting engineers who focus on district and building energy systems. Consequently, the library primarily comprises models for HVAC components and subsystems and their interactions with the building envelope. As such, the building envelope, itself, is a 1-d-simulation model of limited complexity. Even though, we include a reduced- and a high-order modelling approach, specialized software for detailed (3-d) building envelope simulations exist that clearly outperform the building envelope models in our library. Exemplary tools are EnergyPlus (Crawley et al. 2001) or IDA-ICE (EQUA Simulation AB 2023). The approaches implemented in the AixLib target the building envelope's implementation in conjunction with an HVAC simulation. Consequently, the focus lies on a purely energetic assessment. Still, these simplifications might impede some applications.

In addition to that, despite the aim to simplify model parameterization, some models are time-consuming and error-prone to work with. We take the high-order building envelope model as an example. Driven by the aim to enable a modular system setup, modelling a whole building envelope model based on the high-order approach is time-consuming. This motivated the coupling of external building envelope software like Spawn of EnergyPlus (Wetter et al. 2022). Spawn of EnergyPlus is an open-source simulation engine, enabling the coupling of EnergyPlus' heat transfer, daylighting, and internal load computations with HVAC and control models in Modelica (Wetter et al. 2022). Nonetheless, if users want to model all relevant components of a building energy system using one language, AixLib provides the required models.

Apart from that, AixLib promotes open-source development and easy accessibility, resulting in the fact that developers of almost any expertise level can contribute. While this increases the model variety and simplifies the modelling start, it inherently leads to not perfectly aligned models that clearly differ in their numerical performance. The implemented CI solely compares whether model changes affect the reference results and whether syntax error exist. However, there is no toolchain that sets any thresholds on the computational efficiency or the general model structure. Consequently, the models' computational performances differ significantly (see Section 3.4). The broad range of contributors also leads to the tendency that models are applied to use cases they were not initially validated for. This is partially caused by a superficial documentation. Nonetheless, this risk also exists for any commercial software.

Furthermore, even though unified parameterization exists for most of the packages, the same parameterization concept cannot be applied on all model types. For example, the idea to reduce the parameter set to design parameters like a nominal mass flow rate and a nominal pressure difference, is suited to fluid-based systems and components. Consequently, the same parameter set is not used in, e.g., the electrical package.

Apart from that, at the time of publishing, not all models but a great share is compatible with open-source simulation environments like OpenModelica. The reasons for some models not to be compatible with, e.g., OpenModelica are:

• the derivation from the upstream library Modelica IBPSA,

• the integration of state machines, and

• the use of the sdf format.

5. Conclusions

This paper presents the open-source Modelica library AixLib, which is part of the cooperation within Project 1 organized by the International Building Performance Simulation Association (Wetter et al. 2019) (see Section 1). Choosing Modelica as a language aims at facililtating the use of the modelling library since no expensive licenses are required. AixLib enables modular system design, which is especially crucial for effective model development in building energy systems (Wüllhorst, Maier, et al. 2022). To realize this, AixLib uses unified interfaces and also provides aggregated subsystems that can be easily combined (see Section 2.2). In this context, we demonstrate in this paper that models for all of the relevant domains, namely HVAC, building envelope, electrical components, and external as well as internal boundary condition models are available (see Section 2.1). The existence of all relevant domains is of major importance as the energy transition requires the interconnection of the domains and the possibility to analyse their dynamic interaction (see Section 1). In order to achieve a high model quality, we introduced a continuous integration process performing automated model validation (see Section 2.3). In Section 2.3, we also give some examples on what types of validation we apply.

The interconnection of subsystems leads to an increase in complexity, enhancing the significance of simulation studies for building energy system design and operation. However, the know-how on using simulation methods in practice is still limited and static calculation schemes are used instead. We want to promote the use of simulation models in practice by relying on gray-box modelling and enabling the incorporation of manufacturer data. Therefore, we included a DataBase package in our library and provide some exemplary performance data for, e.g., heat pumps, photovoltaic systems, and building walls (see Section 2.1).

As often discussed in the literature, an increase in model complexity leads to an increase in computational effort. In addition, model complexity should always be adapted to the simulation's purpose. We account for this trade-off and provide models with different levels of detail within the library and demonstrate the diverse modelling depths in Section 3.1 to Section 3.3. For example, a detailed assessment of a component's operational behaviour (see air-handling unit in Section 3.1) requires a higher modelling depth than a demand estimation for an entire district (see district heating and cooling system in Section 3.3). AixLib supports the detailed analysis of composite systems and consequently the introduction of innovative building system concepts by covering packages of all relevant domains. To demonstrate how coupled building performance simulations can be realized, we introduce a use case of a coupled heat pump system with radiators and a building envelope model with eight heated zones (see Section 3.2).

Apart from that, model handling within Modelica to, e.g., automate parameter studies or derive model peripheries is tedious. This is why supplementary open-source tools have been developed over the last years relying on AixLib models, which are shortly described in this paper. The majority of these additional tools is implemented in Python and speeds up the model development (see Section 2.4). With the second use case being a coupled heat pump system, we demonstrate one of these supplementary tools, called ebcpy, and prove how we can facilitate parameter studies and system design (see Section 3.2). Furthermore, the tool TEASER is presented for use case 3. With TEASER, we demonstrate how to obtain realistic simulated demand profiles of district energy systems in Modelica (Remmen et al. 2018).

6. Future work

Over the last 10 years, AixLib has been initially developed and continuously refined ever since. Even though AixLib already contains many relevant models and covers different modelling depths, continuous model development and enhancements are key to ensure the high quality of the library. Despite the ongoing model improvements, we identify the following main development goals for the next years:

• Enhance unification: Due to the high number of developers and despite modelling guidelines, not all models in AixLib are based on the same structure, interfaces, and parameter definitions. We therefore continuously work on harmonization of existing and new model developments and strengthen our guidelines.

• Develop limited parameter input models: Even though the library already includes simplified parameterization based on, e.g. manufacturer data, the developers are currently working on additional simplified, modular subsystems which are parameterized based on a handful of parameters. This further facilitates model application and dissemination.

• Include crucial electricity-based models: The transition of the energy system demands sector coupling by, e.g., higher inclusion of electricity-based components such as photovoltaic power plants and battery energy system storage and their simultaneous simulation. We therefore focus on developing more of these models for these components in our Electrical package. This complements the already existing photovoltaic power system model.

• Include fluid model interaction with reduced-order building models: Research has proven that reduced-order building models show great potential for district simulations and more complex buildings. However, currently, suitable fluid-based system models which thermally activate the building envelope, e.g., concrete core activation, including their validation are still missing.

• Enhance ventilation modelling: With rising insulation standards and consequently air tightness, the necessity of ventilation becomes more relevant. Existing models for natural and mechanical ventilation need to be improved to accurately predict their influence on building energy performance.

We invite everyone to support our aspiration and contribute on GitHub: https://github.com/RWTH-EBC/AixLib.

Acknowledgments

This work emerged from the IBPSA Project 1, an international project conducted under the umbrella of the International Building Performance Simulation Association (IBPSA). Project 1 will develop and demonstrate a BIM/GIS and Modelica Framework for building and community energy system design and operation.

Data availability statement

The data that support the findings of this study are available from the corresponding author, Laura Maier, upon reasonable request.

Disclosure statement

No potential conflict of interest was reported by the author(s).

Additional information

Funding

In addition, we gratefully acknowledge the financial support by the Federal Ministry for Economic Affairs and Climate Action (BMWK), promotional reference 03EN3026C as well as all other projects listed in Table 4.

Notes

1 https://github.com/lbl-srg/modelica-buildings

2 https://github.com/UdK-VPT/BuildingSystems

3 https://github.com/open-ideas/IDEAS

4 https://github.com/RWTH-EBC/AixLib

5 https://github.com/ibpsa/modelica-ibpsa

6 https://heatbeat.de/en/

7 https://tlk-energy.de/en

8 https://github.com/lbl-srg/BuildingsPy

9 https://developers.google.com/chart

10 https://github.com/IBPSA/modelica-IBPSA

11 Intel(R) Xeon(R) CPU E5-1650 v3 @3.50 GHz, 32 GB DDR3 RAM, 64 bit, SSD hard drive