Group – Energy
Management System (EMS)[LINK]
The Energy Management System (EMS) is one of the high-level
control methods available in EnergyPlus. An EMS is able to
access a wide variety of sensor data and use this data to
direct various types of control actions. The concept is to
emulate, inside EnergyPlus, the types of controls possible
with the digital energy management systems used in real
buildings.
In the hierarchy of EnergyPlus controls, the EMS module is
a high-level, generalized, supervisory control for building
systems. The EMS replicates the functionality of many of the
existing high-level control objects in EnergyPlus. Similar to
the AvailabilityManager objects, the EMS can turn on and off
pumps and fans. Similar to the DemandManager objects, the EMS
can turn on and off lights and electric equipment, change the
set points on zone thermostats, and dispatch on-site
generation. Similar to the SetpointManager objects, the EMS
can change the set points on system nodes. Similar to the
PlantEquipmentOperation objects, the EMS can turn on and off
supply-side heating, cooling, and heat rejection equipment,
i.e., boilers, chillers, cooling towers, etc. Similar to the
ElectricLoadCenter:Distribution,
the EMS can turn on and off on-site generation equipment.
A separate document called Application Guide for
EMS contains much more information on how to use the EMS.
The EMS uses the EnergyPlus Runtime Language (Erl) for custom
programming of control routines.
EnergyManagementSystem:Sensor[LINK]
The EnergyManagmentSystem:Sensor object is used to declare
an Erl variable that is linked to EnergyPlus output variables
or meters. EMS sensors are used to get information from
elsewhere in the model for use in control calculations. The
separate output files called eplusout.rdd and eplusout.mdd
provide a listing of the output variables and meters that can
be used as sensors.
This field contains a unique name for the sensor that
becomes the name of a variable for use in Erl programs. No
spaces are allowed in the object name. This name will be a
global variable in Erl programs and cannot duplicate any other
global scope Erl variable.
Field:
Output:Variable or Output:Meter Index Key Name[LINK]
The key reference for the specified output variable. For
example, if System Node Temperature is the output variable,
the unique node name is the key. The Key Name field
should be omitted for weather variables and meters because
they do not have a key.
Field:
Output:Variable or Output:Meter Name[LINK]
The name of the output variable or meter that is to be
mapped to the Erl variable for the sensor. The names that can
be used in a specific model are included in the .RDD output
file.
Examples of this object follow.
EnergyManagementSystem:Sensor,
T1, !Name
Perimeter_ZN_1 , ! Output:Variable or Output:Meter Index Key Name
Zone Mean Air Temperature ; ! Output:Variable or Output:Meter Name
EnergyManagementSystem:Sensor,
PMV5, !Name
Core_ZN , ! Output:Variable Index Key Name
Zone Thermal Comfort Fanger Model PMV ; ! Output:Variable Name
EnergyManagementSystem:Sensor,
T_VAV5FanIn, !Name
VAV_5_HeatC-VAV_5_FanNode , ! Output:Variable Index Key Name
System Node Temperature ; ! Output:Variable Name
EnergyManagementSystem:Sensor,
cooling_setpoint, ! Name
CLGSETP_SCH , ! Output:Variable Index Key Name
Schedule Value ; ! Output:Variable Name
EnergyManagementSystem:Actuator[LINK]
This object maps an Erl variable to a control actuator
elsewhere in EnergyPlus. The EMS then initiates control
actions by changing the value of this variable inside an Erl
program. The Application Guide for EMS contains much more
information on EMS actuators. The eplusout.EDD file can
contain a listing of the actuators available for a specific
model. As a debugging aid, to help catch spelling mistakes for
example, the program checks to see if any actuators were never
used during the simulation and issues a warning for any that
it finds.
The field contains a unique name for the actuator that
becomes the name of a variable for use in Erl programs. No
spaces or other special characters including dash, plus, and
minus, are allowed in the object name. This name will be a
global variable in Erl programs and cannot duplicate any other
global scope Erl variable.
Field: Actuated
Component Unique Name[LINK]
This field defines a unique name for the specific entity
that is to be controlled. The names for each individual
component are listed in the EDD output file when Verbose mode
is used see the input object Output:EnergyManagementSystem
for more on the EDD file. These will often be user-defined
names of input objects or system nodes, but some actuators are
automatically setup by the program and will not be completely
user-defined.
Field: Actuated
Component Type[LINK]
The field defines the type of the entity that is to be
controlled by the actuator. The component types available vary
with the specifics of individual models. The types of
components that can be used as actuators in a specific model
are listed in the EDD output file see the input object Output:EnergyManagementSystem
for more on the EDD file. Components can be object types
defined elsewhere in the IDD but there are other types of
entities such as nodes and system-level actuators that do not
directly correspond to IDF objects.
Field: Actuated
Component Control Type[LINK]
This field defines the type of control to be done on the
specific entity being controlled. The control types available
are listed in the EDD output. Specific components may have
more than one type of control available, such as flow rate or
temperature, and this field is used to distinguish between
them.
Example input objects.
EnergyManagementSystem:Actuator,
VAV_5_NightCycleStatus, ! Name
VAV_5, ! Actuated Component Unique Name
AirLoopHVAC, ! Actuated Component Type
Availability Status; ! Actuated Component Control Type
EnergyManagementSystem:Actuator,
VAV_1_SAT_setpoint, ! Name
VAV_1 Supply Equipment Outlet Node , ! Actuated Component Unique Name
System Node Setpoint, ! Actuated Component Type
Temperature Setpoint; ! Actuated Component Control Type
EnergyManagementSystem:Actuator,
myCLGSETP_SCH_Override, ! Name
CLGSETP_SCH, !- Actuated Component Unique Name
Schedule:Constant, ! Actuated Component Type
Schedule Value; ! Actuated Component Control Type
EnergyManagementSystem:ProgramCallingManager[LINK]
The EnergyManagementSystem:ProgramCallingManager
object is used to specify when individual Erl programs are
run. This object manages two temporal aspects of running Erl
programs. The first is when they are run relative to the rest
of EnergyPlus, and the second is when they are run relative to
each other. EMS applications can use multiple EnergyManagementSystem:ProgramCallingManager
objects. For example, one manager may execute an
initialization program once at the beginning of the run period
while additional managers call various sets of programs from
different EMS Calling Points.
Control schemes can be organized using a multiple Erl
programs and this object this specifies the order in which
they are executed. Program Name 1 is run first,
Program Name 2 is run second, etc. The run order can
be important if there are interactions or dependencies between
two or more programs. Within each program there may be calls
to execute subroutine programs but only calling managers are
used to execute main-level programs.
This is a unique name for this particular program
manager.
Field:
EnergyPlus Model Calling Point[LINK]
This field describes when the Erl programs managed under
this object are called during an EnergyPlus simulation. All of
the programs listed are called at this same calling point.
There are 15 possible calling points summarized below. For
more information see the section on EMS Calling Points in the
Application Guide for EMS.
BeginNewEnvironment. This calling point occurs near the
beginning of each environment period. Environment periods
include sizing periods such as design days and run periods.
This calling point will not be useful for control actions but
is useful for initialization of Erl program variables and
other one-time set up actions for EMS.
AfterNewEnvironmentWarmUpIsComplete. This calling point
occurs at the beginning of each environment period but after
warm up days are complete. Warm up days are used to condition
the transient aspects of the model with the first day before
proceeding. This calling point will not be useful for control
actions but is useful for re-initializing Erl programs with
fresh values after warm up is complete. Programs called from
this point might be used to reset counters or summed variables
that would change during warmup.
BeginZoneTimestepBeforeInitHeatBalance. This calling
point occurs at the beginning of each timestep before
“InitHeatBalance” executes but after the weather manager and
exterior energy use manager. “InitHeatBalance” refers to the
step in EnergyPlus modeling when the solar shading and
daylighting coefficients are calculated. This calling point is
useful for controlling components that affect the building
envelope including surface constructions, window shades, and
shading surfaces. Programs called from this point might
actuate the building envelope or internal gains based on
current weather or on the results from the previous timestep.
Demand management routines might use this calling point to
operate window shades, change active window constructions,
activate exterior shades, etc.
BeginZoneTimestepAfterInitHeatBalance. This calling
point occurs at the beginning of each timestep after
“InitHeatBalance” executes and before
“ManageSurfaceHeatBalance”. “InitHeatBalance” refers to the
step in EnergyPlus modeling when the solar shading and
daylighting coefficients are calculated. This calling point is
useful for controlling components that affect the building
envelope including surface constructions and window shades.
Programs called from this point might actuate the building
envelope or internal gains based on current weather or on the
results from the previous timestep. Demand management routines
might use this calling point to operate window shades, change
active window constructions, etc.
BeginTimestepBeforePredictor. This calling point
happens near the beginning of each timestep but before
predictor executes. Predictor refers to the step in EnergyPlus
modeling where the zone’s thermal loads are calculated. This
calling point is useful for controlling components that affect
the thermal loads that the systems will be attempting to meet.
Programs called from this point might actuate the building
envelope or internal gains based on current weather and the
results from the previous timestep.
AfterPredictorBeforeHVACManagers. This calling point
happens each timestep just after predictor executes but before
the traditional supervisory control models for SetpointManager
and AvailabilityManager are called. This calling point is
useful for a variety of control actions. However, if there are
conflicts, the EMS control actions may be overwritten by the
actions of any traditional SetpointManagers or
AvailabilityManagers in the model.
AfterPredictorAfterHVACManagers. This calling point
happens each timestep after predictor executes and after the
SetpointManager and AvailabilityManager models are called.
This calling point is useful for a variety of control actions.
However, if there are conflicts, SetpointManager or
AvailabilityManager actions may be overwritten by EMS control
actions.
InsideHVACSystemIterationLoop. This calling point
happens each HVAC iteration. The HVAC systems solvers iterate
to convergence within each timestep and this calling point is
inside this iteration loop. This calling point is useful for a
variety of control actions. Being inside the interation loop,
this calling point has the advantage that input data need not
necessarily be lagged from prior timestep results and can, in
some cases, improve the accuracy of controls. The disadvantage
is that programs may run an excessive number of times slowing
down the execution of the program.
EndOfZoneTimestepBeforeZoneReporting. This calling
point happens each zone timestep just before the output
reports are updated for zone-timestep variables and meters.
This calling point is useful for custom output variables with
Zone
frequency because they will be in sync with the rest of the
zone output variables.
EndOfZoneTimestepAfterZoneReporting. This calling point
happens each zone timestep just after the output reports are
updated for zone-timestep variables and meters. This calling
point is the last one of a timestep and is useful for making
control decisions for the next zone timestep using the final
meter values for the current zone timestep.
EndOfSystemTimestepBeforeHVACReporting. This calling
point happens each system timestep just before the output
reports are updated for HVAC-timestep variables and meters.
This calling point is useful for custom output variables with
HVAC frequency because they will be in sync with the rest of
the system output variables.
EndOfSystemTimestepAfterHVACReporting. This calling
point happens each system timestep just after the output
reports are updated for HVAC-timestep variables and meters.
This calling point is useful for making control decisions for
the next system timestep using the final meter values for the
current system timestep.
EndOfZoneSizing. This calling point happens once during
each simulation and only if the run is set to do zone sizing.
The calling point occurs just after the native zone sizing
calculations are completed but before the sizing results are
finalized. This calling point is useful for taking the
intermediate results of zone sizing calculations and modifying
them based on custom calculations.
EndOfSystemSizing. This calling pont happens once
during each simulation and only if the run is set to do system
sizing. The calling point occurs just after the native air
system sizing calculations are completed but before the sizing
results are finalized. This calling point is useful for taking
the intermediate results of zone and system sizing
calculations and modifying them based on custom
calculations.
AfterComponentInputReadIn. This calling point occurs
early in the simulation when HVAC component s input data has
been processed but before any component-level calculations for
automatic sizing. This calling point occurs once for each of
the types of HVAC components that have EMS actuators for
autosize overrides. This calling point is not directly useful
for control actions but is useful for overriding the results
of sizing at the component level.
UserDefinedComponentModel. This calling point occurs
when user-defined HVAC and plant component models are called
to be simulated. This calling point is only used for the
programs that model custom components. This calling point
differs from the others in that when it is being used the
calls to trigger include a reference to a specific EnergyManagementSystem:ProgramCallingManager
and only the one manger is executed.
UnitarySystemSizing. This calling point occurs when
Unitary systems begin their calculations for determining the
size values for autosized input fields. This calling point is
used for overriding the autosizing outcomes for unitary
systems. Each unitary system in the simulation will call this
point one time. This calling point is used to override sizing
in the following input objects: AirLoopHVAC:UnitarySystem,
AirLoopHVAC:Unitary:Furnace:HeatOnly,
AirLoopHVAC:UnitaryHeatOnly,
AirLoopHVAC:UnitaryHeatCool,AirLoopHVAC:Unitary:Furnace:HeatCool,
AirLoopHVAC:UnitaryHeatPump:AirToAir,
and AirLoopHVAC:UnitaryHeatPump:WaterToAir.
Field: Program Name 1[LINK]
The name of the EnergyManagementSystem:Program
object that will be the first to run for the calling
point.
Field: Program Name 2 ..
N[LINK]
The name of the EnergyManagementSystem:Program
object that will be the second to run. Additional programs can
be listed. The object is automatically extensible to
accommodate as many programs as needed.
IDF examples:
EnergyManagementSystem:ProgramCallingManager,
Initialize EMS for Run , ! Name
BeginNewEnvironment , ! EnergyPlus Model Calling Point
InitializeMyEMS; ! Program Name 1
EnergyManagementSystem:ProgramCallingManager,
EMS-based Setpoint Managers , ! Name
AfterPredictorAfterHVACManagers , ! EnergyPlus Model Calling Point
VAV_5_SchedSetpoint , !Program Name 2
VAV5MixedAirManagers,
VAV_1_SchedSetpoint,
VAV1MixedAirManagers,
VAV_3_SchedSetpoint,
VAV3MixedAirManagers,
VAV_2_SchedSetpoint,
VAV2MixedAirManagers,
CoolSys1_SchedSetpoint,
HeatSys1_SchedSetpoint,
SHWSys1_SchedSetpoint,
VAV_5_NightCycleMGR,
VAV_1_NightCycleMGR,
VAV_2_NightCycleMGR,
VAV_3_NightCycleMGR;
EnergyManagementSystem:Program[LINK]
The EnergyManagementSystem:Program
object is the central processor of the EMS and the primary
container for the EnergyPlus Runtime Language, or
Erl. The EnergyManagementSystem:Program
objects are run in the order and point during an EnergyPlus
simulation that is specified in an EnergyManagementSystem:ProgramCallingManager
object. Multiple EnergyManagementSystem:Program
objects are allowed and may interact (or interfere) with each
other. The Application Guide for EMS provides a
comprehensive overview of Erl programming.
The object definition is very simple. There is a name
followed by lines of Erl program code.
This field is the unique name of the Erl program. The name
can be used to call the program to run from another program or
subroutine. No spaces or other special characters such as
plus, minus, dash, are allowed in the name.
Field Set: Program
lines 1 to N[LINK]
Each remaining field contains a single line of code for the
EnergyPlus Runtime Language, or Erl. Erl is a little
programming language with its own syntax. The commas
separating fields can be thought of as end of line characters.
The Application Guide for EMS provides the details on
Erl program code.
Example IDF input objects follow.
EnergyManagementSystem:Program,
RH_OpeningController , ! Name
IF ZoneRH < 25,
SET MyOpenFactor = 0.0 ,
ELSEIF ZoneRH > 60,
SET MyOpenFactor = 1.0 ,
ELSE,
SET MyOpenFactor = (ZoneRH - 25) / (60 - 25),
ENDIF;
EnergyManagementSystem:Program,
AverageZoneTemps , ! Name
SET Zn1vol = 346.0225, ! zone air volume
SET Zn2vol = 205.2650, ! zone air volume
SET Zn3vol = 346.0225, ! zone air volume
SET Zn4vol = 205.2650, ! zone air volume
SET Zn5vol = 456.4551, ! zone air volume
SET SumNumerator = T1*Zn1vol + T2*Zn2vol + T3*Zn3vol + T4*Zn4vol + T5*Zn5vol,
SET SumDenominator = Zn1vol + Zn2vol + Zn3vol + Zn4vol + Zn5vol,
SET AverageBuildingTemp = SumNumerator / SumDenominator;
EnergyManagementSystem:Program,
VAV2MixedAirManagers , ! Name
SET VAV_2_CoolC_Setpoint = Seasonal_Reset_SAT_Sched - ( T_VAV2FanOut - T_VAV2FanIn),
SET VAV_2_HeatC_Setpoint = Seasonal_Reset_SAT_Sched - ( T_VAV2FanOut - T_VAV2FanIn),
SET VAV_2_OA_Setpoint = Seasonal_Reset_SAT_Sched - ( T_VAV2FanOut - T_VAV2FanIn);
EnergyManagementSystem:Subroutine[LINK]
The EnergyManagementSystem:Subroutine
object contains a block of code written in the EnergyPlus
Runtime Language that can be run from another Erl
program. If the subroutine is never called, it will never run
by itself. Subroutines are useful for encapsulating code that
is called in multiple places. It is also helpful for
organizing and structuring code. When the subroutine finishes
running, control is returned to the object that called it. See
the Application Guide for EMS for information on
writing Erl programs.
The name uniquely identifying the subroutine. The name can
be used to call the subroutine to run from a program or
another subroutine or even itself. No spaces or other special
characters such as minus, dash, plus, are allowed in the
name.
Field set: Lines 1 to N[LINK]
Each remaining field contains a single line of code for the
EnergyPlus Runtime Language, or Erl. Erl is a little
programming language with its own special syntax. The commas
separating fields can be thought of as end of line characters.
The Application Guide for EMS contains the details on
the rules for Erl program code.
IDF examples:
EnergyManagementSystem:Subroutine,
Add4ToN, !- Name
SET N = N + 4; !- EnergyPlus Runtime Language
EnergyManagementSystem:Subroutine,
manage_ext_lights, !- Name
IF inc_solar > 0, !- EnergyPlus Runtime Language
SET ext_lights_pwr = Off,
ELSE,
SET ext_lights_pwr = On,
ENDIF;
EnergyManagementSystem:Subroutine,
manage_solar_collector, !- Name
IF Tout_F < 32, !- EnergyPlus Runtime Language
SET pump_pwr = On,
EXIT,
ENDIF,
SET delta_T = Tcollector Ttank,
IF delta_T > 0,
SET pump_pwr = On,
ELSE,
SET pump_pwr = Off,
ENDIF;
EnergyManagementSystem:GlobalVariable[LINK]
The EnergyManagementSystem:GlobalVariable
object declares one or more global variables that can be
accessed by all Erl programs in the EMS. Erl variables
declared by the user as sensor and actuators objects are
already global variables. Global scope variables are needed to
move date in and out of subroutines because Erl does not
support passing arguments within such calls. Global scope
variables are also needed to pass an Erl variable result to an
output variable. Each field in this object names a new global
Erl variable.
Field: Erl Variable
(1..N) Name[LINK]
The name becomes the global Erl variable name that can be
referenced in the EnergyPlus Runtime Language. No
spaces or other special characters are allowed in the object
name. The name must be unique across all global scope
variables including those declared as sensor and actuators and
the built-in variables.
IDF examples using this object follow:
EnergyManagementSystem:GlobalVariable,
global_var; !- Name
EnergyManagementSystem:GlobalVariable, Temp_C;
EnergyManagementSystem:GlobalVariable, Temp_F;
EnergyManagementSystem:Subroutine,
CalcFahrenheit, !- Name
SET Temp_F = Temp_C * (9/5) + 32;
EnergyManagementSystem:Program,
DummyProgram, !- Name
SET Temp_C = Tout,
RUN CalcFahrenheit,
SET Tout_F = Temp_F,
IF Tout_F > 32,
RUN FreezeProtect,
ENDIF;
EnergyManagementSystem:OutputVariable[LINK]
The EnergyManagementSystem:OutputVariable
object creates a custom output variable that is mapped to an
EMS variable. These can be declared by an EnergyManagementSystem:Sensor
object, an EnergyManagementSystem:Actuator
object, or an EnergyManagementSystem:GlobalVariable
object, or any local variable in an Erl program. The custom
output variable can then be reported to the output file using
the standard EnergyPlus output mechanisms such as with the Output:Variable
object.
The EnergyManagementSystem:OutputVariable
object is a primary way to obtain data from an Erl program and
is likely to be essential for developing and debugging
programs. This object also provides a powerful mechanism to
create custom output variables. See the Application Guide
for EMS for more information.
This field contains the user-defined name for the new
output variable. This is the name that will appear in the RDD
output file and can be referenced in other input for output
such as an Output:Variable
object. By convention, the name is in title case for
capitalization. Units are provided in the Units field.
Field: EMS Variable Name[LINK]
This field contains the EMS variable name that is to be
mapped to the custom output variable. This must be used
elsewhere in Erl programs and cannot have spaces.
Field: Type of Data in
Variable[LINK]
This field describes the nature of the variable. There are
two choices, Averaged or Summed. Averaged variables are state
variables such as temperature, power, or flow rate. Summed
variables are quantities such as energy that accumulate across
time.
Field: Update Frequency[LINK]
This field describes which timestep the variable is
associated with. There are two choices, ZoneTimestep or
SystemTimestep. Variables that are related to the building or
zone loads are generally associated with the zone timestep.
Variables that are related to HVAC system operation are
generally associated with the system timestep.
Field: EMS
Program or Subroutine Name[LINK]
If the EMS variables is a local scope variable, i.e., not
declared as a global scope variable, then this field
identifies which program uses the variable. The field
references the object name of the Erl program or subroutine
object. For global variables, this field should be
omitted.
This field should contain the units for the output variable
in standard EnergyPlus units. It does not need to be enclosed
in square brackets.
Examples of this object follow.
EnergyManagementSystem:OutputVariable,
Weighted Average Building Zone Air Temperature, ! Name
AverageBuildingTemp, ! EMS Variable Name
Averaged, ! Type of Data in Variable
ZoneTimeStep , ! Update Frequency
, ! EMS Program or Subroutine Name
C;
EnergyManagementSystem:OutputVariable,
Main CW Coil Total Cooling Rate, !- Name
CWcoil1_tot_cool_Power, !- EMS Variable Name
Averaged, !- Type of Data in Variable
SystemTimestep, !- Update Frequency
MainCWCoil1_ModelOuput, !- EMS Program or Subroutine Name
W; !- Units
EnergyManagementSystem:MeteredOutputVariable[LINK]
The EnergyManagementSystem:MeteredOutputVariable
object creates a custom output variable that is mapped to an
EMS variable and is also included in the metering system that
EnergyPlus has for aggregating results for different resources
across the model. This object is very similar to EnergyManagementSystem:OutputVariable
with the main differences being that only summed types of data
in the Erl variable and the quantity is to be added to a
meter. This allows for custom output variables that also
impact the results for the amount of electricity or gas
consumed.
This field contains the user-defined name for the new
output variable. This is the name that will appear in the RDD
and MTD output files and can be referenced in other input for
output such as an Output:Variable
object. Units are provided in the Units field.
Field: EMS Variable
Name[LINK]
This field contains the EMS variable name that is to be
mapped to the custom output variable. This must be used
elsewhere in Erl programs and cannot have spaces.
Field: Update Frequency[LINK]
This field describes which timestep the variable is
associated with. There are two choices, ZoneTimestep or
SystemTimestep. Variables that are related to the building or
zone loads are generally associated with the zone timestep.
Variables that are related to HVAC system operation are
generally associated with the system timestep.
Field: EMS
Program or Subroutine Name[LINK]
If the EMS variables is a local scope variable, i.e., not
declared as a global scope variable, then this field
identifies which program uses the variable. The field
references the object name of the Erl program or subroutine
object. For global variables, this field should be
omitted.
Field: Resource Type[LINK]
This field is used to specify the type of resource that the
output variable consumes or produces. The choice here will
determine which of the meters the output should be added to
when EnergyPlus aggregates results for overall consumption.
The following keywords can be used to choose the type of
resource that should be metered:
Electricity, this selects the main
meter for electricity consumption, in units of Joules
[J],
NaturalGas, this selects the meter for
natural gas consumption, in units of Joules [J],
Gasoline, this selects the meter for
gasoline consumption, in units of Joules [J],
Diesel, this selects the meter for
diesel consumption, in units of Joules [J],
Coal, this selects the meter for coal
consumption, in units of Joules [J],
FuelOilNo1, this selects the meter for
#1 Fuel Oil consumption, in units of Joules [J],
FuelOilNo2, this selects the meter for
#2 Fuel Oil consumption, in units of Joules [J],
Propane, this selects the meter for
propane consumption, in units of Joules [J],
WaterUse, this selects the meter for
overall water consumption, in units of cubic meters [m\(^{3}\)],
OnSiteWaterProduced, this selects the
meter for overall on-site water collection, in units of cubic
meters [m\(^{3}\)],
MainsWaterSupply, this selects the
meter for water supplied by utility mains, in units of cubic
meters [m\(^{3}\)],
RainWaterCollected, this selects the
meter for water collected from rain, in units of cubic meters
[m\(^{3}\)],
WellWaterDrawn, this selects the meter
for water drawn from a local well, in units of cubic meters
[m\(^{3}\)],
CondensateWaterCollected, this selects
the meter for water collected from cooling coils as
condensate, in units of cubic meters [m\(^{3}\)],
EnergyTransfer, this selects the
general meter for energy transfers, in units of Joules
[J],
Steam, this selects the meter for
steam energy consumption, in units of Joules [J],
DistrictCooling,
this selects the meter for district chilled water energy
consumption, in units of Joules [J],
DistrictHeating,
this selects the meter for district hot water energy
consumption, in units of Joules [J],
ElectricityProducedOnSite, this
selects the meter for electricity produced on the site, in
units of Joules [J],
SolarWaterHeating, this selects the
meter for hot water heating energy from solar collectors, in
units of Joules [J], and,
SolarAirHeating, this selects the
meter for air heating energy from solar collectors in units of
Joules [J],.
Field: Group Type[LINK]
This field is used to specify how the output variable fits
into the categorization scheme used by the metering system in
EnergyPlus to identify what part of the model is involved.
Metered output variables are classified as being in one of the
following general groups:
Building,
this category includes all the meters associated with parts of
the building that are not related to HVAC or Plant. This
includes internal and exterior services such as lights,
electric equipment, exterior lights, etc.
HVAC, this category includes all the
meters associated with parts of the HVAC system that are
related to air and zone thermal conditioning and ventilation
(but not hydronic plant systems). This includes things like
fans, air conditioners, furnaces etc.
Plant, this category includes all the
meters associated with parts of the hydronic plant system that
are related to heating, cooling, service water heating, and
heat rejection. This includes things like boilers, chillers,
water heaters, towers, etc.
Field: End-Use Category[LINK]
This field is used to specify the end use category that
should be assigned to the resource associated with the output
variable. EnergyPlus reporting includes the breakdown of how
resources are used across different end uses. Metered output
variables must be classified as being in one of the following
end use categories:
Heating
Cooling
InteriorLights
ExteriorLights
InteriorEquipment
ExteriorEquipment
Fans
Pumps
HeatRejection
Humidifier
HeatRecovery
WaterSystems
Refrigeration
OnSiteGeneration
Field: End-Use
Subcategory[LINK]
This field is used to specify the end use subcategory that
will be assigned to the output variable. EnergyPlus reporting
includes the breakdown of how resources are used across
different end uses with added breakdown for the different
subcategories within a particular end use. This user can
define his or her own subcategories and enter them in this
field. Subcategories are reported in the ABUPS End Uses by
Subcategory table and also appear in the LEED Summary EAp2-4/5
Performance Rating Method Compliance table. If left blank,
then no subcategory classification is made and the output is
included in the general subcategory for the end use category
determined in the previous field.
This field should contain the units for the output variable
in standard EnergyPlus units. It does not need to be enclosed
in square brackets.
Examples of this object follow.
EnergyManagementSystem:MeteredOutputVariable,
Zone 1 WinAC Electricity Consumption, !- Name
Zone1WinAC_ElectEnergy, !- EMS Variable Name
SystemTimestep, !- Update Frequency
Zone1_WinAC_ModelOuput, !- EMS Program or Subroutine Name
Electricity, !- Resource Type
HVAC, !- Group Type
Cooling, !- End-Use Category
Window Air Conditioners, !- End-Use Subcategory
J; !- Units
EnergyManagementSystem:TrendVariable[LINK]
The EnergyManagementSystem:TrendVariable
object declares a global trend EMS variable that can be
accessed by all Erl programs in the EMS. Trend variables store
the recent history of the Erl variable they are associated
with. The trend data are useful for examining the progression
of time series data. The user declares a new trend variable
using this object and associates it with another global Erl
variable that will be logged. Trend data are pushed into a
stack so that the most recent data are always at the beginning
of the stack. Once the stack is full, the oldest data are lost
from the trend log. Each value in the trend log is for a zone
timestep into the past. The first value in the trend is the
one from the previous zone time step.
The object name becomes the global EMS trend variable name
that can be referenced in the EnergyPlus Runtime
Language. No spaces or any other special characters are
allowed in the name. Then name must be unique across all
global scope variables including those declared as sensor and
actuators and the built-in variables.
Field: EMS Variable
Name[LINK]
This field contains the EMS variable name that is to be
mapped to the trend variable. This must be a global EMS
variable defined elsewhere and cannot have spaces.
Field: Number
of Timesteps to be Logged[LINK]
This field describes how much data are to be held in the
trend variable. The trended data are held in an array with one
value for each data point going back in time. This field
determines how many elements are in that array. If there are
six timesteps per hour and this field is set to 144, then the
trend will contain data for the most recent 24 hours
period.
Examples of this object follow.
EnergyManagementSystem:TrendVariable,
AvgTemptrendLog1, !- Name
AverageBuildingTemp, !- EMS Variable Name
300; !- Number of Timesteps to be Logged
EnergyManagementSystem:TrendVariable,
PMVtrendLog1, , !- Name
PMV5, !- EMS Variable Name
144; !- Number of Timesteps to be Logged
EnergyManagementSystem:InternalVariable[LINK]
The EMS also provides a method to obtain static data from
elsewhere in the model. Whereas EMS sensors are used for
time-varying data, there are also data that describe certain
design parameters for the building which may be useful for EMS
calculations. A method for accessing internal data is provided
as a time saver and means of better generalizing Erl programs
for wider applicability. Information needed for this input
object is output by EnergyPlus to the eplusout.edd file see
the Output:EnergyManagementSystem
input object. The EDD file can list the internal data index
keys and types that are available for use with this object.
The Application Guide for EMS discuses internal variables in
more depth.
This field contains a unique name for the internal variable
that becomes the name of a variable for use in Erl programs.
No spaces, dashes, plus symbols, minus symbols, or other
special characters are allowed in the name. This name will be
a global variable in Erl programs and cannot duplicate any
other global scope EMS variable.
Field: Internal
Data Index Key Name[LINK]
This field contains the unique identifier for the internal
variable. This is usually a name defined by the user elsewhere
in an IDF input object. For example, for an internal variable
for the floor area of a zone, this would be the name of the
zone.
Field: Internal Data
Type[LINK]
This field defines the type of internal data source that is
to be mapped to the EMS variable. The types of internal source
data that can be used as internal variables are listed in the
EIO output file whan an input file has any EMS-related
objects.
An example of this object follows.
EnergyManagementSystem:InternalVariable,
Zn1vol, !- Name
Perimeter_ZN_1, !- Internal Data Index Key Name
Zone Air Volume; !- Internal Data Type
EnergyManagementSystem:CurveOrTableIndexVariable[LINK]
The EMS provides a method for reusing curve and table input
objects from elsewhere in the model. Input objects, such as Curve:Cubic,
Curve:Biquadratic,
or Table:Lookup,
are used by various component models to describe performance
relationships in a generic way. By using an EnergyManagementSystem:CurveOrTableIndexVariable
input object, these curves and tables can be used in your own
Erl programs. This object sets up an Erl variable that
contains an index that points to specific curve or table. This
index variable is then used as the first argument in a call to
the built-in function called @CurveValue so that the correct
curve or table is evaluated.
This field contains a unique name for the index variable
that becomes the name of a variable for use in Erl programs.
No special characters (including spaces) are allowed in the
name. This name will be a global variable in Erl programs and
cannot duplicate any other global scope EMS variable. The
variable will be filled by the EMS system to have a value that
points to the curve or table object named in the following
field.
Field: Curve or
Table Object Name[LINK]
This field contains the unique name of a Curve:* or Table:*
object defined elsewhere in the input file. The Erl variable
in the previous field will be filled with the index for the
curve or table named here. The value of this index tracks the
order that Curve: and Table: input objects are listed in the
input file.
An example IDF object is:
EnergyManagementSystem:CurveOrTableIndexVariable,
Curve_Quadratic_Ptr, !- Name
HPACCOOLPLFFPLR_curve; !- Curve or Table Object Name
EnergyManagementSystem:ConstructionIndexVariable[LINK]
The EMS provides actuators for overriding the type of
construction used by a surface. The EnergyManagementSystem:ConstructionIndexVariable
input object is used to setup an Erl variable that contains an
index that points to specific Construction.
This index variable is then used with a special actuator
called Surface with the control type Construction
State. See the Application Guide for EMS for more information
on how to use this index variable and the associated
actuator.
This field contains a unique name for the index variable
that becomes the name of a variable for use in Erl programs.
No spaces or characters like dashes, minuses, plus symbols,
are allowed in the name. This name will be a global variable
in Erl programs and cannot duplicate any other global scope
EMS variable. The variable will be filled by the EMS system to
have a value that points to the Construction
object named in the following field.
Field: Construction
Object Name[LINK]
This field contains the unique name of a Construction
object defined elsewhere in the input file. The Erl variable
in the previous field will be filled with the index for the Construction
named here. The value of this index tracks the order that Construction
input objects are listed in the input file.
An example IDF object is:
Construction,
TCwindow_25, !- Name
Clear3PPG, !- Outside Layer
AIR 3MM, !- Layer 2
WO18RT25, !- Layer 3
AIR 8MM, !- Layer 4
SB60Clear3PPG; !- Layer 5
EnergyManagementSystem:ConstructionIndexVariable,
TCwindow_25,
TCwindow_25;
Group – Energy Management System (EMS)[LINK]
The Energy Management System (EMS) is one of the high-level control methods available in EnergyPlus. An EMS is able to access a wide variety of sensor data and use this data to direct various types of control actions. The concept is to emulate, inside EnergyPlus, the types of controls possible with the digital energy management systems used in real buildings.
In the hierarchy of EnergyPlus controls, the EMS module is a high-level, generalized, supervisory control for building systems. The EMS replicates the functionality of many of the existing high-level control objects in EnergyPlus. Similar to the AvailabilityManager objects, the EMS can turn on and off pumps and fans. Similar to the DemandManager objects, the EMS can turn on and off lights and electric equipment, change the set points on zone thermostats, and dispatch on-site generation. Similar to the SetpointManager objects, the EMS can change the set points on system nodes. Similar to the PlantEquipmentOperation objects, the EMS can turn on and off supply-side heating, cooling, and heat rejection equipment, i.e., boilers, chillers, cooling towers, etc. Similar to the ElectricLoadCenter:Distribution, the EMS can turn on and off on-site generation equipment.
A separate document called Application Guide for EMS contains much more information on how to use the EMS. The EMS uses the EnergyPlus Runtime Language (Erl) for custom programming of control routines.
EnergyManagementSystem:Sensor[LINK]
The EnergyManagmentSystem:Sensor object is used to declare an Erl variable that is linked to EnergyPlus output variables or meters. EMS sensors are used to get information from elsewhere in the model for use in control calculations. The separate output files called eplusout.rdd and eplusout.mdd provide a listing of the output variables and meters that can be used as sensors.
Inputs[LINK]
Field: Name[LINK]
This field contains a unique name for the sensor that becomes the name of a variable for use in Erl programs. No spaces are allowed in the object name. This name will be a global variable in Erl programs and cannot duplicate any other global scope Erl variable.
Field: Output:Variable or Output:Meter Index Key Name[LINK]
The key reference for the specified output variable. For example, if System Node Temperature is the output variable, the unique node name is the key. The Key Name field should be omitted for weather variables and meters because they do not have a key.
Field: Output:Variable or Output:Meter Name[LINK]
The name of the output variable or meter that is to be mapped to the Erl variable for the sensor. The names that can be used in a specific model are included in the .RDD output file.
Examples of this object follow.
EnergyManagementSystem:Actuator[LINK]
This object maps an Erl variable to a control actuator elsewhere in EnergyPlus. The EMS then initiates control actions by changing the value of this variable inside an Erl program. The Application Guide for EMS contains much more information on EMS actuators. The eplusout.EDD file can contain a listing of the actuators available for a specific model. As a debugging aid, to help catch spelling mistakes for example, the program checks to see if any actuators were never used during the simulation and issues a warning for any that it finds.
Inputs[LINK]
Field: Name[LINK]
The field contains a unique name for the actuator that becomes the name of a variable for use in Erl programs. No spaces or other special characters including dash, plus, and minus, are allowed in the object name. This name will be a global variable in Erl programs and cannot duplicate any other global scope Erl variable.
Field: Actuated Component Unique Name[LINK]
This field defines a unique name for the specific entity that is to be controlled. The names for each individual component are listed in the EDD output file when Verbose mode is used see the input object Output:EnergyManagementSystem for more on the EDD file. These will often be user-defined names of input objects or system nodes, but some actuators are automatically setup by the program and will not be completely user-defined.
Field: Actuated Component Type[LINK]
The field defines the type of the entity that is to be controlled by the actuator. The component types available vary with the specifics of individual models. The types of components that can be used as actuators in a specific model are listed in the EDD output file see the input object Output:EnergyManagementSystem for more on the EDD file. Components can be object types defined elsewhere in the IDD but there are other types of entities such as nodes and system-level actuators that do not directly correspond to IDF objects.
Field: Actuated Component Control Type[LINK]
This field defines the type of control to be done on the specific entity being controlled. The control types available are listed in the EDD output. Specific components may have more than one type of control available, such as flow rate or temperature, and this field is used to distinguish between them.
Example input objects.
EnergyManagementSystem:ProgramCallingManager[LINK]
The EnergyManagementSystem:ProgramCallingManager object is used to specify when individual Erl programs are run. This object manages two temporal aspects of running Erl programs. The first is when they are run relative to the rest of EnergyPlus, and the second is when they are run relative to each other. EMS applications can use multiple EnergyManagementSystem:ProgramCallingManager objects. For example, one manager may execute an initialization program once at the beginning of the run period while additional managers call various sets of programs from different EMS Calling Points.
Control schemes can be organized using a multiple Erl programs and this object this specifies the order in which they are executed. Program Name 1 is run first, Program Name 2 is run second, etc. The run order can be important if there are interactions or dependencies between two or more programs. Within each program there may be calls to execute subroutine programs but only calling managers are used to execute main-level programs.
Inputs[LINK]
Field: Name[LINK]
This is a unique name for this particular program manager.
Field: EnergyPlus Model Calling Point[LINK]
This field describes when the Erl programs managed under this object are called during an EnergyPlus simulation. All of the programs listed are called at this same calling point. There are 15 possible calling points summarized below. For more information see the section on EMS Calling Points in the Application Guide for EMS.
BeginNewEnvironment. This calling point occurs near the beginning of each environment period. Environment periods include sizing periods such as design days and run periods. This calling point will not be useful for control actions but is useful for initialization of Erl program variables and other one-time set up actions for EMS.
AfterNewEnvironmentWarmUpIsComplete. This calling point occurs at the beginning of each environment period but after warm up days are complete. Warm up days are used to condition the transient aspects of the model with the first day before proceeding. This calling point will not be useful for control actions but is useful for re-initializing Erl programs with fresh values after warm up is complete. Programs called from this point might be used to reset counters or summed variables that would change during warmup.
BeginZoneTimestepBeforeInitHeatBalance. This calling point occurs at the beginning of each timestep before “InitHeatBalance” executes but after the weather manager and exterior energy use manager. “InitHeatBalance” refers to the step in EnergyPlus modeling when the solar shading and daylighting coefficients are calculated. This calling point is useful for controlling components that affect the building envelope including surface constructions, window shades, and shading surfaces. Programs called from this point might actuate the building envelope or internal gains based on current weather or on the results from the previous timestep. Demand management routines might use this calling point to operate window shades, change active window constructions, activate exterior shades, etc.
BeginZoneTimestepAfterInitHeatBalance. This calling point occurs at the beginning of each timestep after “InitHeatBalance” executes and before “ManageSurfaceHeatBalance”. “InitHeatBalance” refers to the step in EnergyPlus modeling when the solar shading and daylighting coefficients are calculated. This calling point is useful for controlling components that affect the building envelope including surface constructions and window shades. Programs called from this point might actuate the building envelope or internal gains based on current weather or on the results from the previous timestep. Demand management routines might use this calling point to operate window shades, change active window constructions, etc.
BeginTimestepBeforePredictor. This calling point happens near the beginning of each timestep but before predictor executes. Predictor refers to the step in EnergyPlus modeling where the zone’s thermal loads are calculated. This calling point is useful for controlling components that affect the thermal loads that the systems will be attempting to meet. Programs called from this point might actuate the building envelope or internal gains based on current weather and the results from the previous timestep.
AfterPredictorBeforeHVACManagers. This calling point happens each timestep just after predictor executes but before the traditional supervisory control models for SetpointManager and AvailabilityManager are called. This calling point is useful for a variety of control actions. However, if there are conflicts, the EMS control actions may be overwritten by the actions of any traditional SetpointManagers or AvailabilityManagers in the model.
AfterPredictorAfterHVACManagers. This calling point happens each timestep after predictor executes and after the SetpointManager and AvailabilityManager models are called. This calling point is useful for a variety of control actions. However, if there are conflicts, SetpointManager or AvailabilityManager actions may be overwritten by EMS control actions.
InsideHVACSystemIterationLoop. This calling point happens each HVAC iteration. The HVAC systems solvers iterate to convergence within each timestep and this calling point is inside this iteration loop. This calling point is useful for a variety of control actions. Being inside the interation loop, this calling point has the advantage that input data need not necessarily be lagged from prior timestep results and can, in some cases, improve the accuracy of controls. The disadvantage is that programs may run an excessive number of times slowing down the execution of the program.
EndOfZoneTimestepBeforeZoneReporting. This calling point happens each zone timestep just before the output reports are updated for zone-timestep variables and meters. This calling point is useful for custom output variables with Zone frequency because they will be in sync with the rest of the zone output variables.
EndOfZoneTimestepAfterZoneReporting. This calling point happens each zone timestep just after the output reports are updated for zone-timestep variables and meters. This calling point is the last one of a timestep and is useful for making control decisions for the next zone timestep using the final meter values for the current zone timestep.
EndOfSystemTimestepBeforeHVACReporting. This calling point happens each system timestep just before the output reports are updated for HVAC-timestep variables and meters. This calling point is useful for custom output variables with HVAC frequency because they will be in sync with the rest of the system output variables.
EndOfSystemTimestepAfterHVACReporting. This calling point happens each system timestep just after the output reports are updated for HVAC-timestep variables and meters. This calling point is useful for making control decisions for the next system timestep using the final meter values for the current system timestep.
EndOfZoneSizing. This calling point happens once during each simulation and only if the run is set to do zone sizing. The calling point occurs just after the native zone sizing calculations are completed but before the sizing results are finalized. This calling point is useful for taking the intermediate results of zone sizing calculations and modifying them based on custom calculations.
EndOfSystemSizing. This calling pont happens once during each simulation and only if the run is set to do system sizing. The calling point occurs just after the native air system sizing calculations are completed but before the sizing results are finalized. This calling point is useful for taking the intermediate results of zone and system sizing calculations and modifying them based on custom calculations.
AfterComponentInputReadIn. This calling point occurs early in the simulation when HVAC component s input data has been processed but before any component-level calculations for automatic sizing. This calling point occurs once for each of the types of HVAC components that have EMS actuators for autosize overrides. This calling point is not directly useful for control actions but is useful for overriding the results of sizing at the component level.
UserDefinedComponentModel. This calling point occurs when user-defined HVAC and plant component models are called to be simulated. This calling point is only used for the programs that model custom components. This calling point differs from the others in that when it is being used the calls to trigger include a reference to a specific EnergyManagementSystem:ProgramCallingManager and only the one manger is executed.
UnitarySystemSizing. This calling point occurs when Unitary systems begin their calculations for determining the size values for autosized input fields. This calling point is used for overriding the autosizing outcomes for unitary systems. Each unitary system in the simulation will call this point one time. This calling point is used to override sizing in the following input objects: AirLoopHVAC:UnitarySystem, AirLoopHVAC:Unitary:Furnace:HeatOnly, AirLoopHVAC:UnitaryHeatOnly, AirLoopHVAC:UnitaryHeatCool,AirLoopHVAC:Unitary:Furnace:HeatCool, AirLoopHVAC:UnitaryHeatPump:AirToAir, and AirLoopHVAC:UnitaryHeatPump:WaterToAir.
Field: Program Name 1[LINK]
The name of the EnergyManagementSystem:Program object that will be the first to run for the calling point.
Field: Program Name 2 .. N[LINK]
The name of the EnergyManagementSystem:Program object that will be the second to run. Additional programs can be listed. The object is automatically extensible to accommodate as many programs as needed.
IDF examples:
EnergyManagementSystem:Program[LINK]
The EnergyManagementSystem:Program object is the central processor of the EMS and the primary container for the EnergyPlus Runtime Language, or Erl. The EnergyManagementSystem:Program objects are run in the order and point during an EnergyPlus simulation that is specified in an EnergyManagementSystem:ProgramCallingManager object. Multiple EnergyManagementSystem:Program objects are allowed and may interact (or interfere) with each other. The Application Guide for EMS provides a comprehensive overview of Erl programming.
The object definition is very simple. There is a name followed by lines of Erl program code.
Inputs[LINK]
Field: Name[LINK]
This field is the unique name of the Erl program. The name can be used to call the program to run from another program or subroutine. No spaces or other special characters such as plus, minus, dash, are allowed in the name.
Field Set: Program lines 1 to N[LINK]
Each remaining field contains a single line of code for the EnergyPlus Runtime Language, or Erl. Erl is a little programming language with its own syntax. The commas separating fields can be thought of as end of line characters. The Application Guide for EMS provides the details on Erl program code.
Example IDF input objects follow.
EnergyManagementSystem:Subroutine[LINK]
The EnergyManagementSystem:Subroutine object contains a block of code written in the EnergyPlus Runtime Language that can be run from another Erl program. If the subroutine is never called, it will never run by itself. Subroutines are useful for encapsulating code that is called in multiple places. It is also helpful for organizing and structuring code. When the subroutine finishes running, control is returned to the object that called it. See the Application Guide for EMS for information on writing Erl programs.
Inputs[LINK]
Field: Name[LINK]
The name uniquely identifying the subroutine. The name can be used to call the subroutine to run from a program or another subroutine or even itself. No spaces or other special characters such as minus, dash, plus, are allowed in the name.
Field set: Lines 1 to N[LINK]
Each remaining field contains a single line of code for the EnergyPlus Runtime Language, or Erl. Erl is a little programming language with its own special syntax. The commas separating fields can be thought of as end of line characters. The Application Guide for EMS contains the details on the rules for Erl program code.
IDF examples:
EnergyManagementSystem:GlobalVariable[LINK]
The EnergyManagementSystem:GlobalVariable object declares one or more global variables that can be accessed by all Erl programs in the EMS. Erl variables declared by the user as sensor and actuators objects are already global variables. Global scope variables are needed to move date in and out of subroutines because Erl does not support passing arguments within such calls. Global scope variables are also needed to pass an Erl variable result to an output variable. Each field in this object names a new global Erl variable.
Inputs[LINK]
Field: Erl Variable (1..N) Name[LINK]
The name becomes the global Erl variable name that can be referenced in the EnergyPlus Runtime Language. No spaces or other special characters are allowed in the object name. The name must be unique across all global scope variables including those declared as sensor and actuators and the built-in variables.
IDF examples using this object follow:
EnergyManagementSystem:OutputVariable[LINK]
The EnergyManagementSystem:OutputVariable object creates a custom output variable that is mapped to an EMS variable. These can be declared by an EnergyManagementSystem:Sensor object, an EnergyManagementSystem:Actuator object, or an EnergyManagementSystem:GlobalVariable object, or any local variable in an Erl program. The custom output variable can then be reported to the output file using the standard EnergyPlus output mechanisms such as with the Output:Variable object.
The EnergyManagementSystem:OutputVariable object is a primary way to obtain data from an Erl program and is likely to be essential for developing and debugging programs. This object also provides a powerful mechanism to create custom output variables. See the Application Guide for EMS for more information.
Inputs[LINK]
Field: Name[LINK]
This field contains the user-defined name for the new output variable. This is the name that will appear in the RDD output file and can be referenced in other input for output such as an Output:Variable object. By convention, the name is in title case for capitalization. Units are provided in the Units field.
Field: EMS Variable Name[LINK]
This field contains the EMS variable name that is to be mapped to the custom output variable. This must be used elsewhere in Erl programs and cannot have spaces.
Field: Type of Data in Variable[LINK]
This field describes the nature of the variable. There are two choices, Averaged or Summed. Averaged variables are state variables such as temperature, power, or flow rate. Summed variables are quantities such as energy that accumulate across time.
Field: Update Frequency[LINK]
This field describes which timestep the variable is associated with. There are two choices, ZoneTimestep or SystemTimestep. Variables that are related to the building or zone loads are generally associated with the zone timestep. Variables that are related to HVAC system operation are generally associated with the system timestep.
Field: EMS Program or Subroutine Name[LINK]
If the EMS variables is a local scope variable, i.e., not declared as a global scope variable, then this field identifies which program uses the variable. The field references the object name of the Erl program or subroutine object. For global variables, this field should be omitted.
Field: Units[LINK]
This field should contain the units for the output variable in standard EnergyPlus units. It does not need to be enclosed in square brackets.
Examples of this object follow.
EnergyManagementSystem:MeteredOutputVariable[LINK]
The EnergyManagementSystem:MeteredOutputVariable object creates a custom output variable that is mapped to an EMS variable and is also included in the metering system that EnergyPlus has for aggregating results for different resources across the model. This object is very similar to EnergyManagementSystem:OutputVariable with the main differences being that only summed types of data in the Erl variable and the quantity is to be added to a meter. This allows for custom output variables that also impact the results for the amount of electricity or gas consumed.
Field: Name[LINK]
This field contains the user-defined name for the new output variable. This is the name that will appear in the RDD and MTD output files and can be referenced in other input for output such as an Output:Variable object. Units are provided in the Units field.
Field: EMS Variable Name[LINK]
This field contains the EMS variable name that is to be mapped to the custom output variable. This must be used elsewhere in Erl programs and cannot have spaces.
Field: Update Frequency[LINK]
This field describes which timestep the variable is associated with. There are two choices, ZoneTimestep or SystemTimestep. Variables that are related to the building or zone loads are generally associated with the zone timestep. Variables that are related to HVAC system operation are generally associated with the system timestep.
Field: EMS Program or Subroutine Name[LINK]
If the EMS variables is a local scope variable, i.e., not declared as a global scope variable, then this field identifies which program uses the variable. The field references the object name of the Erl program or subroutine object. For global variables, this field should be omitted.
Field: Resource Type[LINK]
This field is used to specify the type of resource that the output variable consumes or produces. The choice here will determine which of the meters the output should be added to when EnergyPlus aggregates results for overall consumption. The following keywords can be used to choose the type of resource that should be metered:
Electricity, this selects the main meter for electricity consumption, in units of Joules [J],
NaturalGas, this selects the meter for natural gas consumption, in units of Joules [J],
Gasoline, this selects the meter for gasoline consumption, in units of Joules [J],
Diesel, this selects the meter for diesel consumption, in units of Joules [J],
Coal, this selects the meter for coal consumption, in units of Joules [J],
FuelOilNo1, this selects the meter for #1 Fuel Oil consumption, in units of Joules [J],
FuelOilNo2, this selects the meter for #2 Fuel Oil consumption, in units of Joules [J],
Propane, this selects the meter for propane consumption, in units of Joules [J],
WaterUse, this selects the meter for overall water consumption, in units of cubic meters [m\(^{3}\)],
OnSiteWaterProduced, this selects the meter for overall on-site water collection, in units of cubic meters [m\(^{3}\)],
MainsWaterSupply, this selects the meter for water supplied by utility mains, in units of cubic meters [m\(^{3}\)],
RainWaterCollected, this selects the meter for water collected from rain, in units of cubic meters [m\(^{3}\)],
WellWaterDrawn, this selects the meter for water drawn from a local well, in units of cubic meters [m\(^{3}\)],
CondensateWaterCollected, this selects the meter for water collected from cooling coils as condensate, in units of cubic meters [m\(^{3}\)],
EnergyTransfer, this selects the general meter for energy transfers, in units of Joules [J],
Steam, this selects the meter for steam energy consumption, in units of Joules [J],
DistrictCooling, this selects the meter for district chilled water energy consumption, in units of Joules [J],
DistrictHeating, this selects the meter for district hot water energy consumption, in units of Joules [J],
ElectricityProducedOnSite, this selects the meter for electricity produced on the site, in units of Joules [J],
SolarWaterHeating, this selects the meter for hot water heating energy from solar collectors, in units of Joules [J], and,
SolarAirHeating, this selects the meter for air heating energy from solar collectors in units of Joules [J],.
Field: Group Type[LINK]
This field is used to specify how the output variable fits into the categorization scheme used by the metering system in EnergyPlus to identify what part of the model is involved. Metered output variables are classified as being in one of the following general groups:
Building, this category includes all the meters associated with parts of the building that are not related to HVAC or Plant. This includes internal and exterior services such as lights, electric equipment, exterior lights, etc.
HVAC, this category includes all the meters associated with parts of the HVAC system that are related to air and zone thermal conditioning and ventilation (but not hydronic plant systems). This includes things like fans, air conditioners, furnaces etc.
Plant, this category includes all the meters associated with parts of the hydronic plant system that are related to heating, cooling, service water heating, and heat rejection. This includes things like boilers, chillers, water heaters, towers, etc.
Field: End-Use Category[LINK]
This field is used to specify the end use category that should be assigned to the resource associated with the output variable. EnergyPlus reporting includes the breakdown of how resources are used across different end uses. Metered output variables must be classified as being in one of the following end use categories:
Heating
Cooling
InteriorLights
ExteriorLights
InteriorEquipment
ExteriorEquipment
Fans
Pumps
HeatRejection
Humidifier
HeatRecovery
WaterSystems
Refrigeration
OnSiteGeneration
Field: End-Use Subcategory[LINK]
This field is used to specify the end use subcategory that will be assigned to the output variable. EnergyPlus reporting includes the breakdown of how resources are used across different end uses with added breakdown for the different subcategories within a particular end use. This user can define his or her own subcategories and enter them in this field. Subcategories are reported in the ABUPS End Uses by Subcategory table and also appear in the LEED Summary EAp2-4/5 Performance Rating Method Compliance table. If left blank, then no subcategory classification is made and the output is included in the general subcategory for the end use category determined in the previous field.
Field: Units[LINK]
This field should contain the units for the output variable in standard EnergyPlus units. It does not need to be enclosed in square brackets.
Examples of this object follow.
EnergyManagementSystem:TrendVariable[LINK]
The EnergyManagementSystem:TrendVariable object declares a global trend EMS variable that can be accessed by all Erl programs in the EMS. Trend variables store the recent history of the Erl variable they are associated with. The trend data are useful for examining the progression of time series data. The user declares a new trend variable using this object and associates it with another global Erl variable that will be logged. Trend data are pushed into a stack so that the most recent data are always at the beginning of the stack. Once the stack is full, the oldest data are lost from the trend log. Each value in the trend log is for a zone timestep into the past. The first value in the trend is the one from the previous zone time step.
Inputs[LINK]
Field: Name[LINK]
The object name becomes the global EMS trend variable name that can be referenced in the EnergyPlus Runtime Language. No spaces or any other special characters are allowed in the name. Then name must be unique across all global scope variables including those declared as sensor and actuators and the built-in variables.
Field: EMS Variable Name[LINK]
This field contains the EMS variable name that is to be mapped to the trend variable. This must be a global EMS variable defined elsewhere and cannot have spaces.
Field: Number of Timesteps to be Logged[LINK]
This field describes how much data are to be held in the trend variable. The trended data are held in an array with one value for each data point going back in time. This field determines how many elements are in that array. If there are six timesteps per hour and this field is set to 144, then the trend will contain data for the most recent 24 hours period.
Examples of this object follow.
EnergyManagementSystem:InternalVariable[LINK]
The EMS also provides a method to obtain static data from elsewhere in the model. Whereas EMS sensors are used for time-varying data, there are also data that describe certain design parameters for the building which may be useful for EMS calculations. A method for accessing internal data is provided as a time saver and means of better generalizing Erl programs for wider applicability. Information needed for this input object is output by EnergyPlus to the eplusout.edd file see the Output:EnergyManagementSystem input object. The EDD file can list the internal data index keys and types that are available for use with this object. The Application Guide for EMS discuses internal variables in more depth.
Inputs[LINK]
Field: Name[LINK]
This field contains a unique name for the internal variable that becomes the name of a variable for use in Erl programs. No spaces, dashes, plus symbols, minus symbols, or other special characters are allowed in the name. This name will be a global variable in Erl programs and cannot duplicate any other global scope EMS variable.
Field: Internal Data Index Key Name[LINK]
This field contains the unique identifier for the internal variable. This is usually a name defined by the user elsewhere in an IDF input object. For example, for an internal variable for the floor area of a zone, this would be the name of the zone.
Field: Internal Data Type[LINK]
This field defines the type of internal data source that is to be mapped to the EMS variable. The types of internal source data that can be used as internal variables are listed in the EIO output file whan an input file has any EMS-related objects.
An example of this object follows.
EnergyManagementSystem:CurveOrTableIndexVariable[LINK]
The EMS provides a method for reusing curve and table input objects from elsewhere in the model. Input objects, such as Curve:Cubic, Curve:Biquadratic, or Table:Lookup, are used by various component models to describe performance relationships in a generic way. By using an EnergyManagementSystem:CurveOrTableIndexVariable input object, these curves and tables can be used in your own Erl programs. This object sets up an Erl variable that contains an index that points to specific curve or table. This index variable is then used as the first argument in a call to the built-in function called @CurveValue so that the correct curve or table is evaluated.
Inputs[LINK]
Field: Name[LINK]
This field contains a unique name for the index variable that becomes the name of a variable for use in Erl programs. No special characters (including spaces) are allowed in the name. This name will be a global variable in Erl programs and cannot duplicate any other global scope EMS variable. The variable will be filled by the EMS system to have a value that points to the curve or table object named in the following field.
Field: Curve or Table Object Name[LINK]
This field contains the unique name of a Curve:* or Table:* object defined elsewhere in the input file. The Erl variable in the previous field will be filled with the index for the curve or table named here. The value of this index tracks the order that Curve: and Table: input objects are listed in the input file.
An example IDF object is:
EnergyManagementSystem:ConstructionIndexVariable[LINK]
The EMS provides actuators for overriding the type of construction used by a surface. The EnergyManagementSystem:ConstructionIndexVariable input object is used to setup an Erl variable that contains an index that points to specific Construction. This index variable is then used with a special actuator called Surface with the control type Construction State. See the Application Guide for EMS for more information on how to use this index variable and the associated actuator.
Inputs[LINK]
Field: Name[LINK]
This field contains a unique name for the index variable that becomes the name of a variable for use in Erl programs. No spaces or characters like dashes, minuses, plus symbols, are allowed in the name. This name will be a global variable in Erl programs and cannot duplicate any other global scope EMS variable. The variable will be filled by the EMS system to have a value that points to the Construction object named in the following field.
Field: Construction Object Name[LINK]
This field contains the unique name of a Construction object defined elsewhere in the input file. The Erl variable in the previous field will be filled with the index for the Construction named here. The value of this index tracks the order that Construction input objects are listed in the input file.
An example IDF object is:
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.