Heat transfer & exchangers

ε-NTU heat exchanger calculations, the air-side fan + heat-exchanger model used by ASHP/ASHPB, and the borehole g-function used by GSHP/GSHPB.

ε-NTU heat exchanger

Heat transfer and fluid dynamics calculations.

tmhp.heat_transfer.TRIDIAG_MATRIX_ALGORITHM(a_M, a_P, a_E, a_W, b_P)[source]

Solve tridiagonal matrix system using Thomas algorithm.

Parameters:

  • a_M (list[float]) – Main diagonal (a_P in standard notation).

  • a_P (list[float]) – Not used directly, maintained for signature compatibility.

  • a_E (list[float]) – Upper diagonal.

  • a_W (list[float]) – Lower diagonal.

  • b_P (list[float]) – RHS vector.

Returns:

Solution vector.

Return type:

list[float]

tmhp.heat_transfer.calc_LMTD_counter_flow(Th_in, Th_out, Tc_in, Tc_out)[source]

Calculate Log-Mean Temperature Difference for counter-flow heat exchanger.

Parameters:

  • Th_in (float) – Hot stream inlet temp [K].

  • Th_out (float) – Hot stream outlet temp [K].

  • Tc_in (float) – Cold stream inlet temp [K].

  • Tc_out (float) – Cold stream outlet temp [K].

Returns:

LMTD [K].

Return type:

float

tmhp.heat_transfer.calc_LMTD_parallel_flow(Th_in, Th_out, Tc_in, Tc_out)[source]

Calculate Log-Mean Temperature Difference for parallel-flow heat exchanger.

Parameters:

  • Th_in (float) – Hot stream inlet temp [K].

  • Th_out (float) – Hot stream outlet temp [K].

  • Tc_in (float) – Cold stream inlet temp [K].

  • Tc_out (float) – Cold stream outlet temp [K].

Returns:

LMTD [K].

Return type:

float

tmhp.heat_transfer.calc_UA_tank_arr(arr_D_in, arr_D_out, arr_L, arr_k, h_in, h_out)[source]

Calculate thermal conductance (UA) of a multi-layer cylindrical tank.

Parameters:

  • arr_D_in (array_like or list) – Inner diameters of layers [m].

  • arr_D_out (array_like or list) – Outer diameters of layers [m].

  • arr_L (array_like or list) – Lengths of layers [m].

  • arr_k (array_like or list) – Thermal conductivities of layers [W/mK].

  • h_in (float) – Inner convection coefficient [W/m2K].

  • h_out (float) – Outer convection coefficient [W/m2K].

Returns:

Thermal conductance [W/K].

Return type:

float

tmhp.heat_transfer.calc_h_vertical_plate(T_s, T_inf, L, fluid='Air', is_active=True)[source]

Calculate natural convection heat transfer coefficient for a vertical plate.

Parameters:

  • T_s (float) – Surface temperature [K].

  • T_inf (float) – Fluid temperature [K].

  • L (float) – Characteristic length [m].

  • fluid (str, optional) – Fluid name. Default is ‘Air’.

  • is_active (bool, optional) – If False, returns np.nan.

Returns:

Heat transfer coefficient [W/m2K].

Return type:

float

tmhp.heat_transfer.calc_simple_tank_UA(r0=0.2, H=0.8, x_shell=0.01, x_ins=0.1, k_shell=25.0, k_ins=0.03, h_o=10.0)[source]

Calculate simple tank UA value.

Parameters:

  • r0 (float) – Tank radius [m]

  • H (float) – Tank height [m]

  • x_shell (float) – Shell thickness [m]

  • x_ins (float) – Insulation thickness [m]

  • k_shell (float) – Shell thermal conductivity [W/mK]

  • k_ins (float) – Insulation thermal conductivity [W/mK]

  • h_o (float) – External convective heat transfer coefficient [W/m²K]

Returns:

Tank UA value [W/K]

Return type:

float

