Per-product Network constructors, with EPANET companion files (replica of #687)

[jpalm3r]

Replica of #687, which was merged and then reverted (#690) before it should have landed — see #690 for why. #687's own branch (read-network-res) can't be reopened as a PR: it's already an ancestor of main's history from the original merge, so GitHub sees zero commits to compare.

This branch is a fresh cherry-pick of #687's 23 commits onto current main, verified to introduce exactly the same 19-file changeset #687 did (git diff --stat origin/main network-constructors-v2), with no unrelated drift — main picked up an unrelated keep_duplicates removal (#657) after #687 branched, and this replica correctly leaves that alone rather than reintroducing it.

Original description, unchanged:

---## Why

Network.from_res1d read far more than res1d files. mikeio1d's single Res1D class opens nine extensions across five products, so the name promised one format and delivered nine. Rather than guess which of the nine work, I ran every one of mikeio1d's own fixtures through the loader — which turned up more than a naming problem.

One constructor per product

Only where a committed fixture backs it:

Network.from_mike(res)                              # .res1d, .res11   MIKE 1D, MIKE 11
Network.from_epanet(res, resx=None, inp=None)       # .res + companions

Both delegate to one private _from_mikeio1d, so adding a product later is a docstring and one call. Passing a file the other one reads raises ValueError: ... Use Network.from_epanet() instead.

from_res1d is removed rather than deprecated: it only shipped in the 1.4.0a3 alpha, and the network module is opt-in and absent from the API reference, so a shim would have added a second name for the tested path without protecting a real caller.

EPANET companion files

An EPANET run writes more than one file, and the .res is not the whole picture:

File	What it adds
.res	The network and its main timeseries. Required.
.resx	Extra results — tank volume, pump energy. Merged onto matching nodes.
.inp	The model input. The only one of the three carrying reach lengths.

network = Network.from_epanet("model.res", resx="model.resx", inp="model.inp")

inp= gives 12 of the 13 reaches real lengths (3209.5, 1609.3 m …); the pump keeps None, since [PIPES] is the one section with lengths. resx= adds Volume and Volume Percentage on the tank and reservoir.

.resx was previously refused as if it were a broken network. It is not a network at all — its node and reach IDs are a strict subset of the sibling .res, carrying different quantities — so it belongs as an argument, not a constructor. A companion is validated against the main file (same time axis, no unknown IDs) rather than merged on trust, since two runs would line up silently and produce a network nothing downstream would flag.

mikeio1d does not read .inp at all, so model/adapters/_inp.py parses the sections we need. No new dependency: pulling in wntr or swmmio for two sections each would weigh more than the parser (ADR-010). It is shared with SWMM, which uses the same .inp layout.

Not covered: resx= merges node quantities only. Its reach-level quantities (pump energy, efficiency, costs) sit on single-gridpoint reaches with no breakpoint to live on — #680.

Reach length is now optional

Reach length matters in rivers and sewer networks and not in link-node models, so NetworkReach.length is no longer an @abstractmethod. It defaults to None, subclasses override it only where a length exists, and BasicReach's argument defaults to None too.

The adapter also stops trusting mikeio1d's 0. ResultReach.length returns 0 when the length cannot be read — its own docstring says so — which every EPANET reach hits without an .inp. Reporting that as a zero-length reach makes a length-weighted graph algorithm treat the pipe as free, so it maps to None and networkx fails loudly instead: shortest-path treats the edge as unreachable, weight-summing calls raise TypeError. Dropping the edge attribute would have been worse, since networkx defaults a missing weight to 1.

Two bugs found on the way

MIKE 11 never worked. _simplify_colnames called to_dataframe() on nodes with no quantities — MIKE 11 keeps its timeseries on reach gridpoints, so its nodes are empty — and mikeio1d raised Could not create DataFrame with zero items. Guarding on quantities fixes it: network_cali.res11 now loads with 3 reaches, 71 nodes, real reach lengths and 23/21/23 breakpoints.

.resx failed opaquely. Res1DReach.__init__ compared start_node.id != reach.start_node with None on both sides, so the check passed and networkx then complained about a None node key three layers from the cause. An explicit is None guard names it instead.

Also added: a TypeError for a Res1D opened with a Path, which otherwise dies with AttributeError: 'WindowsPath' object has no attribute 'endswith' from inside mikeio1d, on every format.

Formats still refused, and why

Extension	Reason
.out (SWMM)	The connectivity is not in the .out — StartNodeIndex is -1 on every reach, coordinates are nan, no chainages. It lives in the companion .inp, which we do not read yet. Tracked in #689 with the pairing verified and one blocker written up.
.prf, .crf, .xrf (MOUSE), .whr (Water Hammer)	No result file exists in this repo or in mikeio1d's testdata, so support cannot be verified. Tracked in #686.
.resx	Not refused any more in the sense that matters — read it via from_epanet(res, resx=...). Passing it as the primary file still raises, and the message says so.

Each refusal now names the file that would lift it. The old wording blamed mikeio1d for not exposing reach start/end nodes, which was true of our code path but wrong about the cause and left the user nowhere to go. (#688 was opened on that mistaken reading and is closed, with a comment explaining what it got wrong.)

Fixtures

Five files copied unchanged from DHI/mikeio1d (MIT, same licence as modelskill) at commit d937466, with provenance in tests/testdata/README.md: network_cali.res11, epanet.res, epanet.resx, epanet.inp, swmm.out. About 261 KB total. swmm.out is deliberately kept without its .inp, so the refusal test fails the day SWMM support lands.

Tests

One is worth pointing at: the two readable extension sets plus the refusal table must union to exactly Res1D.get_supported_file_extensions(). A mikeio1d release that adds a tenth format fails CI and forces a decision, rather than leaving the format silently unreachable.

Otherwise: TestEpanetCompanionInp and TestEpanetCompanionResx cover the lengths, the merge, selective loading, and every refusal path — the two mismatched-file guards need monkeypatching, since the committed fixtures are a matching pair by construction. TestReadInp covers the parser. TestOptionalReachLength covers a subclass that omits length, the None edge attribute, break point distances surviving an undefined total, and both loud networkx failures.

Verification

• full suite: 793 passed, 6 skipped
• ruff check src, mypy src/ and the metrics doctests clean
• new and existing user-guide cells execute from docs/user-guide
• checked against a large confidential EPANET result (~8000 reaches) that cannot be committed

Notes for review

• just docs was not run end to end; I executed the {python} cells directly instead.
• Network still has no quartodoc API page. It had none before, so these constructors are documented in the user guide and their docstrings only. Happy to add one if you want it in the API reference.
• The first three commits on the branch predate the design discussion: they widen from_res1d and test it, and later commits remove it. I left the history as it happened rather than rewriting. a5d1faee has a misleading subject — it only adds a .gitignore rule, it does not commit any data.
• Node20 has been updated to Node24 in the full_test CI pipeline.

Design decisions are recorded in adr/012-network-format-constructors.md.

[Copilot]

Pull request overview

This PR refactors modelskill.network.Network file-based construction to be product-specific (MIKE vs EPANET), adds support for EPANET companion files (.resx for extra node quantities and .inp for pipe lengths), and updates docs/tests/fixtures accordingly to make format support explicit and well-tested.

Changes:

• Replace the ambiguous Network.from_res1d entry point with Network.from_mike and add Network.from_epanet, both delegating to a shared private loader with explicit extension validation and clearer refusal messages.
• Add an .inp parser (_inp.py) to read EPANET pipe lengths and merge .resx node quantities into the main .res network.
• Make NetworkReach.length optional (None when undefined) and update graph construction, documentation, fixtures, and tests to reflect the new behavior and supported/refused formats.

Reviewed changes

Copilot reviewed 14 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/modelskill/network.py	Adds per-product constructors, extension policy tables, companion handling, and optional reach-length behavior in graph construction.
src/modelskill/model/adapters/_res1d.py	Fixes MIKE 11 empty-node handling, adds .resx node-quantity merge helper, and makes reach length optional/overrideable.
src/modelskill/model/adapters/_inp.py	Introduces a minimal EPANET/SWMM-style .inp section parser and EPANET pipe-length reader.
src/modelskill/model/network.py	Updates user-facing guidance/error message to reference Network.from_mike(...) instead of from_res1d(...).
tests/test_network.py	Updates tests to new constructors and adds coverage for extension policy, optional reach length, EPANET companions, and adapter behavior.
tests/notebooks/test_notebooks.py	Updates notebook skip comment to reference the renamed constructor.
docs/user-guide/network.qmd	Documents the per-product constructors, refused formats, EPANET companions, and implications of undefined reach lengths/breakpoints.
notebooks/Collection_systems_network.ipynb	Updates example usage to Network.from_mike(...).
adr/README.md	Adds ADR-012 to the ADR index.
adr/012-network-format-constructors.md	New ADR documenting the rationale for per-product constructors and explicit refusal policy.
roadmap/features/network-models.md	Updates roadmap text to reflect MIKE 11 + EPANET support and format limitations.
tests/testdata/README.md	New provenance documentation for vendored mikeio1d fixtures.
tests/testdata/network_cali.res11	Adds a MIKE 11 fixture to cover .res11 network reading.
tests/testdata/epanet.res	Adds an EPANET .res fixture for from_epanet coverage.
tests/testdata/epanet.resx	Adds an EPANET .resx fixture for companion-quantity merge coverage.
tests/testdata/epanet.inp	Adds an EPANET .inp fixture for pipe-length coverage.
tests/testdata/swmm.out	Adds a SWMM fixture to pin refusal behavior until topology support lands.
.gitignore	Ignores tests/testdata/confidential/* and normalizes uv.lock entry formatting.
.github/workflows/full_test.yml	Updates workflow checkout action version.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.