The lca package

jgrapht-core/src/main/java/org/jgrapht/alg/NaiveLcaFinder.java

@@ -17,7 +17,8 @@
  */
 package org.jgrapht.alg;
 
-import org.jgrapht.*;
+import org.jgrapht.Graph;
+import org.jgrapht.GraphTests;
 
 import java.util.*;
 
@@ -61,8 +62,10 @@
  * 
  * @param <V> the graph vertex type
  * @param <E> the graph edge type
- * 
+ *
+ * @deprecated Replaced by {@link org.jgrapht.alg.lca.NaiveLCAFinder}
  */
+@Deprecated
 public class NaiveLcaFinder<V, E>
 {
     private Graph<V, E> graph;
@@ -259,4 +262,4 @@ private V overlappingMember(Set<V> x, Set<V> y)
     }
 }
 
-// End NaiveLcaFinder.java
+// End NaiveLCAFinder.java

jgrapht-core/src/main/java/org/jgrapht/alg/TarjanLowestCommonAncestor.java

@@ -17,8 +17,8 @@
  */
 package org.jgrapht.alg;
 
-import org.jgrapht.*;
-import org.jgrapht.alg.util.*;
+import org.jgrapht.Graph;
+import org.jgrapht.alg.util.UnionFind;
 
 import java.util.*;
 
@@ -29,8 +29,10 @@
  * @param <E> the graph edge type
  *
  * @author Leo Crawford
+ *
+ * @deprecated Replaced by {@link org.jgrapht.alg.lca.TarjanLCAFinder}
  */
-public class TarjanLowestCommonAncestor<V, E>
+@Deprecated public class TarjanLowestCommonAncestor<V, E>
 {
     private Graph<V, E> g;
 
@@ -232,4 +234,4 @@ public Set<LcaRequestResponse<V>> getOrCreate(V key)
     }
 }
 
-// End TarjanLowestCommonAncestor.java
+// End TarjanLCAFinder.java

jgrapht-core/src/main/java/org/jgrapht/alg/decomposition/HeavyPathDecomposition.java

@@ -32,6 +32,12 @@
  *  into a set of disjoint paths.
  *
  * <p>
+ *  The techniques was first introduced in <i>Sleator, D. D.; Tarjan, R. E. (1983).
+ *  "A Data Structure for Dynamic Trees". Proceedings of the thirteenth annual ACM symposium on Theory of computing
+ *  - STOC '81 doi:10.1145/800076.802464 </i>
+ * </p>
+ *
+ * <p>
  * In a heavy path decomposition, the edges set is partitioned into two sets, a set of heavy edges and a
  * set of light ones according to the relative number of nodes in the vertex's subtree.
  *
@@ -80,7 +86,7 @@ public class HeavyPathDecomposition<V, E> implements TreeToPathDecompositionAlgo
     /**
      * Create an instance with a reference to the tree that we will decompose and to the root of the tree.
      *
-     * Note: The constructor will NOT check if the input tree is a valid tree.
+     * Note: The constructor will NOT check if the input graph is a valid tree.
      *
      * @param tree the input tree
      * @param root the root of the tree
@@ -94,7 +100,7 @@ public HeavyPathDecomposition(Graph<V, E> tree, V root) {
      * forest (one root per tree).
      *
      * Note: If two roots appear in the same tree, an error will be thrown.
-     * Note: The constructor will NOT check if the input forest is a valid forest.
+     * Note: The constructor will NOT check if the input graph is a valid forest.
      *
      * @param forest the input forest
      * @param roots the set of roots of the graph
@@ -512,5 +518,16 @@ public int[] getPositionInPathArray(){
         public int[] getFirstNodeInPathArray(){
             return firstNodeInPath;
         }
+
+        /**
+         * Return the internal parent array.
+         * For each vertex $v \in V$, $parentArray[normalizeVertex(v)] = normalizeVertex(u)$ if $getParent(v) = u$ or
+         * $-1$ if $getParent(v) = null$.
+         *
+         * @return internal parent array
+         */
+        public int[] getParentArray(){
+            return parent;
+        }
     }
 }

jgrapht-core/src/main/java/org/jgrapht/alg/interfaces/LCAAlgorithm.java

