Skip to content

Update Fan:xxx Outputs in IO reference docs #11552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joseph-robertson wants to merge 4 commits into
base: develop
Choose a base branch
from
+105 −13
Draft

Update Fan:xxx Outputs in IO reference docs #11552

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b21f57
Update Outputs sections in docs for all fans.
joseph-robertson Apr 28, 2026
6fa6546
Borrow language and attempt to populate Fan Heat Gain to Air and Fan…
joseph-robertson Apr 28, 2026
c67f8bc
Typo.
joseph-robertson Apr 28, 2026
627e0cc
Highlight RTF variable differences in item lists.
joseph-robertson Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 105 additions & 13 deletions doc/input-output-reference/src/overview/group-fans.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ \subsubsection{Inputs}\label{inputs-fansysmodel}
A field set is pair of values for the flow fraction and electric power fraction at each speed. The sets should be arranged in increasing order so that the flow fractions become larger in subsequent field sets. Typically the highest speed level will match the design maximum and have fractions of 1.0. This object is extensible, so additional sets of the following two fields can be added to the end of this object.

\paragraph{Field: Speed <\#> Flow Fraction}\label{field-speed-flow-fraction-fansysmodel}

This is the flow fraction for the fan speed. This value is multiplied by the Design Maximum Air Flow Rate to obtain the flow rate when operating at this speed.

\paragraph{Field: Speed <\#> Electric Power Fraction}\label{field-speed-power-fraction-fansysmodel}
Expand Down Expand Up @@ -225,13 +226,29 @@ \subsubsection{Outputs}\label{outputs-fansysmodel}

\begin{itemize}
\item
HVAC,Average,Fan Electricity Rate {[}W{]}
HVAC,Average,Fan Electricity Rate {[}W{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
\end{itemize}

Additional variable for single-speed fans:

\begin{itemize}
\item
HVAC,Average,Fan Rise in Air Temperature{[}deltaC{]}
HVAC,Average,Fan Runtime Fraction {[]}
\end{itemize}

Additional variable for two-speed and multi-speed fans:

\begin{itemize}
\item
HVAC,Average,Fan Air Mass Flow Rate{[}kg/s{]}
HVAC,Average,Fan Runtime Fraction Speed <\#> {[]}
Comment on lines 228 to +251
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:SystemModel

Copy link
Copy Markdown
Collaborator

@rraustad rraustad Apr 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually this is for a fan with speeds > 1, which is only for the system fan. Otherwise only Fan Runtime Fraction is reported. Reports that are only for a specific coil type, or for components with speeds, etc., would be highlighted as such. But I could live with this if there are no other changes. You could actually put a ", or" at the end of the previous Fan Runtime Fraction {[]}, or to avoid having to delineate this subtlety further. For example in the coil model these reports are delineated as:

Image

\end{itemize}

\paragraph{Fan Electricity Rate {[}W{]}}\label{fan-electric-power-fansysmodel}
Expand All @@ -246,10 +263,22 @@ \subsubsection{Outputs}\label{outputs-fansysmodel}

This output contains the average rise in air temperature across the fan (outlet air temperature minus inlet air temperature) in degrees Celsius for the time interval being reported.

\paragraph{Fan Air Mass Flow Rate{[}kg/s{]}}\label{fan-air-mass-flow-fansysmodel}
\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-fansysmodel}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-fansysmodel}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.
Comment on lines +270 to +272
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Output "Fan Heat Gain to Air" is new here (Fan:SystemModel), as well as for all other fan types. This description should be double-checked.


\paragraph{Fan Runtime Fraction {[]}}\label{fan-runtime-fraction-fansysmodel}

This output contains the fraction of time that this fan operated for the timestep being reported. Applicable only for single-speed fans.

\paragraph{Fan Runtime Fraction Speed <\#> {[]}}\label{fan-runtime-fraction-speed-fansysmodel}

This output contains the fraction of time that this fan operated at each speed for the timestep being reported. The overall runtime fraction is the sum of the runtime fractions for each speed. Applicable only for two-speed and multi-speed fans.

Copy link
Copy Markdown
Collaborator

@rraustad rraustad Apr 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The overall runtime fraction is the sum of the runtime fractions for each speed.

That doesn't sound right. A fan operating at speed 2 would have RTF between 0 and 1 (e.g., 0.5) where speed 1 RTF should be 1 (I didn't verify that). The overall runtime fraction would not be 1.5. RTF would be 1 for speed 1 and 0.5 for speed 2 but I don't think it's right to say the overall RTF is 1.5.

Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the "Fan Runtime Fraction Speed" comment above, that's a good idea. I had put the subtlety delineation below the item list -- in the descriptions themselves. But yes, we could also highlight the difference directly in the item list.

On the overall system RTF issue, I don't believe that's the behavior currently happening. Here is some sample hourly output for:

Fan:SystemModel,
  air source heat pump supply fan,        !- Name
[...]
  4,                                      !- Number of Speeds
  0.712,                                  !- Speed Flow Fraction 1
  0.39293,                                !- Speed Electric Power Fraction 1
  0.728,                                  !- Speed Flow Fraction 2
  0.4177,                                 !- Speed Electric Power Fraction 2
  1,                                      !- Speed Flow Fraction 3
  1,                                      !- Speed Electric Power Fraction 3
  1,                                      !- Speed Flow Fraction 4
  1;                                      !- Speed Electric Power Fraction 4
image

I don't ever see greater than 1 for a timestep.

Copy link
Copy Markdown
Contributor

@shorowit shorowit Apr 28, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @joseph-robertson. Unless it's somehow specific to how we set up our residential models, we always see the sum of individual speed RTFs <= 1.

Also, it'd be awfully nice if there was an overall system RTF output variable. I know that's scope creep, but it would simplify things for us.

Copy link
Copy Markdown
Collaborator

@rraustad rraustad Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right. It's not the sum of the RTF's, it's the max. Basically means the fan operates the entire time step but the upper speed is cycling.

Copy link
Copy Markdown
Contributor

@shorowit shorowit Apr 29, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the sum is always less than or equal to 1. Look at the right-most column here:

image

Copy link
Copy Markdown
Contributor

@shorowit shorowit Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(In case it's confusing.... speeds 2/4/6 are heating and speeds 1/3/5 are cooling, so you're only seeing the heating speeds operating above.)

Copy link
Copy Markdown
Collaborator

@rraustad rraustad Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, it's reporting the fraction of the time step that each speed is active.

As a FYI, this is technically a part load ratio, where RTF = PLR / PLF.

    thisDXCoil.CoolingCoilRuntimeFraction = PartLoadRatio / PLF;

In UnitarySystem the PartLoadRatio, and 1 - PartLoadRatio, are passed to the fan.

Real64 FanPartLoadRatio = PartLoadRatio;

if (SpeedNum > 1) {
    if ((state.dataUnitarySystems->CoolingLoad && this->m_MultiOrVarSpeedCoolCoil) ||
        (state.dataUnitarySystems->HeatingLoad && this->m_MultiOrVarSpeedHeatCoil)) {
        state.dataUnitarySystems->m_runTimeFraction1 = FanPartLoadRatio;
        state.dataUnitarySystems->m_runTimeFraction2 = 1.0 - FanPartLoadRatio;
    } else {
        state.dataUnitarySystems->m_runTimeFraction1 = FanPartLoadRatio;
        state.dataUnitarySystems->m_runTimeFraction2 = 0.0;
    }

 state.dataFans->fans(this->m_FanIndex)
    ->simulate(state,
               FirstHVACIteration,
               state.dataUnitarySystems->FanSpeedRatio,
               _, // Pressure rise
               _, // Flow fraction
               state.dataUnitarySystems->m_massFlow1,
               state.dataUnitarySystems->m_runTimeFraction1,
               state.dataUnitarySystems->m_massFlow2,
               state.dataUnitarySystems->m_runTimeFraction2,
               _);

\subsection{Fan:ConstantVolume}\label{fanconstantvolume}

This object models a constant air volume fan that is intended to operate continuously based on a time schedule. This fan will not cycle on and off based on cooling/heating load or other control signals (Ref: \hyperref[fanonoff]{Fan:OnOff}).
Expand Down Expand Up @@ -309,6 +338,10 @@ \subsubsection{Outputs}\label{outputs-013}
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
Comment on lines +341 to +344
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:ConstantVolume

\end{itemize}

\paragraph{Fan Electricity Rate {[}W{]}}\label{fan-electric-power-w}
Expand All @@ -323,6 +356,14 @@ \subsubsection{Outputs}\label{outputs-013}

This output field contains the electricity consumption of the fan in Joules for the timestep being reported. This output is also added to a meter with Resource Type = Electricity, End Use Key = Fans, Group Key = System (ref. Output:Meter objects).

\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-kgs}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-w}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.

\subsection{Fan:OnOff}\label{fanonoff}

This object models a constant air volume fan that is intended to cycle on and off in tandem with a cooling or heating system (i.e., AUTO fan control mode). The fan can also operate continuously like \hyperref[fanconstantvolume]{Fan:ConstantVolume}. If modeling continuous operation and this object is used as part of a system that utilizes \hyperref[coilheatinggas-000]{Coil:Heating:Fuel}, \hyperref[coilcoolingdxsinglespeed]{Coil:Cooling:DX:SingleSpeed} or \hyperref[coilheatingdxsinglespeed]{Coil:Heating:DX:SingleSpeed}, the user should confirm proper air flow rates (coil and fan max flows are equal) and that the coil part-load fraction correlation(s) are appropriate (e.g., part-load fraction is less than or equal to 1 for all values of coil part-load ratio). If modeling multi-speed fan operation, this object must be used as part of a compound object that allows multiple fan speeds (e.g., \hyperref[airloophvacunitaryfurnaceheatcool]{AirLoopHVAC:Unitary:Furnace:HeatCool}, \hyperref[zonehvacpackagedterminalairconditioner]{ZoneHVAC:PackagedTerminalAirConditioner}, etc.). In this case, the ratio of the compound object air flow rate to the fan's maximum air flow rate is used to determine the power at alternate fan speeds. The optional input for Fan Power Ratio Function of Speed Ratio Curve Name must be entered to model multi-speed fan operation. An optional fan total efficiency ratio curve is also available to model efficiency differences at alternate fan speeds.
Expand Down Expand Up @@ -397,13 +438,20 @@ \subsubsection{Inputs}\label{inputs-1-017}

\subsubsection{Outputs}\label{outputs-1-011}

HVAC,Average,Fan Electricity Rate {[}W{]}

HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}

