graphwise 1.4.0 → 1.4.2

package/README.md

@@ -81,25 +81,35 @@ where $H_{\text{local}}(v) = -\sum_{\tau} p(\tau) \log p(\tau)$ is the Shannon e
 
 #### PIPE: Path-potential Informed Priority Expansion
 
-$$\pi_{\text{PIPE}}(v) = \frac{\deg(v)}{1 + \text{path\_potential}(v)}$$
+$$\pi_{\text{PIPE}}(v) = \frac{\deg(v)}{1 + \mathrm{pathPotential}(v)}$$
 
-where $\text{path\_potential}(v) = |N(v) \cap \bigcup_{j \neq i} V_j|$ counts neighbours already visited by other seed frontiers. High path potential indicates imminent path completion.
+where $\mathrm{pathPotential}(v) = \lvert N(v) \cap \bigcup_{j \neq i} V_j \rvert$ counts neighbours already visited by other seed frontiers. High path potential indicates imminent path completion.
 
 #### SAGE: Salience-Accumulation Guided Expansion
 
-$$\pi_{\text{SAGE}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1 (before first path)} \\ -(\text{salience}(v) \times 1000 - \deg(v)) & \text{Phase 2 (after first path)} \end{cases}$$
+$$
+\pi_{\text{SAGE}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1 (before first path)} \\ -(\text{salience}(v) \times 1000 - \deg(v)) & \text{Phase 2 (after first path)} \end{cases}
+$$
 
 where $\text{salience}(v)$ counts discovered paths containing $v$. Salience dominates in Phase 2; degree serves as tiebreaker.
 
 #### REACH: Retrospective Expansion with Adaptive Convergence
 
-$$\pi_{\text{REACH}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1} \\ \log(\deg(v) + 1) \times (1 - \widehat{\text{MI}}(v)) & \text{Phase 2} \end{cases}$$
+$$
+\pi_{\text{REACH}}(v) = \begin{cases} \log(\deg(v) + 1) & \text{Phase 1} \\ \log(\deg(v) + 1) \times (1 - \widehat{\text{MI}}(v)) & \text{Phase 2} \end{cases}
+$$
 
-where $\widehat{\text{MI}}(v) = \frac{1}{|\mathcal{P}_{\text{top}}|} \sum_{p} J(N(v), N(p_{\text{endpoint}}))$ estimates MI via Jaccard similarity to discovered path endpoints.
+where $\widehat{\text{MI}}(v)$ estimates MI via Jaccard similarity to discovered path endpoints:
+
+$$
+\widehat{\text{MI}}(v) = \frac{1}{\lvert \mathcal{P}\_{\text{top}} \rvert} \sum\_{p} J(N(v), N(p\_{\text{endpoint}}))
+$$
 
 #### MAZE: Multi-frontier Adaptive Zone Expansion
 
-$$\pi^{(1)}(v) = \frac{\deg(v)}{1 + \text{path\_potential}(v)} \qquad \pi^{(2)}(v) = \pi^{(1)}(v) \times \frac{1}{1 + \lambda \cdot \text{salience}(v)}$$
+$$
+\pi^{(1)}(v) = \frac{\deg(v)}{1 + \mathrm{pathPotential}(v)} \qquad \pi^{(2)}(v) = \pi^{(1)}(v) \times \frac{1}{1 + \lambda \cdot \text{salience}(v)}
+$$
 
 Phase 1 uses PIPE's path potential until $M$ paths found. Phase 2 incorporates SAGE's salience feedback. Phase 3 evaluates diversity, path count, and salience plateau for termination.
 
@@ -129,7 +139,9 @@ Single-phase weighted blend of degree and MI. Related to SAGE but uses continuou
 
 #### SIFT: Salience-Informed Frontier Threshold
 
-$$\pi_{\text{SIFT}}(v) = \begin{cases} 1 - \overline{\text{MI}} & \text{if } \overline{\text{MI}} \geq \tau \\ \deg(v) + 100 & \text{otherwise} \end{cases}$$
+$$
+\pi_{\text{SIFT}}(v) = \begin{cases} 1 - \overline{\text{MI}} & \text{if } \overline{\text{MI}} \geq \tau \\ \deg(v) + 100 & \text{otherwise} \end{cases}
+$$
 
 MI-threshold-based priority with degree fallback. Related to REACH but uses a hard threshold instead of continuous MI-weighted priority.
 
@@ -215,7 +227,7 @@ where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jacca
 | --------------------------- | --------------------------------------------------- |
 | **Katz Index**              | $\sum_{k=1}^{\infty} \beta^k (A^k)_{st}$            |
 | **Communicability**         | $(e^A)_{st}$                                        |
-| **Resistance Distance**     | $L^{+}_{ss} + L^{+}_{tt} - 2L^{+}_{st}$             |
+| **Resistance Distance**     | $L^{+}\_{ss} + L^{+}\_{tt} - 2L^{+}\_{st}$          |
 | **Jaccard Arithmetic Mean** | $\frac{1}{k} \sum J(N(u), N(v))$                    |
 | **Degree-Sum**              | $\sum_{v \in P} \deg(v)$                            |
 | **Widest Path**             | $\min_{(u,v) \in P} w(u,v)$                         |

