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.
BeginZoneTimestepBeforeSetCurrentWeather. This calling point occurs near the beginning of each timestep during weather data setup. It is called from “ManageWeather” before “SetCurrentWeather” which sets the environment variables for a given timestep. “SetCurrentWeather” is where the Weather Data actuators may override certain environment variables. Note that this calling point is not active during sizing.
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 iteration 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 point 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. This object is extensible, so additional fields of this type can be added to the end of this object.
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_Modeloutput, !- 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 No 1 Fuel Oil consumption, in units of Joules [J],
FuelOilNo2, this selects the meter for No 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 [m3],
OnSiteWaterProduced, this selects the meter for overall on-site water collection, in units of cubic meters [m3],
MainsWaterSupply, this selects the meter for water supplied by utility mains, in units of cubic meters [m3],
RainWaterCollected, this selects the meter for water collected from rain, in units of cubic meters [m3],
WellWaterDrawn, this selects the meter for water drawn from a local well, in units of cubic meters [m3],
CondensateWaterCollected, this selects the meter for water collected from cooling coils as condensate, in units of cubic meters [m3],
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],
DistrictHeatingWater, 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_Modeloutput, !- 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 when 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.
BeginZoneTimestepBeforeSetCurrentWeather. This calling point occurs near the beginning of each timestep during weather data setup. It is called from “ManageWeather” before “SetCurrentWeather” which sets the environment variables for a given timestep. “SetCurrentWeather” is where the Weather Data actuators may override certain environment variables. Note that this calling point is not active during sizing.
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 iteration 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 point 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. This object is extensible, so additional fields of this type can be added to the end of this object.
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 No 1 Fuel Oil consumption, in units of Joules [J],
FuelOilNo2, this selects the meter for No 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 [m3],
OnSiteWaterProduced, this selects the meter for overall on-site water collection, in units of cubic meters [m3],
MainsWaterSupply, this selects the meter for water supplied by utility mains, in units of cubic meters [m3],
RainWaterCollected, this selects the meter for water collected from rain, in units of cubic meters [m3],
WellWaterDrawn, this selects the meter for water drawn from a local well, in units of cubic meters [m3],
CondensateWaterCollected, this selects the meter for water collected from cooling coils as condensate, in units of cubic meters [m3],
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],
DistrictHeatingWater, 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 when 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-2023 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.