PinchProblem

OpenPinch.PinchProblem is the canonical stateful workflow for one process-engineering case.

Lifecycle

prepared

Construction or load(...) validates and prepares streams, utilities, zones, periods, and configuration.

targeted

A descriptive target method stores the latest result. All-period methods additionally populate the ordered period_results cache.

designed

A descriptive design method returns a HEN design view with ranked network selection and grid rendering.

invalidated

Loading new input, changing stored options, changing the temperature-approach contribution, or mutating a process component clears results that no longer describe the prepared problem.

Interaction Matrix

Surface	Purpose	Return	State effect	Dependency
load, validate, validation_report, to_problem_json	Prepare, check, and serialize input	zone, report, or mapping	prepare or observe	base
target.direct_heat_integration, indirect_heat_integration, total_site_heat_integration, all_heat_integration	Core Pinch and Total Site analysis	target output	targeted	base
target.heat_exchanger_area_and_cost, exergy, energy_transfer	Enrich a thermal target	target output	targeted	base
target.carnot_*, vapour_compression_*, brayton_*, mvr_heat_pump	Model-specific HPR studies	target output	targeted	HPR extras by model
target.cogeneration and named turbine-model methods	Cogeneration screening	target output	targeted	base
target.all_periods.*	Mirror supported targeting over ordered periods	period-to-output mapping	period cache	method-specific
components.add_process_mvr, components.inventory	Add or inspect process MVR mutations	component or mapping	invalidates on mutation	HPR extras
design.*heat_exchanger_network, open_hens, pinch_design, thermal_derivative, network_evolution	HEN synthesis and improvement	design view	designed	HEN solver
summary_frame, metrics, report and state properties	Inspect prepared or cached state	dataframe, mapping, report, or record	none	base
plot.catalog, plot.data, and named plot methods	Inspect cached graph data or build a figure	catalog, mapping, or figure	none	plotting
plot.export, plot.export_gallery, export_excel, show_dashboard	Explicit publication side effects	paths or dashboard handle	none	output-specific

Argument Precedence

Effective arguments resolve as named keyword > options > stored config > default. Named keywords and options apply only to that call. Use update_options(...) when a later call should inherit a persistent engineering value. Configuration never stores which target or design method to run.

Process MVR Component Results

components.add_process_mvr(...) returns the component it created. Use engineering argument names such as compressor_efficiency and motor_efficiency. The returned object exposes active, activate(), deactivate(), original_streams, replacement_streams, stage_results_by_period, affected_zone_paths, and work_for_zone(). Changing component activity invalidates cached targets, so rerun the chosen target method afterward.

Complete API

class OpenPinch.PinchProblem(source=None, *, project_name='Site')

Bases: object

Typed orchestrator for loading input data and running targeting.

Parameters:

• source (TargetInput | JsonDict | PathLike | tuple[PathLike, PathLike] | None)

• project_name (Optional[str])

components

Descriptor returning a problem-bound component accessor.

design

Non-data descriptor exposing design workflows on problem instances.

plot

Bind the presentation-owned graph accessor to one problem instance.

target

Non-data descriptor exposing the explicit target accessor on instances.

load(source=None)

Load problem inputs from JSON, Excel, CSV, or an in-memory object.

Parameters:

source (TargetInput | Dict[str, Any] | str | Path | tuple[str | Path, str | Path] | None)

Return type:

Zone | None

property period_ids: dict[str, int]

Return the canonical period_id -> idx lookup for the loaded problem.

property config

Read-only snapshot of stored flat numerical configuration values.

property period_results

Ordered detached outputs from the latest all-period target workflow.

validate()

Validate the currently loaded problem data without running targeting.

Return type:

TargetInput

validation_report()

Return structured validation results without raising for bad inputs.

Return type:

ValidationReport

summary_frame(*, detailed=False, include_periods=False, include_weighted_average=False)

Return the solved target summary as a pandas DataFrame.

Parameters:

• detailed (bool)

• include_periods (bool)

• include_weighted_average (bool)

Return type:

DataFrame

metrics(*, include_periods=False, include_weighted_average=False)

Return typed summary metrics for the current solved result.

Parameters:

• include_periods (bool)

• include_weighted_average (bool)

Return type:

list[ReportMetric]

report(*, include_periods=False, include_weighted_average=False)

Return a typed report without writing any files.

Parameters:

• include_periods (bool)

• include_weighted_average (bool)

Return type:

ProblemReport

export_excel(destination, *, include_periods=False, include_weighted_average=False)

Export the solved target summary and problem tables to an Excel file.

Parameters:

• destination (str | Path)

• include_periods (bool)

• include_weighted_average (bool)

Return type:

Any

compare_to(other_problem, *, target_name=None, base_label='Base case', other_label='Scenario')

Compare numeric summary metrics of two solved problems.

Parameters:

• other_problem (PinchProblem)

• target_name (str | None)

• base_label (str)

• other_label (str)

Return type:

DataFrame

property problem_filepath: Any | None

Return the filepath of the problem that was loaded or supplied.

property problem_data: Dict[str, Any] | TargetInput | None

Return the raw problem definition that was loaded or supplied.

property results: TargetOutput | None

Return the cached targeting results, if targeting has been executed.

property master_zone: Zone | None

Return the prepared root zone after a successful load() pass.

property process_components: dict[str, Any]

Memory-only process components applied to the prepared model.

property hot_streams: StreamCollection

Hot process streams on the root analysis zone.

property cold_streams: StreamCollection

Cold process streams on the root analysis zone.

property hot_utilities: StreamCollection

Hot utility streams on the root analysis zone.

property cold_utilities: StreamCollection

Cold utility streams on the root analysis zone.

property project_name: str

Return the project label used for the root zone and exports.

to_problem_json()

Return canonical JSON-compatible problem inputs.

Return type:

Dict[str, Any]

set_dt_cont_multiplier(value, *, zone_name=None)

Update one zone-tree multiplier and rebuild the prepared analysis state.

Parameters:

• value (float)

• zone_name (str | None)

Return type:

Zone

update_options(options, *, replace=False)

Update the problem options in-place and rebuild the analysis state.

Parameters:

• options (Dict[str, Any])

• replace (bool)

Return type:

Zone

show_dashboard(*, zone=None, graph_data=None, page_title='OpenPinch Dashboard', value_rounding=2)

Launch the Streamlit dashboard for the analysed problem.

Parameters:

• zone (Zone | None)

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

• page_title (str | None)

• value_rounding (int)

Return type:

None

The operation-level inventory and tutorial owner for every member is published in Tutorial Coverage Map.