From d9c80fa3ae412e4ed465a47858549b9ee7a182d2 Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 09:01:00 -0700 Subject: [PATCH 01/16] First commit --- docs/cugraph/source/nx_cugraph/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cugraph/source/nx_cugraph/index.rst b/docs/cugraph/source/nx_cugraph/index.rst index 110300c183..fe26134156 100644 --- a/docs/cugraph/source/nx_cugraph/index.rst +++ b/docs/cugraph/source/nx_cugraph/index.rst @@ -26,7 +26,7 @@ By simply `installing and enabling nx-cugraph Date: Fri, 4 Oct 2024 10:38:38 -0700 Subject: [PATCH 02/16] Updates to filetree and table --- .../source/basics/cugraph_cascading.md | 53 ----- docs/cugraph/source/basics/cugraph_intro.md | 68 ------- docs/cugraph/source/basics/index.rst | 73 ++++++- docs/cugraph/source/basics/nx_transition.rst | 181 ------------------ docs/cugraph/source/index.rst | 16 +- docs/cugraph/source/nx_cugraph/index.rst | 27 ++- docs/cugraph/source/top_toc.rst | 2 + 7 files changed, 92 insertions(+), 328 deletions(-) delete mode 100644 docs/cugraph/source/basics/cugraph_cascading.md delete mode 100644 docs/cugraph/source/basics/cugraph_intro.md delete mode 100644 docs/cugraph/source/basics/nx_transition.rst diff --git a/docs/cugraph/source/basics/cugraph_cascading.md b/docs/cugraph/source/basics/cugraph_cascading.md deleted file mode 100644 index bad3d7fa6a..0000000000 --- a/docs/cugraph/source/basics/cugraph_cascading.md +++ /dev/null @@ -1,53 +0,0 @@ - -# Method Cascading and cuGraph - -BLUF: cuGraph does not support method cascading - -[Method Cascading](https://en.wikipedia.org/wiki/Method_cascading) is a popular, and useful, functional programming concept and is a great way to make code more readable. Python supports method cascading ... _for the most part_. There are a number of Python built-in classes that do not support cascading. - -An example, from cuDF, is a sequence of method calls for loading data and then finding the largest values from a subset of the data (yes there are other ways this could be done): - -``` -gdf = cudf.from_pandas(df).query(‘val > 200’).nlargest(‘va’3) -``` - -cuGraph does not support method cascading for two main reasons: (1) the object-oriented nature of the Graph data object leverages in-place methods, and (2) the fact that algorithms operate on graphs rather than graphs running algorithms. - -## Graph Data Objects -cuGraph follows an object-oriented design for the Graph objects. Users create a Graph and can then add data to object, but every add method call returns `None`. - -_Why Inplace methods?_
-cuGraph focuses on the big graph problems where there are 10s of millions to trillions of edges (Giga bytes to Terabytes of data). At that scale, creating a copy of the data becomes memory inefficient. - -_Why not return `self` rather than `None`?_
-It would be simple to modify the methods to return `self` rather than `None`, however it opens the methods to misinterpretation. Consider the following code: - -``` -# cascade flow - makes sense -G = cugraph.Graph().from_cudf_edgelist(df) - -# non-cascaded code can be confusing -G = cugraph.Graph() -G2 = G.from_cudf_edgelist(df) -G3 = G.from_cudf_edgelist(df2) -``` -The confusion with the non-cascade code is that G, G1, and G3 are all the same object with the same data. Users could be confused since it is not obvious that changing G3 would also change both G2 and G. To prevent confusion, cuGraph has opted to not return `self`. - -_Why not add a flag "return_self" to the methods?_
-``` -# cascade flow - makes sense -G = cugraph.Graph().from_cudf_edgelist(df, return_self=True) -``` -The fact that a developer would explicitly add a "return_self" flag to the method indicates that the developer is aware that the method returns None. It is just as easy for the developer to use a non-cascading workflow. - -### Algorithms -Algorithms operate on graph objects. -``` -cugraph.pagerank(G) and not G.pagerank() -``` -This pattern allows cuGraph to maintain a particular object-oriented model, where Graph objects simply maintain graph data, and algorithm functions operate independently on Graph objects. While this model has benefits that simplify the overall design and its usability in the majority of use cases, it does mean that the developer cannot cascade graph creation into an algorithm call. - -``` -# will not work -G = cugraph.Graph().from_cudf_edgelist(df).pagerank() -``` diff --git a/docs/cugraph/source/basics/cugraph_intro.md b/docs/cugraph/source/basics/cugraph_intro.md deleted file mode 100644 index 7ad2825604..0000000000 --- a/docs/cugraph/source/basics/cugraph_intro.md +++ /dev/null @@ -1,68 +0,0 @@ - -# cuGraph Introduction -The Data Scientist has a collection of techniques within their -proverbial toolbox. Data engineering, statistical analysis, and -machine learning are among the most commonly known. However, there -are numerous cases where the focus of the analysis is on the -relationship between data elements. In those cases, the data is best -represented as a graph. Graph analysis, also called network analysis, -is a collection of algorithms for answering questions posed against -graph data. Graph analysis is not new. - -The first graph problem was posed by Euler in 1736, the [Seven Bridges of -Konigsberg](https://en.wikipedia.org/wiki/Seven_Bridges_of_K%C3%B6nigsberg), -and laid the foundation for the mathematical field of graph theory. -The application of graph analysis covers a wide variety of fields, including -marketing, biology, physics, computer science, sociology, and cyber to name a few. - -RAPIDS cuGraph is a library of graph algorithms that seamlessly integrates -into the RAPIDS data science ecosystem and allows the data scientist to easily -call graph algorithms using data stored in a GPU DataFrame, NetworkX Graphs, or even -CuPy or SciPy sparse Matrix. - - -## Vision -The vision of RAPIDS cuGraph is to ___make graph analysis ubiquitous to the -point that users just think in terms of analysis and not technologies or -frameworks___. This is a goal that many of us on the cuGraph team have been -working on for almost twenty years. Many of the early attempts focused on -solving one problem or using one technique. Those early attempts worked for -the initial goal but tended to break as the scope changed (e.g., shifting -to solving a dynamic graph problem with a static graph solution). The limiting -factors usually came down to compute power, ease-of-use, or choosing a data -structure that was not suited for all problems. NVIDIA GPUs, CUDA, and RAPIDS -have totally changed the paradigm and the goal of an accelerated unified graph -analytic library is now possible. - -The compute power of the latest NVIDIA GPUs (RAPIDS supports Pascal and later -GPU architectures) make graph analytics 1000x faster on average over NetworkX. -Moreover, the internal memory speed within a GPU allows cuGraph to rapidly -switch the data structure to best suit the needs of the analytic rather than -being restricted to a single data structure. cuGraph is working with several -frameworks for both static and dynamic graph data structures so that we always -have a solution to any graph problem. Since Python has emerged as the de facto -language for data science, allowing interactivity and the ability to run graph -analytics in Python makes cuGraph familiar and approachable. RAPIDS wraps all -the graph analytic goodness mentioned above with the ability to perform -high-speed ETL, statistics, and machine learning. To make things even better, -RAPIDS and DASK allows cuGraph to scale to multiple GPUs to support -multi-billion edge graphs. - - -## Terminology - -cuGraph is a collection of GPU accelerated graph algorithms and graph utility -functions. The application of graph analysis covers a lot of areas. -For Example: -* [Network Science](https://en.wikipedia.org/wiki/Network_science) -* [Complex Network](https://en.wikipedia.org/wiki/Complex_network) -* [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory) -* [Social Network Analysis](https://en.wikipedia.org/wiki/Social_network_analysis) - -cuGraph does not favor one field over another. Our developers span the -breadth of fields with the focus being to produce the best graph library -possible. However, each field has its own argot (jargon) for describing the -graph (or network). In our documentation, we try to be consistent. In Python -documentation we will mostly use the terms __Node__ and __Edge__ to better -match NetworkX preferred term use, as well as other Python-based tools. At -the CUDA/C layer, we favor the mathematical terms of __Vertex__ and __Edge__. diff --git a/docs/cugraph/source/basics/index.rst b/docs/cugraph/source/basics/index.rst index 7bba301b65..7ad2825604 100644 --- a/docs/cugraph/source/basics/index.rst +++ b/docs/cugraph/source/basics/index.rst @@ -1,11 +1,68 @@ -====== -Basics -====== +# cuGraph Introduction +The Data Scientist has a collection of techniques within their +proverbial toolbox. Data engineering, statistical analysis, and +machine learning are among the most commonly known. However, there +are numerous cases where the focus of the analysis is on the +relationship between data elements. In those cases, the data is best +represented as a graph. Graph analysis, also called network analysis, +is a collection of algorithms for answering questions posed against +graph data. Graph analysis is not new. -.. toctree:: - :maxdepth: 2 +The first graph problem was posed by Euler in 1736, the [Seven Bridges of +Konigsberg](https://en.wikipedia.org/wiki/Seven_Bridges_of_K%C3%B6nigsberg), +and laid the foundation for the mathematical field of graph theory. +The application of graph analysis covers a wide variety of fields, including +marketing, biology, physics, computer science, sociology, and cyber to name a few. - cugraph_intro - nx_transition - cugraph_cascading +RAPIDS cuGraph is a library of graph algorithms that seamlessly integrates +into the RAPIDS data science ecosystem and allows the data scientist to easily +call graph algorithms using data stored in a GPU DataFrame, NetworkX Graphs, or even +CuPy or SciPy sparse Matrix. + + +## Vision +The vision of RAPIDS cuGraph is to ___make graph analysis ubiquitous to the +point that users just think in terms of analysis and not technologies or +frameworks___. This is a goal that many of us on the cuGraph team have been +working on for almost twenty years. Many of the early attempts focused on +solving one problem or using one technique. Those early attempts worked for +the initial goal but tended to break as the scope changed (e.g., shifting +to solving a dynamic graph problem with a static graph solution). The limiting +factors usually came down to compute power, ease-of-use, or choosing a data +structure that was not suited for all problems. NVIDIA GPUs, CUDA, and RAPIDS +have totally changed the paradigm and the goal of an accelerated unified graph +analytic library is now possible. + +The compute power of the latest NVIDIA GPUs (RAPIDS supports Pascal and later +GPU architectures) make graph analytics 1000x faster on average over NetworkX. +Moreover, the internal memory speed within a GPU allows cuGraph to rapidly +switch the data structure to best suit the needs of the analytic rather than +being restricted to a single data structure. cuGraph is working with several +frameworks for both static and dynamic graph data structures so that we always +have a solution to any graph problem. Since Python has emerged as the de facto +language for data science, allowing interactivity and the ability to run graph +analytics in Python makes cuGraph familiar and approachable. RAPIDS wraps all +the graph analytic goodness mentioned above with the ability to perform +high-speed ETL, statistics, and machine learning. To make things even better, +RAPIDS and DASK allows cuGraph to scale to multiple GPUs to support +multi-billion edge graphs. + + +## Terminology + +cuGraph is a collection of GPU accelerated graph algorithms and graph utility +functions. The application of graph analysis covers a lot of areas. +For Example: +* [Network Science](https://en.wikipedia.org/wiki/Network_science) +* [Complex Network](https://en.wikipedia.org/wiki/Complex_network) +* [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory) +* [Social Network Analysis](https://en.wikipedia.org/wiki/Social_network_analysis) + +cuGraph does not favor one field over another. Our developers span the +breadth of fields with the focus being to produce the best graph library +possible. However, each field has its own argot (jargon) for describing the +graph (or network). In our documentation, we try to be consistent. In Python +documentation we will mostly use the terms __Node__ and __Edge__ to better +match NetworkX preferred term use, as well as other Python-based tools. At +the CUDA/C layer, we favor the mathematical terms of __Vertex__ and __Edge__. diff --git a/docs/cugraph/source/basics/nx_transition.rst b/docs/cugraph/source/basics/nx_transition.rst deleted file mode 100644 index 9da2fe9b49..0000000000 --- a/docs/cugraph/source/basics/nx_transition.rst +++ /dev/null @@ -1,181 +0,0 @@ -************************************** -NetworkX by calling cuGraph Algorithms -************************************** - - -*Note: this is a work in progress and will be updatred and changed as we better flesh out -compatibility issues* - -Latest Update -############# - -Last Update: March 7th, 2024 -Release: 24.04 - -**CuGraph is now a registered backend for networkX. This is described in the following blog: -`Accelerating NetworkX on NVIDIA GPUs for High Performance Graph Analytics -`_ - - -Easy Path – Use NetworkX Graph Objects, Accelerated Algorithms -############################################################## - -Rather than updating all of your existing code, simply update the calls to -graph algorithms by replacing the module name. This allows all the complicated -ETL code to be unchanged while still seeing significate performance -improvements. Again this will be deprecated since networkX dispatching to nx_cugraph -has many advantages. - - -.. image:: ../images/Nx_Cg_1.png - :width: 600 - -It is that easy. All algorithms in cuGraph support a NetworkX graph object as -input and match the NetworkX API list of arguments. - -Currently, cuGraph accepts both NetworkX Graph and DiGraph objects. We will be -adding support for Bipartite graph and Multigraph over the next few releases. - -Differences in Algorithms -########################## - -Since cuGraph currently does not support attribute rich graphs, those -algorithms that return simple scores (centrality, clustering, etc.) best match -the NetworkX process. Algorithms that return a subgraph will do so without -any additional attributes on the nodes or edges. - -Algorithms that exactly match -***************************** - -+-------------------------------+------------------------+ -| Algorithm | Differences | -+===============================+========================+ -| Core Number | None | -+-------------------------------+------------------------+ -| HITS | None | -+-------------------------------+------------------------+ -| PageRank | None | -+-------------------------------+------------------------+ -| Personal PageRank | None | -+-------------------------------+------------------------+ -| Strongly Connected Components | None | -+-------------------------------+------------------------+ -| Weakly Connected Components | None | -+-------------------------------+------------------------+ - -| - - - -Algorithms that do not copy over additional attributes -************************************************************************ - -+-------------------------------+-------------------------------------+ -| Algorithm | Differences | -+===============================+=====================================+ -| K-Truss | Does not copy over attributes | -+-------------------------------+-------------------------------------+ -| K-Core | Does not copy over attributes | -+-------------------------------+-------------------------------------+ -| Subgraph Extraction | Does not copy over attributes | -+-------------------------------+-------------------------------------+ - -| - - -Algorithms not in NetworkX -************************** - -+--------------------------------------+----------------------------+ -| Algorithm | Differences | -+======================================+============================+ -| Ensemble Clustering for Graphs (ECG) | Currently not in NetworkX | -+--------------------------------------+----------------------------+ -| Force Atlas 2 | Currently not in NetworkX | -+--------------------------------------+----------------------------+ -| Leiden | Currently not in NetworkX | -+--------------------------------------+----------------------------+ -| Louvain | Currently not in NetworkX | -+--------------------------------------+----------------------------+ -| Overlap coefficient | Currently not in NetworkX | -+--------------------------------------+----------------------------+ -| Spectral Clustering | Currently not in NetworkX | -+--------------------------------------+----------------------------+ - -| - - -Algorithm where not all arguments are supported -*********************************************** - -+----------------------------+-------------------------------------------------+ -| Algorithm | Differences | -+============================+=================================================+ -|Betweenness Centrality | weight is currently not supported – ignored | -| | endpoints is currently not supported – ignored | -+----------------------------+-------------------------------------------------+ -|Edge Betweenness Centrality | weight is currently not supported – ignored | -+----------------------------+-------------------------------------------------+ -| Katz Centrality | beta is currently not supported – ignored | -| | max_iter defaults to 100 versus 1000 | -+----------------------------+-------------------------------------------------+ - -| - -Algorithms where the results are different -****************************************** - - -For example, the NetworkX traversal algorithms typically return a generator -rather than a dictionary. - - -+----------------------------+-------------------------------------------------+ -| Algorithm | Differences | -+============================+=================================================+ -| Triangle Counting | this algorithm simply returns the total number | -| | of triangle and not the number per vertex | -| | (on roadmap to update) | -+----------------------------+-------------------------------------------------+ -| Jaccard coefficient | Currently we only do a 1-hop computation rather | -| | than an all-pairs. Fix is on roadmap | -+----------------------------+-------------------------------------------------+ -| Breadth First Search (BFS) | Returns a Pandas DataFrame with: | -| | [vertex][distance][predecessor] | -+----------------------------+-------------------------------------------------+ -| Single Source | Returns a Pandas DataFrame with: | -| Shortest Path (SSSP) | [vertex][distance][predecessor] | -+----------------------------+-------------------------------------------------+ - -| - -Graph Building -############## - -The biggest difference between NetworkX and cuGraph is with how Graph objects -are built. NetworkX, for the most part, stores graph data in a dictionary. -That structure allows easy insertion of new records. Consider the following -code for building a NetworkX Graph:: - - # Read the node data - df = pd.read_csv( data_file) - - # Construct graph from edge list. - G = nx.DiGraph() - - for row in df.iterrows(): - G.add_edge( - row[1]["1"], row[1]["2"], count=row[1]["3"] - ) - - -The code block is perfectly fine for NetworkX. However, the process of iterating over the dataframe and adding one node at a time is problematic for GPUs and something that we try and avoid. cuGraph stores data in columns (i.e. arrays). Resizing an array requires allocating a new array one element larger, copying the data, and adding the new value. That is not very efficient. - -If your code follows the above model of inserting one element at a time, the we suggest either rewriting that code or using it as is within NetworkX and just accelerating the algorithms with cuGraph. - -Now, if your code bulk loads the data from Pandas, then RAPIDS can accelerate that process by orders of magnitude. - -.. image:: ../images/Nx_Cg_2.png - :width: 600 - -The above cuGraph code will create cuGraph.Graph object and not a NetworkX.Graph object. diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 259a36b8fd..062156e034 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -20,10 +20,10 @@ a supported GPU. Getting started with cuGraph Required hardware/software for cuGraph and `RAPIDS `_ - * NVIDIA GPU, Volta architecture or later, with `compute capability 7.0+`_ + * NVIDIA GPU, Volta architecture or later, with `compute capability 7.0+ `_ * CUDA 11.2-11.8, 12.0-12.5 * Python version 3.10, 3.11, or 3.12 - * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. NetworkX version 3.4 or newer is recommended. (`see below <#cugraph-using-networkx-code>`). + * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. NetworkX version 3.4 or newer is recommended. (`see below `_). Installation The latest RAPIDS System Requirements documentation is located `here `_. @@ -41,9 +41,9 @@ This includes several ways to set up cuGraph * From Windows - * `Conda `_ - * `Docker `_ - * `pip `_ + * `Conda `_ + * `Docker `_ + * `pip `_ cuGraph Using NetworkX Code @@ -67,11 +67,11 @@ their existing NetworkX code using an NVIDIA GPU and cuGraph. # Call cugraph.degree_centrality vertex_bc = cugraph.degree_centrality(G) -There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ +There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ has many examples of loading graph data and running algorithms in Jupyter notebooks. The `cuGraph test code _` contain python scripts setting up and calling cuGraph algorithms. -A simple example of `testing the degree centrality algorithm `_ -is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well. +A simple example of `testing the degree centrality algorithm `_ +is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well. .. toctree:: :maxdepth: 2 diff --git a/docs/cugraph/source/nx_cugraph/index.rst b/docs/cugraph/source/nx_cugraph/index.rst index fe26134156..8e726e53e1 100644 --- a/docs/cugraph/source/nx_cugraph/index.rst +++ b/docs/cugraph/source/nx_cugraph/index.rst @@ -1,10 +1,11 @@ nx-cugraph ----------- -nx-cugraph is a `NetworkX backend `_ that provides **GPU acceleration** to many popular NetworkX algorithms. +nx-cugraph is a NetworkX backend that provides **GPU acceleration** to many popular NetworkX algorithms. By simply `installing and enabling nx-cugraph `_, users can see significant speedup on workflows where performance is hindered by the default NetworkX implementation. With ``nx-cugraph``, users can have GPU-based, large-scale performance **without** changing their familiar and easy-to-use NetworkX code. +In ``bc_demo.py`` .. code-block:: python import pandas as pd @@ -16,6 +17,12 @@ By simply `installing and enabling nx-cugraph Date: Fri, 4 Oct 2024 11:02:28 -0700 Subject: [PATCH 03/16] Update --- .../cugraph/source/nx_cugraph/how-it-works.md | 56 ++++++++++--------- .../cugraph/source/nx_cugraph/installation.md | 4 +- 2 files changed, 32 insertions(+), 28 deletions(-) diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index f9dc5af67a..20cd376ef1 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -4,35 +4,28 @@ NetworkX has the ability to **dispatch function calls to separately-installed th NetworkX backends let users experience improved performance and/or additional functionality without changing their NetworkX Python code. Examples include backends that provide algorithm acceleration using GPUs, parallel processing, graph database integration, and more. -While NetworkX is a pure-Python implementation with minimal to no dependencies, backends may be written in other languages and require specialized hardware and/or OS support, additional software dependencies, or even separate services. Installation instructions vary based on the backend, and additional information can be found from the individual backend project pages listed in the NetworkX Backend Gallery. +While NetworkX is a pure-Python implementation with minimal to no dependencies, backends may be written in other languages and require specialized hardware and/or OS support, additional software dependencies, or even separate services. Installation instructions vary based on the backend, and additional information can be found from the individual backend project pages. ![nxcg-execution-flow](../_static/nxcg-execution-diagram.jpg) ## Enabling nx-cugraph -NetworkX will use nx-cugraph as the graph analytics backend if any of the -following are used: +NetworkX will use `nx-cugraph` as the backend if any of the following are used: -### `NETWORKX_BACKEND_PRIORITY` environment variable. +### `NX_CUGRAPH_AUTOCONFIG` environment variable. -The `NETWORKX_BACKEND_PRIORITY` environment variable can be used to have NetworkX automatically dispatch to specified backends. This variable can be set to a single backend name, or a comma-separated list of backends ordered using the priority which NetworkX should try. If a NetworkX function is called that nx-cugraph supports, NetworkX will redirect the function call to nx-cugraph automatically, or fall back to the next backend in the list if provided, or run using the default NetworkX implementation. See [NetworkX Backends and Configs](https://networkx.org/documentation/stable/reference/backends.html). +The `NX_CUGRAPH_AUTOCONFIG` environment variable can be used to configure NetworkX for full zero code change acceleration using `nx-cugraph`. If a NetworkX function is called that `nx-cugraph` supports, NetworkX will redirect the function call to `nx-cugraph` automatically, or fall back to either another backend if enabled or the default NetworkX implementation. See the [NetworkX documentation on backends](https://networkx.org/documentation/stable/reference/backends.html) for configuring NetworkX manually. -For example, this setting will have NetworkX use nx-cugraph for any function called by the script supported by nx-cugraph, and the default NetworkX implementation for all others. ``` -bash> NETWORKX_BACKEND_PRIORITY=cugraph python my_networkx_script.py -``` - -This example will have NetworkX use nx-cugraph for functions it supports, then try other_backend if nx-cugraph does not support them, and finally the default NetworkX implementation if not supported by either backend: -``` -bash> NETWORKX_BACKEND_PRIORITY="cugraph,other_backend" python my_networkx_script.py +bash> NX_CUGRAPH_AUTOCONFIG=True python my_networkx_script.py ``` ### `backend=` keyword argument To explicitly specify a particular backend for an API, use the `backend=` keyword argument. This argument takes precedence over the -`NETWORKX_BACKEND_PRIORITY` environment variable. This requires anyone +`NX_CUGRAPH_AUTOCONFIG` environment variable. This requires anyone running code that uses the `backend=` keyword argument to have the specified backend installed. @@ -49,9 +42,9 @@ requires the user to write code for a specific backend, and therefore requires the backend to be installed, but has the advantage of ensuring a particular behavior without the potential for runtime conversions. -To use type-based dispatching with nx-cugraph, the user must import the backend +To use type-based dispatching with `nx-cugraph`, the user must import the backend directly in their code to access the utilities provided to create a Graph -instance specifically for the nx-cugraph backend. +instance specifically for the `nx-cugraph` backend. Example: ```python @@ -84,31 +77,42 @@ G = nx.from_pandas_edgelist(df, source="src", target="dst") Run the command: ``` user@machine:/# ipython bc_demo.ipy + +CPU times: user 7min 36s, sys: 5.22 s, total: 7min 41s +Wall time: 7min 41s ``` You will observe a run time of approximately 7 minutes...more or less depending on your CPU. Run the command again, this time specifying cugraph as the NetworkX backend. +```bash +user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython bc_demo.ipy + +CPU times: user 4.14 s, sys: 1.13 s, total: 5.27 s +Wall time: 5.32 s ``` -user@machine:/# NETWORKX_BACKEND_PRIORITY=cugraph ipython bc_demo.ipy -``` -This run will be much faster, typically around 20 seconds depending on your GPU. -``` -user@machine:/# NETWORKX_BACKEND_PRIORITY=cugraph ipython bc_demo.ipy +This run will be much faster, typically around 4 seconds depending on your GPU. +```bash +user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython bc_demo.ipy ``` -There is also an option to cache the graph conversion to GPU. This can dramatically improve performance when running multiple algorithms on the same graph. Caching is enabled by default for NetworkX versions 3.4 and later, but if using an older version, set "NETWORKX_CACHE_CONVERTED_GRAPHS=True" +There is also an option to cache the graph conversion to GPU. This can dramatically improve performance when running multiple algorithms on the same graph. Caching is enabled by default for NetworkX versions 3.4 and later, but if using an older version, set `NETWORKX_CACHE_CONVERTED_GRAPHS=True`. ``` -NETWORKX_BACKEND_PRIORITY=cugraph NETWORKX_CACHE_CONVERTED_GRAPHS=True ipython bc_demo.ipy +user@machine:/# NX_CUGRAPH_AUTOCONFIG=cugraph NETWORKX_CACHE_CONVERTED_GRAPHS=True ipython bc_demo.ipy ``` When running Python interactively, the cugraph backend can be specified as an argument in the algorithm call. For example: -``` +```python nx.betweenness_centrality(cit_patents_graph, k=k, backend="cugraph") ``` +*Note, the examples above were run using the following specs*: +```{note} +NetworkX 3.4 +nx-cugraph 24.10 +CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM +GPU: NVIDIA Quadro RTX 8000 80GB RAM +``` -The latest list of algorithms supported by nx-cugraph can be found [here](https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#algorithms) or in the next section. - ---- +The latest list of algorithms supported by `nx-cugraph` can be found in the [cugraph documentation](https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#algorithms), or in the next section. diff --git a/docs/cugraph/source/nx_cugraph/installation.md b/docs/cugraph/source/nx_cugraph/installation.md index 8d221f16fe..03a8ac2596 100644 --- a/docs/cugraph/source/nx_cugraph/installation.md +++ b/docs/cugraph/source/nx_cugraph/installation.md @@ -1,4 +1,4 @@ -# Getting Started +# Installing nx-cugraph This guide describes how to install ``nx-cugraph`` and use it in your workflows. @@ -14,7 +14,7 @@ This guide describes how to install ``nx-cugraph`` and use it in your workflows. More details about system requirements can be found in the [RAPIDS System Requirements Documentation](https://docs.rapids.ai/install#system-req). -## Installing nx-cugraph +## Installing Packages Read the [RAPIDS Quick Start Guide](https://docs.rapids.ai/install) to learn more about installing all RAPIDS libraries. From ef9a379a41fda2eb09d6ca96827c0bbcf1d68c0b Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 11:09:41 -0700 Subject: [PATCH 04/16] Fix links, formatting, etc --- docs/cugraph/source/nx_cugraph/benchmarks.md | 4 +- .../cugraph/source/nx_cugraph/how-it-works.md | 2 + .../nx_cugraph/supported-algorithms.rst | 69 ++++++++++--------- readme_pages/pylibcugraph.md | 2 +- 4 files changed, 40 insertions(+), 37 deletions(-) diff --git a/docs/cugraph/source/nx_cugraph/benchmarks.md b/docs/cugraph/source/nx_cugraph/benchmarks.md index 31d5e5b09e..f016a829f2 100644 --- a/docs/cugraph/source/nx_cugraph/benchmarks.md +++ b/docs/cugraph/source/nx_cugraph/benchmarks.md @@ -15,7 +15,7 @@ class="title-ref"> ## Reproducing Benchmarks -Below are the steps to reproduce the results on your workstation. These are documented in this [README](https://github.com/rapidsai/cugraph/blob/HEAD/benchmarks/nx-cugraph/pytest-based). +Below are the steps to reproduce the results on your own. 1. Clone the latest @@ -25,4 +25,4 @@ Below are the steps to reproduce the results on your workstation. These are docu 4. Install the latest `nx-cugraph` by following the [guide](installation.md) -5. Follow the instructions written in the README here: `cugraph/benchmarks/nx-cugraph/pytest-based/` +5. Follow the instructions written in the README [here](https://github.com/rapidsai/cugraph/blob/HEAD/benchmarks/nx-cugraph/pytest-based) diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index 20cd376ef1..09b6f6ca8e 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -11,6 +11,8 @@ While NetworkX is a pure-Python implementation with minimal to no dependencies, ## Enabling nx-cugraph +It is recommended to use `networkx>=3.4` for optimal compatibility, but `nx-cugraph` will work with `3.0+`. + NetworkX will use `nx-cugraph` as the backend if any of the following are used: ### `NX_CUGRAPH_AUTOCONFIG` environment variable. diff --git a/docs/cugraph/source/nx_cugraph/supported-algorithms.rst b/docs/cugraph/source/nx_cugraph/supported-algorithms.rst index b21ef7bb66..8f57c02b24 100644 --- a/docs/cugraph/source/nx_cugraph/supported-algorithms.rst +++ b/docs/cugraph/source/nx_cugraph/supported-algorithms.rst @@ -2,7 +2,7 @@ Supported Algorithms ===================== The nx-cugraph backend to NetworkX connects -`pylibcugraph <../../readme_pages/pylibcugraph.md>`_ (cuGraph's low-level Python +`pylibcugraph `_ (cuGraph's low-level Python interface to its CUDA-based graph analytics library) and `CuPy `_ (a GPU-accelerated array library) to NetworkX's familiar and easy-to-use API. @@ -209,6 +209,40 @@ Algorithms | is_tree | +---------------------+ + +Utilities +------- + ++-------------------------+ +| **Classes** | ++=========================+ +| is_negatively_weighted | ++-------------------------+ + ++----------------------+ +| **Convert** | ++======================+ +| from_dict_of_lists | ++----------------------+ +| to_dict_of_lists | ++----------------------+ + ++--------------------------+ +| **Convert Matrix** | ++==========================+ +| from_pandas_edgelist | ++--------------------------+ +| from_scipy_sparse_array | ++--------------------------+ + ++-----------------------------------+ +| **Relabel** | ++===================================+ +| convert_node_labels_to_integers | ++-----------------------------------+ +| relabel_nodes | ++-----------------------------------+ + Generators ------------ @@ -316,39 +350,6 @@ Generators | les_miserables_graph | +-------------------------------+ -Other -------- - -+-------------------------+ -| **Classes** | -+=========================+ -| is_negatively_weighted | -+-------------------------+ - -+----------------------+ -| **Convert** | -+======================+ -| from_dict_of_lists | -+----------------------+ -| to_dict_of_lists | -+----------------------+ - -+--------------------------+ -| **Convert Matrix** | -+==========================+ -| from_pandas_edgelist | -+--------------------------+ -| from_scipy_sparse_array | -+--------------------------+ - -+-----------------------------------+ -| **Relabel** | -+===================================+ -| convert_node_labels_to_integers | -+-----------------------------------+ -| relabel_nodes | -+-----------------------------------+ - To request nx-cugraph backend support for a NetworkX API that is not listed above, visit the `cuGraph GitHub repo `_. diff --git a/readme_pages/pylibcugraph.md b/readme_pages/pylibcugraph.md index 3bb552141e..fcb5a62493 100644 --- a/readme_pages/pylibcugraph.md +++ b/readme_pages/pylibcugraph.md @@ -4,7 +4,7 @@


