OpenPinch 0.7.1__tar.gz → 0.7.2__tar.gz

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/adapters/io/csv.py

@@ -13,11 +13,14 @@ from .records import (
     validate_utility_data,
 )
 from .tabular import (
-    get_column_names_and_units as _get_column_names_and_units,
+    problem_frame_from_sheet as _problem_frame_from_sheet,
 )
 from .tabular import (
     problem_records_from_frame as _write_problem_to_dict_and_list,
 )
+from .tabular import (
+    summary_frame_from_sheet as _summary_frame_from_sheet,
+)
 from .tabular import (
     target_records_from_frame as _write_targets_to_dict_and_list,
 )
@@ -121,18 +124,15 @@ def _parse_csv_with_units(
             "(names, units, and data rows)."
         )
 
-    col_names, col_units = _get_column_names_and_units(
-        df_full,
-        sheet_name=kind,
-        row_units=row_units,
-    )
-    df_data: pd.DataFrame = df_full.iloc[row_data:].copy()
-
-    for index in range(len(df_data.columns), len(col_names), -1):
-        df_data = df_data.drop(columns=index - 1)
-    # Columns the table leaves out stay absent so the input contract applies
-    # its defaults; padding them with 0 forced dt_cont and htc to zero.
-    df_data.columns = col_names[: len(df_data.columns)]
+    if kind == "Summary":
+        df_data, units_map = _summary_frame_from_sheet(df_full, row_units, row_data)
+    else:
+        # Columns the table leaves out stay absent so the input contract
+        # applies its defaults; padding them with 0 forced dt_cont and htc to
+        # zero.
+        df_data, units_map = _problem_frame_from_sheet(
+            df_full, kind, row_units, row_data
+        )
 
     def to_number_maybe(value):
         if isinstance(value, str):
@@ -151,7 +151,6 @@ def _parse_csv_with_units(
     text_columns = [name for name in ("zone", "name", "type") if name in df_data]
     numeric_columns = [name for name in df_data.columns if name not in text_columns]
     df_data[numeric_columns] = df_data[numeric_columns].map(to_number_maybe)
-    units_map = dict(zip(col_names, col_units))
     if kind == "Summary":
         return _write_targets_to_dict_and_list(df_data, units_map, project_name)
     return _write_problem_to_dict_and_list(df_data, units_map)

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/adapters/io/records.py

@@ -53,6 +53,7 @@ def validate_stream_data(sd: pd.DataFrame):
         append = cleaned.append
         previous_zone = None
         used_names = set()
+        original_names: dict[tuple, str] = {}
         next_default_name_idx = 1
 
         for record in records:
@@ -84,6 +85,15 @@ def validate_stream_data(sd: pd.DataFrame):
                 )
             else:
                 record["name"] = _normalize_label(name, default_stream_prefix)
+                key = (record["zone"], record["name"])
+                original = _label_text(name)
+                earlier = original_names.setdefault(key, original)
+                if earlier != original:
+                    raise ValueError(
+                        f"Stream names {earlier!r} and {original!r} in zone "
+                        f"{record['zone']!r} both become {record['name']!r}; "
+                        "rename one of them."
+                    )
 
             used_names.add(record["name"])
             append(record)
@@ -121,24 +131,51 @@ def validate_utility_data(ud: pd.DataFrame):
             valid = ~name_series.isna()
             if valid.any():
                 valid &= name_series.astype(str).str.strip() != ""
+            records = ud.replace({pd.NA: None}).to_dict(orient="records")
+            for row, record in enumerate(records, start=1):
+                if not valid.iloc[row - 1]:
+                    _warn_unnamed_utility(row, record)
             ud = ud.loc[valid].reset_index(drop=True)
         return ud
 
     cleaned = []
     append = cleaned.append
-    for record in ud:
+    for row, record in enumerate(ud, start=1):
         if not isinstance(record, dict):
             continue
         name = record.get("name")
-        if name is None or pd.isna(name):
-            continue
-        if isinstance(name, str) and not name.strip():
+        if (
+            name is None
+            or pd.isna(name)
+            or (isinstance(name, str) and not name.strip())
+        ):
+            _warn_unnamed_utility(row, record)
             continue
         record = {**record, "name": _label_text(name)}
         append(record)
     return cleaned
 
 
+def _warn_unnamed_utility(row: int, record: dict) -> None:
+    """Warn when a utility row dropped for having no name carries data."""
+    if any(_cell_has_data(value) for key, value in record.items() if key != "name"):
+        warnings.warn(
+            f"Utility data: utility row {row} has no name and was ignored.",
+            UserWarning,
+            stacklevel=4,
+        )
+
+
+def _cell_has_data(value) -> bool:
+    if isinstance(value, dict):
+        value = value.get("value", value.get("values"))
+    if isinstance(value, str):
+        return bool(value.strip())
+    if isinstance(value, (list, tuple)):
+        return any(_cell_has_data(item) for item in value)
+    return value is not None and not pd.isna(value)
+
+
 def _label_text(value) -> str:
     """Return a name as text; spreadsheets give numeric names as numbers."""
     if isinstance(value, float) and value.is_integer():

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/adapters/io/tabular.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import re
+import warnings
 from typing import Any, Optional
 
+import numpy as np
 import pandas as pd
 
 from ...domain.enums import IntegrationType, TargetMethod, ZoneType
@@ -59,12 +62,126 @@ def get_column_names_and_units(df_full, sheet_name, row_units=1):
     return col_names, col_units
 
 
+# Header spellings accepted for each column, compared after lower-casing,
+# reading a Greek delta as "d", dropping any bracketed unit and removing
+# everything but letters and digits.
+_HEADER_ALIASES = {
+    "Stream Data": {
+        "zone": ("process zone", "zone name"),
+        "name": ("stream", "stream name"),
+        "t_supply": ("ts", "tsupply", "supply temperature", "tin"),
+        "t_target": ("tt", "ttarget", "target temperature", "tout"),
+        "heat_flow": ("dh", "heat load", "duty", "q"),
+        "heat_capacity_flowrate": ("cp", "mcp", "fcp", "heat capacity flowrate"),
+        "dt_cont": ("dtcont", "dt contribution"),
+        "htc": ("heat transfer coefficient",),
+    },
+    "Utility Data": {
+        "name": ("utility", "utility name"),
+        "type": ("utility type",),
+        "t_supply": ("ts", "tsupply", "supply temperature", "tin"),
+        "t_target": ("tt", "ttarget", "target temperature", "tout"),
+        "dt_cont": ("dtcont", "dt contribution"),
+        "price": ("cost", "unit price"),
+        "htc": ("heat transfer coefficient",),
+        "heat_flow": ("dh", "heat load", "duty", "q"),
+    },
+}
+
+
+def _header_key(text: str) -> str:
+    key = re.sub(r"\(.*?\)|\[.*?\]", "", text).lower().replace("δ", "d")
+    return re.sub(r"[^a-z0-9]", "", key)
+
+
+def _map_header_row(header: list, sheet_name: str) -> Optional[list]:
+    """Return the field name for each column, or None when no header is known."""
+    aliases = {
+        _header_key(alias): field
+        for field, names in _HEADER_ALIASES[sheet_name].items()
+        for alias in (field, *names)
+    }
+    labels = [
+        cell.strip() if isinstance(cell, str) and cell.strip() else None
+        for cell in header
+    ]
+    fields = [aliases.get(_header_key(label)) if label else None for label in labels]
+    if not any(fields):
+        return None
+    for field in set(filter(None, fields)):
+        columns = [label for label, f in zip(labels, fields) if f == field]
+        if len(columns) > 1:
+            raise ValueError(
+                f"{sheet_name} has more than one column for {field!r}: "
+                f"{', '.join(repr(column) for column in columns)}."
+            )
+    unknown = [label for label, f in zip(labels, fields) if label and not f]
+    if unknown:
+        warnings.warn(
+            f"{sheet_name} column(s) {', '.join(repr(u) for u in unknown)} "
+            "are not recognised and were ignored.",
+            UserWarning,
+            stacklevel=4,
+        )
+    return fields
+
+
+def problem_frame_from_sheet(
+    df_full: pd.DataFrame,
+    sheet_name: str,
+    row_units: int,
+    row_data: int,
+) -> tuple[pd.DataFrame, dict]:
+    """Select a stream or utility table's columns and their units.
+
+    Columns are matched by the header text in the first row. A header with no
+    recognised column name falls back to the fixed column order.
+    """
+    col_names, _ = get_column_names_and_units(df_full, sheet_name, row_units)
+    raw_units = [
+        unit.replace("°", "deg") if isinstance(unit, str) else None
+        for unit in df_full.iloc[row_units].tolist()
+    ]
+    fields = _map_header_row(df_full.iloc[0].tolist(), sheet_name)
+    if fields is None:
+        warnings.warn(
+            f"{sheet_name} header row has no recognised column names; columns "
+            f"are read in the order {', '.join(col_names)}.",
+            UserWarning,
+            stacklevel=3,
+        )
+        count = min(len(df_full.columns), len(col_names))
+        fields = col_names[:count] + [None] * (len(df_full.columns) - count)
+    positions = [index for index, field in enumerate(fields) if field]
+    df_data = df_full.iloc[row_data:, positions].copy()
+    df_data.columns = [fields[index] for index in positions]
+    units_map = {fields[index]: raw_units[index] for index in positions}
+    return df_data, units_map
+
+
+def summary_frame_from_sheet(
+    df_full: pd.DataFrame,
+    row_units: int,
+    row_data: int,
+) -> tuple[pd.DataFrame, dict]:
+    """Name a summary table's columns by position and collect their units."""
+    col_names, col_units = get_column_names_and_units(df_full, "Summary", row_units)
+    df_data = df_full.iloc[row_data:, : len(col_names)].copy()
+    df_data.columns = col_names[: len(df_data.columns)]
+    return df_data, dict(zip(col_names, col_units))
+
+
 def problem_records_from_frame(df_data: pd.DataFrame, units_map: dict) -> list:
     """Convert stream/utility tables into JSON-ready row dictionaries with units."""
     if df_data.empty:
         return []
 
     clean_df = df_data.replace({pd.NA: None}).reset_index(drop=True)
