Analysis Package

This is an unsupported contributor reference. Analysis modules may move or change without a compatibility facade; external callers should use OpenPinch.PinchProblem.

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.application._problem.input.construction validates options, normalises the zone hierarchy, and constructs Zone, Stream, and StreamCollection objects.

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

3. OpenPinch.analysis.targeting.cascade builds the shifted and real temperature problem tables used throughout the rest of the workflow.

4. OpenPinch.analysis.targeting.direct computes direct integration targets for unit-operation and process zones.

5. OpenPinch.analysis.targeting.total_site aggregates solved subzones into site-style indirect integration targets when the hierarchy requires it.

6. OpenPinch.analysis.graphs.service converts solved tables and targets into serialisable graph data for reporting and Streamlit visualisation.

Service Package Map

Deterministic engineering analyses and specialist calculations.

Service-layer orchestration helpers for prepared OpenPinch workflows.

OpenPinch.application.targeting.data_preprocessing_service(input_data, project_name='Site')

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

Parameters:

• input_data (TargetInput)

• project_name (str)

Return type:

Zone

OpenPinch.application.targeting.direct_heat_integration_service(zone, args=None)

Run direct heat integration targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.exergy_targeting_service(zone, args=None)

Enrich the first compatible existing target family with exergy outputs.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.indirect_heat_integration_service(zone, args=None)

Run indirect heat integration targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.direct_heat_pump_service(zone, args=None)

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

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.indirect_heat_pump_service(zone, args=None)

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

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.direct_refrigeration_service(zone, args=None)

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

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.indirect_refrigeration_service(zone, args=None)

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

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.power_cogeneration_service(zone, args=None)

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

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.area_cost_targeting_service(zone, args=None)

Refresh direct integration targets before area and cost reporting.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

OpenPinch.application.targeting.energy_transfer_analysis_service(zone, args=None)

Create the energy-transfer diagram and heat-surplus/deficit table.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

Zone

Preparation and Zone Construction

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

Construct validated Zone trees and attach stream/utility data.

OpenPinch.application._problem.input.construction.prepare_problem(streams=None, utilities=None, options=None, project_name='Site', zone_tree=None)

Build the top-level zone hierarchy for analysis.

Parameters:

• streams (List[StreamSchema] | None)

• utilities (List[UtilitySchema] | None)

• options (Dict[str, Any] | None)

• project_name (str)

• zone_tree (ZoneTreeSchema)

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.analysis.heat_pumps.service.

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

OpenPinch.analysis.targeting.direct.compute_direct_integration_targets(zone, args=None)

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:

• zone (Zone)

• args (dict | None)

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.analysis.targeting.total_site.compute_total_subzone_utility_targets(zone, args=None)

Sums and records zonal targets.

Parameters:

• zone (Zone)

• args (dict | None)

Return type:

TotalProcessTarget

OpenPinch.analysis.targeting.total_site.compute_indirect_integration_targets(zone, args=None)

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:

• zone (Zone)

• args (dict | None)

Return type:

TotalSiteTarget | None

Problem Tables, Utility Allocation, and Graph Data

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

• OpenPinch.analysis.targeting.cascade generates the cascade tables and extracts pinch, utility, and heat-recovery targets from them.

• OpenPinch.analysis.targeting.utilities assigns multiple utilities across heating and cooling deficits while respecting temperature feasibility.

• OpenPinch.analysis.targeting.grand_composite derives pocket-free, assisted, and other Grand Composite Curve variants used for interpretation and advanced targeting.

• OpenPinch.analysis.graphs.service translates tables and targets into the graph structures emitted in TargetOutput.

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.analysis.targeting.cascade.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.analysis.targeting.cascade.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.analysis.targeting.cascade.create_problem_table_with_t_int(streams=None, is_shifted=True, extra_T_intervals=None, period_idx=None)

Return a problem table populated with ordered unique temperature intervals.

Parameters:

• streams (StreamCollection)

• is_shifted (bool)

• extra_T_intervals (list | float | ndarray)

• period_idx (int | None)

Return type:

ProblemTable

OpenPinch.analysis.targeting.cascade.problem_table_algorithm(pt, hot_streams=None, cold_streams=None, is_shifted=True, idx=None)

Fast calculation of the problem table using vectorized cascade formulas.

Parameters:

• pt (ProblemTable)

• hot_streams (StreamCollection)

• cold_streams (StreamCollection)

• is_shifted (bool)

• idx (int | None)

Return type:

