Prepare 0.9.0 release

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.