@woosh/meep-engine 2.138.19 → 2.139.0

package/src/core/graph/metis/native/MetisGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetisGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/metis/native/MetisGraph.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAWQ;;;;OAIG;IACH,mBAFU,WAAW,GAAC,IAAI,CAEG;IAE7B,8BAA8B;IAC9B,eADW,UAAU,GAAC,IAAI,CACD;IACzB,8BAA8B;IAC9B,aADW,UAAU,GAAC,IAAI,CACH;IAIvB;;;OAGG;IACH,kBAFU,WAAW,GAAC,IAAI,CAEE;IAE5B;;;;OAIG;IACH,mBAFU,WAAW,GAAC,IAAI,CAEG;IAE7B;;;;OAIG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,gBAFU,MAAM,CAEO;IAEvB;;;;;OAKG;IACH,mBAFU,WAAW,GAAC,IAAI,CAEG;IAE7B;;;;;OAKG;IACH,6BAFU,UAAU,GAAC,IAAI,CAEc;IAIvC;;;;OAIG;IACH,iBAFU,WAAW,GAAC,IAAI,CAEC;IAE3B;;;;OAIG;IACH,iBAFU,WAAW,GAAC,IAAI,CAEC;IAE3B;;;;OAIG;IACH,0BAFU,WAAW,GAAC,IAAI,CAEU;IAEpC;;;;;OAKG;IACH,2BAFU,UAAU,GAAC,IAAI,CAEY;IAErC;;;;;;;;;;;;OAYG;IACH,yBAFU,iBAAiB,GAAC,IAAI,CAEG;IAGvC;;;;;;;;;;;;;;;;OAgBG;IACH,0CAFW,MAAM,QAyBhB;IAED;;;;OAIG;IACH,+BAcC;IAGL,sBAAiC;CAFhC;yBA/MwB,uBAAuB;kCADd,8DAA8D"}

package/src/core/graph/metis/native/MetisGraph.js

