Getting Started

This is the fastest supported path from a clean environment to a solved OpenPinch case. It uses the packaged basic_pinch.json sample case so you can verify the installation before preparing your own data.

Install

Install the base package for core Python workflows:

python -m pip install openpinch

Install optional extras only when the workflow needs them:

Extra

Use when you need

Command

base

validation, targeting, summaries, schema-driven runs

python -m pip install openpinch

notebook

Jupyter notebooks, Plotly graph rendering, Excel import/export

python -m pip install "openpinch[notebook]"

dashboard

Streamlit dashboard review plus graph/export dependencies

python -m pip install "openpinch[dashboard]"

synthesis

solver-backed heat exchanger network synthesis

python -m pip install "openpinch[synthesis]" then idaes get-extensions

brayton_cycle

TESPy-backed Brayton-cycle tooling

python -m pip install "openpinch[brayton_cycle]"

OpenPinch currently targets Python 3.14.

Run the First Solve

from OpenPinch import PinchProblem

problem = PinchProblem("basic_pinch.json", project_name="basic_pinch")
validation = problem.validation_report()
result = problem.target()
summary = problem.summary_frame()

print(validation.valid)
print(summary[["Target", "Hot Utility Target", "Cold Utility Target"]])

When no local file named basic_pinch.json exists, PinchProblem resolves the packaged sample case that ships with OpenPinch. The same wrapper also loads JSON files, Excel workbooks, CSV bundles, TargetInput models, and plain mappings.

Read the Result

For a first pass, read the summary table in this order:

  1. Hot Utility Target

  2. Cold Utility Target

  3. Heat Recovery

  4. Hot Pinch and Cold Pinch

Then inspect graphs if you installed the notebook or dashboard extra:

gcc = problem.plot.grand_composite_curve()
catalog = problem.plot.catalog()

The Grand Composite Curve is usually the best first graph for utility placement and Heat Pump screening questions.

Use Named Studies When You Compare Cases

Use PinchWorkspace when the study has a baseline and variants:

from OpenPinch import PinchWorkspace

workspace = PinchWorkspace(
    source="crude_preheat_train.json",
    project_name="crude_preheat_train",
)
workspace.scenario("wide_dt", dt_cont_multiplier=0.5)
comparison = workspace.compare_cases("baseline", "wide_dt")

Use the CLI Only for Notebook Assets

The supported CLI copies packaged notebooks. It does not solve cases:

openpinch notebook -o notebooks

Use Python for validation, solves, graph export, Excel export, dashboards, and advanced targeting.

Use these pages instead: