Air Terminal Unit[LINK]
The input object called AirTerminal:SingleDuct:UserDefined
provides a shell for creating custom models for an air
terminal that connects a multi-zone air handler to a thermal
zone. This device is analogous to the single-duct terminal
units in the Group – Air Distribution Equipment, such as AirTerminal:SingleDuct:VAV:Reheat
or AirTerminal:SingleDuct:ConstantVolume:FourPipeInduction.
In addition to the primary air connection that connects
from the air loop to the zone, there are options for
additional connections to a second air stream (e.g. for
outdoor ventilation or heat source or sink), up to two
separate plant loop connections (e.g. hot water and chilled
water), a water supply tank, a water collection tank, and a
separate zone for skin losses.
The air terminal unit is a associated with a thermal zone
(by the ZoneHVAC:EquipmentConnections,
ZoneHVAC:EquipmentList,
and ZoneHVAC:AirDistributionUnit
objects). In EnergyPlus, when there are controlled thermal
zones with thermostat (and humidistat) controls, the central
routines predict the loads that zone equipment need to meet in
order to maintain control of the zone conditions. When there
are multiple types of equipment serving a zone, they are
sequenced to meet heating or cooling loads in a particular
order. Rather than the total predicted load, the second or
third devices need to know the load that remains after the
earlier-sequenced devices have already operated on the zone.
The following internal variables are useful inputs for
controlling zone equipment in your models:
An internal variable called “Remaining Sensible Load to
Heating Setpoint” provides the current value for the sensible
load, in [W], that remains for this device that if delivered
will allow the zone to reach the heating setpoint under
current conditions.
An internal variable called “Remaining Sensible Load to
Cooling Setpoint” provides the current value for the sensible
load, in [W], that remains for this device that if delivered
will allow the zone to reach the cooling setpoint under
current conditions.
An internal variable called “Remaining Latent Load to
Humidifying Setpoint” provides the current value for the
latent load, in [kg/s], that remains for this device that if
delivered will allow the zone to reach the humidification
setpoint under current conditions.
An internal variable called “Remaining Latent Load to
Dehumidifying Setpoint” provides the current value for the
latent load, in [kg/s], that remains for this device that if
delivered will allow the zone to reach the dehumidification
setpoint under current conditions.
Primary Air Connection[LINK]
The primary air connection includes both an inlet and an
outlet that are required to be used when using this
component. This called the primary air connection because it
is how the terminal unit is connected from the air handle to
the zone. The inlet to the custom air terminal unit is a node
that is also the outlet from an AirLoopHVAC:ZoneSplitter
object. The following EMS internal variables are made
available for this inlet node and should be useful inputs to
your own custom models:
An internal variable called “Inlet Temperature for
Primary Air Connection,” provides the current value for the
drybulb air temperature at the component’s inlet node, in
[C].
An internal variable called “Inlet Humidity Ratio for
Primary Air Connection,” provides the current value for the
moist air humidity ratio at the component’s inlet node, in
[kgWater/kgDryAir]
An internal variable called “Inlet Density for Primary
Air Connection,” provides the current value for the density of
moist air at the component’s main inlet node, in [kg/m\(^{3}\)].
An internal variable called “Inlet Specific Heat for
Primary Air Connection,” provides the current value for the
specific heat of moist air at the component’s main inlet node,
in [J/kg-C].
The inlet node also has an actuator associated with it so
that the rate of air flow leaving the thermal zone and
entering the unit can be passed to the rest of EnergyPlus.
- An actuator called “Primary Air Connection,” with the
control type “Inlet Mass Flow Rate,” in [kg/s], needs to be
used. This will set the flow rate of air leaving the zone
splitter and entering the air terminal unit.
The primary outlet for the custom air terminal unit is a
node that is also an inlet to the zone. The following EMS
actuators are created for this outlet node and must be used to
pass results from the custom model to the rest of
EnergyPlus:
An actuator called “Primary Air Connection,” with the
control type “Outlet Temperature,” in [C], needs to be used.
This will set the drybulb temperature of the air leaving the
air terminal unit and entering the zone through the zone air
inlet node.
An actuator called “Primary Air Connection,” with the
control type “Outlet Humidity Ratio,” in [kgWater/kgDryAir],
needs to be used. This will set the humidity ratio of the air
leaving the air terminal unit and entering the zone through
the zone air inlet node.
An actuator called “Primary Air Connection,” with the
control type “Outlet Mass Flow Rate,” in [kg/s], needs to be
used. This will set the flow rate of air leaving the air
terminal unit and entering the zone through the zone air inlet
node.
It is not required that the primary air connections inlet
and outlet mass flow rates be identical. However, if there is
an imbalance, then the model should use the secondary air
connection to balance air mass flows.
Secondary Air
Connection[LINK]
The secondary air connection provides options for an added
inlet node, or outlet node, or both depending on the user’s
needs. This separate air stream can be used for outdoor air
ventilation or as a source or sink for energy. The secondary
air inlet node will often be defined to be an outdoor air node
(ref. OutdoorAir:Node) but that is not required. The
secondary air outlet node can be used as relief exhaust when
the unit is providing outdoor air ventilation. If the
secondary air outlet is not really connected to anything else
and just releases air to the outdoors, then it isn’t necessary
that moist air properties be set using actuators because they
will not impact anything else in the model.
If the secondary air connection inlet node is used, then
the following internal variables and actuator are made
available:
An internal variable called “Inlet Temperature for
Secondary Air Connection,” provides the current value for the
drybulb air temperature at the secondary inlet node, in
[C].
An internal variable called “Inlet Humidity Ratio for
Secondary Air Connection,” provides the current value for the
moist air humidity ratio at the secondary inlet node, in
[kgWater/kgDryAir]
An internal variable called “Inlet Density for
Secondary Air Connection,” provides the current value for the
density of moist air at the secondary inlet node, in
[kg/m\(^{3}\)].
An internal variable called “Inlet Specific Heat for
Secondary Air Connection,” provides the current value for the
specific heat of moist air at the secondary inlet node, in
[J/kg-C].
An actuator called “Secondary Air Connection,” with the
control type “Inlet Mass Flow Rate,” in [kg/s], needs to be
used. This will set the flow rate of air entering the air
terminal unit through the secondary air connection
inlet.
If the secondary air connection outlet node is used, then
the following actuators are created:
An actuator called “Secondary Air Connection,” with the
control type “Outlet Temperature,” in [C], needs to be used.
This will set the drybulb temperature of the air leaving the
air terminal unit through the secondary air outlet
node.
An actuator called “Secondary Air Connection,” with the
control type “Outlet Humidity Ratio,” in [kgWater/kgDryAir],
needs to be used. This will set the humidity ratio of the air
leaving the air terminal unit through the secondary air outlet
node.
An actuator called “Secondary Air Connection,” with the
control type “Outlet Mass Flow Rate,” in [kg/s], needs to be
used. This will set the flow rate of air leaving the air
terminal unit through the secondary air outlet node.
Plant Connections[LINK]
The user defined air terminal unit can also be connected to
up to two different plants to provide hydronic-based cooling,
heating, or heat source or rejection.
Although the air terminal unit actively conditions the
zone, from the point of view of plant they are demand
components. These plant connections are always “demand” in
the sense that the air terminal unit will place loads onto the
plant loops serving it and are not configured to be able to
meet plant loads in the way that supply equipment could
(loading mode is always DemandsLoad). These plant connections
are always of the type that when flow is requested, the loop
will be operated to try and meet the flow request and if not
already running, these flow requests can turn on the loop
(loop flow request mode is always
NeedsFlowAndTurnsLoopOn).
For plant loops, both the inlet and outlet nodes need to be
used for each loop connection. The AirTerminal:SingleDuct:UserDefined
object appears directly on the Branch
object used to describe the plant. The central plant routines
require that each plant component be properly initialized and
registered. Special actuators are provided for these
initializations and they should be filled with values by the
Erl programs that are called by the program calling manager
assigned to the air terminal unit for model setup and sizing.
The following three actuators are created for each of
“N” plant loops and must be used to properly register
the plant connection:
An actuator called “Plant Connection N” with
the control type “Minimum Mass Flow Rate,” in [kg/s], should
be used. This will set the so-called hardware limit for
component’s minimum mass flow rate when operating. (If not
used, then the limit will be set to zero which may be okay for
many if not most models.)
An actuator called “Plant Connection N” with
the control type “Maximum Mass Flow Rate,” in [kg/s], needs to
be used. This will set the so-called hardware limit for the
component’s maximum mass flow rate when operating.
An actuator called “Plant Connection N” with
the control type “Design Volume Flow Rate,” in [m\(^{3}\)/s], needs to be used.
This will register the size of the component for use in sizing
the plant loop and supply equipment that will need to meet the
loads.
For each plant loop connection that is used, the following
internal variables are available for inputs to the custom
component model:
An internal variable called “Inlet Temperature for
Plant Connection N” provides the current value for
the temperature of the fluid entering the component, in
[C].
An internal variable called “Inlet Mass Flow Rate for
Plant Connection N” provides the current value for
the mass flow rate of the fluid entering the component, in
[kg/s].
An internal variable called “Inlet Density for Plant
Connection N” provides the current value for the
density of the fluid entering the component, in [kg/m\(^{3}\)]. This density is
sensitive to the fluid type (e.g. if using glycol in the plant
loop) and fluid temperature at the inlet.
An internal variable called “Inlet Specific Heat for
Plant Connection N” provides the current value for
the specific heat of the fluid entering the component, in
[J/kg-C]. This specific heat is sensitive to the fluid type
(e.g. if using glycol in the plant loop) and fluid temperature
at the inlet.
For each plant loop connection that is used, the following
EMS actuators are created and must be used to pass results
from the custom model to the rest of EnergyPlus:
An actuator called “Plant Connection N” with
the control type “Outlet Temperature,” in [C], needs to be
used. This is the temperature of the fluid leaving the air
terminal unit through that particular plant
connection.
An actuator called “Plant Connection N” with
the control type “Mass Flow Rate,” in kg/s, needs to be used.
This actuator registers the component model’s request for
plant fluid flow. The actual mass flow rate through the
component may be different than requested if the overall loop
situation is such that not enough flow is available to meet
all the various requests. In general, this actuator is used
to lodge a request for flow, but the more accurate flow rate
will be the internal variable called “Inlet Mass Flow Rate for
Plant Connection N.”
The user defined air terminal unit can be connected to the
water use models in EnergyPlus that allow modeling on-site
storage. If a supply inlet water storage tank is used, then
an actuator called “Water System” with the control type
“Supplied Volume Flow Rate,” in m\(^{3}\)/s, needs to be used. This
sets up the air terminal unit as a demand component for that
storage tank. If a collection outlet water storage tank is
used, then an actuator called “Water System” with the control
type “Collected Volume Flow Rate,” in m\(^{3}\)/s, needs to be used.
The user defined air terminal unit can be connected to an
ambient zone and provide internal gains to that zone. The
zone can be different than the one that unit is connected to
via the primary air connection if desired. This is for “skin
losses” that the unit might have that result from
inefficiencies and other non-ideal behavior. When an ambient
zone is specified, the following actuators are created that
can be used for different types of internal gains to the named
zone:
An actuator called “Component Zone
Internal Gain” with the control type “Sensible Heat Gain
Rate,” in [W], is available. This can be used for purely
convective sensible heat gains (or losses) to a zone.
An actuator called “Component Zone
Internal Gain” with the control type “Return Air Heat Gain
Rate,” in [W], is available. This can be used for purely
convective sensible heat gains (or losses) to the return air
duct for a zone.
An actuator called “Component Zone
Internal Gain” with the control type “Thermal Radiation Heat
Gain Rate,” in [W], is available. This can be used for
thermal radiation gains (or losses) to a zone.
An actuator called “Component Zone
Internal Gain” with the control type “Latent Heat Gain Rate,’
in [W], is available. This can be used for latent moisture
gains (or losses) to a zone.
An actuator called “Component Zone
Internal Gain” with the control type “Return Air Latent Heat
Gain Rate,” in [W], is available. This can be used for latent
moisture gains (or losses) to a the return air duct for a
zone.
An actuator called “Component Zone
Internal Gain” with the control type “Carbon Dioxide Gain
Rate,” in [m\(^{3}\)/s], is
available. This can be used for carbon dioxide gains (or
losses) to a zone.
An actuator called “Component Zone
Internal Gain” with the control type “Gaseous Contaminant Gain
Rate,” in [m\(^{3}\)/s], is
available. This can be used for generic gaseous air pollutant
gains (or losses) to a zone.
Air Terminal Unit[LINK]
The input object called AirTerminal:SingleDuct:UserDefined provides a shell for creating custom models for an air terminal that connects a multi-zone air handler to a thermal zone. This device is analogous to the single-duct terminal units in the Group – Air Distribution Equipment, such as AirTerminal:SingleDuct:VAV:Reheat or AirTerminal:SingleDuct:ConstantVolume:FourPipeInduction.
In addition to the primary air connection that connects from the air loop to the zone, there are options for additional connections to a second air stream (e.g. for outdoor ventilation or heat source or sink), up to two separate plant loop connections (e.g. hot water and chilled water), a water supply tank, a water collection tank, and a separate zone for skin losses.
The air terminal unit is a associated with a thermal zone (by the ZoneHVAC:EquipmentConnections, ZoneHVAC:EquipmentList, and ZoneHVAC:AirDistributionUnit objects). In EnergyPlus, when there are controlled thermal zones with thermostat (and humidistat) controls, the central routines predict the loads that zone equipment need to meet in order to maintain control of the zone conditions. When there are multiple types of equipment serving a zone, they are sequenced to meet heating or cooling loads in a particular order. Rather than the total predicted load, the second or third devices need to know the load that remains after the earlier-sequenced devices have already operated on the zone. The following internal variables are useful inputs for controlling zone equipment in your models:
An internal variable called “Remaining Sensible Load to Heating Setpoint” provides the current value for the sensible load, in [W], that remains for this device that if delivered will allow the zone to reach the heating setpoint under current conditions.
An internal variable called “Remaining Sensible Load to Cooling Setpoint” provides the current value for the sensible load, in [W], that remains for this device that if delivered will allow the zone to reach the cooling setpoint under current conditions.
An internal variable called “Remaining Latent Load to Humidifying Setpoint” provides the current value for the latent load, in [kg/s], that remains for this device that if delivered will allow the zone to reach the humidification setpoint under current conditions.
An internal variable called “Remaining Latent Load to Dehumidifying Setpoint” provides the current value for the latent load, in [kg/s], that remains for this device that if delivered will allow the zone to reach the dehumidification setpoint under current conditions.
Primary Air Connection[LINK]
The primary air connection includes both an inlet and an outlet that are required to be used when using this component. This called the primary air connection because it is how the terminal unit is connected from the air handle to the zone. The inlet to the custom air terminal unit is a node that is also the outlet from an AirLoopHVAC:ZoneSplitter object. The following EMS internal variables are made available for this inlet node and should be useful inputs to your own custom models:
An internal variable called “Inlet Temperature for Primary Air Connection,” provides the current value for the drybulb air temperature at the component’s inlet node, in [C].
An internal variable called “Inlet Humidity Ratio for Primary Air Connection,” provides the current value for the moist air humidity ratio at the component’s inlet node, in [kgWater/kgDryAir]
An internal variable called “Inlet Density for Primary Air Connection,” provides the current value for the density of moist air at the component’s main inlet node, in [kg/m\(^{3}\)].
An internal variable called “Inlet Specific Heat for Primary Air Connection,” provides the current value for the specific heat of moist air at the component’s main inlet node, in [J/kg-C].
The inlet node also has an actuator associated with it so that the rate of air flow leaving the thermal zone and entering the unit can be passed to the rest of EnergyPlus.
The primary outlet for the custom air terminal unit is a node that is also an inlet to the zone. The following EMS actuators are created for this outlet node and must be used to pass results from the custom model to the rest of EnergyPlus:
An actuator called “Primary Air Connection,” with the control type “Outlet Temperature,” in [C], needs to be used. This will set the drybulb temperature of the air leaving the air terminal unit and entering the zone through the zone air inlet node.
An actuator called “Primary Air Connection,” with the control type “Outlet Humidity Ratio,” in [kgWater/kgDryAir], needs to be used. This will set the humidity ratio of the air leaving the air terminal unit and entering the zone through the zone air inlet node.
An actuator called “Primary Air Connection,” with the control type “Outlet Mass Flow Rate,” in [kg/s], needs to be used. This will set the flow rate of air leaving the air terminal unit and entering the zone through the zone air inlet node.
It is not required that the primary air connections inlet and outlet mass flow rates be identical. However, if there is an imbalance, then the model should use the secondary air connection to balance air mass flows.
Secondary Air Connection[LINK]
The secondary air connection provides options for an added inlet node, or outlet node, or both depending on the user’s needs. This separate air stream can be used for outdoor air ventilation or as a source or sink for energy. The secondary air inlet node will often be defined to be an outdoor air node (ref. OutdoorAir:Node) but that is not required. The secondary air outlet node can be used as relief exhaust when the unit is providing outdoor air ventilation. If the secondary air outlet is not really connected to anything else and just releases air to the outdoors, then it isn’t necessary that moist air properties be set using actuators because they will not impact anything else in the model.
If the secondary air connection inlet node is used, then the following internal variables and actuator are made available:
An internal variable called “Inlet Temperature for Secondary Air Connection,” provides the current value for the drybulb air temperature at the secondary inlet node, in [C].
An internal variable called “Inlet Humidity Ratio for Secondary Air Connection,” provides the current value for the moist air humidity ratio at the secondary inlet node, in [kgWater/kgDryAir]
An internal variable called “Inlet Density for Secondary Air Connection,” provides the current value for the density of moist air at the secondary inlet node, in [kg/m\(^{3}\)].
An internal variable called “Inlet Specific Heat for Secondary Air Connection,” provides the current value for the specific heat of moist air at the secondary inlet node, in [J/kg-C].
An actuator called “Secondary Air Connection,” with the control type “Inlet Mass Flow Rate,” in [kg/s], needs to be used. This will set the flow rate of air entering the air terminal unit through the secondary air connection inlet.
If the secondary air connection outlet node is used, then the following actuators are created:
An actuator called “Secondary Air Connection,” with the control type “Outlet Temperature,” in [C], needs to be used. This will set the drybulb temperature of the air leaving the air terminal unit through the secondary air outlet node.
An actuator called “Secondary Air Connection,” with the control type “Outlet Humidity Ratio,” in [kgWater/kgDryAir], needs to be used. This will set the humidity ratio of the air leaving the air terminal unit through the secondary air outlet node.
An actuator called “Secondary Air Connection,” with the control type “Outlet Mass Flow Rate,” in [kg/s], needs to be used. This will set the flow rate of air leaving the air terminal unit through the secondary air outlet node.
Plant Connections[LINK]
The user defined air terminal unit can also be connected to up to two different plants to provide hydronic-based cooling, heating, or heat source or rejection.
Although the air terminal unit actively conditions the zone, from the point of view of plant they are demand components. These plant connections are always “demand” in the sense that the air terminal unit will place loads onto the plant loops serving it and are not configured to be able to meet plant loads in the way that supply equipment could (loading mode is always DemandsLoad). These plant connections are always of the type that when flow is requested, the loop will be operated to try and meet the flow request and if not already running, these flow requests can turn on the loop (loop flow request mode is always NeedsFlowAndTurnsLoopOn).
For plant loops, both the inlet and outlet nodes need to be used for each loop connection. The AirTerminal:SingleDuct:UserDefined object appears directly on the Branch object used to describe the plant. The central plant routines require that each plant component be properly initialized and registered. Special actuators are provided for these initializations and they should be filled with values by the Erl programs that are called by the program calling manager assigned to the air terminal unit for model setup and sizing. The following three actuators are created for each of “N” plant loops and must be used to properly register the plant connection:
An actuator called “Plant Connection N” with the control type “Minimum Mass Flow Rate,” in [kg/s], should be used. This will set the so-called hardware limit for component’s minimum mass flow rate when operating. (If not used, then the limit will be set to zero which may be okay for many if not most models.)
An actuator called “Plant Connection N” with the control type “Maximum Mass Flow Rate,” in [kg/s], needs to be used. This will set the so-called hardware limit for the component’s maximum mass flow rate when operating.
An actuator called “Plant Connection N” with the control type “Design Volume Flow Rate,” in [m\(^{3}\)/s], needs to be used. This will register the size of the component for use in sizing the plant loop and supply equipment that will need to meet the loads.
For each plant loop connection that is used, the following internal variables are available for inputs to the custom component model:
An internal variable called “Inlet Temperature for Plant Connection N” provides the current value for the temperature of the fluid entering the component, in [C].
An internal variable called “Inlet Mass Flow Rate for Plant Connection N” provides the current value for the mass flow rate of the fluid entering the component, in [kg/s].
An internal variable called “Inlet Density for Plant Connection N” provides the current value for the density of the fluid entering the component, in [kg/m\(^{3}\)]. This density is sensitive to the fluid type (e.g. if using glycol in the plant loop) and fluid temperature at the inlet.
An internal variable called “Inlet Specific Heat for Plant Connection N” provides the current value for the specific heat of the fluid entering the component, in [J/kg-C]. This specific heat is sensitive to the fluid type (e.g. if using glycol in the plant loop) and fluid temperature at the inlet.
For each plant loop connection that is used, the following EMS actuators are created and must be used to pass results from the custom model to the rest of EnergyPlus:
An actuator called “Plant Connection N” with the control type “Outlet Temperature,” in [C], needs to be used. This is the temperature of the fluid leaving the air terminal unit through that particular plant connection.
An actuator called “Plant Connection N” with the control type “Mass Flow Rate,” in kg/s, needs to be used. This actuator registers the component model’s request for plant fluid flow. The actual mass flow rate through the component may be different than requested if the overall loop situation is such that not enough flow is available to meet all the various requests. In general, this actuator is used to lodge a request for flow, but the more accurate flow rate will be the internal variable called “Inlet Mass Flow Rate for Plant Connection N.”
Water Use[LINK]
The user defined air terminal unit can be connected to the water use models in EnergyPlus that allow modeling on-site storage. If a supply inlet water storage tank is used, then an actuator called “Water System” with the control type “Supplied Volume Flow Rate,” in m\(^{3}\)/s, needs to be used. This sets up the air terminal unit as a demand component for that storage tank. If a collection outlet water storage tank is used, then an actuator called “Water System” with the control type “Collected Volume Flow Rate,” in m\(^{3}\)/s, needs to be used.
Ambient Zone[LINK]
The user defined air terminal unit can be connected to an ambient zone and provide internal gains to that zone. The zone can be different than the one that unit is connected to via the primary air connection if desired. This is for “skin losses” that the unit might have that result from inefficiencies and other non-ideal behavior. When an ambient zone is specified, the following actuators are created that can be used for different types of internal gains to the named zone:
An actuator called “Component Zone Internal Gain” with the control type “Sensible Heat Gain Rate,” in [W], is available. This can be used for purely convective sensible heat gains (or losses) to a zone.
An actuator called “Component Zone Internal Gain” with the control type “Return Air Heat Gain Rate,” in [W], is available. This can be used for purely convective sensible heat gains (or losses) to the return air duct for a zone.
An actuator called “Component Zone Internal Gain” with the control type “Thermal Radiation Heat Gain Rate,” in [W], is available. This can be used for thermal radiation gains (or losses) to a zone.
An actuator called “Component Zone Internal Gain” with the control type “Latent Heat Gain Rate,’ in [W], is available. This can be used for latent moisture gains (or losses) to a zone.
An actuator called “Component Zone Internal Gain” with the control type “Return Air Latent Heat Gain Rate,” in [W], is available. This can be used for latent moisture gains (or losses) to a the return air duct for a zone.
An actuator called “Component Zone Internal Gain” with the control type “Carbon Dioxide Gain Rate,” in [m\(^{3}\)/s], is available. This can be used for carbon dioxide gains (or losses) to a zone.
An actuator called “Component Zone Internal Gain” with the control type “Gaseous Contaminant Gain Rate,” in [m\(^{3}\)/s], is available. This can be used for generic gaseous air pollutant gains (or losses) to a zone.
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.