uor-foundation 0.1.3

// @generated by uor-crate from uor-ontology — do not edit manually

//! `homology/` namespace — Simplicial complexes, chain complexes, boundary operators, and homology groups for structural reasoning..
//!
//! Space: Bridge

use crate::Primitives;

/// A k-simplex: a finite set of k+1 vertices drawn from constraint objects.
pub trait Simplex<P: Primitives> {
    /// The dimension k of a simplex (number of vertices minus one).
    fn dimension(&self) -> P::Integer;
    /// Associated type for `Constraint`.
    type Constraint: crate::user::type_::Constraint<P>;
    /// A vertex of this simplex, drawn from the set of constraint objects.
    fn vertex(&self) -> &[Self::Constraint];
    /// The number of vertices in this simplex (dimension + 1).
    fn vertex_count(&self) -> P::PositiveInteger;
    /// Associated type for `Simplex`.
    type SimplexTarget: Simplex<P>;
    /// Indicates that this simplex is a face of another simplex.
    fn is_face_of(&self) -> &[Self::SimplexTarget];
    /// Associated type for `FiberCoordinate`.
    type FiberCoordinate: crate::bridge::partition::FiberCoordinate<P>;
    /// A fiber coordinate in the partition whose intersection pins this simplex.
    fn pin_intersection(&self) -> &[Self::FiberCoordinate];
}

/// A simplicial complex: a set of simplices closed under taking faces.
pub trait SimplicialComplex<P: Primitives> {
    /// Associated type for `Simplex`.
    type Simplex: Simplex<P>;
    /// A simplex belonging to this simplicial complex.
    fn has_simplex(&self) -> &[Self::Simplex];
    /// The maximum dimension of any simplex in this simplicial complex.
    fn max_dimension(&self) -> P::Integer;
    /// The Euler characteristic of this simplicial complex: the alternating sum of simplex counts by dimension.
    fn euler_characteristic(&self) -> P::Integer;
    /// The total number of vertices (0-simplices) in this simplicial complex.
    fn simplicial_vertex_count(&self) -> P::NonNegativeInteger;
}

/// A face map d_i: removes vertex i from a simplex, producing a face.
pub trait FaceMap<P: Primitives> {
    /// The index i of the vertex removed by this face map d_i.
    fn removes_vertex(&self) -> P::NonNegativeInteger;
    /// Associated type for `Simplex`.
    type Simplex: Simplex<P>;
    /// The source simplex of this face map.
    fn source_simplex(&self) -> &Self::Simplex;
    /// The target face (result simplex) of this face map.
    fn target_face(&self) -> &Self::Simplex;
}

/// A free abelian group generated by k-simplices (the k-th chain group C_k).
pub trait ChainGroup<P: Primitives> {
    /// The degree k of this chain group (the dimension of its generating simplices).
    fn degree(&self) -> P::Integer;
    /// Associated type for `Simplex`.
    type Simplex: Simplex<P>;
    /// A simplex that generates this chain group.
    fn generated_by(&self) -> &[Self::Simplex];
}

/// The boundary operator ∂_k: C_k → C_{k-1}. Satisfies ∂² = 0.
pub trait BoundaryOperator<P: Primitives> {
    /// Associated type for `ChainGroup`.
    type ChainGroup: ChainGroup<P>;
    /// The source chain group C_k of this boundary operator.
    fn source_group(&self) -> &Self::ChainGroup;
    /// The target chain group C_{k-1} of this boundary operator.
    fn target_group(&self) -> &Self::ChainGroup;
    /// Whether this boundary operator satisfies the fundamental property ∂² = 0.
    fn satisfies_boundary_squared_zero(&self) -> P::Boolean;
}

/// A chain complex: a sequence of chain groups connected by boundary operators.
pub trait ChainComplex<P: Primitives> {
    /// Associated type for `ChainGroup`.
    type ChainGroup: ChainGroup<P>;
    /// A chain group belonging to this chain complex.
    fn has_chain_group(&self) -> &[Self::ChainGroup];
    /// Associated type for `BoundaryOperator`.
    type BoundaryOperator: BoundaryOperator<P>;
    /// A boundary operator belonging to this chain complex.
    fn has_boundary(&self) -> &[Self::BoundaryOperator];
}

/// The k-th homology group H_k = ker(∂_k) / im(∂_{k+1}). Measures k-dimensional holes.
pub trait HomologyGroup<P: Primitives> {
    /// The degree k of this homology group H_k.
    fn homology_degree(&self) -> P::Integer;
    /// The Betti number β_k = rank(H_k): the rank of this homology group.
    fn betti_number(&self) -> P::NonNegativeInteger;
}

