EplusLauncher: An API to Perform Complex EnergyPlus Simulations in MATLAB^® and C#

Abstract

There is a growing concern about how to mitigate climate change, in which the production and use of energy has a great impact as one of the largest sources of global greenhouse gases (GHG). Buildings are responsible for a large percentage of these emissions. Therefore, there has been an increase in research in this area, in order to reduce their consumption and increase their efficiency. One of the major simulation programs used in optimization research is EnergyPlus. The purpose of this software is the complete energy simulation of a building, although it lacks tools to analyze its results and, above all, to manage and edit its simulations. For this reason, we developed an application programming interface (API) that serves to merge two areas which are highly demanded by researchers: energy building simulation (using EnergyPlus) and tools for the management and design of research experiments (in this case, MATLAB^®). The developed API allows the user to perform complex simulations using EnergyPlus in a simple way, as it allows the editing of each simulation and the analysis of the simulation results through MATLAB^®. In addition, it enables the user to simultaneously run multiple simulations, using either all computer core processors or a selection of them (i.e., allowing parallel computing), reducing the simulation time. The API was developed in the C# language, such that it can be used with any software that can import $.NET$ libraries.

1. Introduction

In February 2019, the Pew Research Center published a report on the top global threats [1], in which it stated that concern about global climate change has climbed, such that it is now at the top of the eight international threats, along with concerns about ISIS, cyberattacks, North Korea’s nuclear program, and others. This research center “is a nonpartisan fact tank that informs the public about the issues, attitudes and trends shaping America and the world” [2]. The report also highlighted that “people around the world agree that climate change poses a severe risk to their countries”, as well as the concern of the Intergovernmental Panel on Climate Change (IPCC) about its possible impacts in both the near and distant future.

As is well-known, buildings and construction play an important role in mitigating global warming, as they are large consumers of final energy (36%) and, therefore, are large producers of CO₂ emissions (39%) [3]. This is one of the main reasons there have been many studies on how to improve the building energy performance, how to optimize their HVAC systems, how to obtain cost-optimal retrofit solutions, and so on. In 2014, Nguyen et al. [4] reviewed the simulation-based optimization methods currently used to analyze building energy performance. In the review, they stated that EnergyPlus [5] and TRNSYS (Transient System Simulation Tool) are the main simulation tools used in the field of building optimization research, with values of 37.2% and 35.3%, respectively. TRNSYS, as explained in [6], has “a modular structure that implements a component-based approach”. These components may be as simple as a weather file or part of an HVAC system, or as complex as an entire building. The software calculates and solves different equations representing the building energy model. In contrast, EnergyPlus is an entire building energy simulation software, which serves to calculate energy consumption taking into account many aspects that thermally influence the building. It has a lot of features and capabilities, such as different heat balance algorithms, advanced fenestration models, a large number of HVAC possibilities, Functional Mockup Interfaces (FMI) that enable co-simulation with other software, and so on.

In terms of optimization software, Attia et al. [7] performed a literature review by reviewing of 165 publications and 28 interviews with optimization experts about the trends in simulation-based building performance optimization (BPO) tools. In the review, they found that GenOpt [8] and MATLAB^® were the most used tools, and MATLAB^® the most popular tool. This is because MATLAB^® has a optimization toolbox which provides a large set of algorithms to minimize or maximize objectives taking into account different constraints, including solvers for linear and non-linear programming, with continuous and discrete variables, and so on. In addition, it features tools which enable the user to analyze the optimization results. As Yan et al. [9] highlighted in their conclusions: “although there have been many software tools developed specially for building optimization design, Matlab is still the most popular tool for optimal solution searches”.

Although coupling TRNSYS and MATLAB^® have also been commonly used to simulate and optimize energy buildings [10,11], we focus on coupling EnergyPlus and MATLAB^® in this article. Within this group, almost all studies can be organized into two large groups: those that used co-simulation to perform optimization and those that used MATLAB^® to launch EnergyPlus simulations and analyze their results.