package/dist/expansion/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/expansion/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,eAAe,EAEf,MAAM,SAAS,CAAC;AAqBjB;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAoOjB"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/expansion/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,eAAe,EAEf,MAAM,SAAS,CAAC;AAqBjB;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAwOjB"}

package/dist/expansion/maze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maze.d.ts","sourceRoot":"","sources":["../../src/expansion/maze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AASjB;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAwEjB"}
+{"version":3,"file":"maze.d.ts","sourceRoot":"","sources":["../../src/expansion/maze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AASjB;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAsEjB"}

package/dist/expansion/reach.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../../src/expansion/reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC3D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAiDjB"}
+{"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../../src/expansion/reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC3D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CA2EjB"}

package/dist/expansion/sage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sage.d.ts","sourceRoot":"","sources":["../../src/expansion/sage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAsDjB"}
+{"version":3,"file":"sage.d.ts","sourceRoot":"","sources":["../../src/expansion/sage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAU,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAiDjB"}

package/dist/index/index.cjs

@@ -26,6 +26,8 @@ function base(graph, seeds, config) {
 	const { maxNodes = 0, maxIterations = 0, maxPaths = 0, priority = degreePriority, debug = false } = config ?? {};
 	if (seeds.length === 0) return emptyResult("base", startTime);
 	const numFrontiers = seeds.length;
+	const allVisited = /* @__PURE__ */ new Set();
+	const combinedVisited = /* @__PURE__ */ new Map();
 	const visitedByFrontier = [];
 	const predecessors = [];
 	const queues = [];
@@ -37,15 +39,16 @@ function base(graph, seeds, config) {
 		if (seed === void 0) continue;
 		const seedNode = seed.id;
 		predecessors[i]?.set(seedNode, null);
-		const seedPriority = priority(seedNode, createPriorityContext(graph, seedNode, i, visitedByFrontier, [], 0));
+		combinedVisited.set(seedNode, i);
+		allVisited.add(seedNode);
+		const seedPriority = priority(seedNode, createPriorityContext(graph, seedNode, i, combinedVisited, allVisited, [], 0));
 		queues[i]?.push({
 			nodeId: seedNode,
 			frontierIndex: i,
 			predecessor: null
 		}, seedPriority);
 	}
-	const allVisited = /* @__PURE__ */ new Set();
-	const sampledEdges = /* @__PURE__ */ new Set();
+	const sampledEdgeMap = /* @__PURE__ */ new Map();
 	const discoveredPaths = [];
 	let iterations = 0;
 	let edgesTraversed = 0;
@@ -90,6 +93,7 @@ function base(graph, seeds, config) {
 		const frontierVisited = visitedByFrontier[activeFrontier];
 		if (frontierVisited === void 0 || frontierVisited.has(nodeId)) continue;
 		frontierVisited.set(nodeId, activeFrontier);
+		combinedVisited.set(nodeId, activeFrontier);
 		if (predecessor !== null) {
 			const predMap = predecessors[activeFrontier];
 			if (predMap !== void 0) predMap.set(nodeId, predecessor);
@@ -111,11 +115,16 @@ function base(graph, seeds, config) {
 		const neighbours = graph.neighbours(nodeId);
 		for (const neighbour of neighbours) {
 			edgesTraversed++;
-			const edgeKey = nodeId < neighbour ? `${nodeId}::${neighbour}` : `${neighbour}::${nodeId}`;
-			sampledEdges.add(edgeKey);
+			const [s, t] = nodeId < neighbour ? [nodeId, neighbour] : [neighbour, nodeId];
+			let targets = sampledEdgeMap.get(s);
+			if (targets === void 0) {
+				targets = /* @__PURE__ */ new Set();
+				sampledEdgeMap.set(s, targets);
+			}
+			targets.add(t);
 			const frontierVisited = visitedByFrontier[activeFrontier];
 			if (frontierVisited === void 0 || frontierVisited.has(neighbour)) continue;
-			const neighbourPriority = priority(neighbour, createPriorityContext(graph, neighbour, activeFrontier, visitedByFrontier, discoveredPaths, iterations + 1));
+			const neighbourPriority = priority(neighbour, createPriorityContext(graph, neighbour, activeFrontier, combinedVisited, allVisited, discoveredPaths, iterations + 1));
 			queue.push({
 				nodeId: neighbour,
 				frontierIndex: activeFrontier,
@@ -127,14 +136,7 @@ function base(graph, seeds, config) {
 	const endTime = performance.now();
 	const visitedPerFrontier = visitedByFrontier.map((m) => new Set(m.keys()));
 	const edgeTuples = /* @__PURE__ */ new Set();
-	for (const edgeKey of sampledEdges) {
-		const parts = edgeKey.split("::");
-		if (parts.length === 2) {
-			const source = parts[0];
-			const target = parts[1];
-			if (source !== void 0 && target !== void 0) edgeTuples.add([source, target]);
-		}
-	}
+	for (const [source, targets] of sampledEdgeMap) for (const target of targets) edgeTuples.add([source, target]);
 	return {
 		paths: discoveredPaths,
 		sampledNodes: allVisited,
@@ -154,10 +156,7 @@ function base(graph, seeds, config) {
 /**
 * Create priority context for a node.
 */
-function createPriorityContext(graph, nodeId, frontierIndex, visitedByFrontier, discoveredPaths, iteration) {
-	const combinedVisited = /* @__PURE__ */ new Map();
-	for (const frontierMap of visitedByFrontier) for (const [id, idx] of frontierMap) combinedVisited.set(id, idx);
-	const allVisited = new Set(combinedVisited.keys());
+function createPriorityContext(graph, nodeId, frontierIndex, combinedVisited, allVisited, discoveredPaths, iteration) {
 	return {
 		graph,
 		degree: graph.degree(nodeId),
@@ -341,10 +340,12 @@ function hae(graph, seeds, config) {
 * visited by OTHER frontiers (not the current frontier).
 */
 function pipePriority(nodeId, context) {
-	const graph = context.graph;
-	const neighbours = new Set(graph.neighbours(nodeId));
+	const neighbours = context.graph.neighbours(nodeId);
 	let pathPotential = 0;
-	for (const [visitedId, frontierIdx] of context.visitedByFrontier) if (frontierIdx !== context.frontierIndex && neighbours.has(visitedId)) pathPotential++;
+	for (const neighbour of neighbours) {
+		const visitedBy = context.visitedByFrontier.get(neighbour);
+		if (visitedBy !== void 0 && visitedBy !== context.frontierIndex) pathPotential++;
+	}
 	return context.degree / (1 + pathPotential);
 }
 /**
@@ -387,10 +388,7 @@ function sage(graph, seeds, config) {
 	*/
 	function sagePriority(nodeId, context) {
 		const pathCount = context.discoveredPaths.length;
-		if (pathCount > 0 && !inPhase2) {
-			inPhase2 = true;
-			for (const path of context.discoveredPaths) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
-		}
+		if (pathCount > 0 && !inPhase2) inPhase2 = true;
 		if (pathCount > lastPathCount) {
 			for (let i = lastPathCount; i < pathCount; i++) {
 				const path = context.discoveredPaths[i];
@@ -440,6 +438,23 @@ function jaccard(graph, source, target, config) {
 */
 function reach(graph, seeds, config) {
 	let inPhase2 = false;
+	const jaccardCache = /* @__PURE__ */ new Map();
+	/**
+	* Compute Jaccard similarity with caching.
+	*
+	* Exploits symmetry of Jaccard (J(A,B) = J(B,A)) to reduce
+	* duplicate computations when the same pair appears in multiple
+	* discovered paths. Key format ensures consistent ordering.
+	*/
+	function cachedJaccard(source, target) {
+		const key = source < target ? `${source}::${target}` : `${target}::${source}`;
+		let score = jaccardCache.get(key);
+		if (score === void 0) {
+			score = jaccard(graph, source, target);
+			jaccardCache.set(key, score);
+		}
+		return score;
+	}
 	/**
 	* REACH priority function with MI estimation.
 	*/
@@ -451,8 +466,8 @@ function reach(graph, seeds, config) {
 		for (const path of context.discoveredPaths) {
 			const fromNodeId = path.fromSeed.id;
 			const toNodeId = path.toSeed.id;
-			totalMI += jaccard(graph, nodeId, fromNodeId);
-			totalMI += jaccard(graph, nodeId, toNodeId);
+			totalMI += cachedJaccard(nodeId, fromNodeId);
+			totalMI += cachedJaccard(nodeId, toNodeId);
 			endpointCount += 2;
 		}
 		const miHat = endpointCount > 0 ? totalMI / endpointCount : 0;
@@ -500,9 +515,12 @@ function maze(graph, seeds, config) {
 			}
 			lastPathCount = pathCount;
 		}
-		const nodeNeighbours = new Set(graph.neighbours(nodeId));
+		const nodeNeighbours = graph.neighbours(nodeId);
 		let pathPotential = 0;
-		for (const [visitedId, frontierIdx] of context.visitedByFrontier) if (frontierIdx !== context.frontierIndex && nodeNeighbours.has(visitedId)) pathPotential++;
+		for (const neighbour of nodeNeighbours) {
+			const visitedBy = context.visitedByFrontier.get(neighbour);
+			if (visitedBy !== void 0 && visitedBy !== context.frontierIndex) pathPotential++;
+		}
 		if (!inPhase2) return context.degree / (1 + pathPotential);
 		const salience = salienceCounts.get(nodeId) ?? 0;
 		return context.degree / (1 + pathPotential) * (1 / (1 + SALIENCE_WEIGHT * salience));