Skip to content

Commit

Permalink
Docs and consistency cleanup for rustworkx-core generators (#784)
Browse files Browse the repository at this point in the history 
* Initial r-ary

* Complete tests

* Lint and name change

* Clippy

* Code and docs consistency

* Docs changes to generators.rs

* Reorder graphs in generators.rs

* Switch binomial tree to update_edge

* Update bidirectional docs

* Cleanup rest of docs and return find_edge in binomial tree

* Second round on heavy docs

* Minor doc change

* Make core utils and cleanup docs

* Fmt

* Text and PyGraph fixes
  • Loading branch information
@enavarro51
enavarro51 committed Feb 4, 2023
1 parent 1ffa4d4 commit b659159
Show file tree
Hide file tree
Showing 18 changed files with 686 additions and 679 deletions.
23 changes: 10 additions & 13 deletions rustworkx-core/src/generators/barbell_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,36 +16,33 @@ use petgraph::data::{Build, Create};
use petgraph::visit::{Data, NodeIndexable, NodeRef};

use super::utils::get_num_nodes;
use super::utils::pairwise;
use super::InvalidInputError;
use crate::utils::pairwise;

/// Generate an undirected barbell graph where two identical mesh graphs are
/// Generate a barbell graph where two identical complete graphs are
/// connected by a path.
///
/// .. note::
///
/// If neither `num_path_nodes` nor `path_weights` (described below) is not specified
/// then this is equivalent to two mesh graphs joined together.
/// If neither `num_path_nodes` nor `path_weights` (described below) are
/// specified, then this is equivalent to two complete graphs joined together.
///
/// Arguments:
///
/// * `num_mesh_nodes` - The number of nodes to generate the mesh graph
/// with. Node weights will be None if this is specified. If both
/// `num_mesh_nodes` and `mesh_weights` are set this will be ignored and
/// `num_mesh_nodes` and `mesh_weights` are set, this will be ignored and
/// `mesh_weights` will be used.
/// * `num_path_nodes` - The number of nodes to generate the path
/// with. Node weights will be None if this is specified. If both
/// `num_path_nodes` and `path_weights` are set this will be ignored and
/// `num_path_nodes` and `path_weights` are set, this will be ignored and
/// `path_weights` will be used.
/// * `mesh_weights` - A list of node weights for the mesh graph. If both
/// `num_mesh_nodes` and `mesh_weights` are set `num_mesh_nodes` will
/// `num_mesh_nodes` and `mesh_weights` are set, `num_mesh_nodes` will
/// be ignored and `mesh_weights` will be used.
/// * `path_weights` - A list of node weights for the path. If both
/// `num_path_nodes` and `path_weights` are set `num_path_nodes` will
/// `num_path_nodes` and `path_weights` are set, `num_path_nodes` will
/// be ignored and `path_weights` will be used.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if weights are specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if node weights are specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
///
Expand Down Expand Up @@ -147,7 +144,7 @@ where
}
};
let pathlen = path_nodes.len();
if pathlen > 0 {
if !path_nodes.is_empty() {
graph.add_edge(
graph.from_index(meshlen - 1),
graph.from_index(meshlen),
Expand Down
9 changes: 4 additions & 5 deletions rustworkx-core/src/generators/binomial_tree_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,14 @@ use super::InvalidInputError;
///
/// * `order` - The order of the binomial tree.
/// * `weights` - A `Vec` of node weight objects. If the number of weights is
/// less than 2**order extra nodes with None will be appended.
/// less than 2**order, extra nodes with None will be appended.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a pallel edge.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
5 changes: 2 additions & 3 deletions rustworkx-core/src/generators/complete_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,11 @@ use super::InvalidInputError;
/// Arguments:
///
/// * `num_nodes` - The number of nodes to create a complete graph for. Either this or
/// `weights must be specified. If both this and `weights are specified, weights
/// `weights` must be specified. If both this and `weights` are specified, `weights`
/// will take priorty and this argument will be ignored
/// * `weights` - A `Vec` of node weight objects.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
///
Expand Down
9 changes: 4 additions & 5 deletions rustworkx-core/src/generators/cycle_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,17 +21,16 @@ use super::InvalidInputError;
/// Arguments:
///
/// * `num_nodes` - The number of nodes to create a cycle graph for. Either this or
/// `weights must be specified. If both this and `weights are specified, weights
/// `weights` must be specified. If both this and `weights` are specified, `weights`
/// will take priorty and this argument will be ignored.
/// * `weights` - A `Vec` of node weight objects.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a pallel edge.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
13 changes: 7 additions & 6 deletions rustworkx-core/src/generators/full_rary_tree_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,22 @@ use petgraph::visit::{Data, NodeIndexable};

use super::InvalidInputError;

/// Creates a full r-ary tree of `n` nodes.
/// Generate a full r-ary tree of `n` nodes.
/// Sometimes called a k-ary, n-ary, or m-ary tree.
///
/// Arguments:
///
/// * `branching factor` - The number of children at each node.
/// * `num_nodes` - The number of nodes in the graph.
/// * `weights` - A list of node weights. If the number of weights is
/// less than n, extra nodes with with None weight will be appended.
/// less than n, extra nodes with None weight will be appended.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a pallel edge.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
7 changes: 3 additions & 4 deletions rustworkx-core/src/generators/grid_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ use super::InvalidInputError;
///
/// * `rows` - The number of rows to generate the graph with.
/// If specified, cols also need to be specified.
/// * `cols`: The number of rows to generate the graph with.
/// * `cols`: The number of columns to generate the graph with.
/// If specified, rows also need to be specified. rows*cols
/// defines the number of nodes in the graph.
/// * `weights`: A `Vec` of node weights. Nodes are filled row wise.
Expand All @@ -32,11 +32,10 @@ use super::InvalidInputError;
/// If number of nodes(rows*cols) is greater than length of
/// weights list, extra nodes with None weight are appended.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a parallel edge.
///
Expand Down
78 changes: 39 additions & 39 deletions rustworkx-core/src/generators/heavy_hex_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,53 +17,53 @@ use petgraph::visit::{Data, NodeIndexable};

use super::InvalidInputError;

/// Generate an undirected heavy hex graph. Fig. 2 of
/// https://arxiv.org/abs/1907.09528
/// An ASCII diagram of the graph is given by:
///
/// .. note::
/// Generate a heavy hex graph.
///
/// Fig. 2 of <https://arxiv.org/abs/1907.09528>
/// An ASCII diagram of the graph is given by:
/// ```text
/// ... D-S-D D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// ... D D-S-D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// | | |
/// ...-F F-S-F ...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F F-...
/// | | |
/// ... D D-S-D ...
///```
///
/// Arguments:
///
/// * `d` - Distance of the code. If ``d`` is set to ``1`` a graph with a
/// single node will be returned. d must be an odd number.
/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
/// single node will be returned. `d` must be an odd number.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a pallel edge.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
56 changes: 30 additions & 26 deletions rustworkx-core/src/generators/heavy_square_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,38 +17,42 @@ use petgraph::visit::{Data, NodeIndexable};

use super::InvalidInputError;

/// Generate an directed heavy square graph. Fig. 6 of
/// https://arxiv.org/abs/1907.09528.
/// An ASCII diagram of the graph is given by:
///
/// .. note::
/// Generate a heavy square graph.
///
/// Fig. 6 of <https://arxiv.org/abs/1907.09528>
/// An ASCII diagram of the graph is given by:
/// ```text
/// ... S ...
/// \ / \
/// ... D D D ...
/// | | |
/// ... F-S-F-S-F-...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F-S-F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// \ / \
/// ... S ...
///
/// ... D D D ...
/// | | |
/// ... F-S-F-S-F-...
/// | | |
/// ... D D D ...
/// | | |
/// ... F-S-F-S-F-...
/// | | |
/// .........
/// | | |
/// ... D D D ...
/// \ / \
/// ... S ...
/// ```
/// NOTE: This function generates the four-frequency variant of the heavy square code.
/// This function implements Fig 10.b left of the `paper <https://arxiv.org/abs/1907.09528>`_.
/// This function implements Fig 10.b left of the paper <https://arxiv.org/abs/1907.09528>.
/// This function doesn't support the variant Fig 10.b right.
///
/// :param int d: distance of the code. If ``d`` is set to ``1`` a
/// :class:`~rustworkx.PyDiGraph` with a single node will be returned.
/// :param bool multigraph: When set to False the output
/// :class:`~rustworkx.PyDiGraph` object will not be not be a multigraph and
/// won't allow parallel edges to be added. Instead
/// calls which would create a parallel edge will update the existing edge.
/// Arguments:
///
/// * `d` - Distance of the code. If `d` is set to `1` a graph with a
/// single node will be returned. `d` must be an odd number.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
7 changes: 3 additions & 4 deletions rustworkx-core/src/generators/hexagonal_lattice_graph.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,13 +24,12 @@ use super::InvalidInputError;
/// * `rows` - The number of rows to generate the graph with.
/// * `cols` - The number of columns to generate the graph with.
/// * `default_node_weight` - A callable that will return the weight to use
/// for newly created nodes. This is ignored if `weights` is specified,
/// as the weights from that argument will be used instead.
/// for newly created nodes. This is ignored if `weights` is specified.
/// * `default_edge_weight` - A callable that will return the weight object
/// to use for newly created edges.
/// * `bidirectional` - Whether edges are added bidirectionally, if set to
/// * `bidirectional` - Whether edges are added bidirectionally. If set to
/// `true` then for any edge `(u, v)` an edge `(v, u)` will also be added.
/// If the graph is undirected this will result in a pallel edge.
/// If the graph is undirected this will result in a parallel edge.
///
/// # Example
/// ```rust
Expand Down
Loading

0 comments on commit b659159

Please sign in to comment.