Domain Classes

The class layer is the in-memory model behind the OpenPinch workflow. Most of these objects are created for you by prepare_problem(), but they are also useful directly when building tests, custom workflows, or post-processing studies.

How These Objects Fit Together

  • Stream and StreamCollection represent the thermal streams and ordered stream sets used to build problem tables.

  • Zone groups streams, utilities, targets, and subzones into a hierarchical model of the process, site, or wider system.

  • ProblemTable stores the numerical temperature-interval cascade that drives pinch and utility calculations.

  • BaseTargetModel stores one solved set of metrics for a zone and is later serialised into the public output schema.

  • Value wraps scalar and discrete-period quantities with units for report-friendly serialisation.

Core domain classes used throughout OpenPinch.

Streams and Collections

These are the most commonly manipulated domain objects outside the top-level service layer.

Data model representing process and utility streams.

class OpenPinch.classes.stream.Stream(name='Stream', t_supply=None, t_target=None, p_supply=None, p_target=None, h_supply=None, h_target=None, dt_cont=0.0, dt_cont_multiplier=1.0, heat_flow=0.0, htc=1.0, price=None, is_process_stream=True, fluid_name=None, fluid_phase=None, segments=None)[source]

Bases: object

Generic thermal stream used for both process and utility duties.

A Stream stores supply/target states together with derived values such as hot/cold classification, shifted temperature bounds, heat-capacity flow rate, and simple economic attributes. The same class is reused for process streams, utilities, and derived net streams created during site- level aggregation.

Initialise a stream and infer hot/cold classification.

Parameters:

  • name (str)

  • t_supply (Optional[MaybeVU])

  • t_target (Optional[MaybeVU])

  • p_supply (Optional[MaybeVU])

  • p_target (Optional[MaybeVU])

  • h_supply (Optional[MaybeVU])

  • h_target (Optional[MaybeVU])

  • dt_cont (MaybeVU)

  • dt_cont_multiplier (float)

  • heat_flow (MaybeVU)

  • htc (MaybeVU)

  • price (Optional[MaybeVU])

  • is_process_stream (bool)

  • fluid_name (Optional[str])

  • fluid_phase (Optional[str | FluidPhase])

  • segments (list[object] | tuple[object, ...] | None)

property name: str

Stream name.

property is_process_stream: bool

Process or utility stream.

property fluid_name: str | None

CoolProp fluid name or mixture specification.

property fluid_phase: str | None

sol, sle, liq, vle, sve, or gas.

Type:

Optional fluid-phase flag

property segments: tuple[StreamSegment, ...]

Ordered immutable view of the stream’s piecewise thermal segments.

property has_segments: bool

Return whether this physical stream has an explicit thermal profile.

property segment_count: int

Return the number of explicit thermal segments.

property type: str | None

Stream type (Hot, Cold, Both).

property num_periods: int | None

Number of periods.

property t_supply: Value | None

Supply temperature (e.g., degC).

property t_target: Value | None

Target temperature (e.g., degC).

property p_supply: Value | None

Supply pressure (e.g., kPa).

property p_target: Value | None

Target pressure (e.g., kPa).

property h_supply: Value | None

Supply enthalpy (e.g., kJ/kg).

property h_target: Value | None

Target enthalpy (e.g., kJ/kg).

property dt_cont: Value

Preserved base delta-T contribution before any zone multiplier.

property dt_cont_act: Value

Effective delta-T contribution used in shifted-temperature calculations.

property dt_cont_multiplier: float

Effective delta-T contribution used in shifted-temperature calculations.

property dt_cont_multiplier_locked: bool

Whether the delta-T contribution multiplier is locked against changes.

property heat_flow: Value

Stream heat flow view over a scalar or multiperiod duty value.

property htc: float

Heat transfer coefficient (e.g., kW/m^2/K).

property htr: Value | None

Heat transfer resistance (e.g., m^2.K/kW).

property price: Value

Unit energy price (e.g., $/MWh).

property ut_cost: Value | None

Utility cost (e.g., $/y).

property CP: Value | None

Heat capacity flowrate (e.g., kW/K).

property rCP: Value | None

Resistance-capacity product (1/heat transfer rate).

property active: bool

Whether the stream is active in analysis.

property t_min: Value | None

Minimum temperature (supply or target depending on hot/cold).

property t_max: Value | None

Maximum temperature (supply or target depending on hot/cold).

property t_min_star: Value | None

Shifted minimum temperature.

property t_max_star: Value | None

Shifted maximum temperature.

property t_entr_mean: Value | None

Entropic mean temperature of supply and target temperatures.

property stream_type: str | None

Alias for the stream thermal type.

property is_active: bool

Alias for whether the stream participates in analysis.

property supply_temperature: Value | None

Alias for the supply temperature.

property target_temperature: Value | None

Alias for the target temperature.

property minimum_temperature: Value | None

Alias for the minimum stream temperature.

property maximum_temperature: Value | None

Alias for the maximum stream temperature.

property shifted_minimum_temperature: Value | None

Alias for the shifted minimum stream temperature.

property entropic_mean_temperature: Value | None

Alias for the entropic mean temperature.

property shifted_maximum_temperature: Value | None

Alias for the shifted maximum stream temperature.

property supply_pressure: Value | None

Alias for the supply pressure.

property target_pressure: Value | None

Alias for the target pressure.

property supply_enthalpy: Value | None

Alias for the supply enthalpy.

property target_enthalpy: Value | None

Alias for the target enthalpy.

property delta_t_contribution: Value

Alias for the base shifted-temperature contribution.

property delta_t_contribution_multiplier: float

Alias for the shifted-temperature contribution multiplier.

property effective_delta_t_contribution: Value

Alias for the effective shifted-temperature contribution.

property heat_transfer_coefficient: Value

Alias for the heat transfer coefficient.

property heat_transfer_resistance: Value | None

Alias for the heat-transfer resistance.

property utility_cost: Value | None

Alias for the derived utility cost.

property resistance_capacity_product: Value | None

Alias for the stream resistance-capacity product.

invert()[source]

Flip a utility stream into its generating process-stream analogue.

Return type:

None

replace_segments(segments)[source]

Normalize and atomically replace the piecewise profile.

Return type:

None

update_segment(index, **changes)[source]

Apply one segment update transactionally and revalidate the profile.

Parameters:

index (int)

Return type:

None

update_segments(updates)[source]

Atomically apply sparse attribute changes to ordered child segments.

Parameters:

updates (Mapping[int, Mapping[str, object]])

Return type:

None

classmethod from_temperature_heat_profile(*, name, points, heat_scale=1.0, heat_unit='kW', dt_diff_max=None, **stream_kwargs)[source]

Build one segmented stream from ordered [heat, temperature] points.

Parameters:
Return type:

Stream

Utility container for managing ordered sets of stream objects.

class OpenPinch.classes.stream_collection.StreamCollection(streams=None)[source]

Bases: object

A dynamic, ordered collection of streams.

Key features include:

  • Add and remove streams by name.

  • Prevent overwriting existing streams by auto-renaming.

  • Configure sort keys as attributes or callables.

  • Iterate efficiently with lazy sorting.

  • Support ascending or descending ordering.

Initialise an empty collection sorted by descending supply temperature.

Parameters:

streams (List['Stream'] | None)

property period_ids: dict[str, int] | None

Return the canonical period identifiers for this collection.

property weights: ndarray | None

Return the canonical period weights for this collection.

property num_periods: int | None

Return the number of periods for this collection.

add(stream, key=None, prevent_overwrite=True)[source]

Insert a stream, optionally renaming the key to avoid collisions.

Parameters:
Return type:

str

add_many(streams, keys=None, prevent_overwrite=True)[source]

Insert several streams, optionally using explicit keys for each stream.

Parameters:
remove(stream_name)[source]

Remove a stream by name.

Parameters:

stream_name (str)

sum_stream_attribute(attr_name, idx=None)[source]

Return the total of a specified attribute for streams in the collection.

Parameters:

  • attr_name (str)

  • idx (int | None)

Return type:

float

set_common_stream_attribute(attr_name, value, *, idx=None)[source]

Set a common attribute across all streams in the collection.

Parameters:

  • attr_name (str)

  • value (Any)

  • idx (int | None)

set_sort_key(key, reverse=False)[source]

Set the sorting key. Supports attribute names or custom lambdas.

Parameters:
copy(*, deep=False)[source]

Return a copy of the collection, optionally deep-copying streams.

Parameters:

deep (bool)

Return type:

StreamCollection

set_period_context(period_ids, weights, num_periods=None)[source]

Persist the canonical shared period model for this collection.

Parameters:
Return type:

None

numeric_view(idx=None)[source]

Return a cached dense numeric view for stream-analysis kernels.

Parameters:

idx (int | None)

Return type:

