Implement Leiden stats proc

Co-authored-by: Ioannis Panagiotas <ioannis.panagiotas@neotechnology.com>

Author: vnickolov

algo/src/main/java/org/neo4j/gds/leiden/Leiden.java

@@ -36,7 +36,7 @@
 
 //TODO: take care of potential issues w. self-loops
 
-public class Leiden extends Algorithm<HugeLongArray> {
+public class Leiden extends Algorithm<LeidenResult> {
 
     private final Graph rootGraph;
 
@@ -74,7 +74,7 @@ public Leiden(
     }
 
     @Override
-    public HugeLongArray compute() {
+    public LeidenResult compute() {
         var workingGraph = rootGraph;
         var orientation = rootGraph.isUndirected() ? Orientation.UNDIRECTED : Orientation.NATURAL;
 
@@ -85,6 +85,7 @@ public HugeLongArray compute() {
         HugeLongArray partition = HugeLongArray.newArray(workingGraph.nodeCount());
         partition.setAll(nodeId -> nodeId);
 
+        boolean didConverge = false;
         int iteration;
         // move on with refinement -> aggregation -> local move again
         for (iteration = 0; iteration < maxIterations; iteration++) {
@@ -97,7 +98,8 @@ public HugeLongArray compute() {
             communityVolumes = localMovePhasePartition.communityVolumes();
             var communitiesCount = Arrays.stream(partition.toArray()).distinct().count();
 
-            if (communitiesCount == workingGraph.nodeCount()) {
+            didConverge = communitiesCount == workingGraph.nodeCount();
+            if (didConverge) {
                 break;
             }
 
@@ -140,7 +142,7 @@ public HugeLongArray compute() {
             nodeVolumes = communityData.aggregatedNodeSeedVolume;
         }
 
-        return dendrograms[iteration - 1];
+        return LeidenResult.of(dendrograms[iteration - 1], iteration, didConverge);
     }
 
     private void initVolumes(HugeDoubleArray nodeVolumes, HugeDoubleArray communityVolumes) {

algo/src/main/java/org/neo4j/gds/leiden/LeidenResult.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.leiden;
+
+import org.immutables.value.Value;
+import org.neo4j.gds.annotation.ValueClass;
+import org.neo4j.gds.core.utils.paged.HugeLongArray;
+
+import java.util.function.LongUnaryOperator;
+
+@ValueClass
+@SuppressWarnings("immutables:subtype")
+public interface LeidenResult {
+
+    HugeLongArray communities();
+
+    long ranLevels();
+
+    boolean didConverge();
+
+    @Value.Derived
+    default LongUnaryOperator communitiesFunction() {
+        return communities()::get;
+    }
+
+    static LeidenResult of(HugeLongArray communities, long ranLevels, boolean didConverge) {
+        return ImmutableLeidenResult.of(communities, ranLevels, didConverge);
+    }
+
+}

algo/src/main/java/org/neo4j/gds/leiden/LeidenStatsConfig.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.leiden;
+
+
+import org.neo4j.gds.annotation.Configuration;
+import org.neo4j.gds.annotation.ValueClass;
+import org.neo4j.gds.core.CypherMapWrapper;
+
+@ValueClass
+@Configuration
+@SuppressWarnings("immutables:subtype")
+public interface LeidenStatsConfig extends LeidenBaseConfig {
+    static LeidenStatsConfig of(CypherMapWrapper userInput) {
+        return new LeidenStatsConfigImpl(userInput);
+    }
+}

algo/src/test/java/org/neo4j/gds/leiden/FootballTest.java

@@ -53,7 +53,7 @@ class FootballTest {
     void leiden(long seed) {
         var gamma = 1.0 / graph.relationshipCount();
         Leiden leiden = new Leiden(graph, 5, gamma, 0.01, seed, 1, ProgressTracker.NULL_TRACKER);
-        var communities = leiden.compute();
+        var communities = leiden.compute().communities();
         var communitiesMap = LongStream
             .range(0, graph.nodeCount())
             .mapToObj(v -> "a" + v)

algo/src/test/java/org/neo4j/gds/leiden/KarateTest.java

@@ -50,7 +50,7 @@ class KarateTest {
     void leiden(long seed) {
         var gamma = 1.0 / graph.relationshipCount();
         Leiden leiden = new Leiden(graph, 5, gamma, 0.01, seed, 1, ProgressTracker.NULL_TRACKER);
-        var communities = leiden.compute();
+        var communities = leiden.compute().communities();
         var communitiesMap = LongStream
             .range(0, graph.nodeCount())
             .mapToObj(v -> "a" + v)

algo/src/test/java/org/neo4j/gds/leiden/LeidenTest.java

@@ -74,9 +74,16 @@ class LeidenTest {
 
     @Test
     void leiden() {
-        Leiden leiden = new Leiden(graph, 2, 1.0 / graph.relationshipCount(), 0.01, 19L, 1, ProgressTracker.NULL_TRACKER
+        int maxLevels = 3;
+        Leiden leiden = new Leiden(graph, maxLevels, 1.0 / graph.relationshipCount(), 0.01, 19L, 1, ProgressTracker.NULL_TRACKER
         );
-        var communities = leiden.compute();
+
+        var leidenResult = leiden.compute();
+
+        assertThat(leidenResult.ranLevels()).isLessThanOrEqualTo(maxLevels);
+        assertThat(leidenResult.didConverge()).isTrue();
+
+        var communities = leidenResult.communities();
         var communitiesMap = LongStream
             .range(0, graph.nodeCount())
             .mapToObj(v -> "a" + v)

proc/community/src/main/java/org/neo4j/gds/leiden/LeidenStatsProc.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.leiden;
+
+import org.neo4j.gds.AlgoBaseProc;
+import org.neo4j.gds.AlgorithmFactory;
+import org.neo4j.gds.core.CypherMapWrapper;
+import org.neo4j.gds.executor.ComputationResultConsumer;
+import org.neo4j.gds.executor.ProcedureExecutor;
+import org.neo4j.procedure.Description;
+import org.neo4j.procedure.Name;
+import org.neo4j.procedure.Procedure;
+
+import java.util.Map;
+import java.util.stream.Stream;
+
+import static org.neo4j.procedure.Mode.READ;
+
+public class LeidenStatsProc extends AlgoBaseProc<Leiden, LeidenResult, LeidenStatsConfig, StatsResult> {
+
+    @Procedure(value = "gds.alpha.leiden.stats", mode = READ)
+    @Description(STATS_DESCRIPTION)
+    public Stream<StatsResult> stats(
+        @Name(value = "graphName") String graphName,
+        @Name(value = "configuration", defaultValue = "{}") Map<String, Object> configuration
+    ) {
+        var statsSpec = new LeidenStatsSpec();
+        return new ProcedureExecutor<>(
+            statsSpec,
+            executionContext()
+        ).compute(graphName, configuration, true, true);
+    }
+
+
+
+    @Override
+    @Deprecated
+    public AlgorithmFactory<?, Leiden, LeidenStatsConfig> algorithmFactory() {
+        return null;
+    }
+
+    @Override
+    @Deprecated
+    public <T extends ComputationResultConsumer<Leiden, LeidenResult, LeidenStatsConfig, Stream<StatsResult>>> T computationResultConsumer() {
+        return null;
+    }
+
+    @Override
+    @Deprecated
+    protected LeidenStatsConfig newConfig(String username, CypherMapWrapper config) {
+        return null;
+    }
+}

proc/community/src/main/java/org/neo4j/gds/leiden/LeidenStatsSpec.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Neo4j is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package org.neo4j.gds.leiden;
+
+import org.neo4j.gds.executor.AlgorithmSpec;
+import org.neo4j.gds.executor.ComputationResultConsumer;
+import org.neo4j.gds.executor.GdsCallable;
+import org.neo4j.gds.executor.NewConfigFunction;
+
+import java.util.stream.Stream;
+
+import static org.neo4j.gds.executor.ExecutionMode.STREAM;
+import static org.neo4j.gds.leiden.LeidenStreamProc.DESCRIPTION;
+
+@GdsCallable(name = "gds.alpha.leiden.stats", description = DESCRIPTION, executionMode = STREAM)
+public class LeidenStatsSpec implements AlgorithmSpec<Leiden, LeidenResult, LeidenStatsConfig, Stream<StatsResult>, LeidenAlgorithmFactory<LeidenStatsConfig>> {
+    @Override
+    public String name() {
+        return "LeidenStats";
+    }
+
+    @Override
+    public LeidenAlgorithmFactory<LeidenStatsConfig> algorithmFactory() {
+        return new LeidenAlgorithmFactory<>();
+    }
+
+    @Override
+    public NewConfigFunction<LeidenStatsConfig> newConfigFunction() {
+        return (__, config) -> LeidenStatsConfig.of(config);
+    }
+
+    @Override
+    public ComputationResultConsumer<Leiden, LeidenResult, LeidenStatsConfig, Stream<StatsResult>> computationResultConsumer() {
+        return (computationResult, executionContext) -> {
+            var leidenResult = computationResult.result();
+            if (leidenResult == null) {
+                return Stream.empty();
+            }
+
+            var statsBuilder = new StatsResult.StatsBuilder(
+                executionContext.callContext(),
+                computationResult.config().concurrency()
+            );
+
+            var statsResult = statsBuilder
+                .withLevels(leidenResult.ranLevels())
+                .withDidConverge(leidenResult.didConverge())
+                .withCommunityFunction(leidenResult.communitiesFunction())
+                .withPreProcessingMillis(computationResult.preProcessingMillis())
+                .withComputeMillis(computationResult.computeMillis())
+                .withNodeCount(computationResult.graph().nodeCount())
+                .withConfig(computationResult.config())
+                .build();
+
+            return Stream.of(statsResult);
+        };
+    }
+}

proc/community/src/main/java/org/neo4j/gds/leiden/LeidenStreamSpec.java

@@ -19,7 +19,6 @@
  */
 package org.neo4j.gds.leiden;
 
-import org.neo4j.gds.core.utils.paged.HugeLongArray;
 import org.neo4j.gds.executor.AlgorithmSpec;
 import org.neo4j.gds.executor.ComputationResultConsumer;
 import org.neo4j.gds.executor.GdsCallable;
@@ -32,7 +31,7 @@
 import static org.neo4j.gds.leiden.LeidenStreamProc.DESCRIPTION;
 
 @GdsCallable(name = "gds.alpha.leiden.stream", description = DESCRIPTION, executionMode = STREAM)
-public class LeidenStreamSpec implements AlgorithmSpec<Leiden, HugeLongArray, LeidenStreamConfig, Stream<StreamResult>, LeidenAlgorithmFactory<LeidenStreamConfig>> {
+public class LeidenStreamSpec implements AlgorithmSpec<Leiden, LeidenResult, LeidenStreamConfig, Stream<StreamResult>, LeidenAlgorithmFactory<LeidenStreamConfig>> {
     @Override
     public String name() {
         return "LeidenStream";
@@ -49,10 +48,14 @@ public NewConfigFunction<LeidenStreamConfig> newConfigFunction() {
     }
 
     @Override
-    public ComputationResultConsumer<Leiden, HugeLongArray, LeidenStreamConfig, Stream<StreamResult>> computationResultConsumer() {
+    public ComputationResultConsumer<Leiden, LeidenResult, LeidenStreamConfig, Stream<StreamResult>> computationResultConsumer() {
         return (computationResult, executionContext) -> {
+            var leidenResult = computationResult.result();
+            if (leidenResult == null) {
+                return Stream.empty();
+            }
             var graph = computationResult.graph();
-            var communities = computationResult.result();
+            var communities = leidenResult.communities();
             return LongStream.range(0, graph.nodeCount())
                 .mapToObj(nodeId -> new StreamResult(graph.toOriginalNodeId(nodeId), communities.get(nodeId)));
         };