rustworkx

You can see the full rendered docs at:
https://www.rustworkx.org/

A high-performance, general-purpose graph library for Python, written in Rust.

Usage

Once installed, simply import rustworkx.
All graph classes and top-level functions are accessible with a single import.
To illustrate this, the following example calculates the shortest path
between two nodes A and C in an undirected graph.

import rustworkx

# Rustworkx's undirected graph type.
graph = rustworkx.PyGraph()

# Each time add node is called, it returns a new node index
a = graph.add_node("A")
b = graph.add_node("B")
c = graph.add_node("C")

# add_edges_from takes tuples of node indices and weights,
# and returns edge indices
graph.add_edges_from([(a, b, 1.5), (a, c, 5.0), (b, c, 2.5)])

# Returns the path A -> B -> C
rustworkx.dijkstra_shortest_paths(graph, a, c, weight_fn=float)

Installing rustworkx

rustworkx is published on PyPI so on x86_64, i686, ppc64le, s390x, and
aarch64 Linux systems, x86_64 on Mac OSX, and 32 and 64 bit Windows
installing is as simple as running:

pip install rustworkx

This will install a precompiled version of rustworkx into your Python
environment.

Installing on a platform without precompiled binaries

If there are no precompiled binaries published for your system you'll have to
build the package from source. However, to be able to build the package
from the published source package you need to have Rust >= 1.79 installed (and
also cargo which is normally included with
rust) You can use rustup (a cross platform installer for
rust) to make this simpler, or rely on
other installation methods.
A source package is also published on pypi, so you still can also run the above
pip command to install it. Once you have rust properly installed, running:

pip install rustworkx

will build rustworkx for your local system from the source package and install
it just as it would if there was a prebuilt binary available.

[!NOTE]
To build from source you will need to ensure you have pip >=19.0.0
installed, which supports PEP-517, or that you have manually installed
setuptools-rust>=1.9 prior to running pip install rustworkx. If you receive an
error about setuptools-rust not being found you should upgrade pip with
pip install -U pip or manually install setuptools-rust with
pip install -U setuptools-rust and try again.

Optional dependencies

If you're planning to use the rustworkx.visualization module you will need to
install optional dependencies to use the functions. The matplotlib based drawer
function rustworkx.visualization.mpl_draw requires that the
matplotlib library is installed. This can be
installed with pip install matplotlib or when you're installing rustworkx with
pip install 'rustworkx[mpl]'. If you're going to use the graphviz based drawer
function rustworkx.visualization.graphviz_drawer first you will need to install
graphviz, instructions for this can be found here:
https://graphviz.org/download/#executable-packages. Then you
will need to install the pillow Python library.
This can be done either with pip install pillow or when installing rustworkx
with pip install 'rustworkx[graphviz]'.

If you would like to install all the optional Python dependencies when you
install rustworkx you can use pip install 'rustworkx[all]' to do this.

Conda Ecosystem

Community-supported binaries are published to conda-forge. Although
unofficial, they can be helpful for users of the conda ecosystem (including mamba, micromamba, and pixi). To install, simply run:

conda install -c conda-forge rustworkx

Authors and Citation

rustworkx is the work of many people who contribute
to the project at different levels. If you use rustworkx in your research, please cite our
paper as per the included BibTeX file.

Community

Besides Github interactions (such as opening issues) there are two locations
available to talk to other rustworkx users and developers. The first is a
public Slack channel in the Qiskit workspace,
#rustworkx. You can join the
Qiskit Slack workspace here. Additionally,
there is an IRC channel #rustworkx on the OFTC IRC network

Building from source

The first step for building rustworkx from source is to clone it locally
with:

git clone https://github.com/Qiskit/rustworkx.git

rustworkx uses PyO3 and
setuptools-rust to build the
python interface, which enables using standard python tooling to work. So,
assuming you have rust installed, you can easily install rustworkx into your
python environment using pip. Once you have a local clone of the repo, change
your current working directory to the root of the repo. Then, you can install
rustworkx into your python env with:

pip install .

Assuming your current working directory is still the root of the repo.
Otherwise you can run:

pip install $PATH_TO_REPO_ROOT

which will install it the same way. Then rustworkx is installed in your
local python environment. There are 2 things to note when doing this
though, first if you try to run python from the repo root using this
method it will not work as you expect. There is a name conflict in the
repo root because of the local python package shim used in building the
package. Simply run your python scripts or programs using rustworkx
outside of the repo root. The second issue is that any local changes you
make to the rust code will not be reflected live in your python environment,
you'll need to recompile rustworkx by rerunning pip install to have any
changes reflected in your python environment.

Develop Mode

If you'd like to build rustworkx in debug mode and use an interactive debugger
while working on a change you can set SETUPTOOLS_RUST_CARGO_PROFILE="dev"
as an environment variable to build and install rustworkx in develop mode.
This will build rustworkx without optimizations and include debuginfo
when running pip install. That can be handy for debugging.

[!TIP]
It's worth noting that pip install -e does not work, as it will link the python
packaging shim to your python environment but not build the rustworkx binary.

Project history

Rustworkx was originally called retworkx and was created initially to be
a replacement for Qiskit's previous (and current)
NetworkX usage (hence the original name). The project was originally started
to build a faster directed graph to use as the underlying data structure for
the DAG at the center of
qiskit's transpiler. However,
since its initial introduction the project has grown substantially and now
covers all applications that need to work with graphs which includes
Qiskit.

Dependencies of rustworkx (3).
Dependency	Optional
numpy	false
matplotlib	true
pillow	true

Package profile

rustworkx

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description