HVAC,Sum,Fan Electricity Energy {[}J{]}

HVAC,Average,Fan Runtime Fraction {[]}
\begin{itemize}
\item
HVAC,Average,Fan Electricity Rate {[}W{]}
\item
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
\item
HVAC,Average,Fan Runtime Fraction {[]}
Comment on lines +442 to +453
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:OnOff

\end{itemize}

\paragraph{Fan Electricity Rate {[}W{]}}\label{fan-electric-power-w-1}

Expand All @@ -417,6 +465,14 @@ \subsubsection{Outputs}\label{outputs-1-011}

This output field contains the electricity consumption of the fan in Joules for the timestep being reported. This output is also added to a meter with Resource Type = Electricity, End Use Key = Fans, Group Key = System (ref. Output:Meter objects).

\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-kgs-1}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-w-1}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.

\paragraph{Fan Runtime Fraction {[]}}\label{fan-runtime-fraction}

This output field contains the fraction of time that this fan operated for the timestep being reported.
Expand Down Expand Up @@ -542,6 +598,10 @@ \subsubsection{Outputs}\label{outputs-2-009}
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
Comment on lines +601 to +604
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:VariableVolume

\end{itemize}

\paragraph{Fan Electricity Rate {[}W{]}}\label{fan-electric-power-w-2}
Expand All @@ -556,6 +616,14 @@ \subsubsection{Outputs}\label{outputs-2-009}

