Service Layer

The service layer is the boundary between validated input data and the prepared/solved in-memory model. It is the right integration surface when you want more control than PinchProblem provides but do not want to invoke individual low-level algorithms directly.

Layering

The service stack is designed in three steps:

1. validate or receive typed request data

2. prepare the inputs into a Zone hierarchy

3. dispatch direct, indirect, HPR, cogeneration, or area/cost targeting

Use Cases

Use the service layer when you need to:

• embed OpenPinch in another application with a stable request/response boundary

• prepare a zone hierarchy once and run multiple advanced studies against it

• inspect the prepared model before solving

• bypass file handling entirely and work with typed inputs

Main Service Surface

Public service-layer entry points and reusable targeting helpers.

OpenPinch.services.data_preprocessing_service(input_data, project_name='Site')

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

Parameters:

• input_data (Any)

• project_name (str)

Return type:

Zone

OpenPinch.services.direct_heat_integration_service(zone, args=None)

Run direct heat integration targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.indirect_heat_integration_service(zone, args=None)

Run indirect heat integration targeting for an aggregated zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.direct_heat_pump_service(zone, args=None)

Run direct heat pump targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.indirect_heat_pump_service(zone, args=None)

Run indirect heat pump targeting for an aggregated zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.direct_refrigeration_service(zone, args=None)

Run direct refrigeration targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.indirect_refrigeration_service(zone, args=None)

Run indirect refrigeration targeting for an aggregated zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.power_cogeneration_service(zone, args=None)

Run turbine cogeneration targeting for a prepared zone.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.area_cost_targeting_service(zone, args=None)

Recompute direct integration targets with area/cost targeting enabled.

Parameters:

• zone (Zone)

• args (dict)

Return type:

Zone

OpenPinch.services.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.services.get_capital_cost_targets(area, num_units, zone_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.

• 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.get_output_graph_data(zone, graph_sets=None)

Returns Json data points for each process.

Parameters:

• zone (Zone)

• graph_sets (dict | None)

Return type:

dict

OpenPinch.services.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

Preparation Entry Point

The preparation stage is the key boundary between external inputs and the internal model. It validates configuration choices, builds the zone tree, applies dt_cont multipliers, instantiates process and utility streams, and produces the Zone object consumed by the solver stack.

Stateful inputs remain state-aware after preparation, but state selection does not happen inside prepare_problem(...). Instead, the selected state is applied later through the targeting-service args dictionaries or the higher level problem.target.*(..., state_id=...) wrappers.

OpenPinch.services.input_data_processing.data_preparation.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

Typical Preparation and Solve Pattern

from OpenPinch.lib.schemas.io import TargetInput
from OpenPinch.services import (
    data_preprocessing_service,
    direct_heat_integration_service,
    indirect_heat_integration_service,
)

input_data = TargetInput.model_validate(payload)
zone = data_preprocessing_service(input_data, project_name="Example")

direct_heat_integration_service(zone, {"state_id": "peak"})
indirect_heat_integration_service(zone, {"state_id": "peak"})

Each targeting service mutates the prepared zone in place, records the requested state metadata on the zone, and adds or refreshes the corresponding target model.

Direct High-Level Orchestration

For callers that want one function rather than an object wrapper, the root orchestration helper remains available:

High-level orchestration for running an OpenPinch analysis.

The functions in this module wire together data validation, pinch targeting, and output formatting. They act as the main entry points used by the PinchProblem helper class as well as external callers embedding OpenPinch in larger workflows.

OpenPinch.main.pinch_analysis_service(data, project_name='Project')

Validate input data, run targeting, and return TargetOutput.

Parameters:

• data (Any) – Raw request data matching OpenPinch.lib.schemas.io.TargetInput. Dictionaries, Pydantic models, and dataclass-like objects are accepted.

• project_name (str) – Optional label used in generated graphs and result files.

Returns:

Validated response data containing solved targets and graph data.

Return type:

TargetOutput

Choosing Between Interfaces

• Use OpenPinch.main.pinch_analysis_service() when you want a typed request/response contract.

• Use OpenPinch.services when you want to prepare a zone once and run several advanced analyses against the same prepared state.

• Use PinchProblem when you want a notebook- and file-oriented convenience wrapper with summaries and exports.

The service layer is also the best place to look when you are trying to understand how the narrative workflow maps onto the actual analysis pipeline.