amari-functional

Functional analysis on multivector spaces - Hilbert spaces, linear operators, spectral theory, and Sobolev spaces for Clifford algebras.

Overview

amari-functional provides the mathematical foundations of functional analysis applied to Clifford algebra-valued function spaces. The crate implements the complete hierarchy from vector spaces to Hilbert spaces, bounded linear operators with spectral decomposition, and Sobolev spaces for weak derivatives.

Features

• Space Hierarchy: VectorSpace → NormedSpace → BanachSpace → InnerProductSpace → HilbertSpace
• Finite-Dimensional Hilbert Spaces: Cl(P,Q,R) as 2^(P+Q+R)-dimensional Hilbert spaces
• L² Function Spaces: Square-integrable multivector-valued functions
• Linear Operators: Bounded, compact, self-adjoint, and Fredholm operators
• Matrix Operators: Explicit matrix representations with composition and norms
• Spectral Theory: Eigenvalue computation, spectral decomposition, functional calculus
• Eigenvalue Algorithms: Power method, inverse iteration, Jacobi algorithm
• Sobolev Spaces: H^k spaces with weak derivatives and Poincaré inequalities
• Phantom Types: Compile-time verification of operator properties
• Formal Verification: Optional Creusot contracts for theorem verification

Installation

Add to your Cargo.toml:

[dependencies]
amari-functional = "0.14"

Feature Flags

[dependencies]
# Default features
amari-functional = "0.14"

# With parallel computation (Rayon)
amari-functional = { version = "0.14", features = ["parallel"] }

# With formal verification (Creusot)
amari-functional = { version = "0.14", features = ["formal-verification"] }

Quick Start

Hilbert Space Operations

use amari_functional::space::{MultivectorHilbertSpace, HilbertSpace, InnerProductSpace};

// Create the Hilbert space Cl(2,0,0) ≅ ℝ⁴
let space: MultivectorHilbertSpace<2, 0, 0> = MultivectorHilbertSpace::new();

// Create elements: 1 + 2e₁ and 3e₂ + 4e₁₂
let x = space.from_coefficients(&[1.0, 2.0, 0.0, 0.0]).unwrap();
let y = space.from_coefficients(&[0.0, 0.0, 3.0, 4.0]).unwrap();

// Inner product (these are orthogonal)
let ip = space.inner_product(&x, &y);
assert!(ip.abs() < 1e-10);

// Norm and distance
let norm_x = space.norm(&x);
let dist = space.distance(&x, &y);

// Orthogonal projection
let proj = space.project(&x, &y);

// Gram-Schmidt orthonormalization
let basis = space.basis();
let orthonormal = space.gram_schmidt(&basis);

Matrix Operators

use amari_functional::operator::{MatrixOperator, LinearOperator, BoundedOperator};
use amari_core::Multivector;

// Identity operator
let id: MatrixOperator<2, 0, 0> = MatrixOperator::identity();

// Diagonal operator
let diag = MatrixOperator::<2, 0, 0>::diagonal(&[4.0, 3.0, 2.0, 1.0]).unwrap();

// Apply to a vector
let x = Multivector::<2, 0, 0>::from_slice(&[1.0, 1.0, 1.0, 1.0]);
let result = diag.apply(&x).unwrap();
// result = [4, 3, 2, 1]

// Operator composition
let composed = diag.multiply(&id).unwrap();

// Operator norm ||T||
let norm = diag.operator_norm();

// Check symmetry (self-adjointness)
assert!(diag.is_symmetric(1e-10));

Spectral Decomposition

use amari_functional::operator::MatrixOperator;
use amari_functional::spectral::{spectral_decompose, SpectralDecomposition};

// Create a symmetric positive-definite matrix
let matrix = MatrixOperator::<2, 0, 0>::diagonal(&[4.0, 3.0, 2.0, 1.0]).unwrap();

// Compute spectral decomposition: T = Σᵢ λᵢ Pᵢ
let decomp = spectral_decompose(&matrix, 100, 1e-10).unwrap();

// Get eigenvalues
let eigenvalues = decomp.eigenvalues();
// [4.0, 3.0, 2.0, 1.0]

// Spectral properties
let radius = decomp.spectral_radius();      // 4.0
let cond = decomp.condition_number();       // Some(4.0)
let pos_def = decomp.is_positive_definite(); // true

// Functional calculus: apply f(T) = √T
let x = Multivector::<2, 0, 0>::from_slice(&[1.0, 0.0, 0.0, 0.0]);
let sqrt_Tx = decomp.apply_function(|lambda| lambda.sqrt(), &x);
// √T · e₀ = 2 · e₀

Eigenvalue Algorithms

use amari_functional::operator::MatrixOperator;
use amari_functional::spectral::{power_method, inverse_iteration, compute_eigenvalues};

let matrix = MatrixOperator::<2, 0, 0>::diagonal(&[4.0, 3.0, 2.0, 1.0]).unwrap();