+    # Blank separator rows (empty or whitespace-only cells) carry no data; drop
+    # them before numeric cells are wrapped as {"value": None, ...} records.
+    clean_df = clean_df.loc[~clean_df.map(_is_blank_cell).all(axis=1)]
+    if clean_df.empty:
+        return []
     records = clean_df.to_dict(orient="records")
 
     for column_name, unit in units_map.items():
@@ -78,11 +195,14 @@ def problem_records_from_frame(df_data: pd.DataFrame, units_map: dict) -> list:
                 lambda value: isinstance(value, str) and not value.strip()
             )
             invalid = numeric_values.isna() & ~missing
+            invalid |= column_values.map(
+                lambda value: isinstance(value, (bool, np.bool_))
+            )
             if invalid.any():
                 row = invalid[invalid].index[0]
                 raise ValueError(
                     f"Column {column_name!r} has a non-numeric value at "
-                    f"data row {row + 1}: {column_values.iloc[row]!r}."
+                    f"data row {row + 1}: {column_values.loc[row]!r}."
                 )
             value_entries = [
                 {"value": (None if pd.isna(val) else float(val)), "unit": unit}
@@ -97,6 +217,12 @@ def problem_records_from_frame(df_data: pd.DataFrame, units_map: dict) -> list:
     return records
 
 
+def _is_blank_cell(value: Any) -> bool:
+    if isinstance(value, str):
+        return not value.strip()
+    return value is None or bool(pd.isna(value))
+
+
 def target_records_from_frame(
     df_data: pd.DataFrame,
     units_map: dict,

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/adapters/io/workbook.py

@@ -11,11 +11,14 @@ from .records import (
     validate_utility_data,
 )
 from .tabular import (
-    get_column_names_and_units as _get_column_names_and_units,
+    problem_frame_from_sheet as _problem_frame_from_sheet,
 )
 from .tabular import (
     problem_records_from_frame as _write_problem_to_dict_and_list,
 )
+from .tabular import (
+    summary_frame_from_sheet as _summary_frame_from_sheet,
+)
 from .tabular import (
     target_records_from_frame as _write_targets_to_dict_and_list,
 )
@@ -102,23 +105,16 @@ def _parse_sheet_with_units(
             "(names, units, and data rows)."
         )
 
-    col_names, col_units = _get_column_names_and_units(
-        df_full,
-        sheet_name,
-        row_units,
-    )
-    df_data: pd.DataFrame = df_full.iloc[row_data:].copy()
-
-    for index in range(len(df_data.columns), len(col_names), -1):
-        df_data = df_data.drop(columns=index - 1)
-    # Columns the table leaves out stay absent so the input contract applies
-    # its defaults; padding them with 0 forced dt_cont and htc to zero.
-    df_data.columns = col_names[: len(df_data.columns)]
-
-    units_map = dict(zip(col_names, col_units))
-    if sheet_name != "Summary":
-        # Keep every numeric column's unit (price included), as the CSV reader
-        # does; text columns carry no unit.
+    if sheet_name == "Summary":
+        df_data, units_map = _summary_frame_from_sheet(df_full, row_units, row_data)
+    else:
+        # Columns the table leaves out stay absent so the input contract
+        # applies its defaults; padding them with 0 forced dt_cont and htc to
+        # zero. Numeric columns keep their unit (price included), as the CSV
+        # reader does; text columns carry no unit.
+        df_data, units_map = _problem_frame_from_sheet(
+            df_full, sheet_name, row_units, row_data
+        )
         units_map = {
             key: unit
             for key, unit in units_map.items()

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/analysis/energy_transfer/diagram.py

@@ -259,6 +259,15 @@ def get_base_problem_table(
 
 
 def get_source_problem_table(target: UtilitySummaryTarget) -> ProblemTable:
+    # The target's own table is unrounded; the saved GCC graph is rounded to
+    # 4 dp for plotting, so it is only a fallback.
+    table = getattr(target, "pt", None)
+    if (
+        isinstance(table, ProblemTable)
+        and has_problem_table_values(table, ProblemTableLabel.T)
+        and has_problem_table_values(table, ProblemTableLabel.H_NET)
+    ):
+        return table
     graphs = getattr(target, "graphs", None)
     if isinstance(graphs, dict):
         gcc = graphs.get(GraphType.GCC.value)

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/analysis/exergy/service.py

@@ -332,11 +332,9 @@ def apply_exergy_targeting(target: Any, *, dt_cont_multiplier: float = 1.0) -> A
     }
     target.exergy_sources = float(nlp_output["source_total"])
     target.exergy_sinks = float(nlp_output["sink_total"])
-    target.ETE = (
-        (target.exergy_sinks / target.exergy_sources)
-        if target.exergy_sources > tol
-        else 0.0
-    )
+    gained, released = _balanced_curve_exergy_transfer(target, spec)
+    target.exergy_released = released
+    target.ETE = gained / released if released > tol else 0.0
     target.exergy_req_min = float(gcc_output[ProblemTableLabel.X_GCC.value][0])
     target.exergy_des_min = float(gcc_output[ProblemTableLabel.X_GCC.value][-1])
     return target
@@ -515,6 +513,129 @@ def _resolve_target_exergy_spec(
     return None
 
 
+def _balanced_curve_exergy_transfer(
+    target: Any, spec: dict[str, Any]
+) -> tuple[float, float]:
+    """Return the exergy gained and released across the BCC heat transfer (kW).
+
+    The Balanced Composite Curves are the process composites plus the
+    utilities (and any heat-pump streams), relative to ``ENV_TEMPERATURE``.
+    Above ambient the hot curve releases exergy and the cold curve gains it;
+    below ambient the roles swap, since cooling a stream there raises its
+    exergy. The ratio of gained to released exergy is the exergy transfer
+    effectiveness: at most 1, and the shortfall is the exergy destroyed in
+    heat transfer. A Direct Integration target uses its real-temperature
+    table. Other targets use their own table, un-shifted interval by interval
+    as the exergy curves are.
+    """
+    t_env = spec["t_env"]
+    pt_real = getattr(target, "pt_real", None)
+    real_columns = (
+        [
+            _optional_column(pt_real, label)
+            for label in (
+                ProblemTableLabel.H_HOT,
+                ProblemTableLabel.H_HOT_UT,
+                ProblemTableLabel.H_COLD,
+                ProblemTableLabel.H_COLD_UT,
+            )
+        ]
+        if pt_real is not None
+        else [None]
+    )
+    if all(column is not None for column in real_columns):
+        t_vals = _to_float_array(pt_real[ProblemTableLabel.T])
+        hot_curves = [(real_columns[0], 0.0), (real_columns[1], 0.0)]
+        cold_curves = [(real_columns[2], 0.0), (real_columns[3], 0.0)]
+    else:
+        pt = target.pt
+        t_vals = spec["temperatures"]
+        n_intervals = max(len(t_vals) - 1, 0)
+        if spec["gcc_is_real"]:
+            hot_offset = cold_offset = np.zeros(n_intervals, dtype=float)
+        else:
+            hot_offset = _interval_shifts(
+                spec.get("hot_shifts"), n_intervals, spec["dt_cont_shift"]
+            )
+            cold_offset = -_interval_shifts(
+                spec.get("cold_shifts"), n_intervals, spec["dt_cont_shift"]
+            )
+        # Heat-pump streams carry no temperature contribution.
+        hot_curves = [
+            (_optional_column(pt, ProblemTableLabel.H_HOT), hot_offset),
+            (_optional_column(pt, ProblemTableLabel.H_HOT_UT), hot_offset),
+            (_optional_column(pt, ProblemTableLabel.H_HOT_HP), 0.0),
+        ]
+        cold_curves = [
+            (_optional_column(pt, ProblemTableLabel.H_COLD), cold_offset),
+            (_optional_column(pt, ProblemTableLabel.H_COLD_UT), cold_offset),
+            (_optional_column(pt, ProblemTableLabel.H_COLD_HP), 0.0),
+        ]
+    gained = released = 0.0
+    for curves, is_hot in ((hot_curves, True), (cold_curves, False)):
+        for h_vals, offset in curves:
+            if h_vals is None:
+                continue
+            # Above ambient the hot curve releases and the cold curve gains;
+            # below ambient it is the other way round.
+            above, below = _curve_exergy_changes(t_vals, h_vals, offset, t_env)
+            if is_hot:
+                released += above
+                gained += below
+            else:
+                released += below
+                gained += above
+    return float(gained), float(released)
+
+
+def _curve_exergy_changes(
+    t_vals: np.ndarray,
+    h_vals: np.ndarray,
+    offset: np.ndarray | float,
+    t_env: float,
+) -> tuple[float, float]:
+    """Return the (above-ambient, below-ambient) exergy of a T-H curve, in kW.
+
+    Each interval contributes dH (1 - T0/T) integrated along it, which is
+    positive above ambient and negative below; intervals that cross ambient
+    are split there, and the below-ambient part is returned as a magnitude.
+    ``t_vals`` are in degC, falling down the table, and ``offset`` moves each
+    interval onto real temperatures. A linear segment is integrated exactly.
+    """
+    h_vals = np.nan_to_num(np.asarray(h_vals, dtype=float))
+    t_abs = np.asarray(t_vals, dtype=float) + C_to_K
+    t_upper = t_abs[:-1] + offset
+    t_lower = t_abs[1:] + offset
+    t_ref = t_env + C_to_K
+    delta_h = h_vals[:-1] - h_vals[1:]
+    above = below = 0.0
+    for t_u, t_l, d_h in zip(
+        np.broadcast_to(t_upper, delta_h.shape),
+        np.broadcast_to(t_lower, delta_h.shape),
+        delta_h,
+    ):
+        if abs(d_h) <= tol:
+            continue
+        span = t_u - t_l
+        if abs(span) <= tol:
+            pieces = [d_h * (1.0 - t_ref / t_u)]
+        else:
+            cp = d_h / span
+            hi, lo = max(t_u, t_l), min(t_u, t_l)
+            bounds = [hi, t_ref, lo] if lo < t_ref < hi else [hi, lo]
+            sign = 1.0 if span > 0 else -1.0
+            pieces = [
+                sign * cp * ((a - b) - t_ref * np.log(a / b))
+                for a, b in zip(bounds[:-1], bounds[1:])
+            ]
+        for piece in pieces:
+            if piece >= 0.0:
+                above += piece
+            else:
+                below -= piece
+    return float(above), float(below)
+
+
 def _zone_stream_shift_sources(target: Any) -> tuple[list, list, int | None] | None:
     """Return the hot and cold streams (with utilities) behind ``target``."""
     zone = getattr(target, "parent_zone", None)

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/analysis/graphs/composite.py

@@ -6,7 +6,7 @@ from typing import Any
 
 import numpy as np
 
-from ...domain.configuration import tol
+from ...domain.configuration import duty_tolerance, heat_resolution, tol
 from ...domain.enums import (
     ArrowHead,
     GraphType,
@@ -34,12 +34,16 @@ def clean_composite_curve_ends(
     """Remove redundant constant-enthalpy points from curve ends."""
     y_vals = np.asarray(y_vals)
     x_vals = np.asarray(x_vals)
-    # Compare the duty range with tol (variance is in kW^2, so a small curve
-    # with a real duty would vanish).
-    if x_vals.size == 0 or np.ptp(x_vals) <= tol:
+    # Compare the duty range with the heat-flow resolution (variance is in
+    # kW^2, so a small curve with a real duty would vanish).
+    if x_vals.size == 0 or np.ptp(x_vals) <= heat_resolution(x_vals):
         return np.array([]), np.array([])
-    start_mask = ~np.isclose(x_vals, x_vals[0] * np.ones(len(x_vals)), atol=tol)
-    end_mask = ~np.isclose(x_vals, x_vals[-1] * np.ones(len(x_vals)), atol=tol)
+    # Only rounding residue counts as constant at the ends: an absolute
+    # tolerance relative to the duty, not np.isclose's default rtol=1e-5 of
+    # the end value, which trimmed real end segments on MW-scale curves.
+    atol = max(duty_tolerance(x_vals), np.finfo(float).eps)
+    start_mask = np.abs(x_vals - x_vals[0]) > atol
+    end_mask = np.abs(x_vals - x_vals[-1]) > atol
     start = np.flatnonzero(start_mask)[0] - 1
     end = np.flatnonzero(end_mask)[-1] + 1
     return y_vals[start : end + 1], x_vals[start : end + 1]
@@ -114,7 +118,11 @@ def _make_composite_graph(
     for field, stream_loc in zip(fields, stream_types):
         column_key = _column_key(field)
         x_vals = _column_to_list(data, column_key)
-        if _should_plot_series(x_vals):
+        # A constant series (for example the cold composite of a problem with
+        # only hot streams) has no curve to draw.
+        if _should_plot_series(x_vals) and np.ptp(
+            np.asarray(x_vals, dtype=float)
+        ) > heat_resolution(x_vals):
             segments.extend(
                 _graph_cc(
                     key,

{openpinch-0.7.1 → openpinch-0.7.2}/OpenPinch/analysis/heat_exchanger_networks/extraction/metadata.py

@@ -252,9 +252,9 @@ def _identities_by_axis(
     )
 
 
-def _single_utility(identities: tuple[str, ...], label: str) -> str:
+def _utilities(identities: tuple[str, ...], label: str) -> tuple[str, ...]:
     if not identities:
         raise ValueError(
             f"solved heat exchanger network extraction requires at least one {label}."
         )
-    return identities[0]
+    return identities