StreamCollectionNumericView

segment_numeric_view(idx=None)[source]

Return a cached numeric view expanded to ordered thermal segments.

Parameters:

idx (int | None)

Return type:

StreamCollectionNumericView

get_index(stream)[source]

Return the position (index) of a stream object in the sorted stream list.

Return type:

int

items()[source]

Return the underlying keyed stream items in insertion order.

export_to_csv(filename='heat pump streams')[source]

Export stream data to results/<filename> and return the path written.

Parameters:

filename (str)

Return type:

Path

to_dict(idx=None, *, expand_segments=False)[source]

Return stream data as serializable rows in standard reporting order.

Parameters:

  • idx (int | None)

  • expand_segments (bool)

Return type:

dict[str, list[Any]]

get_hot_streams(include_process_streams=True, include_utility_streams=True, invert_utility=False, sort_attr=None)[source]

Return a new collection containing only hot streams.

Parameters:

  • include_process_streams (bool)

  • include_utility_streams (bool)

  • invert_utility (bool)

  • sort_attr (str | None)

get_cold_streams(include_process_streams=True, include_utility_streams=True, invert_utility=False, sort_attr=None)[source]

Return a new collection containing only cold streams.

Parameters:

  • include_process_streams (bool)

  • include_utility_streams (bool)

  • invert_utility (bool)

  • sort_attr (str | None)

get_process_streams(sort_attr=None)[source]

Return a new collection containing only process streams.

Parameters:

sort_attr (str | None)

get_hot_process_streams(sort_attr=None)[source]

Return a new collection containing only hot process streams.

Parameters:

sort_attr (str | None)

get_cold_process_streams(sort_attr=None)[source]

Return a new collection containing only cold process streams.

Parameters:

sort_attr (str | None)

get_utility_streams(sort_attr=None)[source]

Return a new collection containing only utility streams.

Parameters:

sort_attr (str | None)

get_hot_utility_streams(sort_attr=None)[source]

Return a new collection containing only hot utility streams.

Parameters:

sort_attr (str | None)

get_cold_utility_streams(sort_attr=None)[source]

Return a new collection containing only cold utility streams.

Parameters:

sort_attr (str | None)

get_inverted_hot_utility_streams(sort_attr=None)[source]

Return a new collection containing only inverted hot utility streams.

Parameters:

sort_attr (str | None)

get_inverted_cold_utility_streams(sort_attr=None)[source]

Return a new collection containing only inverted cold utility streams.

Parameters:

sort_attr (str | None)

Zones, Targets, and Tables

These classes represent the solved hierarchy and its numerical results.

Zone data structure capturing nested scopes and their thermal targets.

class OpenPinch.classes.zone.Zone(name='Zone', type='Process Zone', config=None, parent_zone=None)[source]

Bases: object

Hierarchical analysis boundary containing streams, utilities, and targets.

Zones form the backbone of the in-memory OpenPinch model. Each zone can own process streams, utility streams, solved targets, generated graphs, and nested child zones. Direct and indirect integration routines progressively populate this structure as the analysis moves from local process scopes up to site-style aggregation.

Initialise an empty zone with stream, target, and graph containers.

Parameters:
property name

Display name used when addressing the zone in the hierarchy.

property type

Zone type type from ZoneType.

property config

Configuration object controlling analysis behaviour for this zone.

property parent_zone

Direct parent zone in the site hierarchy, if any.

property active: bool

Whether the zone participates in the current analysis.

property period_ids: dict[str, int] | None

Canonical period_id -> idx lookup for this zone.

property weights

Canonical period weights for this zone.

property num_periods

Number of distinct states for this zone.

property address: str

Slash-delimited path from the root zone to this zone.

property dt_cont_multiplier: float

Effective multiplier applied to stream and utility dt_cont values.

property hot_streams

Process streams that release heat within this zone.

property cold_streams

Process streams that require heat within this zone.

property net_hot_streams

Net hot streams derived from zonal aggregation.

property net_cold_streams

Net cold streams derived from zonal aggregation.

property hot_utilities

Hot utility streams assigned to the zone.

property cold_utilities

Cold utility streams assigned to the zone.

property graphs

Graphs generated for this zone.

property subzones

Immediate child zones keyed by name.

property targets

Energy targets keyed by target name.

property process_streams

Combined hot and cold process streams for the zone.

property net_process_streams

Combined net hot and net cold process streams for the zone.

property utility_streams

Combined hot and cold utility streams for the zone.

property all_streams

All process and utility streams defined on the zone.

set_period_context(period_ids, weights, num_periods)[source]

Set the canonical period lookup owned by this zone and propagate refs.

Parameters:
Return type:

None

add_graph(name, result)[source]

Store a graph result under name for later export or display.

Parameters:

name (str)

add_zone(zone_to_add, sub=True)[source]

Add a single zone object keyed by its name.

If the zone name already exists: - If the zone is identical (e.g. same stream and utility objects), skip. - If it’s different, add it with a suffix like ‘_1’, ‘_2’, etc.

Parameters:

sub (bool)

add_target(target_to_add)[source]

Add one target to a specific zone.

Parameters:

target_to_add (BaseTargetModel)

add_targets(targets=None)[source]

Add multiple targets to a specific zone.

Parameters:

targets (list | None)

get_subzone(loc=None)[source]

Resolve a slash-delimited zone path relative to this zone.

Parameters:

loc (str)

Return type:

Zone

calc_utility_cost()[source]

Calculate and cache the annual utility cost across assigned utilities.

import_hot_and_cold_streams_from_sub_zones(get_net_streams=False, is_n_zone_depth=True, is_new_stream_collection=True)[source]

Get referenced hot and cold streams across multiple subzones.

Parameters:

  • get_net_streams (bool)

  • is_n_zone_depth (bool)

  • is_new_stream_collection (bool)

get_target_zone(zone_name)[source]

Resolve zone_name to the concrete zone that should receive a target.

Parameters:

zone_name (str | list | None)

Return type:

Zone

lock_dt_cont_multiplier()[source]

Lock the dt_cont_multiplier to prevent further changes.

Lightweight table structure used by the pinch analysis pipeline.

class OpenPinch.classes.problem_table.ProblemTable(data_input=None, add_default_labels=True)[source]

Bases: object

NumPy-backed pinch problem table with enum-friendly accessors.

Initialise the table from a dictionary or list-of-columns structure.

Parameters:
class ColumnViewByIndex(parent)[source]

Bases: object

Expose read/write access to columns addressed by integer index.

Parameters:

parent (ProblemTable)

property icol

Return a view for column access by integer position.

class ColumnViewByName(parent)[source]

Bases: object

Expose read/write access to columns addressed by label or enum.

Parameters:

parent (ProblemTable)

property col

Return a view for column access by string label or ProblemTableLabel.

class ColumnsViewByName(parent)[source]

Bases: object

Vectorised view over multiple labelled columns or enums.

Parameters:

parent (ProblemTable)

property cols

Return a vectorised view over multiple labelled columns or enums.

class LocationByRowByColName(parent)[source]

Bases: object

Row/column accessor mirroring DataFrame.loc semantics.

Parameters:

parent (ProblemTable)

property loc

Expose row/column access using label semantics (loc).

class LocationByRowByCol(parent)[source]

Bases: object

Row/column accessor mirroring DataFrame.iloc semantics.

Parameters:

parent (ProblemTable)

property iloc

Expose row/column access using positional semantics (iloc).

slice(keys)[source]

Return a new ProblemTable containing only the requested columns.

Parameters:

keys (str | ProblemTableLabel | Sequence[str | ProblemTableLabel])

Return type:

ProblemTable

property shape

Tuple describing (rows, columns) for the buffer.

property to_dataframe: DataFrame

Convert the buffer into a pandas DataFrame.

property copy

Return a deep copy of the table.

to_list(col=None)[source]

Return table data as Python lists; optionally restrict to a single column.

Parameters:

col (str | ProblemTableLabel | None)

round(decimals)[source]

Round the underlying NumPy buffer in-place.

pinch_idx(col=ProblemTableLabel.H_NET)[source]

Return the row indices of the hot and cold pinch temperatures.

Parameters:

col (int | str | ProblemTableLabel)

Return type:

Tuple[int, int, bool]

pinch_temperatures(col_T=ProblemTableLabel.T, col_H=ProblemTableLabel.H_NET)[source]

Determine the hottest hot and coldest cold pinch temperatures.

Parameters:
Return type:

Tuple[float | None, float | None]

shift_heat_cascade(dh, col)[source]

Shift a heat-cascade column by dh and return a table copy.

Parameters:
Return type:

ProblemTable

share_temperature_intervals(other)[source]

Mutate both tables so they use the union of their temperature intervals.

Returns a tuple containing (rows_inserted_into_self, rows_inserted_into_other).

Parameters:

