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)

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)

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

The targeting parsers decode optimiser vectors into temperatures, ambient duties, base duty scales, split vectors, and process availability arrays. The aggregate backend classes then allocate requested duties from base/split coordinates, clip those requests to availability, and add any excess to the penalty term. Leaf physical unit models receive only concrete model duties. Simulated vapour-compression backends then combine the HPR streams with the background and ambient streams into one residual GCC. The pocket-free GCC end points provide residual external utilities for operating-cost accounting; cycle penalties remain separate feasibility terms.

Common helpers shared across heat pump targeting models.

Normalisation helpers for optimisation vectors used in HP targeting.

class OpenPinch.services.heat_pump_integration.common.encoding.DutyAllocation(Q_base, Q_request, Q_available, Q_model, Q_excess)

Bases: object

Decoded stage-duty allocation from one base duty and split vector.

Parameters:

• Q_base (float)

• Q_request (ndarray)

• Q_available (ndarray)

• Q_model (ndarray)

• Q_excess (ndarray)

OpenPinch.services.heat_pump_integration.common.encoding.allocate_stage_duties(Q_base, x_split, Q_available)

Decode and availability-limit per-stage model duties.

Parameters:

• Q_base (float)

• x_split (ndarray)

• Q_available (ndarray)

Return type:

DutyAllocation

OpenPinch.services.heat_pump_integration.common.encoding.decode_duty_splits(x_split, Q_base)

Decode stick-breaking split fractions into nonnegative stage duties.

Parameters:

• x_split (ndarray)

• Q_base (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.encode_base_and_duty_splits(Q_request, Q_limit)

Encode a seed duty vector into base-duty scale and split fractions.

Parameters:

• Q_request (ndarray)

• Q_limit (float)

Return type:

tuple[float, float, ndarray]

OpenPinch.services.heat_pump_integration.common.encoding.encode_duty_splits(Q_request, Q_base)

Encode nonnegative stage duties as bounded stick-breaking fractions.

Parameters:

• Q_request (ndarray)

• Q_base (float)

Return type:

ndarray

OpenPinch.services.heat_pump_integration.common.encoding.map_x_arr_to_T_arr(x, T_0, T_1)

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)

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)

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)

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)

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)

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)

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)

Encode ambient duties back into one bounded signed decision variable.

Parameters:

• Q_amb_hot (float)

• Q_amb_cold (float)

• scale (float)

Return type:

float

OpenPinch.services.heat_pump_integration.common.encoding.require_stage_duty_allocation(*, Q_base, x_split, Q_available, duty_name)

Validate and allocate one base/split/availability duty input set.

Parameters:

• Q_base (float)

• x_split (ndarray | None)

• Q_available (ndarray | None)

• duty_name (str)

Return type:

DutyAllocation

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, config, period_idx=0, debug=False)

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)

• config (Configuration)

• period_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)

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.solve_hpr_multiperiod_placement(f_obj, x0_ls, bnds, args)

Optimise one shared HPR vector against all prepared period cases.

Parameters:

• f_obj (Callable)

• x0_ls (list | float)

• bnds (list)

• args (MultiPeriodHPRTargetInputs)

Return type:

HPRBackendResult

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

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)

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)

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.get_carnot_hpr_cycle_streams(T_cond, Q_cond, T_evap, Q_evap, args)

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_Q_vals_at_T_hpr_from_bckgrd_profile(T_hpr, T_vals, H_vals, *, is_cond=True)

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.validate_vapour_hp_refrigerant_ls(num_stages, args)

Return one refrigerant name per vapour-compression stage.

Parameters:

• num_stages (int)

• args (HeatPumpTargetInputs)

Return type:

list

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)

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.calc_simulated_hpr_annualized_costs(*, work, work_arr, Q_ext_heat, Q_ext_cold, hpr_streams, hx_units, penalty_power_equivalent, args)

Return unit-aware annualized cost accounting for simulated HPR candidates.

Parameters:

• work (float)

• work_arr (ndarray | None)

• Q_ext_heat (float)

• Q_ext_cold (float)

• hpr_streams (StreamCollection)

• hx_units (int)

• penalty_power_equivalent (float)

• args (HeatPumpTargetInputs)

Return type:

SimulatedHPRAnnualizedCostAccounting

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)

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 (ndarray | None)

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

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

Parameters:

• args (HeatPumpTargetInputs)

• state (HPRParsedState)

• work (float)

• work_arr (ndarray)

