# Coupling EnergyPlus with Functional Mock-up Units for co-simulation[LINK]

The Functional Mock-up Unit (FMU) for co-simulation import for EnergyPlus allows EnergyPlus to conduct co-simulation with various programs that are packaged as FMUs. A FMU is a component which implements the Functional Mock-up Interface (FMI) standard (http://www.modelisar.com).

A FMU is distributed in the form of a zip file that may contain physical models, model descriptions, source code, and executable programs for various platforms. The FMU for co-simulation import provides EnergyPlus with a standard interface to conduct and control co-simulation with an arbitrary number of FMUs without any middle-ware, such as the Building Controls Virtual Test Bed (BCVTB Documentation, 2011).

The FMU for co-simulation import allows coupling of continuous-time and discrete-time models exported from different simulation programs. In the current implementation, EnergyPlus is implemented as the co-simulation master. It controls the data exchange between the subsystems and the synchronization of all slave simulation programs.

The FMU for co-simulation import enables the direct link between the EnergyPlus kernel and other simulation tools. It will make the co-simulation easier to conduct as no middle-ware is involved. This direct link will decrease run-time by eliminating the transaction layer. In addition, by separating the co-simulation interface from the EnergyPlus kernel, the FMU interface is reusable when EnergyPlus is updated. Furthermore, the FMU contains executable files that have the same interface to EnergyPlus regardless of their original programming environment. Some commercial tools allow running their FMU without licensing requirement.

**Notes:**

1) The current implementation of FMU for co-simulation is only supported on Windows and Linux.

2) FMUs must be in a folder to which the user has *write* access.

## Data exchange between EnergyPlus and FMUs[LINK]

Prior to describing the data exchange between EnergyPlus and FMUs, some definitions and terminologies used in the remainder of this document will be introduced.

A variable of a system described by a system of differential algebraic equations (DAE) is defined as differential variable if its derivatives are present in the DAE. A variable of a system described by a system of DAE is defined as algebraic if its derivatives do not appear explicitly in the DAE (Fabian et al., 2008).

Because in subsequent discussions, it will be distinguished between algebraic and differential variables, a notation for different system of equations that involve algebraic and differential variables will be introduced. Let q∈N , then

- If x1 and x2 are differential variables, then the system is

F(˙x1,x1,˙x2,x2,u,t)=0 with *F*: ℝn x ℝn x ℝm x ℝm x ℝq x ℝ → ℝn+m.

- If x1 is a differential variable and x2 is an algebraic variable, then the system is

G(˙x1,x1,x2,u,t)=0 with *G*: ℝn x ℝn x ℝm x ℝq x ℝ → ℝn+m.

- If x1 is an algebraic variable and x2 is a differential variable, then the system is

H(x1,˙x2,x2,u,t)=0 with *H:* ℝn xℝm xℝm xℝq xℝ →ℝn+m.

- If x1 is an algebraic variable and x2 is an algebraic variable, then the system is

I(x1,x2,u,t)=0 with *I*: ℝn xℝm xℝq xℝ →ℝn+m.

Figure 2 shows a case where a FMU is linked to an EnergyPlus model for co-simulation. The FMU and EnergyPlus could be linked through differential or algebraic variables.

Table 1 shows the different system configurations that are possible.

In the first case, the variable x1 and x2 are differential variables in both systems.

In the second case, the variable x1 is a differential variable and the variable x2 is an algebraic variable.

In the third case, the variable x1 is an algebraic variable and the variable x2 is a differential variable.

In the fourth case, the variable x1 is an algebraic variable and the variable x2 is an algebraic variable.

In the current implementation, it will be focused on the first and the second cases since the third and the fourth cases will constrain the FMU to be solved numerically in the iteration solver loop of EnergyPlus. This will necessitate the ability of the FMU to reject time steps (Modelisar, 2010) which is currently not implemented in the EnergyPlus FMU for co-simulation import. Applications for case 1 and 2 are described in the next sections.

