Zone Forced Air Unit[LINK]
The input object called ZoneHVAC:ForcedAir:UserDefined
provides a shell for creating custom models of a device that
serves as a single-zone HVAC unit that operates by circulating
air in and out of the zone. This device is analogous to those
component models in the Group – Zone
Forced Air Units, such as ZoneHVAC:PackagedTerminalAirConditioner
or ZoneHVAC:WaterToAirHeatPump.
In addition to the primary air connection that connects 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 three separate plant loop connections
(e.g. hot water, chilled water, heat rejection), a water
supply tank, a water collection tank, and a separate zone for
skin losses.
The zone unit is associated with a thermal zone (by the ZoneHVAC:EquipmentConnections
and ZoneHVAC:EquipmentList
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 is called the primary air connection because
it is how the zone unit is connected to the zone. The inlet
to the custom zone unit is a node that is also an exhaust
outlet from the zone. 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
through the zone exhaust air node.
The primary outlet for the custom zone 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
zone 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 zone 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 zone
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 zone
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
zone 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 zone 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 zone
unit through the secondary air outlet node.
Plant Connections[LINK]
The user defined zone unit can also be connected to up to
three different plants to provide hydronic-based cooling,
heating, and/or heat source or rejection.
Although the zone 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
zone 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 ZoneHVAC:ForcedAir: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 zone 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 zone
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 zone 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 zone 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 zone 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.
Zone Forced Air Unit[LINK]
The input object called ZoneHVAC:ForcedAir:UserDefined provides a shell for creating custom models of a device that serves as a single-zone HVAC unit that operates by circulating air in and out of the zone. This device is analogous to those component models in the Group – Zone Forced Air Units, such as ZoneHVAC:PackagedTerminalAirConditioner or ZoneHVAC:WaterToAirHeatPump.
In addition to the primary air connection that connects 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 three separate plant loop connections (e.g. hot water, chilled water, heat rejection), a water supply tank, a water collection tank, and a separate zone for skin losses.
The zone unit is associated with a thermal zone (by the ZoneHVAC:EquipmentConnections and ZoneHVAC:EquipmentList 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 is called the primary air connection because it is how the zone unit is connected to the zone. The inlet to the custom zone unit is a node that is also an exhaust outlet from the zone. 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 zone 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 zone 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 zone 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 zone 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 zone 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 zone 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 zone 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 zone unit through the secondary air outlet node.
Plant Connections[LINK]
The user defined zone unit can also be connected to up to three different plants to provide hydronic-based cooling, heating, and/or heat source or rejection.
Although the zone 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 zone 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 ZoneHVAC:ForcedAir: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 zone 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 zone 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 zone 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 zone 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 zone 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.