Analysis Package

The analysis package contains the numerical workflow that turns validated inputs into pinch targets, utility allocations, and graph-ready composite curve data. The modules are designed so that the high-level service layer can use them in sequence, but they can also be called directly for custom studies or research workflows.

Pipeline Overview

The analysis stack typically runs in this order:

  1. OpenPinch.services.input_data_processing.data_preparation validates options, normalises the zone hierarchy, and constructs Zone, Stream, and StreamCollection objects.

  2. OpenPinch.services.services_entry selects the orchestration path used by the high-level service layer and PinchProblem.target.* helpers.

  3. OpenPinch.services.common.problem_table_analysis builds the shifted and real temperature problem tables used throughout the rest of the workflow.

  4. OpenPinch.services.direct_heat_integration.direct_integration_entry computes direct integration targets for unit-operation and process zones.

  5. OpenPinch.services.indirect_heat_integration.indirect_integration_entry aggregates solved subzones into site-style indirect integration targets when the hierarchy requires it.

  6. OpenPinch.services.common.graph_data converts solved tables and targets into serialisable graph payloads for reporting and Streamlit visualisation.

Service Package Map

Public service-layer entry points and reusable targeting helpers.

Service-layer orchestration helpers for prepared OpenPinch workflows.

OpenPinch.services.services_entry.data_preprocessing_service(input_data, project_name='Site')[source]

Validate raw input data and construct the in-memory zone tree.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.direct_heat_integration_service(zone, args=None)[source]

Run direct heat integration targeting for a prepared zone.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.indirect_heat_integration_service(zone, args=None)[source]

Run indirect heat integration targeting for a prepared zone.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.direct_heat_pump_service(zone, args=None)[source]

Run direct Heat Pump targeting after ensuring a base DI target exists.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.indirect_heat_pump_service(zone, args=None)[source]

Run indirect Heat Pump targeting after ensuring a base TS target exists.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.direct_refrigeration_service(zone, args=None)[source]

Run direct refrigeration targeting after ensuring a base DI target exists.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.indirect_refrigeration_service(zone, args=None)[source]

Run indirect refrigeration targeting after ensuring a base TS target exists.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.power_cogeneration_service(zone, args=None)[source]

Post-process one compatible target in TS -> IHP -> IR -> DHP -> DR -> DI order.

Parameters:
Return type:

Zone

OpenPinch.services.services_entry.area_cost_targeting_service(zone, args=None)[source]

Refresh direct integration targets before area and cost reporting.

Parameters:
Return type:

Zone

Preparation and Zone Construction

These functions are the bridge between external schema inputs and the internal object model.

Input validation and zone-tree construction services.

Construct validated Zone trees and attach stream/utility data.

OpenPinch.services.input_data_processing.data_preparation.prepare_problem(streams=None, utilities=None, options=None, project_name='Site', zone_tree=None)[source]

Build the top-level zone hierarchy for analysis.

Parameters:
Return type:

Zone

Direct and Indirect Targeting Entrypoints

These modules own the top-level targeting workflows once a zone tree has been constructed.

  • Direct integration works on process streams within a zone and applies Problem Table analysis, utility targeting, optional Heat Pump targeting, and optional cost/exergy add-ons.

  • Indirect integration aggregates the net thermal behaviour of solved subzones and applies utility-to-utility balancing for Total Site studies.

  • Lower-level Heat Pump and refrigeration screening for both routes is centralised in OpenPinch.services.heat_pump_integration.heat_pump_and_refrigeration_entry.

Direct heat integration entry point for process and unit-level targeting.

OpenPinch.services.direct_heat_integration.direct_integration_entry.compute_direct_integration_targets(zone, args=None)[source]

Populate a Zone with detailed direct heat integration pinch targets.

The function aggregates Problem Table calculations, multi-utility targeting, pinch temperature detection, and graph preparation. Results are cached on the provided zone and used later by site and regional aggregation routines.

Parameters:
Return type:

DirectIntegrationTarget

Indirect heat-integration entry point for total site style targeting.

The routines in this module aggregate process-level direct-integration outputs from subzones, construct site process/utility cascades, and calculate net utility balances after feasible inter-zone heat recovery.

OpenPinch.services.indirect_heat_integration.indirect_integration_entry.compute_total_subzone_utility_targets(zone, args=None)[source]

Sums and records zonal targets.

Parameters:
Return type:

TotalProcessTarget

OpenPinch.services.indirect_heat_integration.indirect_integration_entry.compute_indirect_integration_targets(zone, args=None)[source]

Compute indirect integration targets for an aggregated zone.

The routine assumes the relevant child zones have already been solved for direct integration. It then sums subzone targets, builds site-level net stream cascades, performs utility-to-utility balancing, and records the resulting Total Site target on zone before returning it.

Parameters:
Return type:

