Plant Component[LINK]
The input object called PlantComponent:UserDefined
provides a shell for creating custom models of a device that
is part of the plant models used for hydronic-type systems.
This object can be used for primary heating or cooling
devices, such as boilers or chillers.
Although the other user-defined component models can also
connect to plant, they are always simple “demand” components
(from the point of view of plant modeling) and their calls to
simulate are led by the air side portions of the program’s
calling tree. The plant-centric component here however, is
called to simulate along with other plant components (in flow
order) by plant’s central routines.
The user defined plant component can use up to four
different plant loop connections, one optional air connection,
a water supply tank, a water collection tank, and an ambient
zone for skin losses.
Plant Connections[LINK]
The user defined plant component can be connected to up to
four different plant loops.
For plant loops, both the inlet and outlet nodes need to be
used for each loop connection. The PlantComponent: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 that particular loop connection for model setup
and sizing. The following six 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.
An actuator called “Plant Connection N” with
the control type “Minimum Loading Capacity,” in [W], needs to
be used if the device is to be used as a supply component with
load-based operation schemes.
An actuator called “Plant connection N” with
the control type “Maximum Loading Capacity,” in [W], needs to
be used if the device is to be used as a supply component with
load-based operation schemes.
An actuator called “Plant Connection N” with
the control type “Optimal Loading Capacity,” in [W], needs to
be used if the device is to be used as a supply component with
load-based operation schemes.
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.
An internal variable called “Load Request for Plant
Connection N” provides the current value for the desired
operating capacity, in [W]. This is the input for how the
model is being asked to meet the loads on the supply side.
This is the result of the central routines for operation
schemes and should be useful for controlling a plant model.
(This internal variable is not made available when this plant
connection’s loading mode is set to DemandsLoad.)
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.”
For each plant loop connection that is used, there is input
required to specify the nature of the connection with respect
to loads. One of the following choices must be selected
depending on the purpose of the component model.
DemandsLoad. This type of loading is used for plant
connections that place a load on the loop. Connections that
use this loading scheme are not set up to meet loads and
interact with the operation schemes. For example, this
loading mode is appropriate for the condenser side of a
chiller.
MeetsLoadWithPassiveCapacity. This type of loading is
used for plant connections where the component has some
capacity to meet loads but it is not really of the type that
could be controlled. For example, a ground heat exchanger is
passive because while it can provide some level of heat
rejection or source, the amount will vary with current
conditions and cannot usually be explicitly
controlled.
MeetsLoadWithNominalCapacity. This type of loading is
used for plant connections where the component has
controllable capacity to meet loads and no outlet temperature
restrictions.
MeetsLoadWithNominalCapacityLowOutLimit. This type of
loading is used for plant connections where the component has
controllable capacity to meet loads but with a lower limit on
the fluid temperature at the outlet node. For example, this
can be used for a chiller evaporator connection when the
chiller is prevented from producing chilled water below a
certain temperature limit. When this type of loading is
selected, an actuator is created to allow setting the low
temperature limit for use by the load dispatch routines. The
actuator is called “Plant Connection N” with the
control type “Low Outlet Temperature Limit,” in [C], and needs
to be used.
MeetsLoadWithNominalCapacityHiOutLimit. This type of
loading is used for plant connections where the component has
controllable capacity to meet loads but with an upper limit on
the fluid temperature at the outlet node. For example, this
can be used for a boiler connection when the boiler is
prevented from producing hot water above a certain temperature
limit. When this type of loading is selected, an actuator is
created to allow setting the high temperature limit for use by
the load dispatch routines. The actuator is called “Plant
Connection N” with the control type “High Outlet
Temperature Limit,” in [C], and needs to be used.
For each plant loop connection, there is input required for
the nature of the flow requests made by the component with
respect to determining the overall flow for the loop. Mass
flow request are also important for resolving the flow rates
in parallel branches, but the mode here is related to the
problem of determining the overall flow rate for the loop, not
the flow down one particular branch. The overall loop flow
rate is a function of all the flow requests made by the
different devices on the loop and different types of devices
have different implications for the overall loop rate. One of
the following three choices must be made depending on the
nature of the plant component.
NeedsFlowIfLoopOn. Devices with this flow request mode
will contribute to the overall loop flow rate but will not
initiate flow themselves. Other devices on the plant loop (of
type NeedsFlowAndTurnsLoopOn ) need to make flow requests to
get the loop flowing at all, but once it is flowing, this
device can affect the overall loop flow rate. For example, a
chiller may have a lower limit on the allowable chilled water
flow rate through its evaporator and if that lower limit is
higher than the current request for chilled water by the
cooling coils, then the overall loop flow will be that needed
by the chiller rather than the coils.
NeedsFlowAndTurnsLoopOn. Devices with this flow
request mode will contribute to the overall loop flow rate and
initiate flow themselves. This mode is used for demand
component such as coils. Devices with this mode will initiate
loops to turn on and start moving fluid.
ReceivesWhateverFlowAvailable. Devices with this flow
request mode will not contribute to the overall loop flow rate
and do not initiate flow themselves. These are essentially
passive devices that take whatever flow is sent to them, such
as a ground heat exchanger.
Separate program calling managers are available for each
plant loop connection. The user defined plant component is
called to simulate by the central plant routines (whereas the
other user defined components are called by the central HVAC
routines). The calls to simulate are made for each connection
and you may want or need to perform different model
calculations depending on which plant loop connection is being
simulated at the time. There is an Erl program calling
manager for initialization, setup, and sizing that needs to be
used for each plant connection and is only called
during the early plant loop initialization phase. There is
also an Erl program calling manager for the model calculations
to perform for each plant connection.
Air Connection[LINK]
An air connection is available that includes both an inlet
and an outlet node. This can be used for air source or heat
rejections. The following EMS internal variables are made
available for the inlet node, if it is used, and should be
useful inputs to your own custom models:
An internal variable called “Inlet Temperature for Air
Connection,” provides the current value for the drybulb air
temperature at the component’s inlet node, in [C].
An internal variable called “Inlet Mass Flow Rate for
Air Connection,” provides the current value for the mass flow
rate of air at the component’s inlet node, in [kg/s].
An internal variable called “Inlet Humidity Ratio for
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 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
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 following EMS actuators are created for the outlet air
node, if it is used, and must be used to pass results from the
custom model to the rest of EnergyPlus:
An actuator called “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
component.
An actuator called “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 component.
An actuator called “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
component.
The user defined plant component 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 plant component 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 plant component can be connected to an
ambient zone and provide internal gains to that zone. This is
for “skin losses” that the component 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.
Plant Component[LINK]
The input object called PlantComponent:UserDefined provides a shell for creating custom models of a device that is part of the plant models used for hydronic-type systems. This object can be used for primary heating or cooling devices, such as boilers or chillers.
Although the other user-defined component models can also connect to plant, they are always simple “demand” components (from the point of view of plant modeling) and their calls to simulate are led by the air side portions of the program’s calling tree. The plant-centric component here however, is called to simulate along with other plant components (in flow order) by plant’s central routines.
The user defined plant component can use up to four different plant loop connections, one optional air connection, a water supply tank, a water collection tank, and an ambient zone for skin losses.
Plant Connections[LINK]
The user defined plant component can be connected to up to four different plant loops.
For plant loops, both the inlet and outlet nodes need to be used for each loop connection. The PlantComponent: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 that particular loop connection for model setup and sizing. The following six 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.
An actuator called “Plant Connection N” with the control type “Minimum Loading Capacity,” in [W], needs to be used if the device is to be used as a supply component with load-based operation schemes.
An actuator called “Plant connection N” with the control type “Maximum Loading Capacity,” in [W], needs to be used if the device is to be used as a supply component with load-based operation schemes.
An actuator called “Plant Connection N” with the control type “Optimal Loading Capacity,” in [W], needs to be used if the device is to be used as a supply component with load-based operation schemes.
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.
An internal variable called “Load Request for Plant Connection N” provides the current value for the desired operating capacity, in [W]. This is the input for how the model is being asked to meet the loads on the supply side. This is the result of the central routines for operation schemes and should be useful for controlling a plant model. (This internal variable is not made available when this plant connection’s loading mode is set to DemandsLoad.)
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.”
For each plant loop connection that is used, there is input required to specify the nature of the connection with respect to loads. One of the following choices must be selected depending on the purpose of the component model.
DemandsLoad. This type of loading is used for plant connections that place a load on the loop. Connections that use this loading scheme are not set up to meet loads and interact with the operation schemes. For example, this loading mode is appropriate for the condenser side of a chiller.
MeetsLoadWithPassiveCapacity. This type of loading is used for plant connections where the component has some capacity to meet loads but it is not really of the type that could be controlled. For example, a ground heat exchanger is passive because while it can provide some level of heat rejection or source, the amount will vary with current conditions and cannot usually be explicitly controlled.
MeetsLoadWithNominalCapacity. This type of loading is used for plant connections where the component has controllable capacity to meet loads and no outlet temperature restrictions.
MeetsLoadWithNominalCapacityLowOutLimit. This type of loading is used for plant connections where the component has controllable capacity to meet loads but with a lower limit on the fluid temperature at the outlet node. For example, this can be used for a chiller evaporator connection when the chiller is prevented from producing chilled water below a certain temperature limit. When this type of loading is selected, an actuator is created to allow setting the low temperature limit for use by the load dispatch routines. The actuator is called “Plant Connection N” with the control type “Low Outlet Temperature Limit,” in [C], and needs to be used.
MeetsLoadWithNominalCapacityHiOutLimit. This type of loading is used for plant connections where the component has controllable capacity to meet loads but with an upper limit on the fluid temperature at the outlet node. For example, this can be used for a boiler connection when the boiler is prevented from producing hot water above a certain temperature limit. When this type of loading is selected, an actuator is created to allow setting the high temperature limit for use by the load dispatch routines. The actuator is called “Plant Connection N” with the control type “High Outlet Temperature Limit,” in [C], and needs to be used.
For each plant loop connection, there is input required for the nature of the flow requests made by the component with respect to determining the overall flow for the loop. Mass flow request are also important for resolving the flow rates in parallel branches, but the mode here is related to the problem of determining the overall flow rate for the loop, not the flow down one particular branch. The overall loop flow rate is a function of all the flow requests made by the different devices on the loop and different types of devices have different implications for the overall loop rate. One of the following three choices must be made depending on the nature of the plant component.
NeedsFlowIfLoopOn. Devices with this flow request mode will contribute to the overall loop flow rate but will not initiate flow themselves. Other devices on the plant loop (of type NeedsFlowAndTurnsLoopOn ) need to make flow requests to get the loop flowing at all, but once it is flowing, this device can affect the overall loop flow rate. For example, a chiller may have a lower limit on the allowable chilled water flow rate through its evaporator and if that lower limit is higher than the current request for chilled water by the cooling coils, then the overall loop flow will be that needed by the chiller rather than the coils.
NeedsFlowAndTurnsLoopOn. Devices with this flow request mode will contribute to the overall loop flow rate and initiate flow themselves. This mode is used for demand component such as coils. Devices with this mode will initiate loops to turn on and start moving fluid.
ReceivesWhateverFlowAvailable. Devices with this flow request mode will not contribute to the overall loop flow rate and do not initiate flow themselves. These are essentially passive devices that take whatever flow is sent to them, such as a ground heat exchanger.
Separate program calling managers are available for each plant loop connection. The user defined plant component is called to simulate by the central plant routines (whereas the other user defined components are called by the central HVAC routines). The calls to simulate are made for each connection and you may want or need to perform different model calculations depending on which plant loop connection is being simulated at the time. There is an Erl program calling manager for initialization, setup, and sizing that needs to be used for each plant connection and is only called during the early plant loop initialization phase. There is also an Erl program calling manager for the model calculations to perform for each plant connection.
Air Connection[LINK]
An air connection is available that includes both an inlet and an outlet node. This can be used for air source or heat rejections. The following EMS internal variables are made available for the inlet node, if it is used, and should be useful inputs to your own custom models:
An internal variable called “Inlet Temperature for Air Connection,” provides the current value for the drybulb air temperature at the component’s inlet node, in [C].
An internal variable called “Inlet Mass Flow Rate for Air Connection,” provides the current value for the mass flow rate of air at the component’s inlet node, in [kg/s].
An internal variable called “Inlet Humidity Ratio for 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 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 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 following EMS actuators are created for the outlet air node, if it is used, and must be used to pass results from the custom model to the rest of EnergyPlus:
An actuator called “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 component.
An actuator called “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 component.
An actuator called “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 component.
Water Use[LINK]
The user defined plant component 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 plant component 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 plant component can be connected to an ambient zone and provide internal gains to that zone. This is for “skin losses” that the component 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.