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 Qiskit#328

docs/source/index.rst

@@ -2,12 +2,48 @@
 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 <https://www.apache.org/licenses/LICENSE-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 <https://www.rust-lang.org/>`__ 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 <https://networkx.org/>`__
+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 <README>
    Retworkx API <api>
    Visualization <visualization>
    Release Notes <release_notes>

docs/source/networkx.rst

@@ -1,3 +1,5 @@
+.. _networkx:
+
 ###########################
 retworkx for networkx users
 ###########################

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
 =====
 

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)

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)

releasenotes/notes/add-transitivity-function-c32d2bbbf3857c40.yaml → 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`.

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.

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)

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.

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 <http://bolyai.cs.elte.hu/egres/tr/egres-18-03.pdf>`__. If you
+    want to retain use the order based on node ids, you can set
+    ``id_order=True`` which is the default behavior.

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.

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 <https://matplotlib.org/>`__ 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.

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 
+    <https://onlinelibrary.wiley.com/doi/abs/10.1002/spe.4380211102>`__.

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

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