TotalSiteTarget

Problem Tables, Utility Allocation, and Graph Data

These modules implement the numerical building blocks that the entry-point workflows depend on.

Problem Table generation and cascade utilities for pinch analysis.

This module collects the vectorised implementations of the temperature interval problem table, cascade shifting logic, and helper routines used when deriving zonal targets and plotting data for composite curves.

OpenPinch.services.common.problem_table_analysis.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:
Return type:

ProblemTable

OpenPinch.services.common.problem_table_analysis.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:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.problem_table_analysis.create_problem_table_with_t_int(streams=None, is_shifted=True, extra_T_intervals=None, idx=None)[source]

Return a problem table populated with ordered unique temperature intervals.

Parameters:
Return type:

ProblemTable

OpenPinch.services.common.problem_table_analysis.problem_table_algorithm(pt, hot_streams=None, cold_streams=None, is_shifted=True, idx=None)[source]

Fast calculation of the problem table using vectorized cascade formulas.

Parameters:
Return type:

ProblemTable

OpenPinch.services.common.problem_table_analysis.get_heat_recovery_target_from_pt(pt)[source]

Compute the heat-recovery target implied by a solved problem table.

Parameters:

pt (ProblemTable) – Problem table with populated H_hot and H_net columns.

Returns:

Maximum direct heat recovery for the analysed zone.

Return type:

float

OpenPinch.services.common.problem_table_analysis.set_zonal_targets(pt, pt_real)[source]

Assign thermal targets and integration degree from process-table data.

Parameters:
Return type:

dict

Target multiple utilities over a heating or cooling profile from the pinch.

OpenPinch.services.common.utility_targeting.target_utilities_for_load_profiles(*, hot_utilities, cold_utilities, T_vals, H_net_cold, H_net_hot, pinch_idx, is_real_temperatures=False, idx=None)[source]

Targets multiple utilities for precomputed hot- and cold-side load profiles.

Parameters:
Return type:

Tuple[StreamCollection, StreamCollection]

OpenPinch.services.common.utility_targeting.get_utility_targets(pt, pt_real=None, hot_utilities=None, cold_utilities=None, is_direct_integration=True, idx=None)[source]

Target utility usage and compute GCC variants for a zone.

Parameters:

  • pt (ProblemTable) – Shifted and real problem tables used for constructing composite curves.

  • pt_real (ProblemTable) – Shifted and real problem tables used for constructing composite curves.

  • hot_utilities (StreamCollection) – Candidate utility collections that will be targeted across temperature intervals.

  • cold_utilities (StreamCollection) – Candidate utility collections that will be targeted across temperature intervals.

  • is_direct_integration (bool) – When True (default) the function assumes the zone represents a process area and applies additional targeting logic appropriate for that context.

  • idx (int | None)

Returns:

Updated (pt, pt_real, hot_utilities, cold_utilities) collections with derived profiles embedded.

Return type:

tuple

Determine various forms of the grand composite curve.

OpenPinch.services.common.gcc_manipulation.get_additional_GCCs(pt, do_vert_cc_calc=False, do_assisted_ht_calc=False, assisted_ht_dt_cut=10.0, assisted_ht_dt_cut_min=0.0, is_process_stream=True)[source]

Populate derived GCC variants used by utility and integration targeting.

Parameters:

  • pt (ProblemTable) – Problem table containing baseline H_net and Composite Curve columns.

  • do_vert_cc_calc (bool) – Enable vertical heat-transfer transformation for assisted integration.

  • do_assisted_ht_calc (bool) – Enable pocket extraction and assisted heat-transfer GCC adjustments.

  • assisted_ht_dt_cut (float)

  • assisted_ht_dt_cut_min (float)

  • is_process_stream (bool)

Returns:

Updated problem table with additional GCC-related columns.

Return type:

ProblemTable

OpenPinch.services.common.gcc_manipulation.get_GCC_without_pockets(pt, col_H_NP=ProblemTableLabel.H_NET_NP, col_H=ProblemTableLabel.H_NET)[source]

Flatten GCC pockets by inserting breakpoints so the profile becomes monotonic.

Parameters:
Return type:

Tuple[ProblemTable, ProblemTable]

OpenPinch.services.common.gcc_manipulation.get_GCC_with_partial_pockets(T_col, h_net, h_net_np, dt_cut=10, dt_cut_min=0)[source]

Return GCC updates for the assisted profile after partially cutting pockets.

Parameters:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.gcc_manipulation.get_GCC_with_vertical_heat_transfer(T_col, h_cold, h_hot, h_net)[source]

Return the extreme GCC with vertical heat transfer on the composite curves.

Parameters:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.gcc_manipulation.get_GCC_needing_utility(T_col, h_net)[source]

Return the actual GCC.