tmhp.heat_transfer.darcy_friction_factor(Re, e, d, is_active=True)[source]

Calculate the Darcy friction factor.

Uses Haaland equation.

Parameters:

  • Re (float) – Reynolds number.

  • e (float) – Surface roughness [m].

  • d (float) – Diameter [m].

  • is_active (bool, optional) – If False, returns np.nan.

Returns:

Friction factor.

Return type:

float

Air-side fan & heat exchanger

Heat exchanger and fan utility functions.

Functions for velocity-dependent UA calculation, HX performance solving, fan power curves, and HP schedule checking.

tmhp.hx_fan.calc_UA_from_dV_fan(dV_fan, dV_fan_design, A_cross, UA, exponent=0.71)[source]

Calculate velocity-dependent UA via lumped scaling (Wang et al., 2000).

Parameters:

  • dV_fan (float) – Current fan flow rate [m³/s].

  • dV_fan_design (float) – Design fan flow rate [m³/s].

  • A_cross (float) – Heat exchanger cross-sectional area [m²].

  • UA (float) – Design UA value [W/K].

  • exponent (float) – Exponent for velocity scaling. Default is 0.71 for a 1-row configuration.

Returns:

Scaled UA value [W/K].

Return type:

float

Notes

Instead of the Dittus-Boelter tube-side exponent (0.8), this uses a simplified lumped exponent (default 0.71). This derivation assumes a 1-row plain fin-and-tube configuration (N=1) where the Colburn j-factor is proportional to Re^-0.29, leading to h ∝ V^0.71. Multi-row coils may use exponents between 0.5 and 0.8 depending on configuration. Reference: Wang et al. (2000), DOI: 10.1016/S0017-9310(99)00333-6

tmhp.hx_fan.calc_fan_power_from_dV_fan(dV_fan, fan_params, vsd_coeffs, is_active=True)[source]

Calculate fan power using ASHRAE 90.1 VSD Curve.

Parameters:

  • dV_fan (float) – Current flow rate [m³/s].

  • fan_params (dict) – Must contain fan_design_flow_rate and fan_design_power.

  • vsd_coeffs (dict) – VSD Curve coefficients (c1 through c5).

  • is_active (bool) – If False, returns np.nan.

Returns:

Fan power [W].

Return type:

float

Borehole g-function

Borehole g-function and air property helpers.

Provides: - Finite Line Source (FLS) g-function for borehole heat exchangers - Air dynamic viscosity (Sutherland’s formula) and Prandtl number

tmhp.g_function.f(x)[source]

Helper function for G-function calculation.

Parameters:

x (float) – Input value

Returns:

f(x) = x*erf(x) - (1-exp(-x²))/√π

Return type:

float

tmhp.g_function.chi(s, rb, H, z0=0)[source]

Helper function for G-function calculation.

Parameters:

  • s (float) – Integration variable

  • rb (float) – Borehole radius [m]

  • H (float) – Borehole height [m]

  • z0 (float, optional) – Reference depth [m] (default: 0)

Returns:

chi function value

Return type:

float

tmhp.g_function.G_FLS(t, ks, as_, rb, H)[source]

Calculate the g-function for finite line source (FLS) model.

This function calculates the g-function used in ground source heat pump analysis. Results are cached for performance.

Parameters:

  • t (float) – Time [s]

  • ks (float) – Ground thermal conductivity [W/mK]

  • as (float) – Ground thermal diffusivity [m²/s]

  • rb (float) – Borehole radius [m]

  • H (float) – Borehole height [m]

Returns:

g-function value [mK/W]. Returns scalar for single time value, array for multiple time values.

Return type:

float or array

tmhp.g_function.precompute_gfunction(N_1, N_2, B, H_b, D_b, r_b, alpha_s, k_s, t_max_s, dt_s)[source]

Precompute g-function using pygfunction and return an interpolator.

Creates a rectangular borehole field and computes the g-function for log-spaced time steps up to t_max_s (plus an extra margin). Returns a callable interp1d object predicting the g-function [mK/W].

