Ground-source heat pump (GSHP — space conditioning)

GSHP conditions a building zone, drawing or rejecting heat through the same g-function borehole heat exchanger as GSHPB.

Overview

The class is tmhp.GroundSourceHeatPump. Use it when the heat pump’s job is space conditioning rather than DHW production.

For quick parametric studies that do not need the full refrigerant cycle, tmhp.GroundSourceHeatPumpEmpirical provides a simpler EnergyPlus EquationFit COP model with the same borehole-response backbone.

Base usage

from tmhp import GroundSourceHeatPump

gshp = GroundSourceHeatPump(
    ref="R410A",
    N_1=1, N_2=1,
    H_b=150.0,
)

# See API reference below for the full constructor and
# analyze_steady / analyze_dynamic signatures.

Source-side mechanics

Same g-function-based borehole as Ground-source heat pump boiler (GSHPB). See that page for the detailed mechanic and the g-function figure.

Sink-side mechanics

A zone temperature / load proxy stands in for the building, as in Air-source heat pump (ASHP — space conditioning). The indoor-unit load Q_r_iu selects operating mode: positive values are cooling, negative values are heating, and zero values are off operation.

Empirical alternative

class tmhp.GroundSourceHeatPumpEmpirical(H_b=150.0, D_b=2.0, r_b=0.08, k_p=0.4, k_grout=1.5, r_out=0.016, r_in=0.013, D_s=0.032, k_g=2.0, c_g=800.0, rho_g=2000.0, T_g=15.0, dV_f=20.0, Q_rated_cooling=20590.0, Q_rated_heating=16450.0, E_pmp=100.0, dP_iu_fan_design=60.0, eta_iu_fan_design=0.6, dt_hours=1, sim_hours=8760, Q_r_iu=0.0, T0=20.0)[source]

Bases: object

Ground source heat pump model using the EnergyPlus EquationFit COP model.

Uses borehole heat exchangers with pygfunction step-response factor array for precise soil thermal response with temporal superposition of dynamic building loads.

This model computes borehole thermal resistance R_b* automatically using the pygfunction multipole method (Hellström 1991), and fan power using the ASHRAE 90.1 VSD curve.

For a full refrigerant-cycle model, see GroundSourceHeatPump.

Parameters:

  • H_b (float)

  • D_b (float)

  • r_b (float)

  • k_p (float)

  • k_grout (float)

  • r_out (float)

  • r_in (float)

  • D_s (float)

  • k_g (float)

  • c_g (float)

  • rho_g (float)

  • T_g (float)

  • dV_f (float)

  • Q_rated_cooling (float)

  • Q_rated_heating (float)

  • E_pmp (float)

  • dP_iu_fan_design (float)

  • eta_iu_fan_design (float)

  • dt_hours (int)

  • sim_hours (int)

  • Q_r_iu (float)

  • T0 (float)

H_b: float = 150.0
D_b: float = 2.0
r_b: float = 0.08
k_p: float = 0.4
k_grout: float = 1.5
r_out: float = 0.016
r_in: float = 0.013
D_s: float = 0.032
k_g: float = 2.0
c_g: float = 800.0
rho_g: float = 2000.0
T_g: float = 15.0
dV_f: float = 20.0
Q_rated_cooling: float = 20590.0
Q_rated_heating: float = 16450.0
E_pmp: float = 100.0
dP_iu_fan_design: float = 60.0
eta_iu_fan_design: float = 0.6
dt_hours: int = 1
sim_hours: int = 8760
Q_r_iu: float = 0.0
T0: float = 20.0
system_update()[source]

Advance the model by one timestep.

Call this method once per timestep after setting Q_r_iu and T0. The method computes COP, temperatures, fan power, and component exergy balances.

