Max-flow mutate facade

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

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,

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

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

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

@@ -469,6 +469,7 @@ class OpenGdsProcedureSmokeTest extends BaseProcTest {
         "gds.louvain.write",
         "gds.louvain.write.estimate",
 
+        "gds.maxFlow.mutate",
         "gds.maxFlow.stats",
         "gds.maxFlow.stream",
 
@@ -632,7 +633,7 @@ void countShouldMatch() {
         );
 
         // If you find yourself updating this count, please also update the count in SmokeTest.kt
-        int expectedCount = 470;
+        int expectedCount = 471;
         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);
+    }
+}

proc/path-finding/src/test/java/org/neo4j/gds/paths/maxflow/MaxFlowMutateProcTest.java

@@ -0,0 +1,116 @@
+/*
+ * 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.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.neo4j.gds.BaseProcTest;
+import org.neo4j.gds.GdsCypher;
+import org.neo4j.gds.RelationshipType;
+import org.neo4j.gds.catalog.GraphProjectProc;
+import org.neo4j.gds.core.Username;
+import org.neo4j.gds.core.loading.GraphStoreCatalog;
+import org.neo4j.gds.extension.IdFunction;
+import org.neo4j.gds.extension.Inject;
+import org.neo4j.gds.extension.Neo4jGraph;
+
+import java.util.Optional;
+import java.util.concurrent.atomic.LongAdder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class MaxFlowMutateProcTest extends BaseProcTest {
+
+    @Neo4jGraph
+    static final String DB_CYPHER = """
+        CREATE
+            (a:Node {id: 0}),
+            (b:Node {id: 1}),
+            (c:Node {id: 2}),
+            (d:Node {id: 3}),
+            (e:Node {id: 4}),
+            (a)-[:R {w: 4.0}]->(d),
+            (b)-[:R {w: 3.0}]->(a),
+            (c)-[:R {w: 2.0}]->(a),
+            (c)-[:R {w: 0.0}]->(b),
+            (d)-[:R {w: 5.0}]->(e)
+        """;
+
+    @Inject
+    private IdFunction idFunction;
+
+    @BeforeEach
+    void setup() throws Exception {
+        registerProcedures(MaxFlowMutateProc.class, GraphProjectProc.class);
+        var createQuery = GdsCypher.call(DEFAULT_GRAPH_NAME)
+            .graphProject()
+            .withAnyLabel()
+            .withRelationshipProperty("w")
+            .yields();
+        runQuery(createQuery);
+    }
+
+    @Test
+    void testMutate() {
+        String query = GdsCypher.call(DEFAULT_GRAPH_NAME)
+            .algo("gds.maxFlow")
+            .mutateMode()
+            .addParameter("sourceNodes", idFunction.of("a"))
+            .addParameter("capacityProperty", "w")
+            .addParameter("targetNodes", idFunction.of("e"))
+            .addParameter("mutateRelationshipType", "MAX_FLOW")
+            .addParameter("mutateProperty", "flow")
+            .yields("totalFlow", "relationshipsWritten");
+
+        var rowCount = runQueryWithRowConsumer(query,
+        resultRow -> {
+
+            assertThat(resultRow.get("totalFlow")).isInstanceOf(Double.class);
+            assertThat(resultRow.get("relationshipsWritten")).isInstanceOf(Long.class);
+
+            assertThat((double) resultRow.get("totalFlow")).isEqualTo(4D);
+            assertThat((long) resultRow.get("relationshipsWritten")).isEqualTo(2L);
+        });
+        assertThat(rowCount).isEqualTo(1L);
+
+        var mutatedGraph = GraphStoreCatalog
+            .get(Username.EMPTY_USERNAME.username(), db.databaseName(), DEFAULT_GRAPH_NAME)
+            .graphStore()
+            .getGraph(RelationshipType.of("MAX_FLOW"), Optional.of("flow"));
+
+        assertThat(mutatedGraph.relationshipCount()).isEqualTo(2L);
+
+        var relationshipCounter = new LongAdder();
+        mutatedGraph.forEachRelationship(mutatedGraph.toMappedNodeId(idFunction.of("a")), 0, (s, t, w) -> {
+            assertThat(t).isEqualTo(mutatedGraph.toMappedNodeId(idFunction.of("d")));
+            assertThat(w).isEqualTo(4D);
+            relationshipCounter.increment();
+            return true;
+        });
+        mutatedGraph.forEachRelationship(mutatedGraph.toMappedNodeId(idFunction.of("d")), 0, (s, t, w) -> {
+            assertThat(t).isEqualTo(mutatedGraph.toMappedNodeId(idFunction.of("e")));
+            assertThat(w).isEqualTo(4D);
+            relationshipCounter.increment();
+            return true;
+        });
+        assertThat(relationshipCounter.longValue()).isEqualTo(2L);
+
+    }
+}

proc/path-finding/src/test/java/org/neo4j/gds/paths/maxflow/MaxFlowStreamProcTest.java

@@ -33,16 +33,6 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-/**
- * a                a
- * 1 /   \ 2          /  \
- * /     \          /    \
- * b --3-- c        b      c
- * |       |   =>   |      |
- * 4       5        |      |
- * |       |        |      |
- * d --6-- e        d      e
- */
 class MaxFlowStreamProcTest extends BaseProcTest {
 
     @Neo4jGraph(offsetIds = true)