• Q_heat (ndarray)

• Q_cool (ndarray)

• cop_h (float)

• hpr_streams (StreamCollection)

• model (Any)

• penalty_terms (list[float] | None)

• 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, period_idx=0, title=None)

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)

• period_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, period_idx=None)

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)

• period_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, period_idx=None)

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)

• period_idx (int | None)

Return type:

ProblemTableUpdateKwargs

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

Return a penalty value for an inequality-constraint residual.

Parameters:

• g (float | list | ndarray)

• eta (float)

• rho (float)

• form (str)

Return type:

float64

HPR Schemas

class OpenPinch.lib.schemas.hpr.HeatPumpTargetInputs(*, hpr_type, Q_hpr_target, Q_heat_max, Q_cool_max, z_amb_hot, z_amb_cold, dt_range_max, T_hot, H_hot, T_cold, H_cold, n_cond, n_evap, n_mvr, eta_comp, eta_mvr_comp, eta_motor, eta_exp, dtcont_hp, dt_hp_ihx, dt_cascade_hx, dt_phase_change, heat_to_power_ratio, cold_to_power_ratio, ele_price, annual_op_time, discount_rate, serv_life, hpr_comp_fixed_cost, hpr_comp_variable_cost, hpr_comp_cost_exp, hpr_hx_fixed_cost, hpr_hx_variable_cost, hpr_hx_cost_exp, is_heat_pumping, max_multi_start, T_env, dt_env_cont, eta_ii_hpr_carnot, eta_ii_he_carnot, refrigerant_ls, mvr_fluid_ls, do_refrigerant_sort, initialise_simulated_cycle, allow_integrated_expander, bckgrd_hot_streams, bckgrd_cold_streams, bb_minimiser, eta_penalty, rho_penalty, period_idx=0, debug)

Bases: BaseModel

Parameter bundle for heat pump and refrigeration targeting routines.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

• hpr_type (str)

• Q_hpr_target (float)

• Q_heat_max (float)

• Q_cool_max (float)

• z_amb_hot (ndarray)

• z_amb_cold (ndarray)

• dt_range_max (float)

• T_hot (ndarray)

• H_hot (ndarray)

• T_cold (ndarray)

• H_cold (ndarray)

• n_cond (int)

• n_evap (int)

• n_mvr (int)

• eta_comp (float)

• eta_mvr_comp (float)

• eta_motor (float)

• eta_exp (float)

• dtcont_hp (float)

• dt_hp_ihx (float)

• dt_cascade_hx (float)

• dt_phase_change (float)

• heat_to_power_ratio (float)

• cold_to_power_ratio (float)

• ele_price (float)

• annual_op_time (float)

• discount_rate (float)

• serv_life (float)

• hpr_comp_fixed_cost (float)

• hpr_comp_variable_cost (float)

• hpr_comp_cost_exp (float)

• hpr_hx_fixed_cost (float)

• hpr_hx_variable_cost (float)

• hpr_hx_cost_exp (float)

• is_heat_pumping (bool)

• max_multi_start (int)

• T_env (float)

• dt_env_cont (float)

• eta_ii_hpr_carnot (float)

• eta_ii_he_carnot (float)

• refrigerant_ls (List[str])

• mvr_fluid_ls (List[str])

• do_refrigerant_sort (bool)

• initialise_simulated_cycle (bool)

• allow_integrated_expander (bool)

• bckgrd_hot_streams (StreamCollection)

• bckgrd_cold_streams (StreamCollection)

• bb_minimiser (str)

• eta_penalty (float)

• rho_penalty (float)

• period_idx (int)

• debug (bool)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.lib.schemas.hpr.HPRBackendResult(*, obj, utility_tot, w_net, Q_ext_heat, Q_ext_cold, hpr_operating_cost=None, hpr_capital_cost=None, hpr_annualized_capital_cost=None, hpr_total_annualized_cost=None, hpr_compressor_capital_cost=None, hpr_heat_exchanger_capital_cost=None, feasibility_penalty=0.0, Q_amb_hot, Q_amb_cold, success=True, w_hpr=None, w_he=None, heat_recovery=None, cop_h=None, eta_he=None, amb_streams=None, T_cond=None, T_evap=None, Q_cond=None, Q_evap=None, Q_cond_he=None, Q_evap_he=None, dT_subcool=None, dT_superheat=None, T_comp_out=None, dT_gc=None, dT_comp=None, Q_heat=None, Q_cool=None, failure_reason=None, artifacts=None, period_outputs=None, weighted_output=None, design_vector=None, period_ids=None, period_weights=None)

