2.2. Validation System

We often require our cell complexes to satisfy geometric constraints. The validation system provides modular, extensible validation for embedded cell complexes to ensure they represent proper embeddings in Euclidean space.

2.2.1. Overview

The validation system distinguishes between two types of rules:

• Structural Rules (always checked): Basic requirements like vertex counts and dimension validity

• Geometric Rules (optional): Embedding properties like non-intersecting edges and faces

2.2.2. Architecture

The validation system consists of several components:

1. Base Classes: Abstract interfaces for validation rules and results

2. Validation Rules: Concrete implementations for specific validation checks

3. Validator: Main orchestrator that manages and applies rules

2.2.3. Validation Rules

2.2.3.1. Structural Rules (Always Enforced)

• DimensionValidityRule: Ensures cell dimensions are non-negative

• VertexCountRule: Validates correct vertex counts for cell dimensions

  • 0-cells must have exactly 1 vertex

  • 1-cells must have exactly 2 vertices

  • k-cells (k ≥ 2) must have at least 3 vertices

2.2.3.2. Geometric Rules (Optional)

• EdgeInteriorRule: Ensures no vertices lie on edge interiors

• FaceInteriorRule: Ensures no vertices lie inside face interiors

• SelfIntersectionRule: Validates that face edges don’t self-intersect

• BoundaryEdgeRule: Ensures required boundary edges exist for faces

2.2.4. Usage

from ect import EmbeddedComplex

# Enable validation during construction
K = EmbeddedComplex(validate_embedding=True)

# Or enable/disable later
K.enable_embedding_validation(tol=1e-10)
K.disable_embedding_validation()

# Override per operation
K.add_cell(vertices, dim=2, check=True)

2.2.5. Custom Validation Rules

You can create custom validation rules by inheriting from ValidationRule:

from ect.validation import ValidationRule, ValidationResult

class MyCustomRule(ValidationRule):
    @property
    def name(self) -> str:
        return "My Custom Rule"
    
    @property
    def is_structural(self) -> bool:
        return False  # Geometric rule
    
    def applies_to_dimension(self, dim: int) -> bool:
        return dim == 2  # Only for 2-cells
    
    def validate(self, cell_coords, all_coords, cell_indices, all_indices, dim):
        # Your validation logic here
        if some_condition:
            return ValidationResult.valid()
        else:
            return ValidationResult.invalid("Validation failed")

# Add to validator
K.get_validator().add_rule(MyCustomRule())

2.2.6. API Reference

2.2.6.1. Main Module

Embedding validation system for EmbeddedComplex.

This module provides a flexible, extensible system for validating that cell complexes represent proper embeddings in Euclidean space.

class ect.validation.EmbeddingValidator(tolerance=1e-10, edge_checker=None)

Main validator that orchestrates multiple validation rules.

This class manages a collection of validation rules and applies them to cells based on their dimension and the configured rule set.

__init__(tolerance=1e-10, edge_checker=None)

Initialize the embedding validator.

Parameters:

• tolerance – Default tolerance for geometric validation

• edge_checker – Function to check if an edge exists between two vertex indices

add_rule(rule)

Add a custom validation rule.

Parameters:

rule – ValidationRule to add

Returns:

Self for method chaining

disable_rule(rule_class)

Temporarily disable a rule type.

Parameters:

rule_class – Class of rule to disable

Returns:

Self for method chaining

enable_permissive_validation()

Enable permissive validation with loose tolerance.

Returns:

Self for method chaining

enable_strict_validation()

Enable strict validation with tight tolerance.

Returns:

Self for method chaining

get_rule_names()

Get names of all registered rules.

Returns:

List of rule names

get_rules_for_dimension(dim)

Get all rules that apply to a specific dimension.

Parameters:

dim – Cell dimension

Returns:

List of applicable ValidationRules

remove_rule(rule_class)

Remove all rules of a specific type.

Parameters:

rule_class – Class of rules to remove

Returns:

Self for method chaining

set_edge_checker(edge_checker)

Set the edge checker function for boundary validation.

Parameters:

edge_checker – Function that takes two vertex indices and returns bool

Returns:

Self for method chaining

set_tolerance(tolerance)

Set tolerance for all rules.

Parameters:

tolerance – New tolerance value

Returns:

Self for method chaining

validate_cell(cell_coords, all_coords, cell_indices, all_indices, dim, check_geometric=True)

Validate a cell using applicable rules.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell

• check_geometric – Whether to check geometric rules (structural rules always checked)

Returns:

ValidationResult for the cell

Raises:

ValueError – If validation fails

validate_cell_safe(cell_coords, all_coords, cell_indices, all_indices, dim, check_geometric=True)

Validate a cell, catching and wrapping any exceptions.

Same as validate_cell but returns ValidationResult instead of raising.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell

• check_geometric – Whether to check geometric rules (structural rules always checked)

Returns:

ValidationResult for the cell

validate_coordinates(coords, expected_dim=None)

