@woosh/meep-engine 2.138.19 → 2.139.0

package/src/core/graph/metis/native/coarsen/coarsen_graph.js

@@ -0,0 +1,94 @@
+import { create_coarse_graph } from "./create_coarse_graph.js";
+import { match_shem } from "./match_shem.js";
+
+/**
+ * If contraction shrinks the graph by less than this much in a level, further
+ * coarsening probably won't help. Matches the COARSEN_FRACTION threshold in
+ * libmetis/defs.h.
+ */
+const MIN_USEFUL_CONTRACTION_RATIO = 0.85;
+
+/**
+ * Safety cap: if we somehow keep contracting forever (shouldn't happen, but
+ * stops a runaway loop in pathological inputs).
+ */
+const MAX_COARSENING_LEVELS = 32;
+
+/**
+ * Drive the coarsening phase: repeatedly match + contract until the coarsest
+ * graph is small enough, or the contraction ratio drops below the threshold.
+ *
+ * On entry, `graph` is the original finest graph. On return, the result is the
+ * coarsest graph; walking `.finer_graph` repeatedly reaches the original.
+ *
+ * Mirrors `CoarsenGraph` from libmetis/coarsen.c.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {{random: function():number, coarsen_until_vertex_count: number}} opts
+ *   `coarsen_until_vertex_count`: stop coarsening once vertex_count drops at or
+ *   below this. METIS uses `max(vertex_count / (20·log2(nparts)), 30·nparts)`.
+ * @returns {import('../MetisGraph.js').MetisGraph} the coarsest graph
+ */
+export function coarsen_graph(graph, opts) {
+    const random = opts.random;
+    const coarsen_until_vertex_count = opts.coarsen_until_vertex_count;
+
+    let current_level = graph;
+    let remaining_levels = MAX_COARSENING_LEVELS;
+
+    // Three vertex_count-sized buffers reused across every coarsening level.
+    // Sized to the finest graph's vertex_count; subsequent (coarser) levels
+    // only need a prefix. match_shem either refills the active range itself
+    // (`partner_of_vertex`) or overwrites every entry it reads
+    // (`visit_order` and `sort_key_degree`), so stale tail data is harmless.
+    const partner_of_vertex = new Uint32Array(graph.vertex_count);
+    const visit_order = new Uint32Array(graph.vertex_count);
+    const sort_key_degree = new Uint32Array(graph.vertex_count);
+
+    while (remaining_levels-- > 0) {
+
+        // Cap a single coarse vertex's weight at ~1.5x what one balanced
+        // partition could hold at the coarsest level. METIS uses
+        // 1.5 * total_vertex_weight / coarsen_until_vertex_count.
+        // The total is preserved across coarsening, so recomputing per level
+        // is cheap and follows the size threshold naturally.
+        const max_coarse_vertex_weight = Math.max(
+            1,
+            Math.ceil(1.5 * current_level.total_vertex_weight / coarsen_until_vertex_count)
+        );
+
+        const coarse_vertex_count = match_shem(
+            current_level,
+            random,
+            max_coarse_vertex_weight,
+            partner_of_vertex,
+            visit_order,
+            sort_key_degree
+        );
+
+        if (coarse_vertex_count >= current_level.vertex_count) {
+            // Matching collapsed nothing — graph is too irregular to benefit
+            // from another level. Stop.
+            break;
+        }
+
+        const coarser = create_coarse_graph(current_level, coarse_vertex_count, partner_of_vertex);
+        const contraction_ratio = coarser.vertex_count / current_level.vertex_count;
+
+        current_level = coarser;
+
+        if (current_level.vertex_count <= coarsen_until_vertex_count) {
+            break;
+        }
+        if (contraction_ratio > MIN_USEFUL_CONTRACTION_RATIO) {
+            // Contraction stalled; further levels offer diminishing returns.
+            break;
+        }
+        if (current_level.adjacency_length < current_level.vertex_count / 2) {
+            // Graph is too sparse to benefit from another coarsening pass.
+            break;
+        }
+    }
+
+    return current_level;
+}

