@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -1 +1 @@
-{"version":3,"file":"metis.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis.js"],"names":[],"mappings":"AAIA;IAQQ,+BAAsB;IAG1B;;;;;;;;;OASG;IACH,sBARW,MAAM,WACN,MAAM,kBACN,WAAW,aACX,WAAW,gBACX,WAAW,2BAET,UAAU,CAkBtB;CACJ;;kBAKS,KAAK;;sCA/CuB,+CAA+C"}
+{"version":3,"file":"metis.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH;IAQQ,+BAAsB;IAG1B;;;;;;;;;;;OAWG;IACH,sBARW,MAAM,WACN,MAAM,kBACN,WAAW,aACX,WAAW,gBACX,WAAW,2BAET,UAAU,CAkBtB;CACJ;;kBAMS,KAAK;;sCAnEuB,+CAA+C"}

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

@@ -2,6 +2,23 @@ import { OnDemandWorkerManager } from "../../process/worker/OnDemandWorkerManage
 import WorkerBuilder from "../../process/worker/WorkerBuilder.js";
 
 
+/**
+ * @deprecated Use the native JS implementation at
+ * `./native/metis_partition_kway.js` instead.
+ *
+ * This class wraps the WASM-compiled METIS via a worker. It depends on
+ * `libs/metis/metis.js` being served by the host app and on a `micron_partition`
+ * global being defined inside that script. The native equivalent has no such
+ * dependencies, is synchronous (no worker round-trip), and tracks the latest
+ * `KarypisLab/METIS` master rather than the 2013-era 5.1.0 release.
+ *
+ * Migration:
+ *   - Was:  `await Metis.INSTANCE.partition(nv, k, xadj, adj, ewgt, options)`
+ *   - Now:  `metis_partition_kway(nv, k, xadj, adj, ewgt, { seed, niter, ufactor })`
+ *
+ * The native function returns the partition array directly (synchronously);
+ * wrap in `Promise.resolve(...)` if you need a promise-returning surface.
+ */
 export class Metis {
     constructor() {
         const wb = new WorkerBuilder();
@@ -14,6 +31,8 @@ export class Metis {
     }
 
     /**
+     * @deprecated Use `metis_partition_kway` from
+     * `./native/metis_partition_kway.js` instead.
      *
      * @param {number} n_vertices
      * @param {number} n_parts
@@ -44,6 +63,7 @@ export class Metis {
 
 /**
  * Singleton instance
+ * @deprecated Use the native implementation at `./native/metis_partition_kway.js`.
  * @readonly
  * @type {Metis}
  */

package/src/core/graph/metis/metis_cluster_bs.d.ts

@@ -1,4 +1,15 @@
 /**
+ * @deprecated Calls the WASM-backed `Metis.INSTANCE`, which is deprecated. Build
+ * the equivalent on top of `metis_partition_kway` from
+ * `./native/metis_partition_kway.js` — the binary-search-on-k pattern here is
+ * independent of the partitioner, so the same loop body works against either
+ * backend.
+ *
+ * The native partitioner does roughly the same balance enforcement internally
+ * via FM with `ub_factor = 1.03`, so the binary search typically converges in
+ * 1-2 passes; for many use cases a single `metis_partition_kway` call with
+ * `k = Math.ceil(node_count / patch_size)` is sufficient and the BS wrapper is
+ * unnecessary.
  *
  * @param {Uint32Array} result
  * @param {number} node_count

package/src/core/graph/metis/metis_cluster_bs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metis_cluster_bs.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis_cluster_bs.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,yCARW,WAAW,cACX,MAAM,kBACN,WAAW,oBACX,WAAW,uBACX,WAAW,cACX,MAAM,GACJ,QAAQ,MAAM,CAAC,CA6G3B"}
+{"version":3,"file":"metis_cluster_bs.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis_cluster_bs.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,yCARW,WAAW,cACX,MAAM,kBACN,WAAW,oBACX,WAAW,uBACX,WAAW,cACX,MAAM,GACJ,QAAQ,MAAM,CAAC,CA6G3B"}

package/src/core/graph/metis/metis_cluster_bs.js

@@ -8,6 +8,17 @@ import { metis_options } from "./metis_options.js";
 const MAX_STEPS = 50;
 
 /**
+ * @deprecated Calls the WASM-backed `Metis.INSTANCE`, which is deprecated. Build
+ * the equivalent on top of `metis_partition_kway` from
+ * `./native/metis_partition_kway.js` — the binary-search-on-k pattern here is
+ * independent of the partitioner, so the same loop body works against either
+ * backend.
+ *
+ * The native partitioner does roughly the same balance enforcement internally
+ * via FM with `ub_factor = 1.03`, so the binary search typically converges in
+ * 1-2 passes; for many use cases a single `metis_partition_kway` call with
+ * `k = Math.ceil(node_count / patch_size)` is sufficient and the BS wrapper is
+ * unnecessary.
  *
  * @param {Uint32Array} result
  * @param {number} node_count

package/src/core/graph/metis/metis_options.d.ts

@@ -1,6 +1,21 @@
 /**
- * See metis.h for more details
- * -1 is the used to signal absence of value, in which case a default will be used
+ * @deprecated Used only by the deprecated WASM-backed `Metis` class. The
+ * native partitioner at `./native/metis_partition_kway.js` accepts a plain
+ * object literal instead:
+ *
+ *   metis_partition_kway(nv, k, xadj, adj, ewgt, {
+ *       seed: 0xCAFE,                                  // integer; default 0
+ *       niter: 10,                                     // FM passes per level
+ *       ufactor: 30,                                   // imbalance per-mille
+ *       initial_partition_strategy: 'recursive_bisection' // or 'bfs'
+ *   });
+ *
+ * Most `metis.h` options (ctype, iptype, rtype, no2hop, minconn, contig,
+ * compress, ncuts, pfactor, etc.) are not exposed by the native impl because
+ * those code paths aren't implemented. If you need one, file a request.
+ *
+ * See metis.h for more details on the original fields.
+ * -1 is used to signal absence of value, in which case a default will be used.
  */
 export class metis_options {
     ptype: number;

package/src/core/graph/metis/metis_options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metis_options.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis_options.js"],"names":[],"mappings":"AACA;;;GAGG;AACH;IACI,cAAW;IACX,gBAAa;IACb;;;;;OAKG;IACH,OAFU,MAAM,CAEL;IACX,eAAY;IACZ,cAAW;IACX,eAAY;IACZ,cAAW;IACX,cAAW;IACX;;;;OAIG;IACH,MAFU,MAAM,CAEN;IACV,eAAY;IACZ,gBAAa;IACb,eAAY;IACZ,gBAAa;IACb,gBAAa;IACb,cAAW;IACX,gBAAa;IACb,kBAAe;IACf,iBAAe;CAClB"}
+{"version":3,"file":"metis_options.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/metis_options.js"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI,cAAW;IACX,gBAAa;IACb;;;;;OAKG;IACH,OAFU,MAAM,CAEL;IACX,eAAY;IACZ,cAAW;IACX,eAAY;IACZ,cAAW;IACX,cAAW;IACX;;;;OAIG;IACH,MAFU,MAAM,CAEN;IACV,eAAY;IACZ,gBAAa;IACb,eAAY;IACZ,gBAAa;IACb,gBAAa;IACb,cAAW;IACX,gBAAa;IACb,kBAAe;IACf,iBAAe;CAClB"}

package/src/core/graph/metis/metis_options.js

@@ -1,7 +1,22 @@
 
 /**
- * See metis.h for more details
- * -1 is the used to signal absence of value, in which case a default will be used
+ * @deprecated Used only by the deprecated WASM-backed `Metis` class. The
+ * native partitioner at `./native/metis_partition_kway.js` accepts a plain
+ * object literal instead:
+ *
+ *   metis_partition_kway(nv, k, xadj, adj, ewgt, {
+ *       seed: 0xCAFE,                                  // integer; default 0
+ *       niter: 10,                                     // FM passes per level
+ *       ufactor: 30,                                   // imbalance per-mille
+ *       initial_partition_strategy: 'recursive_bisection' // or 'bfs'
+ *   });
+ *
+ * Most `metis.h` options (ctype, iptype, rtype, no2hop, minconn, contig,
+ * compress, ncuts, pfactor, etc.) are not exposed by the native impl because
+ * those code paths aren't implemented. If you need one, file a request.
+ *
+ * See metis.h for more details on the original fields.
+ * -1 is used to signal absence of value, in which case a default will be used.
  */
 export class metis_options {
     ptype = -1;

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

@@ -0,0 +1,144 @@
+/**
+ * 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 {
+    /**
+     * 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}
+     */
+    coarse_vertex_map: Uint32Array | null;
+    /** @type {MetisGraph|null} */
+    coarser_graph: MetisGraph | null;
+    /** @type {MetisGraph|null} */
+    finer_graph: MetisGraph | null;
+    /**
+     * Partition id per vertex, in [0, nparts).
+     * @type {Uint32Array|null}
+     */
+    vertex_partition: Uint32Array | null;
+    /**
+     * Per-partition total weight (sum of `vertex_weights` for vertices
+     * currently assigned to that partition).
+     * @type {Uint32Array|null}
+     */
+    partition_weights: Uint32Array | null;
+    /**
+     * Current edge cut: sum of weights of edges whose endpoints lie in
+     * different partitions. Tracked incrementally during refinement.
+     * @type {number}
+     */
+    current_cut: number;
+    /**
+     * Number of vertices currently on a partition boundary.
+     * @type {number}
+     */
+    boundary_count: number;
+    /**
+     * 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}
+     */
+    boundary_vertices: Uint32Array | 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}
+     */
+    boundary_position_of_vertex: Int32Array | null;
+    /**
+     * Internal degree: sum of edge weights from v to vertices in v's own
+     * partition. ("id" in METIS / FM literature.)
+     * @type {Uint32Array|null}
+     */
+    internal_degree: Uint32Array | null;
+    /**
+     * External degree: sum of edge weights from v to vertices in other
+     * partitions. ("ed" in METIS / FM literature.)
+     * @type {Uint32Array|null}
+     */
+    external_degree: Uint32Array | null;
+    /**
+     * Number of distinct neighbouring partitions reachable from v through
+     * its edges. ("nnbrs" in METIS.)
+     * @type {Uint32Array|null}
+     */
+    neighbor_partition_count: Uint32Array | 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}
+     */
+    neighbor_partition_offset: Int32Array | 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}
+     */
+    neighbor_partition_pool: BinaryElementPool | 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: number): void;
+    /**
+     * 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(): void;
+    isMetisGraph: boolean;
+}
+import { CSRGraph } from "../../csr/CSRGraph.js";
+import { BinaryElementPool } from "../../../geom/3d/topology/struct/binary/BinaryElementPool.js";
+//# sourceMappingURL=MetisGraph.d.ts.map

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