other (ProblemTable)

Return type:

Tuple[int, int]

insert_temperature_interval(T_ls)[source]

Insert any missing temperature intervals and return count inserted.

Parameters:

T_ls (List[float] | float)

Return type:

int

insert(row_dict, index)[source]

Insert a single row (dict of column: value) at the specified index.

Parameters:
update_row(index, row_dict)[source]

Update selected columns for one row using values from row_dict.

Parameters:
update(updates=None, T_col=None)[source]

Assign aligned column values in-place using an explicit source T column.

Parameters:
Return type:

ProblemTable

delete_row(index)[source]

Remove a row at index from the buffer.

Parameters:

index (int)

sort_by_column(column, ascending=True)[source]

Sort rows in-place by the given column.

Parameters:
export(filename='problem_table', sheet_name='ProblemTable', include_index=False)[source]

Export the table to results/<filename>.xlsx and return the path.

Parameters:

  • filename (str)

  • sheet_name (str)

  • include_index (bool)

Return type:

Path

Heat Exchanger Network Design Records

These classes are the OpenPinch-native public result model for heat exchanger network design outcomes. They expose exchanger links by source and sink stream identity; raw solver axis positions remain internal implementation details.

OpenPinch-native heat exchanger design records.

class OpenPinch.classes.heat_exchanger.HeatExchanger(*, exchanger_id=None, kind, source_stream, sink_stream, source_stream_role, sink_stream_role, stage=None, period_states, area=None, match_allowed=True, capital_cost=None, segment_area_contributions=<factory>, solver_metadata=<factory>, source_metadata=<factory>)[source]

Bases: BaseModel

One labelled heat-transfer link in a heat exchanger network.

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:
model_config = {'extra': 'forbid', 'validate_assignment': True}

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

property has_segment_area_contributions: bool

Return whether exact local segment-area slices are available.

property segment_duty_by_period: dict[str, float]

Return local slice duty totals grouped by operating period.

property segment_area_by_period: dict[str, float]

Return local slice area totals grouped by operating period.

property segment_design_area: float | None

Return the maximum period-total slice area when slices are available.

property period_ids: tuple[str, ...]

Return ordered operating-period identities for this exchanger.

state(period_id=None)[source]

Return one period state, requiring identity for multiperiod results.

Parameters:

period_id (str | None)

Return type:

HeatExchangerPeriodState

involves_stream(stream_id)[source]

Return whether this exchanger uses stream_id as source or sink.

Parameters:

stream_id (str)

Return type:

bool

matches(*, source_stream, sink_stream, stage=None)[source]

Return whether this exchanger matches a labelled stream-stage link.

Parameters:

  • source_stream (str)

  • sink_stream (str)

  • stage (int | None)

Return type:

bool

class OpenPinch.classes.heat_exchanger.HeatExchangerKind(*values)[source]

Bases: str, Enum

Supported heat-transfer link families in a heat exchanger network design.

class OpenPinch.classes.heat_exchanger.HeatExchangerStreamRole(*values)[source]

Bases: str, Enum

Identity class for the source and sink streams on an exchanger link.

OpenPinch-native heat exchanger network result model.

class OpenPinch.classes.heat_exchanger_network.HeatExchangerNetwork(*, exchangers=<factory>, run_id=None, task_id=None, period_id=None, method=None, stage_count=None, objective_value=None, total_annual_cost=None, utility_cost=None, capital_cost=None, summary_metrics=<factory>, solver_axis_metadata=<factory>, source_metadata=<factory>)[source]

Bases: BaseModel

Ordered heat exchanger network result collection.

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:
model_config = {'extra': 'forbid', 'validate_assignment': True}

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

build_grid_diagram(*, period_id=None, stream_line_width=5.0, temperature_scaled=False)[source]

Return a grid diagram for this heat exchanger network.

Parameters:

  • period_id (str | None)

  • stream_line_width (float)

  • temperature_scaled (bool)

Return type:

Any

quantify_controllability(*, period_id=None, **kwargs)[source]

Return steady-state controllability metrics for this network.

Parameters:

  • period_id (str | None)

  • kwargs (Any)

Return type:

Any

property period_ids: tuple[str, ...]

Return ordered period identities represented by exchanger states.

resolve_period_id(period_id=None)[source]

Resolve an optional period identity without ambiguous multiperiod access.

Parameters:

period_id (str | None)

Return type:

str | None

exchangers_involving_stream(stream_id, *, active_only=False, period_id=None)[source]

Return all exchangers that use stream_id as source or sink.

Parameters:

  • stream_id (str)

  • active_only (bool)

  • period_id (str | None)

Return type:

tuple[HeatExchanger, …]

exchanger_between(*, source_stream, sink_stream, stage=None, kind=None)[source]

Return the unique exchanger for a labelled source/sink/stage link.

Parameters:
Return type:

HeatExchanger | None

total_duty(*, kind=None, stream=None, stage=None, active_only=True, period_id=None)[source]

Return duty total filtered by kind, stream identity, and stage.

Parameters:
Return type:

float

total_area(*, kind=None, stream=None, stage=None, active_only=True, period_id=None)[source]

Return area total filtered by kind, stream identity, and stage.

Parameters:
Return type:

float

total(label, *, kind=None, stream=None, stage=None, active_only=True, period_id=None)[source]

Return a numeric total for a supported heat exchanger network label.

Parameters:
Return type:

float

labelled_value(label, *, source_stream, sink_stream, stage=None, kind=None, period_id=None)[source]

Return a labelled value from one source/sink/stage exchanger link.

Parameters:
Return type:

float | bool | None

Heat Exchanger Network Unit Models

The HEN synthesis unit-model modules sit below the public design accessors. They are useful when inspecting how the pinch-design and stagewise equations are assembled, but users normally call the methods through problem.design.

Private equation-model boundary for OpenPinch heat exchanger network synthesis.

The symbols in this package are implementation details behind the problem-rooted synthesis service. Importing the package must stay lightweight; GEKKO, Pyomo, and external solver checks happen only when a concrete backend is created or configured.

Base setup for migrated heat exchanger network equation kernels.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.base.BaseHeatExchangerNetworkModel(name, framework, solver, solver_arrays, dTmin, z_restriction, min_dqda, minimisation_goal, non_isothermal_model, integers, tol, solver_options=None, import_file=None)[source]

Bases: ABC

Shared private state for migrated PDM/TDM/ESM equation models.

The constructor mirrors the source OpenHENS solver defaults, but it accepts OpenPinch-prepared solver arrays instead of a CSV path. This layer owns the guarded GEKKO backend setup, source-shaped array normalization, inherited topology restrictions, common diagnostics, and helper equations that are stable across the moved private PinchDecompModel and StageWiseModel. HENS-08 still owns topology evolution and stage-reduction behavior; those remain outside the base contract.

Parameters:

  • name (str)

  • framework (Literal['PDM', 'TDM', 'ESM'])

  • solver (Literal['couenne', 'ipopt-pyomo', 'ipopt-GEKKO', 'apopt'])

  • solver_arrays (PreparedSolverArrays)

  • dTmin (float)

  • z_restriction (list | None)

  • min_dqda (float)

  • minimisation_goal (Literal['hot utility', 'total utility', 'utility costs', 'heat recovery', 'total cost', 'variable total cost'])

  • non_isothermal_model (bool)

  • integers (bool)

  • tol (float)

  • solver_options (Mapping[str, Any] | Sequence[str] | None)

  • import_file (Path | None)

setup_model()[source]

Create and configure the GEKKO model behind optional guards.

Return type:

None

abstractmethod setup()[source]

Create concrete equation variables, constraints, and objective.

Return type:

None

abstractmethod set_preprocessing()[source]

Populate model dimensions and derived solver constants.

Return type:

None

abstractmethod set_stage_wise_superstructure()[source]

Create the stage-wise superstructure in concrete model slices.

Return type:

None

abstractmethod set_obj()[source]

Attach the concrete objective formula unchanged from OpenHENS.

Return type:

None

abstractmethod get_post_process()[source]

Extract solved arrays after a successful concrete solve.

Return type:

None

get_alpha_values()[source]

Calculate source alpha flow-on values in a post-optimisation solve.

Return type:

list

set_alpha_dqda_equations(*, m=None, postoptimisation=False)[source]

Move the source alpha and dQ/dA equations without changing formulas.

Parameters:

  • m (Any | None)

  • postoptimisation (bool)

Return type:

None

set_blank_input_parameters()[source]

Initialize the solver-array attributes expected by source equations.

Return type:

None

get_model_parameters_from_solver_arrays()[source]

Populate model attributes from the OpenPinch private array adapter.

Return type:

None

set_match_restrictions(restrictions)[source]

Apply inherited topology restrictions in the source array shape.

Return type:

None

optimise(print_output)[source]

