@woosh/meep-engine 2.138.20 → 2.139.0

package/src/core/graph/metis/native/initial/initial_kway_recursive_bisection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Initial k-way partitioning via multilevel recursive bisection (MLRB) — the
+ * approach described in Karypis & Kumar 1998, §2.2.
+ *
+ * Quality-wise this is the algorithm the paper actually advocates for the
+ * initial-partition phase. We split the graph in two with weights proportional
+ * to the k-way target, recurse on each half, then project the resulting
+ * sub-partitions back as a 0..k-1 assignment on the parent.
+ *
+ * Compared to `initial_kway_bfs`, MLRB produces meaningfully better initial
+ * cuts at the cost of more work at this phase. Since refinement dominates total
+ * runtime, the overall slowdown is small while the cut improvement is large.
+ *
+ * Mirrors `MlevelRecursiveBisection` from libmetis/pmetis.c, sans the inner
+ * coarsening loop — at this point our caller has already coarsened the graph
+ * and we operate on the coarsest level only.
+ *
+ * Writes to `graph.vertex_partition[]` (sized for `partition_count` partitions,
+ * values in [0, partition_count)). On entry `graph.vertex_partition` may be
+ * unallocated; we install fresh state.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the coarsest graph from
+ *   the outer multilevel pipeline
+ * @param {number} partition_count k
+ * @param {number} ub_factor load-imbalance factor (typically 1.03)
+ * @param {function():number} random
+ */
+export function initial_kway_recursive_bisection(graph: import('../MetisGraph.js').MetisGraph, partition_count: number, ub_factor: number, random: () => number): void;
+//# sourceMappingURL=initial_kway_recursive_bisection.d.ts.map

package/src/core/graph/metis/native/initial/initial_kway_recursive_bisection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initial_kway_recursive_bisection.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/initial/initial_kway_recursive_bisection.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wDANW,OAAO,kBAAkB,EAAE,UAAU,mBAErC,MAAM,aACN,MAAM,gBACK,MAAM,QAgB3B"}

package/src/core/graph/metis/native/initial/initial_kway_recursive_bisection.js

