OpenPinch 0.2.0__tar.gz → 0.2.1__tar.gz

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/classes/_problem/_target_accessor.py

@@ -164,19 +164,18 @@ class _TargetAccessor:
         include_subzones: bool = False,
         state_id: Optional[str] = None,
     ) -> BaseTargetModel:
-        """Run turbine cogeneration post-processing on a compatible target."""
-        target_id = TT.DI.value
+        """
+        Run cogeneration on `TS -> IHP -> IR -> DHP -> DR -> DI`
+        unless overridden.
+        """
         runtime_options = dict(options or {})
         if state_id is not None:
             runtime_options["state_id"] = state_id
-        if runtime_options and "base_target_type" in runtime_options:
-            target_id = str(runtime_options["base_target_type"])
-        return self._problem._execute_targeting(
-            target_id=target_id,
+        return self._problem._execute_cogeneration_targeting(
             application_zone=zone_name,
             options=runtime_options,
             include_subzones=include_subzones,
-            direct_service_func=power_cogeneration_service,
+            service_func=power_cogeneration_service,
         )
 
     def area_cost(

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/classes/pinch_problem.py

@@ -179,6 +179,53 @@ class PinchProblem:
                 f"for zone {zone.name!r}."
             ) from exc
 
+    def _execute_cogeneration_targeting(
+        self,
+        *,
+        application_zone: Optional[str | Zone],
+        options: Optional[dict[str, Any]],
+        include_subzones: bool,
+        service_func: Optional[ZoneService] = None,
+        sid: str = None,
+    ) -> BaseTargetModel:
+        """Run cogeneration targeting and return the family selected at runtime."""
+        execution_master_zone = self._build_execution_master_zone()
+        runtime_options, sid = self._resolve_runtime_state_options(
+            options,
+            zone=execution_master_zone,
+        )
+        zone = self._resolve_target_zone(
+            application_zone, master_zone=execution_master_zone
+        )
+        if include_subzones:
+            self._run_targeting_for_zone_and_subzones(
+                zone=zone,
+                direct_service_func=service_func,
+                options=runtime_options,
+                sid=sid,
+            )
+        else:
+            if service_func is not None:
+                service_func(zone, runtime_options)
+            self._results = TargetOutput.model_validate(
+                extract_results(execution_master_zone, state_id=sid)
+            )
+
+        selected_target_type = getattr(zone, "_selected_cogeneration_target_type", None)
+        if not isinstance(selected_target_type, str):
+            raise RuntimeError(
+                "Cogeneration did not select a compatible target "
+                f"for zone {zone.name!r}."
+            )
+        try:
+            return zone.targets[selected_target_type]
+        except KeyError as exc:
+            raise RuntimeError(
+                "Cogeneration selected target "
+                f"{selected_target_type!r} for zone {zone.name!r}, "
+                "but that target was not available on the zone."
+            ) from exc
+
     def _resolve_target_zone(
         self,
         application_zone: Optional[str] = None,

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/lib/__init__.py

@@ -18,6 +18,7 @@ from .enums import (
     ZT,
     ArrowHead,
     BB_Minimiser,
+    CogenerationTarget,
     GraphType,
     HeatExchangerTypes,
     HeatFlowUnits,
@@ -113,6 +114,7 @@ __all__ = [
     "schemas",
     "ACTIVATE_TIMING",
     "C_to_K",
+    "CogenerationTarget",
     "Configuration",
     "LOG_TIMING",
     "T_CRIT",

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/lib/enums.py

@@ -1,10 +1,27 @@
-"""Enumerations defining canonical labels across OpenPinch.
+"""Enumerations and lightweight typed contracts used across OpenPinch.
 
 These enums standardize zone types, stream classifications, Problem Table
 column names, graph labels, and options keys used by configuration and schemas.
 """
 
+from __future__ import annotations
+
 from enum import Enum
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from ..classes.stream_collection import StreamCollection
+    from .config import Configuration
+
+
+class CogenerationTarget(Protocol):
+    """Compatible target surface required by cogeneration analysis helpers."""
+
+    config: Configuration
+    hot_utilities: StreamCollection
+    work_target: float | None
+    turbine_efficiency_target: float | None
+    state_ids: dict[str, int] | None
 
 
 class ZoneType(Enum):
@@ -286,6 +303,7 @@ class BB_Minimiser(str, Enum):
 __all__ = [
     "ArrowHead",
     "BB_Minimiser",
+    "CogenerationTarget",
     "GraphType",
     "GT",
     "HeatExchangerTypes",

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/services/power_cogeneration/power_cogeneration_analysis.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING
 import numpy as np
 
 from ...lib.config import T_CRIT, Configuration, tol
+from ...lib.enums import CogenerationTarget
 from ...utils.miscellaneous import get_state_index
 from ...utils.water_properties import psat_T
 from .unit_models.multi_stage_steam_turbine import MultiStageSteamTurbine
@@ -15,7 +16,6 @@ if TYPE_CHECKING:
     import numpy as np
 
     from ...classes.stream import Stream
-    from ...classes.zone import Zone
 
 __all__ = [
     "get_power_cogeneration_above_pinch",
@@ -24,18 +24,18 @@ __all__ = [
 
 
 def get_power_cogeneration_above_pinch(
-    zone: Zone,
+    target: CogenerationTarget,
     args: dict | None = None,
-) -> Zone:
-    """Calculate the power cogeneration potential above pinch for a given zone."""
-    turbine_params = _prepare_turbine_parameters(zone.config)
+) -> CogenerationTarget:
+    """Calculate above-Pinch cogeneration for a compatible thermal target object."""
+    turbine_params = _prepare_turbine_parameters(target.config)
     idx, sid = get_state_index(
-        state_ids=getattr(zone, "state_ids", None),
+        state_ids=getattr(target, "state_ids", None),
         args=args,
     )
-    utility_data = _preprocess_utilities(zone, turbine_params, idx=idx)
+    utility_data = _preprocess_utilities(target, turbine_params, idx=idx)
     if utility_data is None:
-        return zone
+        return target
 
     turbine = MultiStageSteamTurbine()
     total_work, details = turbine.solve(
@@ -51,9 +51,9 @@ def get_power_cogeneration_above_pinch(
         is_high_p_cond_flash=turbine_params["is_high_p_cond_flash"],
     )
 
-    zone.work_target = total_work
-    zone.turbine_efficiency_target = details["overall_efficiency"]
-    return zone
+    target.work_target = total_work
+    target.turbine_efficiency_target = details["overall_efficiency"]
+    return target
 
 
 def get_power_cogeneration_below_pinch(
@@ -96,18 +96,18 @@ def _prepare_turbine_parameters(zone_config: Configuration) -> dict:
 
 
 def _preprocess_utilities(
-    zone: Zone,
+    target: CogenerationTarget,
     turbine_params: dict,
     *,
     idx: int | None = None,
 ) -> dict | None:
-    """Translate hot-utility demands into turbine stage temperatures and duties."""
+    """Translate target hot-utility demands into turbine stage temperatures."""
     stage_temperatures: list[float] = []
     stage_heat_flows: list[float] = []
     source_indices: list[int] = []
 
     u: Stream
-    for i, u in enumerate(zone.hot_utilities):
+    for i, u in enumerate(target.hot_utilities):
         t_supply = float(u.t_supply[idx])
         t_target = float(u.t_target[idx])
         heat_flow = float(u.heat_flow[idx])

{openpinch-0.2.0 → openpinch-0.2.1}/OpenPinch/services/services_entry.py

@@ -30,6 +30,15 @@ __all__ = [
     "area_cost_targeting_service",
 ]
 
+_COGENERATION_TARGET_ORDER = (
+    TT.TS.value,
+    TT.IHP.value,
+    TT.IR.value,
+    TT.DHP.value,
+    TT.DR.value,
+    TT.DI.value,
+)
+
 
 def _record_selected_state(zone: Zone, args: dict | None) -> tuple[int, str | None]:
     """Persist the selected state metadata on a prepared zone."""
@@ -78,6 +87,86 @@ def _apply_zone_config_overrides(zone: Zone, args: dict | None) -> None:
         setattr(zone.config, key, value)
 
 
+def _normalize_cogeneration_base_target_type(
+    base_target_type: object | None,
+) -> str | None:
+    """Validate an explicit cogeneration base target override."""
+    if base_target_type is None:
+        return None
+
+    normalized = str(base_target_type)
+    if normalized not in _COGENERATION_TARGET_ORDER:
+        supported = ", ".join(_COGENERATION_TARGET_ORDER)
+        raise ValueError(
+            "Unsupported cogeneration base_target_type "
+            f"{normalized!r}. Supported types: {supported}."
+        )
+    return normalized
+
+
+def _get_cogeneration_candidate_order(
+    base_target_type: str | None,
+) -> tuple[str, ...]:
+    """Return the exact cogeneration target search order for this call."""
+    if base_target_type is not None:
+        return (base_target_type,)
+    return _COGENERATION_TARGET_ORDER
+
+
+def _get_cogeneration_refresh_services():
+    """Map compatible cogeneration target families to their prerequisite service."""
+    return {
+        TT.DI.value: direct_heat_integration_service,
+        TT.TS.value: indirect_heat_integration_service,
+        TT.DHP.value: direct_heat_pump_service,
+        TT.DR.value: direct_refrigeration_service,
+        TT.IHP.value: indirect_heat_pump_service,
+        TT.IR.value: indirect_refrigeration_service,
+    }
+
+
+def _ensure_cogeneration_target(
+    zone: Zone,
+    *,
+    target_type: str,
+    refresh_args: dict | None,
+    compare_args: dict | None,
+):
+    """Ensure one compatible target family exists for the requested state."""
+    target = zone.targets.get(target_type)
+    if _target_matches_requested_state(
+        target,
+        args=compare_args,
+        state_ids=getattr(zone, "state_ids", None),
+    ):
+        return target
+
+    refresh_service = _get_cogeneration_refresh_services().get(target_type)
+    if refresh_service is None:
+        return None
+
+    refresh_service(zone, refresh_args)
+    refreshed_target = zone.targets.get(target_type)
+    if _target_matches_requested_state(
+        refreshed_target,
+        args=compare_args,
+        state_ids=getattr(zone, "state_ids", None),
+    ):
+        return refreshed_target
+    return None
+
+
+def _format_cogeneration_state_suffix(args: dict | None) -> str:
+    """Render the selected state into cogeneration error messages."""
+    if not isinstance(args, dict):
+        return ""
+    if args.get("state_id") is not None:
+        return f" for state_id {str(args['state_id'])!r}"
+    if args.get("idx") is not None:
+        return f" for idx {int(args['idx'])}"
+    return ""
+
+
 def data_preprocessing_service(
     input_data: TargetInput,
     project_name: str = "Site",
@@ -203,56 +292,45 @@ def indirect_refrigeration_service(zone: Zone, args: dict | None = None) -> Zone
 
 
 def power_cogeneration_service(zone: Zone, args: dict | None = None) -> Zone:
-    """Post-process an existing target to recover above Pinch cogeneration work."""
+    """Post-process one compatible target in
+    TS -> IHP -> IR -> DHP -> DR -> DI order."""
     _apply_zone_config_overrides(zone, args)
-    target_type = [
-        TT.IHP.value,
-        TT.IR.value,
-        TT.TS.value,
-        TT.DHP.value,
-        TT.DR.value,
-        TT.DI.value,
-    ]
     runtime_args = dict(args or {})
+    explicit_target_type = _normalize_cogeneration_base_target_type(
+        runtime_args.get("base_target_type")
+    )
     idx, sid = _record_selected_state(zone, runtime_args)
     runtime_args["idx"] = idx
     if sid is not None:
         runtime_args["state_id"] = sid
-    refresh_args = runtime_args if isinstance(args, dict) else None
-    compare_args = runtime_args if isinstance(args, dict) else None
-    should_refresh_missing_target = False
-    if "base_target_type" in runtime_args:
-        target_type = [str(runtime_args["base_target_type"])]
-        should_refresh_missing_target = True
-    elif len(zone.targets) == 0:
-        direct_heat_integration_service(zone, refresh_args)
-    refresh_services = {
-        TT.DI.value: direct_heat_integration_service,
-        TT.TS.value: indirect_heat_integration_service,
-        TT.DHP.value: direct_heat_pump_service,
-        TT.DR.value: direct_refrigeration_service,
-        TT.IHP.value: indirect_heat_pump_service,
-        TT.IR.value: indirect_refrigeration_service,
-    }
-    for tt in target_type:
-        existing_target = zone.targets.get(tt)
-        if existing_target is None and not should_refresh_missing_target:
+    compare_args = dict(args or {}) if isinstance(args, dict) else {}
+    zone._selected_cogeneration_target_type = None
+
+    for target_type in _get_cogeneration_candidate_order(explicit_target_type):
+        target = _ensure_cogeneration_target(
+            zone,
+            target_type=target_type,
+            refresh_args=runtime_args,
+            compare_args=compare_args,
+        )
+        if target is None:
+            if explicit_target_type is not None:
+                raise RuntimeError(
+                    "Cogeneration could not produce target "
+                    f"{target_type!r} for zone {zone.name!r}"
+                    f"{_format_cogeneration_state_suffix(runtime_args)}."
+                )
             continue
-        if existing_target is None or not _target_matches_requested_state(
-            existing_target,
-            args=compare_args,
-            state_ids=getattr(zone, "state_ids", None),
-        ):
-            refresh_service = refresh_services.get(tt)
-            if refresh_service is not None:
-                refresh_service(zone, refresh_args)
-        if tt in zone.targets:
-            if isinstance(args, dict):
-                get_power_cogeneration_above_pinch(zone.targets[tt], args=runtime_args)
-            else:
-                get_power_cogeneration_above_pinch(zone.targets[tt])
-            return zone
-    raise ValueError("Load data before running pinch analysis services.")
+
+        get_power_cogeneration_above_pinch(target, args=runtime_args)
+        zone._selected_cogeneration_target_type = target_type
+        return zone
+
+    raise RuntimeError(
+        "Cogeneration could not find a compatible target for zone "
+        f"{zone.name!r}{_format_cogeneration_state_suffix(runtime_args)} "
+        f"using implicit order {' -> '.join(_COGENERATION_TARGET_ORDER)}."
+    )
 
 
 def area_cost_targeting_service(zone: Zone, args: dict | None = None) -> Zone:

{openpinch-0.2.0 → openpinch-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: OpenPinch
-Version: 0.2.0
+Version: 0.2.1
 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

{openpinch-0.2.0 → openpinch-0.2.1}/pyproject.toml

@@ -34,7 +34,7 @@ dependencies=[
   "pydantic",
   "scipy",
 ]
-version = "0.2.0"
+version = "0.2.1"
 authors = [
   { name="Tim Walmsley", email="tim.walmsley@waikato.ac.nz" },
 ]

openpinch-0.2.0/OpenPinch/services/power_cogeneration_analysis/power_cogeneration_analysis.py

@@ -1,139 +0,0 @@
-"""Utility routines for estimating turbine cogeneration targets."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import numpy as np
-
-from ...lib.config import T_CRIT, Configuration, tol
-from ...utils.miscellaneous import get_state_index
-from ...utils.water_properties import psat_T
-from ..power_cogeneration.unit_models.multi_stage_steam_turbine import (
-    MultiStageSteamTurbine,
-)
-
-if TYPE_CHECKING:
-    import numpy as np
-
-    from ...classes.stream import Stream
-    from ...classes.zone import Zone
-
-__all__ = [
-    "get_power_cogeneration_above_pinch",
-    "get_power_cogeneration_below_pinch",
-]
-
-
-def get_power_cogeneration_above_pinch(
-    zone: Zone,
-    args: dict | None = None,
-) -> Zone:
-    """Calculate the power cogeneration potential above pinch for a given zone."""
-    turbine_params = _prepare_turbine_parameters(zone.config)
-    idx, sid = get_state_index(
-        state_ids=getattr(zone, "state_ids", None),
-        args=args,
-    )
-    utility_data = _preprocess_utilities(zone, turbine_params, idx=idx)
-    if utility_data is None:
-        return zone
-
-    turbine = MultiStageSteamTurbine()
-    total_work, details = turbine.solve(
-        utility_data["stage_temperatures"],
-        utility_data["stage_heat_flows"],
-        mode="above_pinch",
-        T_in=turbine_params["T_in"],
-        P_in=turbine_params["P_in"],
-        model=turbine_params["model"],
-        min_eff=turbine_params["min_eff"],
-        load_frac=turbine_params["load_frac"],
-        mech_eff=turbine_params["mech_eff"],
-        is_high_p_cond_flash=turbine_params["is_high_p_cond_flash"],
-    )
-
-    zone.work_target = total_work
-    zone.turbine_efficiency_target = details["overall_efficiency"]
-    return zone
-
-
-def get_power_cogeneration_below_pinch(
-    temperatures: np.ndarray,
-    heat_flows: np.ndarray,
-    *,
-    zone_config: Configuration | None = None,
-    T_sink: float | None = None,
-) -> tuple[float, dict]:
-    """Solve a below Pinch turbine target against an environmental sink."""
-    zone_config = zone_config or Configuration()
-    turbine_params = _prepare_turbine_parameters(zone_config)
-    sink_temperature = zone_config.T_ENV if T_sink is None else float(T_sink)
-
-    turbine = MultiStageSteamTurbine()
-    return turbine.solve(
-        temperatures,
-        heat_flows,
-        mode="below_pinch",
-        T_sink=sink_temperature,
-        model=turbine_params["model"],
-        min_eff=turbine_params["min_eff"],
-        load_frac=turbine_params["load_frac"],
-        mech_eff=turbine_params["mech_eff"],
-        is_high_p_cond_flash=turbine_params["is_high_p_cond_flash"],
-    )
-
-
-def _prepare_turbine_parameters(zone_config: Configuration) -> dict:
-    """Load and sanitize turbine parameters from ``zone_config``."""
-    return {
-        "P_in": float(zone_config.TURB_P_IN),
-        "T_in": float(zone_config.TURB_T_IN),
-        "min_eff": float(zone_config.MIN_EFF),
-        "model": zone_config.TURB_MODEL,
-        "load_frac": min(max(float(zone_config.LOAD_FRACTION), 0.0), 1.0),
-        "mech_eff": min(max(float(zone_config.ETA_MECH), 0.0), 1.0),
-        "is_high_p_cond_flash": bool(zone_config.IS_HIGH_P_COND_FLASH),
-    }
-
-
-def _preprocess_utilities(
-    zone: Zone,
-    turbine_params: dict,
-    *,
-    idx: int | None = None,
-) -> dict | None:
-    """Translate hot-utility demands into turbine stage temperatures and duties."""
-    stage_temperatures: list[float] = []
-    stage_heat_flows: list[float] = []
-    source_indices: list[int] = []
-
-    u: Stream
-    for i, u in enumerate(zone.hot_utilities):
-        t_supply = float(u.t_supply[idx])
-        t_target = float(u.t_target[idx])
-        heat_flow = float(u.heat_flow[idx])
-        dt_cont_act = float(u.dt_cont_act[idx])
-        if t_supply >= T_CRIT or heat_flow <= tol:
-            continue
-
-        T_stage = (
-            t_target
-            if abs(t_supply - t_target) < 1.0 + tol
-            else t_target + dt_cont_act * 2
-        )
-        if turbine_params["P_in"] + tol < psat_T(T_stage):
-            continue
-
-        stage_temperatures.append(float(T_stage))
-        stage_heat_flows.append(float(heat_flow))
-        source_indices.append(i)
-
-    if not stage_temperatures:
-        return None
-
-    return {
-        "stage_temperatures": np.asarray(stage_temperatures, dtype=float),
-        "stage_heat_flows": np.asarray(stage_heat_flows, dtype=float),
-        "source_indices": np.asarray(source_indices, dtype=int),
-    }