From 178ecc0b59281939108e928490d05bfc48f78e68 Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 10:34:54 -0500 Subject: [PATCH 1/7] Reorder README.md sections - Moves project history toward the bottom of the page to make it clearer that Rustworkx is freestanding and has utility beyond just Qiskit. - Moves usage upwards, since this is often how new potential users will evaluate how well the library will suit their needs. --- README.md | 68 +++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index b406e312af..a831b94d43 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,29 @@ 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. -## Project history +## Using rustworkx -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 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() + +# 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 @@ -88,30 +100,6 @@ 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() - -# 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) -``` - ## Building from source The first step for building rustworkx from source is to clone it locally @@ -179,3 +167,15 @@ 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/) + +## Project history + +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. From 79cc2e61d7685b87f175b0892a61d0477a0d3431 Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 16:49:00 +0100 Subject: [PATCH 2/7] Tweak usage text. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a831b94d43..1581c94792 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,11 @@ any Python application. ## 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: +Once you have rustworkx installed, simply import `rustworkx`. +All graph classes and top-level functions are accessible from the root +package. +To illustrate this, the following example calculates the shortest path +between two nodes A and C in a `PyGraph` (an undirected graph): ```python3 import rustworkx From 8b09fa7f752f7bc2353fc22a4b5d635d506a74cb Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 16:54:10 +0100 Subject: [PATCH 3/7] More tweaking. --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1581c94792..700a4b8a13 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,8 @@ - You can see the full rendered docs at: -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. +rustworkx is a high-performance general purpose graph library for Python, +written in Rust. ## Using rustworkx @@ -25,11 +23,12 @@ Once you have rustworkx installed, simply import `rustworkx`. All graph classes and top-level functions are accessible from the root package. To illustrate this, the following example calculates the shortest path -between two nodes A and C in a `PyGraph` (an undirected graph): +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 From ee7bacf8211e2c03bf7ee3806b1ceed20bd34312 Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 16:56:29 +0100 Subject: [PATCH 4/7] Move description and status around. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 700a4b8a13..f5efa84a3c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # rustworkx +A high-performance general purpose graph library for Python, +written in Rust. + +## Status [![License](https://img.shields.io/github/license/Qiskit/rustworkx.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0) ![Build Status](https://github.com/Qiskit/rustworkx/actions/workflows/main.yml/badge.svg?branch=main) [![Build Status](https://img.shields.io/travis/com/Qiskit/rustworkx/main.svg?style=popout-square)](https://travis-ci.com/Qiskit/rustworkx) @@ -14,9 +18,6 @@ - You can see the full rendered docs at: -rustworkx is a high-performance general purpose graph library for Python, -written in Rust. - ## Using rustworkx Once you have rustworkx installed, simply import `rustworkx`. From b59bf9f29cfd4f343e6a11d881fab4b9fa92423e Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 16:58:37 +0100 Subject: [PATCH 5/7] Shrink Status header. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f5efa84a3c..d22997ccf2 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ A high-performance general purpose graph library for Python, written in Rust. -## Status +### Status [![License](https://img.shields.io/github/license/Qiskit/rustworkx.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0) ![Build Status](https://github.com/Qiskit/rustworkx/actions/workflows/main.yml/badge.svg?branch=main) [![Build Status](https://img.shields.io/travis/com/Qiskit/rustworkx/main.svg?style=popout-square)](https://travis-ci.com/Qiskit/rustworkx) From 86ce6e68ea62265a6394a5419a5caf3afb205245 Mon Sep 17 00:00:00 2001 From: Kevin Hartman Date: Tue, 27 Feb 2024 17:02:28 +0100 Subject: [PATCH 6/7] A few more minor tweaks. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d22997ccf2..3972556441 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,9 @@ written in Rust. - You can see the full rendered docs at: -## Using rustworkx +## Usage -Once you have rustworkx installed, simply import `rustworkx`. +Once installed, simply import `rustworkx`. All graph classes and top-level functions are accessible from the root package. To illustrate this, the following example calculates the shortest path From 7868dde5e1fc36aeff6d9929659acf74c42ef8ec Mon Sep 17 00:00:00 2001 From: Ivan Carvalho <8753214+IvanIsCoding@users.noreply.github.com> Date: Tue, 27 Feb 2024 20:05:32 -0500 Subject: [PATCH 7/7] Improve README.md --- README.md | 49 ++++++++++++++++++++++++------------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 3972556441..4be818d64d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,5 @@ # rustworkx -A high-performance general purpose graph library for Python, -written in Rust. - -### Status [![License](https://img.shields.io/github/license/Qiskit/rustworkx.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0) ![Build Status](https://github.com/Qiskit/rustworkx/actions/workflows/main.yml/badge.svg?branch=main) [![Build Status](https://img.shields.io/travis/com/Qiskit/rustworkx/main.svg?style=popout-square)](https://travis-ci.com/Qiskit/rustworkx) @@ -18,11 +14,12 @@ written in Rust. - You can see the full rendered docs at: +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 from the root -package. +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. @@ -47,7 +44,7 @@ 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: @@ -55,7 +52,7 @@ installing is as simple as running: 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 @@ -77,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 @@ -102,6 +100,21 @@ 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. +## 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 + +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 The first step for building rustworkx from source is to clone it locally @@ -150,26 +163,12 @@ 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 - -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/) - ## Project history Rustworkx was originally called retworkx and was created initially to be