Graphs Polytopes API

Polytopes

The polytopes module contains functions and classes for working with polytope graphs.

class graphcalc.graphs.polytopes.core.PolytopeGraph(*args, backend=None, **kwargs)

Bases: SimpleGraph

A subclass of SimpleGraph that ensures the graph satisfies polytope graph conditions.

A polytope graph is defined as a graph that is: 1. Simple: No self-loops or multiple edges. 2. Planar: Can be embedded in the plane without edge crossings. 3. 3-Connected: Remains connected after the removal of any two vertices.

is_polytope_graph()

Checks if the graph satisfies the polytope graph conditions.

draw()

Draws the graph using a planar layout with Matplotlib.

read_edge_list(filepath, delimiter=None)

Reads an edge list from a file and validates the graph as a polytope graph.

read_adjacency_matrix(filepath, delimiter=None)

Reads an adjacency matrix from a file and validates the graph as a polytope graph.

is_simple()

Checks if the graph is a simple polytope graph.

draw(with_labels=True, node_color='lightblue', node_size=500, font_size=10)

Draw the graph using a planar layout with Matplotlib.

Parameters:

• with_labels (bool, optional) – Whether to display node labels (default is True).

• node_color (str or list, optional) – The color of the nodes (default is “lightblue”).

• node_size (int, optional) – The size of the nodes (default is 500).

• font_size (int, optional) – The font size of the labels (default is 10).

Notes

This method always uses a planar layout to ensure no edge crossings.

is_polytope_graph()

Check if the graph satisfies the polytope graph conditions.

Returns:

True if the graph is a valid polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> import graphcalc.graphs as gc
>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.polytopes import PolytopeGraph
>>> from graphcalc.graphs.core.basics import SimpleGraph
>>> G = gc.polytopes.cube_graph()

>>> polytope = PolytopeGraph(edges=G.edges, nodes=G.nodes, name="Cube Graph")
>>> polytope.is_polytope_graph()
True

is_simple()

Check if the graph is of a simple polytope, i.e., a 3-regular, 3-connected, and planar graph.

Returns:

True if the graph is simple, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> from graphcalc.graphs.polytopes import PolytopeGraph
>>> from graphcalc.graphs.core.basics import SimpleGraph
>>> G = gc.polytopes.cube_graph()

>>> polytope = PolytopeGraph(edges=G.edges, nodes=G.nodes, name="Cube Graph")
>>> polytope.is_simple()
True

read_adjacency_matrix(filepath, delimiter=None)

Read an adjacency matrix from a file, create the graph, and validate that it remains a valid polytope graph.

Parameters:

• filepath (str) – The path to the file containing the adjacency matrix.

• delimiter (str, optional) – The delimiter used in the file.

Raises:

ValueError – If the graph is not a valid polytope graph after reading the adjacency matrix.

read_edge_list(filepath, delimiter=None)

Read an edge list from a file (CSV or TXT), add edges to the graph, and validate that the graph remains a valid polytope graph.

Parameters:

• filepath (str) – The path to the file containing the edge list.

• delimiter (str, optional) – The delimiter used in the file.

Raises:

ValueError – If the graph is not a valid polytope graph after reading the edge list.

class graphcalc.graphs.polytopes.core.SimplePolytopeGraph(*args, backend=None, **kwargs)

Bases: PolytopeGraph

add_edge(u_of_edge, v_of_edge, **attr)

Add an edge and validate the graph remains a valid simple polytope graph.

Raises:

ValueError – If adding the edge makes the graph invalid as a simple polytope graph.

add_edges_from(ebunch_to_add, **attr)

Add multiple edges and validate the graph remains a valid simple polytope graph.

Parameters:

• ebunch_to_add (iterable of edges) – An iterable of edges to add.

• **attr (keyword arguments) – Additional edge attributes.

Raises:

ValueError – If the graph is not valid after all edges are added.

is_3_regular()

Check if the graph is 3-regular.

Returns:

True if the graph is 3-regular, False otherwise.

Return type:

bool

read_adjacency_matrix(filepath, delimiter=None)

Read an adjacency matrix from a file, create the graph, and validate that it remains a valid simple polytope graph.

Parameters:

• filepath (str) – The path to the file containing the adjacency matrix.

• delimiter (str, optional) – The delimiter used in the file.

Raises:

ValueError – If the graph is not a valid simple polytope graph after reading the adjacency matrix.

read_edge_list(filepath, delimiter=None)

Read an edge list from a file (CSV or TXT), add edges to the graph, and validate that the graph remains a valid simple polytope graph.

Parameters:

• filepath (str) – The path to the file containing the edge list.

• delimiter (str, optional) – The delimiter used in the file.

Raises:

ValueError – If the graph is not a valid simple polytope graph after reading the edge list.

Polytope graph generators.

