diff --git a/docs/source/api.rst b/docs/source/api.rst index b054289eb2..039c168d3c 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -14,6 +14,122 @@ Graph Classes retworkx.PyDiGraph retworkx.PyDAG +Algorithm Functions +=================== + +.. _shortest-paths: + +Shortest Paths +-------------- + +.. autosummary:: + :toctree: stubs + + retworkx.dijkstra_shortest_paths + retworkx.dijkstra_shortest_path_lengths + retworkx.all_pairs_dijkstra_shortest_paths + retworkx.all_pairs_dijkstra_path_lengths + retworkx.distance_matrix + retworkx.floyd_warshall_numpy + retworkx.floyd_warshall + retworkx.astar_shortest_path + retworkx.k_shortest_path_lengths + +.. _traversal: + +Traversal +--------- + +.. autosummary:: + :toctree: stubs + + retworkx.dfs_edges + retworkx.bfs_successors + retworkx.topological_sort + retworkx.lexicographical_topological_sort + retworkx.descendants + retworkx.ancestors + retworkx.collect_runs + +.. _dag-algorithms: + +DAG Algorithms +-------------- + +.. autosummary:: + :toctree: stubs + + retworkx.dag_longest_path + retworkx.dag_longest_path_length + retworkx.is_directed_acyclic_graph + retworkx.layers + +.. _tree: + +Tree +---- + +.. autosummary:: + :toctree: stubs + + retworkx.minimum_spanning_edges + retworkx.minimum_spanning_tree + +.. _isomorphism: + +Isomorphism +----------- + +.. autosummary:: + :toctree: stubs + + retworkx.is_isomorphic + retworkx.is_subgraph_isomorphic + retworkx.is_isomorphic_node_match + +.. _matching: + +Matching +-------- + +.. autosummary:: + :toctree: stubs + + retworkx.max_weight_matching + retworkx.is_matching + retworkx.is_maximal_matching + +.. _connectivity-cycle-finding: + +Connectivity and Cycles +----------------------- + +.. autosummary:: + :toctree: stubs + + retworkx.strongly_connected_components + retworkx.number_weakly_connected_components + retworkx.weakly_connected_components + retworkx.is_weakly_connected + retworkx.cycle_basis + retworkx.digraph_find_cycle + +.. _other-algorithms: + +Other Algorithm Functions +------------------------- + +.. autosummary:: + :toctree: stubs + + retworkx.complement + retworkx.adjacency_matrix + retworkx.all_simple_paths + retworkx.transitivity + retworkx.core_number + retworkx.graph_greedy_color + retworkx.digraph_union + Generators ========== @@ -46,141 +162,105 @@ Random Circuit Functions retworkx.undirected_gnm_random_graph retworkx.random_geometric_graph -Algorithm Functions -=================== +.. _layout-functions: -Specific Graph Type Methods ---------------------------- +Layout Functions +================ + +.. autosummary:: + :toctree: stubs + + retworkx.random_layout + retworkx.spring_layout + retworkx.bipartite_layout + retworkx.circular_layout + retworkx.shell_layout + retworkx.spiral_layout + + +.. _converters: + +Converters +========== + +.. autosummary:: + :toctree: stubs + + retworkx.networkx_converter + +.. _api-functions-pydigraph: + +API functions for PyDigraph +=========================== + +These functions are algorithm functions that are type specific for +:class:`~retworkx.PyDiGraph` or :class:`~retworkx.PyDAG` objects. Universal +functions from Retworkx API that work for both graph types internally call +the functions from the explicitly typed based on the data type. .. autosummary:: :toctree: stubs - retworkx.bfs_successors - retworkx.dag_longest_path - retworkx.dag_longest_path_length - retworkx.number_weakly_connected_components - retworkx.weakly_connected_components - retworkx.is_weakly_connected - retworkx.is_directed_acyclic_graph retworkx.digraph_is_isomorphic - retworkx.graph_is_isomorphic retworkx.digraph_is_subgraph_isomorphic - retworkx.graph_is_subgraph_isomorphic - retworkx.topological_sort - retworkx.descendants - retworkx.ancestors - retworkx.lexicographical_topological_sort - retworkx.graph_distance_matrix retworkx.digraph_distance_matrix - retworkx.floyd_warshall - retworkx.graph_floyd_warshall_numpy retworkx.digraph_floyd_warshall_numpy - retworkx.collect_runs - retworkx.layers retworkx.digraph_adjacency_matrix - retworkx.graph_adjacency_matrix - retworkx.graph_all_simple_paths retworkx.digraph_all_simple_paths - retworkx.graph_astar_shortest_path retworkx.digraph_astar_shortest_path - retworkx.graph_dijkstra_shortest_paths retworkx.digraph_dijkstra_shortest_paths retworkx.digraph_all_pairs_dijkstra_shortest_paths - retworkx.graph_dijkstra_shortest_path_lengths - retworkx.graph_all_pairs_dijkstra_shortest_paths retworkx.digraph_dijkstra_shortest_path_lengths retworkx.digraph_all_pairs_dijkstra_path_lengths - retworkx.graph_k_shortest_path_lengths - retworkx.graph_all_pairs_dijkstra_path_lengths retworkx.digraph_k_shortest_path_lengths - retworkx.graph_greedy_color - retworkx.cycle_basis - retworkx.strongly_connected_components - retworkx.graph_dfs_edges retworkx.digraph_dfs_edges retworkx.digraph_find_cycle - retworkx.digraph_union - retworkx.is_matching - retworkx.is_maximal_matching - retworkx.max_weight_matching - retworkx.minimum_spanning_edges - retworkx.minimum_spanning_tree - retworkx.graph_transitivity retworkx.digraph_transitivity - retworkx.graph_core_number retworkx.digraph_core_number - retworkx.graph_complement retworkx.digraph_complement + retworkx.digraph_random_layout + retworkx.digraph_bipartite_layout + retworkx.digraph_circular_layout + retworkx.digraph_shell_layout + retworkx.digraph_spiral_layout + retworkx.digraph_spring_layout -.. _universal-functions: - -Universal Functions -------------------- - -These functions are algorithm functions that wrap per graph object -type functions in the algorithms API but can be run with a -:class:`~retworkx.PyGraph`, :class:`~retworkx.PyDiGraph`, or -:class:`~retworkx.PyDAG` object. - -.. autosummary:: - :toctree: stubs - retworkx.complement - retworkx.distance_matrix - retworkx.floyd_warshall_numpy - retworkx.adjacency_matrix - retworkx.all_simple_paths - retworkx.astar_shortest_path - retworkx.dijkstra_shortest_paths - retworkx.dijkstra_shortest_path_lengths - retworkx.all_pairs_dijkstra_shortest_paths - retworkx.all_pairs_dijkstra_path_lengths - retworkx.k_shortest_path_lengths - retworkx.dfs_edges - retworkx.is_isomorphic - retworkx.is_subgraph_isomorphic - retworkx.is_isomorphic_node_match - retworkx.transitivity - retworkx.core_number - retworkx.random_layout - retworkx.bipartite_layout - retworkx.circular_layout - retworkx.shell_layout - retworkx.spiral_layout - retworkx.spring_layout +.. _api-functions-pygraph: -.. _layout-functions: +API functions for PyGraph +========================= -Layout Functions -================ +These functions are algorithm functions that are type specific for +:class:`~retworkx.PyGraph` objects. Universal functions from Retworkx API that +work for both graph types internally call the functions from the explicitly +typed API based on the data type. .. autosummary:: :toctree: stubs - retworkx.random_layout - retworkx.spring_layout + retworkx.graph_is_isomorphic + retworkx.graph_is_subgraph_isomorphic + retworkx.graph_distance_matrix + retworkx.graph_floyd_warshall_numpy + retworkx.graph_adjacency_matrix + retworkx.graph_all_simple_paths + retworkx.graph_astar_shortest_path + retworkx.graph_dijkstra_shortest_paths + retworkx.graph_dijkstra_shortest_path_lengths + retworkx.graph_all_pairs_dijkstra_shortest_paths + retworkx.graph_k_shortest_path_lengths + retworkx.graph_all_pairs_dijkstra_path_lengths + retworkx.graph_dfs_edges + retworkx.graph_transitivity + retworkx.graph_core_number + retworkx.graph_complement retworkx.graph_random_layout - retworkx.digraph_random_layout - retworkx.bipartite_layout retworkx.graph_bipartite_layout - retworkx.digraph_bipartite_layout - retworkx.circular_layout retworkx.graph_circular_layout - retworkx.digraph_circular_layout - retworkx.shell_layout retworkx.graph_shell_layout - retworkx.digraph_shell_layout - retworkx.spiral_layout retworkx.graph_spiral_layout - retworkx.digraph_spiral_layout - -Converters ----------- - -.. autosummary:: - :toctree: stubs - - retworkx.networkx_converter + retworkx.graph_spring_layout Exceptions ========== diff --git a/docs/source/networkx.rst b/docs/source/networkx.rst index b114f6aa00..683e17bfe2 100644 --- a/docs/source/networkx.rst +++ b/docs/source/networkx.rst @@ -89,11 +89,11 @@ or more concisely:: dist_matrix = rx.digraph_floyd_warshall_numpy(graph, weight_fn=lambda edge: edge) -The other large difference to keep in mind is that most functions in retworkx +The other large difference to keep in mind is that many functions in retworkx are explicitly typed. This means that they either always return or accept either a :class:`~retworkx.PyDiGraph` or a :class:`~retworkx.PyGraph` but not -both. The exception to this are the :ref:`universal-functions` which will -dispatch to the statically typed equivalent based on the object they receive. +both. Generally, functions prefixed with `graph_*` and `digraph_*` explicitly typed. +Explicitly typed functions also indicate their type on the docstrings. This is different from networkx where everything is pretty much dynamically typed and you can pass a graph object to any function and it will work as expected (unless it isn't supported and then it will raise an exception). diff --git a/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml b/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml index ce029bea5c..da3f5baadd 100644 --- a/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml +++ b/releasenotes/notes/0.8.0/add-universal-functions-1e54351f1f7afa4b.yaml @@ -1,7 +1,7 @@ --- features: - | - New :ref:`universal-functions` that can take in a :class:`~retworkx.PyGraph` + New universal functions that can take in a :class:`~retworkx.PyGraph` or :class:`~retworkx.PyDiGraph` instead of being class specific have been to the retworkx API. These new functions are: diff --git a/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml b/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml index 733f5050ce..00d7c6dde5 100644 --- a/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml +++ b/releasenotes/notes/0.8.0/prepare-0.8-f3ec8cbf07dfdbb7.yaml @@ -3,7 +3,7 @@ prelude: > This release includes several new features and bug fixes. The main features for this release are some usability improvements including the introduction of new methods for interacting with edges, constructing graphs from - adjacency matrices, and :ref:`universal-functions` that are not strictly + adjacency matrices, and universal functions that are not strictly typed and will work with either a :class:`~retworkx.PyGraph` or :class:`~retworkx.PyDiGraph` object. It also includes new algorithm functions around matchings for a :class:`~retworkx.PyGraph`, including a