From b2770a55a6b60d76883aa46d8cd1cc763be95a50 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 27 May 2021 11:01:41 -0400 Subject: [PATCH] Prepare 0.9.0 release This commit starts the preparation for the 0.9.0 release. It moves all the release notes for the release into a separate folder (to distinguish them from notes for future releases) and also reworks the content of the release notes and updates the documentation for the release. This commit should be the last one merged before releasing 0.9.0 to ensure we've moved and updated all the release notes before the release. Partially implements #328 --- docs/source/index.rst | 39 ++++++++++++++++++- docs/source/networkx.rst | 2 + docs/source/release_notes.rst | 7 +++- ...tree-graph-generator-1f6ff6ba3809b901.yaml | 23 +++++++++++ .../add-copy-method-f2abb1222b323dab.yaml | 0 .../add-core_number-b1d3b2fb7ebd276f.yaml | 0 ...-edge-indices-method-c1868ab1dab61b18.yaml | 0 .../add-num-methods-08ac0963b9961f5e.yaml | 0 .../add-nx-converter-1feffc8d5aa13365.yaml | 0 ...ndom-geometric-graph-ef131e3955c6b178.yaml | 14 +++++++ .../add-random-layout-c1c2751be971e5d0.yaml | 0 ...ransitivity-function-c32d2bbbf3857c40.yaml | 2 +- .../bump-msrv-d581a8cbeff8915b.yaml | 0 .../complement-361c90c7dda69df8.yaml | 0 .../custom-path-returns-e1d5fc1e02809179.yaml | 0 .../dijkstra-all-pairs-ecdc3d9a5a267350.yaml | 0 .../expand-isomorphism-cfb646cfef66fa25.yaml | 14 +++++++ .../extend-generators-07a5d34d5e637a6a.yaml | 23 +++++++++++ .../find-successors-by-d3589b1b1d0b1633.yaml | 8 ++++ .../fixed-mutability-0ab3030db0d77239.yaml | 0 .../floyd-warshall-fix-d8ec2131dfaeab82.yaml | 0 ...rphic-matching-order-be0cfa8b796cd55c.yaml | 11 ++++++ ...inimum-spanning-tree-4afa29b3c0dbd2fb.yaml | 11 ++++++ .../mpl-draw-f2a3224671907eaf.yaml | 0 ...-directed-generators-dc7bbb53480d5d0a.yaml | 0 .../0.9.0/prepare-0.9-dab64f0197fc6233.yaml | 11 ++++++ .../0.9.0/spring-layout-c21a31f21bc113a0.yaml | 7 ++++ .../write_edge_list-5f3de403770a811e.yaml | 0 ...tree-graph-generator-1f6ff6ba3809b901.yaml | 4 -- ...ndom-geometric-graph-ef131e3955c6b178.yaml | 5 --- .../expand-isomorphism-cfb646cfef66fa25.yaml | 9 ----- .../extend-generators-07a5d34d5e637a6a.yaml | 5 --- .../find-successors-by-d3589b1b1d0b1633.yaml | 6 --- ...rphic-matching-order-be0cfa8b796cd55c.yaml | 7 ---- ...inimum-spanning-tree-4afa29b3c0dbd2fb.yaml | 6 --- .../notes/spring-layout-c21a31f21bc113a0.yaml | 6 --- retworkx/__init__.py | 28 +++++++++++-- src/digraph.rs | 32 ++++++++++++--- src/graph.rs | 27 +++++++++---- 39 files changed, 240 insertions(+), 67 deletions(-) create mode 100644 releasenotes/notes/0.9.0/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml rename releasenotes/notes/{ => 0.9.0}/add-copy-method-f2abb1222b323dab.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/add-core_number-b1d3b2fb7ebd276f.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/add-edge-indices-method-c1868ab1dab61b18.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/add-num-methods-08ac0963b9961f5e.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/add-nx-converter-1feffc8d5aa13365.yaml (100%) create mode 100644 releasenotes/notes/0.9.0/add-random-geometric-graph-ef131e3955c6b178.yaml rename releasenotes/notes/{ => 0.9.0}/add-random-layout-c1c2751be971e5d0.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/add-transitivity-function-c32d2bbbf3857c40.yaml (66%) rename releasenotes/notes/{ => 0.9.0}/bump-msrv-d581a8cbeff8915b.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/complement-361c90c7dda69df8.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/custom-path-returns-e1d5fc1e02809179.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/dijkstra-all-pairs-ecdc3d9a5a267350.yaml (100%) create mode 100644 releasenotes/notes/0.9.0/expand-isomorphism-cfb646cfef66fa25.yaml create mode 100644 releasenotes/notes/0.9.0/extend-generators-07a5d34d5e637a6a.yaml create mode 100644 releasenotes/notes/0.9.0/find-successors-by-d3589b1b1d0b1633.yaml rename releasenotes/notes/{ => 0.9.0}/fixed-mutability-0ab3030db0d77239.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/floyd-warshall-fix-d8ec2131dfaeab82.yaml (100%) create mode 100644 releasenotes/notes/0.9.0/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml create mode 100644 releasenotes/notes/0.9.0/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml rename releasenotes/notes/{ => 0.9.0}/mpl-draw-f2a3224671907eaf.yaml (100%) rename releasenotes/notes/{ => 0.9.0}/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml (100%) create mode 100644 releasenotes/notes/0.9.0/prepare-0.9-dab64f0197fc6233.yaml create mode 100644 releasenotes/notes/0.9.0/spring-layout-c21a31f21bc113a0.yaml rename releasenotes/notes/{ => 0.9.0}/write_edge_list-5f3de403770a811e.yaml (100%) delete mode 100644 releasenotes/notes/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml delete mode 100644 releasenotes/notes/add-random-geometric-graph-ef131e3955c6b178.yaml delete mode 100644 releasenotes/notes/expand-isomorphism-cfb646cfef66fa25.yaml delete mode 100644 releasenotes/notes/extend-generators-07a5d34d5e637a6a.yaml delete mode 100644 releasenotes/notes/find-successors-by-d3589b1b1d0b1633.yaml delete mode 100644 releasenotes/notes/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml delete mode 100644 releasenotes/notes/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml delete mode 100644 releasenotes/notes/spring-layout-c21a31f21bc113a0.yaml diff --git a/docs/source/index.rst b/docs/source/index.rst index 599c210533..6e99b92a49 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,12 +2,47 @@ retworkx Documentation ###################### +retworkx is a Python package for working with graphs and complex networks. It +enables the creation, interaction with, and study of graphs and networks. + +It provides: + + * Data structures for creating graphs including directed graphs and multigraphs + * A library of standard graph algorithms + * Generators for various types of graphs including random graphs + * Visualization functions for graphs + +It is licensed under the +`Apache 2.0 `__ license and the +source code is hosted on Github at: + +https://github.com/Qiskit/retworkx + +retworkx is written in the +`Rust programming language `__ to leverage Rust's +inherent performance and safety. While this provides numerous advantages +including significantly improved performance it does mean that the library +needs to be compiled when being installed from source (as opposed to a pure +Python library which can just be installed). retworkx supports and publishes +pre-compiled binaries for Linux on x86, x86_64, aarch64, s390x, and ppc64le, +MacOS on x86_64, and arm64, and Windows 32bit and 64bit systems. However if you're running outside of these platforms to install retworkx you will need a +rust compiler installed. + +retworkx was originally created to be a high performance replacement for the +Qiskit project's internal usage of the `NetworkX `__ +library (which is where the name comes from Rust + NetworkX = retworkx) but is +not a drop-in replacement for NetworkX (see :ref:`networkx` for more details). +However, since it was originally created it has grown to be an independent +high performance general purpose graph library that can be used for any +application that needs to interact with graphs or complex networks. + + Contents: .. toctree:: - :maxdepth: 3 + :maxdepth: 2 - README + Overview and Installation Retworkx API Visualization Release Notes diff --git a/docs/source/networkx.rst b/docs/source/networkx.rst index c6e029f344..b6da086e79 100644 --- a/docs/source/networkx.rst +++ b/docs/source/networkx.rst @@ -1,3 +1,5 @@ +.. _networkx: + ########################### retworkx for networkx users ########################### diff --git a/docs/source/release_notes.rst b/docs/source/release_notes.rst index adfd39f069..ae79c0f5e3 100644 --- a/docs/source/release_notes.rst +++ b/docs/source/release_notes.rst @@ -1,4 +1,8 @@ -.. release-notes:: Release Notes +************* +Release Notes +************* + +.. release-notes:: 0.7.1 ===== @@ -97,6 +101,7 @@ Fixes source. This has been fixed so building from sdist will always use known working versions that we use for testing in CI. + 0.6.0 ===== diff --git a/releasenotes/notes/0.9.0/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml b/releasenotes/notes/0.9.0/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml new file mode 100644 index 0000000000..093a71b8f0 --- /dev/null +++ b/releasenotes/notes/0.9.0/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml @@ -0,0 +1,23 @@ +--- +features: + - | + Added a new generator functions, + :func:`retworkx.generators.binomial_tree_graph` and + :func:`retworkx.generators.directed_binomial_tree_graph`, for constructing + a binomial tree graph. For example: + + .. jupyter-execute:: + + import retworkx + from retworkx.visualization import mpl_draw + + graph = retworkx.generators.binomial_tree_graph(4) + mpl_draw(graph) + + .. jupyter-execute:: + + import retworkx + from retworkx.visualization import mpl_draw + + graph = retworkx.generators.directed_binomial_tree_graph(4) + mpl_draw(graph) diff --git a/releasenotes/notes/add-copy-method-f2abb1222b323dab.yaml b/releasenotes/notes/0.9.0/add-copy-method-f2abb1222b323dab.yaml similarity index 100% rename from releasenotes/notes/add-copy-method-f2abb1222b323dab.yaml rename to releasenotes/notes/0.9.0/add-copy-method-f2abb1222b323dab.yaml diff --git a/releasenotes/notes/add-core_number-b1d3b2fb7ebd276f.yaml b/releasenotes/notes/0.9.0/add-core_number-b1d3b2fb7ebd276f.yaml similarity index 100% rename from releasenotes/notes/add-core_number-b1d3b2fb7ebd276f.yaml rename to releasenotes/notes/0.9.0/add-core_number-b1d3b2fb7ebd276f.yaml diff --git a/releasenotes/notes/add-edge-indices-method-c1868ab1dab61b18.yaml b/releasenotes/notes/0.9.0/add-edge-indices-method-c1868ab1dab61b18.yaml similarity index 100% rename from releasenotes/notes/add-edge-indices-method-c1868ab1dab61b18.yaml rename to releasenotes/notes/0.9.0/add-edge-indices-method-c1868ab1dab61b18.yaml diff --git a/releasenotes/notes/add-num-methods-08ac0963b9961f5e.yaml b/releasenotes/notes/0.9.0/add-num-methods-08ac0963b9961f5e.yaml similarity index 100% rename from releasenotes/notes/add-num-methods-08ac0963b9961f5e.yaml rename to releasenotes/notes/0.9.0/add-num-methods-08ac0963b9961f5e.yaml diff --git a/releasenotes/notes/add-nx-converter-1feffc8d5aa13365.yaml b/releasenotes/notes/0.9.0/add-nx-converter-1feffc8d5aa13365.yaml similarity index 100% rename from releasenotes/notes/add-nx-converter-1feffc8d5aa13365.yaml rename to releasenotes/notes/0.9.0/add-nx-converter-1feffc8d5aa13365.yaml diff --git a/releasenotes/notes/0.9.0/add-random-geometric-graph-ef131e3955c6b178.yaml b/releasenotes/notes/0.9.0/add-random-geometric-graph-ef131e3955c6b178.yaml new file mode 100644 index 0000000000..3f47cccecf --- /dev/null +++ b/releasenotes/notes/0.9.0/add-random-geometric-graph-ef131e3955c6b178.yaml @@ -0,0 +1,14 @@ +--- +features: + - | + Added new function :func:`~retworkx.random_geometric_graph` which can be + used to generate random geometric graphs. For example: + + .. jupyter-execute:: + + import retworkx + from retworkx.visualization import mpl_draw + + + graph = retworkx.random_geometric_graph(8, .95, 5) + mpl_draw(graph) diff --git a/releasenotes/notes/add-random-layout-c1c2751be971e5d0.yaml b/releasenotes/notes/0.9.0/add-random-layout-c1c2751be971e5d0.yaml similarity index 100% rename from releasenotes/notes/add-random-layout-c1c2751be971e5d0.yaml rename to releasenotes/notes/0.9.0/add-random-layout-c1c2751be971e5d0.yaml diff --git a/releasenotes/notes/add-transitivity-function-c32d2bbbf3857c40.yaml b/releasenotes/notes/0.9.0/add-transitivity-function-c32d2bbbf3857c40.yaml similarity index 66% rename from releasenotes/notes/add-transitivity-function-c32d2bbbf3857c40.yaml rename to releasenotes/notes/0.9.0/add-transitivity-function-c32d2bbbf3857c40.yaml index 5c7054f727..e1a9f82ac6 100644 --- a/releasenotes/notes/add-transitivity-function-c32d2bbbf3857c40.yaml +++ b/releasenotes/notes/0.9.0/add-transitivity-function-c32d2bbbf3857c40.yaml @@ -1,6 +1,6 @@ --- features: - | - A new function, :func:`~retworkx.transitivity` was added to + Added new function, :func:`~retworkx.transitivity` was added to calculate the transitivity coefficient of a :class:`~retworkx.PyGraph` and a :class:`~retworkx.PyDiGraph`. diff --git a/releasenotes/notes/bump-msrv-d581a8cbeff8915b.yaml b/releasenotes/notes/0.9.0/bump-msrv-d581a8cbeff8915b.yaml similarity index 100% rename from releasenotes/notes/bump-msrv-d581a8cbeff8915b.yaml rename to releasenotes/notes/0.9.0/bump-msrv-d581a8cbeff8915b.yaml diff --git a/releasenotes/notes/complement-361c90c7dda69df8.yaml b/releasenotes/notes/0.9.0/complement-361c90c7dda69df8.yaml similarity index 100% rename from releasenotes/notes/complement-361c90c7dda69df8.yaml rename to releasenotes/notes/0.9.0/complement-361c90c7dda69df8.yaml diff --git a/releasenotes/notes/custom-path-returns-e1d5fc1e02809179.yaml b/releasenotes/notes/0.9.0/custom-path-returns-e1d5fc1e02809179.yaml similarity index 100% rename from releasenotes/notes/custom-path-returns-e1d5fc1e02809179.yaml rename to releasenotes/notes/0.9.0/custom-path-returns-e1d5fc1e02809179.yaml diff --git a/releasenotes/notes/dijkstra-all-pairs-ecdc3d9a5a267350.yaml b/releasenotes/notes/0.9.0/dijkstra-all-pairs-ecdc3d9a5a267350.yaml similarity index 100% rename from releasenotes/notes/dijkstra-all-pairs-ecdc3d9a5a267350.yaml rename to releasenotes/notes/0.9.0/dijkstra-all-pairs-ecdc3d9a5a267350.yaml diff --git a/releasenotes/notes/0.9.0/expand-isomorphism-cfb646cfef66fa25.yaml b/releasenotes/notes/0.9.0/expand-isomorphism-cfb646cfef66fa25.yaml new file mode 100644 index 0000000000..7d64828363 --- /dev/null +++ b/releasenotes/notes/0.9.0/expand-isomorphism-cfb646cfef66fa25.yaml @@ -0,0 +1,14 @@ +--- +features: + - | + The :func:`~retworkx.is_isomorphic` function has been expanded so it can + now also take in a :class:`~retworkx.PyGraph` in addition to the + the :class:`~retworkx.PyDiGraph` already supported. + - | + The :func:`~retworkx.is_isomorphic` function now has two new optional + kwargs ``node_matcher`` and ``edge_matcher`` which can be used to specify + functions to use for comparing node and edge data payloads. + - | + The :func:`~retworkx.is_isomorphic_node_match` function has been expanded + so it can take in a :class:`~retworkx.PyGraph` in addition to the + :class:`~retworkx.PyDiGraph` it already supported. diff --git a/releasenotes/notes/0.9.0/extend-generators-07a5d34d5e637a6a.yaml b/releasenotes/notes/0.9.0/extend-generators-07a5d34d5e637a6a.yaml new file mode 100644 index 0000000000..b36bf6bb40 --- /dev/null +++ b/releasenotes/notes/0.9.0/extend-generators-07a5d34d5e637a6a.yaml @@ -0,0 +1,23 @@ +--- +features: + - | + Added new generator functions, + :func:`retworkx.generators.directed_hexagonal_lattice_graph` and + :func:`retworkx.generators.hexagonal_lattice_graph`, for constructing a + hexagonal lattice graph. For example: + + .. jupyter-execute:: + + import retworkx + from retworkx.visualization import mpl_draw + + graph = retworkx.generators.directed_hexagonal_lattice_graph(3, 3) + mpl_draw(graph) + + .. jupyter-execute:: + + import retworkx + from retworkx.visualization import mpl_draw + + graph = retworkx.generators.hexagonal_lattice_graph(3, 3) + mpl_draw(graph) diff --git a/releasenotes/notes/0.9.0/find-successors-by-d3589b1b1d0b1633.yaml b/releasenotes/notes/0.9.0/find-successors-by-d3589b1b1d0b1633.yaml new file mode 100644 index 0000000000..acfb3c1734 --- /dev/null +++ b/releasenotes/notes/0.9.0/find-successors-by-d3589b1b1d0b1633.yaml @@ -0,0 +1,8 @@ +--- +features: + - | + Added two new methods, :meth:`~retworkx.PyDiGraph.find_successors_by_edge` + and :meth:`~retworkx.PyDiGraph.find_predecessors_by_edge`, were added to + :class:`~retworkx.PyDiGraph`. These methods efficiently retrieve the + neighbors in the graph which are connected to a node with edges matching a + filter function. diff --git a/releasenotes/notes/fixed-mutability-0ab3030db0d77239.yaml b/releasenotes/notes/0.9.0/fixed-mutability-0ab3030db0d77239.yaml similarity index 100% rename from releasenotes/notes/fixed-mutability-0ab3030db0d77239.yaml rename to releasenotes/notes/0.9.0/fixed-mutability-0ab3030db0d77239.yaml diff --git a/releasenotes/notes/floyd-warshall-fix-d8ec2131dfaeab82.yaml b/releasenotes/notes/0.9.0/floyd-warshall-fix-d8ec2131dfaeab82.yaml similarity index 100% rename from releasenotes/notes/floyd-warshall-fix-d8ec2131dfaeab82.yaml rename to releasenotes/notes/0.9.0/floyd-warshall-fix-d8ec2131dfaeab82.yaml diff --git a/releasenotes/notes/0.9.0/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml b/releasenotes/notes/0.9.0/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml new file mode 100644 index 0000000000..94b5cc97bf --- /dev/null +++ b/releasenotes/notes/0.9.0/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml @@ -0,0 +1,11 @@ +--- +features: + - | + The :func:`~retworkx.is_isomorphic` and + :func:`~retworkx.is_isomorphic_node_match` functions have a new kwarg, + ``id_order`` which is used to adjust the node matching order used. + If you set ``id_order=False`` then the matching order used is the heuristic + matching order proposed in the + `VF2++ paper `__. If you + want to retain use the order based on node ids, you can set + ``id_order=True`` which is the default behavior. diff --git a/releasenotes/notes/0.9.0/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml b/releasenotes/notes/0.9.0/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml new file mode 100644 index 0000000000..25b48e6dc6 --- /dev/null +++ b/releasenotes/notes/0.9.0/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml @@ -0,0 +1,11 @@ +--- +features: + - | + Added new function, :func:`~retworkx.minimum_spanning_tree`, to calculate the + minimum spanning tree of a :class:`~retworkx.PyGraph` object and return the + MST as a new :class:`~retworkx.PyGraph` object. + - | + Added a new function, :func:`~retworkx.minimum_spanning_edges`, to calculate + the minimum spanning tree of a :class:`~retworkx.PyGraph` object and return + the :class:`~retworkx.WeightedEdgeList` for the weighted edge list of the + MST of a graph. diff --git a/releasenotes/notes/mpl-draw-f2a3224671907eaf.yaml b/releasenotes/notes/0.9.0/mpl-draw-f2a3224671907eaf.yaml similarity index 100% rename from releasenotes/notes/mpl-draw-f2a3224671907eaf.yaml rename to releasenotes/notes/0.9.0/mpl-draw-f2a3224671907eaf.yaml diff --git a/releasenotes/notes/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml b/releasenotes/notes/0.9.0/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml similarity index 100% rename from releasenotes/notes/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml rename to releasenotes/notes/0.9.0/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml diff --git a/releasenotes/notes/0.9.0/prepare-0.9-dab64f0197fc6233.yaml b/releasenotes/notes/0.9.0/prepare-0.9-dab64f0197fc6233.yaml new file mode 100644 index 0000000000..9c87010402 --- /dev/null +++ b/releasenotes/notes/0.9.0/prepare-0.9-dab64f0197fc6233.yaml @@ -0,0 +1,11 @@ +--- +prelude: | + This release is a new feature release that includes a plethora of new + features and bug fixes. The highlights of this release are the introduction + of the :mod:`retwork.visualization` module, which includes a + `matplotlib `__ based drawer + (:func:`~retworkx.visualization.mpl_draw`), and layout functions such + as :func:`~retworkx.spring_layout` for generating a layout in + visualization. Additionally, the generator functions in + :mod:`retworkx.generators` have been expanded to include new graph + generators, and new algorithm functions have been added. diff --git a/releasenotes/notes/0.9.0/spring-layout-c21a31f21bc113a0.yaml b/releasenotes/notes/0.9.0/spring-layout-c21a31f21bc113a0.yaml new file mode 100644 index 0000000000..a53d23cbb0 --- /dev/null +++ b/releasenotes/notes/0.9.0/spring-layout-c21a31f21bc113a0.yaml @@ -0,0 +1,7 @@ +--- +features: + - | + Added a new function, :func:`~retworkx.spring_layout` to generate layouts + for :class:`~retworkx.PyGraph` and :class:`~retworkx.PyDiGraph` + using the `Fruchterman-Reingold force-directed algorithm + `__. diff --git a/releasenotes/notes/write_edge_list-5f3de403770a811e.yaml b/releasenotes/notes/0.9.0/write_edge_list-5f3de403770a811e.yaml similarity index 100% rename from releasenotes/notes/write_edge_list-5f3de403770a811e.yaml rename to releasenotes/notes/0.9.0/write_edge_list-5f3de403770a811e.yaml diff --git a/releasenotes/notes/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml b/releasenotes/notes/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml deleted file mode 100644 index 23bef73d62..0000000000 --- a/releasenotes/notes/add-binomial-tree-graph-generator-1f6ff6ba3809b901.yaml +++ /dev/null @@ -1,4 +0,0 @@ ---- -features: - - | - Added a new generator for constructing a binomial tree graph (:func:`retworkx.generators.binomial_tree_graph`). diff --git a/releasenotes/notes/add-random-geometric-graph-ef131e3955c6b178.yaml b/releasenotes/notes/add-random-geometric-graph-ef131e3955c6b178.yaml deleted file mode 100644 index 4faf085ebe..0000000000 --- a/releasenotes/notes/add-random-geometric-graph-ef131e3955c6b178.yaml +++ /dev/null @@ -1,5 +0,0 @@ ---- -features: - - | - A new function :func:`~retworkx.random_geometric_graph` was added - to generate random geometric graphs. diff --git a/releasenotes/notes/expand-isomorphism-cfb646cfef66fa25.yaml b/releasenotes/notes/expand-isomorphism-cfb646cfef66fa25.yaml deleted file mode 100644 index c8153a3aef..0000000000 --- a/releasenotes/notes/expand-isomorphism-cfb646cfef66fa25.yaml +++ /dev/null @@ -1,9 +0,0 @@ ---- -features: - - | - :func:`~retworkx.is_isomorphic` can take in a :class:`~retworkx.PyGraph` - or :class:`~retworkx.PyDiGraph`. You can optionally specify two functions - to compare node and edge data. - - | - :func:`~retworkx.is_isomorphic_node_match` can take in a :class:`~retworkx.PyGraph` - or :class:`~retworkx.PyDiGraph`. diff --git a/releasenotes/notes/extend-generators-07a5d34d5e637a6a.yaml b/releasenotes/notes/extend-generators-07a5d34d5e637a6a.yaml deleted file mode 100644 index f42cc8b899..0000000000 --- a/releasenotes/notes/extend-generators-07a5d34d5e637a6a.yaml +++ /dev/null @@ -1,5 +0,0 @@ ---- -features: - - | - Added new generators for constructing a hexagonal lattice graph (:func:`retworkx.generators.hexagonal_lattice_graph`) - and directed hexagonal lattice graph (:func:`retworkx.generators.directed_hexagonal_lattice_graph`). diff --git a/releasenotes/notes/find-successors-by-d3589b1b1d0b1633.yaml b/releasenotes/notes/find-successors-by-d3589b1b1d0b1633.yaml deleted file mode 100644 index 3f1a527b36..0000000000 --- a/releasenotes/notes/find-successors-by-d3589b1b1d0b1633.yaml +++ /dev/null @@ -1,6 +0,0 @@ ---- -features: - - | - Two new functions were added to :class:`~retworkx.PyDiGraph`: :meth:`~retworkx.PyDiGraph.find_successors_by_edge` - and :meth:`~retworkx.PyDiGraph.find_predecessors_by_edge` to efficiently retrieve the neighbors in the graph - who are connected to a node with edges matching a filter function. diff --git a/releasenotes/notes/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml b/releasenotes/notes/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml deleted file mode 100644 index 9d3716579d..0000000000 --- a/releasenotes/notes/is-isomorphic-matching-order-be0cfa8b796cd55c.yaml +++ /dev/null @@ -1,7 +0,0 @@ ---- -features: - - | - :func:`~retworkx.is_isomorphic` and :func:`~retworkx.is_isomorphic_node_match` - match the nodes in order specified by a heuristic matching order proposed - in VF2++ paper, if `id_order=False`. If you want to use the order based on - node ids, you should set `id_order=True`. diff --git a/releasenotes/notes/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml b/releasenotes/notes/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml deleted file mode 100644 index da32509eeb..0000000000 --- a/releasenotes/notes/minimum-spanning-tree-4afa29b3c0dbd2fb.yaml +++ /dev/null @@ -1,6 +0,0 @@ ---- -features: - - | - Two new functions were added: :func:`~retworkx.minimum_spanning_tree` to calculate the - MST of a :class:`~retworkx.PyGraph`, and :func:`~retworkx.minimum_spanning_edges` to - retrieve the :class:`~retworkx.WeightedEdgeList` of the MST of a graph. diff --git a/releasenotes/notes/spring-layout-c21a31f21bc113a0.yaml b/releasenotes/notes/spring-layout-c21a31f21bc113a0.yaml deleted file mode 100644 index aa48261fb2..0000000000 --- a/releasenotes/notes/spring-layout-c21a31f21bc113a0.yaml +++ /dev/null @@ -1,6 +0,0 @@ ---- -features: - - | - Add a new function, `~retworkx.spring_layout` to generate layouts for - :class:`~retworkx.PyGraph` and :class:`~retworkx.PyDiGraph` - using Fruchterman-Reingold force-directed algorithm. diff --git a/retworkx/__init__.py b/retworkx/__init__.py index 2f671deb87..6065cb4a9e 100644 --- a/retworkx/__init__.py +++ b/retworkx/__init__.py @@ -26,9 +26,11 @@ class PyDAG(PyDiGraph): The PyDAG class is used to create a directed graph. It can be a multigraph (have multiple edges between nodes). Each node and edge - (although rarely used for edges) is indexed by an integer id. Additionally, - each node and edge contains an arbitrary Python object as a weight/data - payload. + (although rarely used for edges) is indexed by an integer id. These ids + are stable for the lifetime of the graph object and on node or edge + deletions you can have holes in the list of indices for the graph. + Additionally, each node and edge contains an arbitrary Python object as a + weight/data payload. You can use the index for access to the data payload as in the following example: @@ -82,6 +84,26 @@ class PyDAG(PyDiGraph): penalty that grows as the graph does. If you're adding a node and edge at the same time, leveraging :meth:`PyDAG.add_child` or :meth:`PyDAG.add_parent` will avoid this overhead. + + By default a ``PyDAG`` is a multigraph (meaning there can be parallel + edges between nodes) however this can be disabled by setting the + ``multigraph`` kwarg to ``False`` when calling the ``PyDAG`` constructor. + For example:: + + import retworkx + dag = retworkx.PyDAG(multigraph=False) + + This can only be set at ``PyDiGraph`` initialization and not adjusted after + creation. When :attr:`~retworkx.PyDiGraph.multigraph` is set to ``False`` + if a method call is made that would add a parallel edge it will instead + update the existing edge's weight/data payload. + + :param bool check_cycle: When this is set to ``True`` the created + ``PyDAG`` has runtime cycle detection enabled. + :param bool multgraph: When this is set to ``False`` the created + ``PyDAG`` object will not be a multigraph. When ``False`` if a method + call is made that would add parallel edges the the weight/weight from + that method call will be used to update the existing edge in place. """ pass diff --git a/src/digraph.rs b/src/digraph.rs index 0a1daea328..d687514865 100644 --- a/src/digraph.rs +++ b/src/digraph.rs @@ -54,12 +54,14 @@ use super::{ /// A class for creating directed graphs /// -/// The PyDiGraph class is used to create a directed graph. It can be a +/// The ``PyDiGraph`` class is used to create a directed graph. It can be a /// multigraph (have multiple edges between nodes). Each node and edge -/// (although rarely used for edges) is indexed by an integer id. Additionally -/// each node and edge contains an arbitrary Python object as a weight/data -/// payload. You can use the index for access to the data payload as in the -/// following example: +/// (although rarely used for edges) is indexed by an integer id. These ids +/// are stable for the lifetime of the graph object and on node or edge +/// deletions you can have holes in the list of indices for the graph. +/// Additionally, each node and edge contains an arbitrary Python object as a +/// weight/data payload. You can use the index for access to the data payload +/// as in the following example: /// /// .. jupyter-execute:: /// @@ -110,6 +112,26 @@ use super::{ /// penalty that grows as the graph does. If you're adding a node and edge at /// the same time leveraging :meth:`PyDiGraph.add_child` or /// :meth:`PyDiGraph.add_parent` will avoid this overhead. +/// +/// By default a ``PyDiGraph`` is a multigraph (meaning there can be parallel +/// edges between nodes) however this can be disabled by setting the +/// ``multigraph`` kwarg to ``False`` when calling the ``PyDiGraph`` +/// constructor. For example:: +/// +/// import retworkx +/// graph = retworkx.PyDiGraph(multigraph=False) +/// +/// This can only be set at ``PyDiGraph`` initialization and not adjusted after +/// creation. When :attr:`~retworkx.PyDiGraph.multigraph` is set to ``False`` +/// if a method call is made that would add a parallel edge it will instead +/// update the existing edge's weight/data payload. +/// +/// :param bool check_cycle: When this is set to ``True`` the created +/// ``PyDiGraph`` has runtime cycle detection enabled. +/// :param bool multgraph: When this is set to ``False`` the created +/// ``PyDiGraph`` object will not be a multigraph. When ``False`` if a +/// method call is made that would add parallel edges the the weight/weight +/// from that method call will be used to update the existing edge in place. #[pyclass(module = "retworkx", subclass, gc)] #[text_signature = "(/, check_cycle=False, multigraph=True)"] #[derive(Clone)] diff --git a/src/graph.rs b/src/graph.rs index 7a3cb48fc7..b6ca605694 100644 --- a/src/graph.rs +++ b/src/graph.rs @@ -49,10 +49,12 @@ use petgraph::visit::{ /// /// The PyGraph class is used to create an undirected graph. It can be a /// multigraph (have multiple edges between nodes). Each node and edge -/// (although rarely used for edges) is indexed by an integer id. Additionally, -/// each node and edge contains an arbitrary Python object as a weight/data -/// payload. You can use the index for access to the data payload as in the -/// following example: +/// (although rarely used for edges) is indexed by an integer id. These ids +/// are stable for the lifetime of the graph object and on node or edge +/// deletions you can have holes in the list of indices for the graph. +/// Additionally, each node and edge contains an arbitrary Python object as a +/// weight/data payload. You can use the index for access to the data payload +/// as in the following example: /// /// .. jupyter-execute:: /// @@ -78,12 +80,23 @@ use petgraph::visit::{ /// print("Node Index: %s" % node_index) /// print(graph[node_index]) /// +/// By default a ``PyGraph`` is a multigraph (meaning there can be parallel +/// edges between nodes) however this can be disabled by setting the +/// ``multigraph`` kwarg to ``False`` when calling the ``PyGraph`` +/// constructor. For example:: +/// +/// import retworkx +/// graph = retworkx.PyGraph(multigraph=False) +/// +/// This can only be set at ``PyGraph`` initialization and not adjusted after +/// creation. When :attr:`~retworkx.PyGraph.multigraph` is set to ``False`` +/// if a method call is made that would add a parallel edge it will instead +/// update the existing edge's weight/data payload. /// /// :param bool multigraph: When this is set to ``False`` the created PyGraph -/// object will not be a multigraph (which is the default behavior). When -/// ``False`` if parallel edges are added the weight/weight from that +/// object will not be a multigraph. When ``False`` if a method call is +/// made that would add parallel edges the the weight/weight from that /// method call will be used to update the existing edge in place. -/// #[pyclass(module = "retworkx", subclass, gc)] #[text_signature = "(/, multigraph=True)"] #[derive(Clone)]