Delegate solver execution with explicit model state.

Parameters:

print_output (bool)

Return type:

None

output_to_cmd_line()[source]

Emit the same solved-array diagnostics as the source base model.

Return type:

None

Migrated PDM coordinator and above/below-pinch model construction.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.pinch_design.PinchDecompModel(*, name, framework, solver, solver_arrays, dTmin, z_restriction, min_dqda, minimisation_goal, non_isothermal_model, integers, tol, pinch_loc, pinch_decomposition, stage_selection, solver_options=None)[source]

Bases: BaseHeatExchangerNetworkModel

Source-compatible private PDM slice for one pinch side.

Parameters:

  • name (str)

  • framework (Literal['PDM'])

  • solver (Literal['couenne', 'ipopt-pyomo', 'ipopt-GEKKO', 'apopt'])

  • solver_arrays (PreparedSolverArrays)

  • dTmin (float)

  • z_restriction (list | None)

  • min_dqda (float)

  • minimisation_goal (Literal['hot utility', 'cold utility', 'total utility', 'utility costs', 'heat recovery', 'total cost', 'variable total cost', 'min units'])

  • non_isothermal_model (bool)

  • integers (bool)

  • tol (float)

  • pinch_loc (Literal['above', 'below'])

  • pinch_decomposition (PinchDesignDecomposition)

  • stage_selection (Literal['automated'] | list[int] | tuple[int, int])

  • solver_options (Mapping[str, Any] | Sequence[str] | None)

setup()[source]

Create concrete equation variables, constraints, and objective.

Return type:

None

get_model_parameters_from_solver_arrays()[source]

Populate model attributes from the OpenPinch private array adapter.

Return type:

None

calculate_pinch()[source]

Read target values from the private OpenPinch decomposition.

Return type:

None

set_preprocessing()[source]

Pre-process PDM superstructure parameters.

Return type:

None

set_stage_wise_superstructure()[source]

Create PDM variables, constraints, and binaries.

Return type:

None

set_obj()[source]

Attach PDM objective expressions.

Return type:

None

get_post_process()[source]

Extract source PDM side arrays after a successful solve.

Return type:

None

amalgamate_networks(*, below_case, above_case)[source]

Amalgamate solved above/below-pinch side models into one network.

Parameters:
Return type:

StageWiseModel

Migrated StageWise TDM/ESM equation construction.

This module is private to the problem-rooted synthesis service. The equations mirror the source OpenHENS StageWise model while taking prepared OpenPinch solver arrays instead of source CSV rows.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.stagewise.StageWiseModel(*, name, framework, solver, solver_arrays, stages, dTmin, z_restriction, min_dqda, minimisation_goal, non_isothermal_model, integers, tol, solver_options=None)[source]

Bases: BaseHeatExchangerNetworkModel

Source-compatible StageWise model for private TDM/ESM construction.

Parameters:

  • name (str)

  • framework (Literal['TDM', 'ESM', 'PDM'])

  • solver (Literal['couenne', 'ipopt-pyomo', 'ipopt-GEKKO', 'apopt'])

  • solver_arrays (PreparedSolverArrays)

  • stages (int)

  • dTmin (float)

  • z_restriction (list | None)

  • min_dqda (float)

  • minimisation_goal (Literal['hot utility', 'cold utility', 'total utility', 'utility costs', 'heat recovery', 'total cost', 'variable total cost', 'dQ/dA obj'])

  • non_isothermal_model (bool)

  • integers (bool)

  • tol (float)

  • solver_options (Mapping[str, Any] | Sequence[str] | None)

setup()[source]

Create concrete equation variables, constraints, and objective.

Return type:

None

set_preprocessing()[source]

Pre-process SynHEAT superstructure parameters for all states.

Return type:

None

set_stage_wise_superstructure()[source]

Create StageWise variables, constraints, and binaries.

Return type:

None

set_dqda_equations()[source]

Apply the source TDM minimum dQ/dA restriction.

Return type:

None

set_initial_values_for_variables(init_solution, *, brackets=False)[source]

Warm-start this model from a solved parent model.

Parameters:

brackets (bool)

Return type:

None

get_net_benefit_evolution(print_output, max_depth=5, n_ad_branches=1, n_rm_branches=1, max_parallel=1, no_improvement_patience=None)[source]

Evolve topology using branched add/remove net-benefit heuristics.

Parameters:

  • print_output (bool)

  • max_depth (int)

  • n_ad_branches (int)

  • n_rm_branches (int)

  • max_parallel (int)

  • no_improvement_patience (int | None)

get_n_minus_one_evolution(print_output, unit, prev_case)[source]

Build and solve the source minus-one topology evolution candidate.

Parameters:
get_n_plus_one_evolution(print_output, unit, prev_case)[source]

Build and solve the source plus-one topology evolution candidate.

Parameters:
set_obj()[source]

Attach source StageWise objective expressions unchanged.

Return type:

None

get_post_process()[source]

Extract source post-process arrays after a successful solve.

Return type:

None

get_lowest_benefit_HX()[source]

Return the active exchanger with the lowest source net benefit.

Return type:

list[list[int]]

get_lowest_benefit_HX_candidates(limit)[source]

Return active exchangers sorted by ascending source net benefit.

Parameters:

limit (int)

Return type:

list[list[int]]

get_max_benefit_HX()[source]

Return the inactive feasible exchanger with the highest alpha-dQ/dA.

Return type:

list[list[int]]

get_max_benefit_HX_candidates(limit)[source]

Return inactive feasible exchangers sorted by descending alpha-dQ/dA.

Parameters:

limit (int)

Return type:

list[list[int]]

verify()[source]

Run the source solution checks used by topology evolution.

Return type:

tuple[bool, list[str]]

Pinch-decomposition model with explicit stage packing constraints.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.packed_pinch_design.StagePackedPinchDecompModel(*, name, framework, solver, solver_arrays, dTmin, z_restriction, min_dqda, minimisation_goal, non_isothermal_model, integers, tol, pinch_loc, pinch_decomposition, stage_selection, solver_options=None)[source]

Bases: PinchDecompModel

PDM slice with packed recovery stages to reduce stage-index symmetry.

Parameters:

  • name (str)

  • framework (Literal['PDM'])

  • solver (Literal['couenne', 'ipopt-pyomo', 'ipopt-GEKKO', 'apopt'])

  • solver_arrays (PreparedSolverArrays)

  • dTmin (float)

  • z_restriction (list | None)

  • min_dqda (float)

  • minimisation_goal (Literal['hot utility', 'cold utility', 'total utility', 'utility costs', 'heat recovery', 'total cost', 'variable total cost', 'min units'])

  • non_isothermal_model (bool)

  • integers (bool)

  • tol (float)

  • pinch_loc (Literal['above', 'below'])

  • pinch_decomposition (PinchDesignDecomposition)

  • stage_selection (Literal['automated'] | list[int] | tuple[int, int])

  • solver_options (Mapping[str, Any] | Sequence[str] | None)

set_stage_wise_superstructure()[source]

Create PDM variables, constraints, and binaries.

Return type:

None

Stage-wise HEN model with explicit stage packing constraints.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.packed_stagewise.StagePackedStageWiseModel(*, name, framework, solver, solver_arrays, stages, dTmin, z_restriction, min_dqda, minimisation_goal, non_isothermal_model, integers, tol, solver_options=None)[source]

Bases: StageWiseModel

StageWise model with integer-stage symmetry reduced for TDM solves.

Parameters:

  • name (str)

  • framework (Literal['TDM', 'ESM', 'PDM'])

  • solver (Literal['couenne', 'ipopt-pyomo', 'ipopt-GEKKO', 'apopt'])

  • solver_arrays (PreparedSolverArrays)

  • stages (int)

  • dTmin (float)

  • z_restriction (list | None)

  • min_dqda (float)

  • minimisation_goal (Literal['hot utility', 'cold utility', 'total utility', 'utility costs', 'heat recovery', 'total cost', 'variable total cost', 'dQ/dA obj'])

  • non_isothermal_model (bool)

  • integers (bool)

  • tol (float)

  • solver_options (Mapping[str, Any] | Sequence[str] | None)

set_stage_wise_superstructure()[source]

Create StageWise variables, constraints, and binaries.

Return type:

None

Stage-packing constraints for HEN integer model variants.

OpenPinch.services.heat_exchanger_network_synthesis.unit_models.stage_packing.add_recovery_stage_packing_constraints(model)[source]

Force active recovery stages to be contiguous in integer models.

Parameters:

model (Any)

Return type:

None

Internal heat exchanger network problem shell behind the synthesis service.

exception OpenPinch.services.heat_exchanger_network_synthesis.unit_models.problem.ModelSliceUnavailableError[source]

Bases: NotImplementedError

Raised when a later migration slice is asked to run too early.

class OpenPinch.services.heat_exchanger_network_synthesis.unit_models.problem.InternalHeatExchangerNetworkProblem(solver_arrays, name='', framework='TDM', solver='couenne', dTmin=0.1, min_dqda=0.0, z_restriction=None, minimisation_goal='hot utility', non_isothermal_model=False, integers=True, parent=None, tol=0.001, solver_options=None, stage_selection='automated', stages=None, synthesis_task_id=None, pinch_decompositions=None)[source]

Bases: object

OpenPinch-owned replacement for source HeatExchangerNetworkProblem.

This object is private solver state. HENS-07 constructs moved PDM and StageWise models from OpenPinch-prepared solver arrays and emits OpenPinch network/result data at the extraction boundary. HENS-08 still owns stage reduction and topology evolution.

Parameters:
load_model(*, model_factories=None)[source]

Construct the private PDM or StageWise model for this task.

Parameters:

model_factories (Mapping[str, Any] | None)

Return type:

None

get_solution(*, print_output=True, evolution=None, evolution_n_ad_branches=1, evolution_n_rm_branches=1, evolution_max_parallel=1, evolution_no_improvement_patience=None, model_factories=None)[source]

Load, solve, and return the private solved model for this task.

Parameters:

  • print_output (bool)

  • evolution (bool | None)

  • evolution_n_ad_branches (int)

  • evolution_n_rm_branches (int)

  • evolution_max_parallel (int)

  • evolution_no_improvement_patience (int | None)

  • model_factories (Mapping[str, Any] | None)

Return type:

Any

extract_network(*, run_id)[source]

Convert the solved private case into an OpenPinch network result.

Parameters:

run_id (str)

Return type:

HeatExchangerNetwork

extract_result(*, run_id, problem_id=None, workspace_variant=None, period_id=None)[source]

Return the serializable result data for the service boundary.

Parameters:

  • run_id (str)

  • problem_id (str | None)

  • workspace_variant (str | None)

  • period_id (str | None)

Return type:

HeatExchangerNetworkSynthesisResult

remove_unused_stages(case)[source]

Apply the source stage-utilisation reduction after PDM/TDM solves.

Return type:

StageWiseModel

Units and Scalar Helpers

Value supports both ordinary scalar quantities and discrete-period values with period_ids and normalised weights. This makes it suitable for both deterministic reports and period-weighted scenario data.

Unit-aware scalar and multiperiod value wrapper powered by Pint quantities.

class OpenPinch.classes.value.Value(data=None, unit=None)[source]

Bases: object

Thin wrapper around a Pint Quantity with serialization helpers.

Create a scalar or multiperiod value from data and optional unit.

Parameters:

unit (str)

property value

Return scalar or per-period magnitudes for multiperiod values.

property min: Value

Return the minimum stored magnitude as a scalar Value.

property max: Value

Return the maximum stored magnitude as a scalar Value.

property mean: Value

Return the arithmetic mean stored magnitude as a scalar Value.

property weighted_mean: Value

Return the weighted mean stored magnitude as a scalar Value.

property median: Value

Return the median stored magnitude as a scalar Value.

property period_values: ndarray

Return the raw numpy magnitudes for each stored period.

property values: list[float]

Return magnitudes as a JSON-friendly list for period-value compatibility.

property weights: ndarray

Return optional passive period weights carried with this value.

property num_periods: int

Return the number of stored magnitudes.

property unit

Return the unit in a human-friendly compact representation.

to(new_unit)[source]

Return a copy converted to new_unit.

Parameters:

new_unit (str)

Return type:

Value

mutable_copy()[source]

Return an independent writable copy of this value.

Return type:

Value

to_dict()[source]

Serialise the value into a JSON-friendly dictionary.

classmethod from_dict(data)[source]

Instantiate from a scalar or multiperiod serialized mapping.

Process Component Models

Process components are live model mutations attached after preparation and before rerunning targets. The direct process MVR component owns the original stream records, replacement streams, per-period stage results, and activation/deactivation state used by workspace comparison studies.

Lightweight base records for process components.

class OpenPinch.services.components.process_components.ProcessComponent(id, problem, component_type, active=True)[source]

Bases: object

Base class for memory-only process components.

Parameters:
activate()[source]

Activate the component.

deactivate()[source]

Deactivate the component.

MVR-specific process component records and factory.

class OpenPinch.services.components.process_mvr.ProcessMVRComponent(id, problem, component_type='process_mvr', active=True, settings=<factory>, source_selectors=<factory>, stream_records=<factory>)[source]

Bases: ProcessComponent

Memory-only direct process MVR component.

Parameters:
activate()[source]

Use the MVR replacement streams in subsequent targeting.

deactivate()[source]

Restore the original source streams for subsequent targeting.

work_for_zone(zone, *, period_id=None, period_idx=None)[source]

Return active compressor work assigned to streams inside zone.

Parameters:

  • zone (Zone)

  • period_id (str | None)

  • period_idx (int | None)

Return type:

float

OpenPinch.services.components.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, max_stage_t_sat_lift=None, eta_mvr_comp=None, eta_motor=None, options=None, period_id=None)[source]

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)

  • max_stage_t_sat_lift (float | None)

  • eta_mvr_comp (float | None)

  • eta_motor (float | None)

  • options (dict | None)

  • period_id (str | None)

Return type:

ProcessMVRComponent

Direct process-gas MVR component solver.

class OpenPinch.services.components.direct_mvr.direct_gas_mvr.DirectGasMVROutputUnits(temperature='degC', pressure='kPa', enthalpy='kJ/kg', heat_flow='kW')[source]

Bases: object

Units used for public direct-MVR outputs.

Parameters:

  • temperature (str)

  • pressure (str)

  • enthalpy (str)

  • heat_flow (str)

class OpenPinch.services.components.direct_mvr.direct_gas_mvr.DirectGasMVRSettings(n_stages=1, mvr_stage_t_lift=None, mvr_stage_pressure_ratio=None, liquid_injection=False, eta_mvr_comp=0.7, eta_motor=0.95, dt_diff_max=0.1)[source]

Bases: object

User-facing settings for one direct gas MVR solve.

Parameters:

  • n_stages (int)

  • mvr_stage_t_lift (float | None)

  • mvr_stage_pressure_ratio (float | None)

  • liquid_injection (bool)

  • eta_mvr_comp (float)

  • eta_motor (float)

  • dt_diff_max (float)

class OpenPinch.services.components.direct_mvr.direct_gas_mvr.DirectGasMVRStageResult(source_stream, stage_index, p_in, p_out, t_in, t_discharge, t_hot_supply, t_target, heat_flow, work, h_hot_supply, h_target, th_curve, linearised_profile, q_liquid_injection=0.0, liquid_injection_applied=False, temperature_unit='degC', pressure_unit='kPa', enthalpy_unit='kJ/kg', heat_flow_unit='kW', source_mass_flow=0.0, hot_mass_flow=0.0, liquid_injection_ratio=0.0)[source]

Bases: object

Solved accounting for one direct gas MVR stage.

Parameters:
class OpenPinch.services.components.direct_mvr.direct_gas_mvr.DirectGasMVRStreamSolveResult(replacement_streams, stage_results=<factory>)[source]

Bases: object

Solved direct gas MVR streams for one source stream at one period index.

Parameters:
OpenPinch.services.components.direct_mvr.direct_gas_mvr.coerce_positive_mvr_stage_count(value, *, context='Direct gas MVR')[source]

Return a validated integer direct-MVR stage count.

Parameters:

context (str)

Return type:

int

OpenPinch.services.components.direct_mvr.direct_gas_mvr.solve_direct_gas_mvr_stream(stream, *, settings, idx=0)[source]

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

Parameters:
Return type:

DirectGasMVRStreamSolveResult

Thermal Cycle and Cogeneration Unit Models

These classes support the advanced Heat Pump, refrigeration, and utility system workflows documented in OpenPinch.services.heat_pump_integration.heat_pump_and_refrigeration_entry. They are primarily useful for advanced users who want to inspect or construct detailed cycle configurations directly.

Cycle-specific heat pump unit model classes.

Simple vapour-compression heat pump cycle utilities built on CoolProp.

class OpenPinch.services.heat_pump_integration.unit_models.vapour_compression_cycle.VapourCompressionCycle[source]

Bases: object

Single vapour-compression heat pump cycle.

Supports an optional internal heat exchanger.

Initialise an unsolved cycle with default operating assumptions.

property system: dict[str, str]

Unit metadata associated with stored cycle-state values.

property state

Underlying CoolProp fluid state used during cycle calculations.

property cycle_states: list[dict[str, float]]

Container holding the six solved cycle states.

property state_points: list[dict[str, float]]

State points around the cycle.

property Hs: Sequence[float]

Specific enthalpies for the solved state points.