Validate coordinate array format and dimension consistency.

Parameters:

• coords – Coordinate array to validate

• expected_dim – Expected dimension, if known

Returns:

ValidationResult for the coordinates

validate_nodes(nodes, node_checker, expect_exists=True)

Validate node existence/non-existence.

Parameters:

• nodes – List of node identifiers to check

• node_checker – Function that takes node_id and returns bool for existence

• expect_exists – Whether nodes should exist (True) or not exist (False)

Returns:

ValidationResult for the nodes

class ect.validation.ValidationRule(tolerance=1e-10)

Abstract base class for embedding validation rules.

__init__(tolerance=1e-10)

Initialize validation rule.

Parameters:

tolerance – Numerical tolerance for geometric checks

abstractmethod applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

abstract property name

Human-readable name of this validation rule.

set_tolerance(tolerance)

Set the tolerance for this rule.

Parameters:

tolerance – New tolerance value

Returns:

Self for method chaining

abstractmethod validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate a cell against this rule.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell being validated

Returns:

ValidationResult indicating if the cell is valid

class ect.validation.ValidationResult(is_valid, message='', violating_indices=None)

Result of a validation check.

__init__(is_valid, message='', violating_indices=None)

classmethod invalid(message, violating_indices=None)

Create an invalid result with error message.

message = ''

classmethod valid()

Create a valid result.

violating_indices = None

is_valid

class ect.validation.EdgeInteriorRule(tolerance=1e-10)

Validates that no vertices lie on edge interiors.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that no other vertices lie on this edge’s interior.

class ect.validation.FaceInteriorRule(tolerance=1e-10)

Validates that no vertices lie inside face interiors.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that no other vertices lie inside this face.

class ect.validation.SelfIntersectionRule(tolerance=1e-10)

Validates that face edges don’t self-intersect.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that face edges don’t intersect each other

class ect.validation.BoundaryEdgeRule(tolerance=1e-10, edge_checker=None)

Validates that required boundary edges exist for faces.

__init__(tolerance=1e-10, edge_checker=None)

Initialize boundary edge rule.

Parameters:

• tolerance – Numerical tolerance

• edge_checker – Function to check if an edge exists (injected dependency)

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that all boundary edges exist for this face.

class ect.validation.DimensionValidityRule(tolerance=1e-10)

Validates that cell dimension is non-negative.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that dimension is non-negative.

class ect.validation.VertexCountRule(tolerance=1e-10)

Validates that cells have the correct number of vertices for their dimension.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

property name

Human-readable name of this validation rule.

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate vertex count matches cell dimension requirements.

ect.validation.validate_coordinate_array(coords, expected_dim=None)

Standalone function to validate coordinate array format.

ect.validation.validate_node_existence(nodes, node_checker, expect_exists=True)

Standalone function to validate node existence.

2.2.6.2. Base Classes

Base classes for the embedding validation system.

class ect.validation.base.ValidationResult(is_valid, message='', violating_indices=None)

Bases: object

Result of a validation check.

is_valid

message = ''

violating_indices = None

classmethod valid()

Create a valid result.

classmethod invalid(message, violating_indices=None)

Create an invalid result with error message.

__init__(is_valid, message='', violating_indices=None)

class ect.validation.base.ValidationRule(tolerance=1e-10)

Bases: ABC

Abstract base class for embedding validation rules.

__init__(tolerance=1e-10)

Initialize validation rule.

Parameters:

tolerance – Numerical tolerance for geometric checks

abstract property name

Human-readable name of this validation rule.

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

abstractmethod applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

abstractmethod validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate a cell against this rule.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell being validated

Returns:

ValidationResult indicating if the cell is valid

set_tolerance(tolerance)

Set the tolerance for this rule.

Parameters:

tolerance – New tolerance value

Returns:

Self for method chaining

2.2.6.3. Validation Rules

Unified validation rules for embedding validation system.

This module contains all validation rules including both structural rules (which are always checked) and geometric rules (which are optional).

class ect.validation.rules.DimensionValidityRule(tolerance=1e-10)

Bases: ValidationRule

Validates that cell dimension is non-negative.

property name

Human-readable name of this validation rule.

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that dimension is non-negative.

class ect.validation.rules.VertexCountRule(tolerance=1e-10)

Bases: ValidationRule

Validates that cells have the correct number of vertices for their dimension.

property name

Human-readable name of this validation rule.

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate vertex count matches cell dimension requirements.

class ect.validation.rules.CoordinateDimensionRule(tolerance=1e-10, dimension_checker=None)

Bases: ValidationRule

Validates that coordinates have consistent dimensions.

__init__(tolerance=1e-10, dimension_checker=None)

Initialize validation rule.

Parameters:

tolerance – Numerical tolerance for geometric checks

property name

Human-readable name of this validation rule.

property is_structural

Check if this is a structural rule that should always be validated.

Structural rules check basic requirements like vertex counts and dimension validity. They should always be checked regardless of validation settings. Geometric rules check embedding properties and are optional.

