import { Graph } from '../graph/graph';
import { Community } from '../types/clustering-types';
import { Edge, Node } from '../types/graph';
import { WeightFunction } from '../types/weight-function';
/**
 * Result of Louvain community detection including performance statistics.
 */
export interface LouvainResult<N extends Node> {
    /** Detected communities */
    communities: Community<N>[];
    /** Performance and convergence statistics */
    stats: {
        /** Total iterations across all hierarchy levels */
        totalIterations: number;
        /** Number of hierarchy levels processed */
        hierarchyLevels: number;
        /** Runtime in milliseconds */
        runtimeMs: number;
    };
}
/**
 * Get adaptive convergence threshold based on graph size.
 * @param nodeCount - Number of nodes in graph
 * @returns Convergence threshold (1e-5 for large graphs, 1e-6 for small graphs)
 * @remarks
 * Large graphs (>500 nodes) use looser threshold for faster convergence.
 * Small graphs (≤500 nodes) use stricter threshold for higher quality.
 */
export declare const getAdaptiveThreshold: (nodeCount: number) => number;
/**
 * Get adaptive iteration limit based on graph size and hierarchy level.
 * @param nodeCount - Number of nodes in graph
 * @param level - Hierarchy level (0 = first level)
 * @returns Maximum iterations (20, 40, or 50)
 * @remarks
 * First hierarchy level (level 0) with large graphs (>200 nodes) uses lower limit (20)
 * because most node movements happen in the first iteration.
 * Subsequent levels and small graphs use higher limits (40-50) for refinement.
 */
export declare const getAdaptiveIterationLimit: (nodeCount: number, level: number) => number;
/**
 * Determine optimal neighbor selection mode based on graph size.
 * @param nodeCount - Number of nodes in graph
 * @returns Neighbor selection mode ("best" or "random")
 * @remarks
 * **UPDATE (Phase 4 debugging)**: Random mode disabled for citation networks.
 *
 * Testing revealed Fast Louvain random-neighbor selection causes severe quality degradation
 * for citation network graphs (Q=0.05-0.12 vs Q=0.37 with best mode), failing the minimum
 * quality threshold of Q≥0.19. Random mode also paradoxically SLOWED convergence (201 iterations
 * vs 103 with best mode), resulting in 3x slower runtime.
 *
 * Root cause: Citation networks have different structural properties than the social/web networks
 * where Fast Louvain was benchmarked in literature. Accepting first positive ΔQ leads to poor-quality
 * moves that require many iterations to correct.
 *
 * **Current strategy**: Always use best-neighbor mode for quality. Random mode remains available
 * via explicit `mode: "random"` parameter for experimentation but is not recommended.
 */
export declare const determineOptimalMode: () => "best" | "random";
/**
 * Shuffle an array in-place using Fisher-Yates algorithm.
 * @param array - Array to shuffle (modified in-place)
 * @param seed - Optional random seed for deterministic shuffling (for tests)
 * @returns The shuffled array (same reference as input)
 * @remarks
 * Fisher-Yates shuffle guarantees uniform distribution of permutations.
 * If seed is provided, uses simple linear congruential generator (LCG) for PRNG.
 * If seed is undefined, uses Math.random() (non-deterministic).
 *
 * LCG parameters: a=1664525, c=1013904223, m=2^32 (Numerical Recipes)
 */
export declare const shuffle: <T>(array: T[], seed?: number) => T[];
/**
 * Detect communities using the Louvain algorithm.
 *
 * The Louvain method is a greedy optimization method that attempts to optimize
 * the modularity of a partition of the network.
 * @template N - Node type
 * @template E - Edge type
 * @param graph - Input graph (directed or undirected)
 * @param options - Optional configuration (combines legacy and optimization parameters)
 * @param options.weightFn - Weight function for edges (default: all edges weight 1.0) [Legacy]
 * @param options.resolution - Resolution parameter (default: 1.0, higher values favor more communities) [Legacy]
 * @param options.mode - Neighbor selection strategy ("auto", "best", "random") [spec-027 Phase 2]
 * @param options.seed - Random seed for deterministic shuffling [spec-027 Phase 2]
 * @param options.minModularityIncrease - Minimum modularity improvement to continue (adaptive default via getAdaptiveThreshold)
 * @param options.maxIterations - Maximum iterations per phase (adaptive default via getAdaptiveIterationLimit)
 * @returns Array of detected communities
 * @remarks
 * **Adaptive Defaults** (spec-027 Phase 1):
 * - `minModularityIncrease`: 1e-5 for >500 nodes, 1e-6 otherwise
 * - `maxIterations`: 20 for >200 nodes (level 0), 40-50 otherwise
 *
 * **Neighbor Selection Modes** (spec-027 Phase 2):
 * - `"auto"`: Best-neighbor for <200 nodes, random for ≥500 nodes
 * - `"best"`: Always use best-neighbor (quality-first)
 * - `"random"`: Always use random-neighbor (speed-first, Fast Louvain)
 * @example
 * ```typescript
 * const graph = new Graph<PaperNode, CitationEdge>(true);
 * // ... add nodes and edges ...
 *
 * // Basic usage (adaptive defaults)
 * const { communities, stats } = detectCommunities(graph);
 * console.log(`Found ${communities.length} communities in ${stats.totalIterations} iterations`);
 *
 * // Quality-first mode
 * const result = detectCommunities(graph, { mode: "best" });
 *
 * // Speed-first mode for large graphs
 * const fast = detectCommunities(graph, { mode: "random", maxIterations: 10 });
 *
 * // Reproducible results
 * const deterministic = detectCommunities(graph, { seed: 42 });
 * ```
 */
export declare const detectCommunities: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
    weightFn?: WeightFunction<N, E>;
    resolution?: number;
    mode?: "auto" | "best" | "random";
    seed?: number;
    minModularityIncrease?: number;
    maxIterations?: number;
}) => LouvainResult<N>;
//# sourceMappingURL=louvain.d.ts.map