@woosh/meep-engine 2.138.20 → 2.140.0

package/src/core/graph/metis/native/bisection/grow_bisection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Initial bisection by BFS growth from a single random seed.
+ *
+ * All vertices start in partition 1. A random seed is picked, then BFS
+ * expansion moves vertices into partition 0 one at a time until partition 0
+ * reaches the target weight. Includes METIS's "drain" handling: if popping a
+ * vertex would underflow partition 1's minimum weight, skip it and wait for
+ * lighter candidates further down the queue.
+ *
+ * Mirrors `GrowBisection` from libmetis/initpart.c.
+ *
+ * Writes to `graph.vertex_partition[]`. Caller is responsible for sizing
+ * `graph.partition_weights` to 2 entries (which is allocated by the standard
+ * `allocate_partition_state(2)` path).
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {number} target_weight_for_partition_0 the bisection target — partition
+ *   0 should end up at roughly this weight
+ * @param {number} ub_factor load-imbalance factor (e.g. 1.03)
+ * @param {function():number} random
+ */
+export function grow_bisection(graph: import('../MetisGraph.js').MetisGraph, target_weight_for_partition_0: number, ub_factor: number, random: () => number): void;
+//# sourceMappingURL=grow_bisection.d.ts.map

package/src/core/graph/metis/native/bisection/grow_bisection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grow_bisection.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/grow_bisection.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCANW,OAAO,kBAAkB,EAAE,UAAU,iCACrC,MAAM,aAEN,MAAM,gBACK,MAAM,QAmH3B"}

package/src/core/graph/metis/native/bisection/grow_bisection.js

@@ -0,0 +1,137 @@
+import { randomIntegerBetween } from "../../../../math/random/randomIntegerBetween.js";
+
+/**
+ * Initial bisection by BFS growth from a single random seed.
+ *
+ * All vertices start in partition 1. A random seed is picked, then BFS
+ * expansion moves vertices into partition 0 one at a time until partition 0
+ * reaches the target weight. Includes METIS's "drain" handling: if popping a
+ * vertex would underflow partition 1's minimum weight, skip it and wait for
+ * lighter candidates further down the queue.
+ *
+ * Mirrors `GrowBisection` from libmetis/initpart.c.
+ *
+ * Writes to `graph.vertex_partition[]`. Caller is responsible for sizing
+ * `graph.partition_weights` to 2 entries (which is allocated by the standard
+ * `allocate_partition_state(2)` path).
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {number} target_weight_for_partition_0 the bisection target — partition
+ *   0 should end up at roughly this weight
+ * @param {number} ub_factor load-imbalance factor (e.g. 1.03)
+ * @param {function():number} random
+ */
+export function grow_bisection(graph, target_weight_for_partition_0, ub_factor, 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;
+
+    const partition_1_minimum_weight = Math.floor(
+        (total_vertex_weight - target_weight_for_partition_0) / ub_factor
+    );
+    const partition_1_maximum_weight = Math.ceil(
+        (total_vertex_weight - target_weight_for_partition_0) * ub_factor
+    );
+
+    // Start with everything in partition 1.
+    vertex_partition.fill(1);
+    partition_weights[0] = 0;
+    partition_weights[1] = total_vertex_weight;
+
+    if (vertex_count === 0) {
+        return;
+    }
+
+    const bfs_queue = new Uint32Array(vertex_count);
+    const touched = new Uint8Array(vertex_count);
+
+    const seed_vertex = randomIntegerBetween(random, 0, vertex_count - 1);
+    bfs_queue[0] = seed_vertex;
+    touched[seed_vertex] = 1;
+    let queue_head = 0;
+    let queue_tail = 1;
+    let unclaimed_count = vertex_count - 1;
+    let in_drain_mode = false;
+
+    for (;;) {
+        if (queue_head === queue_tail) {
+            // BFS frontier exhausted before reaching the target — the graph
+            // (or this component of it) is smaller than expected. Either the
+            // graph is disconnected, or partition 0 already overflowed its
+            // target and entered drain mode permanently.
+            if (unclaimed_count === 0 || in_drain_mode) {
+                break;
+            }
+            // Pick a random unclaimed vertex to seed a new BFS branch.
+            let skip = randomIntegerBetween(random, 0, unclaimed_count - 1);
+            let chosen = -1;
+            for (let candidate = 0; candidate < vertex_count; candidate++) {
+                if (touched[candidate] !== 0) continue;
+                if (skip === 0) {
+                    chosen = candidate;
+                    break;
+                }
+                skip--;
+            }
+            if (chosen === -1) {
+                break;
+            }
+            bfs_queue[queue_tail++] = chosen;
+            touched[chosen] = 1;
+            unclaimed_count--;
+            queue_head = queue_tail - 1;
+        }
+
+        const vertex = bfs_queue[queue_head++];
+
+        // Moving this vertex would underflow partition 1's lower bound.
+        // METIS calls this "drain mode": skip the vertex and try the next.
+        if (partition_weights[0] > 0 && partition_weights[1] - vertex_weights[vertex] < partition_1_minimum_weight) {
+            in_drain_mode = true;
+            continue;
+        }
+
+        vertex_partition[vertex] = 0;
+        partition_weights[0] += vertex_weights[vertex];
+        partition_weights[1] -= vertex_weights[vertex];
+
+        if (partition_weights[1] <= partition_1_maximum_weight) {
+            // Partition 1 is at or below the upper bound — partition 0 is full enough.
+            break;
+        }
+
+        in_drain_mode = false;
+
+        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 (touched[neighbor] === 0) {
+                bfs_queue[queue_tail++] = neighbor;
+                touched[neighbor] = 1;
+                unclaimed_count--;
+            }
+        }
+    }
+
+    // Pathological edge cases — make sure both partitions are non-empty so
+    // downstream code doesn't choke on a degenerate bisection.
+    if (partition_weights[0] === 0) {
+        const forced_seed = randomIntegerBetween(random, 0, vertex_count - 1);
+        partition_weights[0] += vertex_weights[forced_seed];
+        partition_weights[1] -= vertex_weights[forced_seed];
+        vertex_partition[forced_seed] = 0;
+    }
+    if (partition_weights[1] === 0) {
+        const forced_seed = randomIntegerBetween(random, 0, vertex_count - 1);
+        if (vertex_partition[forced_seed] === 0) {
+            partition_weights[0] -= vertex_weights[forced_seed];
+            partition_weights[1] += vertex_weights[forced_seed];
+            vertex_partition[forced_seed] = 1;
+        }
+    }
+}

package/src/core/graph/metis/native/bisection/split_graph_two_way.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Given a graph and a `vertex_partition[]` containing only 0 and 1, build the
+ * two induced subgraphs (one per side) and return them along with vertex-id
+ * mappings back to the parent.
+ *
+ * Each subgraph's CSR contains only the edges with both endpoints on the same
+ * side. Cross-edges are dropped — they represent the bisection cut and don't
+ * play a role in further recursion.
+ *
+ * Mirrors `SplitGraphPart` from libmetis/pmetis.c, simplified.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph fine graph with a 0/1
+ *   `vertex_partition[]` populated by `grow_bisection` + `fm_2way`
+ * @returns {{
+ *   side_0_subgraph: MetisGraph,
+ *   side_1_subgraph: MetisGraph,
+ *   side_0_subgraph_to_parent: Uint32Array,
+ *   side_1_subgraph_to_parent: Uint32Array,
+ * }}
+ */
+export function split_graph_two_way(graph: import('../MetisGraph.js').MetisGraph): {
+    side_0_subgraph: MetisGraph;
+    side_1_subgraph: MetisGraph;
+    side_0_subgraph_to_parent: Uint32Array;
+    side_1_subgraph_to_parent: Uint32Array;
+};
+import { MetisGraph } from "../MetisGraph.js";
+//# sourceMappingURL=split_graph_two_way.d.ts.map

package/src/core/graph/metis/native/bisection/split_graph_two_way.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split_graph_two_way.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/split_graph_two_way.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2CATW,OAAO,kBAAkB,EAAE,UAAU;qBAG1B,UAAU;qBACV,UAAU;+BACA,WAAW;+BACX,WAAW;EAmG1C;2BAtH0B,kBAAkB"}

package/src/core/graph/metis/native/bisection/split_graph_two_way.js