property Ss: Sequence[float]

Specific entropies for the solved state points.

property Ts: Sequence[float]

Temperatures for the solved state points.

property Ps: Sequence[float]

Pressures for the solved state points.

property q_evap: float | None

Specific evaporator duty.

property Q_evap: float | None

Total evaporator duty.

property q_cas_cool: float | None

Specific cooling passed to a lower cascade stage.

property Q_cas_cool: float | None

Total cooling passed to a lower cascade stage.

property q_cool: float | None

Specific cooling delivered to the process.

property Q_cool: float | None

Total cooling delivered to the process.

property q_cond: float | None

Specific condenser duty.

property Q_cond: float | None

Total condenser duty.

property q_cas_heat: float | None

Specific heat passed to an upper cascade stage.

property Q_cas_heat: float | None

Total heat passed to an upper cascade stage.

property q_heat: float | None

Specific heat delivered to the process.

property Q_heat: float | None

Total heat delivered to the process.

property w_net: float | None

Specific compressor work input.

property work: float | None

Total compressor work input.

property penalty: float | None

Total penalty for excessive subcooling.

property m_dot: float | None

Working fluid mass flow rate.

property dtcont: float | None

Minimum temperature approach carried into derived stream profiles.

property COP_h: float | None

Heating coefficient of performance based on process heat duty.

property COP_r: float | None

Cooling coefficient of performance based on process cooling duty.

property dt_diff_max: float | None

Maximum piecewise temperature error for derived stream profiles.

property refrigerant: str | None

Refrigerant name used for the solved cycle.

property T_evap: float | None

Evaporating temperature in degrees Celsius.

property T_evap_sat_vap: float | None

Saturated vapour temperature at evaporating pressure in degrees Celsius.

property T_cond: float | None

Condensing temperature in degrees Celsius.

property T_cond_sat_liq: float | None

Saturated liquid temperature at condensing pressure in degrees Celsius.

property dT_superheat: float

Applied compressor-inlet superheat.

property dT_subcool: float

Applied condenser-outlet subcooling.

property eta_comp: float

Isentropic compressor efficiency.

property dT_ihx_gas_side: float

Gas-side temperature change across the internal heat exchanger.

property solved: bool

Flag if the cycle has been solved or not.

solve(T_evap, T_cond, *, dtcont, dT_superheat=0.0, dT_subcool=0.0, eta_comp=0.7, refrigerant='water', dT_ihx_gas_side=10.0, Q_heat=None, Q_cas_heat=0.0, Q_cool=None, Q_cas_cool=0.0, is_heat_pump=True)[source]

Solve the heat pump cycle for the provided operating point.

Parameters:

  • T_evap (float) – Liquid saturation temperature in the evaporator [deg C].

  • T_cond (float) – Gas saturation temperature in the condenser [deg C].

  • dtcont (float) – Minimum temperature approach used by HPR targeting [K].

  • dT_superheat (float, optional) – Degree of superheating of the suction gas, supplied by the process [K].

  • dT_subcool (float, optional) – Degree of subcooling after the condenser, heat delivered to the process [K].

  • eta_comp (float, optional) – Isentropic efficiency of the compressor [-].

  • refrigerant (str, optional) – Cycle refrigerant; supports multi-component fluids.

  • dT_ihx_gas_side (float, optional) – Delta-T on the gas side of the internal heat exchanger [K].

  • Q_heat (float, optional) – Heat delivered to the process [W]. Used for heat-pump and cascade configurations only.

  • Q_cas_heat (float, optional) – Extra condenser heat transferred to the next cascade cycle [W]. Used only for cascade heat pump configurations.

  • Q_cool (float, optional) – Cooling delivered to the process [W]. Used for refrigeration and cascade configurations only.

  • Q_cas_cool (float, optional) – Extra evaporator cooling transferred to the next cascade cycle [W]. Used only for cascade refrigeration configurations.

  • is_heat_pump (bool, optional) – Flag to indicate if the cycle is in heat pump or refrigeration mode.

Returns:

Compressor power requirement for the solved operating point [W].

Return type:

float

build_stream_collection(include_cond=False, include_evap=False, is_process_stream=False, dtcont=0.0, dt_diff_max=0.5)[source]

Approximate condenser and evaporator duties as piecewise stream segments.

Parameters:
Return type:

StreamCollection

Parallel heat pump network assembled from independent subcycles.

class OpenPinch.services.heat_pump_integration.unit_models.parallel_vapour_compression_cycles.ParallelVapourCompressionCycles[source]

Bases: object

Parallel set of vapour-compression heat pumps solved independently.

Initialise an unsolved parallel heat pump model.

property Q_evap: float | None

Total evaporator duty across all subcycles.

property Q_evap_arr: ndarray | None

Per-subcycle evaporator duties.

property Q_cas_cool: float | None

Total cooling handed off to cascade coupling, if used.

property Q_cas_cool_arr: ndarray | None

Per-subcycle cooling handed off to cascade coupling.

property Q_cool: float | None

Total cooling delivered to the process.

property Q_cool_arr: ndarray | None

Per-subcycle cooling delivered to the process.

property Q_cond: float | None

Total condenser duty across all subcycles.

property Q_cond_arr: ndarray | None

Per-subcycle condenser duties.

property Q_cas_heat: float | None

Total heat handed off to any downstream cascade usage.

property Q_cas_heat_arr: ndarray | None

Per-subcycle heat handed off to any downstream cascade usage.

property Q_heat: float | None

Total heat delivered to the process.

property Q_heat_arr: ndarray | None

Per-subcycle heat delivered to the process.

property work: float | None

Total compressor work across all subcycles.

property work_arr: ndarray | None

Per-subcycle compressor work.

property penalty: float | None

Total penalty for excessive subcooling.

property dtcont: float | None

Minimum temperature approach propagated to derived stream profiles.

property COP_h: float | None

Heating coefficient of performance for the full network.

property COP_r: float | None

Cooling coefficient of performance for the full network.

property COP_o: float | None

Overall coefficient of performance based on heating plus cooling.

property dt_diff_max: float | None

Maximum piecewise temperature error for derived stream profiles.

property refrigerant: ndarray

Refrigerant assigned to each solved subcycle.

property T_evap: ndarray

Evaporating temperatures for each solved subcycle.

property T_cond: ndarray

Condensing temperatures for each solved subcycle.

property dT_superheat: ndarray

Applied superheat for each solved subcycle.

property dT_subcool: ndarray

Applied subcooling for each solved subcycle.

property eta_comp: ndarray

Compressor efficiency used for each solved subcycle.

property dT_ihx_gas_side: ndarray

Internal heat exchanger gas-side delta-T for each subcycle.

property num_cycles: int

Number of simple heat pump subcycles in the network.

property subcycles: List[VapourCompressionCycle]

Solved simple heat pump subcycles that make up the network.

property solved: bool

Whether the parallel heat pumps have all been solved successfully.

solve(T_evap, T_cond, *, dtcont, dT_superheat=0.0, dT_subcool=0.0, eta_comp=0.7, refrigerant='water', dT_ihx_gas_side=10.0, Q_heat=None, Q_cool=None, Q_heat_base=None, x_heat_split=None, Q_heat_available=None, Q_cool_base=None, x_cool_split=None, Q_cool_available=None, is_heat_pump=True)[source]

Solve a set of parallel simple heat pump cycles.

Parameters:

  • T_evap (np.ndarray) – Liquid saturation temperatures in the evaporator [deg C].

  • T_cond (np.ndarray) – Gas saturation temperatures in the condenser [deg C].

  • dtcont (float) – Minimum temperature approach used by HPR targeting [K].

  • dT_superheat (np.ndarray, optional) – Degree of superheating of the suction gas [K].

  • dT_subcool (np.ndarray, optional) – Degree of subcooling after the condenser [K].

  • eta_comp (float, optional) – Isentropic efficiency of the compressor [-].

  • refrigerant (List[str] | str, optional) – Cycle refrigerants; one per heat pump or a scalar value.

  • dT_ihx_gas_side (np.ndarray | float, optional) – Delta-T on the gas side of the internal heat exchanger [K].

  • Q_heat (np.ndarray | float | None, optional) – Heat delivered to the process [W].

  • Q_cool (np.ndarray | float | None, optional) – Cooling delivered to the process [W].

  • is_heat_pump (bool, optional) – Flag to indicate if the cycle is in heat pump or refrigeration mode.

  • Q_heat_base (float | None)

  • x_heat_split (ndarray | None)

  • Q_heat_available (ndarray | None)

  • Q_cool_base (float | None)

  • x_cool_split (ndarray | None)

  • Q_cool_available (ndarray | None)

Returns:

Total compressor power requirement for the solved operating point [W].

Return type:

float

