PinchProblem

OpenPinch.classes.pinch_problem.PinchProblem is the primary single-case interface in the package. It owns the source inputs, validated problem data, prepared zone tree, solved targets, graph exports, stateful reruns, and several advanced post-processing helpers.

When To Use It

Use PinchProblem when you want:

• support for JSON, workbook, CSV-bundle, packaged sample-case, or in-memory inputs

• one object that keeps both the original case and the solved result state

• compact and detailed summary tables

• graph building and graph export without manually wiring result payloads

• notebook-friendly advanced workflows such as HPR screening or dt_cont sensitivity studies

• selected-state reruns through state_id and batch reruns through target_all_states()

Use PinchWorkspace instead when the study itself needs to keep multiple named cases and compare them over time.

Supported Sources

PinchProblem accepts these load shapes:

• TargetInput or plain mappings

• JSON files

• Excel files such as .xlsx and .xlsb

• a directory with streams.csv and utilities.csv

• a (streams_csv, utilities_csv) tuple

• a packaged sample-case name such as basic_pinch.json when no local file with that name exists

Lifecycle

The typical lifecycle is:

1. construct the wrapper with a project name or input source

2. call load() or pass the source at construction time

3. call validate() if you want a preflight check

4. call target()

5. inspect summaries, graphs, exports, state-specific reruns, or the prepared master_zone

When the source is a bare *.json filename and no local file exists, PinchProblem also resolves packaged sample cases such as basic_pinch.json or crude_preheat_train.json directly.

Core Workflow Members

The main user-facing workflow members are load(), validate(), target(), summary_frame(), export_excel(), compare_to(), set_dt_cont_multiplier(), update_options(), target_all_states(), and show_dashboard().

Stateful Workflows

When the prepared data contains multiple states, the main stateful surfaces are:

• state_ids for the canonical state_id -> idx mapping

• named problem.target.*(..., state_id="peak") reruns

• target_all_states(parallel=False | True | "thread" | "process") for batch solves across every canonical state

State selection happens at targeting time, not at load time. The cached result, summary frame, export surface, and graph payload then reflect the selected state.

Advanced Entry Points

Two descriptor families make PinchProblem broader than a simple wrapper:

problem.plot

Builds Plotly figures for composite curves, grand composite curves, net-load profiles, and related graph families from the cached solved state.

problem.target

Re-runs targeted advanced routines such as direct and indirect heat pump, refrigeration, cogeneration, or area/cost targeting against the prepared zone hierarchy. Named target workflows also accept state_id=... when a input data carries stateful values, and the refreshed summary/export surfaces then expose that selected state on the result rows.

Named target methods also accept zone_name=... and include_subzones=True when you want one zone-level or subtree-level rerun instead of the default root-case solve.

Those accessors are the high-level path into the package’s deeper analytical power without dropping all the way to the raw service modules.

Output and Inspection Surfaces

After solving, the main read and export surfaces are:

• summary_frame() for compact or detailed pandas views

• problem.plot.catalog() for the available graph inventory

• problem.plot.* for Plotly figures and raw graph payloads

• problem.plot.export(...) for standalone HTML graph files

• export_excel(...) for workbook output

• show_dashboard() for the Streamlit-based review surface

PinchProblem API

class OpenPinch.classes.pinch_problem.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])

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 state_ids: dict[str, int]

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

target_all_states(*, parallel=False, max_workers=None, preserve_cached_results=True)

Run default targeting once per canonical state id.

Parameters:

• parallel (bool | str) – False runs serially. True and "process" use a process pool, while "thread" uses a thread pool which is suitable for no-GIL Python builds.

• max_workers (int | None) – Optional executor worker limit for parallel runs.

• preserve_cached_results (bool) – Restore the original results cache after the batch run when True.

Return type:

dict[str, TargetOutput]

validate()

Validate the currently loaded problem data without running targeting.

Return type:

TargetInput

summary_frame(*, detailed=False)

Return the solved target summary as a pandas DataFrame.

Parameters:

detailed (bool)

Return type:

DataFrame

export_excel(results_dir=None)

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

Parameters:

results_dir (str | Path | None)

Return type:

Path

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

Compare the compact summaries of two solved problems.

Parameters:

• other_problem (PinchProblem)

• target_name (str | None)

• base_label (str)

• other_label (str)

Return type:

DataFrame

property problem_filepath: Path | 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 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.

classmethod from_json(data)

Build from an in-memory mapping and apply the normal input cleaners.

Parameters:

data (Dict[str, Any])

Return type:

PinchProblem

to_problem_json(*, canonical=False)

Return the currently loaded problem inputs.

Parameters:

canonical (bool)

Return type:

Dict[str, Any]

canonical_problem_json()

Return canonical mutable problem inputs with an explicit zone tree.

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_payload=None, page_title='OpenPinch Dashboard', value_rounding=2)

Launch the Streamlit dashboard for the analysed problem.

Parameters:

• zone (Zone | None)

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

• page_title (str | None)

• value_rounding (int)

Return type:

None

Heat Pump Integration Comparison

Older examples sometimes refer to broader helper-backed HPR comparison flows. The current object surface instead exposes the explicit advanced HPR routines on problem.target.*, described above and in Service Layer.

Relationship To Lower Layers

PinchProblem is a wrapper, not a separate solver. Under the hood it still validates the input data, prepares a Zone tree, runs the same targeting services documented in Service Layer, and then packages the outputs for summaries, graphs, and export.

If you need to mutate the prepared zone tree directly, inspect stream objects, or run only one analysis stage, move down to Service Layer and Domain Model.