@@ -0,0 +1,54 @@
+/*
+ * (C) Copyright 2018-2018, by Alexandru Valeanu and Contributors.
+ *
+ * JGraphT : a free Java graph-theory library
+ *
+ * This program and the accompanying materials are dual-licensed under
+ * either
+ *
+ * (a) the terms of the GNU Lesser General Public License version 2.1
+ * as published by the Free Software Foundation, or (at your option) any
+ * later version.
+ *
+ * or (per the licensee's choosing)
+ *
+ * (b) the terms of the Eclipse Public License v1.0 as published by
+ * the Eclipse Foundation.
+ */
+package org.jgrapht.alg.interfaces;
+
+import org.jgrapht.alg.util.Pair;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * Algorithm to compute a <a href="https://en.wikipedia.org/wiki/Lowest_common_ancestor">lowest common ancestor</a>
+ * in a tree, forest or DAG.
+ *
+ * @param <V> vertex the graph vertex type
+ *
+ * @author Alexandru Valeanu
+ */
+public interface LCAAlgorithm<V> {
+
+    /**
+     * Return the LCA of a and b
+     *
+     * @param a the first element to find LCA for
+     * @param b the other element to find the LCA for
+     *
+     * @return the LCA of a and b, or null if there is no LCA.
+     */
+    V getLCA(V a, V b);
+
+    /**
+     * Return a list of LCA for a batch of queries
+     *
+     * @param queries a list of pairs of vertices
+     * @return a list L of LCAs where L(i) is the LCA of pair queries(i)
+     */
+    default List<V> getLCAs(List<Pair<V, V>> queries){
+        return queries.stream().map(p -> getLCA(p.getFirst(), p.getSecond())).collect(Collectors.toList());
+    }
+}

jgrapht-core/src/main/java/org/jgrapht/alg/lca/BinaryLiftingLCAFinder.java