ProblemTable

OpenPinch.analysis.targeting.cascade.get_heat_recovery_target_from_pt(pt)

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.analysis.targeting.cascade.set_zonal_targets(pt, pt_real)

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

Parameters:

• pt (ProblemTable)

• pt_real (ProblemTable)

Return type:

dict

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

OpenPinch.analysis.targeting.utilities.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)

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

Parameters:

• hot_utilities (StreamCollection)

• cold_utilities (StreamCollection)

• T_vals (ndarray)

• H_net_cold (ndarray)

• H_net_hot (ndarray)

• pinch_idx (Tuple[int, int])

• is_real_temperatures (bool)

• idx (int | None)

Return type:

Tuple[StreamCollection, StreamCollection]

OpenPinch.analysis.targeting.utilities.get_utility_targets(pt, pt_real=None, hot_utilities=None, cold_utilities=None, is_direct_integration=True, idx=None)

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.analysis.targeting.grand_composite.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)

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.analysis.targeting.grand_composite.get_GCC_without_pockets(pt, col_H_NP=ProblemTableLabel.H_NET_NP, col_H=ProblemTableLabel.H_NET)

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

Parameters:

• pt (ProblemTable)

• col_H_NP (str | ProblemTableLabel)

• col_H (str | ProblemTableLabel)

Return type:

ProblemTable

OpenPinch.analysis.targeting.grand_composite.get_GCC_with_partial_pockets(T_col, h_net, h_net_np, dt_cut=10, dt_cut_min=0)

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

Parameters:

• T_col (ndarray)

• h_net (ndarray)

• h_net_np (ndarray)

• dt_cut (float)

• dt_cut_min (float)

Return type:

ProblemTableUpdateKwargs

OpenPinch.analysis.targeting.grand_composite.get_GCC_with_vertical_heat_transfer(T_col, h_cold, h_hot, h_net)

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

Parameters:

• T_col (ndarray)

• h_cold (ndarray)

• h_hot (ndarray)

• h_net (ndarray)

Return type:

ProblemTableUpdateKwargs

OpenPinch.analysis.targeting.grand_composite.get_GCC_needing_utility(T_col, h_net)

Return the actual GCC.

Parameters:

• T_col (ndarray)

• h_net (ndarray)

Return type:

ProblemTableUpdateKwargs

OpenPinch.analysis.targeting.grand_composite.get_GGC_pockets(T_col, h_net, h_net_np)

Store GCC pocket contribution.

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

Parameters:

• T_col (ndarray)

• h_net (ndarray)

• h_net_np (ndarray)

Return type:

ProblemTableUpdateKwargs

OpenPinch.analysis.targeting.grand_composite.get_seperated_gcc_heat_load_profiles(T_col, H_net, rcp_net=None, is_process_stream=True)

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

Parameters:

• T_col (ndarray)

• H_net (ndarray)

• rcp_net (ndarray)

• is_process_stream (bool)

Return type:

ProblemTableUpdateKwargs

Owner-level orchestration for deterministic graph-data construction.

OpenPinch.analysis.graphs.service.get_output_graph_data(zone, graph_sets=None)

Return serialized graph sets for one zone hierarchy.

Parameters:

• zone (Zone)

• graph_sets (dict | None)

Return type:

dict

Process Component Services

Process components mutate a prepared in-memory model before a target is rerun. They sit below PinchProblem.components and are most useful for workspace before/after studies where the active stream set changes between cases.

Heat-pump and refrigeration analysis.

Lightweight base records for process components.

class OpenPinch.analysis.heat_pumps.components.ProcessComponent(id, problem, component_type, active=True)

Bases: object

Base class for memory-only process components.

Parameters:

• id (str)

• problem (PinchProblem)

• component_type (str)

• active (bool)

activate()

Activate the component.

deactivate()

Deactivate the component.

MVR-specific process component records and factory.

class OpenPinch.analysis.heat_pumps.process_mvr.ProcessMVRComponent(id, problem, component_type='process_mvr', active=True, settings=<factory>, source_selectors=<factory>, stream_records=<factory>)

Bases: ProcessComponent

Memory-only direct process MVR component.

Parameters:

• id (str)

• problem (PinchProblem)

• component_type (str)

• active (bool)

• settings (DirectGasMVRSettings)

• source_selectors (list[Any])

• stream_records (list[_ProcessMVRStreamRecord])

activate()

Use the MVR replacement streams in subsequent targeting.

deactivate()

