@woosh/meep-engine 2.138.19 → 2.139.0

package/src/core/graph/csr/CSRGraph.js

@@ -0,0 +1,319 @@
+import { assert } from "../../assert.js";
+import { is_typed_array_equals } from "../../collection/array/typed/is_typed_array_equals.js";
+import { uint32_array_hash } from "../../collection/array/typed/uint32_array_hash.js";
+
+/**
+ * Compressed Sparse Row representation of a weighted graph.
+ *
+ * The four parallel typed arrays — `edge_addresses`, `adjacency`,
+ * `edge_weights`, `vertex_weights` — share a single `ArrayBuffer` so that
+ * they are co-located in memory. This gives the allocator one allocation
+ * instead of four, the GC one reference to track, and the cache one
+ * contiguous region to prefetch when walking adjacency rows.
+ *
+ * Layout inside the buffer (all uint32, 4 bytes each):
+ *   [0]                       edge_addresses, length vertex_count + 1
+ *   [vertex_count + 1]        adjacency,      length adjacency_length
+ *   [+adjacency_length]       edge_weights,   length adjacency_length
+ *   [+adjacency_length]       vertex_weights, length vertex_count
+ *
+ * Conventions match `mesh_to_metis_graph`:
+ *   - `edge_addresses[v]`     = start of vertex v's adjacency in `adjacency`
+ *   - `edge_addresses[v + 1]` = end (exclusive)
+ *   - `adjacency[k]`          = neighbour vertex id
+ *   - `edge_weights[k]`       = weight of that edge
+ *   - `vertex_weights[v]`     = vertex weight (default 1)
+ *
+ * The class deliberately exposes the raw typed arrays as fields rather than
+ * via accessor methods. Hot loops in graph algorithms want
+ * `for (let k = xadj[v]; k < xadj[v+1]; k++) { ... adj[k] ... }` patterns; a
+ * callback-based iterator API would force a closure allocation per outer
+ * iteration and defeat V8's inlining.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class CSRGraph {
+    /**
+     * @param {number} vertex_count
+     * @param {number} adjacency_length total length of the adjacency list
+     *   (each undirected edge appears twice for symmetric graphs)
+     */
+    constructor(vertex_count, adjacency_length) {
+        assert.isNonNegativeInteger(vertex_count, 'vertex_count');
+        assert.isNonNegativeInteger(adjacency_length, 'adjacency_length');
+
+        /** @type {number} */
+        this.vertex_count = vertex_count;
+        /** @type {number} */
+        this.adjacency_length = adjacency_length;
+
+        // Total uint32 slots: (vertex_count + 1) for edge_addresses,
+        // adjacency_length × 2 for adjacency and edge_weights,
+        // vertex_count for vertex_weights.
+        const total_uint32_slots = (vertex_count + 1) + (adjacency_length * 2) + vertex_count;
+
+        /**
+         * Single backing buffer for all four arrays.
+         * @type {ArrayBuffer}
+         * @private
+         */
+        this.__data_buffer = new ArrayBuffer(total_uint32_slots * 4);
+
+        let byte_offset = 0;
+
+        /**
+         * CSR row pointers. Length = vertex_count + 1; the final entry equals
+         * adjacency_length.
+         * @type {Uint32Array}
+         */
+        this.edge_addresses = new Uint32Array(this.__data_buffer, byte_offset, vertex_count + 1);
+        byte_offset += (vertex_count + 1) * 4;
+
+        /**
+         * CSR column indices — neighbour vertex ids.
+         * @type {Uint32Array}
+         */
+        this.adjacency = new Uint32Array(this.__data_buffer, byte_offset, adjacency_length);
+        byte_offset += adjacency_length * 4;
+
+        /**
+         * Edge weights parallel to `adjacency`.
+         * @type {Uint32Array}
+         */
+        this.edge_weights = new Uint32Array(this.__data_buffer, byte_offset, adjacency_length);
+        byte_offset += adjacency_length * 4;
+
+        /**
+         * Per-vertex weight. Initialised to all-1s; overwrite via direct
+         * indexing or `vertex_weights.set(...)` if your domain needs non-uniform
+         * weights. Remember to call `refresh_total_vertex_weight()` after.
+         * @type {Uint32Array}
+         */
+        this.vertex_weights = new Uint32Array(this.__data_buffer, byte_offset, vertex_count);
+        this.vertex_weights.fill(1);
+
+        /**
+         * Cached `Σ vertex_weights[v]`. Kept in sync via `refresh_total_vertex_weight()`.
+         * @type {number}
+         */
+        this.total_vertex_weight = vertex_count;
+    }
+
+    /**
+     * The underlying shared buffer. Useful for fast bulk operations and for
+     * passing the graph between Web Workers via transfer.
+     * @returns {ArrayBuffer}
+     */
+    get arrayBuffer() {
+        return this.__data_buffer;
+    }
+
+    /**
+     * Degree of vertex `vertex` (number of outgoing edges in the CSR).
+     * @param {number} vertex
+     * @returns {number}
+     */
+    degree_of(vertex) {
+        return this.edge_addresses[vertex + 1] - this.edge_addresses[vertex];
+    }
+
+    /**
+     * Sum of all entries in `edge_weights[0..adjacency_length)`.
+     * Each undirected edge contributes twice for a symmetric graph.
+     * @returns {number}
+     */
+    sum_of_edge_weights() {
+        const edge_weights = this.edge_weights;
+        const n = this.adjacency_length;
+        let sum = 0;
+        for (let i = 0; i < n; i++) {
+            sum += edge_weights[i];
+        }
+        return sum;
+    }
+
+    /**
+     * Recompute and store `total_vertex_weight` from the current `vertex_weights`.
+     */
+    refresh_total_vertex_weight() {
+        const vertex_weights = this.vertex_weights;
+        const n = this.vertex_count;
+        let sum = 0;
+        for (let i = 0; i < n; i++) {
+            sum += vertex_weights[i];
+        }
+        this.total_vertex_weight = sum;
+    }
+
+    /**
+     * Shrink `adjacency` and `edge_weights` in place to `new_adjacency_length`.
+     *
+     * Use after a worst-case allocation has been partially filled (e.g. during
+     * coarse-graph contraction where the exact edge count is only known after
+     * the merge pass). Reallocates the shared buffer at the smaller size and
+     * recreates all four typed-array views; existing references to
+     * `this.adjacency` etc. are invalidated.
+     *
+     * Vertex-side data (`edge_addresses`, `vertex_weights`) and
+     * `total_vertex_weight` are preserved.
+     *
+     * No-op if `new_adjacency_length === adjacency_length`.
+     *
+     * @param {number} new_adjacency_length must be <= current `adjacency_length`
+     */
+    truncate_adjacency(new_adjacency_length) {
+        assert.isNonNegativeInteger(new_adjacency_length, 'new_adjacency_length');
+        assert.lessThanOrEqual(new_adjacency_length, this.adjacency_length, 'truncate_adjacency cannot grow');
+
+        if (new_adjacency_length === this.adjacency_length) {
+            return;
+        }
+
+        // Keep references to the OLD views — they remain valid because the old
+        // buffer stays alive until we drop the last reference to it (which
+        // happens implicitly when we reassign this.__data_buffer at the end).
+        // We can copy DIRECTLY from old views into new views with no
+        // intermediate snapshot, since the two buffers don't overlap.
+        const old_edge_addresses = this.edge_addresses;
+        const old_adjacency = this.adjacency;
+        const old_edge_weights = this.edge_weights;
+        const old_vertex_weights = this.vertex_weights;
+
+        const total_uint32_slots = (this.vertex_count + 1) + (new_adjacency_length * 2) + this.vertex_count;
+        const new_buffer = new ArrayBuffer(total_uint32_slots * 4);
+
+        let byte_offset = 0;
+        const new_edge_addresses = new Uint32Array(new_buffer, byte_offset, this.vertex_count + 1);
+        byte_offset += (this.vertex_count + 1) * 4;
+        const new_adjacency = new Uint32Array(new_buffer, byte_offset, new_adjacency_length);
+        byte_offset += new_adjacency_length * 4;
+        const new_edge_weights = new Uint32Array(new_buffer, byte_offset, new_adjacency_length);
+        byte_offset += new_adjacency_length * 4;
+        const new_vertex_weights = new Uint32Array(new_buffer, byte_offset, this.vertex_count);
+
+        // Direct old-view → new-view copies. `subarray` is a view, not a copy,
+        // so the only data movement is the underlying `.set()`.
+        new_edge_addresses.set(old_edge_addresses);
+        new_adjacency.set(old_adjacency.subarray(0, new_adjacency_length));
+        new_edge_weights.set(old_edge_weights.subarray(0, new_adjacency_length));
+        new_vertex_weights.set(old_vertex_weights);
+
+        this.__data_buffer = new_buffer;
+        this.edge_addresses = new_edge_addresses;
+        this.adjacency = new_adjacency;
+        this.edge_weights = new_edge_weights;
+        this.vertex_weights = new_vertex_weights;
+        this.adjacency_length = new_adjacency_length;
+    }
+
+    /**
+     * Copy the contents of `other` into `this`. Other must have matching
+     * `vertex_count` and `adjacency_length` (so the layouts align).
+     *
+     * Performed as a single bulk Uint32Array `.set()` thanks to the shared
+     * buffer layout — significantly faster than copying the four arrays
+     * individually.
+     *
+     * @param {CSRGraph} other
+     */
+    copy(other) {
+        assert.equal(other.isCSRGraph, true, 'other.isCSRGraph !== true');
+        assert.equal(this.vertex_count, other.vertex_count, 'vertex_count mismatch');
+        assert.equal(this.adjacency_length, other.adjacency_length, 'adjacency_length mismatch');
+
+        new Uint32Array(this.__data_buffer).set(new Uint32Array(other.__data_buffer));
+        this.total_vertex_weight = other.total_vertex_weight;
+    }
+
+    /**
+     * Deep copy. Returns a new `CSRGraph` with independent buffers.
+     * @returns {CSRGraph}
+     */
+    clone() {
+        const out = new CSRGraph(this.vertex_count, this.adjacency_length);
+        out.copy(this);
+        return out;
+    }
+
+    /**
+     * Structural equality — same shape and same buffer contents.
+     * @param {CSRGraph} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+        if (other === null || other === undefined || other.isCSRGraph !== true) {
+            return false;
+        }
+        if (this.vertex_count !== other.vertex_count) {
+            return false;
+        }
+        if (this.adjacency_length !== other.adjacency_length) {
+            return false;
+        }
+        if (this.total_vertex_weight !== other.total_vertex_weight) {
+            return false;
+        }
+        return is_typed_array_equals(
+            new Uint32Array(this.__data_buffer),
+            new Uint32Array(other.__data_buffer)
+        );
+    }
+
+    /**
+     * 32-bit hash mixing the metadata fields and the entire buffer contents.
+     * Uses meep's standard `(h*31 + element)` convention via `uint32_array_hash`.
+     *
+     * @returns {number}
+     */
+    hash() {
+        let h = this.vertex_count;
+        h = ((h << 5) - h) + this.adjacency_length;
+        h = ((h << 5) - h) + this.total_vertex_weight;
+        const buffer_view = new Uint32Array(this.__data_buffer);
+        const buffer_hash = uint32_array_hash(buffer_view, 0, buffer_view.length);
+        h = ((h << 5) - h) + buffer_hash;
+        return h | 0;
+    }
+
+    /**
+     * Construct a CSRGraph from existing arrays by COPYING into a new
+     * shared-buffer instance. The input arrays are not retained.
+     *
+     * `vertex_weights` is optional — if not provided, the new graph keeps the
+     * default all-1s vertex weights and `total_vertex_weight = vertex_count`.
+     *
+     * @param {number} vertex_count
+     * @param {ArrayLike<number>} edge_addresses length vertex_count + 1
+     * @param {ArrayLike<number>} adjacency length edge_addresses[vertex_count]
+     * @param {ArrayLike<number>} edge_weights parallel to adjacency
+     * @param {ArrayLike<number>} [vertex_weights] optional; length vertex_count
+     * @returns {CSRGraph}
+     */
+    static fromArrays(vertex_count, edge_addresses, adjacency, edge_weights, vertex_weights) {
+        const adjacency_length = edge_addresses[vertex_count];
+        const out = new CSRGraph(vertex_count, adjacency_length);
+
+        out.edge_addresses.set(edge_addresses);
+        out.adjacency.set(adjacency);
+        out.edge_weights.set(edge_weights);
+
+        if (vertex_weights !== undefined) {
+            out.vertex_weights.set(vertex_weights);
+            out.refresh_total_vertex_weight();
+        }
+
+        return out;
+    }
+}
+
+/**
+ * Type-check marker — avoids `instanceof` across module realms while still
+ * letting us assert "is a CSRGraph" cheaply.
+ * @readonly
+ * @type {boolean}
+ */
+CSRGraph.prototype.isCSRGraph = true;

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

