Heat Pump and Refrigeration

The Heat Pump and refrigeration stack is the most specialised part of the OpenPinch codebase. It combines preprocessing of background cascades, thermodynamic cycle models, and black-box optimisation to screen direct and indirect integration opportunities.

Where To Start

Most users should still begin with the higher-level surfaces documented in Core API:

problem.target.direct_heat_pump(...)
problem.target.indirect_heat_pump(...)
problem.target.direct_refrigeration(...)
problem.target.indirect_refrigeration(...)

The modules on this page are the lower-level implementation layers behind those helpers.

Package Overview

Heat Pump and refrigeration targeting services.

Public HPR Entrypoints

Public entrypoint for heat pump and refrigeration targeting.

OpenPinch.services.heat_pump_integration.heat_pump_and_refrigeration_entry.compute_direct_heat_pump_or_refrigeration_target(zone, is_heat_pumping, args=None)[source]

Solve an explicit direct Heat Pump or refrigeration target for one zone.

Parameters:

zone (Zone)
is_heat_pumping (bool)
args (dict | None)

Return type:

DirectHeatPumpTarget | DirectRefrigerationTarget | None

OpenPinch.services.heat_pump_integration.heat_pump_and_refrigeration_entry.compute_indirect_heat_pump_or_refrigeration_target(zone, is_heat_pumping, args=None)[source]

Solve an indirect / utility system Heat Pump or refrigeration target.

Parameters:

zone (Zone)
is_heat_pumping (bool)
args (dict | None)

Return type:

IndirectHeatPumpTarget | IndirectRefrigerationTarget | None

Shared Preprocessing and Optimisation Helpers

Common helpers shared across heat pump targeting models.

Normalisation helpers for optimisation vectors used in HP targeting.

OpenPinch.services.heat_pump_integration.common.encoding.map_x_arr_to_T_arr(x, T_0, T_1)[source]

Map cumulative optimisation fractions onto descending stage temperatures.

Parameters:

