OpenPinch 0.2.2__tar.gz → 0.2.4__tar.gz

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/__init__.py

@@ -29,6 +29,7 @@ from .lib import (
     DirectHeatPumpTarget,
     DirectIntegrationTarget,
     DirectRefrigerationTarget,
+    EnergyTransferTarget,
     GetInputOutputData,
     Graph,
     GraphCatalogEntry,
@@ -186,6 +187,7 @@ __all__ = [
     "DirectHeatPumpTarget",
     "DirectIntegrationTarget",
     "DirectRefrigerationTarget",
+    "EnergyTransferTarget",
     "HeatPumpTargetBase",
     "IndirectHeatPumpTarget",
     "IndirectRefrigerationTarget",

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/_problem/__init__.py

@@ -1,5 +1,6 @@
 """Private helpers for the :mod:`OpenPinch.classes.pinch_problem` surface."""
 
+from ._component_accessor import _ComponentAccessorDescriptor
 from ._loading import (
     JsonDict,
     PathLike,
@@ -27,6 +28,7 @@ __all__ = [
     "_LoadedProblemSource",
     "PathLike",
     "_ProblemSourceAdapters",
+    "_ComponentAccessorDescriptor",
     "_PlotAccessorDescriptor",
     "_TargetAccessorDescriptor",
     "_validate_problem_semantics",

openpinch-0.2.4/OpenPinch/classes/_problem/_component_accessor.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from ...services.components.process_mvr import ProcessMVRComponent
+    from ..pinch_problem import PinchProblem
+
+
+class _ComponentAccessor:
+    """Helper namespace for mutating prepared process models with components."""
+
+    def __init__(self, problem: "PinchProblem") -> None:
+        self._problem = problem
+
+    def process_mvr(
+        self,
+        source_streams,
+        *,
+        mvr_id: Optional[str] = None,
+        n_stages: int = 1,
+        liquid_injection: bool = True,
+        mvr_stage_t_lift: Optional[float] = None,
+        mvr_stage_pressure_ratio: Optional[float] = None,
+        max_stage_t_sat_lift: Optional[float] = None,
+        options: Optional[dict[str, Any]] = None,
+        state_id: Optional[str] = None,
+    ) -> "ProcessMVRComponent":
+        """Add a direct process MVR component to selected hot gas stream(s)."""
+        from ...services.components.process_mvr import (
+            create_process_mvr_component,
+        )
+
+        return create_process_mvr_component(
+            self._problem,
+            source_streams=source_streams,
+            mvr_id=mvr_id,
+            n_stages=n_stages,
+            liquid_injection=liquid_injection,
+            mvr_stage_t_lift=mvr_stage_t_lift,
+            mvr_stage_pressure_ratio=mvr_stage_pressure_ratio,
+            max_stage_t_sat_lift=max_stage_t_sat_lift,
+            options=options,
+            state_id=state_id,
+        )
+
+
+class _ComponentAccessorDescriptor:
+    """Descriptor returning a problem-bound component accessor."""
+
+    def __get__(self, obj: "PinchProblem" | None, owner=None):
+        if obj is None:
+            return self
+        return _ComponentAccessor(obj)

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/_problem/_plot_accessor.py

@@ -19,6 +19,9 @@ GraphRecord = Dict[str, Any]
 GraphPayload = Dict[str, GraphRecord]
 
 _GRAPH_TYPE_ALIASES = {
+    "etd": GT.ETD.value,
+    "energy transfer": GT.ETD.value,
+    "energy transfer diagram": GT.ETD.value,
     "cc": GT.CC.value,
     "composite": GT.CC.value,
     "composite curve": GT.CC.value,
@@ -410,6 +413,23 @@ class _PlotAccessor:
             return_graph_data=return_graph_data,
         )
 
+    def energy_transfer_diagram(
+        self,
+        *,
+        zone_name: Optional[str] = None,
+        index: float = 0,
+        show: bool = False,
+        return_graph_data: bool = False,
+    ):
+        """Return the first matching energy-transfer diagram payload or figure."""
+        return self._plot_graph(
+            zone_name=zone_name,
+            graph_type=GT.ETD.value,
+            index=index,
+            show=show,
+            return_graph_data=return_graph_data,
+        )
+
 
 class _PlotAccessorDescriptor:
     """Non-data descriptor exposing a callable plot accessor on instances."""

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/_problem/_target_accessor.py

@@ -7,6 +7,7 @@ from ...services import (
     direct_heat_integration_service,
     direct_heat_pump_service,
     direct_refrigeration_service,
+    energy_transfer_analysis_service,
     exergy_targeting_service,
     indirect_heat_integration_service,
     indirect_heat_pump_service,
@@ -25,7 +26,10 @@ class _TargetAccessor:
         self._problem = problem
 
     def __call__(
-        self, *, options: Optional[dict[str, Any]] = {}, state_id: Optional[str] = None
+        self,
+        *,
+        options: Optional[dict[str, Any]] = None,
+        state_id: Optional[str] = None,
     ):
         runtime_options = dict(options or {})
         if state_id is not None:
@@ -219,6 +223,26 @@ class _TargetAccessor:
             service_func=exergy_targeting_service,
         )
 
+    def energy_transfer(
+        self,
+        *,
+        zone_name: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        include_subzones: bool = False,
+        state_id: Optional[str] = None,
+    ) -> BaseTargetModel:
+        """Create energy-transfer diagram and heat-surplus/deficit outputs."""
+        runtime_options = dict(options or {})
+        if state_id is not None:
+            runtime_options["state_id"] = state_id
+        return self._problem._execute_targeting(
+            target_id=TT.ET.value,
+            application_zone=zone_name,
+            options=runtime_options,
+            include_subzones=include_subzones,
+            direct_service_func=energy_transfer_analysis_service,
+        )
+
 
 class _TargetAccessorDescriptor:
     """Non-data descriptor exposing a callable target accessor on instances."""

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/_problem/_target_dispatch.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import inspect
+from functools import lru_cache
 from typing import Callable
 
 from ...lib.enums import ZT
@@ -31,21 +32,26 @@ def run_targeting_for_zone_and_subzones(
 
 def _invoke_service(service_func: Callable, zone: Zone, args: dict | None = None):
     """Call a targeting callback with backward-compatible argument handling."""
-    if not isinstance(service_func, Callable):
+    if not callable(service_func):
         return None
 
-    if args is None:
+    if args is None or not _service_accepts_args(service_func):
         return service_func(zone)
 
+    return service_func(zone, args)
+
+
+@lru_cache(maxsize=64)
+def _service_accepts_args(service_func: Callable) -> bool:
+    """Return whether a service accepts a second positional ``args`` parameter."""
     try:
         signature = inspect.signature(service_func)
     except TypeError, ValueError:
-        return service_func(zone, args)
+        return True
 
     params = list(signature.parameters.values())
-    accepts_varargs = any(
-        param.kind == inspect.Parameter.VAR_POSITIONAL for param in params
-    )
+    if any(param.kind == inspect.Parameter.VAR_POSITIONAL for param in params):
+        return True
     positional_params = [
         param
         for param in params
@@ -55,10 +61,7 @@ def _invoke_service(service_func: Callable, zone: Zone, args: dict | None = None
             inspect.Parameter.POSITIONAL_OR_KEYWORD,
         )
     ]
-
-    if accepts_varargs or len(positional_params) >= 2:
-        return service_func(zone, args)
-    return service_func(zone)
+    return len(positional_params) >= 2
 
 
 def _invoke_target_handler(
@@ -95,7 +98,7 @@ def _get_unit_operation_targets(
             for subzone in zone.subzones.values():
                 if subzone.type == ZT.O.value:
                     if subzone.config.DO_DIRECT_OPERATION_TARGETING:
-                        if isinstance(direct_service_func, Callable):
+                        if callable(direct_service_func):
                             _invoke_service(direct_service_func, subzone, args)
                 else:
                     raise ValueError(
@@ -103,7 +106,7 @@ def _get_unit_operation_targets(
                         "contain other operation zones."
                     )
 
-        if isinstance(direct_service_func, Callable):
+        if callable(direct_service_func):
             _invoke_service(direct_service_func, zone, args)
 
     return zone
@@ -142,10 +145,10 @@ def _get_process_targets(
                 )
 
         if zone.config.DO_INDIRECT_PROCESS_TARGETING:
-            if isinstance(indirect_service_func, Callable):
+            if callable(indirect_service_func):
                 _invoke_service(indirect_service_func, zone, args)
 
-    if isinstance(direct_service_func, Callable):
+    if callable(direct_service_func):
         _invoke_service(direct_service_func, zone, args)
 
     return zone
@@ -159,7 +162,7 @@ def _get_site_targets(
 ):
     """Run site targeting over the full nested zone hierarchy."""
 
-    if isinstance(direct_service_func, Callable):
+    if callable(direct_service_func):
         _invoke_service(direct_service_func, zone, args)
 
     if len(zone.subzones) > 0:
@@ -194,7 +197,7 @@ def _get_site_targets(
                     "site, process, and operation zones."
                 )
 
-        if isinstance(indirect_service_func, Callable):
+        if callable(indirect_service_func):
             _invoke_service(indirect_service_func, zone, args)
 
     return zone

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/_problem/_validation.py

@@ -17,6 +17,48 @@ from ..value import Value
 
 ValidationContext = dict[str, list[dict[str, Any]]]
 _TEMPERATURE_EQUAL_TOL = 1e-12
+_STREAM_VALUE_FIELDS = (
+    "t_supply",
+    "t_target",
+    "p_supply",
+    "p_target",
+    "h_supply",
+    "h_target",
+    "heat_flow",
+    "dt_cont",
+    "htc",
+)
+_STREAM_OPTIONAL_VALUE_FIELDS = (
+    "p_supply",
+    "p_target",
+    "h_supply",
+    "h_target",
+    "dt_cont",
+    "htc",
+)
+_UTILITY_VALUE_FIELDS = (
+    "t_supply",
+    "t_target",
+    "p_supply",
+    "p_target",
+    "h_supply",
+    "h_target",
+    "heat_flow",
+    "dt_cont",
+    "htc",
+    "price",
+)
+_UTILITY_OPTIONAL_VALUE_FIELDS = (
+    "t_target",
+    "p_supply",
+    "p_target",
+    "h_supply",
+    "h_target",
+    "heat_flow",
+    "dt_cont",
+    "htc",
+    "price",
+)
 
 
 def validate_problem_inputs(
@@ -136,8 +178,8 @@ def semantic_issues(
             section="streams",
             record_index=index,
             record_label=label,
-            field_names=("t_supply", "t_target", "heat_flow", "dt_cont", "htc"),
-            optional_field_names=("dt_cont", "htc"),
+            field_names=_STREAM_VALUE_FIELDS,
+            optional_field_names=_STREAM_OPTIONAL_VALUE_FIELDS,
             config=input_unit_config,
         )
         issues.extend(stream_value_issues)
@@ -157,21 +199,8 @@ def semantic_issues(
             section="utilities",
             record_index=index,
             record_label=label,
-            field_names=(
-                "t_supply",
-                "t_target",
-                "heat_flow",
-                "dt_cont",
-                "htc",
-                "price",
-            ),
-            optional_field_names=(
-                "t_target",
-                "heat_flow",
-                "dt_cont",
-                "htc",
-                "price",
-            ),
+            field_names=_UTILITY_VALUE_FIELDS,
+            optional_field_names=_UTILITY_OPTIONAL_VALUE_FIELDS,
             config=input_unit_config,
         )
         issues.extend(utility_value_issues)
@@ -435,51 +464,16 @@ def _validate_stream_record_states(
     record_label: Optional[str],
 ) -> list[ValidationIssue]:
     issues: list[ValidationIssue] = []
-    issues.extend(
-        _validate_value_finiteness(
-            values.get("t_supply"),
-            section=section,
-            record_index=record_index,
-            record_label=record_label,
-            field_name="t_supply",
-        )
-    )
-    issues.extend(
-        _validate_value_finiteness(
-            values.get("t_target"),
-            section=section,
-            record_index=record_index,
-            record_label=record_label,
-            field_name="t_target",
-        )
-    )
-    issues.extend(
-        _validate_value_finiteness(
-            values.get("heat_flow"),
-            section=section,
-            record_index=record_index,
-            record_label=record_label,
-            field_name="heat_flow",
-        )
-    )
-    issues.extend(
-        _validate_value_finiteness(
-            values.get("dt_cont"),
-            section=section,
-            record_index=record_index,
-            record_label=record_label,
-            field_name="dt_cont",
-        )
-    )
-    issues.extend(
-        _validate_value_finiteness(
-            values.get("htc"),
-            section=section,
-            record_index=record_index,
-            record_label=record_label,
-            field_name="htc",
+    for field_name in _STREAM_VALUE_FIELDS:
+        issues.extend(
+            _validate_value_finiteness(
+                values.get(field_name),
+                section=section,
+                record_index=record_index,
+                record_label=record_label,
+                field_name=field_name,
+            )
         )
-    )
     issues.extend(
         _validate_non_negative_states(
             values.get("heat_flow"),
@@ -522,7 +516,7 @@ def _validate_stream_record_states(
     classifications: dict[str, list[str]] = {
         ST.Hot.value: [],
         ST.Cold.value: [],
-        ST.Both.value: [],
+        ST.Neutral.value: [],
     }
 
     num_states = 1
@@ -558,6 +552,10 @@ def _validate_stream_record_states(
                     ),
                 )
             )
+        elif t_supply_value > t_target_value:
+            classifications[ST.Hot.value].append(str(idx))
+        elif t_supply_value < t_target_value:
+            classifications[ST.Cold.value].append(str(idx))
 
     active_classes = {
         stream_type: state_group
@@ -577,7 +575,7 @@ def _validate_stream_record_states(
                     "Stream states must classify consistently. "
                     f"Hot={classifications[ST.Hot.value]}, "
                     f"Cold={classifications[ST.Cold.value]}, "
-                    f"Neutral={classifications[ST.Both.value]}."
+                    f"Neutral={classifications[ST.Neutral.value]}."
                 ),
             )
         )
@@ -593,7 +591,7 @@ def _validate_utility_record_states(
     record_label: Optional[str],
 ) -> list[ValidationIssue]:
     issues: list[ValidationIssue] = []
-    for field_name in ("t_supply", "t_target", "heat_flow", "dt_cont", "htc", "price"):
+    for field_name in _UTILITY_VALUE_FIELDS:
         issues.extend(
             _validate_value_finiteness(
                 values.get(field_name),

openpinch-0.2.4/OpenPinch/classes/_stream_collection/_numeric_view.py

@@ -0,0 +1,81 @@
+"""Numeric snapshot helpers for :class:`StreamCollection` internals."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ...lib.enums import ST
+from ..value import Value
+
+
+@dataclass(frozen=True)
+class StreamCollectionNumericView:
+    """Dense numeric snapshot of stream properties for internal kernels."""
+
+    t_min: np.ndarray
+    t_max: np.ndarray
+    t_min_star: np.ndarray
+    t_max_star: np.ndarray
+    cp: np.ndarray
+    rcp: np.ndarray
+    heat_flow: np.ndarray
+    dt_cont: np.ndarray
+    is_hot: np.ndarray
+    is_cold: np.ndarray
+    active: np.ndarray
+
+
+def build_numeric_view(streams: list[object], idx: int | None = None):
+    """Build a dense numeric view from stream objects."""
+    n_streams = len(streams)
+    t_min = np.empty(n_streams, dtype=float)
+    t_max = np.empty(n_streams, dtype=float)
+    t_min_star = np.empty(n_streams, dtype=float)
+    t_max_star = np.empty(n_streams, dtype=float)
+    cp = np.empty(n_streams, dtype=float)
+    rcp = np.empty(n_streams, dtype=float)
+    heat_flow = np.empty(n_streams, dtype=float)
+    dt_cont = np.empty(n_streams, dtype=float)
+    is_hot = np.empty(n_streams, dtype=bool)
+    is_cold = np.empty(n_streams, dtype=bool)
+    active = np.empty(n_streams, dtype=bool)
+
+    for stream_idx, stream in enumerate(streams):
+        t_min[stream_idx] = value_at_idx(stream._t_min, idx)
+        t_max[stream_idx] = value_at_idx(stream._t_max, idx)
+        t_min_star[stream_idx] = value_at_idx(stream._t_min_star, idx)
+        t_max_star[stream_idx] = value_at_idx(stream._t_max_star, idx)
+        cp[stream_idx] = value_at_idx(stream._cp, idx)
+        rcp[stream_idx] = value_at_idx(stream._rcp_prod, idx)
+        heat_flow[stream_idx] = value_at_idx(stream._heat_flow, idx)
+        dt_cont[stream_idx] = value_at_idx(stream._dt_cont, idx)
+        is_hot[stream_idx] = stream.type == ST.Hot.value
+        is_cold[stream_idx] = stream.type == ST.Cold.value
+        active[stream_idx] = bool(stream.active)
+
+    return StreamCollectionNumericView(
+        t_min=t_min,
+        t_max=t_max,
+        t_min_star=t_min_star,
+        t_max_star=t_max_star,
+        cp=cp,
+        rcp=rcp,
+        heat_flow=heat_flow,
+        dt_cont=dt_cont,
+        is_hot=is_hot,
+        is_cold=is_cold,
+        active=active,
+    )
+
+
+def value_at_idx(value: Value | None, idx: int | None = None) -> float:
+    """Return one canonical numeric magnitude from a scalar or stateful value."""
+    if value is None:
+        return np.nan
+    magnitudes = value._quantity.magnitude
+    if magnitudes.size == 1:
+        return float(magnitudes[0])
+    state_idx = 0 if idx is None else int(idx)
+    return float(magnitudes[state_idx])

{openpinch-0.2.2 → openpinch-0.2.4}/OpenPinch/classes/pinch_problem.py

@@ -30,6 +30,7 @@ from ..utils.wkbook_to_json import get_problem_from_excel
 from ._problem import (
     JsonDict,
     PathLike,
+    _ComponentAccessorDescriptor,
     _LoadedProblemSource,
     _PlotAccessorDescriptor,
     _ProblemSourceAdapters,
@@ -65,8 +66,10 @@ class PinchProblem:
     _results: Optional[TargetOutput]
     _validated_data: Optional[TargetInput]
     _master_zone: Optional["Zone"]
+    _process_components: dict[str, Any]
     _input_source_kind: str
     _validation_context: Optional[dict[str, list[dict[str, Any]]]]
+    add_component = _ComponentAccessorDescriptor()
     plot = _PlotAccessorDescriptor()
     target = _TargetAccessorDescriptor()
 
@@ -86,6 +89,7 @@ class PinchProblem:
         self._results = None
         self._validated_data = None
         self._master_zone = None
+        self._process_components = {}
         self.results_dir = None
 
         if source is not None:
@@ -132,6 +136,7 @@ class PinchProblem:
             indirect_service_func=indirect_service_func,
             args=runtime_options,
         )
+        self._attach_process_component_work_targets(zone, runtime_options)
         self._results = TargetOutput.model_validate(extract_results(zone, state_id=sid))
         return self._results
 
@@ -167,6 +172,10 @@ class PinchProblem:
                 direct_service_func(zone, runtime_options)
             if indirect_service_func is not None:
                 indirect_service_func(zone, runtime_options)
+            self._attach_process_component_work_targets(
+                execution_master_zone,
+                runtime_options,
+            )
             self._results = TargetOutput.model_validate(
                 extract_results(execution_master_zone, state_id=sid)
             )
@@ -207,6 +216,10 @@ class PinchProblem:
         else:
             if service_func is not None:
                 service_func(zone, runtime_options)
+            self._attach_process_component_work_targets(
+                execution_master_zone,
+                runtime_options,
+            )
             self._results = TargetOutput.model_validate(
                 extract_results(execution_master_zone, state_id=sid)
             )
@@ -273,6 +286,10 @@ class PinchProblem:
         elif service_func is not None:
             service_func(zone, runtime_options)
 
+        self._attach_process_component_work_targets(
+            execution_master_zone,
+            runtime_options,
+        )
         self._results = TargetOutput.model_validate(
             extract_results(execution_master_zone, state_id=sid)
         )
@@ -308,6 +325,51 @@ class PinchProblem:
             return selected_master_zone
         return selected_master_zone.get_subzone(application_zone)
 
+    def _attach_process_component_work_targets(
+        self,
+        zone: "Zone",
+        runtime_options: Optional[dict[str, Any]],
+    ) -> None:
+        if not self._process_components:
+            return
+        state_id = (runtime_options or {}).get("state_id")
+        state_idx = (runtime_options or {}).get("idx")
+        for current_zone in self._walk_zone_tree(zone):
+            component_work = self._process_component_work_for_zone(
+                current_zone,
+                state_id=state_id,
+                state_idx=state_idx,
+            )
+            for target in current_zone.targets.values():
+                if hasattr(target, "process_component_work_target"):
+                    target.process_component_work_target = component_work
+                if (
+                    component_work > 0.0
+                    and hasattr(target, "work_target")
+                    and getattr(target, "work_target", None) is None
+                ):
+                    target.work_target = component_work
+
+    def _process_component_work_for_zone(
+        self,
+        zone: "Zone",
+        *,
+        state_id: str | None,
+        state_idx: int | None,
+    ) -> float:
+        total = 0.0
+        for component in self._process_components.values():
+            work_for_zone = getattr(component, "work_for_zone", None)
+            if work_for_zone is None:
+                continue
+            total += float(work_for_zone(zone, state_id=state_id, state_idx=state_idx))
+        return total
+
+    def _walk_zone_tree(self, zone: "Zone"):
+        yield zone
+        for subzone in zone.subzones.values():
+            yield from self._walk_zone_tree(subzone)
+
     def _build_execution_master_zone(self) -> "Zone":
         if self._problem_data is None and self._master_zone is None:
             raise RuntimeError("No input loaded. Call load(...) first.")
@@ -374,7 +436,7 @@ class PinchProblem:
         options: Optional[dict[str, Any]],
         *,
         zone: "Zone",
-    ) -> tuple[dict[str, Any], str | None, int]:
+    ) -> tuple[dict[str, Any], str | None]:
         runtime_options = dict(options or {})
         idx, sid = get_state_index(state_ids=zone.state_ids, args=runtime_options)
         runtime_options["idx"] = idx
@@ -583,6 +645,11 @@ class PinchProblem:
         """Return the prepared root zone after a successful ``load()`` pass."""
         return self._master_zone
 
+    @property
+    def process_components(self) -> dict[str, Any]:
+        """Memory-only process components applied to the prepared model."""
+        return self._process_components
+
     @property
     def hot_streams(self) -> StreamCollection:
         """Hot process streams on the root analysis zone."""
@@ -755,6 +822,7 @@ class PinchProblem:
         """Revalidate, reconstruct the zone tree, and clear cached results."""
         self._validated_data = self.validate()
         self._master_zone = self._data_preprocessing()
+        self._process_components = {}
         self._results = None
         return self._master_zone