/// The nerve functor N: maps a set of constraints to a simplicial complex.
pub trait NerveFunctor<P: Primitives> {}

/// The chain functor C: maps a simplicial complex to a chain complex.
pub trait ChainFunctor<P: Primitives> {}

/// A simplicial set satisfying the Kan extension condition. The constraint nerve, when promoted from a SimplicialComplex to a KanComplex, carries a full homotopy type — not just its homology groups.
pub trait KanComplex<P: Primitives>: SimplicialComplex<P> {
    /// Associated type for `HornFiller`.
    type HornFiller: HornFiller<P>;
    /// A horn filler witnessing the Kan condition for this complex.
    fn kan_witness(&self) -> &[Self::HornFiller];
}

/// A witness that a given horn (an incomplete simplex boundary) can be filled, certifying the Kan condition at a specific dimension and position.
pub trait HornFiller<P: Primitives> {
    /// The dimension of the horn that this filler completes.
    fn horn_dimension(&self) -> P::NonNegativeInteger;
    /// The position (missing face index) of the horn that this filler completes.
    fn horn_position(&self) -> P::NonNegativeInteger;
}

/// The k-th Postnikov truncation τ≤k of the constraint nerve: a KanComplex whose homotopy groups πj vanish for j > k.
pub trait PostnikovTruncation<P: Primitives> {
    /// The truncation level k of this Postnikov truncation τ≤k.
    fn truncation_level(&self) -> P::NonNegativeInteger;
    /// Associated type for `KanComplex`.
    type KanComplex: KanComplex<P>;
    /// The KanComplex from which this Postnikov truncation is derived.
    fn truncation_source(&self) -> &Self::KanComplex;
    /// Associated type for `KInvariant`.
    type KInvariant: KInvariant<P>;
    /// The k-invariant classifying the extension at this truncation level.
    fn k_invariant(&self) -> &Self::KInvariant;
}

/// The k-invariant κk that classifies the extension from the (k−1)-truncation to the k-truncation of the Postnikov tower. Trivial κk means the truncation splits as a product.
pub trait KInvariant<P: Primitives> {
    /// True iff this k-invariant is trivial, meaning the Postnikov truncation splits as a product.
    fn k_invariant_trivial(&self) -> P::Boolean;
}

/// The deformation complex of a CompleteType T: a chain complex whose H⁰ = automorphisms, H¹ = first-order deformations, H² = obstructions to extending deformations.
pub trait DeformationComplex<P: Primitives>: ChainComplex<P> {
    /// Associated type for `CompleteType`.
    type CompleteType: crate::user::type_::CompleteType<P>;
    /// The CompleteType whose deformation complex this is.
    fn deformation_base(&self) -> &Self::CompleteType;
    /// The dimension of the tangent space H¹(Def(T)): the number of first-order deformations.
    fn tangent_dimension(&self) -> P::NonNegativeInteger;
    /// The dimension of the obstruction space H²(Def(T)): the number of independent obstructions to extending deformations.
    fn obstruction_dimension(&self) -> P::NonNegativeInteger;
}

/// ∂² = 0: the boundary of a boundary is zero.
pub mod boundary_squared_zero {
    /// `forAll`
    pub const FOR_ALL: &str = "c ∈ C_{k+1}";
    /// `lhs`
    pub const LHS: &str = "∂_k(∂_{k+1}(c))";
    /// `rhs`
    pub const RHS: &str = "0";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "ChainComplex → BoundaryOperator → ∂² = 0";
}

/// The nerve functor N: constraints → simplicial complex.
pub mod nerve_functor_n {}

/// The chain functor C: simplicial complex → chain complex.
pub mod chain_functor_c {}

/// ψ_4: HomologyGroups → BettiNumbers (extraction functor).
pub mod psi_4 {
    /// `forAll`
    pub const FOR_ALL: &str = "simplicial complex K";
    /// `lhs`
    pub const LHS: &str = "β_k(K)";
    /// `rhs`
    pub const RHS: &str = "rank(H_k(K))";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str = "HomologyGroup → rank → BettiNumber";
}

/// Index bridge: connects Euler characteristic to alternating Betti sum.
pub mod index_bridge {
    /// `forAll`
    pub const FOR_ALL: &str = "finite simplicial complex K";
    /// `lhs`
    pub const LHS: &str = "χ(K)";
    /// `rhs`
    pub const RHS: &str = "Σ_k (-1)^k β_k";
    /// `verificationDomain` -> `Topological`
    pub const VERIFICATION_DOMAIN: &str = "https://uor.foundation/op/Topological";
    /// `verificationPathNote`
    pub const VERIFICATION_PATH_NOTE: &str =
        "SimplicialComplex → ChainComplex → HomologyGroup → BettiNumber → alternating sum";
}