This module provides generators for graphs corresponding to polytopes. These generators must be explicitly imported.

Examples

>>> from graphcalc.graphs.polytopes.generators import cube_graph, octahedron_graph
>>> G = cube_graph()
>>> H = octahedron_graph()

graphcalc.graphs.polytopes.generators.convex_polytopes_text_example(n=1) → PolytopeGraph

Generate a polytope graph from the first predefined edge list.

Returns:

A polytope graph constructed from edge_list_1.

Return type:

PolytopeGraph

graphcalc.graphs.polytopes.generators.cube_graph() → SimplePolytopeGraph

Generate the graph of a cube.

Returns:

The graph of a cube (3-regular polytope).

Return type:

SimplePolytopeGraph

graphcalc.graphs.polytopes.generators.dodecahedron_graph() → SimplePolytopeGraph

Generate the graph of a dodecahedron.

Returns:

The graph of a dodecahedron (3-regular polytope).

Return type:

SimplePolytopeGraph

graphcalc.graphs.polytopes.generators.icosahedron_graph() → PolytopeGraph

Generate the graph of an icosahedron.

Returns:

The graph of an icosahedron (planar, simple, and 3-connected).

Return type:

PolytopeGraph

graphcalc.graphs.polytopes.generators.octahedron_graph() → PolytopeGraph

Generate the graph of an octahedron.

Returns:

The graph of an octahedron (planar, simple, and 3-connected).

Return type:

PolytopeGraph

graphcalc.graphs.polytopes.generators.tetrahedron_graph() → PolytopeGraph

Generate the graph of a tetrahedron.

Returns:

The graph of a tetrahedron (planar, simple, and 3-connected).

Return type:

PolytopeGraph

graphcalc.graphs.polytopes.invariants.fullerene(G: Graph | SimpleGraph) → bool

Determine whether a graph is a fullerene.

A fullerene is a 3-regular, planar, simple, and connected graph in which every face is either a pentagon or hexagon, and exactly 12 of the faces are pentagons.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The graph to check.

Returns:

True if G is a fullerene, False otherwise.

Return type:

bool

graphcalc.graphs.polytopes.invariants.p_gons(G: Graph | SimpleGraph, p: int = 3) → int

Compute the number of p-sided faces in a planar graph.

This function determines the count of faces with exactly p sides in a given planar graph by leveraging the p-vector. The graph must be planar and connected.

Parameters:

• G (networkx.Graph or graphcalc.SimpleGraph) – A planar graph for which the count of p-sided faces is computed.

• p (int, optional) – The number of sides of the faces to count. Defaults to 3 (triangular faces).

Returns:

The number of p-sided faces in the graph. Returns 0 if no such faces exist.

Return type:

int

Notes

• This function assumes the input graph is planar.

• It internally calls the p_vector function to calculate the p-vector of the graph.

Examples

Count the number of triangular faces in a hexagonal graph:

>>> import graphcalc.graphs as gc
>>> G = gc.cycle_graph(6)  # Hexagon
>>> gc.polytopes.p_gons(G, p=3)
0

Count the number of hexagonal faces in the same graph:

>>> gc.p_gons(G, p=6)
1

Count the number of pentagonal faces in a graph with multiple face types:

>>> G = gc.SimpleGraph()
>>> G.add_edges_from([
...     (0, 1), (1, 2), (2, 3), (3, 0),  # Quadrilateral face
...     (0, 4), (4, 1),  # Two triangular faces
...     (1, 5), (5, 2)
... ])
>>> gc.polytopes.p_gons(G, p=5)
0

graphcalc.graphs.polytopes.invariants.p_vector(G_nx: Graph | SimpleGraph) → List[int]

Compute the p-vector of a planar graph.

The p-vector of a graph is a list where the i-th entry represents the count of i-sided faces (e.g., triangles, quadrilaterals, pentagons) in a planar embedding of the graph. The function assumes the input graph is planar and connected.

Parameters:

G_nx (networkx.Graph or graphcalc.SimpleGraph) – A planar graph for which the p-vector is computed.

Returns:

The p-vector, where the value at index k-3 corresponds to the number of k-sided faces in the graph.

Return type:

list of int

Notes

• This function first checks the planarity of the input graph using NetworkX’s check_planarity.

• If the graph is not planar, a ValueError is raised.

Examples

Compute the p-vector of a simple planar graph:

>>> import graphcalc.graphs as gc
>>> G = gc.cycle_graph(6)  # Hexagon
>>> gc.p_vector(G)
[0, 0, 0, 1]

Compute the p-vector of a graph with multiple face sizes:

>>> G = gc.SimpleGraph()
>>> G.add_edges_from([
...     (0, 1), (1, 2), (2, 3), (3, 0),  # Quadrilateral face
...     (0, 4), (4, 1),  # Two triangular faces
...     (1, 5), (5, 2)
... ])
>>> gc.polytopes.p_vector(G)
[2, 1, 0, 1]

