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 · 2026-05-28T20:14:35Z

@mitchute observed that while #11571 (a different PR) produces only minor diffs across a single file (AirflowNetwork_MultiZone_House_OvercoolDehumid), running year-long regressions on the AirflowNetwork_MultiZone_House_TwoSpeed model reveals notable differences. After investigating, I found that the current approach—which this PR extends—may have some underlying issues. The approach proposed in #11571 could potentially be more appropriate, and the observed diffs might be expected behavior.

The current approach (expanded here) determines OnOffFanRunTimeFraction by taking the maximum of AFNLoopHeatingCoilMaxRTF, AFNLoopOnOffFanRTF, and AFNLoopDXCoilRTF to estimate how cycling fan operation affects the airflow network (AFN). In contrast, #11571 proposes using only the fan runtime fraction (AFNLoopOnOffFanRTF), which could more directly represent actual fan/system cycling. I assumed that result differences might occur when AFNLoopDXCoilRTF or AFNLoopHeatingCoilMaxRTF exceed AFNLoopOnOffFanRTF. Since these variables weren't previously available as outputs, I added code to log them. The data shows several instances where AFNLoopDXCoilRTF > AFNLoopOnOffFanRTF during heating and AFNLoopDXCoilRTF is always 0 during cooling. Both of these are concerning.

I think that comparing these AFN variables to their non-AFN counterparts clarifies what's happening: AFNLoopOnOffFanRTF matches the fan's Fan Runtime Fraction, and during heating, AFNLoopDXCoilRTF matches the heating coil's Heating Coil Runtime Fraction. The issue seems to be that the heating coil runtime fraction is reported at the system's highest operating speed (so in isolation from the system), while the fan runtime fraction is calculated from the average flow rate based on the system's PLR. This results in inconsistencies—speed 1 operation shows coil fractions exceeding fan fractions, and speed 2 shows the opposite—which limits their reliability for determining cycling fan impact on AFN. I also ran the file using a AirLoopHVAC:UnitarySystem and got similar results.

It seems that #11571 could offer a potentially more sound and maintainable approach, as it might avoid dependencies on system/coil expansion logic. That said, we could potentially address these issues in the current approach, though doing so might require considering fixes across multiple coils and systems.

@rraustad, @mitchute - what are your thoughts?

rraustad · 2026-05-29T15:26:25Z

What I think AFN is doing is accounting for true on off cycling with adjustments such as this:

exchangeData(i).MultiZoneSen *= OnOffFanRunTimeFraction;

I am not positive but I think the only way this works is looking at the fan RTF. A coil RTF that reports what a speed is doing is not the same as what the air flow is doing. JMHO. I would welcome @jasondegraw input.

rraustad · 2026-05-29T15:50:36Z

The fall back position would be to leave AFN calculations alone for now and just correct the original issue. At least until this can be better understood. A simulation using constant fan compared to a system using cycling fan may provide insight into which of these methods is more accurate. e.g., a constant fan MultiZoneSen compared to cycling fan MultiZoneSen/RTF should look the same?

Update: it doesn't look like MultiZoneSen is a report variable so a valid report from AFN that adjusts that report by RTF would need to be used. Like this:

        SetupOutputVariable(m_state,
                            "AFN Zone Infiltration Sensible Heat Gain Rate",
                            Constant::Units::W,
                            AirflowNetworkReportData(i).MultiZoneInfiSenGainW,

       AirflowNetworkReportData(i).MultiZoneInfiSenGainW *= RepOnOffFanRunTimeFraction;

So, e.g., a constant fan MultiZoneInfiSenGainW compared to cycling fan MultiZoneInfiSenGainW/RTF should look the same?

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

Merge branch 'develop' into fix_unitary_system_afn_runtime_fracs

be1426f

	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!

lymereJ commented May 28, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

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

rraustad commented May 29, 2026 •

edited

Loading

rraustad commented May 29, 2026 •

edited

Loading