Metadata-Version: 2.4
Name: OpenPinch
Version: 0.1.26
Summary: An advanced pinch analysis and total site integration toolkit
Project-URL: Homepage, https://github.com/waikato-ahuora-smart-energy-systems/OpenPinch
Project-URL: Issues, https://github.com/waikato-ahuora-smart-energy-systems/OpenPinch/issues
Author-email: Tim Walmsley <tim.walmsley@waikato.ac.nz>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.14
Requires-Dist: coolprop
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pint
Requires-Dist: pydantic
Requires-Dist: scipy
Provides-Extra: brayton-cycle
Requires-Dist: tespy; extra == 'brayton-cycle'
Provides-Extra: dashboard
Requires-Dist: openpyxl; extra == 'dashboard'
Requires-Dist: plotly; extra == 'dashboard'
Requires-Dist: pyxlsb; extra == 'dashboard'
Requires-Dist: streamlit; extra == 'dashboard'
Provides-Extra: full
Requires-Dist: ipykernel>=7.2.0; extra == 'full'
Requires-Dist: nbformat>=5.10.4; extra == 'full'
Requires-Dist: openpyxl; extra == 'full'
Requires-Dist: plotly; extra == 'full'
Requires-Dist: pyxlsb; extra == 'full'
Requires-Dist: streamlit; extra == 'full'
Requires-Dist: tespy; extra == 'full'
Provides-Extra: notebook
Requires-Dist: ipykernel>=7.2.0; extra == 'notebook'
Requires-Dist: nbformat>=5.10.4; extra == 'notebook'
Requires-Dist: openpyxl; extra == 'notebook'
Requires-Dist: plotly; extra == 'notebook'
Requires-Dist: pyxlsb; extra == 'notebook'
Description-Content-Type: text/markdown

# OpenPinch

OpenPinch is an open-source toolkit for advanced Pinch Analysis and Total Site Integration. It supports direct and indirect heat integration targeting, multi-utility studies, graph generation, Excel-based workflows, and programmatic analysis in Python.

## Install

Install the published package from PyPI for core CLI and Python usage:

```bash
python -m pip install openpinch
```

If you plan to run the packaged Jupyter notebooks, graph rendering, or Excel
I/O, install the notebook extra:

```bash
python -m pip install "openpinch[notebook]"
```

If you plan to launch the Streamlit dashboard, install the dashboard extra:

```bash
python -m pip install "openpinch[dashboard]"
```

If you need TESPy-backed Brayton-cycle tooling, install the Brayton-cycle
extra:

```bash
python -m pip install "openpinch[brayton_cycle]"
```

If you want the full optional surface in one install:

```bash
python -m pip install "openpinch[full]"
```

OpenPinch currently requires Python `>=3.14`.


## Notebook Workflow

OpenPinch ships with a notebook series for distinct outputs and workflows. Copy them into your working directory with:

```bash
openpinch notebook -o notebooks
```

To run the packaged notebooks in Jupyter, install the notebook extra first with `python -m pip install "openpinch[notebook]"`.

The packaged notebook series currently includes:

- `01_basic_pinch_and_dtcont_sensitivity.ipynb`
- `02_total_site_targets_and_sugcc.ipynb`
- `03_carnot_hpr_comparison.ipynb`

These notebooks are intended to be the main learning path for new users.


## Python Workflow

For script and notebook usage, the main single-case front door is
`PinchProblem`.

```python
from OpenPinch import PinchProblem

problem = PinchProblem("basic_pinch.json", project_name="basic_pinch")
problem.target()

summary = problem.summary_frame()
print(summary)

problem.export_excel("results")
problem.plot.export("graphs", graph_type="gcc")
```

For named study cases and bundle save/load, use `PinchWorkspace`:

```python
from OpenPinch import PinchWorkspace

workspace = PinchWorkspace(
    source="crude_preheat_train.json",
    project_name="crude_preheat_train",
)
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")
```

You can also build a payload directly from the validated schema models:

```python
from OpenPinch import pinch_analysis_service
from OpenPinch.lib.enums import StreamType
from OpenPinch.lib.schemas.io import StreamSchema, TargetInput, UtilitySchema

streams = [
    StreamSchema(
        zone="Process Unit",
        name="Reboiler Vapor",
        t_supply=200.0,
        t_target=120.0,
        heat_flow=8000.0,
        dt_cont=10.0,
        htc=1.5,
    ),
    StreamSchema(
        zone="Process Unit",
        name="Feed Preheat",
        t_supply=40.0,
        t_target=160.0,
        heat_flow=6000.0,
        dt_cont=10.0,
        htc=1.2,
    ),
]

utilities = [
    UtilitySchema(
        name="Cooling Water",
        type=StreamType.Cold,
        t_supply=25.0,
        t_target=35.0,
        heat_flow=120000.0,
        dt_cont=5.0,
        htc=0.8,
        price=12.0,
    )
]

payload = TargetInput(streams=streams, utilities=utilities)
result = pinch_analysis_service(payload, project_name="Example")
```

## Graphing and Dashboard

With the notebook or dashboard extra installed, graph generation in Python
looks like:

```python
figure = problem.plot.grand_composite_curve()
figure.show()
```

To launch the Streamlit dashboard after solving, install
`openpinch[dashboard]` and call:

```python
problem.show_dashboard()
```

## Highlights

- Multi-scale targeting for unit operation, process, site, community, and regional studies
- Direct heat integration and indirect integration through utility systems
- Multiple utility targeting, including non-isothermal utilities
- Composite Curve and Grand Composite Curve graph generation
- Excel workbook import and Excel summary export
- Packaged sample cases and notebook workflows
- Pydantic schema models for validated programmatic usage

## Documentation

Full documentation is available at:

https://openpinch.readthedocs.io/en/latest/

The documentation is organized around install, sample workflows, notebooks, graphing, and the public API.

## History

OpenPinch started in 2011 as an Excel workbook with macros. Since then it has expanded into Total Site Heat Integration, multiple utility targeting, retrofit targeting, cogeneration targeting, and related workflows. The Python implementation began in 2021 to bring those capabilities into a scriptable and testable package interface.

## Citation

In publications and forks, please cite and link the foundational article and this repository.

Timothy Gordon Walmsley, 2026. OpenPinch: An Open-Source Python Library for Advanced Pinch Analysis and Total Site Integration. Process Integration and Optimization for Sustainability. https://doi.org/10.1007/s41660-026-00729-6

## Testing

To run the test suite locally:

```bash
python -m pip install -e . pytest build "hatchling>=1.26"
pytest
```

## Contributors

Founder: Tim Walmsley, University of Waikato

Stephen Burroughs, Benjamin Lincoln, Alex Geary, Harrison Whiting, Khang Tran, Roger Padullés, Jasper Walden

## Contributing

Issues and pull requests are welcome. When submitting code, aim for:

- typed interfaces and clear docstrings
- small methods with singular purpose
- pytest coverage for new user-facing behaviour
- updated docs and notebooks where relevant

## License

OpenPinch is released under the MIT License. See `LICENSE` for details.
