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(...)

Bundle Contract

Workspace bundles use schema version 2. Each item in variants stores its canonical problem mapping under case_input. Version 1, unknown versions, the retired payload field, and unknown bundle fields are rejected; the pre-release API does not provide a compatibility loader.

Core Workflow Members

The main user-facing workflow members are case(), use_case(), copy_case(), list_cases(), get_case_input(), 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. That live case can use problem.target.exergy(...) and the matching exergetic plot accessors exactly like any other PinchProblem.

Serializable variant surface

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

solve_variant() does not currently normalize a dedicated exergy workflow name. Use the live-case PinchProblem surface when you need the exergy post-processing accessor.

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_input(name)

Return a defensive copy of one stored case input.

Parameters:

name (str)

Return type:

Dict[str, Any]

input_view(name)

Return a frontend-friendly editable case input view.

Parameters:

name (str)

Return type:

VariantInputView

validate_variant(name)

Return a structured validation report for one case input.

Parameters:

name (str)

validation_report(case_name=None)

Return a structured validation report for one case input.

Parameters:

case_name (str | None)

set_variant_input(name, case_input, *, base=None)

Create or replace one stored case input.

Parameters:

• name (str)

• case_input (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 a deterministic comparison view across solved variants.

Parameters:

• variant_names (Iterable[str] | None)

• base (str | None)

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='baseline', new_name='new', activate=False)

Clone one existing case into a new named case.

Parameters:

• source_name (str)

• new_name (str)

• activate (bool)

Return type:

PinchProblem

scenario(name, *, base=None, options=None, replace_options=False, dt_cont_multiplier=None, activate=False, solve=False, workflow='target', workflow_options=None)

Create a named scenario from a base case and optional edits.

Parameters:

• name (str)

• base (str | None)

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

• replace_options (bool)

• dt_cont_multiplier (float | None)

• activate (bool)

• solve (bool)

• workflow (str)

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

Return type:

PinchProblem

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

Return one case input, 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 case input 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 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, format=None, periods='selected')

Return the solved summary for one case.

Parameters:

• case_name (str | None)

• detailed (bool)

• format (str | None)

• periods (str)

Return type:

DataFrame

metrics(*, case_name=None, solve=True, periods='selected')

Return typed metrics for one case.

Parameters:

• case_name (str | None)

• solve (bool)

• periods (str)

report(*, case_name=None, solve=True, periods='selected')

Return a typed report for one case.

Parameters:

• case_name (str | None)

• solve (bool)

• periods (str)

export_excel(results_dir=None, *, case_name=None, periods='selected')

Export one case to an Excel workbook.

Parameters:

• results_dir (str | Path | None)

• case_name (str | None)

• periods (str)

Return type:

Path

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:

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