Refrigerant & thermodynamics

CoolProp-backed state-point helpers, cycle-level analysis (compression ratio, isentropic efficiency, COP), and COP correlations.

Refrigerant state points

Refrigerant cycle calculations and optimization.

tmhp.refrigerant.calc_ref_state(T_evap_K, T_cond_K, refrigerant, eta_cmp_isen, mode='heating', dT_superheat=0.0, dT_subcool=0.0, is_active=True)[source]

Compute the four thermodynamic state points of the refrigerant cycle.

The vapour-compression cycle has four canonical state points:

  • State 1 (cmp_in): compressor inlet — low-pressure superheated vapour at the evaporator outlet.

  • State 2 (cmp_out): compressor outlet — high-pressure superheated vapour at the condenser inlet.

  • State 3 (exp_in): expansion-valve inlet — high-pressure subcooled liquid at the condenser outlet.

  • State 4 (exp_out): expansion-valve outlet — low-pressure two-phase mixture at the evaporator inlet.

Keys in the returned dict are always assigned by the physical compressor / expander ports; the mode argument is preserved verbatim under the "mode" key but does not change the key naming.

Note

Whether a given heat exchanger acts as the evaporator or the condenser in heating versus cooling mode is decided by the caller (_calc_state), which chooses T_evap_K and T_cond_K accordingly before calling this function.

Parameters:

  • T_evap_K (float)

  • T_cond_K (float)

  • refrigerant (str)

  • eta_cmp_isen (float | Callable)

  • mode (str)

  • dT_superheat (float)

  • dT_subcool (float)

  • is_active (bool)

Return type:

dict[str, Any]

tmhp.refrigerant.create_lmtd_constraints()[source]

Create LMTD-based constraint functions for cycle optimization.

Optimization requires that the heat transfer calculated by LMTD matches the heat transferred by the refrigerant cycle.

Returns:

Tuple of constraint functions (constraint_tank, constraint_hx).

Return type:

tuple[Any, Any]

tmhp.refrigerant.find_ref_loop_optimal_operation(simulator_func, refrigerant, load_W, initial_guess, bounds, constraint_funcs=None)[source]

Find the optimal operation point for the refrigerant loop.

Minimizes compressor power while satisfying target load and LMTD constraints.

Parameters:

  • simulator_func (callable) – Function that takes [dT_ref_HX, dT_ref_tank] and returns a perf dict.

  • refrigerant (str) – Refrigerant name.

  • load_W (float) – Target heat load [W].

  • initial_guess (list[float]) – Initial guess for [dT_evap, dT_cond].

  • bounds (list[tuple[float, float]]) – Bounds for [dT_evap, dT_cond].

  • constraint_funcs (list[callable], optional) – List of constraint functions. Each takes perf and returns a value that should be 0.

Returns:

Optimal performance dictionary, or None if optimization fails.

Return type:

dict[str, Any] | None

Cycle analysis

Thermodynamic property and exergy calculations.

tmhp.thermodynamics.calc_energy_flow(G, T, T0)[source]

Calculate energy flow rate.

Parameters:

  • G (float or pd.Series) – Heat capacity flow rate (mass_flow * Cp) [W/K].

  • T (float or pd.Series) – Current temperature [K].

  • T0 (float or pd.Series) – Reference/dead state temperature [K].

Returns:

Energy flow rate [W].

Return type:

float or pd.Series

tmhp.thermodynamics.calc_exergy_flow(G, T, T0)[source]

Calculate exergy flow rate.

Parameters:

  • G (float or pd.Series) – Heat capacity flow rate (mass_flow * Cp) [W/K].

  • T (float or pd.Series) – Current temperature [K].

  • T0 (float or pd.Series) – Reference/dead state temperature [K].

Returns:

Exergy flow rate [W].

Return type:

float or pd.Series

tmhp.thermodynamics.calc_refrigerant_exergy(df, ref, T0_K, P0=101325)[source]

Calculate refrigerant state-point exergy using pre-computed properties.

Uses the entropy (s_ref_*) and enthalpy (h_ref_*) columns already present in df (produced by calc_ref_state) to compute specific exergy and exergy flow rate for each refrigerant state point.

Dead-state properties (h0, s0) are evaluated at (T0, P0) for the given refrigerant using CoolProp (vectorized via unique T0 values).

Parameters:

  • df (pd.DataFrame) – DataFrame containing pre-computed enthalpy h_ref_* [J/kg], entropy s_ref_* [J/(kg·K)], and mass-flow m_dot_ref [kg/s] columns.

  • ref (str) – CoolProp refrigerant identifier (e.g. 'R410A').

  • T0_K (pd.Series) – Dead-state (environment) temperature per row [K].

  • P0 (float) – Dead-state pressure [Pa] (default 101325).

Returns:

df with columns added per state point: x_ref_{name} [J/kg], X_ref_{name} [W].