__init__(H_b=150.0, D_b=2.0, r_b=0.08, k_p=0.4, k_grout=1.5, r_out=0.016, r_in=0.013, D_s=0.032, k_g=2.0, c_g=800.0, rho_g=2000.0, T_g=15.0, dV_f=20.0, Q_rated_cooling=20590.0, Q_rated_heating=16450.0, E_pmp=100.0, dP_iu_fan_design=60.0, eta_iu_fan_design=0.6, dt_hours=1, sim_hours=8760, Q_r_iu=0.0, T0=20.0)
Parameters:

  • H_b (float)

  • D_b (float)

  • r_b (float)

  • k_p (float)

  • k_grout (float)

  • r_out (float)

  • r_in (float)

  • D_s (float)

  • k_g (float)

  • c_g (float)

  • rho_g (float)

  • T_g (float)

  • dV_f (float)

  • Q_rated_cooling (float)

  • Q_rated_heating (float)

  • E_pmp (float)

  • dP_iu_fan_design (float)

  • eta_iu_fan_design (float)

  • dt_hours (int)

  • sim_hours (int)

  • Q_r_iu (float)

  • T0 (float)

API reference

Ground source heat pump — physics-based cycle model with indoor unit.

Resolves a vapour-compression refrigerant cycle coupled to a borehole heat exchanger (BHE) on the source side and an indoor-air heat exchanger on the load side. Supports both cooling (Q_r_iu > 0) and heating (Q_r_iu < 0) modes.

At each time step the model finds the minimum-power operating point (compressor + BHE pump + indoor fan) via bounded 2-D optimisation over the evaporator and condenser approach temperature differences.

Borehole thermal response is tracked with pygfunction-based multi-borehole g-functions, enabling robust long-term ground temperature drift modelling.

Architecture mirrors GroundSourceHeatPumpBoiler for the BHE side and AirSourceHeatPump for the indoor-unit side.

class tmhp.ground_source_heat_pump.GroundSourceHeatPump(ref='R32', V_cmp_ref=None, eta_cmp_isen=0.8, dT_superheat=5.0, dT_subcool=5.0, UA_cond=None, UA_evap=None, dV_iu_fan_a_rated=None, dP_iu_fan_rated=None, A_cross_iu=None, eta_iu_fan_rated=None, vsd_coeffs_iu=None, N_1=1, N_2=1, B=6.0, D_b=0, H_b=100, r_b=0.08, R_b=0.108, dV_b_f_lpm=20.04, k_s=2.0, c_s=800, rho_s=2000, Ts=16.0, E_pmp=100, hp_capacity=4000.0, T_a_room=27.0, dT_hx_min=0.5, PR_cycle_min=1.5, PR_cycle_max=5.0, t_max_s=31536000, dt_s=3600, V_disp_cmp=None, UA_cond_design=None, UA_evap_design=None, dV_iu_fan_a_design=None, dP_iu_fan_design=None, eta_iu_fan_design=None)[source]

Bases: object

Ground source heat pump with BHE and indoor-unit air heat exchange.

The refrigerant cycle is resolved via CoolProp. A bounded 2-D optimiser minimises total electrical input (E_cmp + E_pmp + E_iu_fan) over the evaporator and condenser approach temperatures.

