Merge pull request #4293 from DarthMax/1.8_randomwalk_2_beta

1.8 - Promote RandomWalk to beta

Author: jjaderberg

algo/src/main/java/org/neo4j/gds/traversal/RandomWalkAlgorithmFactory.java

@@ -22,10 +22,14 @@
 import org.neo4j.gds.AlgorithmFactory;
 import org.neo4j.gds.api.Graph;
 import org.neo4j.gds.core.utils.mem.AllocationTracker;
+import org.neo4j.gds.core.utils.mem.MemoryEstimation;
+import org.neo4j.gds.core.utils.mem.MemoryEstimations;
+import org.neo4j.gds.core.utils.mem.MemoryRange;
 import org.neo4j.gds.core.utils.progress.tasks.ProgressTracker;
 import org.neo4j.gds.core.utils.progress.tasks.Task;
 import org.neo4j.gds.core.utils.progress.tasks.Tasks;
 import org.neo4j.gds.degree.DegreeCentralityFactory;
+import org.neo4j.gds.mem.MemoryUsage;
 
 import java.util.ArrayList;
 
@@ -57,4 +61,16 @@ public Task progressTask(
 
         return Tasks.task(taskName(), tasks);
     }
+
+    @Override
+    public MemoryEstimation memoryEstimation(CONFIG config) {
+        var memoryUsagePerWalk = MemoryUsage.sizeOfLongArray(config.walkLength());
+        var sizeOfBuffer = MemoryUsage.sizeOfObjectArray(config.walkBufferSize());
+
+        var maxMemoryUsage = sizeOfBuffer + MemoryUsage.sizeOfArray(config.walkBufferSize(), memoryUsagePerWalk);
+
+        return MemoryEstimations.builder(RandomWalk.class)
+            .fixed("random walk buffer", MemoryRange.of(sizeOfBuffer, maxMemoryUsage))
+            .build();
+    }
 }

doc/antora/content-nav.adoc

@@ -80,7 +80,7 @@
 *** xref:alpha-algorithms/minimum-weight-spanning-tree/index.adoc[]
 *** xref:alpha-algorithms/single-source-shortest-path/index.adoc[]
 *** xref:alpha-algorithms/all-pairs-shortest-path/index.adoc[]
-*** xref:alpha-algorithms/random-walk/index.adoc[]
+*** xref:beta-algorithms/random-walk/index.adoc[]
 *** xref:algorithms/bfs/index.adoc[]
 *** xref:algorithms/dfs/index.adoc[]
 ** xref:algorithms/linkprediction/index.adoc[]

doc/asciidoc/algorithms/algorithms-path-finding.adoc

@@ -14,11 +14,12 @@ The Neo4j GDS library includes the following path finding algorithms, grouped by
 ** <<algorithms-dijkstra-single-source, Dijkstra Single-Source>>
 ** <<algorithms-astar, A*>>
 ** <<algorithms-yens, Yen's algorithm>>
+* Beta
+** <<beta-algorithms-random-walk, Random Walk>>
 * Alpha
 ** <<alpha-algorithms-minimum-weight-spanning-tree, Minimum Weight Spanning Tree>>
 ** <<alpha-algorithms-single-source-shortest-path, Single Source Shortest Path>>
 ** <<alpha-algorithm-all-pairs-shortest-path, All Pairs Shortest Path>>
-** <<alpha-algorithms-random-walk, Random Walk>>
 ** <<algorithms-bfs, Breadth First Search>>
 ** <<algorithms-dfs, Depth First Search>>
 
@@ -30,14 +31,14 @@ include::shortest-path/astar.adoc[leveloffset=+1]
 
 include::shortest-path/yens.adoc[leveloffset=+1]
 
+include::beta/randomWalk/beta-random-walk.adoc[leveloffset=+1]
+
 include::alpha/alpha-minimum-weight-spanning-tree.adoc[leveloffset=+1]
 
 include::alpha/alpha-single-shortest-path.adoc[leveloffset=+1]
 
 include::alpha/alpha-all-pairs-shortest-path.adoc[leveloffset=+1]
 
-include::alpha/randomWalk/alpha-random-walk.adoc[leveloffset=+1]
-
 include::alpha/alpha-bfs.adoc[leveloffset=+1]
 
 include::alpha/alpha-dfs.adoc[leveloffset=+1]

