Update Fan:xxx Outputs in IO reference docs by joseph-robertson · Pull Request #11552 · NatLabRockies/EnergyPlus

joseph-robertson · 2026-04-28T20:35:56Z

Pull request overview

Fixes Fan:SystemModel outputs not documented in I/O Ref #11542
Additionally, update IO reference Outputs sections for all fan types (according to SetupOutputVariable calls in Fans.cc).

Description of the purpose of this PR

Pull Request Author

Reviewer

joseph-robertson · 2026-04-28T20:38:05Z

 \item
-HVAC,Average,Fan Electricity Rate {[}W{]}
+  HVAC,Average,Fan Electricity Rate {[}W{]}
+\item
+  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,Sum,Fan Electricity Energy {[}J{]}
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}
 \item
-HVAC,Average,Fan Rise in Air Temperature{[}deltaC{]}
+  HVAC,Average,Fan Runtime Fraction Speed {[]}
 \item
-HVAC,Average,Fan Air Mass Flow Rate{[}kg/s{]}
+  HVAC,Average,Fan Runtime Fraction Speed <\#> {[]}


Fan:SystemModel

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:

Did you want to update this @joseph-robertson, or leave it as-is?

joseph-robertson · 2026-04-28T20:39:11Z

+\item
+  HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
+\item
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}


Fan:ConstantVolume

joseph-robertson · 2026-04-28T20:39:37Z

+\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 {[]}


joseph-robertson · 2026-04-28T20:40:07Z

+\item
+  HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
+\item
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}


Fan:VariableVolume

joseph-robertson · 2026-04-28T20:40:40Z

 \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{]}


Fan:ZoneExhaust

joseph-robertson · 2026-04-28T20:40:59Z

+\item
+  HVAC,Average,Fan Air Mass Flow Rate {[}kg/s{]}
+\item
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}


Fan:ComponentModel

…Runtime Fraction.

joseph-robertson · 2026-04-28T22:33:00Z

+\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.


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.

joseph-robertson · 2026-04-28T22:35:13Z

+\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. Applies 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. Applies only for two-speed and multi-speed fans.


These "Fan Runtime Fraction (Speed <#>)" output descriptions are also new and should be double-checked.

rraustad · 2026-04-28T23:16:08Z

 \item
-HVAC,Average,Fan Electricity Rate {[}W{]}
+  HVAC,Average,Fan Electricity Rate {[}W{]}
+\item
+  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,Sum,Fan Electricity Energy {[}J{]}
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}
 \item
-HVAC,Average,Fan Rise in Air Temperature{[}deltaC{]}
+  HVAC,Average,Fan Runtime Fraction Speed {[]}
 \item
-HVAC,Average,Fan Air Mass Flow Rate{[}kg/s{]}
+  HVAC,Average,Fan Runtime Fraction Speed <\#> {[]}


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:

rraustad · 2026-04-28T23:19:18Z

+\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. Applies only for two-speed and multi-speed fans.
+


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.

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

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

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.

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.

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

(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.)

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, _);

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.

I created #11577 to capture this request.

github-actions · 2026-04-29T23:31:02Z

⚠️ Regressions detected on ubuntu-24.04 for commit `582355f`

Regression Summary

ESO Small Diffs: 706
Table Small Diffs: 392
MTR Small Diffs: 524
Table String Diffs: 177
EIO: 397
JSON Small Diffs: 2
ZSZ Small Diffs: 72
Table Big Diffs: 36
ERR: 14
MTR Big Diffs: 2
ESO Big Diffs: 10
SSZ Small Diffs: 13
EDD: 4
JSON Big Diffs: 2

mitchute

A couple minor questions.

mitchute · 2026-05-05T20:08:51Z

 \item
-HVAC,Average,Fan Electricity Rate {[}W{]}
+  HVAC,Average,Fan Electricity Rate {[}W{]}
+\item
+  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,Sum,Fan Electricity Energy {[}J{]}
+  HVAC,Average,Fan Heat Gain to Air {[}W{]}
 \item
-HVAC,Average,Fan Rise in Air Temperature{[}deltaC{]}
+  HVAC,Average,Fan Runtime Fraction Speed {[]}
 \item
-HVAC,Average,Fan Air Mass Flow Rate{[}kg/s{]}
+  HVAC,Average,Fan Runtime Fraction Speed <\#> {[]}


Did you want to update this @joseph-robertson, or leave it as-is?

mitchute · 2026-05-05T20:16:22Z

+
+\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.


Are there any caveats to this for the continuous speed control option?

github-actions · 2026-05-05T20:40:00Z

⚠️ Regressions detected on ubuntu-24.04 for commit `46fd8df`

Regression Summary

ESO Small Diffs: 707
Table Small Diffs: 392
MTR Small Diffs: 524
Table String Diffs: 177
EIO: 397
JSON Small Diffs: 2
ZSZ Small Diffs: 72
Table Big Diffs: 36
ERR: 14
MTR Big Diffs: 2
EDD: 4
ESO Big Diffs: 10
SSZ Small Diffs: 13
JSON Big Diffs: 2

Update Outputs sections in docs for all fans.

2b21f57

joseph-robertson self-assigned this Apr 28, 2026

joseph-robertson added Documentation Related primarily on the LaTeX-based EnergyPlus documentation Defect Includes code to repair a defect in EnergyPlus labels Apr 28, 2026

joseph-robertson commented Apr 28, 2026

View reviewed changes

Borrow language and attempt to populate Fan Heat Gain to Air and Fan …

6fa6546

…Runtime Fraction.

joseph-robertson commented Apr 28, 2026

View reviewed changes

Typo.

c67f8bc

rraustad reviewed Apr 28, 2026

View reviewed changes

Highlight RTF variable differences in item lists.

627e0cc

joseph-robertson mentioned this pull request May 5, 2026

Set up Fan:SystemModel overall system RTF output variable #11577

Open

Merge branch 'develop' into fan-sys-model-docs

f141d19

joseph-robertson marked this pull request as ready for review May 5, 2026 16:56

joseph-robertson requested review from mitchute May 5, 2026 17:52

NatLabRockies deleted a comment from github-actions Bot May 5, 2026

mitchute reviewed May 5, 2026

View reviewed changes

		\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.

		\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. Applies only for two-speed and multi-speed fans.

Conversation

joseph-robertson commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request overview

Description of the purpose of this PR

Pull Request Author

Reviewer

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rraustad Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rraustad Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rraustad Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joseph-robertson Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shorowit Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shorowit Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 29, 2026

⚠️ Regressions detected on ubuntu-24.04 for commit 582355f

Uh oh!

mitchute left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 5, 2026

⚠️ Regressions detected on ubuntu-24.04 for commit 46fd8df

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joseph-robertson commented Apr 28, 2026 •

edited

Loading

rraustad Apr 28, 2026 •

edited

Loading

rraustad Apr 28, 2026 •

edited

Loading

rraustad Apr 28, 2026 •

edited

Loading

joseph-robertson Apr 28, 2026 •

edited

Loading

shorowit Apr 28, 2026 •

edited

Loading

shorowit Apr 29, 2026 •

edited

Loading

⚠️ Regressions detected on ubuntu-24.04 for commit `582355f`

⚠️ Regressions detected on ubuntu-24.04 for commit `46fd8df`