-CuGraph pylibcugraph +cuGraph pylibcugraph

Part of [RAPIDS](https://rapids.ai) cuGraph, pylibcugraph is a wrapper around the cuGraph C API. It is aimed more at integrators instead of algorithm writers or end users like Data Scientists. Most of the cuGraph python API uses pylibcugraph to efficiently run algorithms by removing much of the overhead of the python-centric implementation, relying more on cython instead. Pylibcugraph is intended for applications that require a tighter integration with cuGraph at the Python layer with fewer dependencies. From ae4813fde2c0a49732a3b1169b9004e0046b55d1 Mon Sep 17 00:00:00 2001 From: acostadon Date: Fri, 4 Oct 2024 14:22:24 -0400 Subject: [PATCH 05/16] added original toc and fixed up landing page --- docs/cugraph/source/index.rst | 55 ++++++++++++++++++++--------------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 062156e034..5bb819fcd4 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -10,20 +10,18 @@ Introduction ~~~~~~~~~~~~ cuGraph is a library of graph algorithms that seamlessly integrates into the RAPIDS data science ecosystem and allows the data scientist to easily call -graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or even -CuPy or SciPy sparse Matrices. Our major integration effort with NetworkX -allows for **zero code change** GPU acceleration through the use of the -nx-cugraph backend. NetworkX and the nx-cugraph backend offer a seamless -transition to GPU accelerated graph analytics for NetworkX users with access to -a supported GPU. +graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or +even CuPy or SciPy sparse Matrices. Our major integration effort with NetworkX allows +**zero code change** use of nx-cuGraph as a backend for NetworkX calls. This offers a near seamless +transition to GPU accelerated graph analytics to NetworkX users with access to a supported GPU. Getting started with cuGraph Required hardware/software for cuGraph and `RAPIDS `_ - * NVIDIA GPU, Volta architecture or later, with `compute capability 7.0+ `_ + * NVIDIA GPU, Volta architecture or later, with `compute capability `_ 7.0+ * CUDA 11.2-11.8, 12.0-12.5 * Python version 3.10, 3.11, or 3.12 - * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. NetworkX version 3.4 or newer is recommended. (`see below `_). + * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. Version 3.3 is required to use `NetworkX Configs `_ `see below <#cugraph-using-networkx-code>`_. Installation The latest RAPIDS System Requirements documentation is located `here `_. @@ -39,27 +37,30 @@ This includes several ways to set up cuGraph **Note: Windows use of RAPIDS depends on prior installation of** `WSL2 `_. -* From Windows +* From windows - * `Conda `_ - * `Docker `_ - * `pip `_ + * `Conda `_ + * `Docker `_ + * `pip `_ -cuGraph Using NetworkX Code +Build From Source -cuGraph is now available as a NetworkX backend using `nx-cugraph `_. -nx-cugraph offers NetworkX users a **zero code change** option to accelerate -their existing NetworkX code using an NVIDIA GPU and cuGraph. +To build from source, check each RAPIDS GitHub README for set up and build instructions. Further links are provided in the `selector tool `_. +If additional help is needed reach out on our `Slack Channel `_. +CuGraph Using NetworkX Code +While the steps above are required to use the full suite of cuGraph graph analytics, cuGraph is now supported as a NetworkX backend using `nx-cugraph `_. +Nx-cugraph offers those with existing NetworkX code, a **zero code change** option with a growing list of supported algorithms. Cugraph API Example .. code-block:: python + # Import needed libraries import cugraph import cudf - + # Create an instance of the popular Zachary Karate Club graph from cugraph.datasets import karate G = karate.get_graph() @@ -67,17 +68,25 @@ their existing NetworkX code using an NVIDIA GPU and cuGraph. # Call cugraph.degree_centrality vertex_bc = cugraph.degree_centrality(G) -There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ + +There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ has many examples of loading graph data and running algorithms in Jupyter notebooks. -The `cuGraph test code _` contain python scripts setting up and calling cuGraph algorithms. -A simple example of `testing the degree centrality algorithm `_ -is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well. +The `cuGraph test code `_ contains python scripts setting up and calling cuGraph algorithms. +A simple example of `testing the degree centrality algorithm `_ +is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well .. toctree:: :maxdepth: 2 - top_toc - + basics/index + nx_cugraph/index + installation/index + tutorials/index + graph_support/index + wholegraph/index + references/index + api_docs/index + Indices and tables ================== From 31cd494a2c064e465096625380a1a82187698168 Mon Sep 17 00:00:00 2001 From: rlratzel Date: Fri, 4 Oct 2024 13:45:33 -0500 Subject: [PATCH 06/16] Revert "added original toc and fixed up landing page" This reverts commit ae4813fde2c0a49732a3b1169b9004e0046b55d1. --- docs/cugraph/source/index.rst | 55 +++++++++++++++-------------------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 5bb819fcd4..062156e034 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -10,18 +10,20 @@ Introduction ~~~~~~~~~~~~ cuGraph is a library of graph algorithms that seamlessly integrates into the RAPIDS data science ecosystem and allows the data scientist to easily call -graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or -even CuPy or SciPy sparse Matrices. Our major integration effort with NetworkX allows -**zero code change** use of nx-cuGraph as a backend for NetworkX calls. This offers a near seamless -transition to GPU accelerated graph analytics to NetworkX users with access to a supported GPU. +graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or even +CuPy or SciPy sparse Matrices. Our major integration effort with NetworkX +allows for **zero code change** GPU acceleration through the use of the +nx-cugraph backend. NetworkX and the nx-cugraph backend offer a seamless +transition to GPU accelerated graph analytics for NetworkX users with access to +a supported GPU. Getting started with cuGraph Required hardware/software for cuGraph and `RAPIDS `_ - * NVIDIA GPU, Volta architecture or later, with `compute capability `_ 7.0+ + * NVIDIA GPU, Volta architecture or later, with `compute capability 7.0+ `_ * CUDA 11.2-11.8, 12.0-12.5 * Python version 3.10, 3.11, or 3.12 - * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. Version 3.3 is required to use `NetworkX Configs `_ `see below <#cugraph-using-networkx-code>`_. + * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. NetworkX version 3.4 or newer is recommended. (`see below `_). Installation The latest RAPIDS System Requirements documentation is located `here `_. @@ -37,30 +39,27 @@ This includes several ways to set up cuGraph **Note: Windows use of RAPIDS depends on prior installation of** `WSL2 `_. -* From windows +* From Windows - * `Conda `_ - * `Docker `_ - * `pip `_ + * `Conda `_ + * `Docker `_ + * `pip `_ -Build From Source +cuGraph Using NetworkX Code -To build from source, check each RAPIDS GitHub README for set up and build instructions. Further links are provided in the `selector tool `_. -If additional help is needed reach out on our `Slack Channel `_. +cuGraph is now available as a NetworkX backend using `nx-cugraph `_. +nx-cugraph offers NetworkX users a **zero code change** option to accelerate +their existing NetworkX code using an NVIDIA GPU and cuGraph. -CuGraph Using NetworkX Code -While the steps above are required to use the full suite of cuGraph graph analytics, cuGraph is now supported as a NetworkX backend using `nx-cugraph `_. -Nx-cugraph offers those with existing NetworkX code, a **zero code change** option with a growing list of supported algorithms. Cugraph API Example .. code-block:: python - # Import needed libraries import cugraph import cudf - + # Create an instance of the popular Zachary Karate Club graph from cugraph.datasets import karate G = karate.get_graph() @@ -68,25 +67,17 @@ Nx-cugraph offers those with existing NetworkX code, a **zero code change** opti # Call cugraph.degree_centrality vertex_bc = cugraph.degree_centrality(G) - -There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ +There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ has many examples of loading graph data and running algorithms in Jupyter notebooks. -The `cuGraph test code `_ contains python scripts setting up and calling cuGraph algorithms. -A simple example of `testing the degree centrality algorithm `_ -is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well +The `cuGraph test code _` contain python scripts setting up and calling cuGraph algorithms. +A simple example of `testing the degree centrality algorithm `_ +is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well. .. toctree:: :maxdepth: 2 - basics/index - nx_cugraph/index - installation/index - tutorials/index - graph_support/index - wholegraph/index - references/index - api_docs/index - + top_toc + Indices and tables ================== From f21753d382500d728b5454ee672bca709b5395f7 Mon Sep 17 00:00:00 2001 From: rlratzel Date: Fri, 4 Oct 2024 13:51:34 -0500 Subject: [PATCH 07/16] Restores clobbered changes, restores TOC, removes unused toc .rst file. --- docs/cugraph/source/index.rst | 9 ++++++++- docs/cugraph/source/top_toc.rst | 15 --------------- 2 files changed, 8 insertions(+), 16 deletions(-) delete mode 100644 docs/cugraph/source/top_toc.rst diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 062156e034..c93d16e442 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -76,7 +76,14 @@ is a good place to start. Some of these show `multi-GPU tests/examples Date: Fri, 4 Oct 2024 14:06:18 -0700 Subject: [PATCH 08/16] 2nd review changes --- docs/cugraph/source/index.rst | 67 +++++++++++-------- docs/cugraph/source/nx_cugraph/benchmarks.md | 6 +- docs/cugraph/source/nx_cugraph/faqs.md | 5 -- .../cugraph/source/nx_cugraph/how-it-works.md | 45 ++++++------- docs/cugraph/source/nx_cugraph/index.rst | 27 +++++--- .../cugraph/source/nx_cugraph/installation.md | 2 +- 6 files changed, 80 insertions(+), 72 deletions(-) delete mode 100644 docs/cugraph/source/nx_cugraph/faqs.md diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index c93d16e442..389bb4ed08 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -11,22 +11,33 @@ Introduction cuGraph is a library of graph algorithms that seamlessly integrates into the RAPIDS data science ecosystem and allows the data scientist to easily call graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or even -CuPy or SciPy sparse Matrices. Our major integration effort with NetworkX -allows for **zero code change** GPU acceleration through the use of the -nx-cugraph backend. NetworkX and the nx-cugraph backend offer a seamless -transition to GPU accelerated graph analytics for NetworkX users with access to -a supported GPU. +CuPy or SciPy sparse Matrices. +--------------------------- +cuGraph Using NetworkX Code +--------------------------- + +cuGraph is now available as a NetworkX backend using `nx-cugraph `_. +Our major integration effort with NetworkX offers NetworkX users a **zero code change** option to accelerate +their existing NetworkX code using an NVIDIA GPU and cuGraph. + +If you would like to continue using default cuGraph, then continue reading down below. + +---------------------------- Getting started with cuGraph +---------------------------- Required hardware/software for cuGraph and `RAPIDS `_ * NVIDIA GPU, Volta architecture or later, with `compute capability 7.0+ `_ * CUDA 11.2-11.8, 12.0-12.5 * Python version 3.10, 3.11, or 3.12 - * NetworkX version 3.0 or newer in order to use use the nx-cuGraph backend. NetworkX version 3.4 or newer is recommended. (`see below `_). + * NetworkX version 3.0 or newer in order to use use the `nx-cugraph` backend. NetworkX version 3.4 or newer is recommended. (`see more details `_). +++++++++++++ Installation -The latest RAPIDS System Requirements documentation is located `here `_. +++++++++++++ + +Please see the latest `RAPIDS System Requirements documentation `_. This includes several ways to set up cuGraph @@ -45,14 +56,6 @@ This includes several ways to set up cuGraph * `Docker `_ * `pip `_ - -cuGraph Using NetworkX Code - -cuGraph is now available as a NetworkX backend using `nx-cugraph `_. -nx-cugraph offers NetworkX users a **zero code change** option to accelerate -their existing NetworkX code using an NVIDIA GPU and cuGraph. - - Cugraph API Example .. code-block:: python @@ -67,26 +70,32 @@ their existing NetworkX code using an NVIDIA GPU and cuGraph. # Call cugraph.degree_centrality vertex_bc = cugraph.degree_centrality(G) -There are several resources containing cuGraph examples, `the cuGraph notebook repository `_ -has many examples of loading graph data and running algorithms in Jupyter notebooks. -The `cuGraph test code _` contain python scripts setting up and calling cuGraph algorithms. -A simple example of `testing the degree centrality algorithm `_ -is a good place to start. Some of these show `multi-GPU tests/examples `_ with larger data sets as well. + There are several resources containing cuGraph examples, the cuGraph `notebook repository `_ has many examples of loading graph data and running algorithms in Jupyter notebooks. + The cuGraph `test code `_ contains script examples of setting up and calling cuGraph algorithms. + + A simple example of `testing the degree centrality algorithm `_ is a good place to start. There are also `multi-GPU examples `_ with larger data sets as well. + +---- + +~~~~~~~~~~~~~~~~~ +Table of Contents +~~~~~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 - basics/index - nx_cugraph/index - installation/index - tutorials/index - graph_support/index - wholegraph/index - references/index - api_docs/index + basics/index + nx_cugraph/index + installation/index + tutorials/index + graph_support/index + wholegraph/index + references/index + api_docs/index +~~~~~~~~~~~~~~~~~~ Indices and tables -================== +~~~~~~~~~~~~~~~~~~ * :ref:`genindex` * :ref:`search` diff --git a/docs/cugraph/source/nx_cugraph/benchmarks.md b/docs/cugraph/source/nx_cugraph/benchmarks.md index f016a829f2..45085c133a 100644 --- a/docs/cugraph/source/nx_cugraph/benchmarks.md +++ b/docs/cugraph/source/nx_cugraph/benchmarks.md @@ -19,10 +19,8 @@ Below are the steps to reproduce the results on your own. 1. Clone the latest -2. Follow the instructions to build an environment +2. Follow the instructions to build and activate an environment -3. Activate the environment - -4. Install the latest `nx-cugraph` by following the [guide](installation.md) +4. Install the latest `nx-cugraph` by following the [Installation Guide](installation.md) 5. Follow the instructions written in the README [here](https://github.com/rapidsai/cugraph/blob/HEAD/benchmarks/nx-cugraph/pytest-based) diff --git a/docs/cugraph/source/nx_cugraph/faqs.md b/docs/cugraph/source/nx_cugraph/faqs.md deleted file mode 100644 index dee943d190..0000000000 --- a/docs/cugraph/source/nx_cugraph/faqs.md +++ /dev/null @@ -1,5 +0,0 @@ -# FAQ - - > **1. Is `nx-cugraph` able to run across multiple GPUs?** - -nx-cugraph currently does not support multi-GPU. Multi-GPU support may be added to a future release of nx-cugraph, but consider [cugraph](https://docs.rapids.ai/api/cugraph/stable) for multi-GPU accelerated graph analytics in Python today. diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index 09b6f6ca8e..0bcf1f128b 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -4,14 +4,13 @@ NetworkX has the ability to **dispatch function calls to separately-installed th NetworkX backends let users experience improved performance and/or additional functionality without changing their NetworkX Python code. Examples include backends that provide algorithm acceleration using GPUs, parallel processing, graph database integration, and more. -While NetworkX is a pure-Python implementation with minimal to no dependencies, backends may be written in other languages and require specialized hardware and/or OS support, additional software dependencies, or even separate services. Installation instructions vary based on the backend, and additional information can be found from the individual backend project pages. - +While NetworkX is a pure-Python implementation, backends may be written to use other libraries and even specialized hardware. `nx-cugraph` is a NetworkX backend that uses RAPIDS cuGraph and NVIDIA GPUs to significantly improve NetworkX performance. ![nxcg-execution-flow](../_static/nxcg-execution-diagram.jpg) ## Enabling nx-cugraph -It is recommended to use `networkx>=3.4` for optimal compatibility, but `nx-cugraph` will work with `3.0+`. +It is recommended to use `networkx>=3.4` for optimal zero code change performance, but `nx-cugraph` will also work with `networkx 3.0+`. NetworkX will use `nx-cugraph` as the backend if any of the following are used: @@ -54,7 +53,10 @@ import networkx as nx import nx_cugraph as nxcg G = nx.Graph() -... + +# populate the graph +# ... + nxcg_G = nxcg.from_networkx(G) # conversion happens once here nx.betweenness_centrality(nxcg_G, k=1000) # nxcg Graph type causes cugraph backend # to be used, no conversion necessary @@ -93,28 +95,21 @@ user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython bc_demo.ipy CPU times: user 4.14 s, sys: 1.13 s, total: 5.27 s Wall time: 5.32 s ``` -This run will be much faster, typically around 4 seconds depending on your GPU. -```bash -user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython bc_demo.ipy -``` -There is also an option to cache the graph conversion to GPU. This can dramatically improve performance when running multiple algorithms on the same graph. Caching is enabled by default for NetworkX versions 3.4 and later, but if using an older version, set `NETWORKX_CACHE_CONVERTED_GRAPHS=True`. -``` -user@machine:/# NX_CUGRAPH_AUTOCONFIG=cugraph NETWORKX_CACHE_CONVERTED_GRAPHS=True ipython bc_demo.ipy -``` +This run will be much faster, typically around 5 seconds depending on your GPU. -When running Python interactively, the cugraph backend can be specified as an argument in the algorithm call. +*Note, the examples above were run using the following specs*: +
-For example: -```python -nx.betweenness_centrality(cit_patents_graph, k=k, backend="cugraph") -``` + NetworkX 3.4 -*Note, the examples above were run using the following specs*: -```{note} -NetworkX 3.4 -nx-cugraph 24.10 -CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM -GPU: NVIDIA Quadro RTX 8000 80GB RAM -``` + nx-cugraph 24.10 + + CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM + + GPU: NVIDIA Quadro RTX 8000 80GB RAM + +
+ +--- -The latest list of algorithms supported by `nx-cugraph` can be found in the [cugraph documentation](https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#algorithms), or in the next section. +The latest list of algorithms supported by `nx-cugraph` can be found in [GitHub](https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#algorithms), or in the [Supported Algorithms Section](supported-algorithms.md). diff --git a/docs/cugraph/source/nx_cugraph/index.rst b/docs/cugraph/source/nx_cugraph/index.rst index 8e726e53e1..8ac4019b97 100644 --- a/docs/cugraph/source/nx_cugraph/index.rst +++ b/docs/cugraph/source/nx_cugraph/index.rst @@ -1,11 +1,14 @@ nx-cugraph ----------- -nx-cugraph is a NetworkX backend that provides **GPU acceleration** to many popular NetworkX algorithms. +``nx-cugraph`` is a NetworkX backend that provides **GPU acceleration** to many popular NetworkX algorithms. -By simply `installing and enabling nx-cugraph `_, users can see significant speedup on workflows where performance is hindered by the default NetworkX implementation. With ``nx-cugraph``, users can have GPU-based, large-scale performance **without** changing their familiar and easy-to-use NetworkX code. +By simply `installing and enabling nx-cugraph `_, users can see significant speedup on workflows where performance is hindered by the default NetworkX implementation. + +Users can have GPU-based, large-scale performance **without** changing their familiar and easy-to-use NetworkX code. + +.. centered:: Timed result from running the following code snippet (called ``demo.ipy``, showing NetworkX with vs. without ``nx-cugraph``) -In ``bc_demo.py`` .. code-block:: python import pandas as pd @@ -17,12 +20,21 @@ In ``bc_demo.py`` %time result = nx.betweenness_centrality(G, k=10) -.. code-block:: bash - user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython bc_demo.ipy +:: + + user@machine:/# ipython demo.ipy + CPU times: user 7min 36s, sys: 5.22 s, total: 7min 41s + Wall time: 7min 41s + + +:: + + user@machine:/# NX_CUGRAPH_AUTOCONFIG=True ipython demo.ipy CPU times: user 4.14 s, sys: 1.13 s, total: 5.27 s Wall time: 5.32 s + .. figure:: ../_static/colab.png :width: 200px :target: https://nvda.ws/4drM4re @@ -33,7 +45,7 @@ In ``bc_demo.py`` +--------------------------------------------------------------------------------------------------------+ | **Zero Code Change Acceleration** | | | -| Just set the environment variable ``NX_CUGRAPH_AUTOCONFIG=True`` to enable nx-cugraph in NetworkX. | +| Just set the environment variable ``NX_CUGRAPH_AUTOCONFIG=True`` to enable ``nx-cugraph`` in NetworkX. | +--------------------------------------------------------------------------------------------------------+ | **Run the same code on CPU or GPU** | | | @@ -49,7 +61,6 @@ Quick Start `_ to get up-and-running with ``nx-c :caption: Contents: how-it-works - supported-algorithms installation + supported-algorithms benchmarks - faqs diff --git a/docs/cugraph/source/nx_cugraph/installation.md b/docs/cugraph/source/nx_cugraph/installation.md index 03a8ac2596..a816801d00 100644 --- a/docs/cugraph/source/nx_cugraph/installation.md +++ b/docs/cugraph/source/nx_cugraph/installation.md @@ -10,7 +10,7 @@ This guide describes how to install ``nx-cugraph`` and use it in your workflows. - **Volta architecture or later NVIDIA GPU, with [compute capability](https://developer.nvidia.com/cuda-gpus) 7.0+** - **[CUDA](https://docs.nvidia.com/cuda/index.html) 11.2, 11.4, 11.5, 11.8, 12.0, 12.2, or 12.5** - **Python >= 3.10** - - **[NetworkX](https://networkx.org/documentation/stable/install.html#) >= 3.0 (version 3.2 or higher recommended)** + - **[NetworkX](https://networkx.org/documentation/stable/install.html#) >= 3.0 (version 3.4 or higher recommended)** More details about system requirements can be found in the [RAPIDS System Requirements Documentation](https://docs.rapids.ai/install#system-req). From f5db17ffe6b0f83a50efa212f898623ce6767a68 Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 14:10:50 -0700 Subject: [PATCH 09/16] Updates --- docs/cugraph/source/index.rst | 2 +- docs/cugraph/source/nx_cugraph/how-it-works.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 389bb4ed08..5a8560ed48 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -21,7 +21,7 @@ cuGraph is now available as a NetworkX backend using `nx-cugraph `_. If you would like to continue using default cuGraph, then continue down below. ---------------------------- Getting started with cuGraph diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index 0bcf1f128b..4a002b0cdb 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -98,7 +98,7 @@ Wall time: 5.32 s This run will be much faster, typically around 5 seconds depending on your GPU. *Note, the examples above were run using the following specs*: -
+
NetworkX 3.4 From f0918d77a97b56ab0cbda8b873abcb322559e94d Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 14:12:17 -0700 Subject: [PATCH 10/16] Updates --- docs/cugraph/source/basics/index.rst | 13 +++++++++---- docs/cugraph/source/index.rst | 2 +- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/cugraph/source/basics/index.rst b/docs/cugraph/source/basics/index.rst index 7ad2825604..42f435c49d 100644 --- a/docs/cugraph/source/basics/index.rst +++ b/docs/cugraph/source/basics/index.rst @@ -1,5 +1,7 @@ +==================== +cuGraph Introduction +==================== -# cuGraph Introduction The Data Scientist has a collection of techniques within their proverbial toolbox. Data engineering, statistical analysis, and machine learning are among the most commonly known. However, there @@ -20,8 +22,10 @@ into the RAPIDS data science ecosystem and allows the data scientist to easily call graph algorithms using data stored in a GPU DataFrame, NetworkX Graphs, or even CuPy or SciPy sparse Matrix. +------------------- +Vision +------------------- -## Vision The vision of RAPIDS cuGraph is to ___make graph analysis ubiquitous to the point that users just think in terms of analysis and not technologies or frameworks___. This is a goal that many of us on the cuGraph team have been @@ -48,8 +52,9 @@ high-speed ETL, statistics, and machine learning. To make things even better, RAPIDS and DASK allows cuGraph to scale to multiple GPUs to support multi-billion edge graphs. - -## Terminology +------------------- +Terminology +------------------- cuGraph is a collection of GPU accelerated graph algorithms and graph utility functions. The application of graph analysis covers a lot of areas. diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 5a8560ed48..f5ed5ef81c 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -21,7 +21,7 @@ cuGraph is now available as a NetworkX backend using `nx-cugraph `_. If you would like to continue using default cuGraph, then continue down below. +Check out `zero code change accelerated NetworkX `_. If you would like to continue using standard cuGraph, then continue down below. ---------------------------- Getting started with cuGraph From 69e291e2e906c39abb0962b976bc46d932126970 Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 14:12:44 -0700 Subject: [PATCH 11/16] Remove package --- docs/cugraph/source/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index f5ed5ef81c..603d249f3b 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -31,7 +31,6 @@ Required hardware/software for cuGraph and `RAPIDS `_ * CUDA 11.2-11.8, 12.0-12.5 * Python version 3.10, 3.11, or 3.12 - * NetworkX version 3.0 or newer in order to use use the `nx-cugraph` backend. NetworkX version 3.4 or newer is recommended. (`see more details `_). ++++++++++++ Installation From 792e21c7f6a27a906bd1bd586ac4e42c7e87e26f Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 14:16:23 -0700 Subject: [PATCH 12/16] Fix formatting --- docs/cugraph/source/nx_cugraph/how-it-works.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index 4a002b0cdb..c7d2e6aa84 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -97,15 +97,13 @@ Wall time: 5.32 s ``` This run will be much faster, typically around 5 seconds depending on your GPU. +
+ *Note, the examples above were run using the following specs*: -
NetworkX 3.4 - nx-cugraph 24.10 - CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM - GPU: NVIDIA Quadro RTX 8000 80GB RAM
From 1872c0f7b9595abff25c524b05ddccc8953988be Mon Sep 17 00:00:00 2001 From: Ralph Liu Date: Fri, 4 Oct 2024 14:35:11 -0700 Subject: [PATCH 13/16] Final review --- docs/cugraph/source/basics/{index.rst => index.md} | 12 +++--------- docs/cugraph/source/index.rst | 2 +- docs/cugraph/source/nx_cugraph/how-it-works.md | 10 +++++----- 3 files changed, 9 insertions(+), 15 deletions(-) rename docs/cugraph/source/basics/{index.rst => index.md} (95%) diff --git a/docs/cugraph/source/basics/index.rst b/docs/cugraph/source/basics/index.md similarity index 95% rename from docs/cugraph/source/basics/index.rst rename to docs/cugraph/source/basics/index.md index 42f435c49d..36aad5166b 100644 --- a/docs/cugraph/source/basics/index.rst +++ b/docs/cugraph/source/basics/index.md @@ -1,6 +1,4 @@ -==================== -cuGraph Introduction -==================== +# cuGraph Introduction The Data Scientist has a collection of techniques within their proverbial toolbox. Data engineering, statistical analysis, and @@ -22,9 +20,7 @@ into the RAPIDS data science ecosystem and allows the data scientist to easily call graph algorithms using data stored in a GPU DataFrame, NetworkX Graphs, or even CuPy or SciPy sparse Matrix. -------------------- -Vision -------------------- +## Vision The vision of RAPIDS cuGraph is to ___make graph analysis ubiquitous to the point that users just think in terms of analysis and not technologies or @@ -52,9 +48,7 @@ high-speed ETL, statistics, and machine learning. To make things even better, RAPIDS and DASK allows cuGraph to scale to multiple GPUs to support multi-billion edge graphs. -------------------- -Terminology -------------------- +## Terminology cuGraph is a collection of GPU accelerated graph algorithms and graph utility functions. The application of graph analysis covers a lot of areas. diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 603d249f3b..592c680bcb 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -21,7 +21,7 @@ cuGraph is now available as a NetworkX backend using `nx-cugraph `_. If you would like to continue using standard cuGraph, then continue down below. +Check out `zero code change accelerated NetworkX `_. If you would like to continue using standard cuGraph, then continue down below. ---------------------------- Getting started with cuGraph diff --git a/docs/cugraph/source/nx_cugraph/how-it-works.md b/docs/cugraph/source/nx_cugraph/how-it-works.md index c7d2e6aa84..5696688d1b 100644 --- a/docs/cugraph/source/nx_cugraph/how-it-works.md +++ b/docs/cugraph/source/nx_cugraph/how-it-works.md @@ -97,14 +97,14 @@ Wall time: 5.32 s ``` This run will be much faster, typically around 5 seconds depending on your GPU. -
+
*Note, the examples above were run using the following specs*: - NetworkX 3.4 - nx-cugraph 24.10 - CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM - GPU: NVIDIA Quadro RTX 8000 80GB RAM +    *NetworkX 3.4*
+    *nx-cugraph 24.10*
+    *CPU: Intel(R) Xeon(R) Gold 6128 CPU @ 3.40GHz 45GB RAM*
+    *GPU: NVIDIA Quadro RTX 8000 80GB RAM*
From e01c86f328c58ee86af67705a64809dd8d14483c Mon Sep 17 00:00:00 2001 From: rlratzel Date: Fri, 4 Oct 2024 16:49:51 -0500 Subject: [PATCH 14/16] Removes mention of NetworkX graphs as input to cugraph, since that is deprecated. --- docs/cugraph/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index 592c680bcb..f07b546769 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -10,8 +10,8 @@ Introduction ~~~~~~~~~~~~ cuGraph is a library of graph algorithms that seamlessly integrates into the RAPIDS data science ecosystem and allows the data scientist to easily call -graph algorithms using data stored in GPU DataFrames, NetworkX Graphs, or even -CuPy or SciPy sparse Matrices. +graph algorithms using data stored in Pandas/cuDF DataFrames or CuPy/SciPy +sparse matrices. --------------------------- cuGraph Using NetworkX Code @@ -71,9 +71,9 @@ This includes several ways to set up cuGraph There are several resources containing cuGraph examples, the cuGraph `notebook repository `_ has many examples of loading graph data and running algorithms in Jupyter notebooks. The cuGraph `test code `_ contains script examples of setting up and calling cuGraph algorithms. - + A simple example of `testing the degree centrality algorithm `_ is a good place to start. There are also `multi-GPU examples `_ with larger data sets as well. - + ---- ~~~~~~~~~~~~~~~~~ From 375ec458ad21c22ca7def458d4466a6c7ef2e3a2 Mon Sep 17 00:00:00 2001 From: rlratzel Date: Fri, 4 Oct 2024 16:51:43 -0500 Subject: [PATCH 15/16] Changes ordering of cuDF/Pandas for consistency. --- docs/cugraph/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cugraph/source/index.rst b/docs/cugraph/source/index.rst index f07b546769..0db1860b2b 100644 --- a/docs/cugraph/source/index.rst +++ b/docs/cugraph/source/index.rst @@ -10,7 +10,7 @@ Introduction ~~~~~~~~~~~~ cuGraph is a library of graph algorithms that seamlessly integrates into the RAPIDS data science ecosystem and allows the data scientist to easily call -graph algorithms using data stored in Pandas/cuDF DataFrames or CuPy/SciPy +graph algorithms using data stored in cuDF/Pandas DataFrames or CuPy/SciPy sparse matrices. --------------------------- From 33629918ee29dc5b1c3b4e68cf80dc1bda5db05d Mon Sep 17 00:00:00 2001 From: rlratzel Date: Fri, 4 Oct 2024 16:56:40 -0500 Subject: [PATCH 16/16] Removes trailing whitespace. --- docs/cugraph/source/nx_cugraph/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cugraph/source/nx_cugraph/index.rst b/docs/cugraph/source/nx_cugraph/index.rst index 8ac4019b97..730958a5b7 100644 --- a/docs/cugraph/source/nx_cugraph/index.rst +++ b/docs/cugraph/source/nx_cugraph/index.rst @@ -3,7 +3,7 @@ nx-cugraph ``nx-cugraph`` is a NetworkX backend that provides **GPU acceleration** to many popular NetworkX algorithms. -By simply `installing and enabling nx-cugraph `_, users can see significant speedup on workflows where performance is hindered by the default NetworkX implementation. +By simply `installing and enabling nx-cugraph `_, users can see significant speedup on workflows where performance is hindered by the default NetworkX implementation. Users can have GPU-based, large-scale performance **without** changing their familiar and easy-to-use NetworkX code.