Parameters:

  • N_1 (int) – Number of boreholes in x-direction.

  • N_2 (int) – Number of boreholes in y-direction.

  • B (float) – Borehole spacing [m].

  • H_b (float) – Borehole depth/length [m].

  • D_b (float) – Buried depth [m].

  • r_b (float) – Borehole radius [m].

  • alpha_s (float) – Ground thermal diffusivity [m²/s].

  • k_s (float) – Ground thermal conductivity [W/mK].

  • t_max_s (float) – Maximum simulation time [s].

  • dt_s (float) – Simulation timestep [s].

Returns:

Interpolator function mapping time [s] to g-function [mK/W].

Return type:

scipy.interpolate.interp1d

tmhp.g_function.chi_mfls(s, r, H, x_prime, U, alpha_s, z0=0)[source]

Helper function for MFLS (Moving Finite Line Source) G-function calculation.

Ref: Molina-Giraldo et al. (2011), “A moving finite line source model to simulate borehole heat exchangers with groundwater advection”

tmhp.g_function.G_MFLS_Field(times, boreholes, v_gw, theta_gw, rho_w, c_w, alpha_s, k_s, rho_s, c_s)[source]

Calculate the spatial superposition of the MFLS response for a bore field.

Parameters:

  • times (np.ndarray) – Array of time values [s]

  • boreholes (list) – List of pygfunction Borehole objects

  • v_gw (float) – Darcy velocity of groundwater [m/s]

  • theta_gw (float) – Direction of groundwater flow [rad]

  • rho_w (float) – Density of groundwater [kg/m³]

  • c_w (float) – Specific heat capacity of groundwater [J/kgK]

  • alpha_s (float) – Ground thermal diffusivity [m²/s]

  • k_s (float) – Ground thermal conductivity [W/mK]

  • rho_s (float) – Density of ground [kg/m³]

  • c_s (float) – Specific heat capacity of ground [J/kgK]

Returns:

Dimensional g-values for the entire field over time [mK/W]

Return type:

np.ndarray

tmhp.g_function.precompute_gfunction_mls(N_1, N_2, B, H_b, D_b, r_b, alpha_s, k_s, rho_s, c_s, v_gw, theta_gw, rho_w, c_w, t_max_s, dt_s)[source]

Precompute the MFLS g-function and return an interpolator.

Parameters:

  • N_1 (int)

  • N_2 (int)

  • B (float)

  • H_b (float)

  • D_b (float)

  • r_b (float)

  • alpha_s (float)

  • k_s (float)

  • rho_s (float)

  • c_s (float)

  • v_gw (float)

  • theta_gw (float)

  • rho_w (float)

  • c_w (float)

  • t_max_s (float)

  • dt_s (float)

Return type:

interp1d

tmhp.g_function.air_dynamic_viscosity(T_K)[source]

Calculate air dynamic viscosity using Sutherland’s formula.

Parameters:

T_K (float) – Temperature [K]

Returns:

  • float – Dynamic viscosity [Pa·s]

  • Reference (Sutherland’s formula for air)

  • mu = mu0 * (T/T0)^1.5 * (T0 + S) / (T + S)

  • where mu0 = 1.716e-5 Pa·s at T0 = 273.15 K, S = 110.4 K

tmhp.g_function.air_prandtl_number(T_K)[source]

Calculate air Prandtl number.

Parameters:

T_K (float) – Temperature [K]

Returns:

  • float – Prandtl number [-]

  • Note (Pr ≈ 0.71 for air at typical temperatures (20-50°C))

  • Temperature dependence is weak, so using constant value.

tmhp.g_function.calc_local_borehole_thermal_resistance(k_s, k_g, k_p, r_b, r_out, r_in, D_s, m_flow_pipe, rho_f, mu_f, cp_f, k_f)[source]

Calculate the local borehole thermal resistance and internal thermal resistance [mK/W] using pygfunction multipole method.

