PinchWorkspace

OpenPinch.PinchWorkspace manages named OpenPinch.PinchProblem cases. The public vocabulary is consistently case-oriented.

Golden Path

from OpenPinch import PinchWorkspace

workspace = PinchWorkspace("crude_preheat_train.json", project_name="Site")
baseline = workspace.case("baseline")
baseline.target.direct_heat_integration()

retrofit = workspace.scenario("retrofit", dt_cont_multiplier=0.8)
retrofit.target.direct_heat_integration()

comparison = workspace.compare_cases("baseline", "retrofit")

Interaction Matrix

Surface	Purpose	Return	State effect	Dependency
construction, load, case, use_case, list_cases	Load, retrieve, select, and list named cases	problem or names	prepare/select	base
scenario	Create an unsolved case from an existing case with named overrides	problem	add case	base
cases(names).target.* and cases(names).design.*	Run one named workflow across an ordered case set	ordered case result	per-case	method-specific
cases(names).summary_frames(), metrics(), and reports()	Observe every selected solved case and preserve per-case failures	result and error mappings	none	base
cases(names).export_excel(directory)	Export each case workbook into a distinctly named case subdirectory	result and error mappings	explicit files	excel
compare_cases and compare_to	Compare cached numerical summaries	dataframe	none	base
target, design, components, plot, config	Forward to the active case	active-case accessor	method-specific	method-specific
update_options and set_dt_cont_multiplier	Change persistent fallback values on a named or active case	none	invalidates case	base
summary_frame, metrics, report, validation and state properties	Observe the selected case without solving	dataframe, mapping, report, or record	none	base
save_bundle, load_bundle, to_problem_json	Persist or recover case inputs	path, workspace, or mapping	explicit persistence	base
export_excel and show_dashboard	Explicit output side effects for the active case	path or dashboard handle	none	output-specific

Observation methods do not solve an unsolved scenario. Call the desired target or design method first. Method arguments remain ephemeral; update_options(...) changes stored fallbacks.

Batch target and design namespaces are intentionally separate: a target batch does not advertise HEN design methods, and a design batch does not advertise targeting methods. One case failing does not discard successful cases; inspect outcome.errors before using outcome.results.

Complete API

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

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)

Load a previously persisted workspace bundle.

Parameters:

path (str | Path)

Return type:

PinchWorkspace

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

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)

Return a structured validation report for one case input.

Parameters:

case_name (str | None)

list_cases()

Return the loaded case names in stable insertion order.

Return type:

list[str]

cases(names=None)

Return an ordered batch view over selected cases.

Parameters:

names (Iterable[str] | None)

Return type:

_CaseBatch

case(name=None)

Return the live PinchProblem for one named case.

Parameters:

name (str | None)

Return type:

PinchProblem

use_case(name)

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)

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)

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)

Validate one case input.

Parameters:

case_name (str | None)

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

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)

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)

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)

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)

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)

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)

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')

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)

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)

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

Parameters:

path (str | Path)

Return type:

Any

See Tutorial Coverage Map for every workspace operation and its executable tutorial owner.