build_stream_collection(include_cond=False, include_evap=False, is_process_stream=False, dtcont=0.0, dt_diff_max=0.5)[source]

Combine piecewise stream approximations from every solved subcycle.

Parameters:
Return type:

StreamCollection

Cascade heat pump network assembled from staged subcycles.

class OpenPinch.services.heat_pump_integration.unit_models.cascade_vapour_compression_cycle.CascadeVapourCompressionCycle[source]

Bases: object

Cascade of vapour-compression heat pumps coupled through cascade exchangers.

Initialise an unsolved cascade with no configured subcycles.

property Q_evap: float | None

Total evaporator duty across all subcycles.

property Q_evap_arr: float | None

Per-subcycle evaporator duties.

property Q_cas_cool: float | None

Total cooling handed off to lower cascade stages.

property Q_cas_cool_arr: float | None

Per-subcycle cooling handed to lower cascade stages.

property Q_cool: float | None

Total cooling delivered to the process.

property Q_cool_arr: float | None

Per-subcycle cooling delivered to the process.

property Q_cond: float | None

Total condenser duty across all subcycles.

property Q_cond_arr: float | None

Per-subcycle condenser duties.

property Q_cas_heat: float | None

Total heat supplied to upper cascade stages.

property Q_cas_heat_arr: float | None

Per-subcycle heat supplied to upper cascade stages.

property Q_heat: float | None

Total heat delivered to the process.

property Q_heat_arr: float | None

Per-subcycle heat delivered to the process.

property work: float | None

Total compressor work, or the infeasibility penalty while unsolved.

property work_arr: float | None

Per-subcycle compressor work.

property penalty: float | None

Total penalty for excessive subcooling.

property dtcont: float | None

Minimum temperature approach propagated to derived stream profiles.

property COP_h: float | None

Heating coefficient of performance for the full cascade.

property COP_r: float | None

Cooling coefficient of performance for the full cascade.

property COP_o: float | None

Overall coefficient of performance based on heating plus cooling.

property dt_diff_max: float | None

Maximum piecewise temperature error for derived stream profiles.

property refrigerant: ndarray

Refrigerant assigned to each solved subcycle.

property T_evap: ndarray

Evaporating temperatures for each solved subcycle.

property T_cond: ndarray

Condensing temperatures for each solved subcycle.

property dT_superheat: ndarray

Applied superheat for each solved subcycle.

property dT_subcool: ndarray

Applied subcooling for each solved subcycle.

property eta_comp: ndarray

Compressor efficiency used for each solved subcycle.

property dT_ihx_gas_side: ndarray

Internal heat exchanger gas-side delta-T for each subcycle.

property dt_cascade_hx: float

Minimum approach temperature enforced between neighbouring stages.

property num_cycles: int

Number of simple heat pump subcycles in the cascade.

property subcycles: List[VapourCompressionCycle]

Solved simple heat pump subcycles that make up the cascade.

property solved: bool

Whether the cascade has been solved successfully.

solve(T_evap, T_cond, *, dtcont, dT_superheat=0.0, dT_subcool=0.0, eta_comp=0.7, refrigerant='water', dT_ihx_gas_side=10.0, Q_heat=None, Q_cool=None, Q_heat_base=None, x_heat_split=None, Q_heat_available=None, Q_cool_base=None, x_cool_split=None, Q_cool_available=None, dt_cascade_hx=1.0, is_heat_pump=True)[source]

Solve the heat pump cycle for the provided operating point.

Parameters:

  • T_evap (np.ndarray) – Liquid saturation temperature in the evaporator [deg C].

  • T_cond (np.ndarray) – Gas saturation temperature in the condenser [deg C].

  • dtcont (float) – Minimum temperature approach used by HPR targeting [K].

  • dT_superheat (np.ndarray, optional) – Degree of superheating of the suction gas, supplied by the process [K].

  • dT_subcool (np.ndarray, optional) – Degree of subcooling after the condenser, heat delivered to the process [K].

  • eta_comp (float, optional) – Isentropic efficiency of the compressor [-].

  • refrigerant (List[str], optional) – Cycle refrigerant; supports multi-component fluids.

  • dT_ihx_gas_side (np.ndarray | float, optional) – Delta-T on the gas side of the internal heat exchanger [K].

  • Q_heat (np.ndarray, optional) – Heat delivered to the process [W].

  • Q_cool (np.ndarray, optional) – Cooling delivered to the process [W].

  • dt_cascade_hx (float, optional) – Temperature difference between condensing and evaporating temperatures in the cascade heat exchanger.

  • is_heat_pump (bool, optional) – Flag to indicate if the cycle is in heat pump or refrigeration mode.

  • Q_heat_base (float | None)

  • x_heat_split (ndarray | None)

  • Q_heat_available (ndarray | None)

  • Q_cool_base (float | None)

  • x_cool_split (ndarray | None)

  • Q_cool_available (ndarray | None)

Returns:

Compressor power requirement for the solved operating point [W].

Return type:

float

build_stream_collection(include_cond=False, include_evap=False, is_process_stream=False, dtcont=0.0, dt_diff_max=0.5)[source]

Combine piecewise stream approximations from every solved subcycle.

Parameters:
Return type:

StreamCollection

Carnot-family HPR backend classes.

class OpenPinch.services.heat_pump_integration.unit_models.carnot_cycles.CascadeCarnotCycle[source]

Bases: object

Cascade Carnot backend with shared solve-state properties.

class OpenPinch.services.heat_pump_integration.unit_models.carnot_cycles.ParallelCarnotCycles[source]

Bases: object

Parallel simple Carnot heat-pump, heat-engine, and recovery stages.

Mechanical vapour recompression cycle utilities built on CoolProp.

class OpenPinch.services.heat_pump_integration.unit_models.mechanical_vapour_recompression_cycle.MechanicalVapourRecompressionCycle[source]

Bases: VapourCompressionCycle

Single-stage mechanical vapour recompression model.

The open stage is represented as source vapour at the evaporating pressure, dry real compression to the condensing pressure, post-compression internal liquid-injection desuperheating, process-side condensation, and optional liquid subcooling.

Initialise an unsolved MVR cycle with water as the default fluid.

property Hs: Sequence[float]

Specific enthalpies for the solved state points.

property Ss: Sequence[float]

Specific entropies for the solved state points.

property Ts: Sequence[float]

Temperatures for the solved state points.

property Ps: Sequence[float]

Pressures for the solved state points.

property eta_mvr_comp: float

MVR compressor isentropic efficiency.

property eta_motor: float

Motor efficiency converting shaft work to electrical work.

property shaft_work: float | None

Compressor shaft work before motor losses.

property source_m_dot: float | None

Vapour mass flow generated or received before liquid injection.

property liquid_injection_ratio: float

Injected liquid mass per unit source vapour mass.

property q_source: float | None

Specific source heat needed to generate inlet vapour.

property q_desuperheat: float | None

External specific desuperheating heat after internal injection.

property q_liquid_injection: float | None

Dry-compression superheat consumed by injection per source mass.

property q_condense: float | None

Condensation and subcooling heat per source mass.

property q_latent_condense: float | None

Latent condensation heat per source mass.

property q_subcool_process: float | None

Process subcooling heat per source mass.

property process_split: float

Fraction of post-injection vapour condensed for process heating.

property process_heat: float

External useful process heat for the stored process split.

property process_m_dot_out: float | None

Post-injection vapour mass flow sent to the next open MVR stage.

property work: float | None

Total electrical work, or finite infeasibility work if unsolved.

property COP_h: float | None

Total condenser-duty coefficient of performance based on electric work.

property COP_process_h: float | None

Useful process-heating coefficient of performance.

property COP_r: float | None

Evaporator-duty coefficient of performance based on electric work.

solve_from_source_heat(T_evap, T_cond, *, Q_source, dT_superheat=0.0, dT_subcool=0.0, eta_mvr_comp=0.7, eta_motor=1.0, fluid='Water', liquid_injection=True, process_split=1.0, source_heat_is_external=True)[source]

Solve an open MVR stage from source heat.

The generated inlet vapour is saturated at T_evap plus any supplied dT_superheat. When source_heat_is_external is false, the source duty is retained for cycle accounting but omitted from build_stream_collection().

Parameters:
Return type:

float

solve_from_mass_flow(T_evap, T_cond, *, m_dot, dT_superheat=0.0, dT_subcool=0.0, eta_mvr_comp=0.7, eta_motor=1.0, fluid='Water', liquid_injection=True, process_split=1.0)[source]

Solve the MVR stage from inlet vapour mass flow.

This is primarily used by serial MVR cascades where a downstream stage receives the uncondensed discharge vapour from the previous stage.

Parameters:
Return type:

float

process_heat_components(process_split=None)[source]

Return external MVR heat components for a process condensation split.

When process_split is omitted, the components stored during solve_from_* are returned.