• Co-simulation between EnergyPlus and MATLAB^®
  Co-simulation is a simulation strategy which allows different simulation programs to run simultaneously and exchange data during the simulation. Each software package expects data from the other, which allows the programs to complement missing features in the other or to optimize the building operation with information obtained during the simulation. EnergyPlus uses the Building Controls Virtual Test Bed (BCVTB) as the software environment that enables the user to couple different elements of EnergyPlus for co-simulation with other software (e.g., MATLAB^®, Modelica, Radiance, TRNSYS, ESP-r, and so on). It is based on the Ptolemy II software environment and has the ability to couple the simulation program with the actual hardware. This communication protocol is open and can be used by other software to perform co-simulation with EnergyPlus; this is the case of MLE+ [12]. The latter is executed in the standard environment of MATLAB^®, which facilitates the finding and fixing of errors (debugging). This is more complicated to do with the direct implementation of BCVTB in MATLAB^®, which requires knowledge of the Ptolemy II programming language. All of the examples that use co-simulation between EnergyPlus and MATLAB^® use one of these (i.e., BCVTB or MLE+).
  For the cases that use BCVTB as the software environment to perform the co-simulation between EnergyPlus and MATLAB^®, the optimizations carried out are focused on Model Predictive Control (MPC) optimizations [13,14,15,16,17,18]; on building energy consumption improvements [19,20]; on thermal comfort using the Human and Building Interaction Toolkit [21]; on considering the condensation risk of a thermally activated building (TAB) in the cooling operation [22]; on how to integrate the ability to simulate double-skin facades into EnergyPlus [23]; on thermal bridges using MATLAB^® [24]; and so on.
  For the cases that use MLE+, the optimizations carried out are similar: Model Predictive Control (MPC) optimizations [25,26,27,28]; building energy performance improvements using phase change materials [29]; analyzing daylight conditions with Radiance [30]; or making decisions based on the thermal comfort levels [31]. It has even been used to create a black-box model with the information provided by EnergyPlus during co-simulation [32].
• Management of EnergyPlus simulations using MATLAB^®
  On the other hand, other studies on optimizing or analyzing the energy performance of a building did not require the use of co-simulation, but focused on managing the simulations and their results. In these cases, it is necessary to develop a personal script that manages EnergyPlus through MATLAB^®, as there exists no dedicated application that does this in a simple way. The research topics that use EnergyPlus in this way are broader: for example, optimizing building energy retrofits using genetic algorithms [33,34,35,36,37,38] or a specific methodology, such as the “Simulation-based Large-scale uncertainty/sensitivity Analysis of Building Energy performance” (SLABE) method [39]; improving the building energy performance when designing the envelope [40]; performing thermostatic optimization [41]; or using Agent-Based Modeling (ABM) to capture the dynamic energy of occupants [42]. In addition, more specific topics have been studied using this strategy, such as: optimizing the control of blind systems [43]; using urban energy models to analyze the urban heat island effect [44]; developing an EnergyPlus meta-model [45]; performing MPC and thermal comfort optimization [46]; developing a sensitivity analysis using the Simlab software [47,48]; optimizing the renewable energy mix of a building [49]; finding an optimal architectural design using BIM at the design stage [50]; or performing automated random parametric simulations [51].
  To make things even more complicated, researchers sometimes prefer to develop a personal script to manage other software, which, in turn, manages EnergyPlus, for example using GenOpt to analyze the energy saving potential of adaptive glazing technologies [52] or the optimal control of a switchable glazing façade [53]; using jEPlus [54] to perform sensitivity analyses, uncertainty quantification, or multi-objective optimizations [55,56,57,58,59]; or, with Rhinoceros and Grasshopper, using Ladybug and Honeybee to evaluate energy saving strategies in commercial buildings with integrated data collection [60].

After analyzing all of these studies, the need for an application that links an optimization tool (e.g., MATLAB^®) with a building energy simulation program (e.g., EnergyPlus) is evident, as highlighted by Attia et al. [7], “for less simulation efforts and feasible optimization it is essential to develop the link between existent building simulation tools and trusted optimization tools”. In particular, the necessity of such integration with MATLAB^® was highlighted by Leow et al. [61]: “There exist other high-performance building simulation applications e.g., TrnSys, ESP-r, EnergyPlus but these offer a less direct integration path with popular mathematical computing and simulation environments e.g., MATLAB”. The authors of Thieblemont et al. [62] also highlighted that, without this application, the possibilities for the optimization of building energy models are reduced “(…) at the moment, the building simulation community mainly uses software having no optimization process like TRNSYS or EnergyPlus does. In consequence, building model software tools must be linked to some optimization tools (Matlab, GenOpt, etc.), which may be difficult to achieve or reduce the modeling possibilities”.

