Grouper.utils module

Grouper.utils.convert_edges_to_nodetype(G)

Convert the edge representation in a graph to use node types instead of node IDs.

Parameters:: G (nx.DiGraph) – The input graph.
Returns:: A new graph with the converted edge representation.
Return type:: nx.DiGraph

Grouper.utils.convert_to_nx(G)

Convert a GroupGraph to a networkx graph.

Parameters:: G (GroupGraph) – The GroupGraph to convert.
Returns:: The networkx representation of the GroupGraph.
Return type:: nxGroupGraph

Grouper.utils.data_to_gg_edge(data, max_ports)

Convert PyG data to GroupGraph edges.

Parameters:

data (torch_geometric.data.Data) – The PyG data object.
max_ports (int) – The maximum number of ports on a node.

Returns:

A list of edges for a GroupGraph.

Return type:

list

class Grouper.utils.nxGroupGraph(node_types=None)

Bases: DiGraph

A graph with ports as parts of nodes that can be connected to other ports.

add_edge(node_port_1, node_port_2)

Add an edge between two nodes in the GroupGraph.

Parameters:

node_port_1 (Tuple[Any, Any]) – Tuple of node and port on the first node.
node_port_2 (Tuple[Any, Any]) – Tuple of node and port on the second node.

Raises:

AttributeError – If a node has no free ports or if nodes or ports are not present in the Graph.

Return type:

None

add_node(nodeID, node_type, smarts, hubs)

Add a node to the GroupGraph.

Parameters:

nodeID (Any) – Identifier for the node.
node_type (str) – Type of the node.
smarts (str) – SMARTS string for the node.
hubs (Sequence[int]) – A sequence of integers representing the hubs.

Raises:

AttributeError – If the node is already present in the Graph.

Return type:

None

make_undirected()

Convert the GroupGraph to an undirected graph.

Adds bonds and updates edge ports accordingly.

n_free_ports(nodeID)

Get the number of free ports on a node.

Parameters:: nodeID (Any) – Identifier for the node.
Returns:: Number of free ports.
Return type:: int

to_PyG_Data(node_descriptor_generator, max_ports=0)

Convert the GroupGraph to a PyG Data representation.

Parameters:

node_descriptor_generator (Callable[[str], Sequence[float]]) – Callable to generate node descriptors. Takes in a SMARTS string and returns a sequence of floats.
max_ports (int, optional) – The maximum number of ports on a node, by default 0

Returns:

PyG Data representation.

Return type:

torch_geometric.data.Data

Grouper.utils.parse_vcolg_line(line)

Parse a single line of vcolg’s terse-format (-T) output.

vcolg writes one connected colored graph per line as

n_vertices n_edges c_0 c_1 … c_{n-1} v0 w0 v1 w1 … vE wE

with the colors and the edge list separated by two spaces. There’s no port information — only which two nodes are bonded — so the caller is responsible for resolving port assignments downstream if they want a fully-formed GroupGraph.

Parameters:: line (str) – A single line of vcolg output produced with -T and -mK.
Returns:: (n_vertices, colors, edges) – n_vertices is the number of nodes; colors[i] is the color (= group index, 0-based) of node i; edges is the list of (src_node, dst_node) pairs. No port information is included.
Return type:: Tuple[int, List[int], List[Tuple[int, int]]]
Raises:: ValueError – If the line doesn’t match vcolg’s expected format (missing the two-space header/edge separator, or the edge list has an odd number of integers).

Examples

from Grouper.utils import parse_vcolg_line

# A 3-node 2-edge path with all three nodes the same color:
n, colors, edges = parse_vcolg_line("3 2 0 0 0   0 1 1 2")
# n == 3
# colors == [0, 0, 0]
# edges == [(0, 1), (1, 2)]

Notes

The parser is intentionally minimal: it does not validate that the colors fit within any specific palette size, nor that the edge endpoints reference valid node indices. Downstream code can layer those checks on top depending on what it’s doing.