Add mesh_layout='prebuilt' for user-provided mesh graphs

[prajwal-tech07]

Describe your changes

Add support for mesh_layout="prebuilt" in create_all_graph_components, enabling users to supply their own mesh graph (e.g. ICON icosahedral, MPAS Voronoi, custom observation networks) instead of relying on library-generated meshes.

Two modes are supported:

• Nodes+edges mode: User provides a complete nx.DiGraph with validated node attributes (pos, type) and edge attributes (len, vdiff). The graph is used as-is after validation.
• Nodes-only mode: User provides an nx.Graph with only nodes (having pos and type attributes). The library automatically builds connectivity edges using Delaunay triangulation (with KDTree fallback for collinear/degenerate cases).

Works with all three m2m_connectivity types: flat, flat_multiscale, and hierarchical.

Changes across 4 files:

File	Change
src/.../mesh/kinds/prebuilt.py (new, 453 lines)	Core module: validation functions, Delaunay edge builder, flat/multiscale/hierarchical constructors
src/.../create/base.py (+197/-38)	Dispatch logic in create_all_graph_components for all 3 m2m_connectivity branches
src/.../mesh/__init__.py (+9)	Public re-exports of prebuilt functions
tests/test_prebuilt_mesh.py (new, 2869 lines)	202 tests across 28 test classes covering validation, Delaunay, flat/multiscale/hierarchical, integration, edge cases, numerical correctness, graph invariants, and stress tests

Motivation: This is a key extensibility feature that decouples mesh topology from the graph construction pipeline, allowing researchers to use arbitrary mesh structures without modifying library internals.

Dependencies: No new dependencies — uses existing networkx, numpy, scipy.spatial (Delaunay, KDTree).

Issue Link

Closes #79

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📖 Documentation (Addition or improvements to documentation)

Checklist before requesting a review

• My branch is up-to-date with the target branch - if not update your fork with the changes from the target branch (use pull with --rebase option if possible).
• I have performed a self-review of my code
• For any new/modified functions/classes I have added docstrings that clearly describe its purpose, expected inputs and returned values
• I have placed in-line comments to clarify the intent of any hard-to-understand passages of my code
• I have updated the documentation to cover introduced code changes
• I have added tests that prove my fix is effective or that my feature works
• I have given the PR a name that clearly describes the change, written in imperative form (context).
• I have requested a reviewer and an assignee (assignee is responsible for merging)

Checklist for reviewers

Each PR comes with its own improvements and flaws. The reviewer should check the following:

• the code is readable
• the code is well tested
• the code is documented (including return types and parameters)
• the code is easy to maintain

Author checklist after completed review

• I have added a line to the CHANGELOG describing this change, in a section
  reflecting type of change (add section where missing):
  • added: when you have added new functionality
  • changed: when default behaviour of the code has been changed
  • fixes: when your contribution fixes a bug

Checklist for assignee

• PR is up to date with the base branch
• the tests pass
• author has added an entry to the changelog (and designated the change as added, changed or fixed)
• Once the PR is ready to be merged, squash commits and merge the PR.

[joeloskarsson]

It seems to me that there are really two mesh layouts added here: the prebuilt and delaunay triangulation from nodes. These are quite different and should be different mesh_layouts IMO. For building mesh from a given set of nodes, it would be nice to make the solution flexible enough to also support other mesh generation methods, e.g. knn-graphs.

[prajwal-tech07]

Hi @joeloskarsson, thanks for the feedback!

This PR implements issue #79, which was split alongside #78 (mesh_layout="rectilinear", PR #81) and #80 (mesh_layout="triangular") as part of a planned series — @leifdenby helped scope these three issues from the original discussion in #71.

The two modes in this PR are intentionally both under mesh_layout="prebuilt":