package/src/core/graph/metis/native/coarsen/create_coarse_graph.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Contract a matched graph into its coarse counterpart.
+ *
+ * Each matched pair (vertex, partner) collapses to a single coarse vertex whose
+ * weight is the sum of both endpoints. Parallel edges to the same coarse
+ * neighbour merge into one edge with summed weight. Self-loops produced by
+ * collapsing the matched pair itself are dropped.
+ *
+ * Mirrors `CreateCoarseGraphNoMask` from libmetis/coarsen.c. The masked variant
+ * (open-addressing hash with a power-of-two mask) is skipped — the unmasked
+ * flat-htable path is fast enough at our scale and is simpler.
+ *
+ * Precondition: `match_shem` has run and produced `graph.coarse_vertex_map`
+ * indexed such that processing vertices in order v=0..vertex_count increments
+ * through coarse ids 0..coarse_vertex_count-1.
+ *
+ * @param {MetisGraph} graph fine graph (input)
+ * @param {number} coarse_vertex_count
+ * @param {Uint32Array} partner_of_vertex `[v]` = match partner of v, or v itself if alone
+ * @returns {MetisGraph} the coarse graph (also assigned to `graph.coarser_graph`)
+ */
+export function create_coarse_graph(graph: MetisGraph, coarse_vertex_count: number, partner_of_vertex: Uint32Array): MetisGraph;
+import { MetisGraph } from "../MetisGraph.js";
+//# sourceMappingURL=create_coarse_graph.d.ts.map

package/src/core/graph/metis/native/coarsen/create_coarse_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create_coarse_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/coarsen/create_coarse_graph.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,2CALW,UAAU,uBACV,MAAM,qBACN,WAAW,GACT,UAAU,CAuItB;2BA5J0B,kBAAkB"}

package/src/core/graph/metis/native/coarsen/create_coarse_graph.js

