# 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:**

- The current implementation of FMU for co-simulation is only supported on Windows and Linux.
- 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 x
_{1} is a differential variable and x_{2} 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 x
_{1} is an algebraic variable and x_{2} 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 x
_{1} is an algebraic variable and x_{2} 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 6 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 2 shows the different system configurations that are possible.

- In the first case, the variable x
_{1} and x_{2} are differential variables in both systems.
- In the second case, the variable x
_{1} is a differential variable and the variable x_{2} is an algebraic variable.
- In the third case, the variable x
_{1} is an algebraic variable and the variable x_{2} is a differential variable.
- In the fourth case, the variable x
_{1} is an algebraic variable and the variable x_{2} 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 *y*_{1}(.) = *x*_{1}(.) and *y*_{2}(.) = *x*_{2}(.). The systems are described by the ordinary differential equations:

dx_{1}/dt = f_{1}(x_{1}, x_{2}), with x_{1}(0) = x_{1,0},

dx_{2}/dt = f_{2}(x_{2}, x_{1}), with x_{2}(0) = x_{2,0}.

Let N∈N denote the number of time steps and let *t*_{k} 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

x_{1}(t_{k+1}) = ~F1(x_{1}(t_{k}), x_{2}(t_{k}), t_{k}, t_{k+1})

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

x_{2}(t_{k+1}) = ~F2(x_{2}(t_{k}), x_{1}(t_{k}), t_{k}, t_{k+1})

with initial conditions *x*_{1}(0) = x_{1,0} and *x*_{2}(0) = x_{2,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 *t*_{k} to *t*_{k+1}, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new state *x*_{1}(t_{k+1}) to the FMU and it receives the state *x*_{2}(t_{k+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 *y*_{1}(.) = *x*_{1}(.) and y_{2}(.) = *x*_{2}(.). In this application, the systems are described by the following equations

dx_{1}/dt = g_{1}(x_{1}, x_{2}), with x_{1}(0) = x_{1,0},

0 = g_{2}(x_{2}, x_{1}).

Let N∈N denote the number of time steps and let *t*_{k} 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

x_{1}(t_{k+1}) = ~G1(x_{1}(t_{k}), x_{2}(t_{k}), t_{k}, t_{k+1})

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

x_{2}(t_{k+1}) = ~G2(x_{2}(t_{k+1}), x_{1}(t_{k+1}), t_{k+1})

with initial condition *x*_{1}(0) = x_{1,0}. ~G1(.,.,.) and ~G2(.,.,.) are the functions that compute the value of the variables at the new time step.

To advance from time *t*_{k} to *t*_{k+1}, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new value *x*_{1}(t_{k+1}) to the FMU and it receives the value *x*_{2}(t_{k+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 7 for one FMU).

- Two or multiple FMUs are linked together only through differential variables in EnergyPlus (see Figure 8 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: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.

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}._{1}is a differential variable and x_{2}is an algebraic variable, then the system isG(˙x1,x1,x2,u,t)=0 with

G:ℝ^{n}x ℝ^{n}x ℝ^{m}x ℝ^{q}x ℝ → ℝ^{n+m}._{1}is an algebraic variable and x_{2}is a differential variable, then the system isH(x1,˙x2,x2,u,t)=0 with

H:ℝ^{n}x ℝ^{m}x ℝ^{m}x ℝ^{q}x ℝ → ℝ^{n+m}._{1}is an algebraic variable and x_{2}is an algebraic variable, then the system isI(x1,x2,u,t)=0 with

I:ℝ^{n}x ℝ^{m}x ℝ^{q}x ℝ → ℝ^{n+m}.Figure 6 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.

Table 2 shows the different system configurations that are possible.

_{1}and x_{2}are differential variables in both systems._{1}is a differential variable and the variable x_{2}is an algebraic variable._{1}is an algebraic variable and the variable x_{2}is a differential variable._{1}is an algebraic variable and the variable x_{2}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

y=_{1}(.)xand_{1}(.)y=_{2}(.)x. The systems are described by the ordinary differential equations:_{2}(.)dx

_{1}/dt = f_{1}(x_{1}, x_{2}), with x_{1}(0) = x_{1,0},dx

_{2}/dt = f_{2}(x_{2}, x_{1}), with x_{2}(0) = x_{2,0}.Let N∈N denote the number of time steps and let

twith k∈{1,…,N} denote the time steps. We will use the subscripts_{k}1and2to 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 sequencex

_{1}(t_{k+1}) = ~F1(x_{1}(t_{k}), x_{2}(t_{k}), t_{k}, t_{k+1})and, similarly, the simulator

2computes for some ~F2 : ℝ^{m}x ℝ^{n}x ℝ x ℝ → ℝ^{m}the sequencex

_{2}(t_{k+1}) = ~F2(x_{2}(t_{k}), x_{1}(t_{k}), t_{k}, t_{k+1})with initial conditions

xand_{1}(0) = x_{1,0}x~F1(.,.,.) and ~F2(.,.,.) are the functions that are used to compute the value of the state variables at the new time step._{2}(0) = x_{2,0.}To advance from time

tto_{k}t, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new state_{k+1}xto the FMU and it receives the state_{1}(t_{k+1})xfrom the FMU. The same procedure is done with the FMU._{2}(t_{k+1})## 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

y=_{1}(.)x=_{1}(.) and y_{2}(.)xIn this application, the systems are described by the following equations_{2}(.).dx

_{1}/dt = g_{1}(x_{1}, x_{2}), with x_{1}(0) = x_{1,0},0 = g

_{2}(x_{2}, x_{1}).Let N∈N denote the number of time steps and let

twith k∈{1,…,N} denote the time steps. We use the same subscripts_{k}1and2as 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 sequencex

_{1}(t_{k+1}) = ~G1(x_{1}(t_{k}), x_{2}(t_{k}), t_{k}, t_{k+1})and, similarly, the simulator

2computes for some ~G2: ℝ^{m}x ℝ^{n}x ℝ → ℝ^{m}the sequencex

_{2}(t_{k+1}) = ~G2(x_{2}(t_{k+1}), x_{1}(t_{k+1}), t_{k+1})with initial condition

x. ~G1(.,.,.) and ~G2(.,.,.) are the functions that compute the value of the variables at the new time step._{1}(0) = x_{1,0}To advance from time

tto_{k}t, each system uses its own time integration algorithm. At the end of the time step, EnergyPlus sends the new value_{k+1}xto the FMU and it receives the value_{1}(t_{k+1})xfrom the FMU. The same procedure is done with the FMU._{2}(t_{k+1})## Requirements[LINK]

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

System with one FMU linked to EnergyPlus.

System with two FMUs linked to EnergyPlus.

Documentation content copyright © 1996-2015 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.