• Nodes+edges: The core use case — user provides a complete nx.DiGraph (ICON, MPAS, custom observation networks). This is what issue [Feat] Add mesh_layout="prebuilt" and mesh_layout="prebuilt_hierarchical" support #79 primarily describes.
• Nodes-only: A convenience mode that auto-builds edges from user-provided node positions. The key distinction from mesh_layout="triangular" ([Feat] Add mesh_layout="triangular" for regular triangular mesh generation #80) is that the nodes themselves come from the user (arbitrary positions), whereas "triangular" generates regular lattice nodes internally from spacing parameters.

That said, I think your point about supporting other mesh generation methods (KNN, radius graphs) for the nodes-only case is a great idea. I could make the connectivity method configurable via mesh_layout_kwargs, e.g.:

mesh_layout_kwargs=dict(
    mesh_graph=my_nodes_graph,
    connectivity_method="delaunay"  # or "knn", "radius"
)python
mesh_layout_kwargs=dict(
    mesh_graph=my_nodes_graph,
    connectivity_method="delaunay"  # or "knn", "radius"
)

This would keep both modes under "prebuilt" (since the user is still "bringing their own nodes") while making connectivity generation pluggable. Would that address your concern, or do you feel they should still be separate

mesh_layout
values?

Happy to adjust the design based on your and @leifdenby's input!

[prajwal-tech07]

Hi @leifdenby! Following up on the meeting - here's my plan for reviving this PR on top of the mesh_layout structure from #92, plus the design questions around input format and docs. Would love a sanity check before I start porting.

1. Branch strategy

This branch predates #81's merge (it carries parallel copies of those commits on the old mesh/kinds/ structure), so a literal merge of #92 would conflict on every file. Instead I'd reset this branch onto feat/triangular-mesh-layout and port the prebuilt code as fresh commits adapted to the layout/ + connectivity/ split - the PR and its history stay alive, and once #92 merges the diff here shrinks to just the prebuilt work.

2. How prebuilt fits the two-step architecture

prebuilt becomes a third layout module (mesh/layout/prebuilt.py) producing the same undirected mesh-primitive contract as rectilinear/triangular:

• Nodes-only input → validate, build adjacency via Delaunay triangulation (adjacency_type="delaunay") → the existing connectivity step runs unchanged.
• Nodes+edges input → the user's edges become the primitive adjacency, and the connectivity step still runs (directs edges, computes len/vdiff).

The second point is a deliberate change from this PR's old design, where a full nx.DiGraph bypassed connectivity entirely. Treating user edges as primitive adjacency keeps len/vdiff computed in exactly one place and keeps mesh_layout × m2m_connectivity fully orthogonal - prebuilt then works with flat, flat_multiscale, and hierarchical (multi-level via a level node attribute).
Does that match your thinking, or do you see a use case for accepting a fully-formed directed mesh graph as-is?

3. User input contract

Canonical: an in-memory networkx.Graph with node attr pos (ndarray (2,), same coordinate system as the grid xy - I'll make this loud in the docs), optional level for multi-level, edges optional.
Convenience: a bare np.ndarray [N, 2] of coordinates for the simplest nodes-only case.
No file-format commitment in the library — instead the docs show how to load real sources (ICON netCDF vertices, a CSV of station locations) into that graph in a few lines.
API: create_all_graph_components(mesh_layout="prebuilt", mesh_layout_kwargs=dict(mesh_graph=G), ...) - no mesh_node_spacing needed since spacing is implied by the user's coordinates.

import networkx as nx
import numpy as np
import weather_model_graphs as wmg

# user's own mesh: e.g. vertices loaded from an ICON grid file
my_mesh = nx.Graph()
for i, (x, y) in enumerate(my_mesh_coords):  # [N, 2], same coords as xy
    my_mesh.add_node(i, pos=np.array([x, y]), type="mesh")
# (optionally add edges here — otherwise Delaunay builds the adjacency)

graph = wmg.create.create_all_graph_components(
    xy=xy_grid,
    mesh_layout="prebuilt",
    mesh_layout_kwargs=dict(mesh_graph=my_mesh),
    m2m_connectivity="flat",
    g2m_connectivity="nearest_neighbour",
    m2g_connectivity="nearest_neighbour",
)

4. Docs

A new jupyter-book chapter prebuilt_mesh.ipynb (after mesh_layout.ipynb in the TOC): motivation (bring your own mesh - icosahedral, Voronoi, observation networks), the input contract, nodes-only vs nodes+edges walkthroughs with plots, multi-level → hierarchical, the validation errors, and an end-to-end create → save example. I'll also trim the old test file down to the essentials (validators, Delaunay properties, one end-to-end per connectivity type).

If this sounds right I'll start with the layout-module port and open the docs chapter alongside it.

[prajwal-tech07]

The revival is implemented and pushed, following the design we converged on in #79:

• mesh_layout="prebuilt" + mesh_layout_kwargs=dict(mesh_graph=...) - nodes-only input (nx.Graph or a bare [N, 2] array), validated and passed through as an edge-less node cloud
• Mesh edges are built in the connectivity step directly from node positions (method="delaunay", default) - no undirected intermediate, per your suggestion
• No pattern given → every layout edge is used; an explicit pattern that doesn't match the primitive's adjacency types raises listing what's available; pattern= on a node cloud points to method=
• Hierarchical via integer level node attribute (lowest = finest), inter_level={"pattern": "nearest", "k": 1} unchanged
• New jupyter-book chapter (prebuilt_mesh.ipynb) covering both nodes-only cases, 45 new tests, all 342 pass

Two conscious deferrals: user-provided edges (Cases 2/4 from the sketches - raises NotImplementedError pointing at #79) and flat_multiscale for prebuilt (level-merging assumes coincident cross-level positions, which arbitrary user clouds don't have - I think it needs the Delaunay-coarsening idea we paused).

Note: this branch is based on #92's branch, so the diff currently includes those commits - it'll shrink to just the prebuilt work once #92 merges, and I'll rebase then.