// Power method: find dominant eigenvalue
let dominant = power_method(&matrix, None, 100, 1e-10).unwrap();
// dominant.eigenvalue.value ≈ 4.0

// Inverse iteration: find eigenvalue near a shift
let near_2 = inverse_iteration(&matrix, 2.1, None, 100, 1e-10).unwrap();
// near_2.eigenvalue.value ≈ 2.0

// Jacobi algorithm: all eigenvalues
let all_eigs = compute_eigenvalues(&matrix, 100, 1e-10).unwrap();
// [4.0, 3.0, 2.0, 1.0]

Sobolev Spaces

use amari_functional::sobolev::{SobolevSpace, SobolevFunction, H1Space, poincare_constant_estimate};
use amari_functional::space::Domain;
use amari_core::Multivector;
use std::sync::Arc;

// Create H¹([0,1], Cl(2,0,0))
let h1: H1Space<2, 0, 0> = H1Space::unit_interval().with_quadrature_points(64);

// Define f(x) = x with f'(x) = 1
let f: SobolevFunction<2, 0, 0, 1> = SobolevFunction::new(
    |x| Multivector::<2, 0, 0>::scalar(x[0]),
    vec![Arc::new(|_x| Multivector::<2, 0, 0>::scalar(1.0))],
    1,
);

// Compute H¹ norm: ||f||²_{H¹} = ||f||²_{L²} + ||f'||²_{L²}
let h1_norm = h1.hk_norm(&f);
// ≈ √(1/3 + 1) = √(4/3) ≈ 1.155

// H¹ seminorm: |f|_{H¹} = ||f'||_{L²}
let seminorm = h1.hk_seminorm(&f);
// ≈ 1.0

// Poincaré constant for [0,1]: C = 1/π
let domain = Domain::interval(0.0, 1.0);
let poincare = poincare_constant_estimate(&domain);
// ≈ 0.318

L² Function Spaces

use amari_functional::space::{MultivectorL2, L2Function, NormedSpace, InnerProductSpace};
use amari_core::Multivector;

// Create L²([0,1], Cl(2,0,0))
let l2: MultivectorL2<2, 0, 0> = MultivectorL2::unit_interval();

// Define f(x) = x · e₀
let f = L2Function::new(|x| Multivector::<2, 0, 0>::scalar(x[0]));

// Define g(x) = (1-x) · e₀
let g = L2Function::new(|x| Multivector::<2, 0, 0>::scalar(1.0 - x[0]));

// L² norm: ||f||² = ∫₀¹ x² dx = 1/3
let norm = l2.norm(&f);
// ≈ √(1/3) ≈ 0.577

// L² inner product: ⟨f,g⟩ = ∫₀¹ x(1-x) dx = 1/6
let ip = l2.inner_product(&f, &g);
// ≈ 0.167

Mathematical Background

Space Hierarchy

The crate implements the standard functional analysis hierarchy:

VectorSpace         - Linear structure with addition and scalar multiplication
    ↓
NormedSpace         - Adds norm ||·|| satisfying triangle inequality
    ↓
BanachSpace         - Complete normed space (Cauchy sequences converge)
    ↓
InnerProductSpace   - Adds inner product ⟨·,·⟩ with ||x||² = ⟨x,x⟩
    ↓
HilbertSpace        - Complete inner product space

Clifford Algebra Hilbert Spaces

The Clifford algebra Cl(P,Q,R) is a 2^(P+Q+R)-dimensional real vector space equipped with the standard L² inner product on coefficients:

⟨x, y⟩ = Σᵢ xᵢ yᵢ

This makes Cl(P,Q,R) into a finite-dimensional Hilbert space isomorphic to ℝ^(2^(P+Q+R)).

Spectral Theorem

For a self-adjoint (symmetric) operator T on a finite-dimensional Hilbert space:

T = Σᵢ λᵢ Pᵢ

where λᵢ are real eigenvalues and Pᵢ are orthogonal projections onto eigenspaces.

Functional Calculus

For any function f: ℝ → ℝ, the operator f(T) is defined via spectral decomposition:

f(T) = Σᵢ f(λᵢ) Pᵢ

This enables computing matrix exponentials, square roots, logarithms, etc.

Sobolev Spaces

The Sobolev space W^{k,p}(Ω, V) consists of functions f: Ω → V with weak derivatives up to order k in L^p. For p = 2, these are Hilbert spaces (H^k) with inner product:

⟨f, g⟩{H^k} = Σ{|α| ≤ k} ∫_Ω ⟨D^α f, D^α g⟩ dx

Poincaré Inequality

For functions with zero boundary conditions on a bounded domain Ω:

||f||{L²} ≤ C ||∇f||{L²}

The Poincaré constant C depends on the domain geometry (C = diam(Ω)/π for intervals).

Modules

Phantom Types

The crate uses phantom types for compile-time verification of operator properties:

