graphdatascience 1.20a1__tar.gz → 1.20a2__tar.gz

{graphdatascience-1.20a1/src/graphdatascience.egg-info → graphdatascience-1.20a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphdatascience
-Version: 1.20a1
+Version: 1.20a2
 Summary: A Python client for the Neo4j Graph Data Science (GDS) library
 Author-email: Neo4j <team-gds@neo4j.org>
 License-Expression: Apache-2.0

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/arrow_client/v2/mutation_client.py

@@ -10,11 +10,17 @@ class MutationClient:
     MUTATE_ENDPOINT = "v2/results.mutate"
 
     @staticmethod
-    def mutate_node_property(client: AuthenticatedArrowClient, job_id: str, mutate_property: str) -> MutateResult:
+    def mutate_node_property(
+        client: AuthenticatedArrowClient,
+        result_store_job_id: str,
+        mutate_property: str,
+        process_job_id: str | None = None,
+    ) -> MutateResult:
         return MutationClient._mutate(
             client=client,
-            job_id=job_id,
+            result_store_job_id=result_store_job_id,
             mutate_property=mutate_property,
+            process_job_id=process_job_id,
         )
 
     @staticmethod
@@ -26,7 +32,7 @@ class MutationClient:
     ) -> MutateResult:
         return MutationClient._mutate(
             client=client,
-            job_id=job_id,
+            result_store_job_id=job_id,
             mutate_property=mutate_property,
             mutate_relationship_type=mutate_relationship_type,
         )
@@ -34,13 +40,16 @@ class MutationClient:
     @staticmethod
     def _mutate(
         client: AuthenticatedArrowClient,
-        job_id: str,
+        result_store_job_id: str,
+        process_job_id: str | None = None,
         mutate_property: str | None = None,
         mutate_relationship_type: str | None = None,
     ) -> MutateResult:
         mutate_config = {
-            "jobId": job_id,
+            "jobId": result_store_job_id,
         }
+        if process_job_id:
+            mutate_config["processJobId"] = process_job_id
         if mutate_relationship_type:
             mutate_config["mutateRelationshipType"] = mutate_relationship_type
         if mutate_property:

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/api/catalog/graph_sampling_endpoints.py

@@ -7,6 +7,7 @@ from typing import NamedTuple, Type
 from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
+from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
 
 
 class GraphSamplingEndpoints(ABC):
