@optave/codegraph 3.3.1 → 3.4.0

package/dist/graph/algorithms/leiden/modularity.js

@@ -0,0 +1,80 @@
+/**
+ * Modularity quality functions.
+ * Vendored from ngraph.leiden (MIT) — no external dependencies.
+ */
+// Typed array safe-access helper (see adapter.ts for rationale)
+function fget(a, i) {
+    return a[i];
+}
+function iget(a, i) {
+    return a[i];
+}
+export function diffModularity(part, g, v, c, gamma = 1.0) {
+    if (g.directed)
+        return diffModularityDirected(part, g, v, c, gamma);
+    const oldC = iget(part.nodeCommunity, v);
+    if (c === oldC)
+        return 0;
+    const k_v = fget(g.strengthOut, v);
+    const m2 = g.totalWeight;
+    const k_v_in_new = part.getNeighborEdgeWeightToCommunity(c) || 0;
+    const k_v_in_old = part.getNeighborEdgeWeightToCommunity(oldC) || 0;
+    const wTot_new = c < part.communityTotalStrength.length ? fget(part.communityTotalStrength, c) : 0;
+    const wTot_old = fget(part.communityTotalStrength, oldC);
+    const gain_remove = -(k_v_in_old / m2 - (gamma * (k_v * wTot_old)) / (m2 * m2));
+    const gain_add = k_v_in_new / m2 - (gamma * (k_v * wTot_new)) / (m2 * m2);
+    return gain_remove + gain_add;
+}
+export function diffModularityDirected(part, g, v, c, gamma = 1.0) {
+    const oldC = iget(part.nodeCommunity, v);
+    if (c === oldC)
+        return 0;
+    const m = g.totalWeight;
+    const k_out = fget(g.strengthOut, v);
+    const k_in = fget(g.strengthIn, v);
+    const w_new_in = c < g.n ? part.getInEdgeWeightFromCommunity(c) || 0 : 0;
+    const w_new_out = c < g.n ? part.getOutEdgeWeightToCommunity(c) || 0 : 0;
+    const w_old_in = part.getInEdgeWeightFromCommunity(oldC) || 0;
+    const w_old_out = part.getOutEdgeWeightToCommunity(oldC) || 0;
+    const T_new = c < part.communityTotalInStrength.length ? fget(part.communityTotalInStrength, c) : 0;
+    const F_new = c < part.communityTotalOutStrength.length ? fget(part.communityTotalOutStrength, c) : 0;
+    const T_old = fget(part.communityTotalInStrength, oldC);
+    const F_old = fget(part.communityTotalOutStrength, oldC);
+    // Self-loop correction: the self-loop edge (v->v) appears in both
+    // outEdgeWeightToCommunity[oldC] and inEdgeWeightFromCommunity[oldC],
+    // making w_old include 2x selfLoop. Since the self-loop moves with the
+    // node, add it back to match moveNodeToCommunity's directed accounting.
+    const selfW = fget(g.selfLoop, v) || 0;
+    const deltaInternal = (w_new_in + w_new_out - w_old_in - w_old_out + 2 * selfW) / m;
+    // The full delta(F*T) expansion includes a constant 2*k_out*k_in term that
+    // doesn't depend on the target community but does affect the move-vs-stay
+    // decision. Without it, coarse-level merges can appear profitable when
+    // they actually decrease quality.
+    const deltaExpected = (gamma * (k_out * (T_new - T_old) + k_in * (F_new - F_old) + 2 * k_out * k_in)) / (m * m);
+    return deltaInternal - deltaExpected;
+}
+export function qualityModularity(part, g, gamma = 1.0) {
+    const m2 = g.totalWeight;
+    let sum = 0;
+    if (g.directed) {
+        for (let c = 0; c < part.communityCount; c++)
+            sum +=
+                fget(part.communityInternalEdgeWeight, c) / m2 -
+                    (gamma *
+                        (fget(part.communityTotalOutStrength, c) * fget(part.communityTotalInStrength, c))) /
+                        (m2 * m2);
+    }
+    else {
+        // communityInternalEdgeWeight counts each undirected edge once (j > i),
+        // but m2 = totalWeight = 2m (sum of symmetrized degrees). The standard
+        // Newman-Girvan formula is Q = sum_c [2*L_c/(2m) - gamma*(d_c/(2m))^2], so
+        // we multiply lc by 2 to match.
+        for (let c = 0; c < part.communityCount; c++) {
+            const lc = fget(part.communityInternalEdgeWeight, c);
+            const dc = fget(part.communityTotalStrength, c);
+            sum += (2 * lc) / m2 - (gamma * (dc * dc)) / (m2 * m2);
+        }
+    }
+    return sum;
+}
+//# sourceMappingURL=modularity.js.map

