Fix heating and cooling runtime fraction for `AirLoopHVAC:UnitarySystem` for airflow network simulations by lymereJ · Pull Request #11491 · NatLabRockies/EnergyPlus

lymereJ · 2026-03-31T22:23:37Z

Pull request overview

Fixes Incorrect heating energy use for AirLoopHVAC:UnitarySystem in AFN simulation with distribution losses #11490

Pull Request Author

Title of PR should be user-synopsis style (clearly understandable in a standalone changelog context)
Label the PR with at least one of: Defect, Refactoring, NewFeature, Performance, and/or DoNoPublish
Pull requests that impact EnergyPlus code must also include unit tests to cover enhancement or defect repair
Author should provide a "walkthrough" of relevant code changes using a GitHub code review comment process
If any diffs are expected, author must demonstrate they are justified using plots and descriptions
If changes fix a defect, the fix should be demonstrated in plots and descriptions

Reviewer

lymereJ · 2026-03-31T22:28:22Z

Here's a comparison of the duct conduction heat gains for the defect file with the "reference" file with this branch:

Also, as expected their energy use is virtually the same:

OPT4 (AirLoopHVAC:UnitarySystem):

OPT3 (AirLoopHVAC:UnitaryHeatCool):

lymereJ

Code walk-through:

lymereJ · 2026-03-31T22:29:58Z

        // Report the current output
        this->reportUnitarySystem(state, AirLoopNum);

+        // Get the actual maximum RTF for AFN simulations


Similar changes as for #11367. We save the RTFs at the system level instead of at the coil level and make the determination here, that way we can also include the supplemental heating coil.

lymereJ · 2026-03-31T22:30:52Z

        int CompIndex = this->m_HeatingCoilIndex;
        HVAC::FanOp fanOp = this->m_FanOpMode;
        Real64 DesOutTemp = this->m_DesiredOutletTemp;
-


These were only applied when the system is controller to a setpoint. The propose changes apply to both load-based and setpoint control.

lymereJ · 2026-03-31T22:31:23Z

+                     latOut);
+
+    // Check that the runtime fraction is less than one so the impact of cycling fan is correctly accounted for in the AFN
+    EXPECT_TRUE(state->dataAirLoop->AirLoopAFNInfo(1).AFNLoopHeatingCoilMaxRTF < 1);


New unit test to make sure that the correct RTF is retrieved. This verification fails on develop.

github-actions · 2026-03-31T22:38:07Z

⚠️ Regressions detected on ubuntu-24.04 for commit `7c78951`

Regression Summary

ESO Small Diffs: 703
Table Small Diffs: 391
MTR Small Diffs: 523
Table String Diffs: 186
EIO: 396
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

rraustad · 2026-04-01T15:15:26Z