use amari_functional::phantom::{
    Bounded, Unbounded,           // Boundedness
    Compact, NonCompact,          // Compactness
    SelfAdjoint, Normal, Unitary, // Symmetry
    Fredholm, SemiFredholm,       // Fredholm property
    DiscreteSpectrum, ContinuousSpectrum, // Spectral type
};

// Type aliases for common operator types
use amari_functional::phantom::{
    CompactSelfAdjointOperator,
    HilbertSchmidtOperator,
    UnitaryOperator,
};

Applications

Quantum Mechanics

use amari_functional::operator::MatrixOperator;
use amari_functional::spectral::spectral_decompose;
use amari_functional::space::{MultivectorHilbertSpace, InnerProductSpace};

// Hamiltonian with energy levels 0, 1, 2, 3
let hamiltonian = MatrixOperator::<2, 0, 0>::diagonal(&[0.0, 1.0, 2.0, 3.0]).unwrap();

// Spectral decomposition for energy eigenstates
let spectral = spectral_decompose(&hamiltonian, 100, 1e-10).unwrap();

// Initial superposition state
let space = MultivectorHilbertSpace::<2, 0, 0>::new();
let psi = space.normalize(
    &space.from_coefficients(&[1.0, 1.0, 0.0, 0.0]).unwrap()
).unwrap();

// Expected energy ⟨ψ|H|ψ⟩
let h_psi = hamiltonian.apply(&psi).unwrap();
let expected_energy = space.inner_product(&psi, &h_psi);

// Time evolution: |ψ(t)⟩ = e^{-iHt}|ψ(0)⟩
let t = 1.0;
let evolved = spectral.apply_function(|E| (-E * t).exp(), &psi);

Numerical PDEs

Sobolev spaces provide the natural setting for weak solutions to PDEs:

use amari_functional::sobolev::{H1Space, SobolevFunction, poincare_constant_estimate};
use amari_functional::space::Domain;

// H¹₀(Ω) for variational formulations
let h1 = H1Space::<2, 0, 0>::new(Domain::interval(0.0, 1.0));

// Poincaré inequality: ||u||_{L²} ≤ C ||∇u||_{L²}
let domain = Domain::interval(0.0, 1.0);
let poincare = poincare_constant_estimate(&domain);

// Energy norm for elliptic problems
// ||u||_a² = ∫ a(x)|∇u|² dx

Signal Processing

Hilbert space projections for signal approximation:

use amari_functional::space::{MultivectorHilbertSpace, HilbertSpace, InnerProductSpace};

let space = MultivectorHilbertSpace::<2, 0, 0>::new();

// Signal in the Hilbert space
let signal = space.from_coefficients(&[1.0, 2.0, 3.0, 4.0]).unwrap();

// Basis for approximation subspace
let e0 = space.basis_vector(0).unwrap();
let e1 = space.basis_vector(1).unwrap();

// Best approximation in subspace
let approx = space.best_approximation(&signal, &[e0, e1]);
// Projection onto span{e₀, e₁}

Machine Learning

Kernel methods and reproducing kernel Hilbert spaces:

use amari_functional::operator::MatrixOperator;
use amari_functional::spectral::spectral_decompose;

// Kernel matrix (Gram matrix)
let kernel = MatrixOperator::<2, 0, 0>::diagonal(&[4.0, 3.0, 2.0, 1.0]).unwrap();

// Spectral decomposition for kernel PCA
let decomp = spectral_decompose(&kernel, 100, 1e-10).unwrap();

// Leading eigenvalues capture most variance
let eigenvalues = decomp.eigenvalues();
let total_variance: f64 = eigenvalues.iter().map(|e| e.value).sum();
let top_2_variance: f64 = eigenvalues.iter().take(2).map(|e| e.value).sum();
let explained_ratio = top_2_variance / total_variance;

Error Handling

The crate provides comprehensive error types:

use amari_functional::{FunctionalError, Result};

// Dimension mismatch
let err = FunctionalError::dimension_mismatch(4, 5);

// Convergence failure
let err = FunctionalError::convergence_error(100, "Power method did not converge");

// Invalid parameters
let err = FunctionalError::invalid_parameters("Matrix must be symmetric");

// Singular operator
let err = FunctionalError::singular_operator();

Performance

• Finite-dimensional operations: O(n²) for matrix-vector, O(n³) for eigenvalue computation
• Numerical integration: Configurable quadrature points for accuracy/speed tradeoff
• Parallel support: Enable parallel feature for Rayon-based parallelism

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

Part of Amari

This crate is part of the Amari mathematical computing library, providing:

• amari-core: Clifford algebra fundamentals
• amari-measure: Measure theory and integration
• amari-calculus: Differential geometry and manifolds
• amari-functional: Functional analysis (this crate)
• amari-info-geom: Information geometry
• And many more...

References

• Reed, M. & Simon, B. Methods of Modern Mathematical Physics (1980)
• Conway, J.B. A Course in Functional Analysis (1990)
• Hestenes, D. & Sobczyk, G. Clifford Algebra to Geometric Calculus (1984)
• Adams, R.A. Sobolev Spaces (1975)