OpenPinch 0.7.2__tar.gz → 0.7.4__tar.gz

{openpinch-0.7.2 → openpinch-0.7.4}/OpenPinch/application/_problem/accessors/design.py

@@ -20,6 +20,18 @@ if TYPE_CHECKING:
     from ...problem import PinchProblem
 
 
+class UtilityChoiceError(ValueError):
+    """A heater or cooler names no utility, and its side has several to choose from."""
+
+    def __init__(self, side: str, utilities: Sequence[str]) -> None:
+        super().__init__(
+            f"pass {side}_utility explicitly; the problem defines "
+            f"{len(utilities)} {side} utilities ({', '.join(utilities)})."
+        )
+        self.side = side
+        self.utilities = tuple(utilities)
+
+
 def _set_if_supplied(values: dict[str, Any], key: str, value: Any) -> None:
     if value is not None:
         values[key] = value
@@ -479,11 +491,7 @@ class _DesignAccessor:
             if getattr(utility.type, "value", utility.type) == kind
         ]
         if len(names) != 1:
-            side = kind.lower()
-            raise ValueError(
-                f"pass {side}_utility explicitly; the problem defines "
-                f"{len(names)} {side} utilities."
-            )
+            raise UtilityChoiceError(kind.lower(), names)
         return names[0]
 
     def optimise_duties(

{openpinch-0.7.2 → openpinch-0.7.4}/OpenPinch/application/_problem/input/utilities.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from copy import deepcopy
-from typing import List, Tuple
+from typing import List, Sequence, Tuple
 
 import numpy as np
 
@@ -82,7 +82,7 @@ def _get_hot_and_cold_utilities(
         cu_t_max=cu_t_max,
         dt_cont_multiplier=placement,
     )
-    utilities_with_defaults = _add_default_utilities(
+    utilities_with_defaults, defaults = _add_default_utilities(
         utilities=utilities_filled,
         config=config,
         add_default_hu=add_default_hu,
@@ -91,28 +91,23 @@ def _get_hot_and_cold_utilities(
         cu_t_max=cu_t_max,
         dt_cont_multiplier=placement,
     )
+    # The streams built from the defaults this preparation added are marked
+    # (by identity, never by name: a given utility may be called HU or CU, and
+    # the collection may rename either), so targeting uses them only as a backup.
     hot_utilities, utilities_left = _create_utilities_list(
         utilities=utilities_with_defaults,
         utility_type=StreamType.Hot.value,
         dt_cont_multiplier=dt_cont_multiplier,
         config=config,
+        defaults=defaults,
     )
     cold_utilities, _ = _create_utilities_list(
         utilities=utilities_left,
         utility_type=StreamType.Cold.value,
         dt_cont_multiplier=dt_cont_multiplier,
         config=config,
+        defaults=defaults,
     )
-    # Mark the defaults this preparation added (never a user utility that is
-    # merely named HU or CU), so targeting uses them only as a backup.
-    for added, collection, name in (
-        (add_default_hu, hot_utilities, "HU"),
-        (add_default_cu, cold_utilities, "CU"),
-    ):
-        if added:
-            for stream in collection:
-                if stream.name == name:
-                    mark_default_utility(stream)
     prepared = hot_utilities + cold_utilities
     period_ids = {
         str(period_id): index
@@ -379,12 +374,26 @@ def _add_default_utilities(
     hu_t_min: float,
     cu_t_max: float,
     dt_cont_multiplier: float = 1.0,
-) -> List[UtilitySchema]:
-    """Add default hot and cold utilities to the list of utilities."""
+) -> Tuple[List[UtilitySchema], List[UtilitySchema]]:
+    """Add default hot and cold utilities to the list; also return the defaults.
+
+    A default is named HU or CU, or HU_1, CU_1, ... when a given utility
+    already has that name, so the given one keeps its name.
+    """
+    taken = {utility.name for utility in utilities}
+
+    def free(name: str) -> str:
+        chosen, counter = name, 1
+        while chosen in taken:
+            chosen, counter = f"{name}_{counter}", counter + 1
+        taken.add(chosen)
+        return chosen
+
+    defaults: List[UtilitySchema] = []
     if add_default_hu:
-        utilities.append(
+        defaults.append(
             _create_default_utility(
-                "HU",
+                free("HU"),
                 StreamType.Hot.value,
                 hu_t_min,
                 config,
@@ -392,16 +401,17 @@ def _add_default_utilities(
             )
         )
     if add_default_cu:
-        utilities.append(
+        defaults.append(
             _create_default_utility(
-                "CU",
+                free("CU"),
                 StreamType.Cold.value,
                 cu_t_max,
                 config,
                 dt_cont_multiplier=dt_cont_multiplier,
             )
         )
-    return utilities
+    utilities.extend(defaults)
+    return utilities, defaults
 
 
 def _create_default_utility(
@@ -435,8 +445,13 @@ def _create_utilities_list(
     utility_type: str,
     dt_cont_multiplier: float = 1.0,
     config: Configuration = Configuration(),
+    defaults: Sequence[UtilitySchema] = (),
 ) -> Tuple[StreamCollection, List[UtilitySchema]]:
-    """Create a sorted list of hot or cold Stream objects based on type."""
+    """Create a sorted list of hot or cold Stream objects based on type.
+
+    The stream built from each utility in ``defaults`` (the default HU and CU
+    added by preparation) is marked as a default utility.
+    """
     created_utilities = StreamCollection()
     unassigned_utilities = utilities
 
@@ -520,8 +535,10 @@ def _create_utilities_list(
                 fluid_name=selected.fluid_name,
                 fluid_phase=selected.fluid_phase,
             )
+        if any(selected is default for default in defaults):
+            mark_default_utility(created)
         created_utilities.add(created, key)
-        created_utilities[key].delta_t_contribution_multiplier = dt_cont_multiplier
+        created.delta_t_contribution_multiplier = dt_cont_multiplier
         if selected.type == utility_type:
             selected.active = False
 

{openpinch-0.7.2 → openpinch-0.7.4}/OpenPinch/application/commands.py

@@ -38,7 +38,10 @@ from ..domain.targets import BaseTargetModel
 from ..presentation.configuration import configuration_field_metadata
 from ..presentation.reporting.hpr import hpr_failure_summary
 from ..presentation.reporting.results import serialize_target
-from ._problem.accessors.design import HeatExchangerNetworkDesignView
+from ._problem.accessors.design import (
+    HeatExchangerNetworkDesignView,
+    UtilityChoiceError,
+)
 from ._problem.input.validation import (
     InputValidationWarning,
     build_validation_report,
@@ -75,12 +78,26 @@ _SESSIONS: dict[str, _Session] = {}
 
 
 class _DefaultUtilityWarning(UserWarning):
-    """A default utility added to a problem that gave none of its kind."""
+    """A default utility added because no given utility of its kind can serve.
+
+    ``given`` names the problem's own utilities of that kind: none at all, or
+    ones that are too warm (cold) or too cool (hot), or capped, to take the
+    whole duty, in which case the default is a backup beside them.
+    """
 
-    def __init__(self, name: str, kind: str) -> None:
-        super().__init__(f"No {kind} utility given; added the default {name!r}.")
+    def __init__(self, name: str, kind: str, given: list[str]) -> None:
+        if given:
+            enough = "cold enough" if kind == "cold" else "hot enough"
+            message = (
+                f"None of the given {kind} utilities is {enough} and uncapped; "
+                f"added the default {name!r} as a backup."
+            )
+        else:
+            message = f"No {kind} utility given; added the default {name!r}."
+        super().__init__(message)
         self.name = name
         self.kind = kind
+        self.given = given
 
 
 def _load_problem(source: Mapping[str, Any]) -> PinchProblem:
@@ -106,9 +123,14 @@ def _load_problem(source: Mapping[str, Any]) -> PinchProblem:
         ("hot", problem.hot_utilities),
         ("cold", problem.cold_utilities),
     ):
+        given = [
+            utility.name for utility in utilities if not is_default_utility(utility)
+        ]
         for utility in utilities:
             if is_default_utility(utility):
-                warnings.warn(_DefaultUtilityWarning(utility.name, kind), stacklevel=1)
+                warnings.warn(
+                    _DefaultUtilityWarning(utility.name, kind, given), stacklevel=1
+                )
     return problem
 
 
@@ -276,6 +298,7 @@ def _warnings_json(caught: list[warnings.WarningMessage]) -> list[dict[str, Any]
                     "details": {
                         "name": warning.message.name,
                         "kind": warning.message.kind,
+                        "given": warning.message.given,
                     },
                 }
             )
@@ -413,6 +436,7 @@ _ANALYSIS_FAILURES = (
     HPRTargetingError,
     HprTargetCompatibilityError,
     OrcTargetingError,
+    UtilityChoiceError,
 )
 
 
@@ -429,6 +453,8 @@ def _error_json(error: Exception) -> dict[str, Any]:
         details = hpr_failure_summary(error)
     elif isinstance(error, HprTargetCompatibilityError):
         details = {"code": error.code}
+    elif isinstance(error, UtilityChoiceError):
+        details = {"side": error.side, "utilities": list(error.utilities)}
     return {"type": type(error).__name__, "message": str(error), "details": details}
 
 

{openpinch-0.7.2 → openpinch-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: OpenPinch
-Version: 0.7.2
+Version: 0.7.4
 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
@@ -63,6 +63,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/openpinch.svg)](https://pypi.org/project/OpenPinch/)
 [![Python versions](https://img.shields.io/pypi/pyversions/openpinch.svg)](https://pypi.org/project/OpenPinch/)
 [![License: MIT](https://img.shields.io/github/license/waikato-ahuora-smart-energy-systems/OpenPinch.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23619779.svg)](https://doi.org/10.5281/zenodo.23619779)
 
 OpenPinch is an open-source Python toolkit for advanced Pinch Analysis and
 Total Site Integration. It supports direct and indirect heat integration
@@ -260,6 +261,10 @@ 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
 
+Each release of the software is archived on Zenodo with its own DOI. The DOI
+https://doi.org/10.5281/zenodo.23619779 always resolves to the latest release;
+cite the DOI of the version you used, listed on its Zenodo page.
+
 ## Contributors
 
 Founder: Tim Walmsley, University of Waikato

{openpinch-0.7.2 → openpinch-0.7.4}/README.md

@@ -5,6 +5,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/openpinch.svg)](https://pypi.org/project/OpenPinch/)
 [![Python versions](https://img.shields.io/pypi/pyversions/openpinch.svg)](https://pypi.org/project/OpenPinch/)
 [![License: MIT](https://img.shields.io/github/license/waikato-ahuora-smart-energy-systems/OpenPinch.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23619779.svg)](https://doi.org/10.5281/zenodo.23619779)
 
 OpenPinch is an open-source Python toolkit for advanced Pinch Analysis and
 Total Site Integration. It supports direct and indirect heat integration
@@ -202,6 +203,10 @@ 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
 
+Each release of the software is archived on Zenodo with its own DOI. The DOI
+https://doi.org/10.5281/zenodo.23619779 always resolves to the latest release;
+cite the DOI of the version you used, listed on its Zenodo page.
+
 ## Contributors
 
 Founder: Tim Walmsley, University of Waikato

{openpinch-0.7.2 → openpinch-0.7.4}/pyproject.toml

@@ -36,7 +36,7 @@ dependencies=[
   "pydantic>=2.12,<3",
   "scipy>=1.16.1,<2",
 ]
-version = "0.7.2"
+version = "0.7.4"
 authors = [
   { name="Tim Walmsley", email="tim.walmsley@waikato.ac.nz" },
 ]