Add nx-cugraph Docs Pages

docs/cugraph/source/nx_cugraph/benchmarks.md

@@ -0,0 +1,28 @@
+# Benchmarks
+
+## NetworkX vs. nx-cugraph
+We ran several commonly used graph algorithms on both `networkx` and `nx-cugraph`. Here are the results
+
+
+<figure>
+
+<!-- ![bench-image](link) -->
+
+<figcaption style="text-align: center;">Results of the <a
+href="https://github.com/rapidsai/cugraph">Benchmark</a> including <span
+class="title-ref">nx-cugraph</span></figcaption>
+</figure>
+
+## Reproducing Benchmarks
+
+Below are the steps to reproduce the results on your workstation. These are documented in <https://github.com/rapidsai/cugraph/tree/branch-24.10/benchmarks/nx-cugraph/pytest-based>.
+
+1. Clone the latest <https://github.com/rapidsai/cugraph>
+
+2. Follow the instructions to build an environment
+
+3. Activate the environment
+
+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/`

docs/cugraph/source/nx_cugraph/faqs.md

@@ -0,0 +1,5 @@
+# FAQ
+
+ > **1. Is `nx-cugraph` able to run across multiple GPUs?**
+
+We currently do not support multi-GPU. There are plans to add support for this later on.

docs/cugraph/source/nx_cugraph/how-it-works.md

@@ -0,0 +1,109 @@
+# How it Works
+
+NetworkX has the ability to **dispatch function calls to separately-installed third-party backends**.
+
+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.
+
+
+![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_AUTOMATIC_BACKENDS` environment variable.
+
+The `NETWORKX_AUTOMATIC_BACKENDS` environment variable can be used to have NetworkX automatically dispatch to specified backends an API is called that the backend supports.
+Set `NETWORKX_AUTOMATIC_BACKENDS=cugraph` to use nx-cugraph to GPU accelerate supported APIs with no code changes.
+Example:
+```
+bash> NETWORKX_AUTOMATIC_BACKENDS=cugraph 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_AUTOMATIC_BACKENDS` environment variable. This requires anyone
+running code that uses the `backend=` keyword argument to have the specified
+backend installed.
+
+Example:
+```
+nx.betweenness_centrality(cit_patents_graph, k=k, backend="cugraph")
+```
+
+### Type-based dispatching
+
+NetworkX also supports automatically dispatching to backends associated with
+specific graph types. Like the `backend=` keyword argument example above, this
+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
+directly in their code to access the utilities provided to create a Graph
+instance specifically for the nx-cugraph backend.
+
+Example:
+```
+import networkx as nx
+import nx_cugraph as nxcg
+
+G = nx.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
+```
+
+## Command Line Example
+
+---
+
+Create `bc_demo.ipy` and paste the code below.
+
+```
+import pandas as pd
+import networkx as nx
+
+url = "https://data.rapids.ai/cugraph/datasets/cit-Patents.csv"
+df = pd.read_csv(url, sep=" ", names=["src", "dst"], dtype="int32")
+G = nx.from_pandas_edgelist(df, source="src", target="dst")
+
+%time result = nx.betweenness_centrality(G, k=10)
+```
+Run the command:
+```
+user@machine:/# ipython bc_demo.ipy
+```
+
+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.
+```
+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
+```
+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.
+```
+NETWORKX_BACKEND_PRIORITY=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:
+```
+nx.betweenness_centrality(cit_patents_graph, k=k, backend="cugraph")
+```
+
+
+The latest list of algorithms supported by nx-cugraph can be found [here](https://github.com/rapidsai/cugraph/blob/main/python/nx-cugraph/README.md#algorithms) or in the next session.
+
+---

docs/cugraph/source/nx_cugraph/index.rst

@@ -1,9 +1,48 @@
-===============================
-nxCugraph as a NetworkX Backend
-===============================
+nx-cugraph
+-----------
 
+nx-cugraph is a `NetworkX backend <https://networkx.org/documentation/stable/reference/utils.html#backends>`_ that provides **GPU acceleration** to many popular NetworkX algorithms.
+
+By simply `installing and enabling nx-cugraph <https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#install>`_, 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.
+
+.. code-block:: python
+
+    import pandas as pd
+    import networkx as nx
+
+    url = "https://data.rapids.ai/cugraph/datasets/cit-Patents.csv"
+    df = pd.read_csv(url, sep=" ", names=["src", "dst"], dtype="int32")
+    G = nx.from_pandas_edgelist(df, source="src", target="dst")
+
+    %time result = nx.betweenness_centrality(G, k=10)
+
+.. figure:: ../_static/colab.png
+    :width: 200px
+    :target: https://github.com/rapidsai-community/showcase/blob/632d50068f2dec08a591c98f4c41092eab2dfae4/getting_started_tutorials/accelerated_networkx_demo.ipynb/
+
+    Try it on Google Colab!
+
+
++---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+
+| **Zero Code Change Acceleration**                                                           | **Third-Party Library Compatible**                                                                                  |
+|                                                                                             |                                                                                                                     |
+| Just ``%load_ext cudf.pandas`` in Jupyter, or pass ``-m cudf.pandas`` on the command line.  | ``nx_cugraph`` is compatible with most third-party libraries that use pandas.                                       |
++---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+
+| **Run the same code on CPU or GPU**                                                         | **100% of the NetworkX API**                                                                                        |
+|                                                                                             |                                                                                                                     |
+| Nothing changes, not even your `import` statements, when going from CPU to GPU.             | Combines the full flexibility of NetworkX with the speed of running on GPU.                                         |
++---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------+
+
+
+``nx-cugraph`` is now Generally Available (GA) as part of the ``RAPIDS`` package.  See `RAPIDS
+Quick Start <https://rapids.ai/#quick-start>`_ to get up-and-running with ``nx-cugraph``.
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 1
+    :caption: Contents:
 