@@ -0,0 +1,215 @@
+/*
+ * (C) Copyright 2018-2018, by Alexandru Valeanu and Contributors.
+ *
+ * JGraphT : a free Java graph-theory library
+ *
+ * This program and the accompanying materials are dual-licensed under
+ * either
+ *
+ * (a) the terms of the GNU Lesser General Public License version 2.1
+ * as published by the Free Software Foundation, or (at your option) any
+ * later version.
+ *
+ * or (per the licensee's choosing)
+ *
+ * (b) the terms of the Eclipse Public License v1.0 as published by
+ * the Eclipse Foundation.
+ */
+package org.jgrapht.alg.lca;
+
+import org.jgrapht.Graph;
+import org.jgrapht.Graphs;
+import org.jgrapht.alg.interfaces.LCAAlgorithm;
+import org.jgrapht.util.VertexToIntegerMapping;
+
+import java.util.*;
+
+import static org.jgrapht.util.MathUtil.log2;
+
+/**
+ * Algorithm for computing lowest common ancestors in rooted trees and forests using the binary lifting method.
+ *
+ * <p>
+ * The method appears in <i>Bender, Michael A., and Martın Farach-Colton. "The level ancestor problem
+ * simplified." Theoretical Computer Science 321.1 (2004): 5-12</i> and it is also nicely presented in
+ * the following article on
+ * <a href="https://www.topcoder.com/community/data-science/data-science-tutorials/range-minimum-query-and-lowest-common-ancestor/#Another%20easy%20solution%20in%20O(N%20logN,%20O(logN)">Topcoder</a>
+ * for more details about the algorithm.
+ * </p>
+ *
+ * <p>
+ * Algorithm idea:<br>
+ * We improve on the naive approach by using jump pointers. These are pointers at a node which reference one of the
+ * node’s ancestors. Each node stores jump pointers to ancestors at levels 1, 2, 4, . . . , 2^k. <br>
+ * Queries are answered by repeatedly jumping from node to node, each time jumping more than half of the
+ * remaining levels between the current ancestor and the goal ancestor (i.e. the lca).
+ * The worst-case number of jumps is $O(log(|V|))$.
+ * </p>
+ *
+ * <p>
+ *  Preprocessing Time complexity: $O(|V| log(|V|))$<br>
+ *  Preprocessing Space complexity:  $O(|V| log(|V|))$<br>
+ *  Query Time complexity: $O(log(|V|))$<br>
+ *  Query Space complexity: $O(1)$<br>
+ * </p>
+ *
+ * @param <V> the graph vertex type
+ * @param <E> the graph edge type
+ *
+ * @author Alexandru Valeanu
+ */
+public class BinaryLiftingLCAFinder<V, E> implements LCAAlgorithm<V> {
+
+    private final Graph<V, E> graph;
+    private final Set<V> roots;
+    private final int maxLevel;
+
+    private Map<V, Integer> vertexMap;
+    private List<V> indexList;
+
+    // ancestors[u][i] = the 2^i ancestor of u (e.g ancestors[u][0] = father(u))
+    private int[][] ancestors;
+
+    private int[] timeIn, timeOut;
+    private int clock = 0;
+
+    private int numberComponent;
+    private int[] component;
+
+    /**
+     * Construct a new instance of the algorithm.
+     *
+     * Note: The constructor will NOT check if the input graph is a valid tree.
+     *
+     * @param graph the input graph
+     * @param root the root of the graph
+     */
+    public BinaryLiftingLCAFinder(Graph<V, E> graph, V root){
+        this(graph, Collections.singleton(Objects.requireNonNull(root, "root cannot be null")));
+    }
+
+    /**
+     * Construct a new instance of the algorithm.
+     *
+     * Note: If two roots appear in the same tree, an error will be thrown.
+     * Note: The constructor will NOT check if the input graph is a valid forest.
+     *
+     * @param graph the input graph
+     * @param roots the set of roots of the graph
+     */
+    public BinaryLiftingLCAFinder(Graph<V, E> graph, Set<V> roots){
+        this.graph = Objects.requireNonNull(graph, "graph cannot be null");
+        this.roots = Objects.requireNonNull(roots, "roots cannot be null");
+        this.maxLevel = log2(graph.vertexSet().size());
+
+        if (this.roots.isEmpty())
+            throw new IllegalArgumentException("roots cannot be empty");
+
+        if (!graph.vertexSet().containsAll(roots))
+            throw new IllegalArgumentException("at least one root is not a valid vertex");
+
+        computeAncestorMatrix();
+    }
+
+    private void normalizeGraph(){
+        VertexToIntegerMapping<V> vertexToIntegerMapping = Graphs.getVertexToIntegerMapping(graph);
+        vertexMap = vertexToIntegerMapping.getVertexMap();
+        indexList = vertexToIntegerMapping.getIndexList();
+    }
+
+    private void dfs(int u, int parent){
+        component[u] = numberComponent;
+        timeIn[u] = ++clock;
+
+        ancestors[0][u] = parent;
+        for (int l = 1; l < maxLevel; l++) {
+            if (ancestors[l - 1][u] != -1)
+                ancestors[l][u] = ancestors[l - 1][ancestors[l - 1][u]];
+        }
+
+        V vertexU = indexList.get(u);
+        for (E edge: graph.edgesOf(vertexU)){
+            int v = vertexMap.get(Graphs.getOppositeVertex(graph, edge, vertexU));
+
+            if (v != parent){
+                dfs(v, u);
+            }
+        }
+
+        timeOut[u] = ++clock;
+    }
+
+    private void computeAncestorMatrix(){
+        ancestors = new int[maxLevel + 1][graph.vertexSet().size()];
+
+        for (int l = 0; l < maxLevel; l++) {
+            Arrays.fill(ancestors[l], -1);
+        }
+
+        timeIn = new int[graph.vertexSet().size()];
+        timeOut = new int[graph.vertexSet().size()];
+
+        // Ensure that isAncestor(x, y) == false if either x and y hasn't been explored yet
+        for (int i = 0; i < graph.vertexSet().size(); i++) {
+            timeIn[i] = timeOut[i] = -(i + 1);
+        }
+
+        numberComponent = 0;
+        component = new int[graph.vertexSet().size()];
+
+        normalizeGraph();
+
+        for (V root: roots) {
+            if (component[vertexMap.get(root)] == 0) {
+                numberComponent++;
+                dfs(vertexMap.get(root), -1);
+            } else {
+                throw new IllegalArgumentException("multiple roots in the same tree");
+            }
+        }
+    }
+
+    private boolean isAncestor(int ancestor, int descendant) {
+        return timeIn[ancestor] <= timeIn[descendant] && timeOut[descendant] <= timeOut[ancestor];
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public V getLCA(V a, V b) {
+        int indexA = vertexMap.getOrDefault(a, -1);
+        if (indexA == -1)
+            throw new IllegalArgumentException("invalid vertex: " + a);
+
+        int indexB = vertexMap.getOrDefault(b, -1);
+        if (indexB == -1)
+            throw new IllegalArgumentException("invalid vertex: " + b);
+
+        // Check if a == b because lca(a, a) == a
+        if (a.equals(b))
+            return a;
+
+        // if a and b are in different components then they do not have a lca
+        if (component[indexA] != component[indexB] || component[indexA] == 0)
+            return null;
+
+        if (isAncestor(indexA, indexB))
+            return a;
+
+        if (isAncestor(indexB, indexA))
+            return b;
+
+        for (int l = maxLevel - 1; l >= 0; l--)
+            if (ancestors[l][indexA] != -1 && !isAncestor(ancestors[l][indexA], indexB))
+                indexA = ancestors[l][indexA];
+
+        int lca = ancestors[0][indexA];
+
+        // if lca is null
+        if (lca == -1)
+            return null;
+        else
+            return indexList.get(lca);
+    }
+}