enex_analysis.air_source_heat_pump_boiler

Integrated System Model: Air Source Heat Pump Boiler (ASHPB).

This system class orchestrates the dynamic interaction between distinct thermodynamic sub-components to simulate the overall heating performance. While implemented as an integrated model, its physical calculations represent the behavior of:

  1. Refrigerant Cycle (Vapor-Compression): Evaluates thermodynamic states using CoolProp, enforcing superheat/subcool margins.

  2. Heat Pump Compressor: Models the compression process using isentropic and volumetric efficiencies to compute the actual discharge enthalpy and mass flow rate. The compressor power is determined from the enthalpy difference and the mass flow rate.

  3. Expansion Valve: Modeled as an isenthalpic expansion device (constant enthalpy) that throttles the refrigerant from the condensing pressure down to the evaporating pressure.

  4. Heat Exchangers (Condenser & Evaporator):

    • Condenser: Placed inside the tank (hydronic), utilizing a static overall heat transfer coefficient (UA_cond_design).

    • Evaporator: Air-coupled outdoor unit, utilizing a dynamic overall heat transfer coefficient (UA_evap) that scales non-linearly with fan airflow (Colburn j-factor analogy).

  5. Thermal Storage Tank: Modeled with lumped-capacitance and DHW mixing logic.

At each time step, the model finds the minimum-power operating point (compressor + fan) via bounded 1-D optimisation (Brent’s method) over the evaporator approach temperature difference.

Note

이 통합 시스템의 작동 원리와 개별 서브 컴포넌트 모델링에 대한 상세 이론적 배경은 Air Source Heat Pump Boiler (ASHPB) 및 Subsystem Components 를 참조하세요.

Optional sub-components (injected via constructor): - SolarThermalCollector — tank-circuit or mains-preheat placement - (future) PVPanel — photovoltaic integration

Tank-level management and UV disinfection are built-in features configured through constructor parameters.

Classes

AirSourceHeatPumpBoiler([ref, V_disp_cmp, ...])

Air source heat pump boiler with outdoor-air evaporator.
class enex_analysis.air_source_heat_pump_boiler.AirSourceHeatPumpBoiler(ref='R134a', V_disp_cmp=0.0002, eta_cmp_isen=None, eta_cmp_vol=None, eta_cmp_mech=0.855, dT_superheat=5.0, dT_subcool=5.0, UA_cond_design=None, UA_evap_design=None, n_evap=0.65, dV_ou_fan_a_design=None, dP_ou_fan_design=60.0, A_cross_ou=None, eta_ou_fan_design=0.6, T_tank_w_upper_bound=65.0, T_tank_w_lower_bound=60.0, T_mix_w_out=40.0, T_sup_w=15.0, hp_capacity=15000.0, dV_mix_w_out_max=0.0045, r0=0.2, H=1.2, x_shell=0.005, x_ins=0.05, k_shell=25, k_ins=0.03, h_o=15, tank_always_full=True, tank_level_lower_bound=0.5, tank_level_upper_bound=1.0, dV_tank_w_in_refill=0.001, prevent_simultaneous_flow=False, hp_on_schedule=None, stc=None, pv=None, uv=None, vsd_coeffs_ou=None)[source]

Air source heat pump boiler with outdoor-air evaporator.

The refrigerant cycle is resolved via CoolProp with user-specified superheat / subcool margins. The condenser approach temperature is determined analytically (dT_ref_cond = Q_cond_target / UA_cond), and a bounded 1-D optimiser (Brent’s method) minimises total electrical input (E_cmp + E_ou_fan) over the evaporator approach.