@@ -0,0 +1,158 @@
+import { assert } from "../../../../assert.js";
+import { MetisGraph } from "../MetisGraph.js";
+
+/**
+ * Contract a matched graph into its coarse counterpart.
+ *
+ * Each matched pair (vertex, partner) collapses to a single coarse vertex whose
+ * weight is the sum of both endpoints. Parallel edges to the same coarse
+ * neighbour merge into one edge with summed weight. Self-loops produced by
+ * collapsing the matched pair itself are dropped.
+ *
+ * Mirrors `CreateCoarseGraphNoMask` from libmetis/coarsen.c. The masked variant
+ * (open-addressing hash with a power-of-two mask) is skipped — the unmasked
+ * flat-htable path is fast enough at our scale and is simpler.
+ *
+ * Precondition: `match_shem` has run and produced `graph.coarse_vertex_map`
+ * indexed such that processing vertices in order v=0..vertex_count increments
+ * through coarse ids 0..coarse_vertex_count-1.
+ *
+ * @param {MetisGraph} graph fine graph (input)
+ * @param {number} coarse_vertex_count
+ * @param {Uint32Array} partner_of_vertex `[v]` = match partner of v, or v itself if alone
+ * @returns {MetisGraph} the coarse graph (also assigned to `graph.coarser_graph`)
+ */
+export function create_coarse_graph(graph, coarse_vertex_count, partner_of_vertex) {
+
+    const vertex_count = graph.vertex_count;
+    const edge_addresses = graph.edge_addresses;
+    const adjacency = graph.adjacency;
+    const edge_weights = graph.edge_weights;
+    const vertex_weights = graph.vertex_weights;
+    const coarse_vertex_map = graph.coarse_vertex_map;
+
+    assert.equal(coarse_vertex_map !== null, true, 'graph.coarse_vertex_map must be set by match_shem before contraction');
+
+    // Worst-case sizing: every edge of the fine graph survives unmerged. The
+    // actual edge count is known only after the merge pass, so we trim at the end.
+    const coarse_graph = new MetisGraph(coarse_vertex_count, graph.adjacency_length);
+    const coarse_edge_addresses = coarse_graph.edge_addresses;
+    const coarse_adjacency = coarse_graph.adjacency;
+    const coarse_edge_weights = coarse_graph.edge_weights;
+    const coarse_vertex_weights = coarse_graph.vertex_weights;
+
+    // For each coarse neighbour id k that we've already seen while building the
+    // current super-vertex's adjacency list, `coarse_nbr_position[k]` is its
+    // slot in our local section of coarse_adjacency. -1 = not seen yet.
+    // Reset only at the touched entries per vertex (O(degree)) rather than
+    // wholesale (O(coarse_vertex_count)).
+    const coarse_nbr_position = new Int32Array(coarse_vertex_count);
+    coarse_nbr_position.fill(-1);
+
+    let next_coarse_id = 0;       // must equal coarse_vertex_map[vertex] when we process it
+    let coarse_edge_cursor = 0;   // running write position into coarse_adjacency / coarse_edge_weights
+    coarse_edge_addresses[0] = 0;
+
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        const partner = partner_of_vertex[vertex];
+        if (partner < vertex) {
+            // Already handled when we processed `partner` earlier in this loop.
+            continue;
+        }
+
+        assert.equal(
+            coarse_vertex_map[vertex], next_coarse_id,
+            'coarse_vertex_map[v] should equal running coarse id counter; match_shem renumbering was skipped or wrong'
+        );
+
+        coarse_vertex_weights[next_coarse_id] = vertex_weights[vertex];
+
+        let coarse_nbr_count_for_this_vertex = 0;
+
+        // ----- Merge vertex's neighbours into the coarse adjacency -----
+        {
+            const edge_start = edge_addresses[vertex];
+            const edge_end = edge_addresses[vertex + 1];
+            for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                const coarse_neighbor = coarse_vertex_map[adjacency[edge_offset]];
+                const existing_position = coarse_nbr_position[coarse_neighbor];
+                if (existing_position === -1) {
+                    coarse_adjacency[coarse_edge_cursor + coarse_nbr_count_for_this_vertex] = coarse_neighbor;
+                    coarse_edge_weights[coarse_edge_cursor + coarse_nbr_count_for_this_vertex] = edge_weights[edge_offset];
+                    coarse_nbr_position[coarse_neighbor] = coarse_nbr_count_for_this_vertex;
+                    coarse_nbr_count_for_this_vertex++;
+                } else {
+                    coarse_edge_weights[coarse_edge_cursor + existing_position] += edge_weights[edge_offset];
+                }
+            }
+        }
+
+        if (vertex !== partner) {
+            // ----- Add the partner's weight and merge its neighbours too -----
+            coarse_vertex_weights[next_coarse_id] += vertex_weights[partner];
+
+            const edge_start = edge_addresses[partner];
+            const edge_end = edge_addresses[partner + 1];
+            for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                const coarse_neighbor = coarse_vertex_map[adjacency[edge_offset]];
+                const existing_position = coarse_nbr_position[coarse_neighbor];
+                if (existing_position === -1) {
+                    coarse_adjacency[coarse_edge_cursor + coarse_nbr_count_for_this_vertex] = coarse_neighbor;
+                    coarse_edge_weights[coarse_edge_cursor + coarse_nbr_count_for_this_vertex] = edge_weights[edge_offset];
+                    coarse_nbr_position[coarse_neighbor] = coarse_nbr_count_for_this_vertex;
+                    coarse_nbr_count_for_this_vertex++;
+                } else {
+                    coarse_edge_weights[coarse_edge_cursor + existing_position] += edge_weights[edge_offset];
+                }
+            }
+
+            // The (vertex, partner) edge maps to (next_coarse_id, next_coarse_id):
+            // a self-loop. Drop it by swap-with-last.
+            const self_loop_position = coarse_nbr_position[next_coarse_id];
+            if (self_loop_position !== -1) {
+                const last_position = coarse_nbr_count_for_this_vertex - 1;
+                if (self_loop_position !== last_position) {
+                    const moved_neighbor = coarse_adjacency[coarse_edge_cursor + last_position];
+                    coarse_adjacency[coarse_edge_cursor + self_loop_position] = moved_neighbor;
+                    coarse_edge_weights[coarse_edge_cursor + self_loop_position] = coarse_edge_weights[coarse_edge_cursor + last_position];
+                    coarse_nbr_position[moved_neighbor] = self_loop_position;
+                }
+                coarse_nbr_count_for_this_vertex = last_position;
+            }
+        }
+
+        // Reset coarse_nbr_position for just the slots we touched.
+        for (let local_position = 0; local_position < coarse_nbr_count_for_this_vertex; local_position++) {
+            coarse_nbr_position[coarse_adjacency[coarse_edge_cursor + local_position]] = -1;
+        }
+        // Self-loop slot may have been populated and popped without leaving a
+        // trace in the loop above; clear unconditionally so subsequent vertices
+        // don't see stale state.
+        coarse_nbr_position[next_coarse_id] = -1;
+
+        coarse_edge_cursor += coarse_nbr_count_for_this_vertex;
+        next_coarse_id++;
+        coarse_edge_addresses[next_coarse_id] = coarse_edge_cursor;
+    }
+
+    assert.equal(next_coarse_id, coarse_vertex_count, 'final coarse id counter must equal coarse_vertex_count');
+
+    // Record the actual adjacency length, but DON'T truncate the underlying
+    // buffer. Truncation here would allocate a fresh shared buffer and bulk-copy
+    // four typed arrays into it just to shrink — at every coarsening level — and
+    // the immediate caller doesn't need the savings; the coarse graph is
+    // short-lived relative to the overall partitioning call.
+    //
+    // The unused tail of `adjacency` and `edge_weights` is harmless: downstream
+    // code consistently uses `adjacency_length` as the source of truth (never
+    // `.length`). Callers that genuinely need the memory back can call
+    // `truncate_adjacency` themselves once they're done filling the graph.
+    coarse_graph.adjacency_length = coarse_edge_cursor;
+    coarse_graph.refresh_total_vertex_weight();
+
+    // Link the levels for later projection back down.
+    coarse_graph.finer_graph = graph;
+    graph.coarser_graph = coarse_graph;
+
+    return coarse_graph;
+}

