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

Reorder and tweak README.md sections #1120

Merged
merged 7 commits into from
Feb 28, 2024
Merged

Reorder and tweak README.md sections #1120

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
178ecc0
Reorder README.md sections
kevinhartman Feb 27, 2024
79cc2e6
Tweak usage text.
kevinhartman Feb 27, 2024
8b09fa7
More tweaking.
kevinhartman Feb 27, 2024
ee7bacf
Move description and status around.
kevinhartman Feb 27, 2024
b59bf9f
Shrink Status header.
kevinhartman Feb 27, 2024
86ce6e6
A few more minor tweaks.
kevinhartman Feb 27, 2024
7868dde
Improve README.md
IvanIsCoding Feb 28, 2024
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
103 changes: 52 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,34 +14,45 @@
- You can see the full rendered docs at:
<https://www.rustworkx.org/>

rustworkx is a general purpose graph library for Python written in Rust to
take advantage of the performance and safety that Rust provides. It is
designed to provide a high performance general purpose graph library for
any Python application.
A high-performance, general-purpose graph library for Python, written in Rust.

## Project history
## Usage

Rustworkx was originally called retworkx and was created initially to be
a replacement for [Qiskit](https://www.ibm.com/quantum/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](https://github.com/Qiskit/qiskit/)'s transpiler. However,
since it's initial introduction the project has grown substantially and now
covers all applications that need to work with graphs which includes
Qiskit.
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.

```python3
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
rustworkx is published on [PyPI](https://pypi.org/project/rustworkx/) 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:

```bash
pip install rustworkx
```

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

### Installing on a platform without precompiled binaries
Expand All @@ -63,7 +74,8 @@ 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
> [!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` prior to running `pip install rustworkx`. If you recieve an
error about `setuptools-rust` not being found you should upgrade pip with
Expand All @@ -88,29 +100,20 @@ 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.

## Using rustworkx

Once you have rustworkx installed you can use it by importing rustworkx.
All the functions and graph classes are off the root of the package.
For example, calculating the shortest path between A and C would be:

```python3
import rustworkx

graph = rustworkx.PyGraph()
## Authors and Citation

# 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")
rustworkx is the work of [many people](https://github.com/Qiskit/rustworkx/graphs/contributors) who contribute
to the project at different levels. If you use rustworkx in your research, please cite our
[paper](https://doi.org/10.21105/joss.03968) as per the included [BibTeX file](CITATION.bib).

# 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)])
## Community

# Returns the path A -> B -> C
rustworkx.dijkstra_shortest_paths(graph, a, c, weight_fn=float)
```
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](https://qiskit.slack.com/messages/rustworkx/). You can join the
Qiskit Slack workspace [here](http://ibm.co/joinqiskitslack). Additionally,
there is an IRC channel `#rustworkx` on the [OFTC IRC network](https://www.oftc.net/)

## Building from source

Expand Down Expand Up @@ -160,22 +163,20 @@ optimizations and include debuginfo which can be handy for debugging. Do note
that installing rustworkx this way will be significantly slower then using
`pip install` and should only be used for debugging/development.

It's worth noting that `pip install -e` does not work, as it will link the python
> [!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. If
you want to build rustworkx in debug mode you have to use
`python setup.py develop`.

## Authors and Citation

rustworkx is the work of [many people](https://github.com/Qiskit/rustworkx/graphs/contributors) who contribute
to the project at different levels. If you use rustworkx in your research, please cite our
[paper](https://doi.org/10.21105/joss.03968) as per the included [BibTeX file](CITATION.bib).

## Community
## Project history

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](https://qiskit.slack.com/messages/rustworkx/). You can join the
Qiskit Slack workspace [here](http://ibm.co/joinqiskitslack). Additionally,
there is an IRC channel `#rustworkx` on the [OFTC IRC network](https://www.oftc.net/)
Rustworkx was originally called retworkx and was created initially to be
a replacement for [Qiskit](https://www.ibm.com/quantum/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](https://github.com/Qiskit/qiskit/)'s transpiler. However,
since it's initial introduction the project has grown substantially and now
covers all applications that need to work with graphs which includes
Qiskit.
Loading