Package-Root API

Process-engineer workflows begin with exactly these imports:

from OpenPinch import PinchProblem, PinchWorkspace

PinchProblem owns one prepared case. PinchWorkspace owns named cases, scenario creation, case batches, comparison, and persistence. Analysis methods are grouped under descriptive accessors such as problem.target, problem.design, problem.components, and problem.plot.

The package root intentionally remains small. Schemas, domain records, and analysis services have concrete owner modules for contributors, but process engineers do not need those imports for supported workflows.

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

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)[source]

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()[source]

Validate the currently loaded problem data without running targeting.

Return type:

TargetInput

validation_report()[source]

Return structured validation results without raising for bad inputs.

Return type:

ValidationReport

summary_frame(*, detailed=False, include_periods=False, include_weighted_average=False)[source]

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)[source]

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)[source]

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)[source]

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')[source]

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()[source]

Return canonical JSON-compatible problem inputs.

Return type:

Dict[str, Any]

set_dt_cont_multiplier(value, *, zone_name=None)[source]

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)[source]

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)[source]

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

class OpenPinch.PinchWorkspace(source=None, *, project_name='Site', baseline_name='baseline')[source]

Bases: object

Manage multiple named PinchProblem cases with a script-native API.

Parameters:

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

  • project_name (Optional[str])

  • baseline_name (str)

classmethod load_bundle(path)[source]

Load a previously persisted workspace bundle.

Parameters:

path (str | Path)

Return type:

PinchWorkspace

load(source, *, case_name=None, activate=True, project_name=None)[source]

Load or replace a named case and return a live validated case.

Parameters:

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

  • case_name (str | None)

  • activate (bool)

  • project_name (str | None)

Return type:

PinchProblem | None

validation_report(case_name=None)[source]

Return a structured validation report for one case input.

Parameters:

case_name (str | None)

list_cases()[source]

Return the loaded case names in stable insertion order.

Return type:

list[str]

cases(names=None)[source]

Return an ordered batch view over selected cases.

Parameters:

names (Iterable[str] | None)

Return type:

_CaseBatch

case(name=None)[source]

Return the live PinchProblem for one named case.

Parameters:

name (str | None)

Return type:

PinchProblem

use_case(name)[source]

Activate one named case and return it.

Parameters:

name (str)

Return type:

PinchProblem

scenario(name, *, base=None, options=None, replace_options=False, dt_cont_multiplier=None, activate=False)[source]

Create and return an unsolved named scenario.

Parameters:

  • name (str)

  • base (str | None)

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

  • replace_options (bool)

  • dt_cont_multiplier (float | None)

  • activate (bool)

Return type:

PinchProblem

to_problem_json(*, case_name=None)[source]

Return canonical problem input for one named case.

Parameters:

case_name (str | None)

Return type:

Dict[str, Any]

property active_case_name: str | None

Return the currently active case name.

property target

Delegate the target accessor to the active case.

property plot

Delegate the plot accessor to the active case.

property design

Delegate the design accessor to the active case.

property components

Delegate the components accessor to the active case.

property config

Return the active case’s read-only configuration view.

property problem_data

Return the active case input.

property problem_filepath

Return the active case filepath when available.

property results

Return the active case results when available.

property master_zone

Return the active case master zone when available.

validate(case_name=None)[source]

Validate one case input.

Parameters:

case_name (str | None)

summary_frame(*, case_name=None, detailed=False, include_periods=False, include_weighted_average=False)[source]

Return the solved summary for one case.

Parameters:

  • case_name (str | None)

  • detailed (bool)

  • include_periods (bool)

  • include_weighted_average (bool)

Return type:

DataFrame

metrics(*, case_name=None, include_periods=False, include_weighted_average=False)[source]

Return typed metrics for one case.

Parameters:

  • case_name (str | None)

  • include_periods (bool)

  • include_weighted_average (bool)

report(*, case_name=None, include_periods=False, include_weighted_average=False)[source]

Return a typed report for one case.

Parameters:

  • case_name (str | None)

  • include_periods (bool)

  • include_weighted_average (bool)

export_excel(destination, *, case_name=None, include_periods=False, include_weighted_average=False)[source]

Export one case to an Excel workbook.

Parameters:

  • destination (str | Path)

  • case_name (str | None)

  • include_periods (bool)

  • include_weighted_average (bool)

Return type:

Any

set_dt_cont_multiplier(value, *, zone_name=None, case_name=None)[source]

Update one case multiplier and keep the stored case input in sync.

Parameters:

  • value (float)

  • zone_name (str | None)

  • case_name (str | None)

update_options(options, *, case_name=None, replace=False)[source]

Update one case’s options and keep the stored case input in sync.

Parameters:

  • options (dict[str, Any])

  • case_name (str | None)

  • replace (bool)

Return type:

PinchProblem

show_dashboard(*, case_name=None, zone=None, graph_data=None, page_title='OpenPinch Dashboard', value_rounding=2)[source]

Launch the dashboard for one case.

Parameters:

  • case_name (str | None)

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

  • page_title (str | None)

  • value_rounding (int)

Return type:

None

compare_to(other_problem, *, case_name=None, other_case_name=None, target_name=None, base_label='Base case', other_label='Scenario')[source]

Compare one workspace case to another problem or workspace case.

Parameters:

  • other_problem (PinchProblem | 'PinchWorkspace')

  • case_name (Optional[str])

  • other_case_name (Optional[str])

  • target_name (Optional[str])

  • base_label (str)

  • other_label (str)

Return type:

pd.DataFrame

compare_cases(base_case, other_case, *, target_name=None, base_label=None, other_label=None)[source]

Compare two cases in the same workspace.

Parameters:

  • base_case (str)

  • other_case (str)

  • target_name (str | None)

  • base_label (str | None)

  • other_label (str | None)

Return type:

DataFrame

save_bundle(path)[source]

Persist the current workspace, syncing any live case edits first.

Parameters:

path (str | Path)

Return type:

Any

See Also