Assumes a Single U-tube configuration.

Parameters:

  • k_s (float) – Ground thermal conductivity [W/mK]

  • k_g (float) – Grout thermal conductivity [W/mK]

  • k_p (float) – Pipe thermal conductivity [W/mK]

  • r_b (float) – Borehole radius [m]

  • r_out (float) – Pipe outer radius [m]

  • r_in (float) – Pipe inner radius [m]

  • D_s (float) – Shank spacing (half distance between pipes) [m]

  • m_flow_pipe (float) – Mass flow rate per pipe [kg/s]

  • rho_f (float) – Fluid density [kg/m³]

  • mu_f (float) – Fluid dynamic viscosity [Pa·s]

  • cp_f (float) – Fluid specific heat capacity [J/kgK]

  • k_f (float) – Fluid thermal conductivity [W/mK]

Returns:

(R_b, R_a) R_b: Local borehole thermal resistance [mK/W]. R_a: Internal thermal resistance between the two pipes [mK/W].

Return type:

tuple[float, float]

tmhp.g_function.calc_effective_borehole_thermal_resistance(R_b, R_a, H, m_flow_pipe, cp_f, boundary_condition='uniform_temperature')[source]

Calculate the effective borehole thermal resistance [mK/W].

Parameters:

  • R_b (float) – Local borehole thermal resistance [mK/W]

  • R_a (float) – Internal thermal resistance between the two pipes [mK/W]

  • H (float) – Borehole depth [m]

  • m_flow_pipe (float) – Mass flow rate per pipe [kg/s]

  • cp_f (float) – Fluid specific heat capacity [J/kgK]

  • boundary_condition (str) – Boundary condition for the calculation. Options: ‘uniform_temperature’ or ‘uniform_heat_flux’.

Returns:

Effective borehole thermal resistance [mK/W].

Return type:

float

References

  1. Hellström, G. (1991). Ground Heat Storage: Thermal Analyses of Duct Storage Systems (Ph.D. thesis). University of Lund, Sweden.

  2. Lamarche, L., Kajl, S., & Beauchamp, B. (2010). A review of methods to evaluate borehole thermal resistances in geothermal heat-pump systems. Geothermics, 39(2), 187-200. DOI: 10.1016/j.geothermics.2010.03.003

  3. Javed, S., & Spitler, J. D. (2016). Accuracy of borehole thermal resistance calculation methods for grouted single U-tube ground heat exchangers. Applied Energy, 182, 161-176. DOI: 10.1016/j.apenergy.2016.08.054

tmhp.g_function.calc_submerged_coil_thermal_resistance(r_out, r_in, D_s, k_p, m_flow_pipe, rho_f, mu_f, cp_f, k_f, v_river=0.5)[source]

Calculate the local thermal resistance [mK/W] of a submerged surface water heat exchanger coil.

Uses the Churchill-Bernstein correlation for cross-flow forced convection over a cylinder to estimate the external (river water) convective heat transfer coefficient. It tricks pygfunction’s SingleUTube model into capturing this pure pipe resistance without any ground thermal mass by assigning exceptionally high thermal conductivities to the grout and ground.

Parameters:

  • r_out (float) – Pipe outer radius [m]

  • r_in (float) – Pipe inner radius [m]

  • D_s (float) – Shank spacing (half distance between pipes) [m]

  • k_p (float) – Pipe thermal conductivity [W/mK]

  • m_flow_pipe (float) – Mass flow rate per pipe [kg/s]

  • rho_f (float) – Internal fluid density [kg/m³]

  • mu_f (float) – Internal fluid dynamic viscosity [Pa·s]

  • cp_f (float) – Internal fluid specific heat capacity [J/kgK]

  • k_f (float) – Internal fluid thermal conductivity [W/mK]

  • v_river (float) – Velocity of the river water cross-flow [m/s]

Returns:

Thermal resistance of the submerged coil [mK/W].

Return type:

float