@@ -1,4 +1,16 @@
 /**
+ * @deprecated Delegates to the deprecated `metis_cluster_bs`, which uses the
+ * WASM-backed `Metis.INSTANCE`. Replace with the native equivalent:
+ *
+ *   import { metis_partition_kway } from "./native/metis_partition_kway.js";
+ *   import { mesh_to_metis_graph } from "./mesh_to_metis_graph.js";
+ *
+ *   const csr = mesh_to_metis_graph(Array.from(mesh.getFaces()));
+ *   const k = Math.ceil(face_count / patch_size);
+ *   const partition = metis_partition_kway(face_count, k, csr.edge_addresses,
+ *       csr.adjacency, csr.edge_weights, { seed: 0xCAFE });
+ *
+ * The native call is synchronous, so this becomes a non-async wrapper.
  *
  * @param {Uint32Array} result
  * @param {TopoMesh} mesh

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

@@ -1 +1 @@
-{"version":3,"file":"cluster_mesh_metis.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/cluster_mesh_metis.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,2CALW,WAAW,8BAEX,MAAM,GACJ,MAAM,CAqBlB"}
+{"version":3,"file":"cluster_mesh_metis.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/metis/cluster_mesh_metis.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2CALW,WAAW,8BAEX,MAAM,GACJ,MAAM,CAqBlB"}

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

@@ -2,6 +2,18 @@ import { mesh_to_metis_graph } from "./mesh_to_metis_graph.js";
 import { metis_cluster_bs } from "./metis_cluster_bs.js";
 
 /**
+ * @deprecated Delegates to the deprecated `metis_cluster_bs`, which uses the
+ * WASM-backed `Metis.INSTANCE`. Replace with the native equivalent:
+ *
+ *   import { metis_partition_kway } from "./native/metis_partition_kway.js";
+ *   import { mesh_to_metis_graph } from "./mesh_to_metis_graph.js";
+ *
+ *   const csr = mesh_to_metis_graph(Array.from(mesh.getFaces()));
+ *   const k = Math.ceil(face_count / patch_size);
+ *   const partition = metis_partition_kway(face_count, k, csr.edge_addresses,
+ *       csr.adjacency, csr.edge_weights, { seed: 0xCAFE });
+ *
+ * The native call is synchronous, so this becomes a non-async wrapper.
  *
  * @param {Uint32Array} result
  * @param {TopoMesh} mesh

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

@@ -1,6 +1,25 @@
+/**
+ * @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 {
     service: OnDemandWorkerManager;
     /**
+     * @deprecated Use `metis_partition_kway` from
+     * `./native/metis_partition_kway.js` instead.
      *
      * @param {number} n_vertices
      * @param {number} n_parts

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