package/dist/graph/algorithms/leiden/modularity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modularity.js","sourceRoot":"","sources":["../../../../src/graph/algorithms/leiden/modularity.ts"],"names":[],"mappings":"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"}

package/dist/graph/algorithms/leiden/optimiser.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Core Leiden/Louvain community detection optimiser.
+ * Vendored from ngraph.leiden (MIT) — adapted to use CodeGraph + local RNG.
+ */
+import { CodeGraph } from '../../model.js';
+import type { GraphAdapter, GraphAdapterOptions } from './adapter.js';
+import type { Partition } from './partition.js';
+declare const CandidateStrategy: {
+    readonly Neighbors: 0;
+    readonly All: 1;
+    readonly RandomAny: 2;
+    readonly RandomNeighbor: 3;
+};
+type CandidateStrategyCode = (typeof CandidateStrategy)[keyof typeof CandidateStrategy];
+export interface LeidenOptions {
+    directed?: boolean;
+    randomSeed?: number;
+    maxLevels?: number;
+    maxLocalPasses?: number;
+    allowNewCommunity?: boolean;
+    candidateStrategy?: 'neighbors' | 'all' | 'random' | 'random-neighbor';
+    quality?: string;
+    resolution?: number;
+    refine?: boolean;
+    preserveLabels?: boolean | Map<number, number>;
+    maxCommunitySize?: number;
+    refinementTheta?: number;
+    fixedNodes?: Set<string> | string[];
+    linkWeight?: GraphAdapterOptions['linkWeight'];
+    nodeSize?: GraphAdapterOptions['nodeSize'];
+    baseNodeIds?: string[];
+}
+export interface NormalizedOptions {
+    directed: boolean;
+    randomSeed: number;
+    maxLevels: number;
+    maxLocalPasses: number;
+    allowNewCommunity: boolean;
+    candidateStrategyCode: CandidateStrategyCode;
+    quality: string;
+    resolution: number;
+    refine: boolean;
+    preserveLabels: boolean | Map<number, number> | undefined;
+    maxCommunitySize: number;
+    refinementTheta: number;
+    fixedNodes: Set<string> | string[] | undefined;
+}
+export interface LevelEntry {
+    graph: GraphAdapter;
+    partition: Partition;
+}
+export interface LouvainResult {
+    graph: GraphAdapter;
+    partition: Partition;
+    levels: LevelEntry[];
+    originalToCurrent: Int32Array;
+    originalNodeIds: string[];
+    baseGraph: GraphAdapter;
+}
+export declare function runLouvainUndirectedModularity(graph: CodeGraph, optionsInput?: LeidenOptions): LouvainResult;
+export {};
+//# sourceMappingURL=optimiser.d.ts.map

package/dist/graph/algorithms/leiden/optimiser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimiser.d.ts","sourceRoot":"","sources":["../../../../src/graph/algorithms/leiden/optimiser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAa,YAAY,EAAE,mBAAmB,EAAe,MAAM,cAAc,CAAC;AAI9F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAUhD,QAAA,MAAM,iBAAiB;;;;;CAKb,CAAC;AAEX,KAAK,qBAAqB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAExF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,iBAAiB,CAAC,EAAE,WAAW,GAAG,KAAK,GAAG,QAAQ,GAAG,iBAAiB,CAAC;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,iBAAiB,EAAE,UAAU,CAAC;IAC9B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,SAAS,EAChB,YAAY,GAAE,aAAkB,GAC/B,aAAa,CA0Lf"}

package/dist/graph/algorithms/leiden/optimiser.js

