Update from_epanet docstring and network.qmd for the new breakpoints

Rewrites the from_epanet docstring's Notes section and the qmd's "EPANET
reach geometry is limited" callout to describe the new behavior: a
reach's single synthetic gridpoint duplicated into two breakpoints (one
at each end), addressable by distance where reach.length is known and
otherwise only via ReachObservation/recall(), plus the resx reach-quantity
merge. Drops the closed #680 reference now that it describes the fix
rather than the gap.

Author: jpalm3r

docs/user-guide/network.qmd

@@ -226,13 +226,12 @@ sorted(
 ::: {.callout-warning}
 ## EPANET reach geometry is limited
 
-EPANET is a link-node model, and mikeio1d reports no length and a single synthetic gridpoint for each reach. So for an EPANET network:
+EPANET is a link-node model, and mikeio1d reports a single synthetic gridpoint for each reach, not tied to either end. That gridpoint is duplicated into two breakpoints, one at each end of the reach, so its own quantities (`Flow`, `Velocity`, ...) reach `find()`/`recall()`/`ReachObservation` the same way a MIKE reach's end data already does. So for an EPANET network:
 
-* without `inp=`, every edge of `network.graph` has `length=None`. A length-weighted `networkx` call then fails rather than returning a meaningless number — shortest-path treats the edge as unreachable, and anything that sums the weights raises `TypeError`. The attribute is always present, since `networkx` defaults a missing weight to `1`. With `inp=`, only pumps and valves stay `None`, since `[PIPES]` is the one section carrying lengths
-* reaches have no breakpoints, so a `ReachObservation` cannot be matched — use `NodeObservation` instead
-* `find(reach=..., distance=<number>)` never resolves; only `distance="start"` and `distance="end"` work
+* without `inp=`, a reach's length is unknown, so only its first breakpoint (`distance=0.0`) is real; the second isn't addressable by a number at all — `find(reach=..., distance=<number>)` only resolves it via `distance="start"`/`"end"` (which return the node, not the breakpoint). The corresponding edges of `network.graph` are `length=None` — a length-weighted `networkx` call then fails rather than returning a meaningless number, since shortest-path treats a `None`-weight edge as unreachable and anything that sums the weights raises `TypeError`
+* with `inp=`, a pipe's second breakpoint sits at its full length, and the edge between the two breakpoints carries that real length. Pumps and valves keep an unaddressable second breakpoint even with `inp=`, since `[PIPES]` is the only section carrying lengths
 
-For the same reason, `resx=` merges node quantities only. Its reach-level quantities — pump energy, efficiency and costs — have no breakpoint to live on, which is tracked in [#680](https://github.com/DHI/modelskill/issues/680).
+`resx=`'s reach-level quantities — pump energy, efficiency and costs — merge onto the matching reach's breakpoints the same way its node quantities merge onto nodes.
 
 Node timeseries, `to_dataframe()`, `to_dataset()`, `find(node=...)` and `recall()` are unaffected.
 :::

src/modelskill/network.py

@@ -541,18 +541,21 @@ def from_epanet(
         resx : str, Path, Res1D or None, optional
             Companion ``.resx`` file from the same run. Its extra node
             quantities (tank ``Volume`` and ``Volume Percentage``) are merged
-            onto the matching nodes. By default None, and those quantities are
-            simply absent.
+            onto the matching nodes, and its extra reach quantities (e.g. pump
+            ``efficiency``, ``energy`` and ``energy costs``) are merged onto
+            the matching reach's breakpoints. By default None, and those
+            quantities are simply absent.
         inp : str, Path or None, optional
             EPANET ``.inp`` input file for the same model, read for its
             ``[PIPES]`` lengths. By default None, and reach lengths are
             undefined.
         nodes : str, list of str, or None, optional
             Which nodes get their timeseries loaded. See :meth:`from_mike`.
         reaches : str, list of str, or None, optional
-            Which reaches get their gridpoint data loaded. See
-            :meth:`from_mike`. EPANET results have no intermediate gridpoints,
-            so this argument has no effect.
+            Which reaches get their breakpoint data loaded. See
+            :meth:`from_mike`. EPANET reaches have at most one gridpoint (see
+            Notes), but this argument still governs whether its data - and
+            any matching ``resx`` reach quantities - are populated.
         quantities : str, list of str, or None, optional
             Which quantities are read at each selected location. See
             :meth:`from_mike`.
@@ -585,22 +588,29 @@ def from_epanet(
 
         Notes
         -----
-        EPANET is a link-node model, and mikeio1d reports no length and a
-        single synthetic gridpoint for each of its reaches. As a result:
-
-        * without ``inp``, every edge of :attr:`graph` has ``length=None``, so a
-          length-weighted graph algorithm fails rather than returning a
-          meaningless number. Pumps and valves keep ``length=None`` even with
-          ``inp``, since ``[PIPES]`` is the only section carrying lengths
-        * reaches have no breakpoints, so
-          :class:`~modelskill.obs.ReachObservation` cannot be matched against
-          an EPANET network — use :class:`~modelskill.obs.NodeObservation`
-        * ``find(reach=..., distance=<number>)`` never resolves; only
-          ``distance="start"`` and ``distance="end"`` work
-
-        For the same reason, ``resx`` merges node quantities only. Its
-        reach-level quantities (pump energy, efficiency and costs) have no
-        breakpoint to live on, which is tracked in issue #680.
+        EPANET is a link-node model, and mikeio1d reports a single synthetic
+        gridpoint for each reach, not tied to either end. That gridpoint is
+        duplicated into two breakpoints, one at each end of the reach, so its
+        own quantities (``Flow``, ``Velocity``, ...) are reachable through
+        :meth:`find`, :meth:`recall` and
+        :class:`~modelskill.obs.ReachObservation` the same way a MIKE reach's
+        end data already is. As a result:
+
+        * without ``inp``, a reach's length is unknown, so only its first
+          breakpoint (``distance=0.0``) is real; the second is not
+          addressable by distance at all — ``find(reach=..., distance=...)``
+          resolves it only via ``distance="start"``/``"end"`` (which return
+          the node, not the breakpoint), or not at all by a number. The
+          corresponding edges of :attr:`graph` are ``length=None``
+        * with ``inp``, a pipe's second breakpoint sits at its full length —
+          both breakpoints are then addressable by distance, and the edge
+          between them carries the pipe's real length. Pumps and valves keep
+          an unaddressable second breakpoint even with ``inp``, since
+          ``[PIPES]`` is the only section carrying lengths
+
+        ``resx``'s reach-level quantities (pump ``efficiency``, ``energy`` and
+        ``energy costs``) merge onto the matching reach's breakpoints the same
+        way its node quantities merge onto nodes.
 
         Node timeseries, :meth:`to_dataframe`, :meth:`to_dataset`,
         ``find(node=...)`` and :meth:`recall` are unaffected.