Graph

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

`Graph`

Graph()

A graph that supported directional edges, parallel edges, self-edges and expression data on the nodes and edges.

Warning: modifying the graph if it is contained in a dict or set will invalidate the hash.

Methods

Name	Description
`__copy__`	Copy the graph.
`__eq__`	Compare two graphs.
`__getitem__`	Get the `idx`th node, consisting of the edge indices and the data.
`__hash__`	Hash the graph.
`__len__`	Get the number of nodes in the graph.
`__neq__`	Compare two graphs.
`__new__`	Create a new empty graph.
`__str__`	Print the graph in a human-readable format.
`add_edge`	Add an edge between the `source` and `target` nodes, returning the index of the edge
`add_node`	Add a node with data `data` to the graph, returning the index of the node
`canonize`	Write the graph in a canonical form
`canonize_edges`	Sort and relabel the edges of the graph, keeping the vertices fixed.
`edge`	Get the `idx`th edge, consisting of the the source vertex, target vertex, whether the edge is directed, and the data.
`edges`	Get all edges, consisting of the the source vertex, target vertex, whether the edge is directed, and the data.
`generate`	Generate all connected graphs with `external_edges` half-edges and the given allowed list of vertex connections
`is_isomorphic`	Check if the graph is isomorphic to another graph.
`node`	Get the `idx`th node, consisting of the edge indices and the data.
`nodes`	Get all nodes, consisting of the edge indices and the data.
`num_edges`	Get the number of edges in the graph.
`num_loops`	Get the number of loops in the graph.
`num_nodes`	Get the number of nodes in the graph.
`set_directed`	Set the directed status of the edge at index `index`, returning the old value.
`set_edge_data`	Set the data of the edge at index `index`, returning the old data.
`set_node_data`	Set the data of the node at index `index`, returning the old data.
`to_dot`	Convert the graph to a graphviz dot string.
`to_mermaid`	Convert the graph to a mermaid string.

`copy`

Graph.__copy__() -> Graph

Copy the graph.

`eq`

Graph.__eq__(other: Graph) -> bool

Compare two graphs.

Parameters

other (Graph) The other operand to combine or compare with.

`getitem`

Graph.__getitem__(idx: int) -> tuple[Sequence[int], Expression]

Get the idxth node, consisting of the edge indices and the data.

Parameters

idx (int) The zero-based index to access.

`hash`

Graph.__hash__() -> int

Hash the graph.

`len`

Graph.__len__() -> int

Get the number of nodes in the graph.

`neq`

Graph.__neq__(other: Graph) -> bool

Compare two graphs.

Parameters

other (Graph) The other operand to combine or compare with.

`new`

Graph.__new__()

Create a new empty graph.

`str`

Graph.__str__() -> str

Print the graph in a human-readable format.

`add_edge`

Graph.add_edge(
    source: int,
    target: int,
    directed: bool = False,
    data: Expression | int | None = None,
) -> int

Add an edge between the source and target nodes, returning the index of the edge.

Optionally, the edge can be set as directed. The default data is the number 0.

Parameters

source (int) The source node index.
target (int) The target node index.
directed (bool) Whether the edge is directed.
data (Expression | int | None) The data to associate with the object.

`add_node`

Graph.add_node(data: Expression | int | None = None) -> int

Add a node with data data to the graph, returning the index of the node. The default data is the number 0.

Parameters

data (Expression | int | None) The data to associate with the object.

`canonize`

Graph.canonize() -> tuple[Graph, Sequence[int], Expression, Sequence[int]]

Write the graph in a canonical form. Returns the canonized graph, the vertex map, the automorphism group size, and the orbit.

`canonize_edges`

Graph.canonize_edges() -> None

Sort and relabel the edges of the graph, keeping the vertices fixed.

`edge`

Graph.edge(idx: int) -> tuple[int, int, bool, Expression]

Get the idxth edge, consisting of the the source vertex, target vertex, whether the edge is directed, and the data.

Parameters

idx (int) The zero-based index to access.

`edges`

Graph.edges() -> list[tuple[int, int, bool, Expression]]

Get all edges, consisting of the the source vertex, target vertex, whether the edge is directed, and the data.

`generate`