@@ -0,0 +1,212 @@
+import { assert } from "../../../assert.js";
+import { BinaryElementPool } from "../../../geom/3d/topology/struct/binary/BinaryElementPool.js";
+import { CSRGraph } from "../../csr/CSRGraph.js";
+
+/**
+ * Holds one graph level of the METIS multilevel pipeline.
+ *
+ * Extends `CSRGraph` — the CSR adjacency (`edge_addresses`, `adjacency`,
+ * `edge_weights`, `vertex_weights`) lives in a single shared `ArrayBuffer`.
+ *
+ * Adds three groups of fields on top of CSR:
+ *
+ *   - **Multilevel link**: `coarse_vertex_map`, `coarser_graph`, `finer_graph`.
+ *     `coarse_vertex_map[v]` is the id of v's super-vertex one level coarser.
+ *
+ *   - **Partition state**: `vertex_partition`, `partition_weights`, `current_cut`,
+ *     plus the boundary list (`boundary_count` / `boundary_vertices` /
+ *     `boundary_position_of_vertex`).
+ *
+ *   - **K-way refinement bookkeeping**: parallel `internal_degree`,
+ *     `external_degree`, `neighbor_partition_count`, `neighbor_partition_offset`
+ *     arrays plus the shared `neighbor_partition_pool` of `(partition_id, edge_weight)`
+ *     records.
+ *
+ * Partition / refinement arrays are allocated lazily by
+ * `allocate_partition_state(partition_count)` because their sizes depend on `k`,
+ * which isn't known at CSR construction time and isn't needed during the
+ * coarsening or initial-partitioning phases.
+ *
+ * Volume objective, multi-constraint balance, separator data, and the various
+ * minconn/contig auxiliary fields from libmetis `graph_t` are intentionally
+ * omitted — they're not on the path we currently use.
+ */
+export class MetisGraph extends CSRGraph {
+    /**
+     * @param {number} vertex_count
+     * @param {number} adjacency_length total length of the adjacency list (each
+     *   undirected edge appears twice)
+     */
+    constructor(vertex_count, adjacency_length) {
+        super(vertex_count, adjacency_length);
+
+        // --- Multilevel links --------------------------------------------------
+
+        /**
+         * Coarsening map: `coarse_vertex_map[v]` is the id of v's super-vertex
+         * in `coarser_graph`. Null until coarsening runs at this level.
+         * @type {Uint32Array|null}
+         */
+        this.coarse_vertex_map = null;
+
+        /** @type {MetisGraph|null} */
+        this.coarser_graph = null;
+        /** @type {MetisGraph|null} */
+        this.finer_graph = null;
+
+        // --- Partition state --------------------------------------------------
+
+        /**
+         * Partition id per vertex, in [0, nparts).
+         * @type {Uint32Array|null}
+         */
+        this.vertex_partition = null;
+
+        /**
+         * Per-partition total weight (sum of `vertex_weights` for vertices
+         * currently assigned to that partition).
+         * @type {Uint32Array|null}
+         */
+        this.partition_weights = null;
+
+        /**
+         * Current edge cut: sum of weights of edges whose endpoints lie in
+         * different partitions. Tracked incrementally during refinement.
+         * @type {number}
+         */
+        this.current_cut = 0;
+
+        /**
+         * Number of vertices currently on a partition boundary.
+         * @type {number}
+         */
+        this.boundary_count = 0;
+
+        /**
+         * Boundary list: the first `boundary_count` entries are vertex ids on
+         * a partition boundary. Order is not meaningful (entries get swapped
+         * with the tail on removal).
+         * @type {Uint32Array|null}
+         */
+        this.boundary_vertices = null;
+
+        /**
+         * Inverse of `boundary_vertices`: `boundary_position_of_vertex[v]` is
+         * the index of v inside `boundary_vertices`, or -1 if v is interior.
+         * Int32Array because of the -1 sentinel.
+         * @type {Int32Array|null}
+         */
+        this.boundary_position_of_vertex = null;
+
+        // --- K-way refinement bookkeeping (parallel arrays, indexed by vertex)
+
+        /**
+         * Internal degree: sum of edge weights from v to vertices in v's own
+         * partition. ("id" in METIS / FM literature.)
+         * @type {Uint32Array|null}
+         */
+        this.internal_degree = null;
+
+        /**
+         * External degree: sum of edge weights from v to vertices in other
+         * partitions. ("ed" in METIS / FM literature.)
+         * @type {Uint32Array|null}
+         */
+        this.external_degree = null;
+
+        /**
+         * Number of distinct neighbouring partitions reachable from v through
+         * its edges. ("nnbrs" in METIS.)
+         * @type {Uint32Array|null}
+         */
+        this.neighbor_partition_count = null;
+
+        /**
+         * Offset (in record units) into `neighbor_partition_pool` for v's list
+         * of (partition_id, edge_weight) entries. -1 if v is interior and no
+         * pool slot has been allocated yet. ("inbr" in METIS.)
+         * @type {Int32Array|null}
+         */
+        this.neighbor_partition_offset = null;
+
+        /**
+         * Pool of per-(vertex, neighbour-partition) records. Each record is
+         * 8 bytes: two uint32 words holding `(partition_id, edge_weight)`.
+         * Access record `r` via:
+         *   const word_base = neighbor_partition_pool.element_word(r);
+         *   const partition_id  = data_uint32[word_base + 2*k    ];
+         *   const edge_weight   = data_uint32[word_base + 2*k + 1];
+         * where `k` is in `[0, neighbor_partition_count[v])`.
+         *
+         * ("cnbrpool" in METIS.)
+         *
+         * @type {BinaryElementPool|null}
+         */
+        this.neighbor_partition_pool = null;
+    }
+
+    /**
+     * Allocate the k-way refinement bookkeeping arrays. Must be called before
+     * any of the refinement routines runs on this graph.
+     *
+     * **`vertex_partition` is preserved** if it's already set with the correct
+     * length. This matters when the initial-partition phase has already
+     * computed an assignment (e.g. recursive bisection leaves the result in
+     * `vertex_partition` as a buffer that's now owned by this graph) — we
+     * don't want to allocate a fresh array just to copy the existing one in.
+     * If `vertex_partition` is `null` or the wrong size, it gets allocated
+     * fresh and zero-filled.
+     *
+     * Everything else (`partition_weights`, `internal_degree`, etc.) is always
+     * allocated fresh because callers expect a clean refinement-state baseline.
+     *
+     * @param {number} partition_count
+     */
+    allocate_partition_state(partition_count) {
+        assert.isNonNegativeInteger(partition_count, 'partition_count');
+
+        const n = this.vertex_count;
+
+        if (this.vertex_partition === null || this.vertex_partition.length !== n) {
+            this.vertex_partition = new Uint32Array(n);
+        }
+        this.partition_weights = new Uint32Array(partition_count);
+        this.boundary_vertices = new Uint32Array(n);
+        this.boundary_position_of_vertex = new Int32Array(n);
+        this.boundary_position_of_vertex.fill(-1);
+
+        this.internal_degree = new Uint32Array(n);
+        this.external_degree = new Uint32Array(n);
+        this.neighbor_partition_count = new Uint32Array(n);
+        this.neighbor_partition_offset = new Int32Array(n);
+        this.neighbor_partition_offset.fill(-1);
+
+        // Each pool record is 8 bytes (uint32 partition_id, uint32 edge_weight).
+        // Initial capacity sized to the adjacency length as a rough upper bound;
+        // the pool grows on demand.
+        this.neighbor_partition_pool = new BinaryElementPool(8, Math.max(64, this.adjacency_length));
+    }
+
+    /**
+     * Reset the partition / refinement bookkeeping in place, leaving the CSR
+     * adjacency and `coarse_vertex_map` untouched. Used between FM passes when
+     * we want to recompute from a fresh `vertex_partition`.
+     */
+    reset_refinement_state() {
+        if (this.internal_degree !== null) {
+            this.internal_degree.fill(0);
+            this.external_degree.fill(0);
+            this.neighbor_partition_count.fill(0);
+            this.neighbor_partition_offset.fill(-1);
+        }
+        if (this.neighbor_partition_pool !== null) {
+            this.neighbor_partition_pool.clear();
+        }
+        if (this.boundary_position_of_vertex !== null) {
+            this.boundary_position_of_vertex.fill(-1);
+        }
+        this.boundary_count = 0;
+    }
+}
+
+MetisGraph.prototype.isMetisGraph = true;

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

