reefer 0.3.0

//! Traits and re-exports that expose the Clifford algebra runtime used by the procedural macros.
//!
//! The macros primarily operate in terms of these traits so they can reason about multivectors
//! symbolically while keeping the runtime implementation modular. Each trait mirrors familiar
//! geometric-algebra terminology (wedge, inner product, duality, etc.) so learners can correlate
//! the Rust APIs with textbook operations.

use abstalg::Domain;
use mask::Mask;
mod algebra;
mod basis;
mod mask;
mod metric;
mod multivector;
mod scalar;

#[allow(unused_imports)]
pub use algebra::{SynAlgebra, SynBasis, SynMultivector};
#[allow(unused_imports)]
pub use basis::{BasisScalar, BasisSpace, Frame};
#[allow(unused_imports)]
pub use metric::Metric;
pub use scalar::{Scalar, ScalarSpace};

#[allow(dead_code)]
/// Trait capturing analytic operations that are useful when modelling Clifford scalars.
///
/// The runtime can opt into these to provide conveniences such as `exp()` on multivectors, but
/// the macros do not currently rely on them. They are kept here as documentation anchors for
/// future extensions.
pub trait AnalyticOps {
    /// Absolute value.
    fn abs(self) -> Self;
    /// Square root.
    fn sqrt(self) -> Self;
    /// Exponential.
    fn exp(self) -> Self;
    /// Natural logarithm.
    fn ln(self) -> Self;
    /// Sine.
    fn sin(self) -> Self;
    /// Cosine.
    fn cos(self) -> Self;
    /// Hyperbolic sine.
    fn sinh(self) -> Self;
    /// Hyperbolic cosine.
    fn cosh(self) -> Self;
    /// Inverse hyperbolic sine.
    fn asinh(self) -> Self;
    /// Two-argument arctangent.
    fn atan2(self, other: Self) -> Self;
    /// Integer power.
    fn powi(self, exp: i32) -> Self;
}

/// Trait implemented by spaces that can report the grade of a multivector and extract components.
pub trait Graded: Domain {
    type Grade;
    type Output;
    /// Determine the grade(s) present in a multivector.
    fn grade_of(&self, elem: &Self::Elem) -> Self::Grade;
    /// Extract components of a given grade.
    fn grade_by(&self, elem: &Self::Elem, grade: Self::Grade) -> Self::Output;
}

/// Duality operations relating multivectors to their duals with respect to a pseudoscalar.
pub trait Duality: Domain {
    type Psuedo;
    type Output;
    /// Compute the dual using the supplied pseudoscalar.
    fn dual(&self, elem: &Self::Elem, psuedo: &Self::Psuedo) -> Self::Output;
    /// Recover the primal element from its dual.
    fn undual(&self, elem: &Self::Elem, psuedo: &Self::Psuedo) -> Self::Output;
}

/// Standard Clifford involutions describing how multivectors transform under sign/ordering changes.
pub trait Involution: Domain {
    type Output;
    /// **Grade involution (main automorphism)**  
    ///
    /// Flips the sign of all elements of odd grade:
    /// `x̂ = (-1)^{grade(x)} x`.
    ///
    /// This map preserves the geometric product:
    /// `(xy)ˆ = x̂ ŷ`, so it is a true *automorphism* of the algebra.
    /// Applying it twice returns the original multivector (`ˆ(x̂) = x`).
    ///
    /// Geometrically, it corresponds to a parity flip of vectors: every vector
    /// changes sign, while scalars and bivectors remain unchanged. Higher-grade
    /// elements change sign according to their grade parity (odd or even).
    #[must_use]
    fn automorphism(&self, elem: Self::Elem) -> Self::Output;
    // {
    //     let grade = self.grade_of(&elem);
    //     if grade % 2 < 1 { elem } else { self.neg(&elem) }
    // }