-   nx_cugraph.md
+    how-it-works
+    supported-algorithms
+    installation
+    benchmarks
+    faqs

docs/cugraph/source/nx_cugraph/installation.md

@@ -0,0 +1,50 @@
+# Getting Started
+
+This guide describes how to install ``nx-cugraph`` use it in your workflows.
+
+
+## System Requirements
+
+`nx-cugraph` requires the following:
+
+ - **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)**
+
+More details about system requirements can be found in the [RAPIDS System Requirements Documentation](https://docs.rapids.ai/install#system-req).
+
+## Installing nx-cugraph
+
+Read the [RAPIDS Quick Start Guide](https://docs.rapids.ai/install) to learn more about installing all RAPIDS libraries.
+
+`nx-cugraph` can be installed using conda or pip. It is included in the RAPIDS metapackage, or can be installed separately.
+
+### Conda
+**Nightly version**
+```bash
+conda install -c rapidsai-nightly -c conda-forge -c nvidia nx-cugraph
+```
+
+**Stable version**
+```bash
+conda install -c rapidsai -c conda-forge -c nvidia nx-cugraph
+```
+
+### pip
+**Nightly version**
+```bash
+pip install nx-cugraph-cu11 --extra-index-url https://pypi.anaconda.org/rapidsai-wheels-nightly/simple
+```
+
+**Stable version**
+```bash
+pip install nx-cugraph-cu11 --extra-index-url https://pypi.nvidia.com
+```
+
+<div style="border: 1px solid #ccc; background-color: #f9f9f9; padding: 10px; border-radius: 5px;">
+
+**Note:**
+ - The `pip install` examples above ar efor CUDA 11. To install for CUDA 12, replace `-cu11` with `-cu12`
+
+</div>

docs/cugraph/source/nx_cugraph/nx_cugraph.md

@@ -1,17 +1,18 @@
 ### nx_cugraph
 
 
-nx-cugraph is a [NetworkX
-backend](<https://networkx.org/documentation/stable/reference/utils.html#backends>) that provides GPU acceleration to many popular NetworkX algorithms.
+Whereas previous versions of cuGraph have included mechanisms to make it
+trivial to plug in cuGraph algorithm calls. Beginning with version 24.02, nx-cuGraph
+is now a [networkX backend](<https://networkx.org/documentation/stable/reference/utils.html#backends>).
+The user now need only [install nx-cugraph](<https://github.com/rapidsai/cugraph/blob/branch-24.08/python/nx-cugraph/README.md#install>)
+to experience GPU speedups.
 
-By simply [installing and enabling nx-cugraph](<https://github.com/rapidsai/cugraph/blob/HEAD/python/nx-cugraph/README.md#install>), 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.
-
-Let's look at some examples of algorithm speedups comparing NetworkX with and without GPU acceleration using nx-cugraph.
+Lets look at some examples of algorithm speedups comparing CPU based NetworkX to dispatched versions run on GPU with nx_cugraph.
 
 Each chart has three measurements.
-* NX - default NetworkX, no GPU acceleration
-* nx-cugraph - GPU-accelerated NetworkX using nx-cugraph. This involves an internal conversion/transfer of graph data from CPU to GPU memory
-* nx-cugraph (preconvert) - GPU-accelerated NetworkX using nx-cugraph with the graph data pre-converted/transferred to GPU
+* NX - running the algorithm natively with networkX on CPU.
+* nx-cugraph - running with GPU accelerated networkX achieved by simply calling the cugraph backend. This pays the overhead of building the GPU resident object for each algorithm called. This achieves significant improvement but stil isn't compleltely optimum.
+* nx-cugraph (preconvert) - This is a bit more complicated since it involves building (precomputing) the GPU resident graph ahead and reusing it for each algorithm.
 
 
 ![Ancestors](../images/ancestors.png)
@@ -22,46 +23,3 @@ Each chart has three measurements.
 ![Pagerank](../images/pagerank.png)
 ![Single Source Shortest Path](../images/sssp.png)
 ![Weakly Connected Components](../images/wcc.png)
-
-### Command line example
-Open bc_demo.ipy and paste the code below.
-
-```
-import pandas as pd
-import networkx as nx
-
-url = "https://data.rapids.ai/cugraph/datasets/cit-Patents.csv"
-df = pd.read_csv(url, sep=" ", names=["src", "dst"], dtype="int32")
-G = nx.from_pandas_edgelist(df, source="src", target="dst")
-
-%time result = nx.betweenness_centrality(G, k=10)
-```
-Run the command:
-```
-user@machine:/# ipython bc_demo.ipy
-```
-
-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.
-```
-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
-```
-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.
-```
-NETWORKX_BACKEND_PRIORITY=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:
-```
-nx.betweenness_centrality(cit_patents_graph, k=k, backend="cugraph")
-```
-
-
-The latest list of algorithms supported by nx-cugraph can be found [here](https://github.com/rapidsai/cugraph/blob/main/python/nx-cugraph/README.md#algorithms).

docs/cugraph/source/nx_cugraph/suppoal.md

@@ -0,0 +1,27 @@
+# Supported Algorithms
+
+
+The nx-cugraph backend to NetworkX connects
+[pylibcugraph](../../readme_pages/pylibcugraph.md) (cuGraph's low-level python
+interface to its CUDA-based graph analytics library) and
+[CuPy](https://cupy.dev/) (a GPU-accelerated array library) to NetworkX's
+familiar and easy-to-use API.
+
+Below is the list of algorithms that are currently supported in nx-cugraph.
+
+### [Algorithms](https://networkx.org/documentation/latest/reference/algorithms/index.html)
+
+
+| **Centrality**    | **Centrality**   |
+|------------------------------|------------------------------|
+| betweenness_centrality       |  betweenness_centrality      |
+| edge_betweenness_centrality  | in_degree_centrality         |
+| degree_centrality            |  edge_betweenness_centrality |
+| in_degree_centrality         | in_degree_centrality         |
+| out_degree_centrality        |  in_degree_centrality        |
+| eigenvector_centrality       |  in_degree_centrality        |
+| katz_centrality              |  in_degree_centrality        |
+
+
+To request nx-cugraph backend support for a NetworkX API that is not listed
+above, visit the [cuGraph GitHub repo](https://github.com/rapidsai/cugraph).