Merge pull request #11161 from neo-technology/max-flow-write-facade

Max-flow stats, mutate and write facade

Author: AlfredClemedtson

applications/algorithms/path-finding/src/main/java/org/neo4j/gds/applications/algorithms/pathfinding/PathFindingAlgorithmsEstimationModeBusinessFacade.java

@@ -19,10 +19,13 @@
  */
 package org.neo4j.gds.applications.algorithms.pathfinding;
 
+import org.neo4j.gds.allshortestpaths.AllShortestPathsConfig;
+import org.neo4j.gds.allshortestpaths.AllShortestPathsMemoryEstimateDefinition;
 import org.neo4j.gds.applications.algorithms.machinery.AlgorithmEstimationTemplate;
 import org.neo4j.gds.applications.algorithms.machinery.MemoryEstimateResult;
 import org.neo4j.gds.config.AlgoBaseConfig;
 import org.neo4j.gds.exceptions.MemoryEstimationNotImplementedException;
+import org.neo4j.gds.maxflow.MaxFlowBaseConfig;
 import org.neo4j.gds.mem.MemoryEstimation;
 import org.neo4j.gds.paths.astar.AStarMemoryEstimateDefinition;
 import org.neo4j.gds.paths.astar.config.ShortestPathAStarBaseConfig;
@@ -49,8 +52,6 @@
 import org.neo4j.gds.traversal.RandomWalkCountingVisitsMemoryEstimateDefinition;
 import org.neo4j.gds.traversal.RandomWalkMemoryEstimateDefinition;
 import org.neo4j.gds.traversal.RandomWalkMutateConfig;