@@ -0,0 +1,72 @@
+/**
+ * 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: number);
+    max_vertex_count: number;
+    boundary_vertices: Uint32Array;
+    boundary_position_of_vertex: Int32Array;
+    internal_degree: Uint32Array;
+    external_degree: Uint32Array;
+    partition_weights: Uint32Array;
+    best_partition_snapshot: Uint32Array;
+    fm_heaps: IndexedFloatMaxHeap[];
+    fm_moved_pass_index: Int32Array;
+    fm_swap_history: Uint32Array;
+    fm_insertion_order: Uint32Array;
+    /** @type {Uint32Array[]} */
+    vertex_partition_pool: Uint32Array[];
+    vertex_partition_pool_top: number;
+    /**
+     * 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: number): Uint32Array;
+    /**
+     * Pop the top vertex_partition slot off the pool. Pairs with
+     * `take_vertex_partition_slot` — call exactly once per take.
+     */
+    release_vertex_partition_slot(): void;
+}
+import { IndexedFloatMaxHeap } from "../refine/IndexedFloatMaxHeap.js";
+//# sourceMappingURL=BisectionScratch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BisectionScratch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/BisectionScratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IACI;;OAEG;IACH,8BAFW,MAAM,EA8BhB;IA3BG,yBAAwC;IAIxC,+BAA0D;IAC1D,wCAAmE;IACnE,6BAAwD;IACxD,6BAAwD;IACxD,+BAA2C;IAC3C,qCAAgE;IAIhE,gCAGC;IACD,gCAA2D;IAE3D,6BAAwD;IACxD,gCAA2D;IAI3D,4BAA4B;IAC5B,uBADW,WAAW,EAAE,CACO;IAC/B,kCAAkC;IAGtC;;;;;;;;;;OAUG;IACH,yCAHW,MAAM,GACJ,WAAW,CAavB;IAED;;;OAGG;IACH,sCAEC;CACJ;oCApGmC,kCAAkC"}

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