This output field contains the electricity consumption of the fan in Joules for the timestep being reported. This output is also added to a meter with Resource Type = Electricity, End Use Key = Fans, Group Key = System (ref. Output:Meter objects).

\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-kgs-2}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-w-2}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.

\subsection{Fan:ZoneExhaust}\label{fanzoneexhaust}

This fan object differs from the other fans in that it stands on its own in a zone rather than serving as one part of an HVAC air system. This object appears directly in a \hyperref[zonehvacequipmentlist]{ZoneHVAC:EquipmentList} object and all the controls are contained within the fan object. The zone exhaust fan model provides a way to include the electrical power used by the fan. It can also impact air flows in central air handlers by decreasing the flow of return air and sometimes increasing the outdoor air flow rate.
Expand Down Expand Up @@ -624,9 +692,13 @@ \subsubsection{Outputs}\label{outputs-3-007}
\item
HVAC,Average,Fan Electricity Rate {[}W{]}
\item
HVAC,Average,Fan Rise in Air Temperature{[}deltaC{]}
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
\item
HVAC,Average,Fan Unbalanced Air Mass Flow Rate {[}kg/s{]}
Comment on lines 692 to 703
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:ZoneExhaust

\item
Expand All @@ -645,6 +717,14 @@ \subsubsection{Outputs}\label{outputs-3-007}