package/src/core/graph/metis/native/coarsen/match_shem.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sorted Heavy-Edge Matching.
+ *
+ * Visits vertices in random order biased toward lower degree first, and for
+ * each unmatched vertex pairs it with the unmatched neighbour sharing the
+ * heaviest edge weight (subject to a coarse-vertex weight cap).
+ *
+ * Outputs:
+ *  - `graph.coarse_vertex_map[v]` = id of the coarse vertex that vertex v
+ *    collapses into. Numbered so that iterating v=0..vertex_count walks coarse
+ *    ids 0..coarse_vertex_count-1 in order — this property is required by
+ *    `create_coarse_graph`.
+ *  - `partner_of_vertex[v]` = the partner of vertex v (or v itself if it ended
+ *    up alone in the matching). Caller-provided buffer, filled in place.
+ *  - returns `coarse_vertex_count`, the number of coarse vertices created.
+ *
+ * Mirrors `Match_SHEM` from libmetis/coarsen.c, single-constraint branch.
+ * The 2-hop matching escape hatch is intentionally skipped — it's a degeneracy
+ * recovery for graphs with many isolated/low-degree vertices that's not on the
+ * critical path; can add later if cluster quality bites.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {function():number} random seeded RNG
+ * @param {number} max_coarse_vertex_weight cap on the combined weight of a
+ *   matched pair; vertices whose own weight already exceeds this are forced
+ *   into singleton coarse vertices
+ * @param {Uint32Array} partner_of_vertex caller-provided buffer of length
+ *   `>= graph.vertex_count`. Will be filled with each vertex's match partner
+ *   (or its own id if it ended up unmatched). The first `graph.vertex_count`
+ *   entries are clobbered; any tail beyond that is left untouched.
+ * @param {Uint32Array} visit_order caller-provided scratch of length
+ *   `>= graph.vertex_count`. Used as the (random-shuffled, degree-sorted)
+ *   visitation order during matching. Contents on entry are ignored;
+ *   contents on return are undefined.
+ * @param {Uint32Array} sort_key_degree caller-provided scratch of length
+ *   `>= graph.vertex_count`. Holds the per-vertex degree buckets used to sort
+ *   `visit_order`. Contents on entry are ignored; contents on return are undefined.
+ * @returns {number} `coarse_vertex_count`
+ */
+export function match_shem(graph: import('../MetisGraph.js').MetisGraph, random: () => number, max_coarse_vertex_weight: number, partner_of_vertex: Uint32Array, visit_order: Uint32Array, sort_key_degree: Uint32Array): number;
+//# sourceMappingURL=match_shem.d.ts.map

