PinchWorkspace

OpenPinch.classes.pinch_workspace.PinchWorkspace is the public multi-case interface in OpenPinch. It keeps named study cases, but each case still resolves to a real PinchProblem instance for targeting, plotting, summaries, export, and advanced workflows. It also exposes a second surface for serializable variant views that are useful for applications or frontend-oriented comparisons.

When To Use It

Use PinchWorkspace when you want:

• named baseline-versus-variant study cases

• script or notebook comparisons without rebuilding case-input helpers

• case copying, input editing, and bundle save/load in one object

• the normal PinchProblem workflow on each case once it is selected

• serializable comparison views in addition to live PinchProblem objects

Lifecycle

The typical lifecycle is:

1. construct the workspace from input data, an existing PinchProblem, or a packaged sample-case name

2. use case(...) or use_case(...) to work with the active PinchProblem

3. clone cases with copy_case(...) and mutate them with update_options(...) or set_dt_cont_multiplier(...)

4. compare cases with compare_cases(...) or solve serializable views with solve_variant(...)

5. persist the study with save_bundle(...)

Core Workflow Members

The main user-facing workflow members are case(), use_case(), copy_case(), list_cases(), get_case_payload(), update_options(), set_dt_cont_multiplier(), compare_cases(), solve_variant(), compare_variants(), save_bundle(), and load_bundle().

Two Related Surfaces

Live-case surface

case(), use_case(), target, plot, summary_frame(), export_excel(), and show_dashboard() all delegate to a real active PinchProblem.

Serializable variant surface

payload_view(), validate_variant(), solve_variant(), and compare_variants() return schema-backed views that are deterministic and easier to pass to another application layer.

Workflow Names and Support Levels

solve_variant() accepts the same high-level workflow names exposed on problem.target.* after normalizing case, hyphens, and spaces.

Stable workflows

target, direct_heat_integration, indirect_heat_integration

Advanced workflows

direct_heat_pump, indirect_heat_pump, direct_refrigeration, indirect_refrigeration, cogeneration, area_cost

The advanced workflows are supported, but the workspace marks them as advanced explicitly so consuming applications can surface that distinction.

Typical Pattern

from OpenPinch import PinchWorkspace

workspace = PinchWorkspace(
    source="crude_preheat_train.json",
    project_name="crude_preheat_train",
)
baseline = workspace.case("baseline")
workspace.copy_case("baseline", "wide_dt", activate=False)
workspace.set_dt_cont_multiplier(0.5, case_name="wide_dt")
comparison = workspace.compare_cases("baseline", "wide_dt")

For application-style usage:

view = workspace.solve_variant(
    "baseline",
    workflow="indirect_heat_integration",
)
comparison_view = workspace.compare_variants(["baseline", "wide_dt"])

PinchWorkspace API

class OpenPinch.classes.pinch_workspace.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

list_variants()

Return the case names in stable insertion order.

Return type:

list[str]

get_variant_payload(name)

Return a defensive copy of one stored payload.

Parameters:

name (str)

Return type:

Dict[str, Any]

payload_view(name)

Return a frontend-friendly editable payload view.

Parameters:

name (str)

Return type:

VariantPayloadView

validate_variant(name)

Return a structured validation report for one payload.

Parameters:

name (str)

set_variant_payload(name, payload, *, base=None)

Create or replace one stored payload.

Parameters:

• name (str)

• payload (TargetInput | Dict[str, Any])

• base (str | None)

Return type:

Dict[str, Any]

solve_variant(name, *, workflow='target', workflow_options=None)

Solve one case and return a serializable frontend-facing view.

Parameters:

• name (str)

• workflow (str)

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

Return type:

ScenarioVariantView

compare_variants(variant_names=None, *, base=None)

Return deterministic comparison payloads across solved variants.

Parameters:

• variant_names (Iterable[str] | None)

• base (str | None)

Return type:

ScenarioComparisonView

list_cases()

Return the loaded case names in stable insertion order.

Return type:

list[str]

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

copy_case(source_name, new_name, *, activate=False)

Clone one existing case into a new named case.

Parameters:

• source_name (str)

• new_name (str)

• activate (bool)

Return type:

PinchProblem

get_case_payload(name=None, *, canonical=True)

Return one case payload, optionally normalised to canonical form.

Parameters:

• name (str | None)

• canonical (bool)

Return type:

Dict[str, Any]

to_problem_json(*, case_name=None, canonical=True)

Return the payload for one case using PinchProblem naming.

Parameters:

• case_name (str | None)

• canonical (bool)

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 problem_data

Return the active case payload.

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 payload.

Parameters:

case_name (str | None)

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

Return the solved summary for one case.

Parameters:

• case_name (str | None)

• detailed (bool)

Return type:

DataFrame

export_excel(results_dir=None, *, case_name=None)

Export one case to an Excel workbook.

Parameters:

• results_dir (str | Path | None)

• case_name (str | None)

Return type:

Path

set_dt_cont_multiplier(value, *, zone_name=None, case_name=None)

Update one case multiplier and keep the stored payload 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 payload in sync.

Parameters:

• options (dict[str, Any])

• case_name (str | None)

• replace (bool)

Return type:

PinchProblem

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

Launch the dashboard for one case.

Parameters:

• case_name (str | None)

• graph_payload (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:

Path

classmethod configuration_field_metadata()

Return declarative metadata for editable configuration fields.

Return type:

list[ConfigurationFieldMetadata]

Relationship To PinchProblem

PinchWorkspace is not a second solver. It orchestrates multiple named case inputs and live PinchProblem cases on top of the same validation, preparation, targeting, graph, export, and stateful workflow surfaces documented for PinchProblem.

Use PinchProblem when you only need one case at a time. Use PinchWorkspace when the study itself has to remember multiple named cases.