Parameters:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.gcc_manipulation.get_GGC_pockets(T_col, h_net, h_net_np)[source]

Store GCC pocket contribution.

This is the difference between the real and pocket-free GCC profiles.

Parameters:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.gcc_manipulation.get_seperated_gcc_heat_load_profiles(T_col, H_net, rcp_net=None, is_process_stream=True)[source]

Determine the net required heating or cooling profile from the GCC.

Parameters:
Return type:

ProblemTableUpdateKwargs

Graph construction helpers for composite curves and related plots.

OpenPinch.services.common.graph_data.get_output_graph_data(zone, graph_sets=None)[source]

Returns Json data points for each process.

Parameters:
Return type:

dict

Advanced Add-On Analyses

The modules below expose specialised calculations that sit on top of the core Problem Table workflow. Some are used automatically when corresponding options are enabled, while others are better viewed as expert-level helper libraries.

The Heat Pump and refrigeration stack is documented separately in Heat Pump and Refrigeration because it spans a dedicated package with multiple cycle optimisers and helper modules. The main low-level entrypoints remain compute_direct_heat_pump_or_refrigeration_target(...) and compute_indirect_heat_pump_or_refrigeration_target(...) in OpenPinch.services.heat_pump_integration.heat_pump_and_refrigeration_entry.

Area targeting methods.

OpenPinch.services.common.capital_cost_and_area_targeting.get_balanced_CC(T_col, H_hot, H_cold, H_hot_ut, H_cold_ut, dT_vals=None, RCP_hot=None, RCP_cold=None, RCP_hot_ut=None, RCP_cold_ut=None)[source]

Create the balanced composite curve using process and utility streams.

Parameters:
Return type:

ProblemTableUpdateKwargs

OpenPinch.services.common.capital_cost_and_area_targeting.get_capital_cost_targets(area, num_units, zone_config)[source]

Estimate equipment and annualized capital costs from area/unit targets.

Parameters:

  • area (float) – Total heat-transfer area target from balanced composite curves.

  • num_units (int) – Minimum exchanger count estimate for the same targeting scenario.

  • zone_config (Configuration) – Active configuration containing fixed/variable cost coefficients, capital exponent, discount rate, and service life assumptions.

Returns:

(capital_cost, annual_capital_cost).

Return type:

tuple[float, float]

OpenPinch.services.common.capital_cost_and_area_targeting.get_area_targets(T_vals, H_hot_bal, H_cold_bal, R_hot_bal, R_cold_bal)[source]

Estimate heat-transfer area targets with vectorised counter-current logic.

Parameters:
Return type:

dict

OpenPinch.services.common.capital_cost_and_area_targeting.get_min_number_hx(T_vals, H_hot_bal, H_cold_bal, hot_streams, cold_streams, hot_utilities, cold_utilities, idx=None)[source]

Estimate the minimum number of exchangers using vectorised interval logic.

Parameters:
Return type:

int

Temperature-driving-force calculations for Composite Curve analysis.

OpenPinch.services.common.temperature_driving_force.get_temperature_driving_forces(T_hot, H_hot, T_cold, H_cold, min_dT=0)[source]

Compute interval temperature-driving-force data between two composites.

Parameters:

  • T_hot (np.array) – Temperature and heat-flow coordinates for the hot composite curve.

  • H_hot (np.array) – Temperature and heat-flow coordinates for the hot composite curve.

  • T_cold (np.array) – Temperature and heat-flow coordinates for the cold composite curve.

  • H_cold (np.array) – Temperature and heat-flow coordinates for the cold composite curve.

  • min_dT (float, default=0) – Minimum approach-temperature offset subtracted from each end-point driving force.

Returns:

Mapping with interval grid and per-interval values: h_vals, delta_T1, delta_T2, dh_vals, t_h1, t_h2, t_c1, t_c2.

Return type:

dict[str, np.ndarray]

Raises:

ValueError – If input arrays are empty, mismatched in length, or represent unbalanced hot/cold duties.

Utility routines for estimating turbine cogeneration targets.

OpenPinch.services.power_cogeneration.power_cogeneration_analysis.get_power_cogeneration_above_pinch(target, args=None)[source]

Calculate above-Pinch cogeneration for a compatible thermal target object.

Parameters:
Return type:

CogenerationTarget

OpenPinch.services.power_cogeneration.power_cogeneration_analysis.get_power_cogeneration_below_pinch(temperatures, heat_flows, *, zone_config=None, T_sink=None)[source]

Solve a below Pinch turbine target against an environmental sink.

Parameters:
Return type:

tuple[float, dict]

Experimental or Partial Analysis Modules

The modules below remain visible for codebase orientation and restoration work, but they should not be read as stable production workflows. They are present in the repository with partial implementations, commented stubs, or incomplete workflow documentation.

Exergy analysis helpers.

Exergy targeting analysis.