Parameters:

process_split (float | None)

Return type:

dict[str, float]

build_stream_collection(include_cond=False, include_evap=False, is_process_stream=False, dtcont=0.0, dt_diff_max=0.5)[source]

Build external MVR process-heating streams.

include_evap emits the source/generator duty only for cycles solved from external source heat. Serial cascade source heat is internal and is not emitted by this unit model.

Parameters:
Return type:

StreamCollection

Vapour-compression plus serial MVR cascade model.

class OpenPinch.services.heat_pump_integration.unit_models.vapour_compression_mvr_cascade.VapourCompressionMvrCascade[source]

Bases: object

Cascade top VC condenser heat into a serial MVR vapour train.

Initialise an unsolved VC+MVR cascade.

property solved: bool

Whether all stages solved successfully.

property vc_cycles: List[VapourCompressionCycle]

Solved low-stage vapour-compression cycles.

property mvr_cycles: List[MechanicalVapourRecompressionCycle]

Solved high-stage MVR cycles.

property subcycles: list

All solved subcycles in low-stage then high-stage order.

property source_split: float

Split of the hottest VC condenser duty used to generate MVR vapour.

property process_split: ndarray

MVR stage vapour fractions condensed for process heating.

property internal_heat: ndarray

Top-stage VC heat transferred internally to the first MVR source.

property direct_vc_heat: ndarray

VC condenser heat left as external process heat.

property mvr_stage_heat: ndarray

Useful MVR process heat from each serial stage.

property mvr_stage_mass_in: ndarray

Source vapour mass flow entering each MVR stage before injection.

property mvr_stage_mass_out: ndarray

Post-injection uncondensed vapour mass flow leaving each MVR stage.

property T_evap_mvr: ndarray

Derived MVR evaporating/saturation temperatures.

property T_cond_mvr: ndarray

Derived MVR condensing/saturation temperatures.

property Q_evap: float | None

External evaporator/source duty across VC stages.

property Q_evap_arr: ndarray

Per-stage external evaporator/source duties.

property Q_cond: float | None

External condenser/sink duty across all stages.

property Q_cond_arr: ndarray

Per-stage external condenser/sink duties.

property Q_heat: float | None

Total external useful heating duty.

property Q_heat_arr: ndarray

Per-stage external useful heating duties.

property Q_cool: float | None

Total external cooling/source duty.

property Q_cool_arr: ndarray

Per-stage external cooling/source duties.

property work: float | None

Total electric work, or finite infeasibility work if unsolved.

property work_arr: ndarray

Per-stage electric work.

property COP_h: float | None

Heating COP for the full cascade.

property penalty: list[float]

Finite infeasibility and soft-constraint penalties.

property T_evap: ndarray

Evaporating temperatures for VC and MVR stages.

property T_cond: ndarray

Condensing temperatures for VC and MVR stages.

solve(*, T_evap_vc, T_cond_vc, dT_lift_mvr, Q_heat_vc=None, mvr_source_split=0.0, mvr_process_split=None, Q_heat_base=None, x_heat_split=None, Q_heat_available=None, dT_subcool_vc=0.0, dT_subcool_mvr=0.0, dT_ihx_gas_side_vc=0.0, eta_comp=0.7, eta_mvr_comp=0.7, eta_motor=1.0, refrigerant='water', mvr_fluid='Water', dt_cascade_hx=0.0, dtcont=0.0)[source]

Solve the VC+MVR cascade for serial MVR lift and split variables.

Parameters:
Return type:

float

build_stream_collection(*, include_cond=True, include_evap=True, is_process_stream=False, dtcont=0.0, dt_diff_max=0.5, include_internal=False)[source]

Build external HPR streams, excluding internal cascade heat by default.

Parameters:
Return type:

StreamCollection

Brayton-cycle heat pump model used by advanced utility targeting workflows.

The class in this module wraps a TESPy network while exposing the shared OpenPinch heat pump cycle helper API.

class OpenPinch.services.heat_pump_integration.unit_models.brayton_heat_pump.SimpleBraytonHeatPumpCycle[source]

Bases: object

Brayton heat pump cycle using TESPy internally.

Public API mirrors the simple Rankine HeatPumpCycle class so the object is interchangeable in downstream code.

Notes

  • The solver uses Network.solve(mode="design").

  • Pressures are left to TESPy to determine (option A). The user provides compressor inlet/outlet temperatures and the heat duty in the HTHX (Q_ht). Compressor and turbine isentropic efficiencies must be specified.

  • The cycle-state mapping is: 0=C1 compressor inlet, 1=C2 compressor outlet, 2=C3 turbine inlet, 3=C4 turbine outlet.

Initialize an unsolved Brayton heat pump cycle container.

property cycle_states

Return cycle state data in cycle-state order.

Returns:

State dictionaries in cycle order: 0=compressor inlet, 1=compressor outlet, 2=turbine inlet, 3=turbine outlet.

Return type:

list[dict]

property Hs: Sequence[float]

Return state specific enthalpies.

Returns:

Enthalpy values [J/kg] for states 0..3.

Return type:

Sequence[float]

property Ts: Sequence[float]

Return state temperatures.

Returns:

Temperatures [degC] for states 0..3.

Return type:

Sequence[float]

property Ps: Sequence[float]

Return state pressures.

Returns:

Pressures [Pa] for states 0..3.

Return type:

Sequence[float]

property Ss: Sequence[float]

Return state specific entropies when available.

Returns:

Entropy values for states 0..3. Entries may be None when not populated by the underlying model.

Return type:

Sequence[float]

property Q_heat: float | None

Return configured heat-delivery target.

Returns:

Requested gas-cooler heat duty [kW].

Return type:

float or None

property Q_cool: float | None

Return low-temperature heat-rejection duty after solution.

Returns:

LTHX duty [kW].

Return type:

float or None

property work_net: float | None

Return net shaft work after solution.

Returns:

Compressor plus turbine power [kW] using TESPy sign convention.

Return type:

float or None

solve(T_comp_in, T_comp_out, dT_gc, Q_heat, eta_comp, eta_exp, is_recuperated, refrigerant=None)[source]

Solve the Brayton cycle using TESPy.

Parameters:

  • T_comp_in (float) – Compressor inlet temperature [degC] (state 1).

  • T_comp_out (float) – Compressor outlet temperature [degC] (state 2).

  • dT_gc (float) – Temperature difference between compressor outlet and turbine inlet: dT_gc = T_comp_out - T_turb_in.

  • Q_heat (float) – Heat delivered in the gas cooler [kW], positive for process heating.

  • eta_comp (float) – Compressor isentropic efficiency (fraction).

  • eta_exp (float) – Turbine/expander isentropic efficiency (fraction).

  • is_recuperated (bool) – Whether recuperation is requested. Currently ignored and downgraded to a warning.

  • refrigerant (Any, optional) – Working-fluid label stored for reporting.

Returns:

The cycle object is updated in place with solved states and duties.

Return type:

None

Raises:

RuntimeError – If TESPy solves but result extraction fails.

get_hp_th_profiles()[source]

Return hot- and cold-side T-h profiles.

Returns:

(HTHX_profile, LTHX_profile).

Return type:

tuple[np.ndarray, np.ndarray]

get_hp_hot_and_cold_streams()[source]

Convert solved profiles to hot and cold utility stream collections.

Returns:

Hot streams from HTHX and cold streams from LTHX.

Return type:

tuple[StreamCollection, StreamCollection]

build_stream_collection(include_cond=False, include_evap=False, is_process_stream=False)[source]

Build a combined stream collection for selected heat exchangers.

Parameters:

  • include_cond (bool, default=False) – Include hot-side (gas-cooler) streams.

  • include_evap (bool, default=False) – Include cold-side (gas-heater) streams.

  • is_process_stream (bool, default=False) – Accepted for the shared stream-building API.

Returns:

Aggregated stream collection based on selected sides.

Return type:

StreamCollection

Multi-stage steam turbine targeting utilities.

class OpenPinch.services.power_cogeneration.unit_models.multi_stage_steam_turbine.MultiStageSteamTurbine[source]

Bases: object

Mutable multi-stage steam turbine solver for pinch targeting.

property solved: bool

Return True after solve() has produced a valid result.

property result: TurbineSolveResult

Return the validated solve result for the most recent run.

property stages: list[TurbineStageResult]

Return the per-stage turbine results from the most recent run.

property total_work: float

Return the total shaft work recovered by the solved turbine train.

solve(temperatures, heat_flows, *, mode, T_in=None, P_in=None, T_sink=None, model='Medina-Flores et al. (2010)', min_eff=0.1, load_frac=1.0, mech_eff=1.0, is_high_p_cond_flash=False)[source]

Solve a turbine targeting problem and return total work plus details.

Parameters:
Return type:

tuple[float, dict]