Metadata-Version: 2.4
Name: OpenUtility
Version: 0.1.1
Summary: Pyomo-based utility-system optimization model and reporting helpers.
Project-URL: Changelog, https://github.com/waikato-ahuora-smart-energy-systems/OpenUtility/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/waikato-ahuora-smart-energy-systems/OpenUtility/tree/main/docs
Project-URL: Issues, https://github.com/waikato-ahuora-smart-energy-systems/OpenUtility/issues
Project-URL: Repository, https://github.com/waikato-ahuora-smart-energy-systems/OpenUtility
Author-email: Tim Walmsley <tim.walmsley@waikato.ac.nz>
License-Expression: MIT
License-File: LICENSE
Keywords: energy-systems,heat-integration,mathematical-optimization,pinch-analysis,pyomo,utility-systems
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.14.2
Requires-Dist: coolprop>=6.6
Requires-Dist: highspy>=1.15.1
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pyomo>=6.10.0
Provides-Extra: dev
Requires-Dist: mypy>=1.18; extra == 'dev'
Requires-Dist: pytest-cov>=7.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: notebook
Requires-Dist: jupyterlab>=4.6.2; extra == 'notebook'
Requires-Dist: mistune>=3.3.3; extra == 'notebook'
Requires-Dist: nbformat>=5; extra == 'notebook'
Requires-Dist: tornado>=6.5.8; extra == 'notebook'
Provides-Extra: release
Requires-Dist: build>=1.3; extra == 'release'
Requires-Dist: hatchling>=1.26; extra == 'release'
Requires-Dist: pip-audit>=2.9; extra == 'release'
Requires-Dist: pip>=26.2; extra == 'release'
Requires-Dist: twine>=6.2; extra == 'release'
Description-Content-Type: text/markdown

# OpenUtility

OpenUtility is an alpha-stage Python package for Pyomo-based utility-system
optimization. It focuses on investment selection, dispatch, thermal and
electric balances, operating-cost reporting, and solver orchestration for
industrial utility systems.

The package is intended to sit beside process-integration and thermodynamic
tools rather than replace them. OpenPinch, TESPy workflows, manufacturer data,
or other upstream tools can generate plain input data; OpenUtility consumes that
data without importing those packages at runtime.

## Package Scope

OpenUtility currently includes:

- typed input data classes for utility-system candidates, costs, thermal nodes,
  operating periods, and HPR performance maps;
- Pyomo MILP model construction for utility investment and dispatch decisions;
- HiGHS solving through Pyomo `SolverFactory("appsi_highs")` and the required
  `highspy` package;
- HPR investment and dispatch modeling, where HPR means heat pump and
  refrigeration;
- generic reporting helpers for model results, benchmarks, operating costs, and
  fuel consumption;
- generic bilevel decomposition bookkeeping, no-good cut helpers, and
  utility-system decomposition wrappers;
- thermal interval helpers for stream-like plain Python objects.

OpenUtility does not currently include:

- OpenPinch or TESPy as runtime dependencies;
- HPR thermodynamic cycle design, refrigerant screening, or performance-map
  generation;
- continuous HPR sizing; first-release HPR sizing is represented by selecting
  among fixed-capacity candidates;
- global interpolation across unrelated HPR temperature points;
- a full public case-study replication package in the distributed wheel;
- a public API named `BEELINE`, although generic bilevel decomposition utilities
  are included.

`OpenUtility/` is the reusable public package. Private replication workflows and
large study-specific artifacts are intentionally outside the package boundary
and are not included in release tests or built wheels.

OpenUtility targets Python `>=3.14.2`.

## Academic Basis

OpenUtility began as a Python/Pyomo implementation of utility-system
optimization methods developed by Julia Jimenez Romero, Adisa Azapagic, and
Robin Smith:

- Julia Jimenez Romero, "Reduction of Industrial Energy Demand through
  Sustainable Integration of Distributed Energy Hubs," PhD thesis, The
  University of Manchester, 2022.
- Jimenez Romero, J., Azapagic, A., and Smith, R., Computers and Chemical
  Engineering, 170, Article 108060, 2023.
  https://doi.org/10.1016/j.compchemeng.2022.108060
- Jimenez Romero, J., Azapagic, A., and Smith, R., "BEELINE: BilevEl
  dEcomposition aLgorithm for synthesis of Industrial eNergy systEms,"
  Computers and Chemical Engineering, 180, Article 108406, 2024.
  https://doi.org/10.1016/j.compchemeng.2023.108406

The package has since been generalized beyond the original replication
workflows and extended with HPR optimization. In OpenUtility, HPR means heat
pump and refrigeration: fixed-capacity HPR candidates can be selected and
dispatched against multi-period thermal-node balances using alpha versioned
plain performance maps. HPR electricity is currently handled by a period-indexed
overlay, while the original non-HPR electricity balance remains static. The HPR
implementation is an optimization-layer model; thermodynamic map generation
remains outside OpenUtility.

## Install

From a checkout:

```bash
python -m pip install -e ".[dev,docs,release]"
```

For normal package use:

```bash
python -m pip install .
```

## Quick Start

```python
from OpenUtility import (
    SteamLevelCandidate,
    UtilitySystemModelData,
    build_utility_system_model,
    pyomo_utility_system_solver,
)

data = UtilitySystemModelData(
    steam_mains=("MP",),
    steam_levels=(
        SteamLevelCandidate(
            name="MP_100",
            steam_main="MP",
            temperature=100.0,
            source_heat_available=5.0,
            sink_heat_demand=5.0,
            generation_enthalpy_delta=1.0,
            use_enthalpy_delta=1.0,
            source_heat_upper_bound=5.0,
            sink_heat_upper_bound=5.0,
        ),
    ),
    power_demand=0.0,
    grid_import_limit=0.0,
    grid_export_limit=0.0,
)
model = build_utility_system_model(data)
status = pyomo_utility_system_solver("appsi_highs")(model)
```

## Verification

Run the full release gate:

```bash
python tools/release_check.py
```

The gate runs linting, formatting, type checking, tests with coverage, Sphinx,
source/wheel build, wheel inspection, `twine check`, dependency audit, and a
fresh wheel-install smoke test.

For offline local triage only:

```bash
python tools/release_check.py --skip-audit --skip-smoke-install
```

## Documentation

Build docs locally:

```bash
python -m sphinx -W -b html docs /tmp/openutility-docs-html
```

OpenUtility `0.1.0` is an alpha release. Public reusable APIs are exposed
through `OpenUtility.__all__` and `OpenUtility.utility_system.__all__`.
