Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs and consistency cleanup for rustworkx-core generators #784

Merged
merged 21 commits into from
Feb 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 10 additions & 13 deletions rustworkx-core/src/generators/barbell_graph.rs
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
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
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
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
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
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
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
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
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