Returns:

True if this rule should always be checked, False if optional

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate coordinate dimensions are consistent.

class ect.validation.rules.EdgeInteriorRule(tolerance=1e-10)

Bases: ValidationRule

Validates that no vertices lie on edge interiors.

property name

Human-readable name of this validation rule.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that no other vertices lie on this edge’s interior.

class ect.validation.rules.FaceInteriorRule(tolerance=1e-10)

Bases: ValidationRule

Validates that no vertices lie inside face interiors.

property name

Human-readable name of this validation rule.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that no other vertices lie inside this face.

class ect.validation.rules.SelfIntersectionRule(tolerance=1e-10)

Bases: ValidationRule

Validates that face edges don’t self-intersect.

property name

Human-readable name of this validation rule.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that face edges don’t intersect each other

class ect.validation.rules.BoundaryEdgeRule(tolerance=1e-10, edge_checker=None)

Bases: ValidationRule

Validates that required boundary edges exist for faces.

__init__(tolerance=1e-10, edge_checker=None)

Initialize boundary edge rule.

Parameters:

• tolerance – Numerical tolerance

• edge_checker – Function to check if an edge exists (injected dependency)

property name

Human-readable name of this validation rule.

applies_to_dimension(dim)

Check if this rule applies to cells of the given dimension.

Parameters:

dim – Cell dimension

Returns:

True if this rule should validate cells of this dimension

validate(cell_coords, all_coords, cell_indices, all_indices, dim=None)

Validate that all boundary edges exist for this face.

ect.validation.rules.validate_coordinate_array(coords, expected_dim=None)

Standalone function to validate coordinate array format.

ect.validation.rules.validate_node_existence(nodes, node_checker, expect_exists=True)

Standalone function to validate node existence.

2.2.6.4. Validator

Main embedding validator class that orchestrates validation rules.

class ect.validation.validator.EmbeddingValidator(tolerance=1e-10, edge_checker=None)

Bases: object

Main validator that orchestrates multiple validation rules.

This class manages a collection of validation rules and applies them to cells based on their dimension and the configured rule set.

__init__(tolerance=1e-10, edge_checker=None)

Initialize the embedding validator.

Parameters:

• tolerance – Default tolerance for geometric validation

• edge_checker – Function to check if an edge exists between two vertex indices

add_rule(rule)

Add a custom validation rule.

Parameters:

rule – ValidationRule to add

Returns:

Self for method chaining

remove_rule(rule_class)

Remove all rules of a specific type.

Parameters:

rule_class – Class of rules to remove

Returns:

Self for method chaining

set_tolerance(tolerance)

Set tolerance for all rules.

Parameters:

tolerance – New tolerance value

Returns:

Self for method chaining

set_edge_checker(edge_checker)

Set the edge checker function for boundary validation.

Parameters:

edge_checker – Function that takes two vertex indices and returns bool

Returns:

Self for method chaining

validate_cell(cell_coords, all_coords, cell_indices, all_indices, dim, check_geometric=True)

Validate a cell using applicable rules.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell

• check_geometric – Whether to check geometric rules (structural rules always checked)

Returns:

ValidationResult for the cell

Raises:

ValueError – If validation fails

validate_cell_safe(cell_coords, all_coords, cell_indices, all_indices, dim, check_geometric=True)

Validate a cell, catching and wrapping any exceptions.

Same as validate_cell but returns ValidationResult instead of raising.

Parameters:

• cell_coords – Coordinates of vertices forming the cell

• all_coords – Coordinates of all vertices in the complex

• cell_indices – Indices of vertices forming the cell

• all_indices – Indices of all vertices in the complex

• dim – Dimension of the cell

• check_geometric – Whether to check geometric rules (structural rules always checked)

Returns:

ValidationResult for the cell

get_rules_for_dimension(dim)

Get all rules that apply to a specific dimension.

Parameters:

dim – Cell dimension

Returns:

List of applicable ValidationRules

get_rule_names()

Get names of all registered rules.

Returns:

List of rule names

disable_rule(rule_class)

Temporarily disable a rule type.

Parameters:

rule_class – Class of rule to disable

Returns:

Self for method chaining

enable_strict_validation()

Enable strict validation with tight tolerance.

Returns:

Self for method chaining

enable_permissive_validation()

Enable permissive validation with loose tolerance.

Returns:

Self for method chaining

validate_coordinates(coords, expected_dim=None)

Validate coordinate array format and dimension consistency.

Parameters:

• coords – Coordinate array to validate

• expected_dim – Expected dimension, if known

Returns:

ValidationResult for the coordinates

validate_nodes(nodes, node_checker, expect_exists=True)

Validate node existence/non-existence.

Parameters:

• nodes – List of node identifiers to check

• node_checker – Function that takes node_id and returns bool for existence

• expect_exists – Whether nodes should exist (True) or not exist (False)

Returns:

ValidationResult for the nodes