Use cases with different system configurations
(1) |
Model1 (Differential variable) |
Model2 (Differential variable) |

(2) |
Model1 (Differential variable) |
Model2 (Algebraic variable) |

(3) |
Model1 (Algebraic variable) |
Model2 (Differential variable) |

(4) |
Model1 (Algebraic variable) |
Model2 (Algebraic variable) |

## Case 1: Linking two systems through differential variables[LINK]

This case could be for an application where a wall with a phase change material (PCM) is modeled in a FMU and is linked to a room model in EnergyPlus. The room air temperature is the differential variable in EnergyPlus and the temperature of the wall with PCM is the differential variable in the FMU. Each system solves a differential equation that is connected to the differential equation of the other system. For simplicity, we assume that *y1(.)* = *x1(.) and y2(.)* = *x2(.).*The systems are described by the ordinary differential equations

dx1/dt = f1(x1, x2), with x1(0) = x1,0 ,

dx2/dt = f2(x2, x1), with x2(0) = x2,0.

Let N∈N denote the number of time steps and let *tk* with k∈{1,...,N} denote the time steps. We will use the subscripts *1* and *2* to denote the variables and the functions that compute the next state variable of the simulator *1* and *2*, respectively.

The first system computes, for k∈{0,...,N−1} and some ~F1 : ℝn x ℝm x ℝ x ℝ → ℝn, the sequence

x1(tk+1) = ~F1 (x1(tk), x2(tk), tk, tk+1)

and, similarly, the simulator *2* computes for some ~F2 : ℝm x ℝn x ℝ x ℝ → ℝm the sequence

x2(tk+1) = ~F2 (x2(tk), x1(tk), tk, tk+1)

with initial conditions *x1(0) = x1,0* and *x2(0) = x2,0.* ~F1 and ~F2 *are the functions that are used to compute the value of the state variables at the new time step

To advance from time *tk* to *tk+1*, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new state *x1(tk+1)* to the FMU and it receives the state *x2(tk+1)* from the FMU. The same procedure is done with the FMU.

## Case 2: Linking two systems through algebraic and differential variables[LINK]

This case could be for an application where a fan is modeled in a FMU and is linked to a room model in EnergyPlus. The room temperature is the differential variable in EnergyPlus and the pressure difference of the fan is the algebraic variable in the FMU. For simplicity, we assume that *y1(.)* = *x1(.) and y2(.)* = *x2(.).* In this application, the systems are described by the following equations

dx1/dt = g1(x1, x2), with x1(0) = x1,0,

0 = g2(x2, x1).

Let N∈N denote the number of time steps and let *tk* with k∈{1,...,N} denote the time steps. We use the same subscripts *1* and *2* as for the first case to denote the variable and the function that computes the next variable of the simulator *1* and *2*, respectively.

The first system computes, for k∈{0,...,N−1} and some ~G1 : ℝn x ℝm x ℝ x ℝ → ℝn, the sequence

x1(tk+1) = ~G1 (x1(tk), x2(tk), tk, tk+1)

and, similarly, the simulator *2* computes for some ~G2 : ℝm x ℝn x ℝ → ℝm the sequence

x2(tk+1) = ~G2 (x2(tk+1), x1(tk+1), tk+1)

with initial condition *x1(0) = x1,0*. ~G1 and ~G2 are the functions that compute the value of the variables at the new time step.

To advance from time *tk* to *tk+1*, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new value *x1(tk+1)* to the FMU and it receives the value *x2(tk+1)* from the FMU. The same procedure is done with the FMU.

The current implementation for linking EnergyPlus with the FMUs has the following requirements:

The data exchange between EnergyPlus and the FMUs is done at the zone time step of EnergyPlus.

Each FMU is linked to EnergyPlus only through a differential variable in EnergyPlus (see Figure 3 for one FMU).

