Prepare 0.11.0 release (#549)

* Prepare 0.11.0 release

This commit prepares the repository for the 0.11.0 release. It makes 2
primary changes it moves the release notes for this release to a
separate directory to separate the release notes from future releases.
The second change is a adding a release note for the prelude providing
the highlights for the release.

* Fix doc build

* Move and update new release notes

* Move new release notes

* Start editing and fixing release notes

* Fix code example for barbell graph release note

* Fix issues in the remaining release notes

* Add note about api stability in retworkx-core to release note

* Apply suggestions from code review

Co-authored-by: Jake Lishman <[email protected]>

* Update releasenotes/notes/0.11/add-cartesian-product-f57b4aeb8cbebee7.yaml

* Add links to retworkx-core on crates.io

* Apply suggestions from code review

Co-authored-by: Kevin Hartman <[email protected]>

Co-authored-by: Jake Lishman <[email protected]>
Co-authored-by: Kevin Hartman <[email protected]>

.mailmap

@@ -0,0 +1,20 @@
+# Entries in this file are made for two reasons:
+# 1) to merge multiple git commit authors that correspond to a single author
+# 2) to change the canonical name and/or email address of an author.
+#
+# Format is:
+#     Canonical Name <Canonical@email> commit name <commit@email>
+#     \--------------+---------------/ \----------+-------------/
+#                 replace                       find
+# See also: 'git shortlog --help' and 'git check-mailmap --help'.
+#
+# If you don't like the way your name is cited by qiskit, please feel free to
+# open a pull request against this file to set your preferred naming.
+#
+# Note that each qiskit element uses its own mailmap so it may be necessary to
+# propagate changes in other repos for consistency.
+#
+
+Ivan Carvalho <[email protected]> <[email protected]>
+Ivan Carvalho <[email protected]> <[email protected]>
+Ivan Carvalho <[email protected]> <[email protected]>

releasenotes/notes/0.11/add-cartesian-product-f57b4aeb8cbebee7.yaml

@@ -0,0 +1,19 @@
+---
+features:
+  - |
+    Added a new function, :func:`~retworkx.cartesian_product` (and its per
+    type variants :func:`~retworkx.digraph_cartesian_product` and
+    :func:`~retworkx.graph_cartesian_product`), which calculates the Cartesian
+    product of two graphs. For example:
+    
+    .. jupyter-execute::
+
+      import retworkx
+      from retworkx.visualization import mpl_draw
+
+      graph_1 = retworkx.generators.path_graph(2)
+      graph_2 = retworkx.generators.path_graph(3)
+
+      graph_product, _ = retworkx.cartesian_product(graph_1, graph_2)
+      
+      mpl_draw(graph_product)

releasenotes/notes/add-node-indices-3c7c37ed4ea75a2c.yaml → releasenotes/notes/0.11/add-node-indices-3c7c37ed4ea75a2c.yaml

@@ -2,7 +2,7 @@
 features:
   - |
     Added a new method, :meth:`~retworkx.PyDiGraph.node_indices`, to the
-    :class:`~retworkx.PyDigraph` and :class:`~retworkx.PyGraph` classes.
+    :class:`~retworkx.PyDiGraph` and :class:`~retworkx.PyGraph` classes.
     This method is identical to the previously existing
     :meth:`~retworkx.PyDiGraph.node_indexes` method but changes the name
     to be consistent with the use of "indices" throughout the rest of

releasenotes/notes/0.11/average-path-length-disconnected-56b118a964af085a.yaml

@@ -0,0 +1,28 @@
+---
+features:
+  - |
+    The :func:`~retworkx.unweighted_average_shortest_path_length` function
+    has a new kwarg ``disconnected``. When ``disconnected`` is set to ``True``
+    the output value calculated by the function will only account for connected
+    node pairs.
+upgrade:
+  - |
+    The default behavior for how the
+    :func:`~retworkx.unweighted_average_shortest_path_length` function handles
+    disconnected graphs has been changed. Previously, disconnected pairs of nodes
+    was assumed to have zero distance which is arguably incorrect/unexpected
+    behavior. To make this more consistent with user expectations this has been
+    changed to an infinite value. In addition, an extra kwarg ``disconnected``
+    was added where, if set to ``True``, the average is taken only over connected
+    node pairs. By default, it's set to ``False``. If the previous behavior of
+    treating disconnected pairs of nodes as having a distance of zero is desired,
+    it can be reproduced using the rest of retworkx API like:
+
+    .. code-block:: python
+
+        import retworkx
+
+        graph = retworkx.undirected_gnm_random_graph(20, 10, seed=42)
+        n = len(graph)
+        d_mat = retworkx.distance_matrix(graph, null_value=0.0)
+        avg_shortest_path = d_mat.sum() / (n * (n - 1.0))

releasenotes/notes/0.11/barbell-graph-generator-5cc9df7148b1a09e.yaml

@@ -0,0 +1,14 @@
+---
+features:
+  - |
+    Added a new generator function, :func:`~retworkx.generators.barbell_graph`,
+    to the ``retworkx.generators`` module that will generate a barbell graph.
+    For example:
+
+    .. jupyter-execute::
+
+      import retworkx.generators
+      from retworkx.visualization import mpl_draw
+
+      graph = retworkx.generators.barbell_graph(4, 3)
+      mpl_draw(graph)

releasenotes/notes/0.11/bugfix-node-holes-210d1b4d329df6dc.yaml

@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    Fixed an issue where :func:`~retworkx.distance_matrix` and
+    :func:`~retworkx.k_shortest_path_lengths` would previously panic if the
+    input graph contains holes in the node indices.

releasenotes/notes/contract-nodes-6ef30bb227fab68d.yaml → releasenotes/notes/0.11/contract-nodes-6ef30bb227fab68d.yaml

@@ -1,7 +1,7 @@
 ---
 features:
   - |
-    New graph class methods :meth:`retworkx.PyDiGraph.contract_nodes`,
+    Added new graph methods :meth:`retworkx.PyDiGraph.contract_nodes`,
     and :meth:`retworkx.PyGraph.contract_nodes`.
     These methods can be used to replace a set of graph nodes with a single new
     equivalent node. Incoming edges and outgoing edges of and to the

releasenotes/notes/edge-index-methods-427f7301c720f565.yaml → releasenotes/notes/0.11/edge-index-methods-427f7301c720f565.yaml

@@ -29,8 +29,8 @@ features:
     its index.
   - |
     Added two new methods, :meth:`~retworkx.PyGraph.out_edges` and
-    :meth:`~retworkx.PyGraph.in_edges`. These methods are the dual of the
-    :class:`~retworkx.PyDiGraph` methods, :meth:`~retworkx.PyDiGraph.out_edges`
-    and :meth:`~retworkx.PyDiGraph.in_edges` and return a
+    :meth:`~retworkx.PyGraph.in_edges` to the :class:`~retworkx.PyGraph` class.
+    These methods are the duals of the :class:`~retworkx.PyDiGraph` methods,
+    :meth:`~retworkx.PyDiGraph.out_edges` and
+    :meth:`~retworkx.PyDiGraph.in_edges` and return a
     :class:`~retworkx.WeightedEdgeList` of the incident edges for a node.
-

releasenotes/notes/0.11/faster-steiner-tree-0066d7cd2df1b28d.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    The algorithm used for the :func:`~retworkx.steiner_tree` implementation
+    has been replaced by a faster algorithm based on:
+    https://doi.org/10.1016/0020-0190(88)90066-X. This new implementation
+    achieves the same approximation ratio as the algorithm used previously,
+    so there should be no change in functionality.

releasenotes/notes/0.11/fix-degree-with-self-loops-5b40c45cc61fcebe.yaml

@@ -0,0 +1,7 @@
+---
+fixes:
+  - |
+    Fixed the :meth:`retworkx.PyGraph.degree` method when running on a node
+    that has self-loops. Previously, the method would increment the node's
+    degree of a self-loop by one instead of two.
+    Fixed `#517 <https://github.com/Qiskit/retworkx/issues/517>`__.

releasenotes/notes/0.11/fix-dispatch-3596ef110cc68338.yaml

@@ -0,0 +1,11 @@
+---
+fixes:
+  - |
+    Fixed the :func:`~retworkx.dfs_edges` function to have the ``source``
+    argument default to ``None`` as was documented. Previously, the ``source``
+    argument was incorrectly required and had no default value.
+    Fixed `#515 <https://github.com/Qiskit/retworkx/issues/515>`__.
+  - |
+    Fixed an oversight in the :func:`~retworkx.union` function where
+    user-defined values for the ``merge_nodes`` and ``merge_edges`` arguments
+    were being ingored.

releasenotes/notes/full-rary-tree-generator-4c533fd73dbd3e48.yaml → releasenotes/notes/0.11/full-rary-tree-generator-4c533fd73dbd3e48.yaml

@@ -2,7 +2,7 @@
 features:
   - |
     Added a new function, :func:`~retworkx.generators.full_rary_tree` that adds
-    support for generating a full r-ary tree of n nodes. For example:
+    support for generating a full :math:`r`\ -ary tree of :math:`n` nodes. For example:
 
     .. jupyter-execute::
 

releasenotes/notes/0.11/negative-weights-in-shortest-path-algos-b205b63bd12d1a26.yaml

@@ -0,0 +1,12 @@
+---
+fixes:
+  - |
+    Fixed an oversight in shortest path algorithms functions, such as:
+    :func:`~retworkx.dijkstra_shortest_paths`,
+    :func:`~retworkx.dijkstra_shortest_path_lengths`,
+    :func:`~retworkx.all_pairs_dijkstra_path_lengths`,
+    :func:`~retworkx.all_pairs_dijkstra_shortest_paths`,
+    :func:`~retworkx.astar_shortest_path`, and
+    :func:`~retworkx.k_shortest_path_lengths` which would previously incorrectly
+    accept edge weights with negative or ``NaN`` values.
+    Fixed `#525 <https://github.com/Qiskit/retworkx/issues/525>`__.

releasenotes/notes/0.11/prepare-0.11-af688e532712c830.yaml

@@ -0,0 +1,69 @@
+---
+prelude: |
+  This release includes many new features and bug fixes. Highlights include
+  additional methods to improve working with edges in both 
+  :class:`~retworkx.PyGraph` and :class:`~retworkx.PyDiGraph`,
+  several new graph generators, and a new set of interactive traversal
+  functions: :func:`~retworkx.bfs_search`, :func:`~retworkx.dfs_search`,
+  :func:`~retworkx.dijkstra_search`, and :class:`~retworkx.TopologicalSorter`,
+  which enable iterative interaction with the graph during different types
+  of traversal.
+
+  This release also introduces a new separate Rust crate
+  `retworkx-core <https://crates.io/crates/retworkx-core>`__ which
+  is a library for use in Rust that's built on top of
+  `petgraph <https://github.com/petgraph/petgraph>`__ that extends the
+  functionality provided by petgraph. The functionality in this crate is generic
+  and can work with any petgraph graph, not just the :class:`~retworkx.PyGraph`
+  amd :class:`~retworkx.PyDiGraph`.
+
+  The 0.11.0 release fully supports Python 3.10. Precompiled binaries
+  for Python 3.10 are published on PyPI (previous releases worked with 3.10 but
+  required compiling from source to install). This is also the last release to
+  support Python 3.6. Starting in retworkx 0.12.0, Python >=3.7 will be required
+  to run retworkx. Additionally, for users compiling retworkx from source, this
+  will be the last release with a minimum supported Rust version (MSRV) of 1.41.
+  In retworkx 0.12.0, the MSRV will be increased to 1.48.
+
+features:
+  - |
+    Added a new workspace crate,
+    `retworkx-core <https://crates.io/crates/retworkx-core>`__ as part of
+    retworkx. This is a standalone Rust library that is built on top of
+    petgraph that provides general algorithms and graph functionality that
+    retworkx needs. This new crate only exposes a Rust interface that is
+    general for any petgraph graph and can be used by any downstream Rust
+    project that wants the extra functionality that retworkx exposes, but
+    without Python.
+
+    It's also worth noting as this is the first release of ``retworkx-core``
+    there may be breaking API changes in a subsequent release. While we will
+    attempt to follow the standard deprecation and stability policy, since
+    we're not necessarily fully committed to the current API and without having
+    a user outside of retworkx, there may be gaps or issues which require
+    breaking changes.
+  - |
+    A new kwarg, ``keep_attributes``, has been added to the NetworkX graph
+    converter function :func:`~retworkx.networkx_converter`. When this argument
+    is set to ``True`` the node attributes from the input NetworkX graph will
+    be preserved. The data payload for the output retworkx graph will be
+    a dictionary containing the attributes, with an extra ``"__networkx_node__"`` key
+    containing the node from NetworkX. For example::
+
+        import networkx as nx
+        import retworkx as rx
+
+        g = nx.Graph()
+        g.add_nodes_from([
+          ("A", {"color": "turquoise", "size": "extra large"}),
+          ("B", {"color": "fuschia", "size": "tiny"}),
+        ])
+        g.add_edge("A", "B")
+        rx_graph = rx.networkx_converter(g, keep_attributes=True)
+        print(rx_graph.nodes())
+        print(rx_graph.weighted_edge_list())
+
+    will output::
+
+        [{'color': 'turquoise', 'size': 'extra large', '__networkx_node__': 'A'}, {'color': 'fuschia', 'size': 'tiny', '__networkx_node__': 'B'}]
+        WeightedEdgeList[(0, 1, {})]