2.1. Embedded Complex

The EmbeddedComplex class is a unified representation for embedded cell complexes supporting arbitrary dimensional cells.

2.1.1. Overview

EmbeddedComplex combines and extends the functionality of the previous EmbeddedGraph and EmbeddedCW classes into a single interface. It supports:

• 0-cells (vertices): Points embedded in Euclidean space

• 1-cells (edges): Line segments between vertices

• k-cells for k ≥ 2: Higher dimensional cells (faces, volumes, etc.)

2.1.2. Basic Usage

from ect import EmbeddedComplex

# Create a complex
K = EmbeddedComplex()

# Add vertices
K.add_node("A", [0, 0])
K.add_node("B", [1, 0])
K.add_node("C", [0.5, 1])

# Add edges
K.add_edge("A", "B")
K.add_edge("B", "C")
K.add_edge("C", "A")

# Add a 2-cell (face)
K.add_face(["A", "B", "C"])

# Or use the general method for any dimension
K.add_cell(["A", "B", "C"], dim=2)

2.1.3. API Reference

class ect.embed_complex.EmbeddedComplex(validate_embedding=False, embedding_tol=1e-10)

Bases: Graph

A unified class to represent an embedded cell complex with cells of arbitrary dimension.

This combines the functionality of EmbeddedGraph and EmbeddedCW, supporting: - 0-cells (vertices) with embedded coordinates - 1-cells (edges) - k-cells for k >= 2 (faces, volumes, etc.)

Parameters:

• validate_embedding (bool) – If True, automatically validate embedding properties when adding cells. Default: False

• embedding_tol (float) – Tolerance for geometric validation. Default: 1e-10

coord_matrix

np.ndarray A matrix of embedded coordinates for each vertex

node_list

list A list of node names

node_to_index

dict A dictionary mapping node ids to their index in the coord_matrix

dim

int The dimension of the embedded coordinates

cells

dict Dictionary mapping dimension k to list of k-cells, where each k-cell is represented as a tuple of vertex indices

validate_embedding

bool Whether to automatically validate embedding properties

embedding_tol

float Tolerance for geometric validation

__init__(validate_embedding=False, embedding_tol=1e-10)

Initialize a graph with edges, name, or graph attributes.

Parameters:

• incoming_graph_data (input graph (optional, default: None)) – Data to initialize graph. If None (default) an empty graph is created. The data can be an edge list, or any NetworkX graph object. If the corresponding optional Python packages are installed the data can also be a 2D NumPy array, a SciPy sparse array, or a PyGraphviz graph.

• attr (keyword arguments, optional (default= no attributes)) – Attributes to add to graph as key=value pairs.

See also

convert

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G = nx.Graph(name="my graph")
>>> e = [(1, 2), (2, 3), (3, 4)]  # list of edges
>>> G = nx.Graph(e)

Arbitrary graph attribute pairs (key=value) may be assigned

>>> G = nx.Graph(e, day="Friday")
>>> G.graph
{'day': 'Friday'}

property coord_matrix

Return the N x D coordinate matrix

property dim

Return the dimension of the embedded coordinates

property node_list

Return ordered list of node names.

property node_to_index

Return a dictionary mapping node ids to their index in the coord_matrix

property position_dict

Return a dictionary mapping node ids to their coordinates

property edge_indices

Return edges as array of index pairs

property faces

Return list of 2-cells (faces) for backward compatibility

add_node(node_id, coord)

Add a vertex to the complex.

Parameters:

• node_id – Identifier for the node

• coord – Array-like coordinates for the node

add_nodes_from_dict(nodes_with_coords)

add_nodes_from(nodes_with_coords)

Add multiple nodes.

Parameters:

• nodes_for_adding (iterable container) – A container of nodes (list, dict, set, etc.). OR A container of (node, attribute dict) tuples. Node attributes are updated using the attribute dict.

• attr (keyword arguments, optional (default= no attributes)) – Update attributes for all nodes in nodes. Node attributes specified in nodes as a tuple take precedence over attributes specified via keyword arguments.

See also

add_node

Notes

When adding nodes from an iterator over the graph you are changing, a RuntimeError can be raised with message: RuntimeError: dictionary changed size during iteration. This happens when the graph’s underlying dictionary is modified during iteration. To avoid this error, evaluate the iterator into a separate object, e.g. by using list(iterator_of_nodes), and pass this object to G.add_nodes_from.