@@ -0,0 +1,119 @@
+import { MetisGraph } from "../MetisGraph.js";
+
+/**
+ * Given a graph and a `vertex_partition[]` containing only 0 and 1, build the
+ * two induced subgraphs (one per side) and return them along with vertex-id
+ * mappings back to the parent.
+ *
+ * Each subgraph's CSR contains only the edges with both endpoints on the same
+ * side. Cross-edges are dropped — they represent the bisection cut and don't
+ * play a role in further recursion.
+ *
+ * Mirrors `SplitGraphPart` from libmetis/pmetis.c, simplified.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph fine graph with a 0/1
+ *   `vertex_partition[]` populated by `grow_bisection` + `fm_2way`
+ * @returns {{
+ *   side_0_subgraph: MetisGraph,
+ *   side_1_subgraph: MetisGraph,
+ *   side_0_subgraph_to_parent: Uint32Array,
+ *   side_1_subgraph_to_parent: Uint32Array,
+ * }}
+ */
+export function split_graph_two_way(graph) {
+    const vertex_count = graph.vertex_count;
+    const parent_edge_addresses = graph.edge_addresses;
+    const parent_adjacency = graph.adjacency;
+    const parent_edge_weights = graph.edge_weights;
+    const parent_vertex_weights = graph.vertex_weights;
+    const parent_vertex_partition = graph.vertex_partition;
+
+    // --- Count per-side vertices and assign subgraph-local ids ---
+    const parent_to_subgraph = new Uint32Array(vertex_count);
+    let side_0_vertex_count = 0;
+    let side_1_vertex_count = 0;
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        if (parent_vertex_partition[vertex] === 0) {
+            parent_to_subgraph[vertex] = side_0_vertex_count;
+            side_0_vertex_count++;
+        } else {
+            parent_to_subgraph[vertex] = side_1_vertex_count;
+            side_1_vertex_count++;
+        }
+    }
+
+    // --- Count per-side edges (only edges with both endpoints same side) ---
+    let side_0_edge_count = 0;
+    let side_1_edge_count = 0;
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        const my_side = parent_vertex_partition[vertex];
+        const edge_start = parent_edge_addresses[vertex];
+        const edge_end = parent_edge_addresses[vertex + 1];
+        for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+            if (parent_vertex_partition[parent_adjacency[edge_offset]] === my_side) {
+                if (my_side === 0) {
+                    side_0_edge_count++;
+                } else {
+                    side_1_edge_count++;
+                }
+            }
+        }
+    }
+
+    // --- Allocate subgraphs and inverse-id maps ---
+    const side_0_subgraph = new MetisGraph(side_0_vertex_count, side_0_edge_count);
+    const side_1_subgraph = new MetisGraph(side_1_vertex_count, side_1_edge_count);
+
+    const side_0_subgraph_to_parent = new Uint32Array(side_0_vertex_count);
+    const side_1_subgraph_to_parent = new Uint32Array(side_1_vertex_count);
+
+    // --- Fill the subgraphs ---
+    side_0_subgraph.edge_addresses[0] = 0;
+    side_1_subgraph.edge_addresses[0] = 0;
+    let side_0_cursor = 0;
+    let side_1_cursor = 0;
+
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        const my_side = parent_vertex_partition[vertex];
+        const subgraph_vertex = parent_to_subgraph[vertex];
+
+        const edge_start = parent_edge_addresses[vertex];
+        const edge_end = parent_edge_addresses[vertex + 1];
+
+        if (my_side === 0) {
+            side_0_subgraph_to_parent[subgraph_vertex] = vertex;
+            side_0_subgraph.vertex_weights[subgraph_vertex] = parent_vertex_weights[vertex];
+            for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                const neighbor = parent_adjacency[edge_offset];
+                if (parent_vertex_partition[neighbor] === 0) {
+                    side_0_subgraph.adjacency[side_0_cursor] = parent_to_subgraph[neighbor];
+                    side_0_subgraph.edge_weights[side_0_cursor] = parent_edge_weights[edge_offset];
+                    side_0_cursor++;
+                }
+            }
+            side_0_subgraph.edge_addresses[subgraph_vertex + 1] = side_0_cursor;
+        } else {
+            side_1_subgraph_to_parent[subgraph_vertex] = vertex;
+            side_1_subgraph.vertex_weights[subgraph_vertex] = parent_vertex_weights[vertex];
+            for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                const neighbor = parent_adjacency[edge_offset];
+                if (parent_vertex_partition[neighbor] === 1) {
+                    side_1_subgraph.adjacency[side_1_cursor] = parent_to_subgraph[neighbor];
+                    side_1_subgraph.edge_weights[side_1_cursor] = parent_edge_weights[edge_offset];
+                    side_1_cursor++;
+                }
+            }
+            side_1_subgraph.edge_addresses[subgraph_vertex + 1] = side_1_cursor;
+        }
+    }
+
+    side_0_subgraph.refresh_total_vertex_weight();
+    side_1_subgraph.refresh_total_vertex_weight();
+
+    return {
+        side_0_subgraph,
+        side_1_subgraph,
+        side_0_subgraph_to_parent,
+        side_1_subgraph_to_parent
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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: import('../MetisGraph.js').MetisGraph, opts: {
+    random: () => number;
+    coarsen_until_vertex_count: number;
+}): import('../MetisGraph.js').MetisGraph;
+//# sourceMappingURL=coarsen_graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coarsen_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/coarsen/coarsen_graph.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,qCANW,OAAO,kBAAkB,EAAE,UAAU;kBACjB,MAAM;gCAA8B,MAAM;IAG5D,OAAO,kBAAkB,EAAE,UAAU,CAgEjD"}

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"}