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(*args, backend=None, **kwargs)[source]

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

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

Initialize an EmbeddedComplex instance.

Parameters:

  • validate_embedding (bool, optional) – If True, automatically validate embedding properties when adding cells. Defaults to False.

  • embedding_tol (float, optional) – Tolerance for geometric validation. Defaults to 1e-10.

Notes

  • The complex supports arbitrary-dimensional cells (vertices, edges, faces, etc.).

  • Embedding validation can be enabled or disabled at initialization or later.

property coord_matrix

Get the coordinate matrix of the embedded complex.

Returns:

A matrix of shape \((N, D)\) where \(N\) is the number of nodes (vertices) and \(D\) is the dimension of the embedding. Each row corresponds to the coordinates of a node in the order given by node_list.

Return type:

np.ndarray

Notes

  • If no nodes have been added, returns an empty array of shape \((0, 0)\).

  • The coordinate matrix is updated automatically as nodes are added or modified.

  • The order of rows matches the order of node identifiers in node_list.

property dim

Get the dimension \(D\) of the embedded coordinates.

Returns:

The number of dimensions (D) for the coordinates of each node. Returns 0 if no nodes exist.

Return type:

int

property node_list

Get the ordered list of node names in the complex.

Returns:

List of node identifiers in the order corresponding to the rows of the coordinate matrix coord_matrix.

Return type:

list

property node_to_index

Get a mapping from node identifiers to their row index in the coordinate matrix coord_matrix.

Returns:

Dictionary mapping node ids to their index in the coordinate matrix.

Return type:

dict

property position_dict

Get a dictionary mapping node ids to their coordinates.

Returns:

Dictionary where keys are node ids and values are coordinate arrays for each node (from coord_matrix).

Return type:

dict

property edge_indices

Get the edges of the complex as an array of index pairs.

Returns:

Array of shape (E, 2) where each row contains the indices of the two nodes forming an edge. Returns an empty array if there are no edges.

Return type:

np.ndarray

property faces

Get the list of 2-cells (faces) in the complex.

Returns:

List of tuples, each representing a face as a sequence of node names. Provided for backward compatibility.

Return type:

list

add_node(node_id, coord)[source]

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)[source]

Add multiple vertices to the complex.

Parameters:

nodes_with_coords (Dict[Union[str, int], np.ndarray]) – Dictionary mapping node ids to coordinates

add_nodes_from(nodes_with_coords)[source]

Add multiple vertices to the complex.

Parameters:

nodes_with_coords (List[Tuple[Union[str, int], np.ndarray]]) – List of (node_id, coordinates) tuples

add_edge(node_id1, node_id2)[source]

Add an edge (1-cell) between two nodes in the complex.

Parameters:

  • node_id1 – Identifier for the first node.

  • node_id2 – Identifier for the second node.

Raises:

ValueError – If either node does not exist in the complex.

add_cell(cell_vertices, dim=None, check=None, embedding_tol=None)[source]

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 embedding_tol.

enable_embedding_validation(tol=1e-10)[source]

Enable automatic embedding validation for all subsequent cell additions.

Parameters:

tol – Tolerance for geometric validation

disable_embedding_validation()[source]

Disable automatic embedding validation for all subsequent cell additions.

After calling this method, new cells will not be checked for geometric embedding validity.

get_validator()[source]

Get the embedding validator instance for advanced configuration.

Returns:

The EmbeddingValidator instance used by this complex

set_validation_rules(rules)[source]

Set custom validation rules.

Parameters:

rules – List of ValidationRule instances

Returns:

Self for method chaining

add_face(face, check=None)[source]

Add a 2-cell (face) to the complex.

Parameters:

  • face (list) – List of node identifiers forming the face.

  • check (Optional[bool]) – Whether to validate the embedding of the face. If None, uses the default setting.

Notes

Provided for backward compatibility with previous interfaces.

add_faces_from(faces)[source]

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

Parameters:

faces (list of lists) – Each sublist contains node identifiers forming a face.