package/src/core/graph/metis/native/coarsen/match_shem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match_shem.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/coarsen/match_shem.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,kCAlBW,OAAO,kBAAkB,EAAE,UAAU,gBAC1B,MAAM,4BACjB,MAAM,qBAGN,WAAW,eAIX,WAAW,mBAIX,WAAW,GAGT,MAAM,CAoIlB"}

package/src/core/graph/metis/native/coarsen/match_shem.js

@@ -0,0 +1,175 @@
+import { array_quick_sort_by_lookup_uint } from "../../../../collection/array/array_quick_sort_by_lookup_uint.js";
+import { array_shuffle } from "../../../../collection/array/array_shuffle.js";
+
+const UNMATCHED = 0xFFFFFFFF;
+
+/**
+ * Sorted Heavy-Edge Matching.
+ *
+ * Visits vertices in random order biased toward lower degree first, and for
+ * each unmatched vertex pairs it with the unmatched neighbour sharing the
+ * heaviest edge weight (subject to a coarse-vertex weight cap).
+ *
+ * Outputs:
+ *  - `graph.coarse_vertex_map[v]` = id of the coarse vertex that vertex v
+ *    collapses into. Numbered so that iterating v=0..vertex_count walks coarse
+ *    ids 0..coarse_vertex_count-1 in order — this property is required by
+ *    `create_coarse_graph`.
+ *  - `partner_of_vertex[v]` = the partner of vertex v (or v itself if it ended
+ *    up alone in the matching). Caller-provided buffer, filled in place.
+ *  - returns `coarse_vertex_count`, the number of coarse vertices created.
+ *
+ * Mirrors `Match_SHEM` from libmetis/coarsen.c, single-constraint branch.
+ * The 2-hop matching escape hatch is intentionally skipped — it's a degeneracy
+ * recovery for graphs with many isolated/low-degree vertices that's not on the
+ * critical path; can add later if cluster quality bites.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {function():number} random seeded RNG
+ * @param {number} max_coarse_vertex_weight cap on the combined weight of a
+ *   matched pair; vertices whose own weight already exceeds this are forced
+ *   into singleton coarse vertices
+ * @param {Uint32Array} partner_of_vertex caller-provided buffer of length
+ *   `>= graph.vertex_count`. Will be filled with each vertex's match partner
+ *   (or its own id if it ended up unmatched). The first `graph.vertex_count`
+ *   entries are clobbered; any tail beyond that is left untouched.
+ * @param {Uint32Array} visit_order caller-provided scratch of length
+ *   `>= graph.vertex_count`. Used as the (random-shuffled, degree-sorted)
+ *   visitation order during matching. Contents on entry are ignored;
+ *   contents on return are undefined.
+ * @param {Uint32Array} sort_key_degree caller-provided scratch of length
+ *   `>= graph.vertex_count`. Holds the per-vertex degree buckets used to sort
+ *   `visit_order`. Contents on entry are ignored; contents on return are undefined.
+ * @returns {number} `coarse_vertex_count`
+ */
+export function match_shem(
+    graph,
+    random,
+    max_coarse_vertex_weight,
+    partner_of_vertex,
+    visit_order,
+    sort_key_degree
+) {
+
+    const vertex_count = graph.vertex_count;
+    const edge_addresses = graph.edge_addresses;
+    const adjacency = graph.adjacency;
+    const edge_weights = graph.edge_weights;
+    const vertex_weights = graph.vertex_weights;
+
+    const coarse_vertex_map = graph.coarse_vertex_map !== null && graph.coarse_vertex_map.length === vertex_count
+        ? graph.coarse_vertex_map
+        : new Uint32Array(vertex_count);
+    graph.coarse_vertex_map = coarse_vertex_map;
+
+    partner_of_vertex.fill(UNMATCHED, 0, vertex_count);
+
+    if (vertex_count === 0) {
+        return 0;
+    }
+
+    // Visitation order: random permutation, then sorted ascending by capped
+    // degree so low-degree (harder to match) vertices get first pick.
+    for (let v = 0; v < vertex_count; v++) {
+        visit_order[v] = v;
+    }
+    array_shuffle(random, visit_order, vertex_count);
+
+    // Visitation order key: bucket vertices by sqrt(1 + degree), capped at
+    // 4× average degree. Mirrors master's heuristic — much more permissive
+    // than 5.1.0's raw-degree + 0.7× cap. Effect: visitation order is roughly
+    // logarithmic in degree, so isolated high-degree outliers don't dominate
+    // the ordering. For graphs with degree variance (real meshes have these),
+    // this gives more uniform matching coverage.
+    const total_adjacency_length = edge_addresses[vertex_count];
+    const average_degree = Math.max(1, Math.floor(4.0 * (total_adjacency_length / vertex_count)));
+
+    for (let v = 0; v < vertex_count; v++) {
+        const degree = edge_addresses[v + 1] - edge_addresses[v];
+        const bucket = Math.floor(Math.sqrt(1 + degree));
+        sort_key_degree[v] = bucket > average_degree ? average_degree : bucket;
+    }
+
+    if (vertex_count > 1) {
+        array_quick_sort_by_lookup_uint(visit_order, sort_key_degree, 0, vertex_count - 1);
+    }
+
+    // --- Pass 1: matching --------------------------------------------------
+    let next_unmatched_search_start = 0;
+
+    for (let visit_position = 0; visit_position < vertex_count; visit_position++) {
+        const vertex = visit_order[visit_position];
+
+        if (partner_of_vertex[vertex] !== UNMATCHED) {
+            continue;
+        }
+
+        let best_partner = vertex;       // self-match if no candidate is found
+        let best_partner_edge_weight = -1;
+
+        if (vertex_weights[vertex] < max_coarse_vertex_weight) {
+
+            const edge_start = edge_addresses[vertex];
+            const edge_end = edge_addresses[vertex + 1];
+
+            if (edge_start === edge_end) {
+                // Isolated vertex: forward-scan visit_order for any other unmatched
+                // vertex. Mirrors METIS's "island" path, which ignores the weight cap
+                // for these pairings.
+                if (next_unmatched_search_start < visit_position) {
+                    next_unmatched_search_start = visit_position;
+                }
+                next_unmatched_search_start++;
+                while (next_unmatched_search_start < vertex_count) {
+                    const candidate = visit_order[next_unmatched_search_start];
+                    if (partner_of_vertex[candidate] === UNMATCHED) {
+                        best_partner = candidate;
+                        break;
+                    }
+                    next_unmatched_search_start++;
+                }
+            } else {
+                // Heavy-edge: pick the unmatched neighbour whose edge has the
+                // greatest weight, subject to the coarse-weight cap.
+                for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                    const neighbor = adjacency[edge_offset];
+                    const weight = edge_weights[edge_offset];
+                    if (
+                        partner_of_vertex[neighbor] === UNMATCHED &&
+                        weight > best_partner_edge_weight &&
+                        vertex_weights[vertex] + vertex_weights[neighbor] <= max_coarse_vertex_weight
+                    ) {
+                        best_partner = neighbor;
+                        best_partner_edge_weight = weight;
+                    }
+                }
+            }
+        }
+
+        if (best_partner !== vertex) {
+            partner_of_vertex[vertex] = best_partner;
+            partner_of_vertex[best_partner] = vertex;
+        }
+        // else: leave UNMATCHED; the renumbering pass below will self-match it.
+    }
+
+    // --- Pass 2: renumber coarse_vertex_map in vertex-id order -------------
+    // `create_coarse_graph` requires that when it processes vertices in order
+    // v = 0..vertex_count, coarse_vertex_map[v] equals the running count of
+    // coarse vertices produced so far. Also self-match anything still UNMATCHED.
+    let coarse_vertex_count = 0;
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        const partner = partner_of_vertex[vertex];
+        if (partner === UNMATCHED) {
+            partner_of_vertex[vertex] = vertex;
+            coarse_vertex_map[vertex] = coarse_vertex_count;
+            coarse_vertex_count++;
+        } else if (vertex <= partner) {
+            coarse_vertex_map[vertex] = coarse_vertex_count;
+            coarse_vertex_map[partner] = coarse_vertex_count;
+            coarse_vertex_count++;
+        }
+    }
+
+    return coarse_vertex_count;
+}

package/src/core/graph/metis/native/initial/initial_kway_bfs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Initial k-way partition via simultaneous BFS from k random seed vertices.
+ *
+ * Each seed grows its partition outward by FIFO BFS, claiming any neighbour
+ * that hasn't been claimed yet. A partition stops growing once its accumulated
+ * vertex weight crosses the per-partition target. Any vertices left unassigned
+ * — typically because their component was fully consumed by a partition that
+ * then hit its cap, or because the graph has more than k components — get
+ * assigned to whichever partition is currently lightest.
+ *
+ * This is a quality-vs-simplicity trade-off relative to METIS's recursive
+ * bisection on the coarsest graph. Bisection produces lower edge cuts but
+ * costs roughly 5× the code. FM uncoarsening recovers a large fraction of the
+ * quality difference, so we ship BFS-growth first and revisit if needed.
+ *
+ * Writes to `graph.vertex_partition[]` and `graph.partition_weights[]`. Both
+ * must already be allocated (call `graph.allocate_partition_state(partition_count)`).
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the coarsest graph
+ * @param {number} partition_count
+ * @param {function():number} random
+ */
+export function initial_kway_bfs(graph: import('../MetisGraph.js').MetisGraph, partition_count: number, random: () => number): void;
+//# sourceMappingURL=initial_kway_bfs.d.ts.map

package/src/core/graph/metis/native/initial/initial_kway_bfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initial_kway_bfs.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/initial/initial_kway_bfs.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAJW,OAAO,kBAAkB,EAAE,UAAU,mBACrC,MAAM,gBACK,MAAM,QAyF3B"}

package/src/core/graph/metis/native/initial/initial_kway_bfs.js

@@ -0,0 +1,122 @@
+import { array_shuffle } from "../../../../collection/array/array_shuffle.js";
+
+const UNASSIGNED = 0xFFFFFFFF;
+
+/**
+ * Fractional overshoot allowed for a partition's weight during BFS growth.
+ * Once a partition crosses `target_weight × this`, it stops claiming new
+ * neighbours. A small slack avoids starving a partition that hits the target
+ * exactly mid-step.
+ */
+const GROWTH_OVERSHOOT_FRACTION = 1.05;
+
+/**
+ * Initial k-way partition via simultaneous BFS from k random seed vertices.
+ *
+ * Each seed grows its partition outward by FIFO BFS, claiming any neighbour
+ * that hasn't been claimed yet. A partition stops growing once its accumulated
+ * vertex weight crosses the per-partition target. Any vertices left unassigned
+ * — typically because their component was fully consumed by a partition that
+ * then hit its cap, or because the graph has more than k components — get
+ * assigned to whichever partition is currently lightest.
+ *
+ * This is a quality-vs-simplicity trade-off relative to METIS's recursive
+ * bisection on the coarsest graph. Bisection produces lower edge cuts but
+ * costs roughly 5× the code. FM uncoarsening recovers a large fraction of the
+ * quality difference, so we ship BFS-growth first and revisit if needed.
+ *
+ * Writes to `graph.vertex_partition[]` and `graph.partition_weights[]`. Both
+ * must already be allocated (call `graph.allocate_partition_state(partition_count)`).
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the coarsest graph
+ * @param {number} partition_count
+ * @param {function():number} random
+ */
+export function initial_kway_bfs(graph, partition_count, random) {
+    const vertex_count = graph.vertex_count;
+    const edge_addresses = graph.edge_addresses;
+    const adjacency = graph.adjacency;
+    const vertex_weights = graph.vertex_weights;
+    const total_vertex_weight = graph.total_vertex_weight;
+    const vertex_partition = graph.vertex_partition;
+    const partition_weights = graph.partition_weights;
+
+    vertex_partition.fill(UNASSIGNED);
+    partition_weights.fill(0);
+
+    if (vertex_count === 0 || partition_count === 0) {
+        return;
+    }
+
+    const partition_weight_cap = Math.ceil((total_vertex_weight / partition_count) * GROWTH_OVERSHOOT_FRACTION);
+
+    // Pick k distinct seeds by shuffling all vertex ids and taking the prefix.
+    // Cheaper alternatives exist for k << vertex_count but this is simple and
+    // unambiguously correct.
+    const shuffled_vertex_ids = new Uint32Array(vertex_count);
+    for (let v = 0; v < vertex_count; v++) {
+        shuffled_vertex_ids[v] = v;
+    }
+    array_shuffle(random, shuffled_vertex_ids);
+
+    // Shared (vertex, partition) FIFO queue. We claim a vertex by writing to
+    // vertex_partition at push time, so every vertex is pushed at most once
+    // and 2*vertex_count bounds the queue size.
+    const bfs_queue = new Uint32Array(vertex_count * 2);
+    let queue_head = 0;
+    let queue_tail = 0;
+
+    const seed_count = Math.min(partition_count, vertex_count);
+    for (let partition = 0; partition < seed_count; partition++) {
+        const seed_vertex = shuffled_vertex_ids[partition];
+        vertex_partition[seed_vertex] = partition;
+        partition_weights[partition] = vertex_weights[seed_vertex];
+        bfs_queue[queue_tail++] = seed_vertex;
+        bfs_queue[queue_tail++] = partition;
+    }
+
+    while (queue_head < queue_tail) {
+        const vertex = bfs_queue[queue_head++];
+        const partition = bfs_queue[queue_head++];
+
+        if (partition_weights[partition] >= partition_weight_cap) {
+            continue;
+        }
+
+        const edge_start = edge_addresses[vertex];
+        const edge_end = edge_addresses[vertex + 1];
+        for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+            const neighbor = adjacency[edge_offset];
+            if (vertex_partition[neighbor] !== UNASSIGNED) {
+                continue;
+            }
+            vertex_partition[neighbor] = partition;
+            partition_weights[partition] += vertex_weights[neighbor];
+            bfs_queue[queue_tail++] = neighbor;
+            bfs_queue[queue_tail++] = partition;
+            if (partition_weights[partition] >= partition_weight_cap) {
+                break;
+            }
+        }
+    }
+
+    // Mop up vertices left unassigned (disconnected components, or stranded
+    // because every neighbour was claimed before the BFS reached them and the
+    // claiming partition then hit its cap). Assign each to the currently
+    // lightest partition.
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        if (vertex_partition[vertex] !== UNASSIGNED) {
+            continue;
+        }
+        let lightest_partition = 0;
+        let lightest_partition_weight = partition_weights[0];
+        for (let partition = 1; partition < partition_count; partition++) {
+            if (partition_weights[partition] < lightest_partition_weight) {
+                lightest_partition_weight = partition_weights[partition];
+                lightest_partition = partition;
+            }
+        }
+        vertex_partition[vertex] = lightest_partition;
+        partition_weights[lightest_partition] += vertex_weights[vertex];
+    }
+}