@@ -146,6 +147,54 @@ class GraphSamplingEndpoints(ABC):
         """
         pass
 
+    @abstractmethod
+    def estimate(
+        self,
+        G: GraphV2,
+        start_nodes: list[int] | None = None,
+        restart_probability: float = 0.1,
+        sampling_ratio: float = 0.15,
+        node_label_stratification: bool = False,
+        relationship_weight_property: str | None = None,
+        relationship_types: list[str] = ALL_TYPES,
+        node_labels: list[str] = ALL_LABELS,
+        concurrency: int | None = None,
+    ) -> EstimationResult:
+        """
+        Estimate the memory consumption of a CNARW algorithm run.
+
+        Parameters
+        ----------
+        G
+            Graph object to use
+        start_nodes : list of int, optional
+            IDs of the initial set of nodes in the original graph from which the sampling random walks will start.
+            By default, a single node is chosen uniformly at random.
+        restart_probability : float, optional
+            The probability that a sampling random walk restarts from one of the start nodes.
+            Default is 0.1.
+        sampling_ratio : float, optional
+            The fraction of nodes in the original graph to be sampled.
+            Default is 0.15.
+        node_label_stratification : bool, optional
+            If true, preserves the node label distribution of the original graph.
+            Default is False.
+        relationship_weight_property
+            Name of the property to be used as weights.
+        relationship_types
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
+        node_labels
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
+        concurrency
+            Number of concurrent threads to use.
+
+        Returns
+        -------
+        EstimationResult
+            Memory estimation details
+        """
+        pass
+
 
 class GraphSamplingResult(BaseResult):
     graph_name: str

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/api/pathfinding/__init__.py

@@ -27,6 +27,12 @@ from graphdatascience.procedure_surface.api.pathfinding.max_flow_endpoints impor
     MaxFlowStatsResult,
     MaxFlowWriteResult,
 )
+from graphdatascience.procedure_surface.api.pathfinding.max_flow_min_cost_endpoints import (
+    MaxFlowMinCostEndpoints,
+    MaxFlowMinCostMutateResult,
+    MaxFlowMinCostStatsResult,
+    MaxFlowMinCostWriteResult,
+)
 from graphdatascience.procedure_surface.api.pathfinding.prize_steiner_tree_endpoints import (
     PrizeSteinerTreeEndpoints,
     PrizeSteinerTreeMutateResult,
@@ -105,6 +111,10 @@ __all__ = [
     "MaxFlowWriteResult",
     "MaxFlowStatsResult",
     "MaxFlowMutateResult",
+    "MaxFlowMinCostEndpoints",
+    "MaxFlowMinCostWriteResult",
+    "MaxFlowMinCostStatsResult",
+    "MaxFlowMinCostMutateResult",
     "PrizeSteinerTreeEndpoints",
     "PrizeSteinerTreeMutateResult",
     "PrizeSteinerTreeStatsResult",

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/api/pathfinding/max_flow_endpoints.py

@@ -9,9 +9,18 @@ from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.base_result import BaseResult
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
 from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
+from graphdatascience.procedure_surface.api.pathfinding.max_flow_min_cost_endpoints import MaxFlowMinCostEndpoints
 
 
 class MaxFlowEndpoints(ABC):
+    @property
+    @abstractmethod
+    def min_cost(self) -> MaxFlowMinCostEndpoints:
+        """
+        Container for Min-Cost Max Flow algorithm endpoints.
+        """
+        ...
+
     @abstractmethod
     def mutate(
         self,

graphdatascience-1.20a2/src/graphdatascience/procedure_surface/api/pathfinding/max_flow_min_cost_endpoints.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pandas import DataFrame
+
+from graphdatascience.graph.v2.graph_api import GraphV2
+from graphdatascience.procedure_surface.api.base_result import BaseResult
+from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
+from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
+
+
+class MaxFlowMinCostEndpoints(ABC):
+    @abstractmethod
+    def mutate(
+        self,
+        G: GraphV2,
+        source_nodes: list[int],
+        target_nodes: list[int],
+        mutate_property: str,
+        mutate_relationship_type: str,
+        *,
+        capacity_property: str | None = None,
+        node_capacity_property: str | None = None,
+        cost_property: str | None = None,
+        alpha: int = 6,
+        concurrency: int | None = None,
+        job_id: str | None = None,
+        log_progress: bool = True,
+        node_labels: list[str] = ALL_LABELS,
+        relationship_types: list[str] = ALL_TYPES,
+        sudo: bool = False,
+        username: str | None = None,
+    ) -> MaxFlowMinCostMutateResult:
+        """
+        Runs the Min-Cost Max Flow algorithm and stores the results in the graph catalog.
+
+        Parameters
+        ----------
+        G
+           Graph object to use
+        source_nodes
+            List of source node IDs.
+        target_nodes
+            List of target node IDs.
+        mutate_property
+            Name of the node property to store the results in.
+        mutate_relationship_type
+            Name of the relationship type to store the results in.
+        capacity_property
+            Name of the relationship property containing capacities.
+        node_capacity_property
+            Name of the node property containing capacities.
+        cost_property
+            Name of the relationship property containing costs.
+        alpha
+            Rate of cost-scaling in the refinement phase of the algorithm. Tuning can improve speed.
+        concurrency
+            Number of concurrent threads to use.
+        job_id
+            Identifier for the computation.
+        log_progress
+            Display progress logging.
+        node_labels
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
+        relationship_types
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
+        sudo
+            Disable the memory guard.
+        username
+            As an administrator, impersonate a different user for accessing their graphs.
+
+        Returns
+        -------
+        MaxFlowMinCostMutateResult
+            Algorithm metrics and statistics
+        """
+        pass
+
+    @abstractmethod
+    def stats(
+        self,
+        G: GraphV2,
+        source_nodes: list[int],
+        target_nodes: list[int],
+        *,
+        capacity_property: str | None = None,
+        node_capacity_property: str | None = None,
+        cost_property: str | None = None,
+        alpha: int = 6,
+        concurrency: int | None = None,
+        job_id: str | None = None,
+        log_progress: bool = True,
+        node_labels: list[str] = ALL_LABELS,
+        relationship_types: list[str] = ALL_TYPES,
+        sudo: bool = False,
+        username: str | None = None,
+    ) -> MaxFlowMinCostStatsResult:
+        """
+        Runs the Min-Cost Max Flow algorithm and returns statistics.
+
+        Parameters
+        ----------
+        G
+           Graph object to use
+        source_nodes
+            List of source node IDs.
+        target_nodes
+            List of target node IDs.
+        capacity_property
+            Name of the relationship property containing capacities.
+        node_capacity_property
+            Name of the node property containing capacities.
+        cost_property
+            Name of the relationship property containing costs.
+        alpha
+            Rate of cost-scaling in the refinement phase of the algorithm. Tuning can improve speed.
+        concurrency
+            Number of concurrent threads to use.
+        job_id
+            Identifier for the computation.
+        log_progress
+            Display progress logging.
+        node_labels
+            Filter the graph using the given node labels. Nodes with any of the given labels will be included.
+        relationship_types
+            Filter the graph using the given relationship types. Relationships with any of the given types will be included.
+        sudo
+            Disable the memory guard.
+        username
+            As an administrator, impersonate a different user for accessing their graphs.
+
+        Returns
+        -------
+        MaxFlowMinCostStatsResult
+            Algorithm metrics and statistics
+        """
+        pass
+
+    @abstractmethod
+    def stream(
+        self,
+        G: GraphV2,
+        source_nodes: list[int],
+        target_nodes: list[int],
+        *,
+        capacity_property: str | None = None,
+        node_capacity_property: str | None = None,
+        cost_property: str | None = None,
+        alpha: int = 6,
+        concurrency: int | None = None,
+        job_id: str | None = None,
+        log_progress: bool = True,
+        node_labels: list[str] = ALL_LABELS,
+        relationship_types: list[str] = ALL_TYPES,
+        sudo: bool = False,
+        username: str | None = None,
+    ) -> DataFrame:
+        """
+        Runs the Min-Cost Max Flow algorithm and streams the flows on relationships.
+
+        Returns
+        -------
+        DataFrame
+            Dataframe containing `source`, `target`, and `flow` per relationship.
+        """
+        pass
+
+    @abstractmethod
+    def write(
+        self,
+        G: GraphV2,
+        source_nodes: list[int],
+        target_nodes: list[int],
+        write_property: str,
+        write_relationship_type: str,
+        *,
+        capacity_property: str | None = None,
+        node_capacity_property: str | None = None,
+        cost_property: str | None = None,
+        alpha: int = 6,
+        concurrency: int | None = None,
+        job_id: str | None = None,
+        log_progress: bool = True,
+        node_labels: list[str] = ALL_LABELS,
+        relationship_types: list[str] = ALL_TYPES,
+        sudo: bool = False,
+        username: str | None = None,
+        write_concurrency: int | None = None,
+    ) -> MaxFlowMinCostWriteResult:
+        """
+        Runs the Min-Cost Max Flow algorithm and writes the results to the Neo4j database.
+
+        Returns
+        -------
+        MaxFlowMinCostWriteResult
+            Algorithm metrics and statistics
+        """
+        pass
+
+    @abstractmethod
+    def estimate(
+        self,
+        G: GraphV2 | dict[str, Any],
+        source_nodes: list[int],
+        target_nodes: list[int],
+        *,
+        capacity_property: str | None = None,
+        node_capacity_property: str | None = None,
+        cost_property: str | None = None,
+        alpha: int = 6,
+        concurrency: int | None = None,
+        node_labels: list[str] = ALL_LABELS,
+        relationship_types: list[str] = ALL_TYPES,
+    ) -> EstimationResult:
+        """
+        Estimate the memory consumption of an algorithm run.
+        """
+        pass
+
+
+class MaxFlowMinCostMutateResult(BaseResult):
+    total_flow: float
+    total_cost: float
+    pre_processing_millis: int
+    compute_millis: int
+    mutate_millis: int
+    relationships_written: int
+    configuration: dict[str, Any]
+
+
+class MaxFlowMinCostStatsResult(BaseResult):
+    total_flow: float
+    total_cost: float
+    pre_processing_millis: int
+    compute_millis: int
+    configuration: dict[str, Any]
+
+
+class MaxFlowMinCostWriteResult(BaseResult):
+    total_flow: float
+    total_cost: float
+    pre_processing_millis: int
+    compute_millis: int
+    write_millis: int
+    relationships_written: int
+    configuration: dict[str, Any]

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/api/pathfinding/steiner_tree_endpoints.py

@@ -70,7 +70,7 @@ class SteinerTreeEndpoints(ABC):
         source_node
             Node id to use as the starting point.
         target_nodes : list[int]
-            The list of target nodes (terminals) that must be connected.
+            List of target node IDs.
         relationship_weight_property
             Name of the property to be used as weights.
         delta : float, default=2.0
@@ -126,7 +126,7 @@ class SteinerTreeEndpoints(ABC):
         source_node
             Node id to use as the starting point.
         target_nodes : list[int]
-            The list of target nodes (terminals) that must be connected.
+            List of target node IDs.
         relationship_weight_property
             Name of the property to be used as weights.
         delta : float, default=2.0
@@ -188,7 +188,7 @@ class SteinerTreeEndpoints(ABC):
         source_node
             Node id to use as the starting point.
         target_nodes : list[int]
-            The list of target nodes (terminals) that must be connected.
+            List of target node IDs.
         relationship_weight_property
             Name of the property to be used as weights.
         delta : float, default=2.0
@@ -251,7 +251,7 @@ class SteinerTreeEndpoints(ABC):
         source_node
             Node id to use as the starting point.
         target_nodes : list[int]
-            The list of target nodes (terminals) that must be connected.
+            List of target node IDs.
         relationship_weight_property
             Name of the property to be used as weights.
         delta : float, default=2.0
@@ -305,7 +305,7 @@ class SteinerTreeEndpoints(ABC):
         source_node
             Node id to use as the starting point.
         target_nodes : list[int]
-            The list of target nodes (terminals) that must be connected.
+            List of target node IDs.
         relationship_weight_property
             Name of the property to be used as weights.
         delta : float, default=2.0

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/arrow/catalog/graph_sampling_arrow_endpoints.py

@@ -9,7 +9,9 @@ from graphdatascience.procedure_surface.api.catalog.graph_sampling_endpoints imp
     GraphWithSamplingResult,
 )
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
+from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
 from graphdatascience.procedure_surface.arrow.catalog.graph_backend_arrow import get_graph
+from graphdatascience.procedure_surface.arrow.endpoints_helper_base import EndpointsHelperBase
 from graphdatascience.procedure_surface.utils.config_converter import ConfigConverter
 
 
@@ -17,6 +19,7 @@ class GraphSamplingArrowEndpoints(GraphSamplingEndpoints):
     def __init__(self, arrow_client: AuthenticatedArrowClient, show_progress: bool = False):
         self._arrow_client = arrow_client
         self._show_progress = show_progress
+        self._helper = EndpointsHelperBase(arrow_client, show_progress=show_progress)
 
     def rwr(
         self,
@@ -105,3 +108,28 @@ class GraphSamplingArrowEndpoints(GraphSamplingEndpoints):
             get_graph(graph_name, self._arrow_client),
             GraphSamplingResult(**JobClient.get_summary(self._arrow_client, job_id)),
         )
+
+    def estimate(
+        self,
+        G: GraphV2,
+        start_nodes: list[int] | None = None,
+        restart_probability: float = 0.1,
+        sampling_ratio: float = 0.15,
+        node_label_stratification: bool = False,
+        relationship_weight_property: str | None = None,
+        relationship_types: list[str] = ALL_TYPES,
+        node_labels: list[str] = ALL_LABELS,
+        concurrency: int | None = None,
+    ) -> EstimationResult:
+        config = ConfigConverter.convert_to_gds_config(
+            start_nodes=start_nodes,
+            restart_probability=restart_probability,
+            sampling_ratio=sampling_ratio,
+            node_label_stratification=node_label_stratification,
+            relationship_weight_property=relationship_weight_property,
+            relationship_types=relationship_types,
+            node_labels=node_labels,
+            concurrency=concurrency,
+        )
+
+        return self._helper.estimate("v2/graph.sample.cnarw.estimate", G, config)

{graphdatascience-1.20a1 → graphdatascience-1.20a2}/src/graphdatascience/procedure_surface/arrow/pathfinding/max_flow_arrow_endpoints.py

@@ -7,12 +7,16 @@ from graphdatascience.arrow_client.v2.remote_write_back_client import RemoteWrit
 from graphdatascience.graph.v2.graph_api import GraphV2
 from graphdatascience.procedure_surface.api.default_values import ALL_LABELS, ALL_TYPES
 from graphdatascience.procedure_surface.api.estimation_result import EstimationResult
+from graphdatascience.procedure_surface.api.pathfinding import MaxFlowMinCostEndpoints
 from graphdatascience.procedure_surface.api.pathfinding.max_flow_endpoints import (
     MaxFlowEndpoints,
     MaxFlowMutateResult,
     MaxFlowStatsResult,
     MaxFlowWriteResult,
 )
+from graphdatascience.procedure_surface.arrow.pathfinding.max_flow_min_cost_arrow_endpoints import (
+    MaxFlowMinCostArrowEndpoints,
+)
 from graphdatascience.procedure_surface.arrow.relationship_endpoints_helper import RelationshipEndpointsHelper
 from graphdatascience.procedure_surface.arrow.stream_result_mapper import (
     map_max_flow_stream_result,
@@ -26,10 +30,17 @@ class MaxFlowArrowEndpoints(MaxFlowEndpoints):
         write_back_client: RemoteWriteBackClient | None = None,
         show_progress: bool = True,
     ):
+        self._min_cost_endpoints = MaxFlowMinCostArrowEndpoints(
+            arrow_client, write_back_client, show_progress=show_progress
+        )
         self._relationship_endpoints = RelationshipEndpointsHelper(
             arrow_client, write_back_client, show_progress=show_progress
         )
 
+    @property
+    def min_cost(self) -> MaxFlowMinCostEndpoints:
+        return self._min_cost_endpoints
+
     def mutate(
         self,
         G: GraphV2,