Restore the original source streams for subsequent targeting.

work_for_zone(zone, *, period_id=None, period_idx=None)

Return active compressor work assigned to streams inside zone.

Parameters:

• zone (Zone)

• period_id (str | None)

• period_idx (int | None)

Return type:

float

OpenPinch.analysis.heat_pumps.process_mvr.create_process_mvr_component(problem, *, source_streams, mvr_id=None, n_stages=1, liquid_injection=True, mvr_stage_t_lift=None, mvr_stage_pressure_ratio=None, eta_mvr_comp=None, eta_motor=None, options=None, period_id=None)

Create, activate, and register a direct process MVR component.

Parameters:

• problem (PinchProblem)

• mvr_id (str | None)

• n_stages (int)

• liquid_injection (bool)

• mvr_stage_t_lift (float | None)

• mvr_stage_pressure_ratio (float | None)

• eta_mvr_comp (float | None)

• eta_motor (float | None)

• options (dict | None)

• period_id (str | None)

Return type:

ProcessMVRComponent

Direct gas MVR models, thermodynamics, units, and execution.

Direct process-gas MVR component solver.

OpenPinch.analysis.heat_pumps.direct_mvr.execution.coerce_positive_mvr_stage_count(value, *, context='Direct gas MVR')

Return a validated integer direct-MVR stage count.

Parameters:

context (str)

Return type:

int

OpenPinch.analysis.heat_pumps.direct_mvr.execution.solve_direct_gas_mvr_stream(stream, *, settings, idx=0)

Solve direct gas MVR replacement streams for one source stream and period.

Parameters:

• stream (Stream)

• settings (DirectGasMVRSettings)

• idx (int)

Return type:

DirectGasMVRStreamSolveResult

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.analysis.heat_pumps.service.

Area targeting methods.

OpenPinch.analysis.targeting.area_cost.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)

Create the balanced composite curve using process and utility streams.

Parameters:

• T_col (ndarray)

• H_hot (ndarray)

• H_cold (ndarray)

• H_hot_ut (ndarray)

• H_cold_ut (ndarray)

• dT_vals (ndarray)

• RCP_hot (ndarray)

• RCP_cold (ndarray)

• RCP_hot_ut (ndarray)

• RCP_cold_ut (ndarray)

Return type:

ProblemTableUpdateKwargs

OpenPinch.analysis.targeting.area_cost.get_capital_cost_targets(area, num_units, config)

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.

• 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.analysis.targeting.area_cost.get_area_targets(T_vals, H_hot_bal, H_cold_bal, R_hot_bal, R_cold_bal)

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

Parameters:

• T_vals (ndarray)

• H_hot_bal (ndarray)

• H_cold_bal (ndarray)

• R_hot_bal (ndarray)

• R_cold_bal (ndarray)

Return type:

dict

OpenPinch.analysis.targeting.area_cost.get_min_number_hx(T_vals, H_hot_bal, H_cold_bal, hot_streams, cold_streams, hot_utilities, cold_utilities, idx=None)

Estimate the minimum number of exchangers using vectorised interval logic.

Parameters:

• T_vals (ndarray)

• H_hot_bal (ndarray)

• H_cold_bal (ndarray)

• hot_streams (StreamCollection)

• cold_streams (StreamCollection)

• hot_utilities (StreamCollection)

• cold_utilities (StreamCollection)

• idx (int | None)

Return type:

int

Temperature-driving-force calculations for Composite Curve analysis.

OpenPinch.analysis.targeting.temperature_driving_force.get_temperature_driving_forces(T_hot, H_hot, T_cold, H_cold, min_dT=0)

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.analysis.power.service.get_power_cogeneration_above_pinch(target, args=None)

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

Parameters:

• target (CogenerationTarget)

• args (dict | None)

Return type:

CogenerationTarget

OpenPinch.analysis.power.service.get_power_cogeneration_below_pinch(temperatures, heat_flows, *, config=None, T_sink=None)

Solve a below Pinch turbine target against an environmental sink.

Parameters:

• temperatures (ndarray)

• heat_flows (ndarray)

• config (Configuration | None)

• T_sink (float | None)

Return type:

tuple[float, dict]

OpenPinch.analysis.power.service.run_power_cogeneration_service(zone, args=None, *, refresh_services, cogeneration_func=<function get_power_cogeneration_above_pinch>)

Post-process one compatible target in service preference order.

Parameters:

• args (dict | None)

• refresh_services (dict[str, object])

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 targeting analysis helpers.