doc/asciidoc/algorithms/alpha/randomWalk/alpha-random-walk.adoc renamed to doc/asciidoc/algorithms/beta/randomWalk/beta-random-walk.adoc

@@ -1,5 +1,5 @@
-[[alpha-algorithms-random-walk]]
-[.alpha]
+[[beta-algorithms-random-walk]]
+[.beta]
 = Random Walk
 
 [abstract]
@@ -27,6 +27,12 @@ A relationship property value greater than 1 will increase the likelihood of a r
 [NOTE]
 To obtain a random walk where the transition probability is independent of the previously visited nodes both the `returnFactor` and the `inOutFactor` can be set to 1.0.
 
+[NOTE]
+====
+Running this algorithm requires sufficient memory availability.
+Before running this algorithm, we recommend that you read <<memory-estimation>>.
+====
+
 [[algorithms-random-walk-syntax]]
 == Syntax
 
@@ -39,7 +45,7 @@ To obtain a random walk where the transition probability is independent of the p
 .Run RandomWalk in stream mode on a named graph.
 [source, cypher, role=noplay]
 ----
-CALL gds.alpha.randomWalk.stream(
+CALL gds.beta.randomWalk.stream(
   graphName: String,
   configuration: Map
 ) YIELD
@@ -111,7 +117,7 @@ CALL gds.graph.create(
 .Run the RandomWalk algorithm on `myGraph`
 [source, cypher, role=noplay]
 ----
-CALL gds.alpha.randomWalk.stream(
+CALL gds.beta.randomWalk.stream(
   'myGraph',
   {
     walkLength: 3,
@@ -147,7 +153,7 @@ RETURN nodeIds, [node IN nodes(path) | node.name ] AS pages
 MATCH (page:Page)
 WHERE page.name IN ['Home', 'About']
 WITH COLLECT(page) as sourceNodes
-CALL gds.alpha.randomWalk.stream(
+CALL gds.beta.randomWalk.stream(
   'myGraph',
   {
     sourceNodes: sourceNodes,

doc/asciidoc/algorithms/alpha/randomWalk/specific-configuration.adoc renamed to doc/asciidoc/algorithms/beta/randomWalk/specific-configuration.adoc

@@ -201,6 +201,9 @@ include::../algorithms/algorithm-tiers.adoc[]
 | `gds.beta.node2vec.stream.estimate`
 | `gds.beta.node2vec.write`
 | `gds.beta.node2vec.write`.estimate
+.2+<.^|<<beta-algorithms-random-walk, Random Walk>>
+| `gds.beta.randomWalk.stream`
+| `gds.beta.randomWalk.stream.estimate`
 |===
 
 [[alpha-tier]]
@@ -239,8 +242,6 @@ include::../algorithms/algorithm-tiers.adoc[]
 | `gds.alpha.hits.stream.estimate`
 | `gds.alpha.hits.write`
 | `gds.alpha.hits.write.estimate`
-.1+<.^|<<alpha-algorithms-random-walk, Random Walk>>
-| `gds.alpha.randomWalk.stream`
 .2+<.^|<<algorithms-strongly-connected-components, Strongly Connected Components>>
 | `gds.alpha.scc.stream`
 | `gds.alpha.scc.write`

doc/asciidoc/operations-reference/appendix-a-graph-algos.adoc

@@ -239,8 +239,8 @@
             <d:tocentry linkend="alpha-algorithm-all-pairs-shortest-path">
                 <?dbhtml filename="alpha-algorithms/all-pairs-shortest-path/index.html"?>
             </d:tocentry>
-            <d:tocentry linkend="alpha-algorithms-random-walk">
-                <?dbhtml filename="alpha-algorithms/random-walk/index.html"?>
+            <d:tocentry linkend="beta-algorithms-random-walk">
+                <?dbhtml filename="beta-algorithms/random-walk/index.html"?>
             </d:tocentry>
             <d:tocentry linkend="algorithms-bfs">
                 <?dbhtml filename="algorithms/bfs/index.html"?>

doc/docbook/content-map.xml

@@ -19,8 +19,8 @@
  */
 package org.neo4j.gds.doc;
 
+import org.neo4j.gds.beta.randomwalk.RandomWalkStreamProc;
 import org.neo4j.gds.catalog.GraphCreateProc;
-import org.neo4j.gds.walking.RandomWalkStreamProc;
 
 import java.util.List;
 
@@ -36,6 +36,6 @@ protected List<Class<?>> procedures() {
 
     @Override
     protected String adocFile() {
-        return "algorithms/alpha/randomWalk/alpha-random-walk.adoc";
+        return "algorithms/beta/randomWalk/beta-random-walk.adoc";
     }
 }

doc/src/test/java/org/neo4j/gds/doc/RandomWalkDocTest.java

@@ -17,14 +17,16 @@
  * 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.walking;
+package org.neo4j.gds.beta.randomwalk;
 
 import org.neo4j.gds.AlgoBaseProc;
 import org.neo4j.gds.AlgorithmFactory;
+import org.neo4j.gds.BaseProc;
 import org.neo4j.gds.api.IdMapping;
 import org.neo4j.gds.config.GraphCreateConfig;
 import org.neo4j.gds.core.CypherMapWrapper;
 import org.neo4j.gds.paths.PathFactory;
+import org.neo4j.gds.results.MemoryEstimateResult;
 import org.neo4j.gds.traversal.RandomWalk;
 import org.neo4j.gds.traversal.RandomWalkAlgorithmFactory;
 import org.neo4j.gds.traversal.RandomWalkStreamConfig;
@@ -50,7 +52,7 @@ public class RandomWalkStreamProc extends AlgoBaseProc<RandomWalk, Stream<long[]
         "Random Walk is an algorithm that provides random paths in a graph. " +
         "It’s similar to how a drunk person traverses a city.";
 
-    @Procedure(name = "gds.alpha.randomWalk.stream", mode = READ)
+    @Procedure(name = "gds.beta.randomWalk.stream", mode = READ)
     @Description(DESCRIPTION)
     public Stream<RandomWalkResult> stream(
         @Name(value = "graphName") Object graphNameOrConfig,
@@ -80,6 +82,15 @@ public Stream<RandomWalkResult> stream(
             });
     }
 
+    @Procedure(value = "gds.beta.randomWalk.stream.estimate", mode = READ)
+    @Description(BaseProc.ESTIMATE_DESCRIPTION)
+    public Stream<MemoryEstimateResult> estimate(
+        @Name(value = "graphName") Object graphNameOrConfig,
+        @Name(value = "configuration", defaultValue = "{}") Map<String, Object> configuration
+    ) {
+        return computeEstimate(graphNameOrConfig, configuration);
+    }
+
     @Override
     protected RandomWalkStreamConfig newConfig(
         String username,

alpha/alpha-proc/src/main/java/org/neo4j/gds/walking/RandomWalkStreamProc.java renamed to proc/beta/src/main/java/org/neo4j/gds/beta/randomwalk/RandomWalkStreamProc.java

@@ -17,24 +17,32 @@
  * 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;
+package org.neo4j.gds.beta.randomwalk;
 
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.DynamicTest;
 import org.junit.jupiter.api.Test;
+import org.neo4j.gds.AlgoBaseProc;
+import org.neo4j.gds.AlgoBaseProcTest;
+import org.neo4j.gds.BaseProcTest;
+import org.neo4j.gds.GdsCypher;
+import org.neo4j.gds.MemoryEstimateTest;
+import org.neo4j.gds.Orientation;
+import org.neo4j.gds.SourceNodesConfigTest;
+import org.neo4j.gds.catalog.GraphCreateProc;
 import org.junit.jupiter.api.TestFactory;
 import org.neo4j.gds.core.CypherMapWrapper;
 import org.neo4j.gds.test.config.ConcurrencyConfigProcTest;
 import org.neo4j.gds.test.config.RelationshipWeightConfigProcTest;
 import org.neo4j.gds.traversal.RandomWalk;
 import org.neo4j.gds.traversal.RandomWalkStreamConfig;
-import org.neo4j.gds.walking.RandomWalkStreamProc;
 import org.neo4j.graphdb.Path;
 import org.neo4j.kernel.internal.GraphDatabaseAPI;
 
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.stream.Collectors;
@@ -46,8 +54,9 @@
 @SuppressWarnings("unchecked")
 class RandomWalkStreamProcTest extends BaseProcTest implements
     AlgoBaseProcTest<RandomWalk, RandomWalkStreamConfig, Stream<long[]>>,
-    SourceNodesConfigTest<RandomWalk, RandomWalkStreamConfig, Stream<long[]>>
-{
+    SourceNodesConfigTest<RandomWalk, RandomWalkStreamConfig, Stream<long[]>>,
+    MemoryEstimateTest<RandomWalk, RandomWalkStreamConfig, Stream<long[]>> {
+
     private static final String DB_CYPHER =
         "CREATE" +
         "  (a:Node1)" +
@@ -65,14 +74,15 @@ class RandomWalkStreamProcTest extends BaseProcTest implements
     @BeforeEach
     void setup() throws Exception {
         registerProcedures(RandomWalkStreamProc.class);
+        registerProcedures(GraphCreateProc.class);
         runQuery(DB_CYPHER);
     }
 
     @Test
     void shouldRunSimpleConfig() {
         String query = GdsCypher.call()
             .loadEverything(Orientation.UNDIRECTED)
-            .algo("gds", "alpha", "randomWalk")
+            .algo("gds", "beta", "randomWalk")
             .streamMode()
             .addParameter("walksPerNode", 3)
             .addParameter("walkLength", 10)
@@ -96,7 +106,7 @@ void shouldRunSimpleConfig() {
     void shouldReturnPath() {
         String query = GdsCypher.call()
             .loadEverything(Orientation.UNDIRECTED)
-            .algo("gds", "alpha", "randomWalk")
+            .algo("gds", "beta", "randomWalk")
             .streamMode()
             .addParameter("walksPerNode", 3)
             .addParameter("walkLength", 10)
@@ -123,7 +133,7 @@ void shouldReturnPath() {
     void shouldThrowOnUnknownStartNode() {
         String query = GdsCypher.call()
             .loadEverything(Orientation.UNDIRECTED)
-            .algo("gds", "alpha", "randomWalk")
+            .algo("gds", "beta", "randomWalk")
             .streamMode()
             .addParameter("walksPerNode", 3)
             .addParameter("walkLength", 10)
@@ -137,7 +147,7 @@ void shouldThrowOnUnknownStartNode() {
     void shouldThrowOnUnselectedStartNode() {
         String query = GdsCypher.call()
             .loadEverything(Orientation.UNDIRECTED)
-            .algo("gds", "alpha", "randomWalk")
+            .algo("gds", "beta", "randomWalk")
             .streamMode()
             .addParameter("walksPerNode", 3)
             .addParameter("walkLength", 10)
@@ -148,6 +158,23 @@ void shouldThrowOnUnselectedStartNode() {
         assertError(query, "Source nodes do not exist in the in-memory graph for the labels ['Node1', 'Node2']: ['3']");
     }
 
+    @Test
+    void shouldRunMemoryEstimation() {
+        String query = GdsCypher.call()
+            .loadEverything(Orientation.UNDIRECTED)
+            .algo("gds", "beta", "randomWalk")
+            .estimationMode(GdsCypher.ExecutionModes.STREAM)
+            .addParameter("walksPerNode", 3)
+            .addParameter("walkLength", 10)
+            .yields("bytesMin", "bytesMax");
+
+
+        assertCypherResult(query, List.of(Map.of(
+            "bytesMin", 299440L,
+            "bytesMax", 395456L
+        )));
+    }
+
     @Override
     public Class<? extends AlgoBaseProc<RandomWalk, Stream<long[]>, RandomWalkStreamConfig>> getProcedureClazz() {
         return RandomWalkStreamProc.class;

alpha/alpha-proc/src/test/java/org/neo4j/gds/RandomWalkStreamProcTest.java renamed to proc/beta/src/test/java/org/neo4j/gds/beta/randomwalk/RandomWalkStreamProcTest.java

@@ -125,7 +125,6 @@ class ListProcTest extends BaseProcTest {
 
         "gds.alpha.shortestPath.deltaStepping.write",
         "gds.alpha.shortestPath.deltaStepping.stream",
-        "gds.alpha.randomWalk.stream",
         "gds.alpha.similarity.cosine.write",
         "gds.alpha.similarity.cosine.stream",
         "gds.alpha.similarity.cosine.stats",
@@ -214,6 +213,9 @@ class ListProcTest extends BaseProcTest {
         "gds.beta.modularityOptimization.write",
         "gds.beta.modularityOptimization.write.estimate",
 
+        "gds.beta.randomWalk.stream",
+        "gds.beta.randomWalk.stream.estimate",
+
         "gds.allShortestPaths.dijkstra.stream",
         "gds.allShortestPaths.dijkstra.stream.estimate",
         "gds.allShortestPaths.dijkstra.mutate",