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.

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).

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_disp_cmp=0.0001, eta_cmp_isen=0.8, dT_superheat=5.0, dT_subcool=5.0, UA_cond_design=None, UA_evap_design=None, dV_iu_fan_a_design=None, dP_iu_fan_design=60.0, A_cross_iu=None, eta_iu_fan_design=0.6, 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, t_max_s=31536000, dt_s=3600)[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_disp_cmp (float)

  • eta_cmp_isen (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond_design (Optional[float])

  • UA_evap_design (Optional[float])

  • dV_iu_fan_a_design (Optional[float])

  • dP_iu_fan_design (float)

  • A_cross_iu (Optional[float])

  • eta_iu_fan_design (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)

  • t_max_s (float)

  • dt_s (float)

__init__(ref='R32', V_disp_cmp=0.0001, eta_cmp_isen=0.8, dT_superheat=5.0, dT_subcool=5.0, UA_cond_design=None, UA_evap_design=None, dV_iu_fan_a_design=None, dP_iu_fan_design=60.0, A_cross_iu=None, eta_iu_fan_design=0.6, 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, t_max_s=31536000, dt_s=3600)[source]
Parameters:

  • ref (str)

  • V_disp_cmp (float)

  • eta_cmp_isen (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond_design (Optional[float])

  • UA_evap_design (Optional[float])

  • dV_iu_fan_a_design (Optional[float])

  • dP_iu_fan_design (float)

  • A_cross_iu (Optional[float])

  • eta_iu_fan_design (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)

  • t_max_s (float)

  • dt_s (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