Parameters:

  • ref (str)

  • V_disp_cmp (float)

  • eta_cmp_isen (float | Callable | None)

  • eta_cmp_vol (float | Callable | None)

  • eta_cmp_mech (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond_design (float | None)

  • UA_evap_design (float | None)

  • n_evap (float)

  • dV_ou_fan_a_design (float | None)

  • dP_ou_fan_design (float)

  • A_cross_ou (float | None)

  • eta_ou_fan_design (float)

  • T_tank_w_upper_bound (float)

  • T_tank_w_lower_bound (float)

  • T_mix_w_out (float)

  • T_sup_w (float)

  • hp_capacity (float)

  • dV_mix_w_out_max (float)

  • r0 (float)

  • H (float)

  • x_shell (float)

  • x_ins (float)

  • k_shell (float)

  • k_ins (float)

  • h_o (float)

  • tank_always_full (bool)

  • tank_level_lower_bound (float)

  • tank_level_upper_bound (float)

  • dV_tank_w_in_refill (float)

  • prevent_simultaneous_flow (bool)

  • hp_on_schedule (list[tuple[float, float]] | None)

  • stc (SolarThermalCollector | None)

  • pv (PhotovoltaicSystem | None)

  • vsd_coeffs_ou (dict | None)

__init__(ref='R134a', V_disp_cmp=0.0002, eta_cmp_isen=None, eta_cmp_vol=None, eta_cmp_mech=0.855, dT_superheat=5.0, dT_subcool=5.0, UA_cond_design=None, UA_evap_design=None, n_evap=0.65, dV_ou_fan_a_design=None, dP_ou_fan_design=60.0, A_cross_ou=None, eta_ou_fan_design=0.6, T_tank_w_upper_bound=65.0, T_tank_w_lower_bound=60.0, T_mix_w_out=40.0, T_sup_w=15.0, hp_capacity=15000.0, dV_mix_w_out_max=0.0045, r0=0.2, H=1.2, x_shell=0.005, x_ins=0.05, k_shell=25, k_ins=0.03, h_o=15, tank_always_full=True, tank_level_lower_bound=0.5, tank_level_upper_bound=1.0, dV_tank_w_in_refill=0.001, prevent_simultaneous_flow=False, hp_on_schedule=None, stc=None, pv=None, uv=None, vsd_coeffs_ou=None)[source]
Parameters:

  • ref (str)

  • V_disp_cmp (float)

  • eta_cmp_isen (float | Callable | None)

  • eta_cmp_vol (float | Callable | None)

  • eta_cmp_mech (float | Callable)

  • dT_superheat (float)

  • dT_subcool (float)

  • UA_cond_design (float | None)

  • UA_evap_design (float | None)

  • n_evap (float)

  • dV_ou_fan_a_design (float | None)

  • dP_ou_fan_design (float)

  • A_cross_ou (float | None)

  • eta_ou_fan_design (float)

  • T_tank_w_upper_bound (float)

  • T_tank_w_lower_bound (float)

  • T_mix_w_out (float)

  • T_sup_w (float)

  • hp_capacity (float)

  • dV_mix_w_out_max (float)

  • r0 (float)

  • H (float)

  • x_shell (float)

  • x_ins (float)

  • k_shell (float)

  • k_ins (float)

  • h_o (float)

  • tank_always_full (bool)

  • tank_level_lower_bound (float)

  • tank_level_upper_bound (float)

  • dV_tank_w_in_refill (float)

  • prevent_simultaneous_flow (bool)

  • hp_on_schedule (list[tuple[float, float]] | None)

  • stc (SolarThermalCollector | None)

  • pv (PhotovoltaicSystem | None)

  • vsd_coeffs_ou (dict | None)

analyze_steady(T_tank_w, T0, Q_ref_cond, *, return_dict=True)[source]

Run a steady-state performance snapshot.

Evaluates the refrigerant cycle at a given operating point (T_tank_w, T0, Q_ref_cond) without solving the tank energy balance or tracking dynamic flows.

Parameters:

  • T_tank_w (float) – Tank water temperature [°C] — treated as a given input.

  • T0 (float) – Dead-state / outdoor-air temperature [°C].

  • Q_ref_cond (float) – Target condenser heat rate [W].

  • return_dict (bool) – If True return dict; else single-row DataFrame.

Return type:

dict | pd.DataFrame

analyze_dynamic(simulation_period_sec, dt_s, T_tank_w_init_C, dhw_usage_schedule, T0_schedule, I_DN_schedule=None, I_dH_schedule=None, T_sup_w_schedule=None, tank_level_init=1.0, result_save_csv_path=None)[source]

Run a time-stepping dynamic simulation.

Fully implicit scheme: fsolve solves for [T_next, level_next] each timestep.

Parameters:

  • simulation_period_sec (int) – Total simulation duration [s].

  • dt_s (int) – Time step size [s].

  • T_tank_w_init_C (float) – Initial tank temperature [°C].

  • dhw_usage_schedule (np.ndarray) – DHW volumetric flow rate per step [m³/s].

  • T0_schedule (array-like) – Outdoor temperature per step [°C].

  • I_DN_schedule (array-like | None) – Direct-normal irradiance per step [W/m²].

  • I_dH_schedule (array-like | None) – Diffuse-horizontal irradiance [W/m²].

  • T_sup_w_schedule (array-like | None) – Mains water supply temperature per step [°C]. If None, the constructor value T_sup_w is used for every step (backward-compatible).

  • tank_level_init (float) – Initial fractional tank level (0–1).

  • result_save_csv_path (str | None) – Optional CSV output path.

Returns:

Per-timestep result DataFrame.

Return type:

pd.DataFrame

postprocess_exergy(df)[source]

Compute ASHP-specific exergy variables.

Owns the full HP exergy topology:

  1. Refrigerant state-point exergy (CoolProp)

  2. Electricity = exergy (compressor, OU fan, UV)

  3. Air exergy (outdoor unit)

  4. Heat exchanger Carnot exergy (condenser, evaporator)

  5. Water exergy (tank inlet/outlet, mixing valve)

  6. Heat loss exergy, tank stored exergy

  7. Subsystem exergy via calc_exergy() protocol

  8. Component-level exergy destruction

  9. Exergetic efficiency metrics

Parameters:

df (pd.DataFrame) – Result DataFrame from analyze_dynamic().

Returns:

DataFrame with exergy columns appended.

Return type:

pd.DataFrame