Return type:

pd.DataFrame

Notes

  • Exergy equation: x = (h − h0) − T0·(s − s0) [J/kg]

  • Exergy flow: X = ṁ · x [W]

  • Rows with NaN enthalpy/entropy propagate NaN naturally.

tmhp.thermodynamics.convert_electricity_to_exergy(df)[source]

Copy all electricity columns (E_*) to exergy columns (X_*).

Electrical energy is 100 %% pure exergy, so X = E for all electricity-consumption columns.

The function searches for columns matching the pattern E_xxx [W] and creates corresponding X_xxx [W] columns.

Parameters:

df (pd.DataFrame) – DataFrame with E_xxx [W] columns.

Returns:

df with X_xxx [W] columns added.

Return type:

pd.DataFrame

tmhp.thermodynamics.generate_entropy_exergy_term(fluid, T, P, Q, T0, P0, phase='gas')[source]

Calculate entropy, enthalpy, and exergy.

Parameters:

  • fluid (str) – Fluid name.

  • T (float) – Temperature [K].

  • P (float) – Pressure [Pa].

  • Q (float) – Quality (0 to 1).

  • T0 (float) – Dead state temperature [K].

  • P0 (float) – Dead state pressure [Pa].

  • phase (Literal['gas', 'liquid', 'twophase'], optional) – Fluid phase. Default is ‘gas’.

Returns:

Entropy [J/kg-K], Enthalpy [J/kg], Exergy [J/kg].

Return type:

tuple[float, float, float]

COP correlations

Heat pump Coefficient of Performance (COP) models.

Provides empirical COP correlations for: - Air source heat pumps (cooling and heating modes) - Ground source heat pumps (modified Carnot model)

tmhp.cop.calc_ASHP_cooling_COP(T_a_int_out, T_a_ext_in, Q_r_int, Q_r_max, COP_ref)[source]

Calculate the Coefficient of Performance (COP) for an Air Source Heat Pump (ASHP) in cooling mode.

Reference: https://publications.ibpsa.org/proceedings/bs/2023/papers/bs2023_1118.pdf

Parameters:

  • T_a_int_out (float) – Indoor air temperature [K]

  • T_a_ext_in (float) – Outdoor air temperature [K]

  • Q_r_int (float) – Indoor heat load [W]

  • Q_r_max (float) – Maximum cooling capacity [W]

  • COP_ref (float) – Reference COP at standard conditions

Returns:

COP value

Return type:

float

Note

COP is calculated based on: - PLR: Part Load Ratio - EIR: Energy input to cooling output ratio

tmhp.cop.calc_ASHP_heating_COP(T0, Q_r_int, Q_r_max)[source]

Calculate the Coefficient of Performance (COP) for an Air Source Heat Pump (ASHP) in heating mode.

Reference: https://www.mdpi.com/2071-1050/15/3/1880

Parameters:

  • T0 (float) – Environmental temperature [K]

  • Q_r_int (float) – Indoor heat load [W]

  • Q_r_max (float) – Maximum heating capacity [W]

Returns:

COP value

Return type:

float

Note

COP is calculated based on PLR (Part Load Ratio).

tmhp.cop.calc_GSHP_COP(T_a_iu_in_K, T_f_out_K, dV_a_ratio, mode)[source]

Calculate COP for a Ground Source Heat Pump.

Uses the EnergyPlus Coil:*:WaterToAir:EquationFit model (Equation-Fit Method).

References

EnergyPlus Engineering Reference, Ch. 16.5.10.2 (Eq. 16.412–16.418, Tang 2005). Dataset: TCH072_GLHP (ClimateMaster 6-ton, Ground Loop HP), source: EnergyPlus/datasets/WaterToAirHeatPumps.idf.

Rated conditions (from IDF comment, 15% methanol antifreeze):

  • Cooling: 70.29 kBtu/h @ 77 °F (25 °C) entering water, EER = 14.35

  • Heating: 56.14 kBtu/h @ 32 °F (0 °C) entering water, COP = 3.42

Parameters:

  • T_a_iu_in_K (float) – Indoor air inlet dry-bulb temperature [K] (= T_a_room). For cooling, internally converted to wet-bulb (T_wb) via CoolProp assuming RH = 50%.

  • T_f_out_K (float) – Source-side inlet water temperature [K] — water returning from the borehole to the heat pump (T_w,in in EnergyPlus notation).

  • dV_a_ratio (float) – Load-side air volumetric flow ratio: V_a / V_a_ref [-] V_a_ref = Q_rated / (rho_a * c_a * 10K) [m³/s]

  • mode (str) – “cooling” or “heating”

  • Units

  • -----

  • Temperatures (K)

  • rates (Flow)

  • Heat/Power (W)

Returns:

COP (dimensionless). Polynomial model is unconditionally stable— no ValueError on temperature inversion.

Return type:

float