5.3. EnergyPlus

5.3. EnergyPlus
	Chapter 5. Configuring programs for use with the BCVTB

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.

Figure 5.8. Architecture of the BCVTB with the EnergyPlus client (black) and other clients (grey).

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:

Its value is assigned by the external interface.
Its value is fixed during the zone time step because this is the synchronization time step for the external interface.

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
`ExternalInterface:Schedule`	x
`ExternalInterface:Actuator`		x
`ExternalInterface:Variable`			x
`Output:Variable`	x	x	x
`EnergyManagementSystem:OutputVariable`			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

5.3.1. Syntax of the xml file that configures the data mapping between EnergyPlus and the external interface

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.

5.3.2. Example 1: Interface using `ExternalInterface:Schedule`

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.

5.3.2.1. Create an EnergyPlus idf file

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

5.3.2.2. Create a configuration file

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)

5.3.2.3. Create a Ptolemy II model

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.

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 .

Figure 5.10. Configuration of the Simulator actor that calls EnergyPlus on Windows.

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:

Figure 5.11. Configuration of the Simulator actor that calls EnergyPlus on Mac OS X.

This completes the configuration.

Note

	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.

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.

5.3.3. Example 2: Interface using `ExternalInterface:Actuator`

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.

5.3.3.1. Create an EnergyPlus idf file

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

5.3.3.2. Create a configuration file

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” .

5.3.4. Example 3: Interface using `ExternalInterface:Variable`

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.

5.3.4.1. Create an EnergyPlus idf file

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

5.3.4.2. Create a configuration file

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” .


5.2. Ptolemy II		5.4. Dymola