graphwise 1.7.0 → 1.8.1

package/dist/ranking-riRrEVAR.cjs

@@ -0,0 +1,1093 @@
+const require_jaccard = require("./jaccard-Bmd1IEFO.cjs");
+//#region src/ranking/parse.ts
+/**
+* Rank paths using PARSE (Path-Aware Ranking via Salience Estimation).
+*
+* Computes geometric mean of edge MI scores for each path,
+* then sorts by salience (highest first).
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths with statistics
+*/
+function parse(graph, paths, config) {
+	const startTime = performance.now();
+	const { mi = require_jaccard.jaccard, epsilon = 1e-10 } = config ?? {};
+	const rankedPaths = [];
+	for (const path of paths) {
+		const salience = computePathSalience(graph, path, mi, epsilon);
+		rankedPaths.push({
+			...path,
+			salience
+		});
+	}
+	rankedPaths.sort((a, b) => b.salience - a.salience);
+	const endTime = performance.now();
+	const saliences = rankedPaths.map((p) => p.salience);
+	const meanSalience = saliences.length > 0 ? saliences.reduce((a, b) => a + b, 0) / saliences.length : 0;
+	const sortedSaliences = [...saliences].sort((a, b) => a - b);
+	const mid = Math.floor(sortedSaliences.length / 2);
+	const medianSalience = sortedSaliences.length > 0 ? sortedSaliences.length % 2 !== 0 ? sortedSaliences[mid] ?? 0 : ((sortedSaliences[mid - 1] ?? 0) + (sortedSaliences[mid] ?? 0)) / 2 : 0;
+	const maxSalience = sortedSaliences.length > 0 ? sortedSaliences[sortedSaliences.length - 1] ?? 0 : 0;
+	const minSalience = sortedSaliences.length > 0 ? sortedSaliences[0] ?? 0 : 0;
+	return {
+		paths: rankedPaths,
+		stats: {
+			pathsRanked: rankedPaths.length,
+			meanSalience,
+			medianSalience,
+			maxSalience,
+			minSalience,
+			durationMs: endTime - startTime
+		}
+	};
+}
+/**
+* Rank paths using async PARSE (Path-Aware Ranking via Salience Estimation).
+*
+* Async variant suitable for use with remote or lazy graph data sources.
+* Computes geometric mean of edge MI scores for each path using Promise.all
+* for parallelism, then sorts by salience (highest first).
+*
+* @param graph - Async source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths with statistics
+*/
+async function parseAsync(graph, paths, config) {
+	const startTime = performance.now();
+	const { mi = require_jaccard.jaccardAsync, epsilon = 1e-10 } = config ?? {};
+	const rankedPaths = [];
+	for (const path of paths) {
+		const salience = await computePathSalienceAsync(graph, path, mi, epsilon);
+		rankedPaths.push({
+			...path,
+			salience
+		});
+	}
+	rankedPaths.sort((a, b) => b.salience - a.salience);
+	const endTime = performance.now();
+	const saliences = rankedPaths.map((p) => p.salience);
+	const meanSalience = saliences.length > 0 ? saliences.reduce((a, b) => a + b, 0) / saliences.length : 0;
+	const sortedSaliences = [...saliences].sort((a, b) => a - b);
+	const mid = Math.floor(sortedSaliences.length / 2);
+	const medianSalience = sortedSaliences.length > 0 ? sortedSaliences.length % 2 !== 0 ? sortedSaliences[mid] ?? 0 : ((sortedSaliences[mid - 1] ?? 0) + (sortedSaliences[mid] ?? 0)) / 2 : 0;
+	const maxSalience = sortedSaliences.length > 0 ? sortedSaliences[sortedSaliences.length - 1] ?? 0 : 0;
+	const minSalience = sortedSaliences.length > 0 ? sortedSaliences[0] ?? 0 : 0;
+	return {
+		paths: rankedPaths,
+		stats: {
+			pathsRanked: rankedPaths.length,
+			meanSalience,
+			medianSalience,
+			maxSalience,
+			minSalience,
+			durationMs: endTime - startTime
+		}
+	};
+}
+/**
+* Compute salience for a single path asynchronously.
+*
+* Uses geometric mean of edge MI scores for length-unbiased ranking.
+* Edge MI values are computed in parallel via Promise.all.
+*/
+async function computePathSalienceAsync(graph, path, mi, epsilon) {
+	const nodes = path.nodes;
+	if (nodes.length < 2) return epsilon;
+	const edgeMIs = await Promise.all(nodes.slice(0, -1).map((source, i) => {
+		const target = nodes[i + 1];
+		if (target !== void 0) return mi(graph, source, target);
+		return Promise.resolve(epsilon);
+	}));
+	let productMi = 1;
+	let edgeCount = 0;
+	for (const edgeMi of edgeMIs) {
+		productMi *= Math.max(epsilon, edgeMi);
+		edgeCount++;
+	}
+	if (edgeCount === 0) return epsilon;
+	const salience = Math.pow(productMi, 1 / edgeCount);
+	return Math.max(epsilon, Math.min(1, salience));
+}
+/**
+* Compute salience for a single path.
+*
+* Uses geometric mean of edge MI scores for length-unbiased ranking.
+*/
+function computePathSalience(graph, path, mi, epsilon) {
+	const nodes = path.nodes;
+	if (nodes.length < 2) return epsilon;
+	let productMi = 1;
+	let edgeCount = 0;
+	for (let i = 0; i < nodes.length - 1; i++) {
+		const source = nodes[i];
+		const target = nodes[i + 1];
+		if (source !== void 0 && target !== void 0) {
+			const edgeMi = mi(graph, source, target);
+			productMi *= Math.max(epsilon, edgeMi);
+			edgeCount++;
+		}
+	}
+	if (edgeCount === 0) return epsilon;
+	const salience = Math.pow(productMi, 1 / edgeCount);
+	return Math.max(epsilon, Math.min(1, salience));
+}
+//#endregion
+//#region src/ranking/baselines/utils.ts
+/**
+* Normalise a set of scored paths and return them sorted highest-first.
+*
+* All scores are normalised relative to the maximum observed score.
+* When `includeScores` is false, raw (un-normalised) scores are preserved.
+* Handles degenerate cases: empty input and all-zero scores.
+*
+* @param paths - Original paths in input order
+* @param scored - Paths paired with their computed scores
+* @param method - Method name to embed in the result
+* @param includeScores - When true, normalise scores to [0, 1]; when false, keep raw scores
+* @returns BaselineResult with ranked paths
+*/
+function normaliseAndRank(paths, scored, method, includeScores) {
+	if (scored.length === 0) return {
+		paths: [],
+		method
+	};
+	const maxScore = Math.max(...scored.map((s) => s.score));
+	if (maxScore === 0) return {
+		paths: paths.map((path) => ({
+			...path,
+			score: 0
+		})),
+		method
+	};
+	return {
+		paths: scored.map(({ path, score }) => ({
+			...path,
+			score: includeScores ? score / maxScore : score
+		})).sort((a, b) => b.score - a.score),
+		method
+	};
+}
+//#endregion
+//#region src/ranking/baselines/shortest.ts
+/**
+* Rank paths by length (shortest first).
+*
+* Score = 1 / path_length, normalised to [0, 1].
+*
+* @param _graph - Source graph (unused for length ranking)
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (shortest first)
+*/
+function shortest(_graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "shortest"
+	};
+	return normaliseAndRank(paths, paths.map((path) => ({
+		path,
+		score: 1 / path.nodes.length
+	})), "shortest", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/degree-sum.ts
+/**
+* Rank paths by sum of node degrees.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest degree-sum first)
+*/
+function degreeSum(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "degree-sum"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		let degreeSum = 0;
+		for (const nodeId of path.nodes) degreeSum += graph.degree(nodeId);
+		return {
+			path,
+			score: degreeSum
+		};
+	}), "degree-sum", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/widest-path.ts
+/**
+* Rank paths by widest bottleneck (minimum edge similarity).
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest bottleneck first)
+*/
+function widestPath(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "widest-path"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		if (path.nodes.length < 2) return {
+			path,
+			score: 1
+		};
+		let minSimilarity = Number.POSITIVE_INFINITY;
+		for (let i = 0; i < path.nodes.length - 1; i++) {
+			const source = path.nodes[i];
+			const target = path.nodes[i + 1];
+			if (source === void 0 || target === void 0) continue;
+			const edgeSimilarity = require_jaccard.jaccard(graph, source, target);
+			minSimilarity = Math.min(minSimilarity, edgeSimilarity);
+		}
+		return {
+			path,
+			score: minSimilarity === Number.POSITIVE_INFINITY ? 1 : minSimilarity
+		};
+	}), "widest-path", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/jaccard-arithmetic.ts
+/**
+* Rank paths by arithmetic mean of edge Jaccard similarities.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest arithmetic mean first)
+*/
+function jaccardArithmetic(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "jaccard-arithmetic"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		if (path.nodes.length < 2) return {
+			path,
+			score: 1
+		};
+		let similaritySum = 0;
+		let edgeCount = 0;
+		for (let i = 0; i < path.nodes.length - 1; i++) {
+			const source = path.nodes[i];
+			const target = path.nodes[i + 1];
+			if (source === void 0 || target === void 0) continue;
+			const edgeSimilarity = require_jaccard.jaccard(graph, source, target);
+			similaritySum += edgeSimilarity;
+			edgeCount++;
+		}
+		return {
+			path,
+			score: edgeCount > 0 ? similaritySum / edgeCount : 1
+		};
+	}), "jaccard-arithmetic", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/pagerank.ts
+/**
+* Compute PageRank centrality for all nodes using power iteration.
+*
+* @param graph - Source graph
+* @param damping - Damping factor (default 0.85)
+* @param tolerance - Convergence tolerance (default 1e-6)
+* @param maxIterations - Maximum iterations (default 100)
+* @returns Map of node ID to PageRank value
+*/
+function computePageRank(graph, damping = .85, tolerance = 1e-6, maxIterations = 100) {
+	const nodes = Array.from(graph.nodeIds());
+	const n = nodes.length;
+	if (n === 0) return /* @__PURE__ */ new Map();
+	const ranks = /* @__PURE__ */ new Map();
+	const newRanks = /* @__PURE__ */ new Map();
+	for (const nodeId of nodes) {
+		ranks.set(nodeId, 1 / n);
+		newRanks.set(nodeId, 0);
+	}
+	let isCurrentRanks = true;
+	for (let iteration = 0; iteration < maxIterations; iteration++) {
+		let maxChange = 0;
+		const currMap = isCurrentRanks ? ranks : newRanks;
+		const nextMap = isCurrentRanks ? newRanks : ranks;
+		for (const nodeId of nodes) {
+			let incomingSum = 0;
+			for (const incomingId of graph.neighbours(nodeId, "in")) {
+				const incomingRank = currMap.get(incomingId) ?? 0;
+				const outDegree = graph.degree(incomingId);
+				if (outDegree > 0) incomingSum += incomingRank / outDegree;
+			}
+			const newRank = (1 - damping) / n + damping * incomingSum;
+			nextMap.set(nodeId, newRank);
+			const oldRank = currMap.get(nodeId) ?? 0;
+			maxChange = Math.max(maxChange, Math.abs(newRank - oldRank));
+		}
+		if (maxChange < tolerance) break;
+		isCurrentRanks = !isCurrentRanks;
+		currMap.clear();
+	}
+	return isCurrentRanks ? ranks : newRanks;
+}
+/**
+* Rank paths by sum of PageRank scores.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest PageRank sum first)
+*/
+function pagerank(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "pagerank"
+	};
+	const ranks = computePageRank(graph);
+	return normaliseAndRank(paths, paths.map((path) => {
+		let prSum = 0;
+		for (const nodeId of path.nodes) prSum += ranks.get(nodeId) ?? 0;
+		return {
+			path,
+			score: prSum
+		};
+	}), "pagerank", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/betweenness.ts
+/**
+* Compute betweenness centrality for all nodes using Brandes algorithm.
+*
+* @param graph - Source graph
+* @returns Map of node ID to betweenness value
+*/
+function computeBetweenness(graph) {
+	const nodes = Array.from(graph.nodeIds());
+	const betweenness = /* @__PURE__ */ new Map();
+	for (const nodeId of nodes) betweenness.set(nodeId, 0);
+	for (const source of nodes) {
+		const predecessors = /* @__PURE__ */ new Map();
+		const distance = /* @__PURE__ */ new Map();
+		const sigma = /* @__PURE__ */ new Map();
+		const queue = [];
+		for (const nodeId of nodes) {
+			predecessors.set(nodeId, []);
+			distance.set(nodeId, -1);
+			sigma.set(nodeId, 0);
+		}
+		distance.set(source, 0);
+		sigma.set(source, 1);
+		queue.push(source);
+		for (const v of queue) {
+			const vDist = distance.get(v) ?? -1;
+			const neighbours = graph.neighbours(v);
+			for (const w of neighbours) {
+				const wDist = distance.get(w) ?? -1;
+				if (wDist < 0) {
+					distance.set(w, vDist + 1);
+					queue.push(w);
+				}
+				if (wDist === vDist + 1) {
+					const wSigma = sigma.get(w) ?? 0;
+					const vSigma = sigma.get(v) ?? 0;
+					sigma.set(w, wSigma + vSigma);
+					const wPred = predecessors.get(w) ?? [];
+					wPred.push(v);
+					predecessors.set(w, wPred);
+				}
+			}
+		}
+		const delta = /* @__PURE__ */ new Map();
+		for (const nodeId of nodes) delta.set(nodeId, 0);
+		const sorted = [...nodes].sort((a, b) => {
+			const aD = distance.get(a) ?? -1;
+			return (distance.get(b) ?? -1) - aD;
+		});
+		for (const w of sorted) {
+			if (w === source) continue;
+			const wDelta = delta.get(w) ?? 0;
+			const wSigma = sigma.get(w) ?? 0;
+			const wPred = predecessors.get(w) ?? [];
+			for (const v of wPred) {
+				const vSigma = sigma.get(v) ?? 0;
+				const vDelta = delta.get(v) ?? 0;
+				if (wSigma > 0) delta.set(v, vDelta + vSigma / wSigma * (1 + wDelta));
+			}
+			if (w !== source) {
+				const current = betweenness.get(w) ?? 0;
+				betweenness.set(w, current + wDelta);
+			}
+		}
+	}
+	return betweenness;
+}
+/**
+* Rank paths by sum of betweenness scores.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest betweenness sum first)
+*/
+function betweenness(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "betweenness"
+	};
+	const bcMap = computeBetweenness(graph);
+	return normaliseAndRank(paths, paths.map((path) => {
+		let bcSum = 0;
+		for (const nodeId of path.nodes) bcSum += bcMap.get(nodeId) ?? 0;
+		return {
+			path,
+			score: bcSum
+		};
+	}), "betweenness", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/katz.ts
+/**
+* Compute truncated Katz centrality between two nodes.
+*
+* Uses iterative matrix-vector products to avoid full matrix powers.
+* score(s,t) = sum_{k=1}^{K} beta^k * walks_k(s,t)
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param k - Truncation depth (default 5)
+* @param beta - Attenuation factor (default 0.005)
+* @returns Katz score
+*/
+function computeKatz(graph, source, target, k = 5, beta = .005) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0) return 0;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	let walks = new Float64Array(n);
+	walks[targetIdx] = 1;
+	let katzScore = 0;
+	for (let depth = 1; depth <= k; depth++) {
+		const walksNext = new Float64Array(n);
+		for (const sourceNode of nodes) {
+			const srcIdx = nodeToIdx.get(sourceNode);
+			if (srcIdx === void 0) continue;
+			const neighbours = graph.neighbours(sourceNode);
+			for (const neighbourId of neighbours) {
+				const nIdx = nodeToIdx.get(neighbourId);
+				if (nIdx === void 0) continue;
+				walksNext[srcIdx] = (walksNext[srcIdx] ?? 0) + (walks[nIdx] ?? 0);
+			}
+		}
+		const walkCount = walksNext[sourceIdx] ?? 0;
+		katzScore += Math.pow(beta, depth) * walkCount;
+		walks = walksNext;
+	}
+	return katzScore;
+}
+/**
+* Rank paths by Katz centrality between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest Katz score first)
+*/
+function katz(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "katz"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		return {
+			path,
+			score: computeKatz(graph, source, target)
+		};
+	}), "katz", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/communicability.ts
+/**
+* Compute truncated communicability between two nodes.
+*
+* Uses Taylor series expansion: (e^A)_{s,t} ≈ sum_{k=0}^{K} A^k_{s,t} / k!
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param k - Truncation depth (default 15)
+* @returns Communicability score
+*/
+function computeCommunicability(graph, source, target, k = 15) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0) return 0;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	let walks = new Float64Array(n);
+	walks[targetIdx] = 1;
+	let commScore = walks[sourceIdx] ?? 0;
+	let factorial = 1;
+	for (let depth = 1; depth <= k; depth++) {
+		const walksNext = new Float64Array(n);
+		for (const fromNode of nodes) {
+			const fromIdx = nodeToIdx.get(fromNode);
+			if (fromIdx === void 0) continue;
+			const neighbours = graph.neighbours(fromNode);
+			for (const toNodeId of neighbours) {
+				const toIdx = nodeToIdx.get(toNodeId);
+				if (toIdx === void 0) continue;
+				walksNext[fromIdx] = (walksNext[fromIdx] ?? 0) + (walks[toIdx] ?? 0);
+			}
+		}
+		factorial *= depth;
+		commScore += (walksNext[sourceIdx] ?? 0) / factorial;
+		walks = walksNext;
+	}
+	return commScore;
+}
+/**
+* Rank paths by communicability between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest communicability first)
+*/
+function communicability(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "communicability"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		return {
+			path,
+			score: computeCommunicability(graph, source, target)
+		};
+	}), "communicability", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/resistance-distance.ts
+/**
+* Compute effective resistance between two nodes via Laplacian pseudoinverse.
+*
+* Resistance = L^+_{s,s} + L^+_{t,t} - 2*L^+_{s,t}
+* where L^+ is the pseudoinverse of the Laplacian matrix.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @returns Effective resistance
+*/
+function computeResistance(graph, source, target) {
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	if (n === 0 || n > 5e3) throw new Error(`Cannot compute resistance distance: graph too large (${String(n)} nodes). Maximum 5000.`);
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	const L = Array.from({ length: n }, () => Array.from({ length: n }, () => 0));
+	for (let i = 0; i < n; i++) {
+		const nodeId = nodes[i];
+		if (nodeId === void 0) continue;
+		const degree = graph.degree(nodeId);
+		const row = L[i];
+		if (row !== void 0) row[i] = degree;
+		const neighbours = graph.neighbours(nodeId);
+		for (const neighbourId of neighbours) {
+			const j = nodeToIdx.get(neighbourId);
+			if (j !== void 0 && row !== void 0) row[j] = -1;
+		}
+	}
+	const Lpinv = pinv(L);
+	const resistance = (Lpinv[sourceIdx]?.[sourceIdx] ?? 0) + (Lpinv[targetIdx]?.[targetIdx] ?? 0) - 2 * (Lpinv[sourceIdx]?.[targetIdx] ?? 0);
+	return Math.max(resistance, 1e-10);
+}
+/**
+* Compute Moore-Penrose pseudoinverse of a matrix.
+* Simplified implementation for small dense matrices.
+*
+* @param A - Square matrix
+* @returns Pseudoinverse A^+
+*/
+function pinv(A) {
+	const n = A.length;
+	if (n === 0) return [];
+	const M = A.map((row) => [...row]);
+	const epsilon = 1e-10;
+	for (let i = 0; i < n; i++) {
+		const row = M[i];
+		if (row !== void 0) row[i] = (row[i] ?? 0) + epsilon;
+	}
+	return gaussianInverse(M);
+}
+/**
+* Compute matrix inverse using Gaussian elimination with partial pivoting.
+*
+* @param A - Matrix to invert
+* @returns Inverted matrix
+*/
+function gaussianInverse(A) {
+	const n = A.length;
+	const aug = A.map((row, i) => {
+		const identity = Array.from({ length: n }, (_, j) => i === j ? 1 : 0);
+		return [...row, ...identity];
+	});
+	for (let col = 0; col < n; col++) {
+		let maxRow = col;
+		for (let row = col + 1; row < n; row++) {
+			const currentRow = aug[row];
+			const maxRowRef = aug[maxRow];
+			if (currentRow !== void 0 && maxRowRef !== void 0 && Math.abs(currentRow[col] ?? 0) > Math.abs(maxRowRef[col] ?? 0)) maxRow = row;
+		}
+		const currentCol = aug[col];
+		const maxRowAug = aug[maxRow];
+		if (currentCol !== void 0 && maxRowAug !== void 0) {
+			aug[col] = maxRowAug;
+			aug[maxRow] = currentCol;
+		}
+		const pivotRow = aug[col];
+		const pivot = pivotRow?.[col];
+		if (pivot === void 0 || Math.abs(pivot) < 1e-12) continue;
+		if (pivotRow !== void 0) for (let j = col; j < 2 * n; j++) pivotRow[j] = (pivotRow[j] ?? 0) / pivot;
+		for (let row = 0; row < n; row++) {
+			if (row === col) continue;
+			const eliminationRow = aug[row];
+			const factor = eliminationRow?.[col] ?? 0;
+			if (eliminationRow !== void 0 && pivotRow !== void 0) for (let j = col; j < 2 * n; j++) eliminationRow[j] = (eliminationRow[j] ?? 0) - factor * (pivotRow[j] ?? 0);
+		}
+	}
+	const Ainv = [];
+	for (let i = 0; i < n; i++) Ainv[i] = (aug[i]?.slice(n) ?? []).map((v) => v);
+	return Ainv;
+}
+/**
+* Rank paths by reciprocal of resistance distance between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest conductance first)
+*/
+function resistanceDistance(graph, paths, config) {
+	const { includeScores = true } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "resistance-distance"
+	};
+	const nodeCount = Array.from(graph.nodeIds()).length;
+	if (nodeCount > 5e3) throw new Error(`Cannot rank paths: graph too large (${String(nodeCount)} nodes). Resistance distance requires O(n^3) computation; maximum 5000 nodes.`);
+	return normaliseAndRank(paths, paths.map((path) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		return {
+			path,
+			score: 1 / computeResistance(graph, source, target)
+		};
+	}), "resistance-distance", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/random-ranking.ts
+/**
+* Deterministic seeded random number generator.
+* Uses FNV-1a-like hash for input → [0, 1] output.
+*
+* @param input - String to hash
+* @param seed - Random seed for reproducibility
+* @returns Deterministic random value in [0, 1]
+*/
+function seededRandom(input, seed = 0) {
+	let h = seed;
+	for (let i = 0; i < input.length; i++) {
+		h = Math.imul(h ^ input.charCodeAt(i), 2654435769);
+		h ^= h >>> 16;
+	}
+	return (h >>> 0) / 4294967295;
+}
+/**
+* Rank paths randomly (null hypothesis baseline).
+*
+* @param _graph - Source graph (unused)
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (randomly ordered)
+*/
+function randomRanking(_graph, paths, config) {
+	const { includeScores = true, seed = 0 } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "random"
+	};
+	return normaliseAndRank(paths, paths.map((path) => {
+		return {
+			path,
+			score: seededRandom(path.nodes.join(","), seed)
+		};
+	}), "random", includeScores);
+}
+//#endregion
+//#region src/ranking/baselines/hitting-time.ts
+/**
+* Seeded deterministic random number generator (LCG).
+* Suitable for reproducible random walk simulation.
+*/
+var SeededRNG = class {
+	state;
+	constructor(seed) {
+		this.state = seed;
+	}
+	/**
+	* Generate next pseudorandom value in [0, 1).
+	*/
+	next() {
+		this.state = this.state * 1103515245 + 12345 & 2147483647;
+		return this.state / 2147483647;
+	}
+};
+/**
+* Compute hitting time via Monte Carlo random walk simulation.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @param walks - Number of walks to simulate
+* @param maxSteps - Maximum steps per walk
+* @param rng - Seeded RNG instance
+* @returns Average hitting time across walks
+*/
+function computeHittingTimeApproximate(graph, source, target, walks, maxSteps, rng) {
+	if (source === target) return 0;
+	let totalSteps = 0;
+	let successfulWalks = 0;
+	for (let w = 0; w < walks; w++) {
+		let current = source;
+		let steps = 0;
+		while (current !== target && steps < maxSteps) {
+			const neighbours = Array.from(graph.neighbours(current));
+			if (neighbours.length === 0) break;
+			const nextNode = neighbours[Math.floor(rng.next() * neighbours.length)];
+			if (nextNode === void 0) break;
+			current = nextNode;
+			steps++;
+		}
+		if (current === target) {
+			totalSteps += steps;
+			successfulWalks++;
+		}
+	}
+	if (successfulWalks > 0) return totalSteps / successfulWalks;
+	return maxSteps;
+}
+/**
+* Compute hitting time via exact fundamental matrix method.
+*
+* For small graphs, computes exact expected hitting times using
+* the fundamental matrix of the random walk.
+*
+* @param graph - Source graph
+* @param source - Source node ID
+* @param target - Target node ID
+* @returns Exact hitting time (or approximation if convergence fails)
+*/
+function computeHittingTimeExact(graph, source, target) {
+	if (source === target) return 0;
+	const nodes = Array.from(graph.nodeIds());
+	const nodeToIdx = /* @__PURE__ */ new Map();
+	nodes.forEach((nodeId, idx) => {
+		nodeToIdx.set(nodeId, idx);
+	});
+	const n = nodes.length;
+	const sourceIdx = nodeToIdx.get(source);
+	const targetIdx = nodeToIdx.get(target);
+	if (sourceIdx === void 0 || targetIdx === void 0) return 0;
+	const P = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		for (let j = 0; j < n; j++) row[j] = 0;
+		P[i] = row;
+	}
+	for (const nodeId of nodes) {
+		const idx = nodeToIdx.get(nodeId);
+		if (idx === void 0) continue;
+		const pRow = P[idx];
+		if (pRow === void 0) continue;
+		if (idx === targetIdx) pRow[idx] = 1;
+		else {
+			const neighbours = Array.from(graph.neighbours(nodeId));
+			const degree = neighbours.length;
+			if (degree > 0) for (const neighbourId of neighbours) {
+				const nIdx = nodeToIdx.get(neighbourId);
+				if (nIdx !== void 0) pRow[nIdx] = 1 / degree;
+			}
+		}
+	}
+	const transientIndices = [];
+	for (let i = 0; i < n; i++) if (i !== targetIdx) transientIndices.push(i);
+	const m = transientIndices.length;
+	const Q = [];
+	for (let i = 0; i < m; i++) {
+		const row = [];
+		for (let j = 0; j < m; j++) row[j] = 0;
+		Q[i] = row;
+	}
+	for (let i = 0; i < m; i++) {
+		const qRow = Q[i];
+		if (qRow === void 0) continue;
+		const origI = transientIndices[i];
+		if (origI === void 0) continue;
+		const pRow = P[origI];
+		if (pRow === void 0) continue;
+		for (let j = 0; j < m; j++) {
+			const origJ = transientIndices[j];
+			if (origJ === void 0) continue;
+			qRow[j] = pRow[origJ] ?? 0;
+		}
+	}
+	const IMQ = [];
+	for (let i = 0; i < m; i++) {
+		const row = [];
+		for (let j = 0; j < m; j++) row[j] = i === j ? 1 : 0;
+		IMQ[i] = row;
+	}
+	for (let i = 0; i < m; i++) {
+		const imqRow = IMQ[i];
+		if (imqRow === void 0) continue;
+		const qRow = Q[i];
+		for (let j = 0; j < m; j++) {
+			const qVal = qRow?.[j] ?? 0;
+			imqRow[j] = (i === j ? 1 : 0) - qVal;
+		}
+	}
+	const N = invertMatrix(IMQ);
+	if (N === null) return 1;
+	const sourceTransientIdx = transientIndices.indexOf(sourceIdx);
+	if (sourceTransientIdx < 0) return 0;
+	let hittingTime = 0;
+	const row = N[sourceTransientIdx];
+	if (row !== void 0) for (const val of row) hittingTime += val;
+	return hittingTime;
+}
+/**
+* Invert a square matrix using Gaussian elimination with partial pivoting.
+*
+* @param matrix - Input matrix (n × n)
+* @returns Inverted matrix, or null if singular
+*/
+function invertMatrix(matrix) {
+	const n = matrix.length;
+	const aug = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		const matRow = matrix[i];
+		for (let j = 0; j < n; j++) row[j] = matRow?.[j] ?? 0;
+		for (let j = 0; j < n; j++) row[n + j] = i === j ? 1 : 0;
+		aug[i] = row;
+	}
+	for (let col = 0; col < n; col++) {
+		let pivotRow = col;
+		const pivotCol = aug[pivotRow];
+		if (pivotCol === void 0) return null;
+		for (let row = col + 1; row < n; row++) {
+			const currRowVal = aug[row]?.[col] ?? 0;
+			const pivotRowVal = pivotCol[col] ?? 0;
+			if (Math.abs(currRowVal) > Math.abs(pivotRowVal)) pivotRow = row;
+		}
+		const augPivot = aug[pivotRow];
+		if (augPivot === void 0 || Math.abs(augPivot[col] ?? 0) < 1e-10) return null;
+		[aug[col], aug[pivotRow]] = [aug[pivotRow] ?? [], aug[col] ?? []];
+		const scaledPivotRow = aug[col];
+		if (scaledPivotRow === void 0) return null;
+		const pivot = scaledPivotRow[col] ?? 1;
+		for (let j = 0; j < 2 * n; j++) scaledPivotRow[j] = (scaledPivotRow[j] ?? 0) / pivot;
+		for (let row = col + 1; row < n; row++) {
+			const currRow = aug[row];
+			if (currRow === void 0) continue;
+			const factor = currRow[col] ?? 0;
+			for (let j = 0; j < 2 * n; j++) currRow[j] = (currRow[j] ?? 0) - factor * (scaledPivotRow[j] ?? 0);
+		}
+	}
+	for (let col = n - 1; col > 0; col--) {
+		const colRow = aug[col];
+		if (colRow === void 0) return null;
+		for (let row = col - 1; row >= 0; row--) {
+			const currRow = aug[row];
+			if (currRow === void 0) continue;
+			const factor = currRow[col] ?? 0;
+			for (let j = 0; j < 2 * n; j++) currRow[j] = (currRow[j] ?? 0) - factor * (colRow[j] ?? 0);
+		}
+	}
+	const inv = [];
+	for (let i = 0; i < n; i++) {
+		const row = [];
+		for (let j = 0; j < n; j++) row[j] = 0;
+		inv[i] = row;
+	}
+	for (let i = 0; i < n; i++) {
+		const invRow = inv[i];
+		if (invRow === void 0) continue;
+		const augRow = aug[i];
+		if (augRow === void 0) continue;
+		for (let j = 0; j < n; j++) invRow[j] = augRow[n + j] ?? 0;
+	}
+	return inv;
+}
+/**
+* Rank paths by inverse hitting time between endpoints.
+*
+* @param graph - Source graph
+* @param paths - Paths to rank
+* @param config - Configuration options
+* @returns Ranked paths (highest inverse hitting time first)
+*/
+function hittingTime(graph, paths, config) {
+	const { includeScores = true, mode = "auto", walks = 1e3, maxSteps = 1e4, seed = 42 } = config ?? {};
+	if (paths.length === 0) return {
+		paths: [],
+		method: "hitting-time"
+	};
+	const nodeCount = Array.from(graph.nodeIds()).length;
+	const actualMode = mode === "auto" ? nodeCount < 100 ? "exact" : "approximate" : mode;
+	const rng = new SeededRNG(seed);
+	const scored = paths.map((path) => {
+		const source = path.nodes[0];
+		const target = path.nodes[path.nodes.length - 1];
+		if (source === void 0 || target === void 0) return {
+			path,
+			score: 0
+		};
+		const ht = actualMode === "exact" ? computeHittingTimeExact(graph, source, target) : computeHittingTimeApproximate(graph, source, target, walks, maxSteps, rng);
+		return {
+			path,
+			score: ht > 0 ? 1 / ht : 0
+		};
+	});
+	const maxScore = Math.max(...scored.map((s) => s.score));
+	if (!Number.isFinite(maxScore)) return {
+		paths: paths.map((path) => ({
+			...path,
+			score: 0
+		})),
+		method: "hitting-time"
+	};
+	return normaliseAndRank(paths, scored, "hitting-time", includeScores);
+}
+//#endregion
+Object.defineProperty(exports, "betweenness", {
+	enumerable: true,
+	get: function() {
+		return betweenness;
+	}
+});
+Object.defineProperty(exports, "communicability", {
+	enumerable: true,
+	get: function() {
+		return communicability;
+	}
+});
+Object.defineProperty(exports, "degreeSum", {
+	enumerable: true,
+	get: function() {
+		return degreeSum;
+	}
+});
+Object.defineProperty(exports, "hittingTime", {
+	enumerable: true,
+	get: function() {
+		return hittingTime;
+	}
+});
+Object.defineProperty(exports, "jaccardArithmetic", {
+	enumerable: true,
+	get: function() {
+		return jaccardArithmetic;
+	}
+});
+Object.defineProperty(exports, "katz", {
+	enumerable: true,
+	get: function() {
+		return katz;
+	}
+});
+Object.defineProperty(exports, "pagerank", {
+	enumerable: true,
+	get: function() {
+		return pagerank;
+	}
+});
+Object.defineProperty(exports, "parse", {
+	enumerable: true,
+	get: function() {
+		return parse;
+	}
+});
+Object.defineProperty(exports, "parseAsync", {
+	enumerable: true,
+	get: function() {
+		return parseAsync;
+	}
+});
+Object.defineProperty(exports, "randomRanking", {
+	enumerable: true,
+	get: function() {
+		return randomRanking;
+	}
+});
+Object.defineProperty(exports, "resistanceDistance", {
+	enumerable: true,
+	get: function() {
+		return resistanceDistance;
+	}
+});
+Object.defineProperty(exports, "shortest", {
+	enumerable: true,
+	get: function() {
+		return shortest;
+	}
+});
+Object.defineProperty(exports, "widestPath", {
+	enumerable: true,
+	get: function() {
+		return widestPath;
+	}
+});
+
+//# sourceMappingURL=ranking-riRrEVAR.cjs.map