Add demand calculation checks #3938

reyery · 2025-10-21T17:22:57Z

Add guards for division by zero and checks for physical limitations.

Introduces checks for invalid input values and potential division by zero in RC model, substation, and thermal network calculations. Raises descriptive ValueErrors when temperature differences or heat transfer coefficients are non-physical or near zero, improving robustness and error reporting for building and network simulations.

Introduces explicit checks for minimum temperature difference in space heating and cooling mass flow calculations. Raises a ValueError with detailed diagnostic information if the supply and return temperatures are too close, preventing division by near-zero and guiding users to check HVAC database values.

Introduces checks to ensure valid temperature differences and COP values in chiller and system COP calculations. Raises descriptive ValueErrors for physically impossible or invalid configurations, improving robustness and error reporting in chiller_vapor_compression.py.

Introduces comprehensive input validation and error handling for temperature differences and ratios in heat pump COP and mass flow calculations. This prevents unphysical or invalid configurations by raising informative ValueErrors when temperature conditions are not met, improving robustness and debugging clarity for air, ground, lake, and sewage heat pump models.

Added checks in calc_pump_power to ensure PUMP_ETA is within (0, 1.0] and P_WATER_KGPERM3 is positive. Raises ValueError with descriptive messages if constants are out of expected range, helping to catch configuration errors early.

Added validation in efficiencies_not_converged to avoid division by zero when previous_efficiency is near zero. Enhanced error message in calc_dTm_HEX with units and additional guidance for debugging temperature configuration issues.

Introduces parameter validation and descriptive error messages in calc_max_diameter and calc_linear_thermal_loss_coefficient to prevent invalid calculations due to non-physical or out-of-range input values. This improves robustness and helps users diagnose configuration or data issues.

Introduces comprehensive input validation and descriptive error messages for logarithm arguments and denominator values in friction factor, Reynolds number, and thermal resistance calculations. These checks help prevent invalid physical configurations and improve debugging by providing detailed context when errors occur.

Replaces ValueError with a return of 0.0 when supply and return temperatures are nearly equal in space heating and cooling mass flow calculations. This reflects the physically correct scenario of no water flow and no pump energy for minimal temperature differences.

Refactored substation_model_heating to correctly handle hours with negligible temperature difference, ensuring heat capacity is zero when physically appropriate. Added robust error handling for invalid temperature configurations and improved nominal condition selection. Updated calc_HEX_heating to return zero values when heat capacity flow is zero, preventing calculation errors.

Improves calc_HEX_cooling by adding input and result validation for cases where primary or secondary side temperature differences are negligible, preventing unnecessary calculations and ensuring meaningful heat transfer results.

Replaces hardcoded temperature difference thresholds with named constants in heat pump, chiller, substation, and thermal network modules for improved maintainability and numerical stability. Adds new constants to cea/constants.py and updates all relevant checks and error messages to use these values.

Copilot

Pull Request Overview

This PR adds validation checks for division by zero and physical limitations in thermal network demand calculations. The changes prevent runtime errors and ensure physically valid configurations by validating temperature differences, pipe dimensions, and thermodynamic constraints before performing calculations.

Key Changes:

Added validation for division by zero in temperature, flow rate, and heat transfer calculations
Introduced new constants for minimum temperature differences and convergence tolerances
Enhanced error messages to provide detailed diagnostic information

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
cea/constants.py	Adds new constants for minimum temperature differences and convergence tolerances
cea/technologies/thermal_network/thermal_network_loss.py	Adds division by zero check for pipe outlet temperature calculation
cea/technologies/thermal_network/thermal_network.py	Adds validation for Reynolds number, Darcy friction factor, and pipe dimension calculations
cea/technologies/thermal_network/substation_matrix.py	Adds validation for heat exchanger effectiveness iteration and temperature differences
cea/technologies/thermal_network/simplified_thermal_network.py	Adds validation for pipe diameter and thermal loss coefficient calculations
cea/technologies/substation.py	Adds temperature difference validation for heat capacity and heat exchanger calculations
cea/technologies/pumps.py	Adds validation for pump efficiency and water density constants
cea/technologies/heatpumps.py	Adds temperature validation for heat pump COP calculations across multiple heat pump types
cea/technologies/chiller_vapor_compression.py	Adds temperature validation and Carnot limit checks for chiller COP calculations
cea/demand/rc_model_SIA.py	Adds validation for building area and heat transfer coefficients in RC model
cea/demand/electrical_loads.py	Adds temperature difference validation for pump auxiliary energy calculations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-23T02:55:14Z

cea/constants.py

+# Temperature difference tolerances for numerical stability
+# Used to avoid division by near-zero in heat transfer and mass flow calculations
+MIN_TEMP_DIFF_FOR_MASS_FLOW_K = 0.001  # Minimum temperature difference for mass flow calculation [K or °C]
+# Physical basis: Below 1 millikelvin, water flow becomes negligible and pump energy ≈ 0