@@ -0,0 +1,498 @@
+/**
+ * Core Leiden/Louvain community detection optimiser.
+ * Vendored from ngraph.leiden (MIT) — adapted to use CodeGraph + local RNG.
+ */
+import { CodeGraph } from '../../model.js';
+import { makeGraphAdapter } from './adapter.js';
+import { diffCPM } from './cpm.js';
+import { diffModularity } from './modularity.js';
+import { makePartition } from './partition.js';
+import { createRng } from './rng.js';
+// Mirrored in DEFAULTS.community (src/infrastructure/config.js) for user override
+// via .codegraphrc.json. Callers (e.g. louvain.ts) can pass overrides through options.
+const DEFAULT_MAX_LEVELS = 50;
+const DEFAULT_MAX_LOCAL_PASSES = 20;
+const GAIN_EPSILON = 1e-12;
+const CandidateStrategy = {
+    Neighbors: 0,
+    All: 1,
+    RandomAny: 2,
+    RandomNeighbor: 3,
+};
+export function runLouvainUndirectedModularity(graph, optionsInput = {}) {
+    const options = normalizeOptions(optionsInput);
+    let currentGraph = graph;
+    const levels = [];
+    const rngSource = createRng(options.randomSeed);
+    const random = () => rngSource.nextDouble();
+    const baseGraphAdapter = makeGraphAdapter(currentGraph, {
+        directed: options.directed,
+        ...optionsInput,
+    });
+    const origN = baseGraphAdapter.n;
+    const originalToCurrent = new Int32Array(origN);
+    for (let i = 0; i < origN; i++)
+        originalToCurrent[i] = i;
+    let fixedNodeMask = null;
+    if (options.fixedNodes) {
+        const fixed = new Uint8Array(origN);
+        const asSet = options.fixedNodes instanceof Set ? options.fixedNodes : new Set(options.fixedNodes);
+        for (const id of asSet) {
+            const idx = baseGraphAdapter.idToIndex.get(String(id));
+            if (idx != null)
+                fixed[idx] = 1;
+        }
+        fixedNodeMask = fixed;
+    }
+    for (let level = 0; level < options.maxLevels; level++) {
+        const graphAdapter = level === 0
+            ? baseGraphAdapter
+            : makeGraphAdapter(currentGraph, { directed: options.directed, ...optionsInput });
+        const partition = makePartition(graphAdapter);
+        partition.graph = graphAdapter;
+        partition.initializeAggregates();
+        const order = new Int32Array(graphAdapter.n);
+        for (let i = 0; i < graphAdapter.n; i++)
+            order[i] = i;
+        let improved = true;
+        let localPasses = 0;
+        const strategyCode = options.candidateStrategyCode;
+        while (improved) {
+            improved = false;
+            localPasses++;
+            shuffleArrayInPlace(order, random);
+            for (let idx = 0; idx < order.length; idx++) {
+                const nodeIndex = order[idx];
+                if (level === 0 && fixedNodeMask && fixedNodeMask[nodeIndex])
+                    continue;
+                const candidateCount = partition.accumulateNeighborCommunityEdgeWeights(nodeIndex);
+                let bestCommunityId = partition.nodeCommunity[nodeIndex];
+                let bestGain = 0;
+                const maxCommunitySize = options.maxCommunitySize;
+                if (strategyCode === CandidateStrategy.All) {
+                    for (let communityId = 0; communityId < partition.communityCount; communityId++) {
+                        if (communityId === partition.nodeCommunity[nodeIndex])
+                            continue;
+                        if (maxCommunitySize < Infinity &&
+                            partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex] >
+                                maxCommunitySize)
+                            continue;
+                        const gain = computeQualityGain(partition, nodeIndex, communityId, options);
+                        if (gain > bestGain) {
+                            bestGain = gain;
+                            bestCommunityId = communityId;
+                        }
+                    }
+                }
+                else if (strategyCode === CandidateStrategy.RandomAny) {
+                    const tries = Math.min(10, Math.max(1, partition.communityCount));
+                    for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
+                        const communityId = (random() * partition.communityCount) | 0;
+                        if (communityId === partition.nodeCommunity[nodeIndex])
+                            continue;
+                        if (maxCommunitySize < Infinity &&
+                            partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex] >
+                                maxCommunitySize)
+                            continue;
+                        const gain = computeQualityGain(partition, nodeIndex, communityId, options);
+                        if (gain > bestGain) {
+                            bestGain = gain;
+                            bestCommunityId = communityId;
+                        }
+                    }
+                }
+                else if (strategyCode === CandidateStrategy.RandomNeighbor) {
+                    const tries = Math.min(10, Math.max(1, candidateCount));
+                    for (let trialIndex = 0; trialIndex < tries; trialIndex++) {
+                        const communityId = partition.getCandidateCommunityAt((random() * candidateCount) | 0);
+                        if (communityId === partition.nodeCommunity[nodeIndex])
+                            continue;
+                        if (maxCommunitySize < Infinity &&
+                            partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex] >
+                                maxCommunitySize)
+                            continue;
+                        const gain = computeQualityGain(partition, nodeIndex, communityId, options);
+                        if (gain > bestGain) {
+                            bestGain = gain;
+                            bestCommunityId = communityId;
+                        }
+                    }
+                }
+                else {
+                    for (let trialIndex = 0; trialIndex < candidateCount; trialIndex++) {
+                        const communityId = partition.getCandidateCommunityAt(trialIndex);
+                        if (maxCommunitySize < Infinity) {
+                            const nextSize = partition.getCommunityTotalSize(communityId) + graphAdapter.size[nodeIndex];
+                            if (nextSize > maxCommunitySize)
+                                continue;
+                        }
+                        const gain = computeQualityGain(partition, nodeIndex, communityId, options);
+                        if (gain > bestGain) {
+                            bestGain = gain;
+                            bestCommunityId = communityId;
+                        }
+                    }
+                }
+                if (options.allowNewCommunity) {
+                    const newCommunityId = partition.communityCount;
+                    const gain = computeQualityGain(partition, nodeIndex, newCommunityId, options);
+                    if (gain > bestGain) {
+                        bestGain = gain;
+                        bestCommunityId = newCommunityId;
+                    }
+                }
+                if (bestCommunityId !== partition.nodeCommunity[nodeIndex] && bestGain > GAIN_EPSILON) {
+                    partition.moveNodeToCommunity(nodeIndex, bestCommunityId);
+                    improved = true;
+                }
+            }
+            if (localPasses >= options.maxLocalPasses)
+                break;
+        }
+        renumberCommunities(partition, options.preserveLabels);
+        let effectivePartition = partition;
+        if (options.refine) {
+            const refined = refineWithinCoarseCommunities(graphAdapter, partition, random, options, level === 0 ? fixedNodeMask : null);
+            // Post-refinement: split any disconnected communities into their
+            // connected components. This is the cheap O(V+E) alternative to
+            // checking gamma-connectedness on every candidate during refinement.
+            // A disconnected community violates even basic connectivity, so
+            // splitting is always correct.
+            splitDisconnectedCommunities(graphAdapter, refined);
+            renumberCommunities(refined, options.preserveLabels);
+            effectivePartition = refined;
+        }
+        levels.push({ graph: graphAdapter, partition: effectivePartition });
+        const fineToCoarse = effectivePartition.nodeCommunity;
+        for (let i = 0; i < originalToCurrent.length; i++) {
+            originalToCurrent[i] = fineToCoarse[originalToCurrent[i]];
+        }
+        // Terminate when no further coarsening is possible. Check both the
+        // move-phase partition (did the greedy phase find merges?) and the
+        // effective partition that feeds buildCoarseGraph (would coarsening
+        // actually reduce the graph?). When refine is enabled the refined
+        // partition starts from singletons and may have more communities than
+        // the move phase found, so checking only effectivePartition would
+        // cause premature termination.
+        if (partition.communityCount === graphAdapter.n &&
+            effectivePartition.communityCount === graphAdapter.n)
+            break;
+        currentGraph = buildCoarseGraph(graphAdapter, effectivePartition);
+    }
+    const last = levels[levels.length - 1];
+    return {
+        graph: last.graph,
+        partition: last.partition,
+        levels,
+        originalToCurrent,
+        originalNodeIds: baseGraphAdapter.nodeIds,
+        baseGraph: baseGraphAdapter,
+    };
+}
+// Build a coarse graph where each community becomes a single node.
+// Self-loops (g.selfLoop[]) don't need separate handling here because they
+// are already present in g.outEdges (directed path keeps them in both arrays).
+// When the coarse graph is fed back to makeGraphAdapter at the next level,
+// the adapter re-detects cu===cu edges as self-loops and populates selfLoop[].
+function buildCoarseGraph(g, p) {
+    const coarse = new CodeGraph({ directed: g.directed });
+    for (let c = 0; c < p.communityCount; c++) {
+        coarse.addNode(String(c), { size: p.communityTotalSize[c] });
+    }
+    const acc = new Map();
+    for (let i = 0; i < g.n; i++) {
+        const cu = p.nodeCommunity[i];
+        const list = g.outEdges[i];
+        for (let k = 0; k < list.length; k++) {
+            const j = list[k].to;
+            const w = list[k].w;
+            const cv = p.nodeCommunity[j];
+            // Undirected: each non-self edge (i,j) appears in both outEdges[i] and
+            // outEdges[j]. For intra-community edges (cu===cv), skip the reverse to
+            // avoid inflating the coarse self-loop weight by 2x.
+            if (!g.directed && cu === cv && j < i)
+                continue;
+            const key = `${cu}:${cv}`;
+            acc.set(key, (acc.get(key) || 0) + w);
+        }
+    }
+    for (const [key, w] of acc.entries()) {
+        const parts = key.split(':');
+        coarse.addEdge(parts[0], parts[1], { weight: w });
+    }
+    return coarse;
+}
+/**
+ * True Leiden refinement phase (Algorithm 3, Traag et al. 2019).
+ *
+ * Key properties that distinguish this from Louvain-style refinement:
+ *
+ * 1. Singleton start — each node begins in its own community.
+ * 2. Singleton guard — only nodes still in singleton communities are
+ *    considered for merging. Once a node joins a non-singleton community
+ *    it is locked for the remainder of the pass. This prevents oscillation
+ *    and is essential for the gamma-connectedness guarantee.
+ * 3. Single pass — one randomized sweep through all nodes, not an
+ *    iterative loop until convergence (that would be Louvain behavior).
+ * 4. Probabilistic selection — candidate communities are sampled from
+ *    a Boltzmann distribution p(v, C) proportional to exp(deltaH / theta),
+ *    with the "stay as singleton" option (deltaH = 0) included in the
+ *    distribution. This means a node may probabilistically choose to remain
+ *    alone even when positive-gain merges exist.
+ *
+ * theta (refinementTheta) controls temperature: lower = more deterministic
+ * (approaches greedy), higher = more exploratory. Determinism is preserved
+ * via the seeded PRNG — same seed produces the same assignments.
+ */
+function refineWithinCoarseCommunities(g, basePart, rng, opts, fixedMask0) {
+    const p = makePartition(g);
+    p.initializeAggregates();
+    p.graph = g;
+    const macro = basePart.nodeCommunity;
+    const commMacro = new Int32Array(p.communityCount);
+    for (let i = 0; i < p.communityCount; i++)
+        commMacro[i] = macro[i];
+    const theta = typeof opts.refinementTheta === 'number' ? opts.refinementTheta : 1.0;
+    if (theta <= 0)
+        throw new RangeError(`refinementTheta must be > 0 (got ${theta})`);
+    // Single pass in random order (Algorithm 3, step 2).
+    const order = new Int32Array(g.n);
+    for (let i = 0; i < g.n; i++)
+        order[i] = i;
+    shuffleArrayInPlace(order, rng);
+    // Pre-allocate flat arrays for candidate collection to avoid per-node GC pressure.
+    // Maximum possible candidates per node is bounded by g.n (community count).
+    const candC = new Int32Array(g.n);
+    const candGain = new Float64Array(g.n);
+    const candWeight = new Float64Array(g.n);
+    for (let idx = 0; idx < order.length; idx++) {
+        const v = order[idx];
+        if (fixedMask0?.[v])
+            continue;
+        // Singleton guard: only move nodes still alone in their community.
+        if (p.getCommunityNodeCount(p.nodeCommunity[v]) > 1)
+            continue;
+        const macroV = macro[v];
+        const touchedCount = p.accumulateNeighborCommunityEdgeWeights(v);
+        const maxSize = Number.isFinite(opts.maxCommunitySize)
+            ? opts.maxCommunitySize
+            : Infinity;
+        // Collect eligible communities and their quality gains.
+        let candLen = 0;
+        for (let t = 0; t < touchedCount; t++) {
+            const c = p.getCandidateCommunityAt(t);
+            if (c === p.nodeCommunity[v])
+                continue;
+            if (commMacro[c] !== macroV)
+                continue;
+            if (maxSize < Infinity) {
+                const nextSize = p.getCommunityTotalSize(c) + g.size[v];
+                if (nextSize > maxSize)
+                    continue;
+            }
+            const gain = computeQualityGain(p, v, c, opts);
+            if (gain > GAIN_EPSILON) {
+                candC[candLen] = c;
+                candGain[candLen] = gain;
+                candLen++;
+            }
+        }
+        if (candLen === 0)
+            continue;
+        // Probabilistic selection: p(v, C) proportional to exp(deltaH / theta),
+        // with the "stay" option (deltaH = 0) included per Algorithm 3.
+        // For numerical stability, subtract the max gain before exponentiation.
+        let maxGain = 0;
+        for (let i = 0; i < candLen; i++) {
+            if (candGain[i] > maxGain)
+                maxGain = candGain[i];
+        }
+        // "Stay as singleton" weight: exp((0 - maxGain) / theta)
+        const stayWeight = Math.exp((0 - maxGain) / theta);
+        let totalWeight = stayWeight;
+        for (let i = 0; i < candLen; i++) {
+            candWeight[i] = Math.exp((candGain[i] - maxGain) / theta);
+            totalWeight += candWeight[i];
+        }
+        const r = rng() * totalWeight;
+        if (r < stayWeight)
+            continue; // node stays as singleton
+        let cumulative = stayWeight;
+        let chosenC = candC[candLen - 1]; // fallback
+        for (let i = 0; i < candLen; i++) {
+            cumulative += candWeight[i];
+            if (r < cumulative) {
+                chosenC = candC[i];
+                break;
+            }
+        }
+        p.moveNodeToCommunity(v, chosenC);
+    }
+    return p;
+}
+/**
+ * Post-refinement connectivity check. For each community, run a BFS on
+ * the subgraph induced by its members (using the adapter's outEdges).
+ * If a community has multiple connected components, assign secondary
+ * components to new community IDs, then reinitialize aggregates once.
+ *
+ * O(V+E) total since communities partition V.
+ *
+ * This replaces the per-candidate gamma-connectedness check from the paper
+ * with a cheaper post-step that catches the most important violation
+ * (disconnected subcommunities).
+ */
+function splitDisconnectedCommunities(g, partition) {
+    const n = g.n;
+    const nc = partition.nodeCommunity;
+    const members = partition.getCommunityMembers();
+    let nextC = partition.communityCount;
+    let didSplit = false;
+    const visited = new Uint8Array(n);
+    const inCommunity = new Uint8Array(n);
+    for (let c = 0; c < members.length; c++) {
+        const nodes = members[c];
+        if (nodes.length <= 1)
+            continue;
+        for (let i = 0; i < nodes.length; i++)
+            inCommunity[nodes[i]] = 1;
+        let componentCount = 0;
+        for (let i = 0; i < nodes.length; i++) {
+            const start = nodes[i];
+            if (visited[start])
+                continue;
+            componentCount++;
+            // BFS within the community subgraph.
+            // For directed graphs, traverse both outEdges and inEdges to check
+            // weak connectivity (reachability ignoring edge direction).
+            const queue = [start];
+            visited[start] = 1;
+            let head = 0;
+            while (head < queue.length) {
+                const v = queue[head++];
+                const out = g.outEdges[v];
+                for (let k = 0; k < out.length; k++) {
+                    const w = out[k].to;
+                    if (inCommunity[w] && !visited[w]) {
+                        visited[w] = 1;
+                        queue.push(w);
+                    }
+                }
+                if (g.directed) {
+                    const inc = g.inEdges[v];
+                    for (let k = 0; k < inc.length; k++) {
+                        const w = inc[k].from;
+                        if (inCommunity[w] && !visited[w]) {
+                            visited[w] = 1;
+                            queue.push(w);
+                        }
+                    }
+                }
+            }
+            if (componentCount > 1) {
+                // Secondary component — assign new community ID directly.
+                const newC = nextC++;
+                for (let q = 0; q < queue.length; q++)
+                    nc[queue[q]] = newC;
+                didSplit = true;
+            }
+        }
+        for (let i = 0; i < nodes.length; i++) {
+            inCommunity[nodes[i]] = 0;
+            visited[nodes[i]] = 0;
+        }
+    }
+    if (didSplit) {
+        // Grow the partition's typed arrays to accommodate new community IDs,
+        // then recompute all aggregates from the updated nodeCommunity array.
+        partition.resizeCommunities(nextC);
+        partition.initializeAggregates();
+    }
+}
+function computeQualityGain(partition, v, c, opts) {
+    if (!partition.graph) {
+        throw new Error('partition.graph must be set before computeQualityGain');
+    }
+    const quality = (opts.quality || 'modularity').toLowerCase();
+    const gamma = typeof opts.resolution === 'number' ? opts.resolution : 1.0;
+    if (quality === 'cpm') {
+        return diffCPM(partition, partition.graph, v, c, gamma);
+    }
+    // diffModularity dispatches to diffModularityDirected internally when g.directed is true
+    return diffModularity(partition, partition.graph, v, c, gamma);
+}
+function shuffleArrayInPlace(arr, rng = Math.random) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        const t = arr[i];
+        arr[i] = arr[j];
+        arr[j] = t;
+    }
+    return arr;
+}
+function resolveCandidateStrategy(options) {
+    const val = options.candidateStrategy;
+    if (typeof val !== 'string')
+        return CandidateStrategy.Neighbors;
+    switch (val) {
+        case 'neighbors':
+            return CandidateStrategy.Neighbors;
+        case 'all':
+            return CandidateStrategy.All;
+        case 'random':
+            return CandidateStrategy.RandomAny;
+        case 'random-neighbor':
+            return CandidateStrategy.RandomNeighbor;
+        default:
+            return CandidateStrategy.Neighbors;
+    }
+}
+function normalizeOptions(options = {}) {
+    const directed = !!options.directed;
+    const randomSeed = Number.isFinite(options.randomSeed)
+        ? options.randomSeed
+        : 42;
+    const maxLevels = Number.isFinite(options.maxLevels)
+        ? options.maxLevels
+        : DEFAULT_MAX_LEVELS;
+    const maxLocalPasses = Number.isFinite(options.maxLocalPasses)
+        ? options.maxLocalPasses
+        : DEFAULT_MAX_LOCAL_PASSES;
+    const allowNewCommunity = !!options.allowNewCommunity;
+    const candidateStrategyCode = resolveCandidateStrategy(options);
+    const quality = (options.quality || 'modularity').toLowerCase();
+    const resolution = typeof options.resolution === 'number' ? options.resolution : 1.0;
+    const refine = options.refine !== false;
+    const preserveLabels = options.preserveLabels;
+    const maxCommunitySize = Number.isFinite(options.maxCommunitySize)
+        ? options.maxCommunitySize
+        : Infinity;
+    const refinementTheta = typeof options.refinementTheta === 'number' ? options.refinementTheta : 1.0;
+    return {
+        directed,
+        randomSeed,
+        maxLevels,
+        maxLocalPasses,
+        allowNewCommunity,
+        candidateStrategyCode,
+        quality,
+        resolution,
+        refine,
+        preserveLabels,
+        maxCommunitySize,
+        refinementTheta,
+        fixedNodes: options.fixedNodes,
+    };
+}
+function renumberCommunities(partition, preserveLabels) {
+    if (preserveLabels && preserveLabels instanceof Map) {
+        partition.compactCommunityIds({ preserveMap: preserveLabels });
+    }
+    else if (preserveLabels === true) {
+        partition.compactCommunityIds({ keepOldOrder: true });
+    }
+    else {
+        partition.compactCommunityIds();
+    }
+}
+//# sourceMappingURL=optimiser.js.map