This article explains the development of this application, in API format, such that its use by other types of software is both simple and versatile. Figure 1 shows the general scheme of simulation in EnergyPlus. As can be seen, the general scheme of an EnergyPlus simulation only requires two files: a weather file ($*.epw$) and a building energy model (BEM) file ($*.idf$). Then, after the simulation, the software generates different outputs (i.e., a $*.csv$ file and an $*.html$ file). Figure 2 shows the same process, but performed with the EplusLauncher API. In this case, the EnergyPlus input files are managed by the API, which is responsible for running the simulations. Then, when the process is finished, MATLAB^® can analyze the output files, making it possible to make new decisions about the input files.

The advantages of EplusLauncher API can be summarized in three main aspects: (i) it allows the editing of the EnergyPlus input files before the simulation process begins; (ii) it manages the EnergyPlus simulation, allowing the use of a selection of computer processors (parallelization); and (iii) it facilitates the analysis of results through MATLAB^®, as all of the operations are performed within the same platform. In the following section, each of these advantages are explained in depth.

The document is structured as follows. Section 2 describes how to use the API and the possibilities of all its options. Section 3 gives an example of its use in a real case scenario. This case was developed for a European project of the program Horizon 2020 under Grant No. 731211, whose name is “project SABINA” (https://sabina-project.eu) [63] (SmArt BI-directional multi eNergy gAteway). Finally, the conclusions are summarized in Section 4.

2. Description of the API

The EplusLauncher API can be downloaded from the SABINA project repository (https://sabina-project.eu/resources/API/index.html), and the documentation can be consulted at this link (https://sabina-project.eu/resources/API/api/index.html).

To explain the use and features of the API, we use a simple parameterization example performed with EnergyPlus and managed by MATLAB^® through the EplusLauncher API. As explained above, the API was developed in C#, thus it can be used by any other software that can import $.NET$ libraries, as is the case for MATLAB^®. The structure of this example could be used easily in other studies, adapting the code to the needs of the particular experiment. It is organized into four MATLAB^® files: “launcher.m”, “EnergyPlusMessage.m”, “SimulationFinished.m”, and “JobsFinished.m”.

• launcher.m
  This is the main file, where almost all of the options must be defined (see Listing 1). First, the paths of the files, including the path of the EplusLauncher API, are defined [API Loading]. Next, it is necessary to configure the API [Launcher configuration]. In this part, it is possible to select the number of cores to perform the simulation (Launcher.MaxCores), where “0” is the maximum. This function is useful as, in some studies, many simulations need to be performed, such as parameterization studies or in the analysis of models that use optimization algorithms, where a group of simulations must be performed before making a decision about the model (for example, a genetic algorithm and its population simulation). For these cases, having the ability to perform a group of simulations at the same time (i.e., parallelization of the simulations) can make these studies feasible. In addition, when the number of cores is high, it is possible to perform several optimizations of different problems at the same time by defining specific cores for each optimization.
  Each of these simulations will be stored inside a folder called (OutputJob#), where # is the number defined by (Launcher.OutputFolderNumber). In the cases where different optimizations are carried out at the same time, it is good practice to identify each of them. Initially, this folder name may seem too simple; however, it satisfies the Windows^® file and path length limitations (due to the maximum character number limitation). The disadvantage is that the file does not give us information about the type of simulation that has been carried out. This Windows^® limitation seemed more important to us than the information that could be given in the folder name. However, this information is collected in the log file, which is created by the command (Launcher.JobsLogFile) and can be accessed to obtain the details of each of the simulations performed by EplusLauncher. As shown below, the folder name (OutputJob#) is defined in the [EnergyPlus configuration] section of launcher.m, whereas the number (#) is defined in the [Launcher configuration] section. The reason for this is to avoid cases where it is necessary to perform different simulations with different configurations (e.g., several jobs with different weather or input files), in which the results will be overwritten because they are assigned the same folder name. Thus, each folder is identified by a unique name and number, preventing errors.
  Listing 1. launcher.m file.

  Listing 1. launcher.m file.
  Next, [EnergyPlus listeners] are defined. These listeners report each EnergyPlus message to MATLAB^®, as well as when a simulation ends or all of the jobs end. They make calls to the other MATLAB^® files (EnergyPlusMessage.m, SimulationFinished.m, and JobsFinished.m) and allow for adding in new code (scripts) for other functionalities that have not yet been developed in the API (e.g., reporting the simulation time or the ongoing results, modify the simulation file during the optimization process using the results, change the optimization strategy if a local minimum has been reached, etc.).
  Then, it is necessary to perform the [EnergyPlus configuration]. In this part, all the files needed to run EnergyPlus are defined: the installation folder of EnergyPlus (config.EnergyPlusFolder); the building energy model file ($*.idf$)(config.InputFile); the weather file ($*.epw$)(config.WeatherFile); the RVI file ($*.rvi$), which is the responsible for reorganizing the EnergyPlus results in the output files ($*.csv$)(config.RviFile); and the name of the output folder (config.OutputFolder). This name will be followed by the number defined in the (Launcher.JobsLogFile) stage.
  Finally, editing of the Building Energy Model (BEM) file and definition of the simulation list is done. EplusLauncher can edit the simulation file ($*.idf$) before each simulation. As $*.idf$ files are text-based files, EplusLauncher searches for tags (i.e., identifiers) in the file and replaces them with other variables. These variables can be text (strings) or values (numbers). These identifiers are defined in the variable (Tags) and their values are variables created by the user. The example given below is the parameterization of a building envelope, where the roughness and density of one of its layers and the insulation thickness are parameterized. In this case, the job list is defined by several “for” loops, in order to select all the variation possibilities of the three parameters. This list must be defined for each analyzed problem, and will be different depending on the type of problem. For example, in the case of optimization using a genetic algorithm, this list of jobs will be the population of each generation, where the different identifiers will be first added to the list of jobs (job.AddTags(Tags)) and, then, the values of these identifiers (job.AddValues([…])).
  The file (launcher.m) ends with the execution command (Launcher.Run()), which, in the example, executes 27 simulations ($3·3·3$) giving all possibilities in the parameterization example (i.e., a brute force technique).
• EnergyPlusMessage.m
  This file displays all EnergyPlus messages in the MATLAB^® command window. It is very helpful, as it reports all possible errors during the simulation process, identifying which simulation has caused the error (see Listing 2).
  Listing 2. EnergyPlusMessage.m file.

  Listing 2. EnergyPlusMessage.m file.
• SimulationFinished.m
  This file summarizes the entire simulation process of each simulation, reporting “correct simulation: True” if the simulation has run without any errors (see Listing 3).
  Listing 3. SimulationFinished.m file.

  Listing 3. SimulationFinished.m file.
• JobsFinished.m
  Finally, this file is executed when all simulations are finished (see Listing 4). In an optimization process, this file is used to add additional operations to extract valuable information from the results obtained, which can be used to edit the EnergyPlus files and repeat the process.
  In general, simulations are carried out on a large scale in all optimization processes; thus, it is necessary to manage the simulation files. EnergyPlus generates an enormous amount of information throughout the simulation process. Many of these files are not used in the study being carried out and only take up space. For this reason, the API has an option to delete files, which is executed at the end of the simulation process. In the example, this function is useful, as the only files that are used after the parameterization are the results files. This removal process is accessed by defining the filenames with their extensions (cleaner.SetFiles()) or by selecting files with the same extension (cleaner.SetFilesExtensions()). Once the files have been defined, the cleaning process is executed in all the folders created during the simulation process using the command (cleaner.CleanFromLogFile()).
  Listing 4. JobsFinished.m file.

  Listing 4. JobsFinished.m file.

The use of this API facilitates the management of EnergyPlus simulations within the MATLAB^® environment, which increases the simulation and optimization possibilities. The API not only allows easy editing of EnergyPlus files, but also allows the user to manage the use of all or part of the processing cores (parallelization) and facilitates the development of complementary scripts to perform analysis of the simulation results at the end of the process. The following section describes the use of this API in a real case scenario, developed for the European project SABINA (https://sabina-project.eu) [63].

3. Example of Use

In the scope of the European project SABINA [63], a model predictive control (MPC) that drives various HVAC systems and takes advantage of a building’s thermal inertia was developed in MATLAB^®. This algorithm needs to be run in conjunction with the EnergyPlus simulated model, in order to validate its performance. To interface the EnergyPlus model with the MATLAB^® environment, some functions were written, following the guidelines mentioned above. Doing so allowed us to quickly test the behavior of the modeled building and interface it with the control algorithms.

The parameters we wanted to automatize through MATLAB^® were the start and end date of the simulation (the run period) and the temperature set points of each room of the simulated building. To do this, we tagged those parameters with an identifiable text string, as described above, in the corresponding $*.idf$ file.

Following that, some structures could be defined to control the parameters. An example is shown below (see Listing 5).

Listing 5. Sabina_Launcher_Example.m file.

Listing 5. Sabina_Launcher_Example.m file.

In the [parameters definition] of this example, the simulation will start on 18 January and finish on 20 January (see Defining runperiod for simulation). Therefore, the simulation was carried out during the heating season.

Using the same methodology, a set of room temperature set points over 24 h, which control the simulation, were defined as follows. In this case, one new temperature set point value was used for each step of 10 min. No algorithm was implemented at this stage, as the development is currently ongoing. Therefore, a step function, varying from a room thermal set point of 17 °C to 25 °C, was applied in each room. For the development of this example, two kinds of set point vectors were defined: a baseline vector that used these limit values every six hours and a set of 10 random set point vectors between these limit values (see Generating set points vector (base) and Generating set points vectors (random)). These tests served to analyze how the simulated building followed the given set points. In the baseline case, it is noted that these important steps were applied to test the building’s behavior in extreme conditions. Indeed, it is neither realistic nor efficient to apply such temperature changes in real conditions.

This temperature scheduler can now be used for any weekly/monthly scheduler to test each set point vector obtained from the MPC algorithms developed in SABINA.

The use of the EplusLauncher API’s multi-core features enables multiple simulation jobs to be launched at the same time. This makes MPC feasible, due to its capacity to perform batches of simulations within reasonable time scales. In fact, in the European project the simulations are used to feed a neural network that will be in charge of obtaining the different MPC solutions. For the training, the parameterization of the simulations is the most appropriate strategy since the behavior of the model is taken into account given different external variables.

Finally, thanks to the fact that the simulations are managed by MATLAB^®, it is possible to access the results directly and analyze them during the simulation process, using the toolboxes in MATLAB^®. This facilitated the development of the SABINA project algorithms for the MPC.

Figure 3 illustrates the thermal control result using the baseline case vector. As explained above, the simulation consisted of three days of simulation during the heating season, using the set points of 17 °C and 25 °C as limit values every six hours. As mentioned above, this simulation serves exclusively to verify that the model follows the set points established in an extreme case, and does not make sense in real conditions.

4. Conclusions

This article describes the development and use of an application programming interface (API), which links an optimization tool (MATLAB^®) and a building energy simulation software (EnergyPlus). This type of application is in high demand by the scientific community due to the rise of research focused on improving buildings in order to combat climate change (e.g., energy conservation measures, improvements in HVAC systems, strategies for optimizing the use of buildings, and so on). In fact, this tool was born from a real need within an optimization process developed by the European project “SABINA” [63]. This project aims to develop new technologies and financial models to connect, control, and actively manage generation and storage assets to exploit synergies between electrical flexibility and the thermal inertia of buildings.

The tool was designed to be easy to use and can be easily improved using MATLAB^® scripts that can complement its features. Its most important features are highlighted below:

• It allows the editing of EnergyPlus input files ($*.idf$) before performing simulations. These modifications are made through a process of searching and replacing tags, which provides great versatility to the editing process. This, together with other EnergyPlus utilities (such as Parametric:Logic, which allows changes to the $*.idf$ file according to certain values) gives this feature great potential for the optimization of building energy models.
• It allows (in a simple way) for selection of the quantity of cores to be used in each optimization process. This not only reduces the total time needed to perform an optimization process but, in cases where a high number of cores are available (i.e., a cluster), several optimizations can be performed at the same time.
• The API is structured in such a way that it is easy to introduce improvements (through scripts) in each of the phases of the simulation/optimization process. It allows for combination of the analysis capabilities of all MATLAB^® toolboxes with the large amount of results that EnergyPlus provides, by allowing both to work under the same platform.

On the other hand, this API is only in its first version and, therefore, is in the testing process. Depending on demand and use, improvements will be developed in one or another direction. To date, the tool has yielded very good results and has proven to be highly suitable for many of the processes developed in the SABINA project.