Workflow Map

OpenPinch supports several valid entrypoints, but they are not interchangeable. The right one depends on what owns the study state, where the inputs come from, and whether you need a live notebook object, a typed service contract, or just the packaged learning assets.

Recommended Entry Points

Notebook-copy CLI

Use this when you want the packaged notebook series copied into your working directory. The CLI does not solve cases, validate data, or export results.

Packaged resource workflow

Use OpenPinch.resources when you want packaged sample cases or notebooks from Python without relying on filesystem-relative paths.

PinchProblem workflow

Use this for notebooks and scripts when you want one object that owns the problem definition, validation, prepared zone tree, solved result, graph accessors, summaries, state selection, and exports.

PinchWorkspace workflow

Use this for notebooks and scripts when you want named study cases, baseline-versus-variant comparison, serializable variant views, and bundle save/load on top of real PinchProblem cases.

Service-layer workflow

Use OpenPinch.main.pinch_analysis_service() when you want a typed request/response boundary for another application or automation layer.

Prepared-zone workflow

Use OpenPinch.services.input_data_processing.data_preparation.prepare_problem() and the lower-level service helpers only when you need to inspect or mutate the intermediate Zone hierarchy directly.

Decision Guide

Use the CLI when:

  • you want openpinch notebook -o notebooks

  • you want a maintained onboarding asset copied locally

  • you do not need a solve yet

Use OpenPinch.resources when:

  • you want to list, read, or copy packaged sample cases from Python

  • you want code to be explicit about where examples come from

  • you want notebook or sample-case assets without hard-coding repo paths

Use PinchProblem when:

  • you are working in notebooks or scripts

  • you want to load one case from JSON, Excel, CSV, or a packaged sample name

  • you want validation, summaries, graphs, exports, and advanced targeting on one object

  • you want access to problem.plot.*, problem.target.*, problem.state_ids, or problem.target_all_states()

Use PinchWorkspace when:

  • you need named baseline and variant cases in one session

  • you want to compare cases without rebuilding case-input management helpers

  • you want both live PinchProblem cases and serializable variant views in the same study

  • you want to persist the full study as a bundle

Use pinch_analysis_service when:

  • you are integrating OpenPinch into another codebase

  • you want a typed TargetInput -> TargetOutput boundary

  • you do not need the convenience wrapper state model

Use the lower-level service stack when:

  • you need direct access to the prepared Zone tree

  • you want to separate validation, preparation, targeting, and extraction

  • you are doing advanced or research-oriented post-processing

Workflow Layering

notebooks / scripts / external app
              |
              +--> openpinch notebook
              +--> OpenPinch.resources
              |
              v
PinchWorkspace / PinchProblem / pinch_analysis_service
              |
              v
      data_preprocessing_service
              |
              v
           Zone tree
              |
              v
direct / indirect / HPR / cogeneration services
              |
              v
   TargetOutput + summaries + graphs + exports

Typical User Paths

First-time user

openpinch notebook -o notebooks -> run notebook 01 -> inspect real PinchWorkspace and PinchProblem calls

Notebook user

PinchWorkspace(source="crude_preheat_train.json") -> copy_case -> set_dt_cont_multiplier -> compare_cases

Single-case script

PinchProblem("basic_pinch.json") -> validate -> target -> summary_frame -> plot.grand_composite_curve()

Stateful study

problem.state_ids -> problem.target.direct_heat_integration(state_id="peak") -> problem.target_all_states()

Advanced HPR study

base case -> problem.target.direct_heat_pump(...) -> compare summary rows and GCC / HPR graph surfaces

Programmatic integration

TargetInput schema -> pinch_analysis_service(...) -> TargetOutput

Where To Go Next

  • For runnable first workflows, go to Guides.

  • For the thermodynamic model behind these workflows, go to Fundamentals.

  • For the exact callable surfaces, go to API Reference.