Figure 5.8 shows the architecture of the connection between EnergyPlus and Ptolemy II. Ptolemy II connects to the external interface in EnergyPlus. In the external interface, the input/output signals that are exchanged between Ptolemy II and EnergyPlus are mapped to EnergyPlus objects. The subject of this section is to show how to configure this mapping and how to use these objects.
The external interface can map to three EnergyPlus input
objects called ExternalInterface:Schedule
,
ExternalInterface:Actuator
and
ExternalInterface:Variable
. The
ExternalInterface:Schedule
can be used to
overwrite schedules. 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 EnergyPlus
zone time step, and will remain constant during this zone
time step.
Compared to EnergyManagementSystem:Actuator
,
the object ExternalInterface:Actuator
has an
optional field called “initial value.” If a value is
specified for this field, then this value will be used
during the warm-up period and the system sizing. If
unspecified, then the numerical value for this object
will only be used during the time stepping. Since
actuators always overwrite other objects (such as a
schedule), all these objects have values that are defined
during the warm-up and the system sizing even if no
initial value is specified. For the objects
ExternalInterface:Schedule
and
ExternalInterface:Variable
, the field
“initial value” is required, and its value will be
used during the warm-up period and the system-sizing.
ExternalInterface:Variable
is a global
variable from the point of view of the EMS language.
Thus, it can be used within any
EnergyManagementSystem:Program
in the same
way as an
EnergyManagementSystem:GlobalVariable
or an
EnergyManagementSystem:Sensor
can be used.
Although variables of type
ExternalInterface:Variable
can be assigned
to EnergyManagementSystem:Actuator
objects,
for convenience, there is also an object called
ExternalInterface:Actuator
. This object
behaves identically to
EnergyManagementSystem:Actuator
, with the
following exceptions:
The external interface can also map to the EnergyPlus
objects Output:Variable
and
EnergyManagementSystem:OutputVariable
. These
objects can be used to send data from EnergyPlus to
Ptolemy II at each zone time step.
We will now present examples that use all of these objects. Table 5.2, “ Overview of the EnergyPlus objects used in the examples. ” shows which EnergyPlus features are used in the examples.
Table 5.2. Overview of the EnergyPlus objects used in the examples.
Example 1 |
Example 2 |
Example 3 | |
|
x | ||
|
x | ||
|
x | ||
|
x |
x |
x |
|
x |
To configure the data exchange, the following three steps are required from the user:
Create an EnergyPlus idf file.
Create an xml file that defines the mapping between EnergyPlus and BCVTB variables.
Create a Ptolemy II model.
These steps are described in the examples below. Prior to discussing the examples, we will explain the syntax of the xml configuration file that defines how data are mapped between the external interface and EnergyPlus
The data mapping between EnergyPlus and the external
interface is defined in an xml file called
variables.cfg
. This file needs to be in the
same directory as the EnergyPlus idf file. The file has
the following header:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE BCVTB-variables SYSTEM "variables.dtd">
Following the header is an element of the form
<BCVTB-variables> </BCVTB-variables>
This element will contain child elements that define the
variable mapping. In between the element tags, a user
needs to specify how the exchanged data is mapped to
EnergyPlus objects. Hence, the order of these elements
matter, and it need to be the same as the order of the
elements in the input and output signal vector of
Ptolemy II actor that calls EnergyPlus. The exchanged
variables are declared in elements that are called
“variable” and have an attribute “source.” As
described above, the external interface can send data to
ExternalInterface:Schedule
,
ExternalInterface:Actuator
, and
ExternalInterface:Variable
. For these
objects, the source
attribute needs to be
set to Ptolemy
, because they are sent by
Ptolemy II. The xml elements for these objects are
defined as follows:
For ExternalInterface:Schedule
, use
<variable source="Ptolemy"> <EnergyPlus schedule="NAME"/> </variable>
where NAME
needs to be the EnergyPlus
schedule name. See
Section 5.3.2, “Example 1: Interface using ExternalInterface:Schedule
”
for an example.
For ExternalInterface:Actuator
, use
<variable source="Ptolemy"> <EnergyPlus actuator="NAME" /> </variable>
where NAME
needs to be the EnergyPlus
actuator name. See
Section 5.3.3, “Example 2: Interface using ExternalInterface:Actuator
”
for an example.
For ExternalInterface:Variable
, use
<variable source="Ptolemy"> <EnergyPlus variable="NAME"/> </variable>
where NAME
needs to be the EnergyPlus
Energy Runtime Language (Erl) variable name. See
Section 5.3.4, “Example 3: Interface using ExternalInterface:Variable
”
for an example.
The external interface can also read data from any
Output:Variable
and
EnergyManagementSystem:OutputVariable
. For
these objects, set the "source" attribute to
"EnergyPlus," because they are computed by EnergyPlus.
The read an Output:Variable
, use
<variable source="EnergyPlus"> <EnergyPlus name="NAME" type="TYPE"/> </variable>
where NAME
needs to be the EnergyPlus key
value (which is typically the name of the EnergyPlus
object instance, such as WEST ZONE
) and
TYPE
needs to be the EnergyPlus variable
(such as ZONE/SYS AIR TEMP). See the following
sections for an example.
To read an
EnergyManagementSystem:OutputVariable
,
use
<variable source="EnergyPlus"> <EnergyPlus name="EMS" type="TYPE"/> </variable>
i.e., the attribute name
must be EMS, and
the attribute type
must be set to the EMS
variable name. See
Section 5.3.4, “Example 3: Interface using ExternalInterface:Variable
”
for an example.
The following sections present examples of this xml file.
In this example, a controller that is implemented in
Ptolemy II computes the room temperature set points for
cooling and heating. The example can be found in the
BCVTB distribution in the folder
bcvtb/examples/ePlusX-schedule
, where
X
stands for the EnergyPlus version number.
Suppose we need to send a schedule value from Ptolemy II
to EnergyPlus, and an output variable from EnergyPlus to
Ptolemy II at each zone time step. This can be
accomplished by using an object of type
ExternalInterface:Schedule
and an object of
type Output:Variable
. To interface
EnergyPlus using an EnergyPlus schedule, the following three
items are needed:
An object that instructs EnergyPlus to activate the external interface.
An EnergyPlus schedule object to which the external interface can write to.
A configuration file to configure the data exchange.
The following sections explain how to declare these items.
The EnergyPlus idf file contains the following objects to activate and use the external interface:
An object that instructs EnergyPlus to activate the external interface.
An object of type
ExternalInterface:Schedule
. The external
interface will write its values to these objects at
each zone time-step.
Objects of type Output:Variable
that
store the data that will be read by the external
interface. The value of any EnergyPlus
Output:Variable
can be read by the
external interface.
The code below shows how to declare these objects. To activate the external interface, we use:
ExternalInterface, !- Object to activate the external interface PtolemyServer; !- Name of external interface
To enter schedules to which the external interface writes, we use:
! Cooling schedule. This schedule is set directly by the external interface. ! During warm-up and system-sizing, it is fixed at 24 degC. ExternalInterface:Schedule, TSetCoo, !- Name Temperature, !- ScheduleType 24; !- Initial Value, used during warm-up ! Heating schedule. This schedule is set directly by the external interface. ! During warm-up and system-sizing, it is fixed at 20 degC. ExternalInterface:Schedule, TSetHea, !- Name Temperature, !- ScheduleType 20; !- Initial Value, used during warm-up
These schedules can be used in the same way as other EnergyPlus schedules. In this example, they are used to change a thermostat setpoint:
ThermostatSetpoint:DualSetpoint, DualSetPoint, !- Name TSetHea, !- Heating Setpoint Temperature Schedule Name TSetCoo; !- Cooling Setpoint Temperature Schedule Name
We also want to read output variables from EnergyPlus, which we declare as
Output:Variable, TSetHea, !- Key Value Schedule Value, !- Variable Name TimeStep; !- Reporting Frequency Output:Variable, TSetCoo, !- Key Value Schedule Value, !- Variable Name TimeStep; !- Reporting Frequency
To specify that data should be exchanged every 15
minutes of simulation time, we enter in the
idf
file the section
Timestep, 4; !- Number of Timesteps per Hour
Note that we have not yet specified the order of the
elements in the signal vector that is exchanged between
EnergyPlus and Ptolemy II. This information is
specified in the file variables.cfg
. The
file variables.cfg
needs to be in the same
directory as the EnergyPlus idf
file. For
the objects used in the section above, the file looks
like
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE BCVTB-variables SYSTEM "variables.dtd"> <BCVTB-variables> <!-- The next two elements send the set points to E+ --> <variable source="Ptolemy"> <EnergyPlus schedule="TSetHea"/> </variable> <variable source="Ptolemy"> <EnergyPlus schedule="TSetCoo"/> </variable> <!-- The next two elements receive the outdoor and the zone air temperature from E+ --> <variable source="EnergyPlus"> <EnergyPlus name="ENVIRONMENT" type="OUTDOOR DRY BULB"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="ZSF1" type="ZONE/SYS AIR TEMPERATURE"/> </variable> <!-- The next two elements receive the schedule value as an output from E+ --> <variable source="EnergyPlus"> <EnergyPlus name="TSetHea" type="Schedule Value"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="TSetCoo" type="Schedule Value"/> </variable> </BCVTB-variables>
This file specifies that the actor that calls EnergyPlus has an input vector with two elements that are computed by Ptolemy II and sent to EnergyPlus, and that it has an output vector with four elements that are computed by EnergyPlus and sent to Ptolemy II. The order of the elements in each vector is determined by the order in the above XML file. Hence, the input vector that contains the signals sent to EnergyPlus has elements
TSetHea TSetCoo
and the output vector that contains values computed by EnergyPlus has elements
Environment (Outdoor drybulb temperature) ZSF1 (ZONE/SYS AIR TEMPERATURE) TSetHea (Schedule Value) TSetCoo (Schedule Value)
To start EnergyPlus from the BCVTB, you will need to create a Ptolemy II model.
The model
bcvtb/examples/ePlus*-schedule/system-windows.xml
,
which is part of the BCVTB installation and is shown in
Figure 5.9
, may be used as a starting point. (For Mac and Linux,
use the file system.xml
.) In this example,
the time step is 15 minutes and the simulation period
is four days.
Figure 5.9.
Ptolemy II system model that links an actor that computes the room temperature setpoint with the Simulator
actor that communicates with EnergyPlus.
In this model, the Simulator actor that calls EnergyPlus is configured for Windows as shown in Figure 5.10 .
The actor calls the file RunEPlus.bat
,
with arguments EMSWindowShadeControl
USA_IL_Chicago-OHare.Intl.AP.725300_TMY3
. The
working directory is the current directory and the
console output is written to the file
simulation.log
. If EnergyPlus does not
communicate with Ptolemy II within 10 seconds, Ptolemy
II will terminate the connection. For Mac OS X and
Linux, the configuration is similar:
This completes the configuration.
![]() | Note |
---|---|
In EnergyPlus 8.3.0 and higher, a cross platform's command line interface called energyplus was added to EnergyPlus to run it from the command line. Figure 5.5 shows how the Simulator actor uses this interface to call Energyplus. The actor calls the program energyplus with a list of parameters which are required to launch and execute EnergyPlus. Details about the interface can be found at https://github.com/NREL/EnergyPlus/blob/develop/doc/running-energyplus-from-command-line.md.
|
Figure 5.12.
Configuration of the Simulator
actor that uses the command line interface to call EnergyPlus.
In this example, a shading controller with a finite
state machine is implemented in Ptolemy II. Inputs to
the controller are the outside temperature and the solar
radiation that is incident on the window. The output of
the controller is the shading actuation signal. This
example describes how to set up EnergyPlus to exchange
data between Ptolemy II and EnergyPlus, using an Energy
Management System (EMS) actuator. The example can be
found in the BCVTB distribution in the folder
bcvtb/examples/ePlus*-actuator
, where
*
stands for the EnergyPlus version number.
The object of type
ExternalInterface:Actuator
behaves
identically to
EnergyManagementSystem:Actuator
, with the
following exceptions:
Its value is assigned by the external interface.
Its value is fixed during the EnergyPlus zone time step because this is the synchronization time step for the external interface.
To interface EnergyPlus using the EMS feature, the following three items are needed:
An object that instructs EnergyPlus to activate the external interface.
EnergyPlus objects that write data from the external interface to the EMS.
A configuration file to configure the data exchange.
The following sections explain how to declare these items.
The code below shows how to set up an EnergyPlus file
that uses EnergyManagmentSystem:Actuator
.
To activate the external interface, we use:
ExternalInterface, !- Object to activate the external interface PtolemyServer; !- Name of external interface
To declare an actuator that changes the control status
of the window with name
Zn001:Wall001:Win001
, we use:
ExternalInterface:Actuator, Zn001_Wall001_Win001_Shading_Deploy_Status, !- Name Zn001:Wall001:Win001, !- Actuated Component Unique Name Window Shading Control, !- Actuated Component Type Control Status, !- Actuated Component Control Type ; !- Optional Initial Value
Thus, the entry is identical with
EnergyManagementSystem:Actuator
, except
for the additional optional field that specifies the
initial value. If unspecified, then the actuator will
only be used during the time stepping, but not during
the warm-up and the system sizing. Since actuators
always overwrite other objects (such as a schedule),
all these objects have values that are defined during
the warm-up and the system sizing even if no initial
value is specified.
We also want to read the outdoor temperature, the zone air temperature, the solar radiation that is incident on the window, and the fraction of time that the shading is on from EnergyPlus. Thus, we declare the output variables
Output:Variable, Environment, !- Key Value Outdoor Dry Bulb, !- Variable Name timestep; !- Reporting Frequency Output:Variable, *, !- Key Value Zone Mean Air Temperature, !- Variable Name timestep; !- Reporting Frequency Output:Variable, Zn001:Wall001:Win001, !- Key Value Surface Ext Solar Incident, !- Variable Name timestep; !- Reporting Frequency Output:Variable, *, !- Key Value Fraction of Time Shading Device Is On, !- Variable Name timestep; !- Reporting Frequency
To specify that data should be exchanged every 10 minutes of simulation time, we enter in the idf file the section
Timestep, 6; !- Number of Timesteps per Hour
Note that we have not yet specified the order of the
elements in the signal vector that is exchanged between
EnergyPlus and Ptolemy II. This information is
specified in the file variables.cfg
. The
file variables.cfg
needs to be in the same
directory as the EnergyPlus idf file. For the objects
used in the section above, the file looks like
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE BCVTB-variables SYSTEM "variables.dtd"> <BCVTB-variables> <variable source="EnergyPlus"> <EnergyPlus name="ENVIRONMENT" type="OUTDOOR DRY BULB"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="WEST ZONE" type="Zone Mean Air Temperature"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="Zn001:Wall001:Win001" type="Surface Ext Solar Incident"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="Zn001:Wall001:Win001" type="Fraction of Time Shading Device Is On"/> </variable> <variable source="Ptolemy"> <EnergyPlus actuator="Zn001_Wall001_Win001_Shading_Deploy_Status"/> </variable> </BCVTB-variables>
This file specifies that the simulator actor that calls EnergyPlus has an input vector with one element that will be written to the actuator, and that it has an output vector with four elements that are computed by EnergyPlus and sent to Ptolemy II. The order of the elements in each vector is determined by the order in the above XML file. Hence, the output vector that contains the signals computed by EnergyPlus has elements
ENVIRONMENT (OUTDOOR DRY BULB) WEST ZONE (Zone Mean Air Temperature) Zn001:Wall001:Win001 (Surface Ext Solar Incident) Zn001:Wall001:Win001 (Fraction of Time Shading Device Is On)
The configuration of the Ptolemy II model is identical to the configuration in Example 1., which is described in Section 5.3.2.3, “Create a Ptolemy II model” .
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. In addition, to set up data
that will be read by the external interface, the example
uses an
EnergyManagementSystem:OutputVariable
.
Similarly to
EnergyManagementSystem:GlobalVariable
, an
ExternalInterface:Variable
can be used in
any EnergyManagementSystem:Program
. The
subject of this example is to illustrate how an
ExternalInterface:Variable
can be set up
for use in an
EnergyManagementSystem:Program
. The example
can be found in the BCVTB distribution in the folder
bcvtb/examples/ePlus*-variable
, where
*
stands for the EnergyPlus version number.
To interface EnergyPlus using an external interface variable, the following items are needed:
An object that instructs EnergyPlus to activate the external interface.
EnergyPlus objects that write data from the external interface to the EMS.
A configuration file to configure the data exchange.
The following sections explain how to declare these items.
To write data from the external interface to an
EnergyPlus EMS variable, the following EnergyPlus
objects may be declared in the idf
file:
ExternalInterface, !- Object to activate the external interface PtolemyServer; !- Name of external interface ExternalInterface:Variable, yShade, !- Name of Erl variable 1; !- Initial Value
The above idf
section activates the
external interface and declares a variable with name
yShade
that can be used in an Erl program.
During the warm-up period and the system-sizing, the
variable yShade
will be set to its initial
value. Afterwards, the value will be assigned from the
external interface at each beginning of a zone time
step and kept constant during the zone time step. From
the point of view of the EMS language,
ExternalInterface:Variable
can be used
like any global variable. Thus, it can be used within
any EnergyManagementSystem:Program
in the
same way as an
EnergyManagementSystem:GlobalVariable
or
an EnergyManagementSystem:Sensor
. The
following idf
section uses
yShade
to actuate the shading control of
the window Zn001:Wall001:Win001
:
! 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
Next, suppose we want to read the outdoor temperature,
the zone air temperature and the solar radiation that
is incident on the window. In addition, we want to read
the variable Erl Shading Control Status
.
This can be done with the following declaration:
Output:Variable, Environment, !- Key Value Outdoor Dry Bulb, !- Variable Name timestep; !- Reporting Frequency Output:Variable, *, !- Key Value Zone Mean Air Temperature, !- Variable Name timestep; !- Reporting Frequency Output:Variable, Zn001:Wall001:Win001, !- Key Value Surface Ext Solar Incident, !- Variable Name timestep; !- Reporting Frequency ! Declare an output variable. This variable is equal to the shading ! signal + 0.1. ! It will be read by the external interface to demonstrate how ! to receive variables. EnergyManagementSystem:OutputVariable, Erl Shading Control Status, !- Name Shade_Signal_01, !- EMS Variable Name Averaged, !- Type of Data in Variable ZoneTimeStep; !- Update Frequency
To specify that data should be exchanged every 10
minutes of simulation time, we enter in the
idf
file the section
Timestep, 6; !- Number of Timesteps per Hour
Note that we have not yet specified the order of the
elements in the signal vector that is exchanged between
EnergyPlus and Ptolemy II. This information is
specified in the file variables.cfg
. The
file variables.cfg
needs to be in the same
directory as the EnergyPlus idf file. For the objects
used in the section above, the file looks like
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE BCVTB-variables SYSTEM "variables.dtd"> <BCVTB-variables> <variable source="Ptolemy"> <EnergyPlus variable="yShade"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="ENVIRONMENT" type="OUTDOOR DRY BULB"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="WEST ZONE" type="Zone Mean Air Temperature"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="Zn001:Wall001:Win001" type="Surface Ext Solar Incident"/> </variable> <variable source="EnergyPlus"> <EnergyPlus name="EMS" type="Erl Shading Control Status"/> </variable> </BCVTB-variables>
This file specifies that the simulator actor that calls
EnergyPlus has an input vector with one element that
will be written to the actuator, and that it has an
output vector with four elements that are computed by
EnergyPlus and sent to Ptolemy II. The order of the
elements in each vector is determined by the order in
the above XML file. Note that the fourth element has
the name EMS
because it is an
EnergyManagementSystem:OutputVariable
.
Hence, the output vector that contains the signals
computed by EnergyPlus has elements
ENVIRONMENT (OUTDOOR DRY BULB) WEST ZONE (Zone Mean Air Temperature) Zn001:Wall001:Win001 (Surface Ext Solar Incident) EMS (Erl Shading Control Status)
The configuration of the Ptolemy II model is identical to the configuration of Example 1, which is described in Section 5.3.2.3, “Create a Ptolemy II model” .