get_coord(node_id)[source]

Get the coordinates of a node.

Parameters:

node_id – Identifier of the node whose coordinates are requested.

Returns:

Coordinate array for the specified node.

Return type:

np.ndarray

Raises:

ValueError – If the node does not exist in the complex.

set_coord(node_id, new_coords)[source]

Set the coordinates of a node.

Parameters:

  • node_id – Identifier of the node to update.

  • new_coords – New coordinates to assign to the node.

Raises:

ValueError – If the coordinates are invalid or the node does not exist.

add_cycle(coord_matrix)[source]

Add nodes in a cyclic pattern from a coordinate matrix.

Parameters:

coord_matrix (np.ndarray) – Matrix of shape (N, D) where each row is the coordinates of a node.

Notes

Nodes are named sequentially and connected in a cycle.

get_center(method='bounding_box')[source]

Calculate the center of the coordinates of all nodes.

Parameters:

method (str) – Method to use for center calculation. Options are “mean”, “bounding_box”, or “origin”.

Returns:

The center coordinates as determined by the specified method.

Return type:

np.ndarray

Raises:

ValueError – If an unknown method is specified.

get_bounding_box()[source]

Get the minimum and maximum values for each coordinate dimension.

Returns:

List of (min, max) tuples for each dimension.

Return type:

list

get_bounding_radius(center_type='bounding_box')[source]

Get the radius of the minimal bounding sphere containing all node coordinates.

Parameters:

center_type (str) – Method to use for center calculation (see get_center).

Returns:

The radius of the minimal bounding sphere.

Return type:

float

get_normal_angle_matrix(edges_only=False, decimals=None)[source]

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)[source]

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')[source]

Transform the coordinates by centering and projecting them.

Parameters:

  • center_type (str) – Method for centering coordinates.

  • projection_type (str) – Method for projecting coordinates (e.g., “pca”).

Raises:

ValueError – If an unknown transform or center type is specified.

center_coordinates(center_type='mean')[source]
scale_coordinates(radius=1)[source]

Scale the coordinates so that the largest distance from the origin equals the given radius.

Parameters:

radius (float) – Target radius for scaling.

project_coordinates(projection_type='pca')[source]

Project the coordinates using the specified projection function.

Parameters:

projection_type (str) – The type of projection to use (e.g., “pca”).

Raises:

ValueError – If an unknown projection type is specified.

pca_projection(target_dim=2)[source]

Reduce the dimensionality of the coordinates using Principal Component Analysis (PCA).

Parameters:

target_dim (int) – Target number of dimensions (default is 2).

Notes

Only reduces dimension if current dimension is greater than target_dim.

validate_plot_parameters()[source]
plot_faces(ax=None, **kwargs)[source]

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(bounding_circle=False, bounding_center_type='bounding_box', color_nodes_theta=None, ax=None, with_labels=True, node_size=300, edge_color='gray', elev=25, azim=-60, face_color='lightblue', face_alpha=0.3, **kwargs)[source]

Visualize the embedded complex in 2D or 3D

Parameters:

  • bounding_circle (bool) – Whether to draw a bounding circle/sphere

  • bounding_center_type (str) – Method for center calculation for bounding shape

  • color_nodes_theta (float, optional) – Angle in radians to color nodes by projection

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

  • with_labels (bool) – Whether to display node labels

  • node_size (int) – Size of nodes in the plot

  • edge_color (str) – Color of edges in the plot

  • elev (float) – Elevation angle for 3D plot

  • azim (float) – Azimuth angle for 3D plot

  • face_color (str) – Color for faces (2-cells)

  • face_alpha (float) – Transparency for faces (2-cells)

  • **kwargs – Additional keyword arguments for plotting functions

Returns:

The axes object with the plot.

Return type:

matplotlib.axes.Axes

ect.embed_complex.EmbeddedGraph

alias of EmbeddedComplex

ect.embed_complex.EmbeddedCW

alias of EmbeddedComplex