- Two or multiple FMUs are linked together only through differential variables in EnergyPlus (see Figure 4 for two FMUs).

## Coupling EnergyPlus with Functional Mock-up Units for co-simulation[LINK]

The Functional Mock-up Unit (FMU) for co-simulation import for EnergyPlus allows EnergyPlus to conduct co-simulation with various programs that are packaged as FMUs. A FMU is a component which implements the Functional Mock-up Interface (FMI) standard (http://www.modelisar.com).

A FMU is distributed in the form of a zip file that may contain physical models, model descriptions, source code, and executable programs for various platforms. The FMU for co-simulation import provides EnergyPlus with a standard interface to conduct and control co-simulation with an arbitrary number of FMUs without any middle-ware, such as the Building Controls Virtual Test Bed (BCVTB Documentation, 2011).

The FMU for co-simulation import allows coupling of continuous-time and discrete-time models exported from different simulation programs. In the current implementation, EnergyPlus is implemented as the co-simulation master. It controls the data exchange between the subsystems and the synchronization of all slave simulation programs.

The FMU for co-simulation import enables the direct link between the EnergyPlus kernel and other simulation tools. It will make the co-simulation easier to conduct as no middle-ware is involved. This direct link will decrease run-time by eliminating the transaction layer. In addition, by separating the co-simulation interface from the EnergyPlus kernel, the FMU interface is reusable when EnergyPlus is updated. Furthermore, the FMU contains executable files that have the same interface to EnergyPlus regardless of their original programming environment. Some commercial tools allow running their FMU without licensing requirement.

Notes:1) The current implementation of FMU for co-simulation is only supported on Windows and Linux.

2) FMUs must be in a folder to which the user has

writeaccess.## Data exchange between EnergyPlus and FMUs[LINK]

Prior to describing the data exchange between EnergyPlus and FMUs, some definitions and terminologies used in the remainder of this document will be introduced.

A variable of a system described by a system of differential algebraic equations (DAE) is defined as differential variable if its derivatives are present in the DAE. A variable of a system described by a system of DAE is defined as algebraic if its derivatives do not appear explicitly in the DAE (Fabian et al., 2008).

System with two variables that could be either differential or algebraic variables. [fig:system-with-two-variables-that-could-be]

Because in subsequent discussions, it will be distinguished between algebraic and differential variables, a notation for different system of equations that involve algebraic and differential variables will be introduced. Let q∈N , then

F(˙x1,x1,˙x2,x2,u,t)=0 with

F: ℝn x ℝn x ℝm x ℝm x ℝq x ℝ → ℝn+m.G(˙x1,x1,x2,u,t)=0 with

G: ℝn x ℝn x ℝm x ℝq x ℝ → ℝn+m.H(x1,˙x2,x2,u,t)=0 with

H:ℝn xℝm xℝm xℝq xℝ →ℝn+m.I(x1,x2,u,t)=0 with

I: ℝn xℝm xℝq xℝ →ℝn+m.Figure 2 shows a case where a FMU is linked to an EnergyPlus model for co-simulation. The FMU and EnergyPlus could be linked through differential or algebraic variables.

System with one FMU linked to EnergyPlus. [fig:system-with-one-fmu-linked-to-energyplus.]

Table 1 shows the different system configurations that are possible.

In the first case, the variable x1 and x2 are differential variables in both systems.

In the second case, the variable x1 is a differential variable and the variable x2 is an algebraic variable.

In the third case, the variable x1 is an algebraic variable and the variable x2 is a differential variable.

In the fourth case, the variable x1 is an algebraic variable and the variable x2 is an algebraic variable.

In the current implementation, it will be focused on the first and the second cases since the third and the fourth cases will constrain the FMU to be solved numerically in the iteration solver loop of EnergyPlus. This will necessitate the ability of the FMU to reject time steps (Modelisar, 2010) which is currently not implemented in the EnergyPlus FMU for co-simulation import. Applications for case 1 and 2 are described in the next sections.