Examples

>>> G = nx.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_nodes_from("Hello")
>>> K3 = nx.Graph([(0, 1), (1, 2), (2, 0)])
>>> G.add_nodes_from(K3)
>>> sorted(G.nodes(), key=str)
[0, 1, 2, 'H', 'e', 'l', 'o']

Use keywords to update specific node attributes for every node.

>>> G.add_nodes_from([1, 2], size=10)
>>> G.add_nodes_from([3, 4], weight=0.4)

Use (node, attrdict) tuples to update attributes for specific nodes.

>>> G.add_nodes_from([(1, dict(size=11)), (2, {"color": "blue"})])
>>> G.nodes[1]["size"]
11
>>> H = nx.Graph()
>>> H.add_nodes_from(G.nodes(data=True))
>>> H.nodes[1]["size"]
11

Evaluate an iterator over a graph if using it to modify the same graph

>>> G = nx.Graph([(0, 1), (1, 2), (3, 4)])
>>> # wrong way - will raise RuntimeError
>>> # G.add_nodes_from(n + 1 for n in G.nodes)
>>> # correct way
>>> G.add_nodes_from(list(n + 1 for n in G.nodes))

add_edge(node_id1, node_id2)

Add an edge (1-cell) between two nodes

add_cell(cell_vertices, dim=None, check=None, embedding_tol=None)

Add a k-cell to the complex.

Parameters:

• cell_vertices – List of vertex identifiers that form the cell

• dim – Dimension of the cell. If None, inferred as len(cell_vertices) - 1

• check – Whether to validate the cell embedding. If None, uses self.validate_embedding

• embedding_tol – Tolerance for geometric validation. If None, uses self.embedding_tol

enable_embedding_validation(tol=1e-10)

Enable automatic embedding validation for all subsequent cell additions.

Parameters:

tol – Tolerance for geometric validation

disable_embedding_validation()

Disable automatic embedding validation for all subsequent cell additions.

get_validator()

Get the embedding validator instance for advanced configuration.

Returns:

The EmbeddingValidator instance used by this complex

set_validation_rules(rules)

Set custom validation rules.

Parameters:

rules – List of ValidationRule instances

Returns:

Self for method chaining

add_face(face, check=None)

Add a 2-cell (face) to the complex. Provided for backward compatibility.

add_faces_from(faces)

Add multiple 2-cells (faces) to the complex.

get_coord(node_id)

Return the coordinates of a node

set_coord(node_id, new_coords)

Set the coordinates of a node

add_cycle(coord_matrix)

Add nodes in a cyclic pattern from coordinate matrix

get_center(method='bounding_box')

Calculate center of coordinates

get_bounding_box()

Get (min, max) for each dimension

get_bounding_radius(center_type='bounding_box')

Get radius of minimal bounding sphere

get_normal_angle_matrix(edges_only=False, decimals=None)

Optimized angle matrix computation using vectorized operations.

Parameters:

• edges_only – Only compute angles between connected vertices

• decimals – Round angles to specified decimal places

Returns:

NaN-filled matrix with pair angles vertex_labels: Ordered node identifiers

Return type:

angle_matrix

get_normal_angles(edges_only=False, decimals=6)

Optimized angle dictionary construction using NumPy grouping.

Parameters:

• edges_only – Only include edge-connected pairs

• decimals – Round angles to specified decimal places

Returns:

Dictionary mapping rounded angles to vertex pairs

transform_coordinates(center_type='bounding_box', projection_type='pca')

Transform coordinates center and orientation

center_coordinates(center_type='mean')

scale_coordinates(radius=1)

Scale coordinates to fit within given radius

project_coordinates(projection_type='pca')

Project coordinates using a function

pca_projection(target_dim=2)

Dimensionality reduction using PCA

validate_plot_parameters()

plot_faces(ax=None, **kwargs)

Plots the 2-cells (faces) of the complex.

Parameters:

• ax (matplotlib.axes.Axes) – The axes to plot the graph on. If None, a new figure is created.

• **kwargs – Additional keyword arguments to pass to the ax.fill function.

Returns:

matplotlib.axes.Axes

The axes object with the plot.

plot(*args, **kwargs)

ect.embed_complex.EmbeddedGraph

alias of EmbeddedComplex

ect.embed_complex.EmbeddedCW

alias of EmbeddedComplex