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 PyPI (Python >=3.14.2):

python -m pip install OpenUtility

For development from a checkout:

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

To install a local checkout:

python -m pip install .

Quick Start

For guided, executable tutorials, start with the six Jupyter examples and the Read the Docs example guide. They cover first solve, equipment selection, scenario analysis, heat pumps, multi-period refrigeration, and binary-selection decomposition. Each uses synthetic data and includes checked results, tables, and plots.

python -m pip install "OpenUtility[notebook]>=0.1.2"
python -m jupyterlab

Download any notebook, select the installed environment's Python kernel, and restart the kernel and run all cells. No checkout or private data is required.

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:

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:

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

Documentation

Read the online documentation.

Build docs locally:

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

OpenUtility is alpha-stage software. Public reusable APIs are exposed through OpenUtility.__all__ and OpenUtility.utility_system.__all__.