Unexpected (hard coded) duct leakage "error" limits causing HPXML file issues.

[chrisbalbach]

Version:
"HPXML to OS", v1.11.0

Rational: The specific case that triggered this was observing that older HPXML files describing 'very leaky' mobile home duct systems, when migrated to the v1.11 HPXML to OS workflow, will no longer simulate w/o error. The HPXML (existing) duct leakage values used to represent the "leaky ducts" of mobile homes (detached duct register boots, etc.) have been field measured and represent common scenarios with large potential for savings when remediated. In other words, we want to be able to quantify and capture these savings when the existing ducts are either sealed/abandoned and new (ductless) heat pumps are installed..

Observed Behavior:
Existing home duct leakage values are triggering (newly added in v1.11) error limits defined in method named "check_duct_leakage" within "airflow.rb". We are unable to de-escalate the "error" to a "warning", without modifying the core dependency, which is not desirable.

Expected Behavior:
Prior to V1.11, these values of duct leakage simulated w/o error, as while "warnings" existed, the error messages were not present. As software developers leveraging the HPXML to OS workflow as a key dependency, we expect our user-experience maintain responsibility for setting value limits (especially errors) of the data entered by our users.

Recommended Solution(s):
Considering the "HPXML to OS" modeling use-case, we believe that unless and HPXML element value results in the corresponding EnergyPlus simulation failing, the evaluation of HPXML Element values that are considered "Errors" (those that halt a simulation) should NOT be implemented within the core dependency, but instead should be implemented within a higher (UI?) layer. This maintains flexibility for the higher layer to set "Error" (and "Warning") limits as defined by the particular software use-case (existing buildings can have ducts in quite poor condition).

Option 1: Within the HPXML to OS "airflow.rb" file, de-escalate the current (2) "Error" limits to "Warnings" and modify message to describe a more severe warning.

Option 2: Remove current "Error" limits from HPXML to OS "airflow.rb" entirely and potentially migrate Error limits to other rulesets.

In cases where the (2) "Error" limits are defined by the specific use-case (for example, limits of an Element value defined by ERI 301, ZERH, etc.), we believe the Element value check should be implemented within in the specific use-case ruleset - not within the upstream core dependency.

[Sashadf2]

I'll add that this is an issue unique to v1.11

check_duct_leakage in v1.10 only issued warnings, not errors

[shorowit]

How much leakage are you trying to model?

We introduced the errors (here) because we had the opposite problem where users where incorrectly modeling very high duct leakage and a warning was not sufficient. We also commonly see issues where users double-count duct leakage -- they intend to model say 30% duct leakage, but they apply 30% to both the supply and return sides, which effectively means they are requesting 60% duct leakage (i.e., more than half the air in the ducts are not making it to the conditioned space).

[chrisbalbach]

Hi Scott: Our "FE Warm" weatherization program has collected duct leakage data (using pre and post pressure pan measurements) as part of manufactured home audit improvements for several years. In this program, ducts must be sealed to leak "no more than 1 Pa. when testing at 25 Pa" (see item (2) in the attached priority list). I can't share individual job results (PII) and I believe the MHEA tool was used for estimating savings these audits, but we want to build tools that support Mobile Home Audits and I can assure you that the reported pre data (both pre and post tests are required) from many of the completed jobs have levels that exceed what v1.11 currently would currently results in a hard "error", and that the combination of ductwork improvements and general air sealing are (2) biggest contributors to program savings (on an ECM basis). Also, for another point of reference, RemRate (another residential software that is often used for modeling existing mobile homes) does not appear to hard limits for entered duct leakages that result in simulation failure. Regardless, I stand by my opinion that in general, "end-use applications" should be responsible for their user management by managing and setting data entry limits (and the consequences of their exceedance), not the core software library/dependency. As an example, our HPXML applications often ask for the depth of a wall cavity (something field verifiable) and then use that information to downstream flag/limit unreasonably large assembly wall R-values entered by the user. We would not expect the "HPXML to OS" workflow take over those kinds of QA/QC functions for us, as the specific limits as to what is an "error" or a "warning" are often "client specific". _Chris

…

________________________________ From: Scott Horowitz ***@***.***> Sent: Monday, March 23, 2026 11:59 AM To: NatLabRockies/OpenStudio-HPXML ***@***.***> Cc: Chris Balbach ***@***.***>; Author ***@***.***> Subject: Re: [NatLabRockies/OpenStudio-HPXML] Unexpected (hard coded) duct leakage "error" limits causing HPXML file issues. (Issue #2180) [https://avatars.githubusercontent.com/u/5861765?s=20&v=4]shorowit left a comment (NatLabRockies/OpenStudio-HPXML#2180)<#2180 (comment)> How much leakage are you trying to model? We introduced the errors (here<#2143>) because we had the opposite problem where users where incorrectly modeling very high duct leakage and a warning was not sufficient. We also commonly see issues where users double-count duct leakage -- they intend to model say 30% duct leakage, but they apply 30% to both the supply and return sides, which effectively means they are requesting 60% duct leakage (i.e., more than half the air in the ducts are not making it to the conditioned space). — Reply to this email directly, view it on GitHub<#2180?email_source=notifications&email_token=ABL3ATPH2YAYWSPNUBA5L5T4SFNMZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJRGE3TENJXHA3KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-4111725786>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABL3ATJISNLSKNTS2KYNTLD4SFNMZAVCNFSM6AAAAACW4ISXNOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCMJRG4ZDKNZYGY>. You are receiving this because you authored the thread.Message ID: ***@***.***> NOTICE: This email may contain material that is confidential, privileged or exempt from disclosure under applicable law. If you are not the intended recipient, including situations where this email was addressed to you in error, please notify the sender immediately and delete this email. Any use, reliance upon, distribution or forwarding of this information without the sender's express permission is unauthorized and strictly prohibited. In no event shall we accept any responsibility for the loss or misuse of information including confidential information which is sent to us or our affiliates by email.

[shorowit]

The error checks are trying to prevent egregiously wrong inputs. For example, if ducts are in unconditioned space, we only throw an error when the sum of supply/return duct leakages to outside exceeds 100%, I would hope you agree with that. It's a bit less obvious where to draw the line for cfm25/cfm50 inputs or ducts in conditioned space, we've tried to be quite conservative but could have missed the mark.

It would be incredibly helpful if you could provide an example (snippet of HPXML inputs, or HPXML file) that causes you to hit an error. Unless I see your inputs, I have no idea if there's a user error/misunderstanding or if it's a legitimate scenario.