Prepare 0.9.0 release (#339)

* 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

* Move new release notes

* Add readme section on optional dependencies

* Fix lint

* Move new release notes

* Update readme based on review comments

* Update index intro based on review comments

* Update release prelude to mention pydot_draw

* Move new release notes

* Use mpl_draw in docstrings

* Add example to graphviz_draw doc

* Update add-transitivity-function-c32d2bbbf3857c40.yaml

* Apply suggestions from code review

Co-authored-by: Ivan Carvalho <[email protected]>

* Update prepare-0.9-dab64f0197fc6233.yaml

* Update pydot-drawer-c5df0aa830679748.yaml

* Update README.md

* Update multigraph release note

* Move and update last new release note

* Add examples to spring layout release note

* Add examples to random layout

* Update add-random-layout-c1c2751be971e5d0.yaml

README.md

@@ -53,6 +53,25 @@ pip install retworkx
 will build retworkx for your local system from the source package and install
 it just as it would if there was a prebuilt binary available.
 
+### Optional dependencies
+
+If you're planning to use the `retworkx.visualization` module you will need to
+install optional dependencies to use the functions. The matplotlib based drawer
+function `retworkx.visualization.mpl_draw` requires that the
+[matplotlib](https://matplotlib.org/) library is installed. This can be
+installed with `pip install matplotlib` or when you're installing retworkx with
+`pip install 'retworkx[mpl]'`. If you're going to use the graphviz based drawer
+function `retworkx.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 [pydot](https://pypi.org/project/pydot/) and
+[pillow](https://python-pillow.org/) Python libraries. This can be done either
+with `pip install pydot pillow` or when installing retworkx with
+`pip install 'retworkx[graphviz]'`.
+
+If you would like to install all the optional Python dependencies when you
+install retworkx you can use `pip install 'retworkx[all]'` to do this.
+
 ## Building from source
 
 The first step for building retworkx from source is to clone it locally

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 <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 are not running on one of these platforms, you will need a rust compiler
+to install retworkx.
+
+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 it
+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 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/0.9.0/add-random-layout-c1c2751be971e5d0.yaml

@@ -0,0 +1,50 @@
+---
+features:
+  - |
+    Added a new layout function, :func:`retworkx.random_layout` (and it's
+    equivalent per type variants :func:`retworkx.graph_random_layout` and
+    :func:`retworkx.diraph_random_layout`) to generate a random layout which
+    can be used for visualizations. For example:
+
+    .. jupyter-execute::
+
+      import retworkx
+      from retworkx.visualization import mpl_draw
+
+      graph = retworkx.generators.directed_grid_graph(5, 5)
+      layout = retworkx.random_layout(graph)
+      mpl_draw(graph, pos=layout)
+
+    or with the :func:`~retworkx.visualization.graphviz_draw` function:
+
+    .. jupyter-execute::
+
+      import retworkx
+      from retworkx.visualization import graphviz_draw
+
+      graph = retworkx.generators.directed_grid_graph(5, 5)
+      layout = retworkx.random_layout(graph)
+      for i in range(25):
+        graph[i] = i
+
+      def node_attr_fn(node):
+          point = layout[node]
+          return {
+              "shape": "circle",
+              "pos": '"%s,%s!"' % (point[0], point[1]),
+              "fillcolor": "yellow",
+              "style": "filled",
+              "fixedsize": "true"
+          }
+
+      graphviz_draw(graph, node_attr_fn=node_attr_fn, method='fdp')
+
+  - |
+    A new custom return class, :class:`retworkx.Pos2DMapping`, has been
+    added. This class will be returned by layout functions and is a drop
+    in replacement for an immutable read-only dictionary of the form::
+
+      {1: [0.1, 0.5]}
+
+    where the keys are node indices and the values are a 2 element sequence
+    that represents the position for the node.

releasenotes/notes/0.9.0/add-subgraph-isomorphism-d22c1b5b015769ec.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Added a new function, :func:`~retworkx.is_subgraph_isomorphic`, to
+    determine if two graphs of the same type (either :class:`~retworkx.PyGraph`
+    or :class:`~retworkx.PyDiGraph`) are induced subgraph isomorphic.

releasenotes/notes/0.9.0/add-transitivity-function-c32d2bbbf3857c40.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    A new function, :func:`~retworkx.transitivity`, was added to
+    calculate the transitivity coefficient of a :class:`~retworkx.PyGraph`
+    or a :class:`~retworkx.PyDiGraph` object.

releasenotes/notes/edge-index-map-cf07a035d02481a1.yaml → releasenotes/notes/0.9.0/edge-index-map-cf07a035d02481a1.yaml

@@ -11,4 +11,4 @@ features:
     Added a new custom return type :class:`~retworkx.EdgeIndexMap` which is
     returned by :meth:`retworkx.PyDiGraph.edge_index_map` and
     :meth:`retworkx.PyGraph.edge_index_map`. It is equivalent to a read-only
-    dict/mapping that represent a mapping of edge indices to the edge.
+    dict/mapping that represent a mapping of edge indices to the edge tuple.

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`, 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/multigraph-to-directed-generators-dc7bbb53480d5d0a.yaml

@@ -0,0 +1,16 @@
+---
+features:
+  - |
+    A new kwarg, ``multigraph`` was added to the :class:`~retworkx.PyDiGraph`
+    generator functions:
+
+     * :func:`retworkx.generators.directed_cycle_graph`
+     * :func:`retworkx.generators.directed_path_graph`
+     * :func:`retworkx.generators.directed_star_graph`
+     * :func:`retworkx.generators.directed_mesh_graph`
+     * :func:`retworkx.generators.directed_grid_graph`
+
+    This can be used to set whether the generated
+    :class:`~retworkx.PyDiGraph` objects are multi graphs or not (to set
+    whether parallel edges can be added or not). By default this is set to
+    ``True``.

releasenotes/notes/0.9.0/prepare-0.9-dab64f0197fc6233.yaml

@@ -0,0 +1,13 @@
+---
+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 a
+    `graphviz <https://graphviz.org/>`__ based drawer
+    (:func:`~retworkx.visualization.graphviz_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 many new algorithm functions have been added.