Reconcile companion node names against the main result file

mikeio1d decodes '.res' text as UTF-8 but '.resx' text as the Windows ANSI
codepage, so a node named 'ØST' in one file is 'ØST' in the other. Four
Danish tank names in a real EPANET model were enough to make the two files
look like different models and fail validation.

Worse when validation passed: the merge looks locations up by the main
file's name, so those nodes lost their companion quantities silently.

The repair is only used when it produces a name the main file actually has,
so a companion from a genuinely different model still raises.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: jpalm3r

src/modelskill/model/adapters/_res1d.py

@@ -5,9 +5,10 @@
 import pandas as pd
 
 if TYPE_CHECKING:
-    from mikeio1d import Res1D
     from mikeio1d.result_network import ResultNode, ResultGridPoint, ResultReach
 
+    from modelskill.network import _Companion
+
 from modelskill.network import NetworkNode, ReachBreakPoint, NetworkReach
 
 
@@ -155,7 +156,7 @@ def _build_reach_breakpoints(
     length: float | None,
     quantities: set[str] | None,
     populate_gridpoints: bool,
-    extra: Res1D | None = None,
+    extra: _Companion | None = None,
 ) -> list[ReachBreakPoint]:
     """Build a reach's break points from its mikeio1d gridpoints.
 
@@ -189,7 +190,9 @@ def _build_reach_breakpoints(
         extra_gridpoints = extra.reaches[reach.name].gridpoints
 
     breakpoints: list[ReachBreakPoint] = []
-    for i, (gp, distances) in enumerate(zip(unique_gridpoints, distances_per_gridpoint)):
+    for i, (gp, distances) in enumerate(
+        zip(unique_gridpoints, distances_per_gridpoint)
+    ):
         data = _simplify_colnames(gp, quantities) if populate_gridpoints else None
         if data is not None and i < len(extra_gridpoints):
             data = _merge_extra_quantities(

src/modelskill/network/__init__.py

@@ -74,6 +74,81 @@
 }
 
 
+# The encodings a companion file's text is worth re-reading as. mikeio1d hands
+# back '.res' names decoded as UTF-8 but '.resx' names decoded with the Windows
+# ANSI codepage, so a name holding a non-ASCII character arrives spelled two
+# ways from one model. cp1252 is that codepage on a Western-European Windows.
+_COMPANION_ENCODINGS = ("cp1252", "latin-1")
+
+
+def _repair_mis_decoded(name: str) -> list[str]:
+    """Re-read a name as UTF-8, undoing a single-byte decoding of those bytes.
+
+    Parameters
+    ----------
+    name : str
+        A location name as the companion file reported it.
+
+    Returns
+    -------
+    list of str
+        The candidate spellings, which is empty when no encoding round-trips.
+        A caller must check a candidate against the main file before using it:
+        the encoding that produced the name is a guess.
+    """
+    candidates = []
+    for encoding in _COMPANION_ENCODINGS:
+        try:
+            repaired = name.encode(encoding).decode("utf-8")
+        except (UnicodeEncodeError, UnicodeDecodeError):
+            continue
+        if repaired != name and repaired not in candidates:
+            candidates.append(repaired)
+    return candidates
+
+
+def _rekey_by_main_file(locations: Any, known: Any) -> dict[str, Any]:
+    """Key a companion file's locations by their names in the main result file.
+
+    A name that already matches, or that no re-reading reconciles, keeps the
+    spelling it came with — so a companion from a genuinely different model
+    still holds names the main file does not, and validation still catches it.
+
+    Parameters
+    ----------
+    locations : mapping of str to location
+        The companion file's nodes or reaches.
+    known : container of str
+        The main file's names for the same kind of location.
+
+    Returns
+    -------
+    dict of str to location
+    """
+    rekeyed = {}
+    for name in locations:
+        key = name
+        if name not in known:
+            key = next(
+                (c for c in _repair_mis_decoded(name) if c in known),
+                name,
+            )
+        rekeyed[key] = locations[name]
+    return rekeyed
+
+
+class _Companion:
+    """A companion result file, keyed by the main file's location names.
+
+    Stands in for the ``Res1D`` it wraps everywhere the loader reaches into a
+    companion, so a node or reach is found under one spelling of its name.
+    """
+
+    def __init__(self, res: Res1D, extra: Res1D) -> None:
+        self.nodes = _rekey_by_main_file(extra.nodes, res.nodes)
+        self.reaches = _rekey_by_main_file(extra.reaches, res.reaches)
+
+
 def _check_file_path_is_str(res: Res1D) -> None:
     """Reject a Res1D opened with a path object rather than a string.
 
@@ -727,9 +802,14 @@ def _read_companion_lengths(inp: str | Path) -> dict[str, float]:
         return read_pipe_lengths(path)
 
     @staticmethod