This output field contains the electricity consumption of the fan in Joules for the timestep being reported. This output is also added to an output meter with Resource Type = Electricity, End Use Key = Fans, Group Key = System (ref. Output:Meter objects).

\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-kgs-3}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-w-3}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.

\paragraph{Fan Unbalanced Air Mass Flow Rate {[}kg/s{]}}\label{fan-unbalanced-air-mass-flow-rate-kgs}

\paragraph{Fan Balanced Air Mass Flow Rate {[}kg/s{]}}\label{fan-balanced-air-mass-flow-rate-kgs}
Expand Down Expand Up @@ -1099,6 +1179,10 @@ \subsubsection{Outputs}\label{outputs-4-005}
HVAC,Average,Fan Rise in Air Temperature {[}deltaC{]}
\item
HVAC,Sum,Fan Electricity Energy {[}J{]}
\item
HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
\item
HVAC,Average,Fan Heat Gain to Air {[}W{]}
Comment on lines +1182 to +1185
Copy link
Copy Markdown
Collaborator Author

@joseph-robertson joseph-robertson Apr 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fan:ComponentModel

\end{itemize}

\paragraph{Fan Electricity Rate {[}W{]}}\label{fan-electric-power-w-4}
Expand All @@ -1113,6 +1197,14 @@ \subsubsection{Outputs}\label{outputs-4-005}

This output field contains the electricity consumption of the fan in Joules for the timestep being reported. This output is also added to a meter with Resource Type = Electricity, End Use Key = Fans, Group Key = System (ref. Output:Meter objects).

\paragraph{Fan Air Mass Flow Rate {[}kg/s{]}}\label{fan-air-mass-flow-kgs-4}

This output contains the average air mass flow rate in kg/s for the time interval being reported.

\paragraph{Fan Heat Gain to Air {[}W{]}}\label{fan-heat-gain-to-air-w-4}

This output contains the average power in Watts lost to the process air stream for the time interval being reported.

\paragraph{Other Outputs}\label{other-outputs}

Several parameters input by the user or calculated during component sizing for the design condition (maximum system airflow) are reported separately in the \textless{}filename\textgreater{}.eio file. These parameters include fan airflow and pressure rise; fan shaft input, motor output, VFD output, and VFD input (rated) power; pulley drive ratio; belt output torque; and fan, belt, motor, VFD, and combined system efficiencies. They can be identified by lines in the .eio file beginning with Component Sizing Information, Fan:ComponentModel . The same values are also reported under the ComponentSizingSummary heading in the \textless{}filename\textgreater{}Table.html file.
Loading