## Case 1: Linking two systems through differential variables[LINK]

This case could be for an application where a wall with a phase change material (PCM) is modeled in a FMU and is linked to a room model in EnergyPlus. The room air temperature is the differential variable in EnergyPlus and the temperature of the wall with PCM is the differential variable in the FMU. Each system solves a differential equation that is connected to the differential equation of the other system. For simplicity, we assume that

y1(.)=x1(.) and y2(.)=x2(.).The systems are described by the ordinary differential equationsdx1/dt = f1(x1, x2), with x1(0) = x1,0 ,

dx2/dt = f2(x2, x1), with x2(0) = x2,0.

Let N∈N denote the number of time steps and let

tkwith k∈{1,...,N} denote the time steps. We will use the subscripts1and2to denote the variables and the functions that compute the next state variable of the simulator1and2, respectively.The first system computes, for k∈{0,...,N−1} and some ~F1 : ℝn x ℝm x ℝ x ℝ → ℝn, the sequence

x1(tk+1) = ~F1 (x1(tk), x2(tk), tk, tk+1)

and, similarly, the simulator

2computes for some ~F2 : ℝm x ℝn x ℝ x ℝ → ℝm the sequencex2(tk+1) = ~F2 (x2(tk), x1(tk), tk, tk+1)

with initial conditions

x1(0) = x1,0andx2(0) = x2,0.~F1 and ~F2 *are the functions that are used to compute the value of the state variables at the new time stepTo advance from time

tktotk+1, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new statex1(tk+1)to the FMU and it receives the statex2(tk+1)from the FMU. The same procedure is done with the FMU.## Case 2: Linking two systems through algebraic and differential variables[LINK]

This case could be for an application where a fan is modeled in a FMU and is linked to a room model in EnergyPlus. The room temperature is the differential variable in EnergyPlus and the pressure difference of the fan is the algebraic variable in the FMU. For simplicity, we assume that

y1(.)=x1(.) and y2(.)=x2(.).In this application, the systems are described by the following equationsdx1/dt = g1(x1, x2), with x1(0) = x1,0,

0 = g2(x2, x1).

Let N∈N denote the number of time steps and let

tkwith k∈{1,...,N} denote the time steps. We use the same subscripts1and2as for the first case to denote the variable and the function that computes the next variable of the simulator1and2, respectively.The first system computes, for k∈{0,...,N−1} and some ~G1 : ℝn x ℝm x ℝ x ℝ → ℝn, the sequence

x1(tk+1) = ~G1 (x1(tk), x2(tk), tk, tk+1)

and, similarly, the simulator

2computes for some ~G2 : ℝm x ℝn x ℝ → ℝm the sequencex2(tk+1) = ~G2 (x2(tk+1), x1(tk+1), tk+1)

with initial condition

x1(0) = x1,0. ~G1 and ~G2 are the functions that compute the value of the variables at the new time step.To advance from time

tktotk+1, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new valuex1(tk+1)to the FMU and it receives the valuex2(tk+1)from the FMU. The same procedure is done with the FMU.## Requirements[LINK]

The current implementation for linking EnergyPlus with the FMUs has the following requirements:

The data exchange between EnergyPlus and the FMUs is done at the zone time step of EnergyPlus.

Each FMU is linked to EnergyPlus only through a differential variable in EnergyPlus (see Figure 3 for one FMU).

System with one FMU linked to EnergyPlus. [fig:system-with-one-fmu-linked-to-energyplus.-001]

System with two FMUs linked to EnergyPlus. [fig:system-with-two-fmus-linked-to-energyplus.]

Documentation content copyright © 1996-2020 The Board of Trustees of the University of Illinois and the Regents of the University of California through the Ernest Orlando Lawrence Berkeley National Laboratory. All rights reserved. EnergyPlus is a trademark of the US Department of Energy.

This documentation is made available under the EnergyPlus Open Source License v1.0.