-    def _open_companion_result(res: Res1D, resx: str | Path | Res1D) -> Res1D:
+    def _open_companion_result(res: Res1D, resx: str | Path | Res1D) -> _Companion:
         """Open and validate a companion ``.resx`` result file.
 
+        Returns
+        -------
+        _Companion
+            The companion's locations, keyed by their names in ``res``.
+
         Raises
         ------
         ValueError
@@ -768,23 +848,25 @@ def _open_companion_result(res: Res1D, resx: str | Path | Res1D) -> Res1D:
                 f"{len(res.time_index)} ending {res.end_time}."
             )
 
-        unknown_nodes = set(extra.nodes) - set(res.nodes)
+        companion = _Companion(res, extra)
+
+        unknown_nodes = set(companion.nodes) - set(res.nodes)
         if unknown_nodes:
             raise ValueError(
                 f"The '.resx' companion holds nodes {sorted(unknown_nodes)} that are "
                 "absent from the '.res' network, so the two files do not describe "
                 "the same model."
             )
 
-        unknown_reaches = set(extra.reaches) - set(res.reaches)
+        unknown_reaches = set(companion.reaches) - set(res.reaches)
         if unknown_reaches:
             raise ValueError(
                 f"The '.resx' companion holds reaches {sorted(unknown_reaches)} that are "
                 "absent from the '.res' network, so the two files do not describe "
                 "the same model."
             )
 
-        return extra
+        return companion
 
     @staticmethod
     def _validate_extension(
@@ -837,7 +919,7 @@ def _load_res1d_network(
         nodes: list[str],
         reaches: list[str],
         *,
-        extra: Res1D | None = None,
+        extra: _Companion | None = None,
         lengths: dict[str, float] | None = None,
         quantities: set[str] | None = None,
     ) -> list[Res1DReach]:

tests/test_network.py

@@ -4,6 +4,7 @@
 import shutil
 import sys
 from pathlib import Path
+from types import SimpleNamespace
 import pytest
 
 pytest.importorskip("networkx")
@@ -32,8 +33,11 @@
     _EPANET_EXTENSIONS,
     _MIKE_EXTENSIONS,
     _UNSUPPORTED_EXTENSIONS,
+    _Companion,
     _find_epanet_companions,
     _network_from_path,
+    _repair_mis_decoded,
+    _rekey_by_main_file,
 )
 from modelskill.obs import NodeObservation, ReachObservation
 from modelskill.quantity import Quantity
@@ -1909,6 +1913,51 @@ def test_unsupported_type_is_refused(self):
             Network.from_epanet(_EPANET_RES, resx=42)  # type: ignore[arg-type]
 
 
+class TestCompanionNameEncoding:
+    """mikeio1d reads '.res' names as UTF-8 and '.resx' names as CP1252.
+
+    A node called 'ØST' in one file is 'ØST' in the other, so the same model
+    looks like two - and the four Danish tank names in a real MIKE+ EPANET
+    model were the ones that surfaced it.
+    """
+
+    def test_a_mis_decoded_name_is_recovered(self):
+        assert _repair_mis_decoded("ØST") == ["ØST"]
+        assert _repair_mis_decoded("Vandværk_Vest") == ["Vandværk_Vest"]
+
+    def test_an_ascii_name_has_nothing_to_recover(self):
+        assert _repair_mis_decoded("Junction_1") == []
+
+    def test_a_name_that_no_encoding_explains_is_left_alone(self):
+        """'ØST' is already correct: its bytes are not valid UTF-8 on their own."""
+        assert _repair_mis_decoded("ØST") == []
+
+    def test_a_companion_location_is_keyed_by_the_main_files_name(self):
+        rekeyed = _rekey_by_main_file({"ØST": "data"}, {"ØST", "Junction_1"})
+
+        assert rekeyed == {"ØST": "data"}
+
+    def test_a_matching_name_is_untouched(self):
+        rekeyed = _rekey_by_main_file({"Junction_1": "data"}, {"Junction_1"})
+
+        assert rekeyed == {"Junction_1": "data"}
+
+    def test_a_name_from_another_model_keeps_its_own_spelling(self):
+        """Otherwise a genuinely different companion would slip past validation."""
+        rekeyed = _rekey_by_main_file({"ØST": "data"}, {"Junction_1"})
+
+        assert rekeyed == {"ØST": "data"}
+
+    def test_a_companion_rekeys_both_nodes_and_reaches(self):
+        res = SimpleNamespace(nodes={"ØST": 1}, reaches={"Vandværk_Vest": 2})
+        extra = SimpleNamespace(nodes={"ØST": 3}, reaches={"Vandværk_Vest": 4})
+
+        companion = _Companion(res, extra)
+
+        assert companion.nodes == {"ØST": 3}
+        assert companion.reaches == {"Vandværk_Vest": 4}
+
+
 class TestReadInp:
     """Minimal .inp reader - see modelskill/model/adapters/_inp.py."""