OpenPinch 0.2.1__tar.gz → 0.2.3__tar.gz

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/__init__.py

@@ -1,5 +1,7 @@
 """OpenPinch public API."""
 
+from __future__ import annotations
+
 import warnings as _warnings
 
 from . import lib
@@ -55,6 +57,7 @@ from .lib import (
     MaybeVU,
     NonLinearStream,
     PayloadRecordView,
+    PinchTemp,
     PinchWorkspaceBundle,
     ProblemTableColumnKey,
     ProblemTableColumnUpdates,
@@ -82,7 +85,6 @@ from .lib import (
     TargetOutput,
     TargetResults,
     TargetType,
-    TempPinch,
     THSchema,
     TotalProcessTarget,
     TotalSiteTarget,
@@ -178,7 +180,7 @@ __all__ = [
     "ZoneTreeSchema",
     "HeatUtility",
     "TargetResults",
-    "TempPinch",
+    "PinchTemp",
     "AnyTargetModel",
     "BaseTargetModel",
     "DirectHeatPumpTarget",

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_problem/__init__.py

@@ -14,7 +14,9 @@ from ._output import (
     locate_summary_row,
 )
 from ._plot_accessor import _PlotAccessorDescriptor
+from ._result_extraction import extract_results
 from ._target_accessor import _TargetAccessorDescriptor
+from ._target_dispatch import run_targeting_for_zone_and_subzones
 from ._validation import (
     _validate_problem_semantics,
     format_schema_validation_error,
@@ -30,8 +32,10 @@ __all__ = [
     "_validate_problem_semantics",
     "build_graph_payload",
     "build_problem_summary_frame",
+    "extract_results",
     "format_schema_validation_error",
     "load_problem_source",
     "locate_summary_row",
     "prepare_in_memory_problem_source",
+    "run_targeting_for_zone_and_subzones",
 ]

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_problem/_output.py

@@ -6,8 +6,8 @@ from typing import Any, Optional
 
 import pandas as pd
 
+from ...lib.schemas.report_units import split_report_value
 from ...utils.export import build_summary_dataframe
-from ...utils.miscellaneous import get_value
 
 
 def build_problem_summary_frame(
@@ -21,40 +21,55 @@ def build_problem_summary_frame(
 
     rows = []
     for target in results.targets:
+        idx = getattr(target, "idx", None)
+        qh_value, qh_unit = split_report_value(target.Qh, idx=idx)
+        qc_value, qc_unit = split_report_value(target.Qc, idx=idx)
+        qr_value, qr_unit = split_report_value(target.Qr, idx=idx)
+        hot_pinch_value, hot_pinch_unit = split_report_value(
+            target.pinch_temp.hot_temp,
+            idx=idx,
+        )
+        cold_pinch_value, cold_pinch_unit = split_report_value(
+            target.pinch_temp.cold_temp,
+            idx=idx,
+        )
         rows.append(
             {
                 "Target": target.name,
                 "State ID": getattr(target, "state_id", None),
-                "Hot Utility Target": maybe_get_value(
-                    target.Qh, state_id=getattr(target, "state_id", None)
+                "Hot Utility Target": format_res(
+                    value=qh_value,
+                    unit=qh_unit,
                 ),
-                "Cold Utility Target": maybe_get_value(
-                    target.Qc, state_id=getattr(target, "state_id", None)
+                "Cold Utility Target": format_res(
+                    value=qc_value,
+                    unit=qc_unit,
                 ),
-                "Heat Recovery": maybe_get_value(
-                    target.Qr, state_id=getattr(target, "state_id", None)
+                "Heat Recovery": format_res(
+                    value=qr_value,
+                    unit=qr_unit,
                 ),
-                "Hot Pinch": maybe_get_value(
-                    target.temp_pinch.hot_temp,
-                    state_id=getattr(target, "state_id", None),
+                "Hot Pinch": format_res(
+                    value=hot_pinch_value,
+                    unit=hot_pinch_unit,
                 ),
-                "Cold Pinch": maybe_get_value(
-                    target.temp_pinch.cold_temp,
-                    state_id=getattr(target, "state_id", None),
+                "Cold Pinch": format_res(
+                    value=cold_pinch_value,
+                    unit=cold_pinch_unit,
                 ),
                 "Hot Utilities": ", ".join(
-                    format_utility(
-                        utility.name,
-                        utility.heat_flow,
-                        state_id=getattr(target, "state_id", None),
+                    format_res(
+                        name=utility.name,
+                        value=utility.heat_flow,
+                        idx=idx,
                     )
                     for utility in target.hot_utilities
                 ),
                 "Cold Utilities": ", ".join(
-                    format_utility(
-                        utility.name,
-                        utility.heat_flow,
-                        state_id=getattr(target, "state_id", None),
+                    format_res(
+                        name=utility.name,
+                        value=utility.heat_flow,
+                        idx=idx,
                     )
                     for utility in target.cold_utilities
                 ),
@@ -106,20 +121,27 @@ def build_graph_payload(results: Any) -> Optional[dict[str, Any]]:
     }
 
 
-def maybe_get_value(value: Any, state_id: str | None = None) -> Any:
-    """Return the scalar value for OpenPinch value objects."""
-    if value is None:
-        return None
-    return get_value(value, state_id=state_id)
-
-
-def format_utility(
-    name: str,
-    heat_flow: Any,
-    state_id: str | None = None,
+def format_res(
+    name: str | None = None,
+    value: Any | None = None,
+    idx: int | None = None,
+    unit: str | None = None,
 ) -> str:
     """Render one utility summary item."""
-    value = maybe_get_value(heat_flow, state_id=state_id)
-    if value is None:
-        return f"{name}: n/a"
-    return f"{name}: {value:.2f}"
+    val, unt = split_report_value(value, idx=idx)
+    if unt is None:
+        unt = unit
+    if val is None:
+        if name:
+            return f"{name}: n/a"
+        else:
+            return "n/a"
+    if unt is None:
+        if name:
+            return f"{name}: {float(val):.2f}"
+        else:
+            return f"{float(val):.2f}"
+    if name:
+        return f"{name}: {float(val):.2f} {unt}"
+    else:
+        return f"{float(val):.2f} {unt}"

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_problem/_plot_accessor.py

@@ -36,6 +36,9 @@ _GRAPH_TYPE_ALIASES = {
     "gcc": GT.GCC.value,
     "grand composite": GT.GCC.value,
     "grand composite curve": GT.GCC.value,
+    "gcc_x": GT.GCC_X.value,
+    "exergy gcc": GT.GCC_X.value,
+    "exergetic grand composite curve": GT.GCC_X.value,
     "nlc": GT.NLP.value,
     "net load": GT.NLP.value,
     "net load curve": GT.NLP.value,
@@ -47,6 +50,9 @@ _GRAPH_TYPE_ALIASES = {
     "net_load curves": GT.NLP.value,
     "net_load profile": GT.NLP.value,
     "net_load profiles": GT.NLP.value,
+    "nlp_x": GT.NLP_X.value,
+    "exergy nlp": GT.NLP_X.value,
+    "exergetic net load profiles": GT.NLP_X.value,
     "tsp": GT.TSP.value,
     "total site": GT.TSP.value,
     "total site profiles": GT.TSP.value,
@@ -302,6 +308,23 @@ class _PlotAccessor:
             return_graph_data=return_graph_data,
         )
 
+    def exergetic_grand_composite_curve(
+        self,
+        *,
+        zone_name: Optional[str] = None,
+        index: float = 0,
+        show: bool = False,
+        return_graph_data: bool = False,
+    ):
+        """Return the first matching exergetic GCC output or figure."""
+        return self._plot_graph(
+            zone_name=zone_name,
+            graph_type=GT.GCC_X.value,
+            index=index,
+            show=show,
+            return_graph_data=return_graph_data,
+        )
+
     def grand_composite_curve_with_heat_pump(
         self,
         *,
@@ -336,6 +359,23 @@ class _PlotAccessor:
             return_graph_data=return_graph_data,
         )
 
+    def exergetic_net_load_profiles(
+        self,
+        *,
+        zone_name: Optional[str] = None,
+        index: float = 0,
+        show: bool = False,
+        return_graph_data: bool = False,
+    ):
+        """Return the first matching exergetic NLP payload or figure."""
+        return self._plot_graph(
+            zone_name=zone_name,
+            graph_type=GT.NLP_X.value,
+            index=index,
+            show=show,
+            return_graph_data=return_graph_data,
+        )
+
     def total_site_profiles(
         self,
         *,

openpinch-0.2.3/OpenPinch/classes/_problem/_result_extraction.py

@@ -0,0 +1,48 @@
+"""Helpers for converting solved zone trees into serializable result payloads."""
+
+from __future__ import annotations
+
+from typing import List
+
+from ...services.common.graph_data import get_output_graph_data
+from ..stream import Stream
+from ..stream_collection import StreamCollection
+from ..zone import Zone
+
+__all__ = ["extract_results"]
+
+
+def extract_results(zone: Zone, state_id: str | None = None) -> dict:
+    """Serialise solved targets, generated utilities, and graph payloads."""
+    return {
+        "name": zone.name,
+        "state_id": state_id,
+        "targets": _get_report(zone, state_id=state_id),
+        "utilities": _get_utilities(zone),
+        "graphs": get_output_graph_data(zone),
+    }
+
+
+def _get_report(zone: Zone, state_id: str | None = None) -> dict:
+    """Create the report payload from one zone and all nested subzones."""
+    targets: List[dict] = []
+
+    for target in zone.targets.values():
+        target_payload = target.serialize_json()
+        if state_id is not None:
+            target_payload["state_id"] = state_id
+        targets.append(target_payload)
+
+    if len(zone.subzones) > 0:
+        for subzone in zone.subzones.values():
+            targets.extend(_get_report(subzone, state_id=state_id))
+
+    return targets
+
+
+def _get_utilities(zone: Zone) -> StreamCollection:
+    """Get any default utilities generated during the analysis."""
+    utilities: StreamCollection = zone.hot_utilities + zone.cold_utilities
+    default_hu: Stream = next((u for u in utilities if u.name == "HU"), None)
+    default_cu: Stream = next((u for u in utilities if u.name == "CU"), None)
+    return [default_hu, default_cu]

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

@@ -7,6 +7,7 @@ from ...services import (
     direct_heat_integration_service,
     direct_heat_pump_service,
     direct_refrigeration_service,
+    exergy_targeting_service,
     indirect_heat_integration_service,
     indirect_heat_pump_service,
     indirect_refrigeration_service,
@@ -198,6 +199,26 @@ class _TargetAccessor:
             direct_service_func=area_cost_targeting_service,
         )
 
+    def exergy(
+        self,
+        *,
+        zone_name: Optional[str] = None,
+        options: Optional[dict[str, Any]] = None,
+        include_subzones: bool = False,
+        state_id: Optional[str] = None,
+    ) -> BaseTargetModel:
+        """Run exergy targeting on the first compatible base target family."""
+        runtime_options = dict(options or {})
+        runtime_options["DO_EXERGY_TARGETING"] = True
+        if state_id is not None:
+            runtime_options["state_id"] = state_id
+        return self._problem._execute_exergy_targeting(
+            application_zone=zone_name,
+            options=runtime_options,
+            include_subzones=include_subzones,
+            service_func=exergy_targeting_service,
+        )
+
 
 class _TargetAccessorDescriptor:
     """Non-data descriptor exposing a callable target accessor on instances."""

openpinch-0.2.1/OpenPinch/utils/multiscale_targeting.py → openpinch-0.2.3/OpenPinch/classes/_problem/_target_dispatch.py

@@ -1,21 +1,17 @@
-"""Recursive dispatch helpers for zone-scale targeting and result extraction."""
+"""Recursive dispatch helpers for zone-scale targeting across subzones."""
+
+from __future__ import annotations
 
 import inspect
-from typing import Callable, List
+from typing import Callable
 
-from ..classes.stream import Stream
-from ..classes.stream_collection import StreamCollection
-from ..classes.zone import Zone
-from ..lib.enums import ZT
-from ..services.common.graph_data import get_output_graph_data
+from ...lib.enums import ZT
+from ..zone import Zone
 
-__all__ = [
-    "get_targets_for_zone_and_sub_zones",
-    "extract_results",
-]
+__all__ = ["run_targeting_for_zone_and_subzones"]
 
 
-def get_targets_for_zone_and_sub_zones(
+def run_targeting_for_zone_and_subzones(
     zone: Zone,
     direct_service_func: Callable = None,
     indirect_service_func: Callable = None,
@@ -28,17 +24,6 @@ def get_targets_for_zone_and_sub_zones(
     return handler(zone, direct_service_func, indirect_service_func, args)
 
 
-def extract_results(zone: Zone, state_id: str | None = None) -> dict:
-    """Serialise solved targets, generated utilities, and graph payloads."""
-    return {
-        "name": zone.name,
-        "state_id": state_id,
-        "targets": _get_report(zone, state_id=state_id),
-        "utilities": _get_utilities(zone),
-        "graphs": get_output_graph_data(zone),
-    }
-
-
 ################################################################################
 # Helper functions
 ################################################################################
@@ -172,16 +157,11 @@ def _get_site_targets(
     indirect_service_func: Callable = None,
     args: dict | None = None,
 ):
-    """Targets heat integration using Total Site Anlysis,
-    by systematically analysing individual zones and then performing
-    site-level indirect integration through the utility system.
-    """
+    """Run site targeting over the full nested zone hierarchy."""
 
-    # Totally integrated analysis for a site zone
     if isinstance(direct_service_func, Callable):
         _invoke_service(direct_service_func, zone, args)
 
-    # Targets sub-zone energy requirements
     if len(zone.subzones) > 0:
         for subzone in zone.subzones.values():
             if subzone.type == ZT.O.value:
@@ -214,7 +194,6 @@ def _get_site_targets(
                     "site, process, and operation zones."
                 )
 
-        # Calculates indirect targets based on different approaches
         if isinstance(indirect_service_func, Callable):
             _invoke_service(indirect_service_func, zone, args)
 
@@ -227,7 +206,7 @@ def _get_community_targets(
     indirect_service_func: Callable = None,
     args: dict | None = None,
 ):
-    """Targets a Community Zone."""
+    """Target a community zone by dispatching each site child."""
     for subzone in zone.subzones.values():
         subzone = _invoke_target_handler(
             _get_site_targets,
@@ -245,7 +224,7 @@ def _get_regional_targets(
     indirect_service_func: Callable = None,
     args: dict | None = None,
 ):
-    """Targets a Regional Zone."""
+    """Target a regional zone by dispatching each community child."""
     for subzone in zone.subzones.values():
         subzone = _invoke_target_handler(
             _get_community_targets,
@@ -257,31 +236,6 @@ def _get_regional_targets(
     return zone
 
 
-def _get_report(zone: Zone, state_id: str | None = None) -> dict:
-    """Creates the database summary of zone targets."""
-    targets: List[dict] = []
-
-    for target in zone.targets.values():
-        target_payload = target.serialize_json()
-        if state_id is not None:
-            target_payload["state_id"] = state_id
-        targets.append(target_payload)
-
-    if len(zone.subzones) > 0:
-        for subzone in zone.subzones.values():
-            targets.extend(_get_report(subzone, state_id=state_id))
-
-    return targets
-
-
-def _get_utilities(zone: Zone) -> StreamCollection:
-    """Gets a list of any default utilities generated during the analysis."""
-    utilities: StreamCollection = zone.hot_utilities + zone.cold_utilities
-    default_hu: Stream = next((u for u in utilities if u.name == "HU"), None)
-    default_cu: Stream = next((u for u in utilities if u.name == "CU"), None)
-    return [default_hu, default_cu]
-
-
 _TARGET_HANDLERS = {
     ZT.R.value: _get_regional_targets,
     ZT.C.value: _get_community_targets,

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_problem/_validation.py

@@ -12,6 +12,7 @@ from pydantic import ValidationError
 from ...lib.enums import ST
 from ...lib.schemas.io import TargetInput
 from ...lib.schemas.workspace import ValidationIssue, ValidationReport
+from ...lib.unit_system import standardise_input_value
 from ..value import Value
 
 ValidationContext = dict[str, list[dict[str, Any]]]
@@ -116,6 +117,8 @@ def semantic_issues(
 ) -> list[ValidationIssue]:
     """Return semantic validation issues for one validated problem definition."""
     issues: list[ValidationIssue] = []
+    options = problem_inputs.options if isinstance(problem_inputs.options, dict) else {}
+    input_unit_config = {"INPUT_UNITS": options.get("INPUT_UNITS", {})}
 
     if len(problem_inputs.streams) == 0:
         issues.append(
@@ -135,6 +138,7 @@ def semantic_issues(
             record_label=label,
             field_names=("t_supply", "t_target", "heat_flow", "dt_cont", "htc"),
             optional_field_names=("dt_cont", "htc"),
+            config=input_unit_config,
         )
         issues.extend(stream_value_issues)
         issues.extend(
@@ -168,6 +172,7 @@ def semantic_issues(
                 "htc",
                 "price",
             ),
+            config=input_unit_config,
         )
         issues.extend(utility_value_issues)
         issues.extend(
@@ -365,6 +370,7 @@ def _coerce_validation_values(
     record_label: Optional[str],
     field_names: tuple[str, ...],
     optional_field_names: tuple[str, ...] = (),
+    config: dict[str, dict[str, Any]] | None = None,
 ) -> tuple[
     dict[str, Value | None],
     dict[str, tuple[list[str] | None, np.ndarray | None]],
@@ -382,7 +388,11 @@ def _coerce_validation_values(
             values[field_name] = None
             continue
         try:
-            values[field_name] = Value(raw_value)
+            values[field_name] = standardise_input_value(
+                raw_value,
+                field_name=field_name,
+                config=config,
+            )
         except (TypeError, ValueError) as exc:
             values[field_name] = None
             issues.append(

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_stream_collection/_helpers.py

@@ -1,5 +1,7 @@
 """Helper utilities for stream collection operations."""
 
+from __future__ import annotations
+
 import pickle
 from typing import Tuple
 

{openpinch-0.2.1 → openpinch-0.2.3}/OpenPinch/classes/_workspace/views.py

@@ -42,6 +42,10 @@ _SUMMARY_METRIC_COLUMNS = [
 ]
 
 
+def _unit_column(metric: str) -> str:
+    return f"{metric} (unit)"
+
+
 def invalid_variant_view(
     *,
     variant_name: str,
@@ -161,6 +165,7 @@ def summary_cards(frame: pd.DataFrame) -> list[SummaryCard]:
                     target_name=target_name,
                     label=metric,
                     value=json_safe(row.get(metric)),
+                    unit=maybe_string(row.get(_unit_column(metric))),
                 )
             )
     return cards
@@ -276,6 +281,13 @@ def summary_metric_deltas(
         for metric in _SUMMARY_METRIC_COLUMNS:
             base_value = json_safe(base_row.get(metric))
             variant_value = json_safe(variant_row.get(metric))
+            unit = maybe_string(
+                base_row.get(_unit_column(metric))
+                or variant_row.get(_unit_column(metric))
+            )
+            units_match = base_row.get(_unit_column(metric)) == variant_row.get(
+                _unit_column(metric)
+            )
             deltas.append(
                 VariantMetricDelta(
                     base_variant=base_name,
@@ -285,7 +297,10 @@ def summary_metric_deltas(
                     metric=metric,
                     base_value=base_value,
                     variant_value=variant_value,
-                    delta=numeric_delta(base_value, variant_value),
+                    unit=unit,
+                    delta=numeric_delta(base_value, variant_value)
+                    if units_match
+                    else None,
                 )
             )
     return deltas