perf: 2-hop pair enumeration in LinkPredictionAnalyzer predict() and predictEnsemble()

For CN/Jaccard/Adamic-Adar methods, only vertex pairs sharing at least
one common neighbor can score > 0. Replace O(V^2) all-pairs sweep with
O(V*delta^2) neighbors-of-neighbors enumeration. On sparse graphs (delta << V)
this is orders of magnitude faster. PA retains O(V^2) sweep since any pair
with non-zero degrees scores positively.

predictEnsemble() also switched from O(V^2) to 2-hop since the ensemble
is dominated by CN/Jaccard/AA signals; PA-only pairs with zero overlap
are extremely weak candidates that would rarely make top-K.

Author: sauravbhattacharya001

Gvisual/src/gvisual/LinkPredictionAnalyzer.java

@@ -174,11 +174,14 @@ public String getSummary() {
     /**
      * Predict missing links using the specified method.
      *
-     * <p>Uses a streaming top-K approach with a min-heap instead of
-     * materializing all candidate pairs in memory. For a graph with V
-     * vertices and K requested predictions, this reduces memory from
-     * O(V²) (one HashSet per pair) to O(K), which is critical for
-     * large graphs (e.g. V=1000 → ~500K fewer HashSet allocations).</p>
+     * <p>Uses a streaming top-K approach with a min-heap of size K.
+     * For COMMON_NEIGHBORS, JACCARD, and ADAMIC_ADAR, only pairs sharing
+     * at least one common neighbor can score &gt; 0, so we enumerate
+     * <b>2-hop pairs</b> (neighbors-of-neighbors) instead of all O(V²)
+     * vertex pairs — reducing work to O(V·Δ²) where Δ is max degree.
+     * On sparse graphs (Δ ≪ V) this is orders of magnitude faster.
+     * PREFERENTIAL_ATTACHMENT still uses the O(V²) sweep since any pair
+     * with non-zero degrees scores positively.</p>
      *
      * @param method scoring method to use
      * @param topK   number of top predictions to return
@@ -191,51 +194,75 @@ public PredictionResult predict(Method method, int topK) {
         long possibleEdges = (long) n * (n - 1) / 2;
         Map<String, Set<String>> adjacency = adjacency();
 
-        List<String> vertexList = new ArrayList<String>(vertices);
-
-        // Min-heap of size topK: keeps only the best predictions in O(K) memory
-        // instead of collecting all O(V²) candidates
         PriorityQueue<PredictedLink> minHeap = new PriorityQueue<PredictedLink>(
                 topK + 1,
                 (PredictedLink a, PredictedLink b) -> Double.compare(a.getScore(), b.getScore()));
 
         int candidatesEvaluated = 0;
 
-        for (int i = 0; i < vertexList.size(); i++) {
-            String u = vertexList.get(i);
-            Set<String> uNeighbors = adjacency.get(u);
+        if (method == Method.PREFERENTIAL_ATTACHMENT) {
+            // PA scores are non-zero for any pair where both endpoints have
+            // neighbors, so O(V²) enumeration is unavoidable.
+            List<String> vertexList = new ArrayList<String>(vertices);
+            for (int i = 0; i < vertexList.size(); i++) {
+                String u = vertexList.get(i);
+                Set<String> uNeighbors = adjacency.get(u);
+                if (uNeighbors.isEmpty()) continue;
 
-            for (int j = i + 1; j < vertexList.size(); j++) {
-                String v = vertexList.get(j);
-                if (uNeighbors.contains(v)) continue; // skip existing edges
-
-                candidatesEvaluated++;
-
-                // Compute common neighbors inline (avoids allocating a HashSet
-                // when score is zero or below the heap threshold)
-                Set<String> vNeighbors = adjacency.get(v);
-                double score;
-
-                if (method == Method.PREFERENTIAL_ATTACHMENT) {
-                    // No common neighbors needed for preferential attachment
-                    score = (double) uNeighbors.size() * vNeighbors.size();
-                    if (score > 0) {
-                        // Only compute common neighbors for the result object
-                        // if this score makes it into the heap
-                        if (minHeap.size() < topK || score > minHeap.peek().getScore()) {
-                            Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
-                            minHeap.offer(new PredictedLink(u, v, score, method, common));
-                            if (minHeap.size() > topK) minHeap.poll();
-                        }
+                for (int j = i + 1; j < vertexList.size(); j++) {
+                    String v = vertexList.get(j);
+                    if (uNeighbors.contains(v)) continue;
+
+                    Set<String> vNeighbors = adjacency.get(v);
+                    if (vNeighbors.isEmpty()) continue;
+
+                    candidatesEvaluated++;
+                    double score = (double) uNeighbors.size() * vNeighbors.size();
+
+                    if (minHeap.size() < topK || score > minHeap.peek().getScore()) {
+                        Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
+                        minHeap.offer(new PredictedLink(u, v, score, method, common));
+                        if (minHeap.size() > topK) minHeap.poll();
                     }
-                } else {
-                    // All other methods need common neighbors for scoring
-                    Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
-                    score = computeScore(method, adjacency, u, v, common);
-                    if (score > 0) {
-                        if (minHeap.size() < topK || score > minHeap.peek().getScore()) {
-                            minHeap.offer(new PredictedLink(u, v, score, method, common));
-                            if (minHeap.size() > topK) minHeap.poll();
+                }
+            }
+        } else {
+            // CN / Jaccard / Adamic-Adar: score is 0 when common neighbors
+            // is empty, so only 2-hop reachable pairs need evaluation.
+            // For each vertex u, walk u's neighbors w, then w's neighbors v
+            // (where v > u lexicographically and v is not adjacent to u).
+            // A seen-set per source u deduplicates the (u,v) pairs.
+            List<String> sortedVertices = new ArrayList<String>(vertices);
+            Collections.sort(sortedVertices);
+            Map<String, Integer> vertexOrd = new HashMap<String, Integer>(n * 2);
+            for (int i = 0; i < sortedVertices.size(); i++) {
+                vertexOrd.put(sortedVertices.get(i), i);
+            }
+
+            for (String u : sortedVertices) {
+                Set<String> uNeighbors = adjacency.get(u);
+                if (uNeighbors.isEmpty()) continue;
+                int uOrd = vertexOrd.get(u);
+
+                // Collect 2-hop candidates: distinct vertices reachable
+                // through exactly one intermediate neighbor
+                Set<String> seen = new HashSet<String>();
+                for (String w : uNeighbors) {
+                    for (String v : adjacency.get(w)) {
+                        // Only consider v > u (lexicographic) to avoid
+                        // evaluating each pair twice, and skip direct neighbors
+                        if (vertexOrd.get(v) > uOrd
+                                && !uNeighbors.contains(v)
+                                && seen.add(v)) {
+                            candidatesEvaluated++;
+                            Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
+                            double score = computeScore(method, adjacency, u, v, common);
+                            if (score > 0
+                                    && (minHeap.size() < topK
+                                        || score > minHeap.peek().getScore())) {
+                                minHeap.offer(new PredictedLink(u, v, score, method, common));
+                                if (minHeap.size() > topK) minHeap.poll();
+                            }
                         }
                     }
                 }
@@ -254,12 +281,14 @@ public PredictionResult predict(Method method, int topK) {
      * Predict using all methods and return a combined ranking.
      * Each method's scores are normalized to [0,1] and averaged.
      *
-     * <p>Uses a two-pass streaming approach: pass 1 computes per-method
-     * max scores (needed for normalization) while keeping only the raw
-     * scores of the current top-K candidates in a min-heap. Pass 2
-     * re-scores only those top-K finalists with normalized values.
-     * This avoids materializing O(V²) pair lists and score arrays,
-     * reducing memory from O(V²) to O(K).</p>
+     * <p>Uses a two-phase approach: for the CN/Jaccard/AA components,
+     * only <b>2-hop pairs</b> (neighbors-of-neighbors) are enumerated
+     * since those are the only pairs with non-zero CN/Jaccard/AA scores.
+     * Preferential Attachment is computed inline for these same pairs.
+     * This reduces the inner loop from O(V²) to O(V·Δ²) on sparse
+     * graphs while still producing correct ensemble rankings (pairs with
+     * zero CN/Jaccard/AA and only a PA signal are extremely weak
+     * candidates and would rarely make the top-K).</p>
      *
      * @param topK number of top predictions to return
      * @return prediction result with ensemble scores
@@ -270,57 +299,60 @@ public PredictionResult predictEnsemble(int topK) {
         int existingEdges = graph.getEdgeCount();
         long possibleEdges = (long) n * (n - 1) / 2;
         Map<String, Set<String>> adjacency = adjacency();
-        List<String> vertexList = new ArrayList<String>(vertices);
 
         Method[] methods = {
             Method.COMMON_NEIGHBORS, Method.JACCARD,
             Method.ADAMIC_ADAR, Method.PREFERENTIAL_ATTACHMENT
         };
 
-        // Pass 1: stream through all pairs, track max scores and keep a
-        // generous top-K candidate pool (4*topK to allow for re-ranking
-        // after normalization).
         int poolSize = Math.max(topK * 4, 64);
         double[] maxScores = new double[4];
         int candidatesEvaluated = 0;
 
-        // Each entry in the heap stores: [u, v, common, scores[4]]
         PriorityQueue<Object[]> minHeap = new PriorityQueue<Object[]>(
                 poolSize + 1,
                 (Object[] a, Object[] b) -> Double.compare(
                         ((double[]) a[3])[4], ((double[]) b[3])[4]));
 
-        for (int i = 0; i < vertexList.size(); i++) {
-            String u = vertexList.get(i);
-            Set<String> uNeighbors = adjacency.get(u);
-
-            for (int j = i + 1; j < vertexList.size(); j++) {
-                String v = vertexList.get(j);
-                if (uNeighbors.contains(v)) continue;
-
-                candidatesEvaluated++;
-
-                Set<String> vNeighbors = adjacency.get(v);
-                // Quick check: if both have zero neighbors, skip
-                if (uNeighbors.isEmpty() && vNeighbors.isEmpty()) continue;
+        // 2-hop enumeration: only pairs sharing ≥1 common neighbor
+        List<String> sortedVertices = new ArrayList<String>(vertices);
+        Collections.sort(sortedVertices);
+        Map<String, Integer> vertexOrd = new HashMap<String, Integer>(n * 2);
+        for (int i = 0; i < sortedVertices.size(); i++) {
+            vertexOrd.put(sortedVertices.get(i), i);
+        }
 
-                Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
-                double[] scores = new double[5]; // [CN, Jaccard, AA, PA, rawSum]
-                for (int m = 0; m < 4; m++) {
-                    scores[m] = computeScore(methods[m], adjacency, u, v, common);
-                }
-                // Skip pairs with no signal at all
-                if (scores[0] == 0 && scores[3] == 0) continue;
+        for (String u : sortedVertices) {
+            Set<String> uNeighbors = adjacency.get(u);
+            if (uNeighbors.isEmpty()) continue;
+            int uOrd = vertexOrd.get(u);
+
+            Set<String> seen = new HashSet<String>();
+            for (String w : uNeighbors) {
+                for (String v : adjacency.get(w)) {
+                    if (vertexOrd.get(v) > uOrd
+                            && !uNeighbors.contains(v)
+                            && seen.add(v)) {
+                        candidatesEvaluated++;
+
+                        Set<String> common = GraphUtils.getCommonNeighbors(adjacency, u, v);
+                        double[] scores = new double[5];
+                        for (int m = 0; m < 4; m++) {
+                            scores[m] = computeScore(methods[m], adjacency, u, v, common);
+                        }
+                        if (scores[0] == 0 && scores[3] == 0) continue;
 
-                scores[4] = scores[0] + scores[1] + scores[2] + scores[3]; // raw sum for heap ordering
+                        scores[4] = scores[0] + scores[1] + scores[2] + scores[3];
 
-                for (int m = 0; m < 4; m++) {
-                    maxScores[m] = Math.max(maxScores[m], scores[m]);
-                }
+                        for (int m = 0; m < 4; m++) {
+                            maxScores[m] = Math.max(maxScores[m], scores[m]);
+                        }
 
-                if (minHeap.size() < poolSize || scores[4] > ((double[]) minHeap.peek()[3])[4]) {
-                    minHeap.offer(new Object[]{u, v, common, scores});
-                    if (minHeap.size() > poolSize) minHeap.poll();
+                        if (minHeap.size() < poolSize || scores[4] > ((double[]) minHeap.peek()[3])[4]) {
+                            minHeap.offer(new Object[]{u, v, common, scores});
+                            if (minHeap.size() > poolSize) minHeap.poll();
+                        }
+                    }
                 }
             }
         }