x (ndarray)
T_0 (float)
T_1 (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_T_arr_to_x_arr(T_arr, T_0, T_1)[source]

Encode descending stage temperatures as cumulative optimisation fractions.

Parameters:

T_arr (ndarray)
T_0 (float)
T_1 (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_x_arr_to_DT_arr(x, T_arr, T_last)[source]

Scale optimisation fractions into temperature differences.

Parameters:

x (ndarray)
T_arr (ndarray)
T_last (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_DT_arr_to_x_arr(DT_arr, T_arr, T_last)[source]

Normalise temperature differences back into optimisation fractions.

Parameters:

DT_arr (ndarray)
T_arr (ndarray)
T_last (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_x_arr_to_Q_arr(x, Q_max)[source]

Scale optimisation fractions into heat duties.

Parameters:

x (ndarray)
Q_max (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_Q_arr_to_x_arr(Q_arr, Q_max)[source]

Normalise heat duties back into optimisation fractions.

Parameters:

Q_arr (ndarray)
Q_max (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_x_to_Q_amb(x, scale)[source]

Split one signed bounded ambient variable into hot and cold duties.

x is interpreted on the open interval (-1, 1) and decoded through atanh so the mapping stays close to linear around zero while ambient duties remain unbounded.

Parameters:

x (float)
scale (float)

Return type:

Tuple[float, float]

OpenPinch.services.heat_pump_integration.common.encoding.map_Q_amb_to_x(Q_amb_hot, Q_amb_cold, scale)[source]

Encode ambient duties back into one bounded signed decision variable.

Parameters:

Q_amb_hot (float)
Q_amb_cold (float)
scale (float)

Return type:

float

Preprocessing helpers for heat pump and refrigeration targeting.

OpenPinch.services.heat_pump_integration.common.preprocessing.construct_HPRTargetInputs(Q_hpr_target, T_vals, H_hot, H_cold, *, is_heat_pumping=True, zone_config, idx=0, debug=False)[source]

Prepare normalised background cascades and solver arguments for HPR targeting.

Parameters:

Q_hpr_target (float)
T_vals (ndarray)
H_hot (ndarray)
H_cold (ndarray)
is_heat_pumping (bool)
zone_config (Configuration)
idx (int)
debug (bool)

Return type:

HeatPumpTargetInputs

Shared helpers for heat pump and refrigeration targeting.

OpenPinch.services.heat_pump_integration.common.shared.solve_hpr_placement(f_obj, x0_ls, bnds, args)[source]

Run the configured multistart optimiser and post-process the best result.

Parameters:

f_obj (Callable)
x0_ls (list | float)
bnds (list)
args (HeatPumpTargetInputs)

Return type:

HPRBackendResult

OpenPinch.services.heat_pump_integration.common.shared.create_stream_collection_of_background_profile(T_vals, H_vals)[source]

Convert a temperature-enthalpy profile into piecewise stream segments.

Parameters:

T_vals (ndarray)
H_vals (ndarray)

Return type:

StreamCollection

OpenPinch.services.heat_pump_integration.common.shared.get_Q_vals_at_T_hpr_from_bckgrd_profile(T_hpr, T_vals, H_vals, *, is_cond=True)[source]

Read stage duties from a background profile at proposed HPR temperatures.

Parameters:

T_hpr (ndarray)
T_vals (ndarray)
H_vals (ndarray)
is_cond (bool)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.shared.compute_entropic_mean_temperature(T_arr, Q_arr, *, input_T_units='C')[source]

Return the entropic mean temperature for a distributed heat load.

Parameters:

T_arr (ndarray | list)
Q_arr (ndarray | list)
input_T_units (str)

Return type:

float

OpenPinch.services.heat_pump_integration.common.shared.calc_carnot_heat_pump_cop(T_h, T_l, eta_ii)[source]

Compute a Carnot-based heating COP with a second-law efficiency factor.

Parameters:

T_h (float | ndarray)
T_l (float | ndarray)
eta_ii (float)

Return type:

float | ndarray

OpenPinch.services.heat_pump_integration.common.shared.calc_carnot_heat_engine_eta(T_h, T_l, eta_ii)[source]

Compute a Carnot-based heat-engine efficiency with a second-law factor.

Parameters:

T_h (float | ndarray)
T_l (float | ndarray)
eta_ii (float)

Return type:

float | ndarray

OpenPinch.services.heat_pump_integration.common.shared.validate_vapour_hp_refrigerant_ls(num_stages, args)[source]

Return one refrigerant name per vapour-compression stage.

Parameters:

num_stages (int)
args (HeatPumpTargetInputs)

Return type:

list

OpenPinch.services.heat_pump_integration.common.shared.get_carnot_hpr_cycle_streams(T_cond, Q_cond, T_evap, Q_evap, args)[source]

Build one combined HPR utility stream collection for Carnot-cycle summaries.

Parameters:

T_cond (ndarray)
Q_cond (ndarray)
T_evap (ndarray)
Q_evap (ndarray)
args (HeatPumpTargetInputs)

Return type:

StreamCollection

OpenPinch.services.heat_pump_integration.common.shared.get_ambient_air_stream(Q_amb_hot=0.0, Q_amb_cold=0.0, args=None)[source]

Build ambient-air exchange streams implied by the solved HPR result.

Parameters:

Q_amb_hot (float)
Q_amb_cold (float)
args (HeatPumpTargetInputs)

Return type:

StreamCollection

OpenPinch.services.heat_pump_integration.common.shared.calc_hpr_obj(work, Q_ext_heat, Q_ext_cold, Q_hpr_target, heat_to_power_ratio=1.0, cold_to_power_ratio=0.0, penalty=0.0)[source]

Return the scalar screening objective used by HPR placement solvers.

Parameters:

work (float)
Q_ext_heat (float)
Q_ext_cold (float)
Q_hpr_target (float)
heat_to_power_ratio (float)
cold_to_power_ratio (float)
penalty (float)

Return type:

float

OpenPinch.services.heat_pump_integration.common.shared.evaluate_carnot_hpr_result(*, args, state, w_net, w_hpr, Q_cond_total, Q_evap_total, w_he=None, heat_recovery=None, cop_h=None, eta_he=None, Q_cond=None, Q_evap=None, Q_cond_he=None, Q_evap_he=None, penalty_terms=None, debug=False)[source]

Shared Carnot-family accounting, plotting, and result assembly.

Parameters:

args (HeatPumpTargetInputs)
state (HPRParsedState)
w_net (float)
w_hpr (float | list | ndarray)
Q_cond_total (ndarray)
Q_evap_total (ndarray)
w_he (float | list | ndarray | None)
heat_recovery (float | list | ndarray | None)
cop_h (float | list | ndarray | None)
eta_he (float | list | ndarray | None)
Q_cond (ndarray | None)
Q_evap (ndarray | None)
Q_cond_he (ndarray | None)
Q_evap_he (ndarray | None)
penalty_terms (Any)
debug (bool)

Return type:

HPRBackendResult

OpenPinch.services.heat_pump_integration.common.shared.evaluate_vapour_hpr_result(*, args, state, work, work_arr, Q_heat, Q_cool, cop_h, hpr_streams, model=None, penalty_terms=None, dT_subcool=None, dT_superheat=None, debug=False)[source]

Shared simulated-vapour accounting, plotting, and result assembly.

Parameters:

args (HeatPumpTargetInputs)
state (HPRParsedState)
work (float)
work_arr (float | list | ndarray)
Q_heat (ndarray)
Q_cool (ndarray)
cop_h (float)
hpr_streams (StreamCollection)
model (Any)
penalty_terms (Any)
dT_subcool (ndarray | None)
dT_superheat (ndarray | None)
debug (bool)

Return type:

HPRBackendResult

OpenPinch.services.heat_pump_integration.common.shared.plot_multi_hp_profiles_from_results(T_hot=None, H_hot=None, T_cold=None, H_cold=None, hpr_hot_streams=None, hpr_cold_streams=None, idx=0, title=None)[source]

Plot background source/sink profiles alongside solved HPR cycle streams.

Parameters:

T_hot (ndarray)
H_hot (ndarray)
T_cold (ndarray)
H_cold (ndarray)
hpr_hot_streams (StreamCollection)
hpr_cold_streams (StreamCollection)
idx (int)
title (str)

Return type:

plotly.graph_objects.Figure

OpenPinch.services.heat_pump_integration.common.shared.get_process_heat_cascade(hot_streams=None, cold_streams=None, all_streams=None, is_shifted=True, known_heat_recovery=None, extra_T_intervals=None, is_full_analysis=False, idx=None)[source]

Prepare, calculate, and analyse the problem table for given streams.

Parameters:

hot_streams (StreamCollection)
cold_streams (StreamCollection)
all_streams (StreamCollection)
is_shifted (bool)
known_heat_recovery (float)
extra_T_intervals (list)
is_full_analysis (bool)
idx (int | None)

Return type:

ProblemTable

OpenPinch.services.heat_pump_integration.common.shared.get_utility_heat_cascade(T_int_vals, hot_utilities=None, cold_utilities=None, is_shifted=True, idx=None)[source]

Prepare and calculate the utility heat cascade for a utility set.

Parameters:

T_int_vals (ndarray)
hot_utilities (StreamCollection)
cold_utilities (StreamCollection)
is_shifted (bool)
idx (int | None)

Return type:

ProblemTableUpdateKwargs

OpenPinch.services.heat_pump_integration.common.shared.g_ineq_penalty(g, *, eta=0.01, rho=10, form='square')[source]

Return a penalty value for an inequality-constraint residual.

Parameters:

g (float | list | ndarray)
eta (float)
rho (float)
form (str)

Return type:

float64

Cycle Optimisation Modules

Brayton HP targeting.

OpenPinch.services.heat_pump_integration.cycles.brayton.optimise_brayton_heat_pump_placement(args)[source]

Optimise a single-stage Brayton Heat Pump placement against the background.

Parameters:: args (HeatPumpTargetInputs)
Return type:: None