Graph.generate(
    external_nodes: Sequence[tuple[Expression | int, HalfEdge]],
    vertex_signatures: Sequence[Sequence[HalfEdge]],
    max_vertices: int | None = None,
    max_loops: int | None = None,
    max_bridges: int | None = None,
    allow_self_loops: bool = False,
    allow_zero_flow_edges: bool = False,
    filter_fn: Callable[[Graph, int], bool] | None = None,
    progress_fn: Callable[[Graph], bool] | None = None,
) -> dict[Graph, Expression]

Generate all connected graphs with external_edges half-edges and the given allowed list of vertex connections. The vertex signatures are given in terms of an edge direction (or None if there is no direction) and edge data.

Returns the canonical form of the graph and the size of its automorphism group (including edge permutations). If KeyboardInterrupt is triggered during the generation, the generation will stop and will yield the currently generated graphs.

Examples

from symbolica import *
g, q = HalfEdge(S("g")), HalfEdge(S("q"), True)
graphs = Graph.generate(
    [(1, g), (2, g)],
    [[g, g, g], [g, g, g, g], [q.flip(), q, g]],
    max_loops=2,
)
for (g, sym) in graphs.items():
    print(f'Symmetry factor = 1/{sym}:')
    print(g.to_dot())

generates all connected graphs up to 2 loops with the specified vertices.

Parameters

external_nodes (Sequence[tuple[Expression | int, HalfEdge]]) The external edges, consisting of a tuple of the node data and a tuple of the edge direction and edge data. If the node data is the same, flip symmetries will be recognized.
vertex_signatures (Sequence[Sequence[HalfEdge]]) The allowed connections for each vertex.
max_vertices (int, optional) The maximum number of vertices in the graph.
max_loops (int, optional) The maximum number of loops in the graph.
max_bridges (int, optional) The maximum number of bridges in the graph.
allow_self_loops (bool, optional) Whether self-edges are allowed.
allow_zero_flow_edges (bool, optional) Whether bridges that do not need to be crossed to connect external vertices are allowed.
filter_fn (Callable[[Graph, int], bool] | None, optional) Set a filter function that is called during the graph generation. The first argument is the graph g and the second argument the vertex count n that specifies that the first n vertices are completed (no new edges will) be assigned to them. The filter function should return true if the current incomplete graph is allowed, else it should return false and the graph is discarded.
progress_fn (Callable[[Graph], bool] | None, optional) Set a progress function that is called every time a new unique graph is created. The argument is the currently generated graph. If the function returns false, the generation is aborted and the currently generated graphs are returned.

`is_isomorphic`

Graph.is_isomorphic(other: Graph) -> bool

Check if the graph is isomorphic to another graph.

Parameters

other (Graph) The other operand to combine or compare with.

`node`

Graph.node(idx: int) -> tuple[Sequence[int], Expression]

Get the idxth node, consisting of the edge indices and the data.

Parameters

idx (int) The zero-based index to access.

`nodes`

Graph.nodes() -> list[tuple[Sequence[int], Expression]]

Get all nodes, consisting of the edge indices and the data.

`num_edges`

Graph.num_edges() -> int

Get the number of edges in the graph.

`num_loops`

Graph.num_loops() -> int

Get the number of loops in the graph.

`num_nodes`

Graph.num_nodes() -> int

Get the number of nodes in the graph.

`set_directed`

Graph.set_directed(index: int, directed: bool) -> bool

Set the directed status of the edge at index index, returning the old value.

Parameters

index (int) The index of the edge whose direction flag should be changed.
directed (bool) Whether the edge is directed.

`set_edge_data`

Graph.set_edge_data(index: int, data: Expression | int) -> Expression

Set the data of the edge at index index, returning the old data.

Parameters

index (int) The index of the edge whose data should be replaced.
data (Expression | int) The data to associate with the object.

`set_node_data`

Graph.set_node_data(index: int, data: Expression | int) -> Expression

Set the data of the node at index index, returning the old data.

Parameters

index (int) The index of the node whose data should be replaced.
data (Expression | int) The data to associate with the object.

`to_dot`

Graph.to_dot() -> str

Convert the graph to a graphviz dot string.

`to_mermaid`

Graph.to_mermaid() -> str

Convert the graph to a mermaid string.