Parameters:

  • ref (str)

  • V_cmp_ref (Optional[float])

  • eta_cmp_isen (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond (Optional[float])

  • UA_evap (Optional[float])

  • dV_iu_fan_a_rated (Optional[float])

  • dP_iu_fan_rated (Optional[float])

  • A_cross_iu (Optional[float])

  • eta_iu_fan_rated (Optional[float])

  • vsd_coeffs_iu (Optional[dict])

  • N_1 (int)

  • N_2 (int)

  • B (float)

  • D_b (float)

  • H_b (float)

  • r_b (float)

  • R_b (float)

  • dV_b_f_lpm (float)

  • k_s (float)

  • c_s (float)

  • rho_s (float)

  • Ts (float)

  • E_pmp (float)

  • hp_capacity (float)

  • T_a_room (float)

  • dT_hx_min (float)

  • PR_cycle_min (float)

  • PR_cycle_max (float)

  • t_max_s (float)

  • dt_s (float)

  • V_disp_cmp (Optional[float])

  • UA_cond_design (Optional[float])

  • UA_evap_design (Optional[float])

  • dV_iu_fan_a_design (Optional[float])

  • dP_iu_fan_design (Optional[float])

  • eta_iu_fan_design (Optional[float])

__init__(ref='R32', V_cmp_ref=None, eta_cmp_isen=0.8, dT_superheat=5.0, dT_subcool=5.0, UA_cond=None, UA_evap=None, dV_iu_fan_a_rated=None, dP_iu_fan_rated=None, A_cross_iu=None, eta_iu_fan_rated=None, vsd_coeffs_iu=None, N_1=1, N_2=1, B=6.0, D_b=0, H_b=100, r_b=0.08, R_b=0.108, dV_b_f_lpm=20.04, k_s=2.0, c_s=800, rho_s=2000, Ts=16.0, E_pmp=100, hp_capacity=4000.0, T_a_room=27.0, dT_hx_min=0.5, PR_cycle_min=1.5, PR_cycle_max=5.0, t_max_s=31536000, dt_s=3600, V_disp_cmp=None, UA_cond_design=None, UA_evap_design=None, dV_iu_fan_a_design=None, dP_iu_fan_design=None, eta_iu_fan_design=None)[source]
Parameters:

  • ref (str)

  • V_cmp_ref (Optional[float])

  • eta_cmp_isen (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond (Optional[float])

  • UA_evap (Optional[float])

  • dV_iu_fan_a_rated (Optional[float])

  • dP_iu_fan_rated (Optional[float])

  • A_cross_iu (Optional[float])

  • eta_iu_fan_rated (Optional[float])

  • vsd_coeffs_iu (Optional[dict])

  • N_1 (int)

  • N_2 (int)

  • B (float)

  • D_b (float)

  • H_b (float)

  • r_b (float)

  • R_b (float)

  • dV_b_f_lpm (float)

  • k_s (float)

  • c_s (float)

  • rho_s (float)

  • Ts (float)

  • E_pmp (float)

  • hp_capacity (float)

  • T_a_room (float)

  • dT_hx_min (float)

  • PR_cycle_min (float)

  • PR_cycle_max (float)

  • t_max_s (float)

  • dt_s (float)

  • V_disp_cmp (Optional[float])

  • UA_cond_design (Optional[float])

  • UA_evap_design (Optional[float])

  • dV_iu_fan_a_design (Optional[float])

  • dP_iu_fan_design (Optional[float])

  • eta_iu_fan_design (Optional[float])

analyze_steady(Q_r_iu, T0, T_a_room=None, *, return_dict=True)[source]

Run a steady-state performance snapshot.

Returns:

Cycle state plus diagnostic flags. Notable keys:

  • "converged" (bool) — True only when the HX optimisation and the SciPy optimiser both succeeded.

  • "failure_reason" (str) — one of "none", "cycle_invalid", "hx_not_converged", or "optimizer_failed".

GSHP triggers an off-mode fallback only when the refrigerant cycle itself was infeasible ("cycle_invalid"); in that case E_cmp [W] is 0 and COP keys are NaN. The other non-"none" values are diagnostic — the cycle numbers are populated and usable.

Return type:

dict | pd.DataFrame

Parameters:

  • Q_r_iu (float)

  • T0 (float)

  • T_a_room (Optional[float])

  • return_dict (bool)

analyze_dynamic(simulation_period_sec, dt_s, Q_r_iu_schedule, T0_schedule, T_a_room_schedule=None, result_save_csv_path=None)[source]

Time-stepping dynamic simulation with BHE superposition.

Parameters:

  • simulation_period_sec (int)

  • dt_s (int)

  • result_save_csv_path (Optional[str])

Return type:

DataFrame

postprocess_exergy(df)[source]

Compute GSHP-specific exergy: 6 subsystems × (X_in, Xc, X_out).

Parameters:

df (DataFrame)

Return type:

DataFrame

Ground source heat pump — simple COP-based model with indoor unit.

This module provides a simplified GSHP model using the EnergyPlus EquationFit COP correlation rather than a full refrigerant cycle analysis. It is a lightweight alternative to the CoolProp-based GroundSourceHeatPump for quick parametric studies.

Borehole thermal response is tracked with pygfunction-based g-functions and temporal superposition of dynamic building loads. The effective borehole thermal resistance R_b* is automatically computed using the pygfunction multipole method.

class tmhp.gshp_empirical.GroundSourceHeatPumpEmpirical(H_b=150.0, D_b=2.0, r_b=0.08, k_p=0.4, k_grout=1.5, r_out=0.016, r_in=0.013, D_s=0.032, k_g=2.0, c_g=800.0, rho_g=2000.0, T_g=15.0, dV_f=20.0, Q_rated_cooling=20590.0, Q_rated_heating=16450.0, E_pmp=100.0, dP_iu_fan_design=60.0, eta_iu_fan_design=0.6, dt_hours=1, sim_hours=8760, Q_r_iu=0.0, T0=20.0)[source]

Bases: object

Ground source heat pump model using the EnergyPlus EquationFit COP model.

Uses borehole heat exchangers with pygfunction step-response factor array for precise soil thermal response with temporal superposition of dynamic building loads.

This model computes borehole thermal resistance R_b* automatically using the pygfunction multipole method (Hellström 1991), and fan power using the ASHRAE 90.1 VSD curve.

For a full refrigerant-cycle model, see GroundSourceHeatPump.

Parameters:

  • H_b (float)

  • D_b (float)

  • r_b (float)

  • k_p (float)

  • k_grout (float)

  • r_out (float)

  • r_in (float)

  • D_s (float)

  • k_g (float)

  • c_g (float)

  • rho_g (float)

  • T_g (float)

  • dV_f (float)

  • Q_rated_cooling (float)

  • Q_rated_heating (float)

  • E_pmp (float)

  • dP_iu_fan_design (float)

  • eta_iu_fan_design (float)

  • dt_hours (int)

  • sim_hours (int)

  • Q_r_iu (float)

  • T0 (float)

H_b: float = 150.0
D_b: float = 2.0
r_b: float = 0.08
k_p: float = 0.4
k_grout: float = 1.5
r_out: float = 0.016
r_in: float = 0.013
D_s: float = 0.032
k_g: float = 2.0
c_g: float = 800.0
rho_g: float = 2000.0
T_g: float = 15.0
dV_f: float = 20.0
Q_rated_cooling: float = 20590.0
Q_rated_heating: float = 16450.0
E_pmp: float = 100.0
dP_iu_fan_design: float = 60.0
eta_iu_fan_design: float = 0.6
dt_hours: int = 1
sim_hours: int = 8760
Q_r_iu: float = 0.0
T0: float = 20.0
system_update()[source]

Advance the model by one timestep.

Call this method once per timestep after setting Q_r_iu and T0. The method computes COP, temperatures, fan power, and component exergy balances.

__init__(H_b=150.0, D_b=2.0, r_b=0.08, k_p=0.4, k_grout=1.5, r_out=0.016, r_in=0.013, D_s=0.032, k_g=2.0, c_g=800.0, rho_g=2000.0, T_g=15.0, dV_f=20.0, Q_rated_cooling=20590.0, Q_rated_heating=16450.0, E_pmp=100.0, dP_iu_fan_design=60.0, eta_iu_fan_design=0.6, dt_hours=1, sim_hours=8760, Q_r_iu=0.0, T0=20.0)
Parameters:

  • H_b (float)

  • D_b (float)

  • r_b (float)

  • k_p (float)

  • k_grout (float)

  • r_out (float)

  • r_in (float)

  • D_s (float)

  • k_g (float)

  • c_g (float)

  • rho_g (float)

  • T_g (float)

  • dV_f (float)

  • Q_rated_cooling (float)

  • Q_rated_heating (float)

  • E_pmp (float)

  • dP_iu_fan_design (float)

  • eta_iu_fan_design (float)

  • dt_hours (int)

  • sim_hours (int)

  • Q_r_iu (float)

  • T0 (float)