Bases: BaseModel

Internal backend result before public schema validation.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

• obj (float)

• utility_tot (float)

• w_net (float | list | ndarray)

• Q_ext_heat (float)

• Q_ext_cold (float)

• hpr_operating_cost (Any)

• hpr_capital_cost (Any)

• hpr_annualized_capital_cost (Any)

• hpr_total_annualized_cost (Any)

• hpr_compressor_capital_cost (Any)

• hpr_heat_exchanger_capital_cost (Any)

• feasibility_penalty (float)

• Q_amb_hot (float)

• Q_amb_cold (float)

• success (bool)

• w_hpr (float | list | ndarray | None)

• w_he (float | list | ndarray | None)

• heat_recovery (float | list | ndarray | None)

• cop_h (float | list | ndarray | None)

• eta_he (float | list | ndarray | None)

• amb_streams (StreamCollection | None)

• T_cond (ndarray | None)

• T_evap (ndarray | None)

• Q_cond (ndarray | None)

• Q_evap (ndarray | None)

• Q_cond_he (ndarray | None)

• Q_evap_he (ndarray | None)

• dT_subcool (ndarray | None)

• dT_superheat (ndarray | None)

• T_comp_out (ndarray | None)

• dT_gc (ndarray | None)

• dT_comp (ndarray | None)

• Q_heat (ndarray | None)

• Q_cool (ndarray | None)

• failure_reason (str | None)

• artifacts (HPRThermoArtifacts | None)

• period_outputs (dict[str, Any] | None)

• weighted_output (Any)

• design_vector (ndarray | None)

• period_ids (list[str] | None)

• period_weights (list[float] | None)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OpenPinch.lib.schemas.hpr.SimulatedHPRAnnualizedCostAccounting(*, hpr_operating_cost, hpr_capital_cost, hpr_annualized_capital_cost, hpr_total_annualized_cost, hpr_compressor_capital_cost, hpr_heat_exchanger_capital_cost, feasibility_penalty)

Bases: BaseModel

Unit-aware annualized cost accounting for simulated HPR candidates.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

• hpr_operating_cost (Value)

• hpr_capital_cost (Value)

• hpr_annualized_capital_cost (Value)

• hpr_total_annualized_cost (Value)

• hpr_compressor_capital_cost (Value)

• hpr_heat_exchanger_capital_cost (Value)

• feasibility_penalty (Value)

model_config = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Cycle Optimisation Services

These modules place or size Heat Pump and refrigeration cycle models against prepared cascade data. The detailed cycle physics live in the unit_models modules documented in Domain Classes.

Only the current public cycle names are routed here, for example "Cascade Carnot cycles", "Parallel Carnot cycles", and "Parallel vapour compression cycles".

Cycle-specific heat pump optimisation models.

Brayton HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.brayton.optimise_brayton_heat_pump_placement(args)

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

Parameters:

args (HeatPumpTargetInputs)

Return type:

None

Cascade vapour-compression HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.cascade_vapour_compression.optimise_cascade_heat_pump_placement(args)

Optimise a cascade vapour-compression placement for the prepared HPR case.

Parameters:

args (HeatPumpTargetInputs)

Return type:

HPRBackendResult

Parallel Carnot HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.parallel_carnot.optimise_parallel_carnot_heat_pump_placement(args)

Optimise parallel simple Carnot stages for a screening-level HPR solve.

Parameters:

args (HeatPumpTargetInputs)

Return type:

HPRBackendResult

Parallel vapour-compression HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.parallel_vapour_compression.optimise_parallel_heat_pump_placement(args)

Optimise multiple parallel vapour-compression stages for the HPR case.

Parameters:

args (HeatPumpTargetInputs)

Return type:

HPRBackendResult

Cascade Carnot HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.cascade_carnot.optimise_cascade_carnot_heat_pump_placement(args)

Optimise cascade Carnot stages for the prepared HPR case.

Parameters:

args (HeatPumpTargetInputs)

Return type:

HPRBackendResult

Vapour-compression plus MVR cascade HP targeting.

OpenPinch.services.heat_pump_integration.targeting_services.vapour_compression_mvr.optimise_vapour_compression_mvr_heat_pump_placement(args)

Optimise a VC low-stage plus MVR high-stage placement.

Parameters:

args (HeatPumpTargetInputs)

Return type:

HPRBackendResult