@@ -0,0 +1,170 @@
+import { BisectionScratch } from "../bisection/BisectionScratch.js";
+import { bisect_graph } from "../bisection/bisect_graph.js";
+import { split_graph_two_way } from "../bisection/split_graph_two_way.js";
+
+/**
+ * How many independent bisection trials to run per recursive level.
+ * METIS uses 4-5; we settle on 4 as a reasonable speed/quality tradeoff.
+ */
+const BISECTION_TRIALS_PER_LEVEL = 4;
+
+/**
+ * FM passes per bisection trial. METIS uses 10.
+ */
+const FM_PASSES_PER_TRIAL = 10;
+
+/**
+ * Initial k-way partitioning via multilevel recursive bisection (MLRB) — the
+ * approach described in Karypis & Kumar 1998, §2.2.
+ *
+ * Quality-wise this is the algorithm the paper actually advocates for the
+ * initial-partition phase. We split the graph in two with weights proportional
+ * to the k-way target, recurse on each half, then project the resulting
+ * sub-partitions back as a 0..k-1 assignment on the parent.
+ *
+ * Compared to `initial_kway_bfs`, MLRB produces meaningfully better initial
+ * cuts at the cost of more work at this phase. Since refinement dominates total
+ * runtime, the overall slowdown is small while the cut improvement is large.
+ *
+ * Mirrors `MlevelRecursiveBisection` from libmetis/pmetis.c, sans the inner
+ * coarsening loop — at this point our caller has already coarsened the graph
+ * and we operate on the coarsest level only.
+ *
+ * Writes to `graph.vertex_partition[]` (sized for `partition_count` partitions,
+ * values in [0, partition_count)). On entry `graph.vertex_partition` may be
+ * unallocated; we install fresh state.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph the coarsest graph from
+ *   the outer multilevel pipeline
+ * @param {number} partition_count k
+ * @param {number} ub_factor load-imbalance factor (typically 1.03)
+ * @param {function():number} random
+ */
+export function initial_kway_recursive_bisection(graph, partition_count, ub_factor, random) {
+    if (partition_count === 1) {
+        if (graph.vertex_partition === null) {
+            graph.vertex_partition = new Uint32Array(graph.vertex_count);
+        }
+        graph.vertex_partition.fill(0);
+        return;
+    }
+
+    // Single scratch allocation reused by every recursive bisect_graph call.
+    // Sized to the coarsest graph; subgraphs only ever touch [0, sub_vertex_count).
+    const scratch = new BisectionScratch(graph.vertex_count);
+
+    recursive_bisect_into_range(graph, 0, partition_count, ub_factor, random, scratch);
+}
+
+/**
+ * Recursively bisect `graph` so that on return `graph.vertex_partition[v]`
+ * holds an integer in `[first_partition_id, first_partition_id + partition_count)`.
+ *
+ * Each call takes one vertex_partition slot from the scratch pool, uses it as
+ * the graph's partition assignment, and releases it on return. Pool depth is
+ * bounded by recursion depth (= log2(k)), so at most ~log2(k) slots are ever
+ * live simultaneously — one per stack frame.
+ *
+ * @param {import('../MetisGraph.js').MetisGraph} graph
+ * @param {number} first_partition_id offset into the parent's partition id space
+ * @param {number} partition_count how many partitions to split this graph into
+ * @param {number} ub_factor
+ * @param {function():number} random
+ * @param {import('../bisection/BisectionScratch.js').BisectionScratch} scratch
+ */
+function recursive_bisect_into_range(graph, first_partition_id, partition_count, ub_factor, random, scratch) {
+    if (partition_count === 1) {
+        // Leaf: assign every vertex of this subgraph to `first_partition_id`.
+        // Borrow a slot from the pool — same as non-leaf calls so the projection
+        // step in the parent can read it back uniformly.
+        const vertex_partition = scratch.take_vertex_partition_slot(graph.vertex_count);
+        if (first_partition_id !== 0) {
+            vertex_partition.fill(first_partition_id, 0, graph.vertex_count);
+        }
+        graph.vertex_partition = vertex_partition;
+        return;
+    }
+
+    // Split k into left_count + right_count such that left_count weights the
+    // bisection target proportionally. For an odd k we put the extra partition
+    // on the right; this is arbitrary but matches METIS's convention.
+    const left_partition_count = Math.floor(partition_count / 2);
+    const right_partition_count = partition_count - left_partition_count;
+
+    // Bisection target: partition 0 gets `left_partition_count / partition_count`
+    // of the total vertex weight, so that subsequent recursion produces evenly
+    // weighted leaves overall.
+    const target_weight_for_partition_0 = Math.round(
+        graph.total_vertex_weight * left_partition_count / partition_count
+    );
+
+    const vertex_partition = scratch.take_vertex_partition_slot(graph.vertex_count);
+
+    bisect_graph(
+        graph,
+        vertex_partition,
+        target_weight_for_partition_0,
+        BISECTION_TRIALS_PER_LEVEL,
+        FM_PASSES_PER_TRIAL,
+        ub_factor,
+        random,
+        scratch
+    );
+
+    if (partition_count === 2) {
+        // Base case: the bisection result IS the final k=2 assignment,
+        // just shifted into the right id range.
+        if (first_partition_id !== 0) {
+            const n = graph.vertex_count;
+            for (let v = 0; v < n; v++) {
+                vertex_partition[v] += first_partition_id;
+            }
+        }
+        // Don't release the slot here — the caller's projection step needs to
+        // read graph.vertex_partition. The parent's recursive_bisect_into_range
+        // releases it after projecting.
+        return;
+    }
+
+    // General case: split the graph into two subgraphs, recurse on each, then
+    // project the sub-partitions back into `graph.vertex_partition`.
+    const {
+        side_0_subgraph,
+        side_1_subgraph,
+        side_0_subgraph_to_parent,
+        side_1_subgraph_to_parent
+    } = split_graph_two_way(graph);
+
+    recursive_bisect_into_range(
+        side_0_subgraph,
+        first_partition_id,
+        left_partition_count,
+        ub_factor,
+        random,
+        scratch
+    );
+    recursive_bisect_into_range(
+        side_1_subgraph,
+        first_partition_id + left_partition_count,
+        right_partition_count,
+        ub_factor,
+        random,
+        scratch
+    );
+
+    // Project assignments back into our own slot.
+    const side_0_partition = side_0_subgraph.vertex_partition;
+    const side_1_partition = side_1_subgraph.vertex_partition;
+
+    for (let sub_v = 0; sub_v < side_0_subgraph.vertex_count; sub_v++) {
+        vertex_partition[side_0_subgraph_to_parent[sub_v]] = side_0_partition[sub_v];
+    }
+    for (let sub_v = 0; sub_v < side_1_subgraph.vertex_count; sub_v++) {
+        vertex_partition[side_1_subgraph_to_parent[sub_v]] = side_1_partition[sub_v];
+    }
+
+    // Children's vertex_partition slots are now free — release them in LIFO
+    // order (side_1 was taken last, so it pops first).
+    scratch.release_vertex_partition_slot();  // side_1
+    scratch.release_vertex_partition_slot();  // side_0
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Pure-JS k-way graph partitioning, drop-in compatible with the existing
+ * `micron_partition(...)` WASM-backed entry point.
+ *
+ * Implements the multilevel pipeline: coarsen → initial partition → uncoarsen
+ * with refinement at every level. Scope matches the subset that meep's
+ * `metis_cluster_bs` actually uses:
+ *   - cut-objective only
+ *   - single balance constraint, all vertex weights = 1
+ *   - uniform target partition weights
+ *   - no minconn / contig / volume / multi-constraint paths
+ *
+ * @param {number} vertex_count
+ * @param {number} partition_count
+ * @param {Uint32Array} edge_addresses CSR row pointers, length vertex_count + 1
+ * @param {Uint32Array} adjacency CSR column indices, length edge_addresses[vertex_count]
+ * @param {Uint32Array} edge_weights parallel to adjacency
+ * @param {{
+ *   seed?: number,
+ *   niter?: number,
+ *   ufactor?: number,
+ *   initial_partition_strategy?: 'recursive_bisection' | 'bfs',
+ * }} [options]
+ *   Only a small slice of `metis_options` is wired; everything else uses METIS
+ *   defaults.
+ *   - `ufactor`: load imbalance factor in METIS units (per-mille over 1.0;
+ *     ufactor = 30 → ub_factor = 1.03). Default 30.
+ *   - `niter`: number of FM passes per level. Default 10.
+ *   - `seed`: RNG seed; same seed + same input ⇒ same partition. Default 0.
+ *   - `initial_partition_strategy`: 'recursive_bisection' (Karypis-Kumar §2.2,
+ *     higher quality) or 'bfs' (simpler, faster initial phase, weaker cut).
+ *     Default 'recursive_bisection'.
+ * @returns {Uint32Array} partition assignment per vertex, values in [0, partition_count)
+ */
+export function metis_partition_kway(vertex_count: number, partition_count: number, edge_addresses: Uint32Array, adjacency: Uint32Array, edge_weights: Uint32Array, options?: {
+    seed?: number;
+    niter?: number;
+    ufactor?: number;
+    initial_partition_strategy?: 'recursive_bisection' | 'bfs';
+}): Uint32Array;
+//# sourceMappingURL=metis_partition_kway.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metis_partition_kway.d.ts","sourceRoot":"","sources":["../../../../../../src/core/graph/metis/native/metis_partition_kway.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,mDAtBW,MAAM,mBACN,MAAM,kBACN,WAAW,aACX,WAAW,gBACX,WAAW;WAEV,MAAM;YACL,MAAM;cACJ,MAAM;iCACa,qBAAqB,GAAG,KAAK;IAWlD,WAAW,CAoFvB"}

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

@@ -0,0 +1,126 @@
+import { seededRandom_Mulberry32 } from "../../../math/random/seededRandom_Mulberry32.js";
+import { coarsen_graph } from "./coarsen/coarsen_graph.js";
+import { initial_kway_bfs } from "./initial/initial_kway_bfs.js";
+import { initial_kway_recursive_bisection } from "./initial/initial_kway_recursive_bisection.js";
+import { MetisGraph } from "./MetisGraph.js";
+import { compute_kway_params } from "./refine/compute_kway_params.js";
+import { refine_kway } from "./refine/refine_kway.js";
+import { RefinementScratch } from "./refine/RefinementScratch.js";
+
+/**
+ * Pure-JS k-way graph partitioning, drop-in compatible with the existing
+ * `micron_partition(...)` WASM-backed entry point.
+ *
+ * Implements the multilevel pipeline: coarsen → initial partition → uncoarsen
+ * with refinement at every level. Scope matches the subset that meep's
+ * `metis_cluster_bs` actually uses:
+ *   - cut-objective only
+ *   - single balance constraint, all vertex weights = 1
+ *   - uniform target partition weights
+ *   - no minconn / contig / volume / multi-constraint paths
+ *
+ * @param {number} vertex_count
+ * @param {number} partition_count
+ * @param {Uint32Array} edge_addresses CSR row pointers, length vertex_count + 1
+ * @param {Uint32Array} adjacency CSR column indices, length edge_addresses[vertex_count]
+ * @param {Uint32Array} edge_weights parallel to adjacency
+ * @param {{
+ *   seed?: number,
+ *   niter?: number,
+ *   ufactor?: number,
+ *   initial_partition_strategy?: 'recursive_bisection' | 'bfs',
+ * }} [options]
+ *   Only a small slice of `metis_options` is wired; everything else uses METIS
+ *   defaults.
+ *   - `ufactor`: load imbalance factor in METIS units (per-mille over 1.0;
+ *     ufactor = 30 → ub_factor = 1.03). Default 30.
+ *   - `niter`: number of FM passes per level. Default 10.
+ *   - `seed`: RNG seed; same seed + same input ⇒ same partition. Default 0.
+ *   - `initial_partition_strategy`: 'recursive_bisection' (Karypis-Kumar §2.2,
+ *     higher quality) or 'bfs' (simpler, faster initial phase, weaker cut).
+ *     Default 'recursive_bisection'.
+ * @returns {Uint32Array} partition assignment per vertex, values in [0, partition_count)
+ */
+export function metis_partition_kway(
+    vertex_count,
+    partition_count,
+    edge_addresses,
+    adjacency,
+    edge_weights,
+    options
+) {
+    const raw_seed = options?.seed;
+    const seed = (raw_seed === undefined || raw_seed === -1) ? 0 : raw_seed;
+
+    const raw_pass_count = options?.niter;
+    const pass_count = (raw_pass_count === undefined || raw_pass_count === -1) ? 10 : raw_pass_count;
+
+    const raw_ufactor = options?.ufactor;
+    const ufactor = (raw_ufactor === undefined || raw_ufactor === -1) ? 30 : raw_ufactor;
+    const ub_factor = 1 + ufactor / 1000;
+
+    const initial_partition_strategy = options?.initial_partition_strategy ?? 'recursive_bisection';
+
+    const random = seededRandom_Mulberry32(seed);
+
+    if (vertex_count === 0 || partition_count <= 1) {
+        return new Uint32Array(vertex_count);
+    }
+
+    // Copy the input CSR into a MetisGraph with a single shared buffer. We
+    // can't alias the caller's arrays directly because CSRGraph owns one
+    // contiguous buffer and aliasing would split the four arrays across
+    // independent buffers, breaking copy/equals/hash. The copy cost is small
+    // relative to the partitioning work that follows.
+    const original_graph = new MetisGraph(vertex_count, edge_addresses[vertex_count]);
+    original_graph.edge_addresses.set(edge_addresses);
+    original_graph.adjacency.set(adjacency);
+    original_graph.edge_weights.set(edge_weights);
+    // vertex_weights stays at the all-1s default; total_vertex_weight = vertex_count.
+
+    // METIS heuristic for the coarsening floor: stop once we're down to about
+    // 30·k vertices (or vertex_count / (20·log2(k)), whichever is greater).
+    const coarsen_until_vertex_count = Math.max(
+        Math.ceil(vertex_count / (20 * Math.log2(Math.max(2, partition_count)))),
+        30 * partition_count
+    );
+
+    let coarsest_graph;
+    if (vertex_count <= coarsen_until_vertex_count) {
+        // Graph is already small enough; skip multilevel. Refinement still runs
+        // on this single level via the refine_kway driver.
+        coarsest_graph = original_graph;
+    } else {
+        coarsest_graph = coarsen_graph(original_graph, { random, coarsen_until_vertex_count });
+    }
+
+    if (initial_partition_strategy === 'recursive_bisection') {
+        // Recursive bisection leaves `coarsest_graph.vertex_partition` pointing
+        // at a buffer that's now owned by the graph (the BisectionScratch goes
+        // out of scope but the partition buffer survives because the graph
+        // still references it). `allocate_partition_state` preserves the
+        // existing vertex_partition, so we just install the rest of the k-way
+        // state on top.
+        initial_kway_recursive_bisection(coarsest_graph, partition_count, ub_factor, random);
+        coarsest_graph.allocate_partition_state(partition_count);
+    } else {
+        coarsest_graph.allocate_partition_state(partition_count);
+        initial_kway_bfs(coarsest_graph, partition_count, random);
+    }
+
+    compute_kway_params(coarsest_graph, partition_count);
+
+    // Shared scratch for fm_kway across every uncoarsening level. Sized to the
+    // original (finest) graph since that's the largest level we'll process.
+    const refinement_scratch = new RefinementScratch(original_graph.vertex_count, partition_count);
+
+    refine_kway(
+        original_graph,
+        coarsest_graph,
+        partition_count,
+        { random, pass_count, ub_factor },
+        refinement_scratch
+    );
+
+    return original_graph.vertex_partition;
+}

package/src/core/graph/metis/native/refine/IndexedFloatMaxHeap.d.ts

@@ -0,0 +1,62 @@
+export class IndexedFloatMaxHeap {
+    /**
+     * @param {number} id_capacity ids must be in [0, id_capacity)
+     * @param {number} [initial_slot_capacity] initial heap slot count (grows on demand)
+     */
+    constructor(id_capacity: number, initial_slot_capacity?: number);
+    __slot_capacity: number;
+    __size: number;
+    __data_buffer: ArrayBuffer;
+    __data_uint32: Uint32Array;
+    __data_float32: Float32Array;
+    /**
+     * Maps id → slot index in [0, size), or SLOT_NOT_PRESENT.
+     * @type {Uint32Array}
+     */
+    __slot_of_id: Uint32Array;
+    get size(): number;
+    /**
+     * Empty the heap. Only resets the index entries that are actually populated,
+     * so this is O(size), not O(id_capacity).
+     */
+    clear(): void;
+    contains(id: any): boolean;
+    /**
+     * Swap the entries at two slot indices, keeping the id→slot index in sync.
+     * @private
+     */
+    private __swap_slots;
+    /**
+     * Restore heap order downward starting at `start_slot`. Used when an entry's
+     * score has just decreased.
+     * @private
+     */
+    private __sift_down;
+    /**
+     * Restore heap order upward starting at `start_slot`. Used when an entry's
+     * score has just increased.
+     * @private
+     */
+    private __sift_up;
+    __grow_capacity(): void;
+    /**
+     * @param {number} id
+     * @param {number} score
+     */
+    insert(id: number, score: number): void;
+    /**
+     * @returns {number} id of the entry with the largest score, or -1 if empty
+     */
+    pop_max(): number;
+    /**
+     * @param {number} id
+     * @param {number} new_score
+     */
+    update(id: number, new_score: number): void;
+    /**
+     * @param {number} id
+     * @returns {boolean} true if the id was present and removed
+     */
+    remove(id: number): boolean;
+}
+//# sourceMappingURL=IndexedFloatMaxHeap.d.ts.map

package/src/core/graph/metis/native/refine/IndexedFloatMaxHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedFloatMaxHeap.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/IndexedFloatMaxHeap.js"],"names":[],"mappings":"AA6BA;IACI;;;OAGG;IACH,yBAHW,MAAM,0BACN,MAAM,EAsBhB;IAbG,wBAA4C;IAC5C,eAAe;IAEf,2BAA4E;IAC5E,2BAAwD;IACxD,6BAA0D;IAE1D;;;OAGG;IACH,cAFU,WAAW,CAE2B;IAIpD,mBAEC;IAED;;;OAGG;IACH,cAQC;IAED,2BAEC;IAED;;;OAGG;IACH,qBAkBC;IAED;;;;OAIG;IACH,oBAsBC;IAED;;;;OAIG;IACH,kBAYC;IAED,wBAUC;IAED;;;OAGG;IACH,WAHW,MAAM,SACN,MAAM,QAehB;IAED;;OAEG;IACH,WAFa,MAAM,CAuBlB;IAED;;;OAGG;IACH,WAHW,MAAM,aACN,MAAM,QAehB;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CA+BnB;CACJ"}