Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates README file to include nx-cugraph user documentation, adds nx-cugraph to main README #3984

Merged
merged 5 commits into from
Nov 8, 2023
Merged

Updates README file to include nx-cugraph user documentation, adds nx-cugraph to main README #3984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1ce3edd
Updates README to accommodate new users.
rlratzel Nov 7, 2023
4614f1e
Removed DGL and PyG from diagram since they are not calling PropertyG…
rlratzel Nov 7, 2023
270a1de
Added nx-cugraph and News section.
rlratzel Nov 7, 2023
793b5d7
Removes mention of notebook, adds table of supported algos, updated n…
rlratzel Nov 8, 2023
42e90f6
Merge branch 'branch-23.12' into branch-23.12-nx_cugraph_readme_update
nv-rliu Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion README.md
View file
Open in desktop
rlratzel marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,18 @@
</div>

-----
## News

## Table of content
___NEW!___ _[nx-cugraph](./python/nx-cugraph/README.md)_, a NetworkX backend that provides GPU acceleration to NetworkX with zero code change.
```
> pip install nx-cugraph-cu11 --extra-index-url https://pypi.nvidia.com
> export NETWORKX_AUTOMATIC_BACKENDS=cugraph
```
That's it. NetworkX now leverages cuGraph for accelerated graph algorithms.

-----

## Table of contents
- Installation
- [Getting cuGraph Packages](./docs/cugraph/source/installation/getting_cugraph.md)
- [Building from Source](./docs/cugraph/source/installation/source_build.md)
Expand All @@ -52,6 +62,7 @@
- [External Data Types](./readme_pages/data_types.md)
- [pylibcugraph](./readme_pages/pylibcugraph.md)
- [libcugraph (C/C++/CUDA)](./readme_pages/libcugraph.md)
- [nx-cugraph](./python/nx-cugraph/README.md)
- [cugraph-service](./readme_pages/cugraph_service.md)
- [cugraph-dgl](./readme_pages/cugraph_dgl.md)
- [cugraph-ops](./readme_pages/cugraph_ops.md)
Expand Down Expand Up @@ -116,6 +127,7 @@ df_page.sort_values('pagerank', ascending=False).head(10)
* ArangoDB - a free and open-source native multi-model database system - https://www.arangodb.com/
* CuPy - "NumPy/SciPy-compatible Array Library for GPU-accelerated Computing with Python" - https://cupy.dev/
* Memgraph - In-memory Graph database - https://memgraph.com/
* NetworkX (via [nx-cugraph](./python/nx-cugraph/README.md) backend) - an extremely popular, free and open-source package for the creation, manipulation, and study of the structure, dynamics, and functions of complex networks - https://networkx.org/
* PyGraphistry - free and open-source GPU graph ETL, AI, and visualization, including native RAPIDS & cuGraph support - http://github.com/graphistry/pygraphistry
* ScanPy - a scalable toolkit for analyzing single-cell gene expression data - https://scanpy.readthedocs.io/en/stable/

Expand Down
Binary file modified img/Stack2.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
135 changes: 119 additions & 16 deletions python/nx-cugraph/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,134 @@

## Description
[RAPIDS](https://rapids.ai) nx-cugraph is a [backend to NetworkX](https://networkx.org/documentation/stable/reference/classes/index.html#backends)
with minimal dependencies (`networkx`, `cupy`, and `pylibcugraph`) to run graph algorithms on the GPU.
to run supported algorithms with GPU acceleration.

### Contribute
## System Requirements

Follow instructions for [contributing to cugraph](https://github.com/rapidsai/cugraph/blob/branch-23.12
and [building from source](https://docs.rapids.ai/api/cugraph/stable/installation/source_build/), then build nx-cugraph in develop (i.e., editable) mode:
```
$ ./build.sh nx-cugraph --pydevelop
```
nx-cugraph requires the following:

* NVIDIA GPU, Pascal architecture or later
* CUDA 11.2, 11.4, 11.5, 11.8, or 12.0
* Python versions 3.9, 3.10, or 3.11
* NetworkX >= version 3.2

### Run tests
More details about system requirements can be found in the [RAPIDS System Requirements documentation](https://docs.rapids.ai/install#system-req)..

Run nx-cugraph tests from `cugraph/python/nx-cugraph` directory:
## Installation

nx-cugraph can be installed using either conda or pip.

### conda
```
$ pytest
conda install -c rapidsai-nightly -c conda-forge -c nvidia nx-cugraph
```
Run nx-cugraph benchmarks:
### pip
```
$ pytest --bench
python -m pip install nx-cugraph-cu11 --extra-index-url https://pypi.nvidia.com
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this need a --pre or >=23.10.0a0 specifier since the latest changes? @vyasr may know. Maybe based on the note below about these being non-nightlies it's not an issue?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, I was relying on the note below that since (I don't believe) we have a way to provide nightly 23.12 wheels. Although if there is a way I'm not aware of, I'd love to be able to describe how users can get nightly 23.12 wheels. @vyasr any thoughts?

```
Run networkx tests (requires networkx version 3.2):
Notes:

* Nightly wheel builds will not be available until the 23.12 release, therefore the index URL for the stable release version is being used in the pip install command above.
* Additional information relevant to installing any RAPIDS package can be found [here](https://rapids.ai/#quick-start).

## Enabling nx-cugraph

NetworkX will use nx-cugraph as the graph analytics backend if any of the
following are 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:
```
$ ./run_nx_tests.sh
bash> NETWORKX_AUTOMATIC_BACKENDS=cugraph python my_networkx_script.py
```
Additional arguments may be passed to pytest such as:

### `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:
```
$ ./run_nx_tests.sh -x --sw -k betweenness
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
```

## 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 (many listed using pylibcugraph names),
available today in pylibcugraph or implemented using CuPy, that are or will be
supported in nx-cugraph.

| feature/algo | release/target version |
| ----- | ----- |
| analyze_clustering_edge_cut | ? |
| analyze_clustering_modularity | ? |
| analyze_clustering_ratio_cut | ? |
| balanced_cut_clustering | ? |
| betweenness_centrality | 23.10 |
| bfs | ? |
| core_number | ? |
| degree_centrality | 23.12 |
| ecg | ? |
| edge_betweenness_centrality | 23.10 |
| ego_graph | ? |
| eigenvector_centrality | 23.12 |
| get_two_hop_neighbors | ? |
| hits | 23.12 |
| in_degree_centrality | 23.12 |
| induced_subgraph | ? |
| jaccard_coefficients | ? |
| katz_centrality | 23.12 |
| k_core | ? |
| k_truss_subgraph | 23.12 |
| leiden | ? |
| louvain | 23.10 |
| node2vec | ? |
| out_degree_centrality | 23.12 |
| overlap_coefficients | ? |
| pagerank | 23.12 |
| personalized_pagerank | ? |
| sorensen_coefficients | ? |
| spectral_modularity_maximization | ? |
| sssp | 23.12 |
| strongly_connected_components | ? |
| triangle_count | ? |
| uniform_neighbor_sample | ? |
| uniform_random_walks | ? |
| weakly_connected_components | ? |

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).
Loading