graphcalc.graphs.polytopes.invariants.polytope_graph(G: Graph | SimpleGraph) → bool

Determine whether a graph is the 1-skeleton of a convex 3D polyhedron.

According to Steinitz’s theorem, a graph is a polytope graph (polyhedral graph) if and only if it is: 1. Simple (no loops or multi-edges), 2. Planar, 3. 3-connected.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The graph to check.

Returns:

True if G is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.path_graph(5)
>>> gc.polytopes.polytope_graph(G)
False

graphcalc.graphs.polytopes.invariants.polytope_graph_with_p6_greater_than_zero(G: Graph | SimpleGraph) → bool

Check if a graph is the graph of a polyhedron with at least one hexagonal face.

A graph is the graph of a polyhedron (or a polytope graph) if and only if it is: 1. Simple: The graph has no self-loops or multiple edges. 2. Planar: The graph can be embedded in the plane without edge crossings. 3. 3-Connected: The graph remains connected after removing any two vertices. 4. At least one hexagonal face: The graph has at least one hexagonal face.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.cube_graph()  # Cubical graph is a polytope graph with hexagonal faces
>>> gc.polytope_graph_with_p6_greater_than_zero(G)
False

graphcalc.graphs.polytopes.invariants.polytope_graph_with_p6_zero(G: Graph | SimpleGraph) → bool

Check if a graph is the graph of a polyhedron with no hexagonal faces.

A graph is the graph of a polyhedron (or a polytope graph) if and only if it is: 1. Simple: The graph has no self-loops or multiple edges. 2. Planar: The graph can be embedded in the plane without edge crossings. 3. 3-Connected: The graph remains connected after removing any two vertices. 4. No hexagonal faces: The graph has no hexagonal faces.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.polytopes.cube_graph()  # Cubical graph is a polytope graph with hexagonal faces
>>> gc.polytopes.polytope_graph_with_p6_zero(G)
True

graphcalc.graphs.polytopes.invariants.simple_graph(G: Graph | SimpleGraph) → bool

Check if a graph is simple.

A graph is simple if: 1. It has no self-loops. 2. It has no multiple edges.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is simple, False otherwise.

Return type:

bool

graphcalc.graphs.polytopes.invariants.simple_polytope_graph(G: Graph | SimpleGraph) → bool

Check if a graph is the graph of a simple polyhedron.

A graph is the graph of a polyhedron (or a polytope graph) if and only if it is: 1. Simple: The graph has no self-loops or multiple edges. 2. Planar: The graph can be embedded in the plane without edge crossings. 3. 3-Connected: The graph remains connected after removing any two vertices. 4. 3-Regular: Each vertex has degree 3.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.polytopes.cube_graph()  # Octahedral graph is a simple polytope graph
>>> gc.polytopes.simple_polytope_graph(G)
True

>>> G = gc.path_graph(5)  # Path graph is not a simple polytope graph
>>> gc.polytopes.simple_polytope_graph(G)
False

graphcalc.graphs.polytopes.invariants.simple_polytope_graph_with_p6_greater_than_zero(G: Graph | SimpleGraph) → bool

Check if a graph is the graph of a simple polyhedron with at least one hexagonal face.

A graph is the graph of a polyhedron (or a polytope graph) if and only if it is: 1. Simple: The graph has no self-loops or multiple edges. 2. Planar: The graph can be embedded in the plane without edge crossings. 3. 3-Connected: The graph remains connected after removing any two vertices. 4. 3-Regular: Each vertex has degree 3. 5. At least one hexagonal face: The graph has at least one hexagonal face.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.polytopes.cube_graph()  # Cubical graph is a simple polytope graph with hexagonal faces
>>> gc.simple_polytope_graph_with_p6_greater_than_zero(G)
False

graphcalc.graphs.polytopes.invariants.simple_polytope_graph_with_p6_zero(G: Graph | SimpleGraph) → bool

Check if a graph is the graph of a simple polyhedron with no hexagonal faces.

A graph is the graph of a polyhedron (or a polytope graph) if and only if it is: 1. Simple: The graph has no self-loops or multiple edges. 2. Planar: The graph can be embedded in the plane without edge crossings. 3. 3-Connected: The graph remains connected after removing any two vertices. 4. 3-Regular: Each vertex has degree 3. 5. No hexagonal faces: The graph has no hexagonal faces.

Parameters:

G (networkx.Graph or graphcalc.SimpleGraph) – The input graph.

Returns:

True if the graph is a polytope graph, False otherwise.

Return type:

bool

Examples

>>> import graphcalc.graphs as gc
>>> G = gc.polytopes.cube_graph()  # Cubical graph is a simple polytope graph with hexagonal faces
>>> gc.polytopes.simple_polytope_graph_with_p6_zero(G)
True