+        if (state.afn->distribution_simulated && this->m_sysType != SysType::PackagedAC && this->m_sysType != SysType::PackagedHP &&
+            this->m_sysType != SysType::PackagedWSHP && AirLoopNum > 0) {
+            refAFNLoopHeatingCoilMaxRTF = state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopHeatingCoilMaxRTF;
+            refAFNLoopCoolingCoilMaxRTF = state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopDXCoilRTF;


Can't you just move these last 2 lines down inside of the block below?

I don't think so because I think this needs to happen before controlUnitarySystemtoSP or controlUnitarySystemtoLoad are called.

I see. Because these same AFN variables are set in the child. In this parent there can be 2 heating coils so the larger RTF should be used and calling the control functions will set AFNLoopHeatingCoilMaxRTF to the RTF of the last coil called.

mitchute

A couple more questions for consideration.

mitchute · 2026-04-30T20:43:38Z

+            case HVAC::CoilType::HeatingSteam:
+            case HVAC::CoilType::HeatingWater:
+            case HVAC::CoilType::UserDefined: {
+                suppHeatingCoilRTF = 1.0;


Why are these types hard coded to RTF = 1 here?

Why not

suppHeatingCoilRTF = this->m_SuppHeatPartLoadFrac

Yup, good catch, I did not propagate the changes from the heating coil to the supplemental coil.

That might work. Here's how those coil types use PLR to modulate fluid flow. So it really depends on how AFN uses these global RTF variables to solve the network. The fan would provide an RTF for airflow and these coils would provide an RTF for temp? pressure drop? not sure. I suspect it's a guess either way unless someone dissects AFN to see how these RTF variables are used.

this->m_SuppHeatPartLoadFrac = PartLoadFrac; this->m_SuppHeatingCycRatio = CycRatio; this->m_SuppHeatingSpeedRatio = SpeedRatio; if (this->m_suppHeatCoilType == HVAC::CoilType::HeatingWater || this->m_suppHeatCoilType == HVAC::CoilType::HeatingSteam) { mdot = PartLoadFrac * this->m_MaxSuppCoilFluidFlow; PlantUtilities::SetComponentFlowRate( state, mdot, this->m_SuppCoilFluidInletNode, this->m_SuppCoilFluidOutletNodeNum, this->m_SuppCoilPlantLoc); }

It looks to me as if this is an indicator of air flow so I am not at all sure why AFN is looking at a coil RTF. What difference would it make on infiltration if a compressor cycled on and off? A fan yes, but a coil? I'm still not sure how/why these coil RTF variables are used.

LoopOnOffFanRunTimeFraction(AirLoopNum) = max(m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopHeatingCoilMaxRTF, m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopOnOffFanRTF, m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopDXCoilRTF); if (AirflowNetworkNodeData(i).AirLoopNum == AirLoopNum) { RepOnOffFanRunTimeFraction = LoopOnOffFanRunTimeFraction(AirLoopNum); } AirflowNetworkReportData(i).MultiZoneInfiSenGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiSenGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiSenLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiSenLossJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiLatGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiLatGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiLatLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneInfiLatLossJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentSenGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentSenGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentSenLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentSenLossJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentLatGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentLatGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentLatLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneVentLatLossJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixSenGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixSenGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixSenLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixSenLossJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixLatGainW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixLatGainJ *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixLatLossW *= RepOnOffFanRunTimeFraction; AirflowNetworkReportData(i).MultiZoneMixLatLossJ *= RepOnOffFanRunTimeFraction;

I think that it is used to determine the impact of cycling fan operation on the AFN (infiltration, duct leakage, conduction, etc.). For this particular issue, the fact that the runtime fraction was not picked up correctly resulted in these adjustment to not be applicable:

https://github.com/NatLabRockies/EnergyPlus/blob/develop/src/EnergyPlus/AirflowNetwork/src/Solver.cpp#L10063-L10150

It looks to me as if this is an indicator of air flow so I am not at all sure why AFN is looking at a coil RTF. What difference would it make on infiltration if a compressor cycled on and off? A fan yes, but a coil?

I agree, fan RTF sounds like a better indicator but it looks like we take the max of coils and fan RTF:

EnergyPlus/src/EnergyPlus/AirflowNetwork/src/Solver.cpp

Lines 9797 to 9799 in 10d33a8

OnOffFanRunTimeFraction = max(m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopHeatingCoilMaxRTF,

m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopOnOffFanRTF,

m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopDXCoilRTF);

mitchute · 2026-04-30T20:48:35Z

+            case HVAC::CoilType::CoolingWater:
+            case HVAC::CoilType::CoolingWaterDetailed:
+            case HVAC::CoilType::UserDefined:
+            case HVAC::CoilType::CoolingDXHXAssisted:


Does this need to pick the RTF off of the child coil data structs? Something like this?

case HVAC::CoilType::CoolingDXHXAssisted: { if (this->m_CoolingCoilIndex > 0) { auto const &hxCoil = state.dataHVACAssistedCC->HXAssistedCoil(this->m_CoolingCoilIndex); if (hxCoil.CoolingCoilIndex > 0) { switch (hxCoil.coolCoilType) { case HVAC::CoilType::CoolingDX: { coolingCoilRTF = state.dataCoilCoolingDX->coilCoolingDXs[hxCoil.CoolingCoilIndex].coolingCoilRuntimeFraction; } break; case HVAC::CoilType::CoolingDXSingleSpeed: { coolingCoilRTF = state.dataDXCoils->DXCoil(hxCoil.CoolingCoilIndex).CoolingCoilRuntimeFraction; } break; case HVAC::CoilType::CoolingDXVariableSpeed: { coolingCoilRTF = state.dataVariableSpeedCoils->VarSpeedCoil(hxCoil.CoolingCoilIndex).RunFrac; } break; default: { coolingCoilRTF = this->m_CoolingPartLoadFrac; } break; } } }

The snippet above isn't tight enough - I'm specifically referring to the CoolingDXHXAssisted branch.

Yes, that seems like a better approach. I'll push changes.

@jasondegraw can you give us a lesson in fan RTF vs coil RTF in how AFN uses these vars in the solver? Why does AFN need to know a coil RTF?

lymereJ added 3 commits March 31, 2026 12:53

Set the AFN coil runtime fraction in simulate().

40a94b9

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

92174e5

Add unit test

991df4f

lymereJ added the Defect Includes code to repair a defect in EnergyPlus label Mar 31, 2026

lymereJ commented Mar 31, 2026

View reviewed changes

lymereJ added the AirflowNetwork Related primarily on airflow-network portions of the codebase label Apr 1, 2026

lymereJ modified the milestone: EnergyPlus 26.2 Bug Fix Freeze Apr 1, 2026

rraustad reviewed Apr 1, 2026

View reviewed changes

Comment thread src/EnergyPlus/UnitarySystem.cc Outdated

rraustad reviewed Apr 1, 2026

View reviewed changes

lymereJ and others added 3 commits April 1, 2026 08:44

Address review comments.

c5c2f0a

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

bb910e4

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

5889dcf

mitchute reviewed Apr 23, 2026

View reviewed changes

Comment thread src/EnergyPlus/UnitarySystem.cc Outdated

mitchute reviewed Apr 23, 2026

View reviewed changes

Comment thread src/EnergyPlus/UnitarySystem.cc

lymereJ added 2 commits April 24, 2026 15:53

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

aa02324

Remove RTF placeholder with system PLR.

763d3c1

NatLabRockies deleted a comment from github-actions Bot Apr 25, 2026

mitchute reviewed Apr 30, 2026

View reviewed changes

lymereJ added 3 commits May 1, 2026 10:26

Remove RTF placeholder with system PLR for supplemental heating coil.

1d2e22f

Get child cooling coil runtime.

9787fc2

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

488bb5f

lymereJ mentioned this pull request May 1, 2026

Use fan RTF only for cycling fan impact on AFN distribution losses #11571

Open

16 tasks

lymereJ added a commit that referenced this pull request May 4, 2026

Test from #11491.

0ee296b

	OnOffFanRunTimeFraction = max(m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopHeatingCoilMaxRTF,
	m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopOnOffFanRTF,
	m_state.dataAirLoop->AirLoopAFNInfo(AirLoopNum).AFNLoopDXCoilRTF);

Conversation

lymereJ commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request overview

Pull Request Author

Reviewer

Uh oh!

lymereJ commented Mar 31, 2026

Uh oh!

lymereJ 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!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 31, 2026

⚠️ Regressions detected on ubuntu-24.04 for commit 7c78951

Uh oh!

Uh oh!

rraustad Apr 1, 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!

Uh oh!

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!

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!

lymereJ Apr 30, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lymereJ commented Mar 31, 2026 •

edited

Loading

⚠️ Regressions detected on ubuntu-24.04 for commit `7c78951`

rraustad Apr 1, 2026 •

edited

Loading

lymereJ Apr 30, 2026 •

edited

Loading