The comment states 'Below 1 millikelvin' but the constant value is 0.001 K, which equals 1 millikelvin. The comment should say 'Below or equal to 1 millikelvin' or 'At 1 millikelvin or below' for accuracy.

Suggested change

# Physical basis: Below 1 millikelvin, water flow becomes negligible and pump energy ≈ 0

# Physical basis: At 1 millikelvin or below, water flow becomes negligible and pump energy ≈ 0

Copilot · 2025-10-23T02:55:14Z

cea/technologies/heatpumps.py



 from math import log, ceil
 import pandas as pd


The import statement is missing the numpy module which was removed from line 14 but is still used in the file (e.g., np.isclose at line 80). The numpy import should be retained.

Suggested change

import pandas as pd

import pandas as pd

import numpy as np

Copilot · 2025-10-23T02:55:15Z

cea/technologies/substation.py

 def efficiencies_not_converged(previous_efficiency, current_efficiency):
-    tolerance = 0.00000001
+    # Convergence tolerance for heat exchanger efficiency iteration
+    tolerance = 1e-08  # Same as HEAT_EXCHANGER_EFFICIENCY_CONVERGENCE_TOL


The comment references 'HEAT_EXCHANGER_EFFICIENCY_CONVERGENCE_TOL' but this constant is not imported or defined in this file or in constants.py. Either this constant should be imported and used instead of the hardcoded value, or the comment should be updated to remove the reference.

Suggested change

tolerance = 1e-08 # Same as HEAT_EXCHANGER_EFFICIENCY_CONVERGENCE_TOL

tolerance = 1e-08 # Convergence tolerance value

Copilot · 2025-10-23T02:55:15Z

cea/technologies/substation.py

+    # Check if primary side has meaningful temperature drop (thi != tho)
+    # If temperatures are essentially equal, no heat transfer occurs, skip iteration


[nitpick] The comment spans lines 756-757 but line 757 is not a continuation of the same logical statement needing a fix. The comment should be consolidated to a single line or properly structured as a multi-line comment block.

Suggested change

# Check if primary side has meaningful temperature drop (thi != tho)

# If temperatures are essentially equal, no heat transfer occurs, skip iteration

# Check if primary side has meaningful temperature drop (thi != tho); if temperatures are essentially equal, no heat transfer occurs, skip iteration

Copilot · 2025-10-23T02:55:15Z

cea/technologies/substation.py

+        # Check if secondary side has meaningful temperature rise (tci != tco)
+        # Even if primary side had temperature drop, heat exchanger may produce negligible secondary-side change
+        # This validates the RESULT of the iteration, while the check above validates the INPUT


[nitpick] This multi-line comment (lines 786-788) describes validation logic but could be more concise. Consider consolidating to: 'Validate secondary side temperature rise from iteration results (unlike primary side input validation above).'

Suggested change

# Check if secondary side has meaningful temperature rise (tci != tco)

# Even if primary side had temperature drop, heat exchanger may produce negligible secondary-side change

# This validates the RESULT of the iteration, while the check above validates the INPUT

# Validate secondary side temperature rise from iteration results (unlike primary side input validation above).

Copilot · 2025-10-23T02:55:15Z

cea/technologies/substation.py

+    # Handle case where cc_kWperK is zero (no heat capacity flow)
+    # This can occur when temperature difference between supply and return is negligible


The comment on lines 879-880 describes handling zero cc_kWperK but the actual check on line 881 also checks for Q_heating_W == 0.0. The comment should mention both conditions being checked.

Suggested change

# Handle case where cc_kWperK is zero (no heat capacity flow)

# This can occur when temperature difference between supply and return is negligible

# Handle cases where either cc_kWperK is zero (no heat capacity flow)

# or Q_heating_W is zero (no heating load). This can occur when temperature difference between supply and return is negligible or there is no demand.

reyery added 12 commits October 21, 2025 12:16

reyery requested a review from martin-mosteiro October 21, 2025 17:22

Remove unused import

fa4a6ff

reyery marked this pull request as ready for review October 23, 2025 02:53

reyery requested a review from Copilot October 23, 2025 02:54

Copilot AI reviewed Oct 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add demand calculation checks #3938

Add demand calculation checks #3938

Uh oh!

reyery commented Oct 21, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Copilot AI Oct 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	# Physical basis: Below 1 millikelvin, water flow becomes negligible and pump energy ≈ 0
	# Physical basis: At 1 millikelvin or below, water flow becomes negligible and pump energy ≈ 0

	tolerance = 1e-08 # Same as HEAT_EXCHANGER_EFFICIENCY_CONVERGENCE_TOL
	tolerance = 1e-08 # Convergence tolerance value

		# Check if primary side has meaningful temperature drop (thi != tho)
		# If temperatures are essentially equal, no heat transfer occurs, skip iteration

		# Handle case where cc_kWperK is zero (no heat capacity flow)
		# This can occur when temperature difference between supply and return is negligible

Uh oh!

Add demand calculation checks #3938

Are you sure you want to change the base?

Add demand calculation checks #3938

Uh oh!

Conversation

reyery commented Oct 21, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants