@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -0,0 +1,290 @@
+/**
+ * 2-way Fiduccia–Mattheyses cut refinement (single-constraint, cut objective).
+ *
+ * Maintains two max-heaps keyed by per-vertex gain (`external_degree − internal_degree`),
+ * one per side of the bisection. Each pass:
+ *   1. Insert every boundary vertex into the queue for its current side.
+ *   2. Repeatedly pop from whichever side is more overweight, move the vertex,
+ *      and update neighbours. Track running cut and remember the best snapshot.
+ *   3. Stop when both queues drain, or when `LIMIT_NONIMPROVING_MOVES` moves
+ *      pass without finding a better cut.
+ *   4. Roll back any moves made after the best-cut snapshot.
+ *
+ * Each vertex is locked after moving once (it can't move back in the same pass).
+ * Locking is reset between passes.
+ *
+ * Mirrors `FM_2WayCutRefine` from libmetis/fm.c.
+ *
+ * All scratch state (heaps, moved-index, swap history, insertion order) is
+ * shared via the `BisectionScratch` passed in by the caller, sized to the
+ * coarsest graph's vertex_count. This eliminates per-trial allocation.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {number} target_weight_for_partition_0
+ * @param {number} pass_count
+ * @param {function():number} random seeded RNG used to shuffle boundary
+ *   insertion order so ties break differently each pass
+ * @param {import('./BisectionScratch.js').BisectionScratch} scratch
+ */
+export function fm_2way(graph, target_weight_for_partition_0, pass_count, random, scratch) {
+    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 vertex_partition = graph.vertex_partition;
+    const partition_weights = graph.partition_weights;
+    const internal_degree = graph.internal_degree;
+    const external_degree = graph.external_degree;
+    const boundary_vertices = graph.boundary_vertices;
+    const boundary_position_of_vertex = graph.boundary_position_of_vertex;
+
+    if (vertex_count === 0 || graph.boundary_count === 0) {
+        return;
+    }
+
+    const target_weight_0 = target_weight_for_partition_0;
+    const target_weight_1 = graph.total_vertex_weight - target_weight_for_partition_0;
+
+    // METIS heuristic: stop a pass after this many moves with no improvement.
+    const limit_nonimproving_moves = Math.min(Math.max(Math.floor(0.01 * vertex_count), 15), 100);
+
+    // METIS uses this for a "close enough to mincut" tolerance when picking
+    // the best snapshot — avoids overreacting to small noise in pwgt-balance.
+    const avg_vertex_weight = Math.min(
+        Math.floor((partition_weights[0] + partition_weights[1]) / 20),
+        Math.floor(2 * (partition_weights[0] + partition_weights[1]) / vertex_count)
+    );
+
+    const queues = scratch.fm_heaps;
+    const moved_pass_index = scratch.fm_moved_pass_index;
+    const swap_history = scratch.fm_swap_history;
+    const insertion_order = scratch.fm_insertion_order;
+
+    const initial_partition_0_diff = Math.abs(target_weight_0 - partition_weights[0]);
+
+    for (let pass = 0; pass < pass_count; pass++) {
+        queues[0].clear();
+        queues[1].clear();
+
+        let best_cut = graph.current_cut;
+        let best_partition_diff = Math.abs(target_weight_0 - partition_weights[0]);
+        let best_cut_swap_index = -1;
+        let running_cut = best_cut;
+        let initial_cut_this_pass = best_cut;
+
+        let boundary_count = graph.boundary_count;
+
+        // Insert boundary vertices in random order so ties break differently each pass.
+        for (let i = 0; i < boundary_count; i++) {
+            insertion_order[i] = i;
+        }
+        // Fisher–Yates shuffle of insertion_order[0..boundary_count)
+        for (let i = boundary_count - 1; i > 0; i--) {
+            const j = (random() * (i + 1)) | 0;
+            if (j !== i) {
+                const tmp = insertion_order[i];
+                insertion_order[i] = insertion_order[j];
+                insertion_order[j] = tmp;
+            }
+        }
+        for (let i = 0; i < boundary_count; i++) {
+            const vertex = boundary_vertices[insertion_order[i]];
+            const gain = external_degree[vertex] - internal_degree[vertex];
+            queues[vertex_partition[vertex]].insert(vertex, gain);
+        }
+
+        let swap_count = 0;
+        for (; swap_count < vertex_count; swap_count++) {
+            // Pick the side that's more overweight (or equivalently, more under-target).
+            const from_side = (target_weight_0 - partition_weights[0]) < (target_weight_1 - partition_weights[1]) ? 0 : 1;
+            const to_side = 1 - from_side;
+
+            const high_gain_vertex = queues[from_side].pop_max();
+            if (high_gain_vertex === -1) {
+                break;
+            }
+
+            const gain = external_degree[high_gain_vertex] - internal_degree[high_gain_vertex];
+            running_cut -= gain;
+
+            partition_weights[from_side] -= vertex_weights[high_gain_vertex];
+            partition_weights[to_side] += vertex_weights[high_gain_vertex];
+
+            const new_partition_diff = Math.abs(target_weight_0 - partition_weights[0]);
+
+            const improves_cut_within_balance = (
+                running_cut < best_cut &&
+                new_partition_diff <= initial_partition_0_diff + avg_vertex_weight
+            );
+            const matches_cut_but_better_balance = (
+                running_cut === best_cut &&
+                new_partition_diff < best_partition_diff
+            );
+
+            if (improves_cut_within_balance || matches_cut_but_better_balance) {
+                best_cut = running_cut;
+                best_partition_diff = new_partition_diff;
+                best_cut_swap_index = swap_count;
+            } else if (swap_count - best_cut_swap_index > limit_nonimproving_moves) {
+                // Pass has gone too long without improvement — undo this last move and stop.
+                running_cut += gain;
+                partition_weights[from_side] += vertex_weights[high_gain_vertex];
+                partition_weights[to_side] -= vertex_weights[high_gain_vertex];
+                break;
+            }
+
+            vertex_partition[high_gain_vertex] = to_side;
+            moved_pass_index[high_gain_vertex] = swap_count;
+            swap_history[swap_count] = high_gain_vertex;
+
+            // After the move, swap id/ed for the moved vertex:
+            // edges that used to be external (going to `to_side`) are now internal,
+            // and vice versa.
+            {
+                const tmp = internal_degree[high_gain_vertex];
+                internal_degree[high_gain_vertex] = external_degree[high_gain_vertex];
+                external_degree[high_gain_vertex] = tmp;
+            }
+
+            // Maybe drop the moved vertex from the boundary.
+            if (external_degree[high_gain_vertex] === 0 && edge_addresses[high_gain_vertex] < edge_addresses[high_gain_vertex + 1]) {
+                const bp = boundary_position_of_vertex[high_gain_vertex];
+                if (bp !== -1) {
+                    const last = boundary_count - 1;
+                    if (bp !== last) {
+                        const moved_to_bp = boundary_vertices[last];
+                        boundary_vertices[bp] = moved_to_bp;
+                        boundary_position_of_vertex[moved_to_bp] = bp;
+                    }
+                    boundary_position_of_vertex[high_gain_vertex] = -1;
+                    boundary_count = last;
+                }
+            }
+
+            // Update id/ed of neighbours, their boundary membership, and their queue positions.
+            const edge_start = edge_addresses[high_gain_vertex];
+            const edge_end = edge_addresses[high_gain_vertex + 1];
+            for (let edge_offset = edge_start; edge_offset < edge_end; edge_offset++) {
+                const neighbor = adjacency[edge_offset];
+                const ewgt = edge_weights[edge_offset];
+                const signed_ewgt = (to_side === vertex_partition[neighbor]) ? ewgt : -ewgt;
+                internal_degree[neighbor] += signed_ewgt;
+                external_degree[neighbor] -= signed_ewgt;
+
+                const n_was_on_boundary = boundary_position_of_vertex[neighbor] !== -1;
+
+                if (n_was_on_boundary) {
+                    if (external_degree[neighbor] === 0) {
+                        // Drop from boundary
+                        const bp = boundary_position_of_vertex[neighbor];
+                        const last = boundary_count - 1;
+                        if (bp !== last) {
+                            const moved_to_bp = boundary_vertices[last];
+                            boundary_vertices[bp] = moved_to_bp;
+                            boundary_position_of_vertex[moved_to_bp] = bp;
+                        }
+                        boundary_position_of_vertex[neighbor] = -1;
+                        boundary_count = last;
+                        if (moved_pass_index[neighbor] === -1) {
+                            queues[vertex_partition[neighbor]].remove(neighbor);
+                        }
+                    } else {
+                        // Still on boundary, update queue priority
+                        if (moved_pass_index[neighbor] === -1) {
+                            const updated_gain = external_degree[neighbor] - internal_degree[neighbor];
+                            queues[vertex_partition[neighbor]].update(neighbor, updated_gain);
+                        }
+                    }
+                } else {
+                    if (external_degree[neighbor] > 0) {
+                        // New boundary vertex
+                        boundary_vertices[boundary_count] = neighbor;
+                        boundary_position_of_vertex[neighbor] = boundary_count;
+                        boundary_count++;
+                        if (moved_pass_index[neighbor] === -1) {
+                            const initial_gain = external_degree[neighbor] - internal_degree[neighbor];
+                            queues[vertex_partition[neighbor]].insert(neighbor, initial_gain);
+                        }
+                    }
+                }
+            }
+        }
+
+        // Reset moved-status for vertices we touched this pass. Preserves the
+        // "all -1" invariant for the shared moved_pass_index across calls.
+        for (let i = 0; i < swap_count; i++) {
+            moved_pass_index[swap_history[i]] = -1;
+        }
+
+        // Roll back any moves made after best_cut_swap_index.
+        for (let i = swap_count - 1; i > best_cut_swap_index; i--) {
+            const vertex = swap_history[i];
+            const flipped_from = vertex_partition[vertex];
+            const flipped_to = 1 - flipped_from;
+            vertex_partition[vertex] = flipped_to;
+
+            // Swap id/ed back
+            {
+                const tmp = internal_degree[vertex];
+                internal_degree[vertex] = external_degree[vertex];
+                external_degree[vertex] = tmp;
+            }
+
+            // Maybe re-add or remove from boundary based on new ed
+            if (external_degree[vertex] === 0 && boundary_position_of_vertex[vertex] !== -1 && edge_addresses[vertex] < edge_addresses[vertex + 1]) {
+                const bp = boundary_position_of_vertex[vertex];
+                const last = boundary_count - 1;
+                if (bp !== last) {
+                    const moved_to_bp = boundary_vertices[last];
+                    boundary_vertices[bp] = moved_to_bp;
+                    boundary_position_of_vertex[moved_to_bp] = bp;
+                }
+                boundary_position_of_vertex[vertex] = -1;
+                boundary_count = last;
+            } else if (external_degree[vertex] > 0 && boundary_position_of_vertex[vertex] === -1) {
+                boundary_vertices[boundary_count] = vertex;
+                boundary_position_of_vertex[vertex] = boundary_count;
+                boundary_count++;
+            }
+
+            partition_weights[flipped_from] -= vertex_weights[vertex];
+            partition_weights[flipped_to] += vertex_weights[vertex];
+
+            // Update neighbours
+            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];
+                const ewgt = edge_weights[edge_offset];
+                const signed_ewgt = (flipped_to === vertex_partition[neighbor]) ? ewgt : -ewgt;
+                internal_degree[neighbor] += signed_ewgt;
+                external_degree[neighbor] -= signed_ewgt;
+
+                if (boundary_position_of_vertex[neighbor] !== -1 && external_degree[neighbor] === 0) {
+                    const bp = boundary_position_of_vertex[neighbor];
+                    const last = boundary_count - 1;
+                    if (bp !== last) {
+                        const moved_to_bp = boundary_vertices[last];
+                        boundary_vertices[bp] = moved_to_bp;
+                        boundary_position_of_vertex[moved_to_bp] = bp;
+                    }
+                    boundary_position_of_vertex[neighbor] = -1;
+                    boundary_count = last;
+                }
+                if (boundary_position_of_vertex[neighbor] === -1 && external_degree[neighbor] > 0) {
+                    boundary_vertices[boundary_count] = neighbor;
+                    boundary_position_of_vertex[neighbor] = boundary_count;
+                    boundary_count++;
+                }
+            }
+        }
+
+        graph.current_cut = best_cut;
+        graph.boundary_count = boundary_count;
+
+        if (best_cut_swap_index <= 0 || best_cut === initial_cut_this_pass) {
+            break;
+        }
+    }
+}

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