@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,101 @@
+import { IndexedFloatMaxHeap } from "../refine/IndexedFloatMaxHeap.js";
+
+/**
+ * Pre-allocated scratch reused by every recursive `bisect_graph` call during
+ * the initial-partition phase.
+ *
+ * Recursive bisection produces O(k) subgraphs that each need their own
+ * refinement state and FM scratch — but only at sizes <= the coarsest vertex
+ * count. Sharing one set of arrays scoped to that maximum eliminates O(k)
+ * typed-array allocations and the corresponding GC pressure.
+ *
+ * Contents:
+ *
+ *   - **Compute-2way state**: `boundary_vertices`, `boundary_position_of_vertex`,
+ *     `internal_degree`, `external_degree`, `partition_weights[2]`.
+ *
+ *   - **FM-2way state**: `fm_heaps` (one per side of the bisection),
+ *     `fm_moved_pass_index`, `fm_swap_history`, `fm_insertion_order`.
+ *
+ *   - **Bisect snapshot**: `best_partition_snapshot` for grow+FM trial selection.
+ *
+ *   - **`vertex_partition_pool`**: a stack of vertex_partition arrays. Each
+ *     recursive call takes a slot (via `take_vertex_partition_slot`) and
+ *     releases it on return. New slots are allocated lazily, capped at
+ *     `log2(k)` total — the maximum recursion depth.
+ *
+ * The two FM heaps are sized to `max_vertex_count` at construction. Their
+ * internal `__slot_of_id` table can hold any id in `[0, max_vertex_count)`, so
+ * subgraphs of any size below that work without expanding. `clear()` resets
+ * heap state in O(size), not O(capacity).
+ *
+ * `fm_moved_pass_index` starts initialised to -1. fm_2way's per-pass cleanup
+ * resets touched entries back to -1, so the invariant is preserved across
+ * calls — no need to refill the whole array between bisect_graph invocations.
+ */
+export class BisectionScratch {
+    /**
+     * @param {number} max_vertex_count typically the coarsest graph's vertex count
+     */
+    constructor(max_vertex_count) {
+        this.max_vertex_count = max_vertex_count;
+
+        // --- 2-way refinement state shared with compute_2way_params ---
+
+        this.boundary_vertices = new Uint32Array(max_vertex_count);
+        this.boundary_position_of_vertex = new Int32Array(max_vertex_count);
+        this.internal_degree = new Uint32Array(max_vertex_count);
+        this.external_degree = new Uint32Array(max_vertex_count);
+        this.partition_weights = new Uint32Array(2);
+        this.best_partition_snapshot = new Uint32Array(max_vertex_count);
+
+        // --- FM_2way scratch ---
+
+        this.fm_heaps = [
+            new IndexedFloatMaxHeap(max_vertex_count, Math.min(max_vertex_count, 1024)),
+            new IndexedFloatMaxHeap(max_vertex_count, Math.min(max_vertex_count, 1024))
+        ];
+        this.fm_moved_pass_index = new Int32Array(max_vertex_count);
+        this.fm_moved_pass_index.fill(-1);
+        this.fm_swap_history = new Uint32Array(max_vertex_count);
+        this.fm_insertion_order = new Uint32Array(max_vertex_count);
+
+        // --- vertex_partition stack pool ---
+
+        /** @type {Uint32Array[]} */
+        this.vertex_partition_pool = [];
+        this.vertex_partition_pool_top = 0;
+    }
+
+    /**
+     * Borrow a vertex_partition slot from the pool. The first `vertex_count`
+     * entries are zero-filled; values past `vertex_count` may hold stale data
+     * from a sibling subgraph and must not be read.
+     *
+     * Returned slot remains owned by the scratch; release with
+     * `release_vertex_partition_slot` once you're done with it.
+     *
+     * @param {number} vertex_count subgraph's vertex_count
+     * @returns {Uint32Array}
+     */
+    take_vertex_partition_slot(vertex_count) {
+        const slot_index = this.vertex_partition_pool_top;
+        let slot = this.vertex_partition_pool[slot_index];
+        if (slot === undefined) {
+            slot = new Uint32Array(this.max_vertex_count);
+            this.vertex_partition_pool.push(slot);
+        } else {
+            slot.fill(0, 0, vertex_count);
+        }
+        this.vertex_partition_pool_top = slot_index + 1;
+        return slot;
+    }
+
+    /**
+     * Pop the top vertex_partition slot off the pool. Pairs with
+     * `take_vertex_partition_slot` — call exactly once per take.
+     */
+    release_vertex_partition_slot() {
+        this.vertex_partition_pool_top--;
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Bisect a graph into two partitions with `target_weight_for_partition_0` weight
+ * landing in partition 0. Runs `bisection_trial_count` independent BFS-grow + FM
+ * trials and keeps the best (lowest-cut) result.
+ *
+ * Mirrors `Init2WayPartition` from libmetis/initpart.c, single-constraint cut
+ * branch only.
+ *
+ * **All scratch state is taken from the supplied `BisectionScratch`**:
+ *   - the 2-way refinement arrays (`internal_degree`, `external_degree`,
+ *     boundary list, `partition_weights[2]`),
+ *   - the FM heaps and pass-local arrays,
+ *   - the best-cut snapshot,
+ *   - and `vertex_partition` itself, which the caller borrows from the
+ *     scratch's stack pool and releases after using the result.
+ *
+ * The k-way bookkeeping arrays (`neighbor_partition_*`, `neighbor_partition_pool`)
+ * are NOT set up here — bisection doesn't need them. They get allocated by
+ * `allocate_partition_state(k)` once recursive bisection is done and the graph
+ * moves into k-way refinement.
+ *
+ * On return, `graph.vertex_partition[]` contains 0/1 in `[0, vertex_count)` and
+ * `graph.current_cut` is the bisection cut. The vertex_partition slot may be
+ * sized larger than vertex_count — only the prefix is meaningful.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {Uint32Array} vertex_partition pre-zeroed slot from the scratch pool;
+ *   typically obtained via `scratch.take_vertex_partition_slot(graph.vertex_count)`
+ * @param {number} target_weight_for_partition_0
+ * @param {number} bisection_trial_count number of independent grow+FM trials
+ * @param {number} fm_pass_count FM passes per trial
+ * @param {number} ub_factor balance tolerance for `grow_bisection`
+ * @param {function():number} random
+ * @param {import('./BisectionScratch.js').BisectionScratch} scratch
+ */
+export function bisect_graph(graph: import('../MetisGraph.js').MetisGraph, vertex_partition: Uint32Array, target_weight_for_partition_0: number, bisection_trial_count: number, fm_pass_count: number, ub_factor: number, random: () => number, scratch: import('./BisectionScratch.js').BisectionScratch): void;
+//# sourceMappingURL=bisect_graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bisect_graph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/bisect_graph.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,oCAVW,OAAO,kBAAkB,EAAE,UAAU,oBACrC,WAAW,iCAEX,MAAM,yBACN,MAAM,iBACN,MAAM,aACN,MAAM,gBACK,MAAM,WACjB,OAAO,uBAAuB,EAAE,gBAAgB,QA6C1D"}

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

@@ -0,0 +1,100 @@
+import { compute_2way_params } from "./compute_2way_params.js";
+import { fm_2way } from "./fm_2way.js";
+import { grow_bisection } from "./grow_bisection.js";
+
+/**
+ * Bisect a graph into two partitions with `target_weight_for_partition_0` weight
+ * landing in partition 0. Runs `bisection_trial_count` independent BFS-grow + FM
+ * trials and keeps the best (lowest-cut) result.
+ *
+ * Mirrors `Init2WayPartition` from libmetis/initpart.c, single-constraint cut
+ * branch only.
+ *
+ * **All scratch state is taken from the supplied `BisectionScratch`**:
+ *   - the 2-way refinement arrays (`internal_degree`, `external_degree`,
+ *     boundary list, `partition_weights[2]`),
+ *   - the FM heaps and pass-local arrays,
+ *   - the best-cut snapshot,
+ *   - and `vertex_partition` itself, which the caller borrows from the
+ *     scratch's stack pool and releases after using the result.
+ *
+ * The k-way bookkeeping arrays (`neighbor_partition_*`, `neighbor_partition_pool`)
+ * are NOT set up here — bisection doesn't need them. They get allocated by
+ * `allocate_partition_state(k)` once recursive bisection is done and the graph
+ * moves into k-way refinement.
+ *
+ * On return, `graph.vertex_partition[]` contains 0/1 in `[0, vertex_count)` and
+ * `graph.current_cut` is the bisection cut. The vertex_partition slot may be
+ * sized larger than vertex_count — only the prefix is meaningful.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {Uint32Array} vertex_partition pre-zeroed slot from the scratch pool;
+ *   typically obtained via `scratch.take_vertex_partition_slot(graph.vertex_count)`
+ * @param {number} target_weight_for_partition_0
+ * @param {number} bisection_trial_count number of independent grow+FM trials
+ * @param {number} fm_pass_count FM passes per trial
+ * @param {number} ub_factor balance tolerance for `grow_bisection`
+ * @param {function():number} random
+ * @param {import('./BisectionScratch.js').BisectionScratch} scratch
+ */
+export function bisect_graph(
+    graph,
+    vertex_partition,
+    target_weight_for_partition_0,
+    bisection_trial_count,
+    fm_pass_count,
+    ub_factor,
+    random,
+    scratch
+) {
+    attach_scratch(graph, vertex_partition, scratch);
+
+    let best_cut = -1;
+    const best_partition = scratch.best_partition_snapshot;
+    const vertex_count = graph.vertex_count;
+
+    for (let trial = 0; trial < bisection_trial_count; trial++) {
+        grow_bisection(graph, target_weight_for_partition_0, ub_factor, random);
+        compute_2way_params(graph);
+        fm_2way(graph, target_weight_for_partition_0, fm_pass_count, random, scratch);
+
+        if (best_cut === -1 || graph.current_cut < best_cut) {
+            best_cut = graph.current_cut;
+            // Snapshot only the active subgraph range — best_partition is
+            // sized to max_vertex_count and may have stale values past
+            // vertex_count from a sibling's earlier bisection.
+            for (let v = 0; v < vertex_count; v++) {
+                best_partition[v] = vertex_partition[v];
+            }
+        }
+
+        if (best_cut === 0) {
+            break;
+        }
+    }
+
+    // Restore the best partition if a later trial wasn't the winner.
+    if (best_cut !== graph.current_cut) {
+        for (let v = 0; v < vertex_count; v++) {
+            vertex_partition[v] = best_partition[v];
+        }
+        compute_2way_params(graph);
+    }
+}
+
+/**
+ * Wire the graph's bisection-state fields to point at the supplied
+ * vertex_partition slot and the shared scratch arrays.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {Uint32Array} vertex_partition pre-zeroed slot owned by the scratch pool
+ * @param {import('./BisectionScratch.js').BisectionScratch} scratch
+ */
+function attach_scratch(graph, vertex_partition, scratch) {
+    graph.vertex_partition = vertex_partition;
+    graph.partition_weights = scratch.partition_weights;
+    graph.boundary_vertices = scratch.boundary_vertices;
+    graph.boundary_position_of_vertex = scratch.boundary_position_of_vertex;
+    graph.internal_degree = scratch.internal_degree;
+    graph.external_degree = scratch.external_degree;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * From a freshly-assigned bisection `vertex_partition[]` (containing only 0
+ * and 1), populate the 2-way refinement bookkeeping: per-partition weights,
+ * per-vertex internal/external degree, boundary list, and total cut.
+ *
+ * Mirrors `Compute2WayPartitionParams` from libmetis/refine.c.
+ *
+ * For 2-way refinement, the neighbour-partition list is trivially "the other
+ * partition", so we don't allocate any cnbr pool — only the parallel
+ * `internal_degree[v]` and `external_degree[v]` arrays are needed.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ */
+export function compute_2way_params(graph: import('../MetisGraph.js').MetisGraph): void;
+//# sourceMappingURL=compute_2way_params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute_2way_params.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/compute_2way_params.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,2CAFW,OAAO,kBAAkB,EAAE,UAAU,QAsE/C"}

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

@@ -0,0 +1,84 @@
+import { assert } from "../../../../assert.js";
+
+/**
+ * From a freshly-assigned bisection `vertex_partition[]` (containing only 0
+ * and 1), populate the 2-way refinement bookkeeping: per-partition weights,
+ * per-vertex internal/external degree, boundary list, and total cut.
+ *
+ * Mirrors `Compute2WayPartitionParams` from libmetis/refine.c.
+ *
+ * For 2-way refinement, the neighbour-partition list is trivially "the other
+ * partition", so we don't allocate any cnbr pool — only the parallel
+ * `internal_degree[v]` and `external_degree[v]` arrays are needed.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ */
+export function compute_2way_params(graph) {
+    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;
+
+    assert.equal(vertex_partition !== null, true, 'graph.vertex_partition must be allocated');
+    assert.equal(partition_weights.length, 2, 'partition_weights must be sized for 2 partitions');
+
+    partition_weights[0] = 0;
+    partition_weights[1] = 0;
+    // internal_degree and external_degree do not need pre-clearing — every
+    // vertex in [0, vertex_count) gets written in the per-vertex loop below,
+    // and we never read past vertex_count.
+    // boundary_position_of_vertex IS read conditionally (only boundary vertices
+    // get set), so it does need a clear — but bounded to the active subgraph
+    // range, since the scratch may be sized for a larger ancestor graph.
+    boundary_position_of_vertex.fill(-1, 0, vertex_count);
+
+    for (let v = 0; v < vertex_count; v++) {
+        partition_weights[vertex_partition[v]] += vertex_weights[v];
+    }
+
+    let boundary_count = 0;
+    let cut_doubled = 0;
+
+    for (let vertex = 0; vertex < vertex_count; vertex++) {
+        const my_partition = vertex_partition[vertex];
+
+        let v_internal_degree = 0;
+        let v_external_degree = 0;
+
+        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_partition = vertex_partition[adjacency[edge_offset]];
+            const edge_weight = edge_weights[edge_offset];
+            if (neighbor_partition === my_partition) {
+                v_internal_degree += edge_weight;
+            } else {
+                v_external_degree += edge_weight;
+            }
+        }
+
+        internal_degree[vertex] = v_internal_degree;
+        external_degree[vertex] = v_external_degree;
+
+        if (v_external_degree > 0 || edge_start === edge_end) {
+            // Add isolated vertices too — they're "boundary" in the degenerate sense
+            // that moving them is free. Matches METIS behaviour.
+            if (v_external_degree > 0) {
+                cut_doubled += v_external_degree;
+                boundary_vertices[boundary_count] = vertex;
+                boundary_position_of_vertex[vertex] = boundary_count;
+                boundary_count++;
+            }
+        }
+    }
+
+    graph.current_cut = cut_doubled >> 1;
+    graph.boundary_count = boundary_count;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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: import('../MetisGraph.js').MetisGraph, target_weight_for_partition_0: number, pass_count: number, random: () => number, scratch: import('./BisectionScratch.js').BisectionScratch): void;
+//# sourceMappingURL=fm_2way.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fm_2way.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/fm_2way.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+BAPW,OAAO,kBAAkB,EAAE,UAAU,iCACrC,MAAM,cACN,MAAM,gBACK,MAAM,WAEjB,OAAO,uBAAuB,EAAE,gBAAgB,QAuQ1D"}

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;
+        }
+    }
+}