The input object called Coil:UserDefined provides a shell for creating custom models for a coil that processes air as part of an air handler. This device is analogous to coils models such as Coil:Cooling:Water, Coil:Heating:Water, and Coil:Cooling:DX:SingleSpeed, but can also be used for heat-exchanger-like devices such as HeatExchanger:AirToAir:SensibleAndLatent or EvaporativeCooler:Indirect:WetCoil.
The user defined coil model can use one or two air connections, one optional plant connection, a water supply tank, a water collection tank, and a separate zone for skin losses.
Air Connections[LINK]
Each of the two air connections that are available include both an inlet and an outlet node that are required for each air connection that is used. The Coil:UserDefined object appears directly on a Branch object used to define the supply side of an air handler, or in the AirLoopHVAC:OutdoorAirSystem:EquipmentList object used to define outdoor air systems. The following EMS internal variables are made available for each inlet node and should be useful inputs to your own custom models:
An internal variable called “Inlet Temperature for Air Connection N,” 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 Air Connection N,” 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 N,” provides the current value for the density of moist air at the component’s main inlet node, in [kg/m3].
An internal variable called “Inlet Specific Heat for Air Connection N,” 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 each outlet node and must be used to pass results from the custom model to the rest of EnergyPlus:
An actuator called “Air Connection N,” with the control type “Outlet Temperature,” in [C], needs to be used. This will set the drybulb temperature of the air leaving the coil.
An actuator called “Air Connection N,” 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 coil.
An actuator called “Air Connection N,” with the control type “Mass Flow Rate,” in [kg/s], needs to be used. This will set the flow rate of air leaving the coil.
Plant Connections[LINK]
The user defined coil can also be connected to one plant loop to provide hydronic-based cooling, heating, or heat source or rejection.
Although the coil actively conditions the air stream passing through it, from the point of view of plant it is a demand component. This plant connection is always “demand” in the sense that the coil will place loads onto the plant loop serving it and is not configured to be able to meet plant loads in the way that supply equipment could (loading mode is always DemandsLoad). This plant connection is 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).
Both the inlet and outlet nodes need to be used is a loop is connected. The Coil: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 coil for model setup and sizing. The following three actuators are created for the plant loop and must be used to properly register the plant connection:
An actuator called “Plant Connection” 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” 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” with the control type “Design Volume Flow Rate,” in [m3/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.
When the plant loop connection is used, the following internal variables are available for inputs to the custom component model:
An internal variable called “Inlet Temperature for Plant Connection” 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” 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” provides the current value for the density of the fluid entering the component, in [kg/m3]. 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” 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.
When the plant loop connection 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” with the control type “Outlet Temperature,” in [C], needs to be used. This is the temperature of the fluid leaving the coil.
An actuator called “Plant Connection” 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.”
The user defined coil 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 m3/s, needs to be used. This sets up the coil 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 m3/s, needs to be used.
The user defined coil can be connected to an ambient zone and provide internal gains to that zone. This is for “skin losses” that the coil 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 [m3/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 [m3/s], is available. This can be used for generic gaseous air pollutant gains (or losses) to a zone.
Air Coil[LINK]
The input object called Coil:UserDefined provides a shell for creating custom models for a coil that processes air as part of an air handler. This device is analogous to coils models such as Coil:Cooling:Water, Coil:Heating:Water, and Coil:Cooling:DX:SingleSpeed, but can also be used for heat-exchanger-like devices such as HeatExchanger:AirToAir:SensibleAndLatent or EvaporativeCooler:Indirect:WetCoil.
The user defined coil model can use one or two air connections, one optional plant connection, a water supply tank, a water collection tank, and a separate zone for skin losses.
Air Connections[LINK]
Each of the two air connections that are available include both an inlet and an outlet node that are required for each air connection that is used. The Coil:UserDefined object appears directly on a Branch object used to define the supply side of an air handler, or in the AirLoopHVAC:OutdoorAirSystem:EquipmentList object used to define outdoor air systems. The following EMS internal variables are made available for each inlet node and should be useful inputs to your own custom models:
An internal variable called “Inlet Temperature for Air Connection N,” 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 Air Connection N,” 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 N,” provides the current value for the density of moist air at the component’s main inlet node, in [kg/m3].
An internal variable called “Inlet Specific Heat for Air Connection N,” 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 each outlet node and must be used to pass results from the custom model to the rest of EnergyPlus:
An actuator called “Air Connection N,” with the control type “Outlet Temperature,” in [C], needs to be used. This will set the drybulb temperature of the air leaving the coil.
An actuator called “Air Connection N,” 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 coil.
An actuator called “Air Connection N,” with the control type “Mass Flow Rate,” in [kg/s], needs to be used. This will set the flow rate of air leaving the coil.
Plant Connections[LINK]
The user defined coil can also be connected to one plant loop to provide hydronic-based cooling, heating, or heat source or rejection.
Although the coil actively conditions the air stream passing through it, from the point of view of plant it is a demand component. This plant connection is always “demand” in the sense that the coil will place loads onto the plant loop serving it and is not configured to be able to meet plant loads in the way that supply equipment could (loading mode is always DemandsLoad). This plant connection is 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).
Both the inlet and outlet nodes need to be used is a loop is connected. The Coil: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 coil for model setup and sizing. The following three actuators are created for the plant loop and must be used to properly register the plant connection:
An actuator called “Plant Connection” 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” 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” with the control type “Design Volume Flow Rate,” in [m3/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.
When the plant loop connection is used, the following internal variables are available for inputs to the custom component model:
An internal variable called “Inlet Temperature for Plant Connection” 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” 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” provides the current value for the density of the fluid entering the component, in [kg/m3]. 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” 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.
When the plant loop connection 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” with the control type “Outlet Temperature,” in [C], needs to be used. This is the temperature of the fluid leaving the coil.
An actuator called “Plant Connection” 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.”
Water Use[LINK]
The user defined coil 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 m3/s, needs to be used. This sets up the coil 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 m3/s, needs to be used.
Ambient Zone[LINK]
The user defined coil can be connected to an ambient zone and provide internal gains to that zone. This is for “skin losses” that the coil 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 [m3/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 [m3/s], is available. This can be used for generic gaseous air pollutant gains (or losses) to a zone.
Documentation content copyright © 1996-2022 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.