    /// **Reversion (transpose, reverse order)**  
    ///
    /// Reverses the order of all vector factors in a product:
    /// `~(a₁ a₂ … aₙ) = aₙ … a₂ a₁`.
    ///
    /// On a homogeneous element of grade *r*, it introduces a sign  
    /// `(-1)^{r(r−1)/2}`. This makes it an *anti-automorphism*:  
    /// `(xy)~ = ~y ~x`.
    ///
    /// Geometrically, it corresponds to reflection of orientation --  
    /// e.g., reversing the orientation of blades and rotors.
    #[must_use]
    fn reverse(&self, elem: Self::Elem) -> Self::Output;
    // {
    //     let grade = self.grade_of(&elem);
    //     if grade % 4 < 2 { elem } else { self.neg(&elem) }
    // }

    /// **Clifford conjugation (combined involution)**  
    ///
    /// Defined as the composition of grade involution and reversion:  
    /// `x† = (x̂)~ = ˆ(~x)`.
    ///
    /// On a homogeneous element of grade *r*, it introduces a sign  
    /// `(-1)^{r(r+1)/2}`. It is also an *anti-automorphism*:  
    /// `(xy)† = y† x†`.
    ///
    /// Geometrically, it behaves like Hermitian conjugation in complex
    /// algebras -- reversing order and flipping the sign of odd grades.
    fn conjugate(&self, elem: Self::Elem) -> Self::Output;
    // {
    //     self.reverse(self.automorphism(elem))
    // }
}

pub trait InnerProduct: Domain {
    type Output;
    /// Compute the inner (dot) product between two multivectors.
    fn inner(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

pub trait ExteriorProduct: Domain {
    type Output;
    /// Compute the outer (wedge) product between two multivectors.
    fn wedge(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

pub trait RegressiveProduct: Domain {
    type Output;
    /// Compute the regressive (meet) product between two multivectors.
    fn antiwedge(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait CommutatorProduct: Domain {
    type Output;
    /// Compute the commutator `lhs rhs - rhs lhs`.
    fn commutate(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait AnticommutatorProduct: Domain {
    type Output;
    /// Compute the anticommutator `lhs rhs + rhs lhs`.
    fn anticommutate(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

pub trait LeftContraction: Domain {
    type Output;
    /// Contract `lhs` onto `rhs`, reducing grade from the left.
    fn contract_onto(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

pub trait RightContraction: Domain {
    type Output;
    /// Contract `lhs` by `rhs`, reducing grade from the right.
    fn contract_by(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait ScalarProduct: Domain {
    type Output;
    /// Compute the scalar product, i.e. grade-0 component of a product.
    fn scalar_product(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait DotProduct: Domain {
    type Output;
    /// Compute the dot product.
    fn dot(&self, lhs: &Self::Elem, rhs: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait Divisibility: Domain {
    /// Determine whether `lhs` divides `rhs` in the algebra.
    fn try_div(&self, _elem1: &Self::Elem, _elem2: &Self::Elem) -> Option<Self::Elem>;
}

#[allow(dead_code)]
pub trait Positivity: Domain {
    /// Check whether a multivector represents a positive element under the algebra's metric.
    fn is_positive(&self, elem: &Self::Elem) -> bool;
}

#[allow(dead_code)]
pub trait SquareRoot: Domain {
    type Output;
    /// Compute a multivector square root.
    fn sqrt(&self, elem: &Self::Elem) -> Self::Output;
}

#[allow(dead_code)]
pub trait Exponential: Domain {
    type Output;
    /// Compute the multivector exponential.
    fn exp(&self, elem: &Self::Elem) -> Self::Output;
    /// Compute the multivector natural logarithm.
    fn ln(&self, elem: &Self::Elem) -> Self::Output;
}
#[allow(dead_code)]
pub trait GeometricProducts:
    InnerProduct
    + ExteriorProduct
    + RegressiveProduct
    + CommutatorProduct
    + AnticommutatorProduct
    + LeftContraction
    + RightContraction
    + ScalarProduct
    + DotProduct
    + Sized
{
}
#[allow(dead_code)]
pub trait CliffordAlgebra:
    Domain + Graded + Duality + Involution + GeometricProducts + Divisibility + Exponential
{
}