Architecture
of the FMU for co-simulation Import[LINK]
Figure 1
shows the architecture of the connection between EnergyPlus
and two FMUs. EnergyPlus imports the FMUs that connect to its
external interface. These FMUs are generated by external
simulation environments that implement the FMI Application
Programming Interface (API) for co-simulation. See http://www.modelisar.com/tools.html for a list
of programs that export FMUs. In the external interface, the
input/output signals that are exchanged between the FMUs and
EnergyPlus are mapped to EnergyPlus objects. The subject of
this External Interface Application Guide is how to configure
this mapping and how to use these objects.
Architecture of the FMU for
co-simulation import. [fig:architecture-of-the-fmu-for-co-simulation]
The external interface can map to three EnergyPlus input
objects called
Prior to discussing the examples, we will explain the
pre-processing steps that are required to prepare EnergyPlus
to be linked to FMUs for co-simulation.
Workflow
of the FMU for co-simulation import[LINK]
To use the FMU for co-simulation import, there are two
important steps: pre-processing and co-simulation. The
pre-processing step generates a section of an EnergyPlus input
file (*.idf) that can be used to configure the FMU for
co-simulation import. The input file defines the input and
output variables for both EnergyPlus and FMUs. The
co-simulation step performs co-simulation.
Figure 2 shows
the work flow for pre-processing. First, a FMU Parser parses
the FMU files (i.e. xxx.fmu) and generates a temporary
EnergyPlus input file (i.e. xxxtmp.idf). The temporary
EnergyPlus input file is not complete as it just contains
information related to the FMU, such as names of the FMU and
properties of each FMU variable including variable name,
associated FMU name, input/output type, data type, units and
definitions. The user will need to manually copy the FMU
information from xxxtmp.idf into the EnergyPlus input file
xxx.idf. The user then needs to modify the xxx.idf file to
link the FMU variables with EnergyPlus variables.
Work flow for pre-processing.
[fig:work-flow-for-pre-processing.]
The FMU parser is a code written in C. It includes Expat
(Expat XML Parser, 2011) which is a XML parser library written
in C. The low level implementation of the function
(parser) that is used to process a FMU is parser
[options] xxx.fmu, where options are as
follows:
–printidf, prints a temporary xxxtmp.idf with
FMU information to be printed,
–unpack, unpacks a FMU to be unpacked,
and
–delete, deletes temporary files related to
FMUs.
A FMU is a zip file which may contain executable programs
for specific platforms, description files and source code. In
the pre-processing step, the FMU Parser will be called with
the command option –printidf. This will cause the
parser to parse the XML file with the model description of the
FMU and write the FMU information in a format of the
EnergyPlus input file (*.idf). The parser will check if all
the required fields from FMU (see next section for details) in
the *.idf file are correctly specified. If the check succeeds,
the parser will successfully close. If the check fails, the
parser will close with an error message. After the EnergyPlus
executable (such as EnergyPlus.exe) terminates, the EnergyPlus
batch file will delete all the temporary files that may have
been generated. The FMU Parser is distributed with
EnergyPlus and can be found in the PreProcess folder
(FMUParser) of the EnergyPlus installation.
Workflow of FMU parser for
pre-processing. [fig:workflow-of-fmu-parser-for-pre-processing.]
Example
1: Interface using
ExternalInterface:FunctionalMockupUnitImport:To:Schedule[LINK]
In this example, an HVAC system implemented in a FMU
(MoistAir.fmu) is linked to a room model in EnergyPlus. The
HVAC system computes sensible and latent heat gain required
for maintaining a set point temperature. The FMU needs as
input the outdoor dry-bulb (TDryBul) temperature, outdoor air
relative humidity (outRelHum), the room dry-bulb temperature
(TRooMea) and the room air relative humidity (rooRelHum). The
outputs of the FMU are the latent (QLatent) and sensible
(QSensible) heat transported across the thermodynamic boundary
of air inlet and outlet of the thermal zone.
To link the FMU with EnergyPlus, we need to send from the
FMU to EnergyPlus two schedule values for the latent and
sensible heat gain and from EnergyPlus to the FMU four output
variables for outdoor dry-bulb temperature, outdoor air
relative humidity, room dry-bulb temperature and room air
relative humidity at each zone time step. This can be
accomplished by using two objects of type ExternalInterface:FunctionalMockupUnitImport:To:Schedule
and four objects of type ExternalInterface:FunctionalMockupUnitImport:From:Variable.
To interface EnergyPlus, the following four items are
needed:
An object that instructs EnergyPlus to activate the
external interface.
An object that specifies the FMU and its
instances.
EnergyPlus objects that read data from EnergyPlus and
send to FMU.
EnergyPlus objects that read data from FMU and send to
EnergyPlus.
To enter output variables from which the external interface
read and send to FMUs, we use:
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
Environment, !- EnergyPlus Key Value
Site Outdoor Air Drybulb Temperature, !- EnergyPlus Variable Name
MoistAir.fmu, !- FMU Filename
Model1, !-FMU Model Name
TDryBul; !- FMU Model Variable Name
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
ZONE ONE, !- EnergyPlus Key Value
Zone Mean Air Temperature, !- EnergyPlus Variable Name
MoistAir.fmu, !- FMU Filename
Model1, !- FMU Model Name
TRooMea; !- FMU Model Variable Name
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
Environment, !- EnergyPlus Key Value
Site Outdoor Air Relative Humidity, !- EnergyPlus Variable Name
MoistAir.fmu, !- FMU Filename
Model1, !- FMU Model Name
outRelHum; !- FMU Model Variable Name
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
ZONE ONE, !- EnergyPlus Key Value
Zone Air Relative Humidity, !- EnergyPlus Variable Name
MoistAir.fmu, !- FMU Filename
Model1, !- FMU Model Name
rooRelHum; !- FMU Model Variable Name
These output variables need to be specified in the idf
file:
Output:Variable,
Environment, !- Key Value
Site Outdoor Air Drybulb Temperature, !- Variable Name
TimeStep; !- Reporting Frequency
Output:Variable,
ZONE ONE, !- Key Value
Zone Mean Air Temperature, !- Variable Name
TimeStep; !- Reporting Frequency
Output:Variable,
Environment, !- Key Value
Site Outdoor Air Relative Humidity, !- Variable Name
TimeStep; !- Reporting Frequency
Output:Variable,
ZONE ONE, !- Key Value
Zone Air Relative Humidity, !- Variable Name
TimeStep; !- Reporting Frequency
To enter schedules to which the external interface writes,
we use:
ExternalInterface:FunctionalMockupUnitImport:To:Schedule,
FMU_OthEquSen_ZoneOne, !- EnergyPlus Variable Name
Any Number, !- Schedule Type Limits Names
MoistAir.fmu, !- FMU Filename
Model1, !- FMU Model Name
QSensible, !- FMU Model Variable Name
0; !- Initial Value
ExternalInterface:FunctionalMockupUnitImport:To:Schedule,
FMU_OthEquLat_ZoneOne, !- EnergyPlus Variable Name
Any Number, !- Schedule Type Limits Names
MoistAir.fmu, !- FMU Filename
Model1, !- FMU Model Name
QLatent, !- FMU Model Variable Name
0; !- Initial Value
This completes the configuration that is required to
simulate EnergyPlus with the FMU.
Example
2: Interface using
ExternalInterface:FunctionalMockupUnitImport:To:Actuator[LINK]
In this example, a shading controller with a finite state
machine is implemented in a FMU (ShadingController.fmu).
Inputs of the FMU are the outside temperature (TRoo) and the
solar irradiation (ISolExt) that is incident on the window.
The output of the FMU is the shading actuation signal
(yShade).This example describes how to set up EnergyPlus to
exchange data between the FMU and EnergyPlus, using an Energy
Management System (EMS) actuator.
To interface EnergyPlus using the EMS feature, the
following four items are needed:
An object that instructs EnergyPlus to activate the
external interface.
An object that specifies the FMU and its
instances.
EnergyPlus objects that read data from EnergyPlus and
send to FMU.
EnergyPlus objects that read data from FMU and send to
EnergyPlus.
To enter the two output variables from which the external
interface read from and send to FMUs, we use:
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
Zn001:Wall001:Win001, !- EnergyPlus Key Value
Surface Outside Face Incident Solar Radiation Rate per Area,
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
ISolExt; !- FMU Model Variable Name
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
WEST ZONE, !- EnergyPlus Key Value
Zone Mean Air Temperature, !- EnergyPlus Variable Name
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
TRoo; !- FMU Model Variable Name
These output variables need to be specified in the idf
file:
Output:Variable,
Zn001:Wall001:Win001, !- Key Value
Surface Outside Face Incident Solar Radiation Rate per Area, !- Var Name
TimeStep; !- Reporting Frequency
Output:Variable,
WEST ZONE, !- Key Value
Zone Mean Air Temperature, !- Variable Name
TimeStep; !- Reporting Frequency
To enter the actuator that changes the control status of
the window with name “Zn001:Wall001:Win001”, we use:
ExternalInterface:FunctionalMockupUnitImport:To:Actuator,
Zn001_Wall001_Win001_Shading_Deploy_Status, !- EnergyPlus Variable Name
Zn001:Wall001:Win001, !- Actuated Component Unique Name
Window Shading Control, !- Actuated Component Type
Control Status, !- Actuated Component Control Type
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
yShade, !- FMU Model Variable Name
6; !- Initial Value
This completes the configuration that is required to
simulate EnergyPlus with the FMU.
Example
3: Interface using
ExternalInterface:FunctionalMockupUnitImport:To:Variable[LINK]
This example implements the same controller as the Example
2. However, the interface with EnergyPlus is done using an
external interface variable instead of an external interface
actuator. Inputs of the FMU are the outside temperature (TRoo)
and the solar irradiation (ISolExt) that is incident on the
window. The output of the FMU is the shading actuation signal
(yShade).
To interface EnergyPlus using an external interface
variable, the following items are needed:
An object that instructs EnergyPlus to activate the
external interface.
An object that specifies the FMU and its
instances.
EnergyPlus objects that read data from EnergyPlus and
send to FMU.
EnergyPlus objects that read data from FMU and send to
EnergyPlus.
To enter the two output variables from which the external
interface read from and send to FMUs, we use:
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
Zn001:Wall001:Win001, !- EnergyPlus Key Value
Surface Outside Face Incident Solar Radiation Rate per Area,
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
ISolExt; !- FMU Model Variable Name
ExternalInterface:FunctionalMockupUnitImport:From:Variable,
WEST ZONE, !- EnergyPlus Key Value
Zone Mean Air Temperature, !- EnergyPlus Variable Name
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
TRoo; !- FMU Model Variable Name
These output variables need to be specified in the idf
file:
Output:Variable,
Zn001:Wall001:Win001, !- Key Value
Surface Outside Face Incident Solar Radiation Rate per Area, !- Var Name
TimeStep; !- Reporting Frequency
Output:Variable,
WEST ZONE, !- Key Value
Zone Mean Air Temperature, !- Variable Name
TimeStep; !- Reporting Frequency
To write data from the external interface to an EnergyPlus
EMS variable, we use the following item in idf file:
ExternalInterface:FunctionalMockupUnitImport:To:Variable,
Shade_Signal, !- EnergyPlus Variable Name
ShadingController.fmu, !- FMU Filename
Model1, !- FMU Model Name
yShade, !- FMU Model Variable Name
1; !- Initial Value
which declares a variable with name yShade that can be used
in an Erl program to actuate the shading control of the window
“Zn001:Wall001:Win001” as follows:
! EMS program. The first assignments sets the shading status and converts it into the
! EnergyPlus signal (i.e., replace 1 by 6).
! The second assignment sets yShade to
! an EnergyManagementSystem:OutputVariable
! which will be read by the external interface.
EnergyManagementSystem:Program,
Set_Shade_Control_State, !- Name
Set Shade_Signal = 6*yShade, !- Program Line 1
Set Shade_Signal_01 = yShade+0.1; !- Program Line 2
! Declare an actuator to which the EnergyManagementSystem:Program will write
EnergyManagementSystem:Actuator,
Shade_Signal, !- Name
Zn001:Wall001:Win001, !- Actuated Component Unique Name
Window Shading Control, !- Actuated Component Type
Control Status; !- Actuated Component Control Type
! Declare a global variable to which the EnergyManagementSystem:Program will write
EnergyManagementSystem:GlobalVariable,
Shade_Signal_01; !- Name of Erl variable
This completes the configuration that is required to
simulate EnergyPlus with the FMU.
FMU Examples[LINK]
Architecture of the FMU for co-simulation Import[LINK]
Figure 1 shows the architecture of the connection between EnergyPlus and two FMUs. EnergyPlus imports the FMUs that connect to its external interface. These FMUs are generated by external simulation environments that implement the FMI Application Programming Interface (API) for co-simulation. See http://www.modelisar.com/tools.html for a list of programs that export FMUs. In the external interface, the input/output signals that are exchanged between the FMUs and EnergyPlus are mapped to EnergyPlus objects. The subject of this External Interface Application Guide is how to configure this mapping and how to use these objects.
The external interface can map to three EnergyPlus input objects called
ExternalInterface:FunctionalMockupUnitImport:To:Schedule
ExternalInterface:FunctionalMockupUnitImport:To:Actuator
ExternalInterface:FunctionalMockupUnitImport:To:Variable.
The ExternalInterface:FunctionalMockupUnitImport:To:Schedule can be used to overwrite schedules, and the other two objects can be used in place of Energy Management System (EMS) actuators and EMS variables. The objects have similar functionality as the objects Schedule:Compact, EnergyManagementSystem:Actuator and EnergyManagementSystem:GlobalVariable, except that their numerical value is obtained from the external interface at the beginning of each zone time step, and will remain constant during this zone time step.
The external interface also uses the ExternalInterface:FunctionalMockupUnitImport:From:Variable object which maps to EnergyPlus objects Output:Variable and EnergyManagementSystem:OutputVariable to send data from EnergyPlus to FMUs at each zone time step.
We will now present examples that use all of these objects. The following table shows which EnergyPlus features are used in the examples.
Prior to discussing the examples, we will explain the pre-processing steps that are required to prepare EnergyPlus to be linked to FMUs for co-simulation.
Workflow of the FMU for co-simulation import[LINK]
To use the FMU for co-simulation import, there are two important steps: pre-processing and co-simulation. The pre-processing step generates a section of an EnergyPlus input file (*.idf) that can be used to configure the FMU for co-simulation import. The input file defines the input and output variables for both EnergyPlus and FMUs. The co-simulation step performs co-simulation.
Figure 2 shows the work flow for pre-processing. First, a FMU Parser parses the FMU files (i.e. xxx.fmu) and generates a temporary EnergyPlus input file (i.e. xxxtmp.idf). The temporary EnergyPlus input file is not complete as it just contains information related to the FMU, such as names of the FMU and properties of each FMU variable including variable name, associated FMU name, input/output type, data type, units and definitions. The user will need to manually copy the FMU information from xxxtmp.idf into the EnergyPlus input file xxx.idf. The user then needs to modify the xxx.idf file to link the FMU variables with EnergyPlus variables.
FMU Parser[LINK]
The FMU parser is a code written in C. It includes Expat (Expat XML Parser, 2011) which is a XML parser library written in C. The low level implementation of the function (parser) that is used to process a FMU is parser [options] xxx.fmu, where options are as follows:
–printidf, prints a temporary xxxtmp.idf with FMU information to be printed,
–unpack, unpacks a FMU to be unpacked, and
–delete, deletes temporary files related to FMUs.
A FMU is a zip file which may contain executable programs for specific platforms, description files and source code. In the pre-processing step, the FMU Parser will be called with the command option –printidf. This will cause the parser to parse the XML file with the model description of the FMU and write the FMU information in a format of the EnergyPlus input file (*.idf). The parser will check if all the required fields from FMU (see next section for details) in the *.idf file are correctly specified. If the check succeeds, the parser will successfully close. If the check fails, the parser will close with an error message. After the EnergyPlus executable (such as EnergyPlus.exe) terminates, the EnergyPlus batch file will delete all the temporary files that may have been generated. The FMU Parser is distributed with EnergyPlus and can be found in the PreProcess folder (FMUParser) of the EnergyPlus installation.
Example 1: Interface using ExternalInterface:FunctionalMockupUnitImport:To:Schedule[LINK]
In this example, an HVAC system implemented in a FMU (MoistAir.fmu) is linked to a room model in EnergyPlus. The HVAC system computes sensible and latent heat gain required for maintaining a set point temperature. The FMU needs as input the outdoor dry-bulb (TDryBul) temperature, outdoor air relative humidity (outRelHum), the room dry-bulb temperature (TRooMea) and the room air relative humidity (rooRelHum). The outputs of the FMU are the latent (QLatent) and sensible (QSensible) heat transported across the thermodynamic boundary of air inlet and outlet of the thermal zone.
To link the FMU with EnergyPlus, we need to send from the FMU to EnergyPlus two schedule values for the latent and sensible heat gain and from EnergyPlus to the FMU four output variables for outdoor dry-bulb temperature, outdoor air relative humidity, room dry-bulb temperature and room air relative humidity at each zone time step. This can be accomplished by using two objects of type ExternalInterface:FunctionalMockupUnitImport:To:Schedule and four objects of type ExternalInterface:FunctionalMockupUnitImport:From:Variable.
To interface EnergyPlus, the following four items are needed:
An object that instructs EnergyPlus to activate the external interface.
An object that specifies the FMU and its instances.
EnergyPlus objects that read data from EnergyPlus and send to FMU.
EnergyPlus objects that read data from FMU and send to EnergyPlus.
Creating the EnergyPlus idf file[LINK]
To create the EnergyPlus idf file the user should:
Use the parser to generate a temporary idf.
Copy the FMU information from the temporary idf into the full idf file.
Modify the full idf file to link the FMU variables with EnergyPlus variables.
The code below shows how the objects will be in the idf.
To activate the external interface, we use:
To define the FMU that will be linked to EnergyPlus, we use:
To enter output variables from which the external interface read and send to FMUs, we use:
These output variables need to be specified in the idf file:
To enter schedules to which the external interface writes, we use:
This completes the configuration that is required to simulate EnergyPlus with the FMU.
Example 2: Interface using ExternalInterface:FunctionalMockupUnitImport:To:Actuator[LINK]
In this example, a shading controller with a finite state machine is implemented in a FMU (ShadingController.fmu). Inputs of the FMU are the outside temperature (TRoo) and the solar irradiation (ISolExt) that is incident on the window. The output of the FMU is the shading actuation signal (yShade).This example describes how to set up EnergyPlus to exchange data between the FMU and EnergyPlus, using an Energy Management System (EMS) actuator.
To interface EnergyPlus using the EMS feature, the following four items are needed:
An object that instructs EnergyPlus to activate the external interface.
An object that specifies the FMU and its instances.
EnergyPlus objects that read data from EnergyPlus and send to FMU.
EnergyPlus objects that read data from FMU and send to EnergyPlus.
Creating the EnergyPlus idf file[LINK]
To create the EnergyPlus idf file the user should:
Use the parser to generate a temporary idf.
Copy the FMU information from the temporary idf into the full idf file.
Modify the full idf file to link the FMU variables with EnergyPlus variables
The code below shows how the objects will be in the idf.
To activate the external interface, we use:
To define the FMU that will be linked to EnergyPlus, we use:
To enter the two output variables from which the external interface read from and send to FMUs, we use:
These output variables need to be specified in the idf file:
To enter the actuator that changes the control status of the window with name “Zn001:Wall001:Win001”, we use:
This completes the configuration that is required to simulate EnergyPlus with the FMU.
Example 3: Interface using ExternalInterface:FunctionalMockupUnitImport:To:Variable[LINK]
This example implements the same controller as the Example 2. However, the interface with EnergyPlus is done using an external interface variable instead of an external interface actuator. Inputs of the FMU are the outside temperature (TRoo) and the solar irradiation (ISolExt) that is incident on the window. The output of the FMU is the shading actuation signal (yShade).
To interface EnergyPlus using an external interface variable, the following items are needed:
An object that instructs EnergyPlus to activate the external interface.
An object that specifies the FMU and its instances.
EnergyPlus objects that read data from EnergyPlus and send to FMU.
EnergyPlus objects that read data from FMU and send to EnergyPlus.
Creating the EnergyPlus idf file[LINK]
To create the EnergyPlus idf file the user should:
Use the parser to generate a temporary idf.
Copy the FMU information from the temporary idf into the full idf file.
Modify the full idf file to link the FMU variables with EnergyPlus
The code below shows how the objects will be in the idf.
To activate the external interface, we use:
To define the FMU that will be linked to EnergyPlus, we use:
To enter the two output variables from which the external interface read from and send to FMUs, we use:
These output variables need to be specified in the idf file:
To write data from the external interface to an EnergyPlus EMS variable, we use the following item in idf file:
which declares a variable with name yShade that can be used in an Erl program to actuate the shading control of the window “Zn001:Wall001:Win001” as follows:
This completes the configuration that is required to simulate EnergyPlus with the FMU.
Documentation content copyright © 1996-2026 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.