-import org.neo4j.gds.allshortestpaths.AllShortestPathsMemoryEstimateDefinition;
-import org.neo4j.gds.allshortestpaths.AllShortestPathsConfig;
 
 /**
  * Here is the top level business facade for all your path finding memory estimation needs.
@@ -130,10 +131,17 @@ MemoryEstimation longestPath() {
         throw new MemoryEstimationNotImplementedException();
     }
 
-    MemoryEstimation maxFlow() {
+    public MemoryEstimation maxFlow() {
         throw new MemoryEstimationNotImplementedException();
     }
 
+    MemoryEstimation maxFlow(
+        MaxFlowBaseConfig configuration,
+        Object graphNameOrConfiguration
+    ) {
+        return maxFlow();
+    }
+
     public MemoryEstimateResult pcst(
         PCSTBaseConfig configuration,
         Object graphNameOrConfiguration

applications/algorithms/path-finding/src/main/java/org/neo4j/gds/applications/algorithms/pathfinding/PathFindingAlgorithmsMutateModeBusinessFacade.java

@@ -32,7 +32,10 @@
 import org.neo4j.gds.applications.algorithms.metadata.RelationshipsWritten;
 import org.neo4j.gds.collections.ha.HugeLongArray;
 import org.neo4j.gds.collections.haa.HugeAtomicLongArray;
+import org.neo4j.gds.maxflow.FlowResult;
+import org.neo4j.gds.maxflow.MaxFlowMutateConfig;
 import org.neo4j.gds.pathfinding.BellmanFordMutateStep;
+import org.neo4j.gds.pathfinding.MaxFlowMutateStep;
 import org.neo4j.gds.pathfinding.PrizeCollectingSteinerTreeMutateStep;
 import org.neo4j.gds.pathfinding.RandomWalkCountingNodeVisitsMutateStep;
 import org.neo4j.gds.pathfinding.SearchMutateStep;
@@ -67,6 +70,7 @@
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.DFS;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.DeltaStepping;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.Dijkstra;
+import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.MaxFlow;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.RandomWalk;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.SingleSourceDijkstra;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.SteinerTree;
@@ -182,6 +186,28 @@ public <RESULT> RESULT depthFirstSearch(
         );
     }
 
+    public <RESULT> RESULT maxFlow(
+        GraphName graphName,
+        MaxFlowMutateConfig configuration,
+        ResultBuilder<MaxFlowMutateConfig, FlowResult, RESULT, RelationshipsWritten> resultBuilder
+    ) {
+        var mutateStep = new MaxFlowMutateStep(
+            configuration.mutateRelationshipType(),
+            configuration.mutateProperty(),
+            mutateRelationshipService
+        );
+
+        return algorithmProcessingTemplateConvenience.processRegularAlgorithmInMutateMode(
+            graphName,
+            configuration,
+            MaxFlow,
+            estimationFacade::maxFlow,
+            (graph, __) -> pathFindingAlgorithms.maxFlow(graph, configuration),
+            mutateStep,
+            resultBuilder
+        );
+    }
+
     public <RESULT> RESULT pcst(
         GraphName graphName,
         PCSTMutateConfig configuration,

applications/algorithms/path-finding/src/main/java/org/neo4j/gds/applications/algorithms/pathfinding/PathFindingAlgorithmsStatsModeBusinessFacade.java

@@ -24,6 +24,8 @@
 import org.neo4j.gds.applications.algorithms.machinery.AlgorithmProcessingTemplateConvenience;
 import org.neo4j.gds.applications.algorithms.machinery.StatsResultBuilder;
 import org.neo4j.gds.collections.ha.HugeLongArray;
+import org.neo4j.gds.maxflow.FlowResult;
+import org.neo4j.gds.maxflow.MaxFlowStatsConfig;
 import org.neo4j.gds.paths.bellmanford.AllShortestPathsBellmanFordStatsConfig;
 import org.neo4j.gds.paths.bellmanford.BellmanFordResult;
 import org.neo4j.gds.paths.delta.config.AllShortestPathsDeltaStatsConfig;
@@ -42,6 +44,7 @@
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.BFS;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.BellmanFord;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.DeltaStepping;
+import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.MaxFlow;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.PCST;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.RandomWalk;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.SteinerTree;
@@ -107,6 +110,21 @@ public <RESULT> RESULT deltaStepping(
         );
     }
 
+    public <RESULT> RESULT maxFlow(
+        GraphName graphName,
+        MaxFlowStatsConfig configuration,
+        StatsResultBuilder<FlowResult, RESULT> resultBuilder
+    ) {
+        return algorithmProcessingTemplateConvenience.processRegularAlgorithmInStatsMode(
+            graphName,
+            configuration,
+            MaxFlow,
+            estimationFacade::maxFlow,
+            (graph, __) -> pathFindingAlgorithms.maxFlow(graph, configuration),
+            resultBuilder
+        );
+    }
+
     public <RESULT> RESULT pcst(
         GraphName graphName,
         PCSTStatsConfig configuration,

applications/algorithms/path-finding/src/main/java/org/neo4j/gds/applications/algorithms/pathfinding/PathFindingAlgorithmsWriteModeBusinessFacade.java

@@ -35,9 +35,12 @@
 import org.neo4j.gds.config.WriteRelationshipConfig;
 import org.neo4j.gds.kspanningtree.KSpanningTreeWriteConfig;
 import org.neo4j.gds.logging.Log;
+import org.neo4j.gds.maxflow.FlowResult;
+import org.neo4j.gds.maxflow.MaxFlowWriteConfig;
 import org.neo4j.gds.mem.MemoryEstimation;
 import org.neo4j.gds.pathfinding.BellmanFordWriteStep;
 import org.neo4j.gds.pathfinding.KSpanningTreeWriteStep;
+import org.neo4j.gds.pathfinding.MaxFlowWriteStep;
 import org.neo4j.gds.pathfinding.PrizeCollectingSteinerTreeWriteStep;
 import org.neo4j.gds.pathfinding.ShortestPathWriteStep;
 import org.neo4j.gds.pathfinding.SpanningTreeWriteStep;
@@ -65,6 +68,7 @@
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.DeltaStepping;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.Dijkstra;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.KSpanningTree;
+import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.MaxFlow;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.PCST;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.SingleSourceDijkstra;
 import static org.neo4j.gds.applications.algorithms.machinery.AlgorithmLabel.SteinerTree;
@@ -170,6 +174,30 @@ public <RESULT> RESULT kSpanningTree(
         );
     }
 
+    public <RESULT> RESULT maxFlow(
+        GraphName graphName,
+        MaxFlowWriteConfig configuration,
+        ResultBuilder<MaxFlowWriteConfig, FlowResult, RESULT, RelationshipsWritten> resultBuilder
+    ) {
+        var writeStep = new MaxFlowWriteStep(
+            writeRelationshipService,
+            configuration.writeRelationshipType(),
+            configuration.writeProperty(),
+            configuration::resolveResultStore,
+            configuration.jobId()
+        );
+
+        return runAlgorithmAndWrite(
+            graphName,
+            configuration,
+            MaxFlow,
+            estimationFacade::maxFlow,
+            (graph, __) -> pathFindingAlgorithms.maxFlow(graph, configuration),
+            writeStep,
+            resultBuilder
+        );
+    }
+
     public <RESULT> RESULT pcst(
         GraphName graphName,
         PCSTWriteConfig configuration,

doc/modules/ROOT/pages/operations-reference/algorithm-references.adoc

@@ -227,8 +227,11 @@
 | `gds.louvain.stream.estimate` label:procedure[Procedure]
 | `gds.louvain.stats` label:procedure[Procedure]
 | `gds.louvain.stats.estimate` label:procedure[Procedure]
-.1+<.^|Max flow
+.4+<.^|Max flow
+| `gds.maxFlow.mutate` label:procedure[Procedure]
+| `gds.maxFlow.stats` label:procedure[Procedure]
 | `gds.maxFlow.stream` label:procedure[Procedure]
+| `gds.maxFlow.write` label:procedure[Procedure]
 .4+<.^|xref:algorithms/approx-max-k-cut.adoc[Approximate Maximum k-cut]
 | `gds.maxkcut.mutate` label:procedure[Procedure]
 | `gds.maxkcut.mutate.estimate` label:procedure[Procedure]

open-packaging/src/test/java/org/neo4j/gds/OpenGdsProcedureSmokeTest.java

@@ -469,7 +469,10 @@ class OpenGdsProcedureSmokeTest extends BaseProcTest {
         "gds.louvain.write",
         "gds.louvain.write.estimate",
 
+        "gds.maxFlow.mutate",
+        "gds.maxFlow.stats",
         "gds.maxFlow.stream",
+        "gds.maxFlow.write",
 
         "gds.nodeSimilarity.mutate",
         "gds.nodeSimilarity.mutate.estimate",
@@ -631,7 +634,7 @@ void countShouldMatch() {
         );
 
         // If you find yourself updating this count, please also update the count in SmokeTest.kt
-        int expectedCount = 469;
+        int expectedCount = 472;
         assertEquals(
             expectedCount,
             returnedRows,

pipeline/src/main/java/org/neo4j/gds/ml/pipeline/MutateModeAlgorithmLibrary.java

@@ -98,7 +98,7 @@ static CanonicalProcedureName algorithmToName(Algorithm algorithm) {
             case Leiden -> CanonicalProcedureName.parse("gds.leiden");
             case Louvain -> CanonicalProcedureName.parse("gds.louvain");
             case LongestPath -> null;
-            case MaxFlow -> null;
+            case MaxFlow -> CanonicalProcedureName.parse("gds.maxflow");
             case Modularity -> null;
             case ModularityOptimization -> CanonicalProcedureName.parse("gds.modularityOptimization");
             case NodeSimilarity -> CanonicalProcedureName.parse("gds.nodeSimilarity");

pipeline/src/main/java/org/neo4j/gds/ml/pipeline/StubbyHolder.java

@@ -51,6 +51,7 @@
 import org.neo4j.gds.ml.pipeline.stubs.LccStub;
 import org.neo4j.gds.ml.pipeline.stubs.LeidenStub;
 import org.neo4j.gds.ml.pipeline.stubs.LouvainStub;
+import org.neo4j.gds.ml.pipeline.stubs.MaxFlowStub;
 import org.neo4j.gds.ml.pipeline.stubs.ModularityOptimizationStub;
 import org.neo4j.gds.ml.pipeline.stubs.Node2VecStub;
 import org.neo4j.gds.ml.pipeline.stubs.NodeSimilarityStub;
@@ -124,7 +125,7 @@ Stub get(Algorithm algorithm) {
             case Leiden -> new LeidenStub();
             case Louvain -> new LouvainStub();
             case LongestPath -> null;
-            case MaxFlow -> null;
+            case MaxFlow -> new MaxFlowStub();
             case Modularity -> null;
             case ModularityOptimization -> new ModularityOptimizationStub();
             case NodeSimilarity -> new NodeSimilarityStub();

pipeline/src/main/java/org/neo4j/gds/ml/pipeline/stubs/MaxFlowStub.java

@@ -0,0 +1,31 @@
+/*
+ * 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.ml.pipeline.stubs;
+
+import org.neo4j.gds.maxflow.MaxFlowMutateConfig;
+import org.neo4j.gds.procedures.algorithms.AlgorithmsProcedureFacade;
+import org.neo4j.gds.procedures.algorithms.pathfinding.MaxFlowMutateResult;
+import org.neo4j.gds.procedures.algorithms.stubs.MutateStub;
+
+public class MaxFlowStub extends AbstractStub<MaxFlowMutateConfig, MaxFlowMutateResult> {
+    protected MutateStub<MaxFlowMutateConfig, MaxFlowMutateResult> stub(AlgorithmsProcedureFacade facade) {
+        return facade.pathFinding().stubs().maxFlow();
+    }
+}

proc/path-finding/src/main/java/org/neo4j/gds/paths/maxflow/MaxFlowMutateProc.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.paths.maxflow;
+
+import org.neo4j.gds.procedures.GraphDataScienceProcedures;
+import org.neo4j.gds.procedures.algorithms.pathfinding.MaxFlowMutateResult;
+import org.neo4j.procedure.Context;
+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.gds.paths.maxflow.MaxFlowConstants.MAXFLOW_DESCRIPTION;
+import static org.neo4j.procedure.Mode.READ;
+
+public class MaxFlowMutateProc {
+    @Context
+    public GraphDataScienceProcedures facade;
+
+    @Procedure(value = "gds.maxFlow.mutate", mode = READ)
+    @Description(MAXFLOW_DESCRIPTION)
+    public Stream<MaxFlowMutateResult> maxFlow(
+        @Name(value = "graphName") String graphName,
+        @Name(value = "configuration", defaultValue = "{}") Map<String, Object> configuration
+    ) {
+        return facade.algorithms().pathFinding().maxFlowMutate(graphName, configuration);
+    }
+}