ppflib 0.1.0

Advanced computational library for Physics-Prime Factorization (PPF): quantum mechanics through number theory, featuring Sign Prime (-1), state space collapse, topological analysis, and IOT geometric realizations
Documentation

ppflib - Physics-Prime Factorization Library

Crates.io Documentation License

A comprehensive Rust library implementing the Physics-Prime Factorization (PPF) mathematical framework for exploring quantum mechanics through number theory.

Overview

The PPF framework extends classical number theory by treating -1 as a special "Sign Prime", creating multiple valid factorizations for integers and enabling a number-theoretic model of quantum phenomena. This library provides a complete implementation with algebraic, topological, and geometric realizations.

Key Features

  • Factorization State Spaces: Complete enumeration of valid P-factorizations S(n)
  • Quantum Collapse: Modeling (-a) × (-b) = ab transitions
  • Sign Prime: The unique negative prime (-1) enabling quantum behavior
  • Algebraic Structures: State space ideals, P-prime spectrum, homological algebra
  • Topological Analysis: Simplicial complexes, Galois groups, Betti numbers
  • Geometric Realizations: IOT metric, tautochrone operators, Hilbert spaces

Quick Start

Add this to your Cargo.toml:

[dependencies]
ppflib = "0.1.0"

Basic Usage

use ppflib::prelude::*;

fn main() -> Result<(), FactorizationError> {
    // Create factorization state spaces
    let classical = FactorizationStateSpace::new(6)?;     // S(6) - classical state
    let quantum = FactorizationStateSpace::new(-6)?;    // S(-6) - quantum state

    println!("S(6) has {} factorizations", classical.size());
    println!("S(-6) has {} factorizations", quantum.size());

    // Demonstrate quantum collapse: (-2) × (-3) = 6
    let s_neg2 = FactorizationStateSpace::new(-2)?;
    let s_neg3 = FactorizationStateSpace::new(-3)?;
    let result = StateSpaceOperations::multiply(&s_neg2, &s_neg3)?;

    if result.collapse_info.collapsed {
        println!("✓ Quantum collapse: (-2) × (-3) → 6");
        println!("Collapse ratio: {:.2}", result.collapse_info.collapse_ratio);
    }

    Ok(())
}

Core Concepts

Factorization State Spaces

Every integer n has a state space S(n) containing all valid P-factorizations:

use ppflib::prelude::*;

let s6 = FactorizationStateSpace::new(6)?;
for factorization in s6.factorizations() {
    println!("{}", factorization); // "2 × 3", "-2 × -3"
}

// Negative integers create quantum state spaces
let s_neg6 = FactorizationStateSpace::new(-6)?;
for factorization in s_neg6.factorizations() {
    println!("{}", factorization); // "-1 × 2 × 3", "-2 × 3", "2 × -3"
}

Quantum Collapse

When two quantum states multiply, they can collapse to classical states:

let s_neg2 = FactorizationStateSpace::new(-2)?;  // Quantum state
let s_neg3 = FactorizationStateSpace::new(-3)?;  // Quantum state
let result = StateSpaceOperations::multiply(&s_neg2, &s_neg3)?;

// Result is S(6) - a classical state!
assert!(result.collapse_info.collapsed);
assert_eq!(result.result_space.value(), 6);

Examples

1. Basic Factorization and Quantum Collapse

See the complete quantum collapse demonstration:

cargo run --example 01_basic_factorization

This example shows:

  • Creating classical vs quantum state spaces
  • Observing quantum collapse during multiplication
  • Analyzing the Sign Prime (-1)
  • Understanding factorization properties

2. Algebraic Structures

Explore the rich algebraic framework:

cargo run --example 02_algebraic_structures

Features demonstrated:

  • State space ideals IS(n)
  • P-prime spectrum analysis
  • Multiplication algebra
  • Homological structures

3. Topological Analysis

Dive into topological properties:

cargo run --example 03_topological_analysis

Includes:

  • Factorization simplicial complexes K(n)
  • Galois groups Gal_P(n) ≅ (ℤ₂)^(k-1)
  • Betti numbers and Euler characteristics
  • Toroidal topology verification (χ = 0)

4. Geometric Structures

Experience the geometric realization:

cargo run --example 04_geometric_structures

Showcases:

  • IOT (Involuted Oblate Toroidal) metric with critical ratio r/R = 1/30
  • Tautochrone operators and geodesics
  • PPF Hilbert space with complexity-based inner product
  • Quantum operators and state evolution

5. Comprehensive Demo

See everything working together:

cargo run --example 05_comprehensive_demo

Mathematical Framework

The Sign Prime

PPF introduces -1 as a "Sign Prime", creating quantum behavior in number theory:

  • Classical states: S(n) for n > 0 (limited factorizations)
  • Quantum states: S(-n) for n > 0 (expanded factorizations via sign prime)
  • Quantum collapse: (-a) × (-b) = ab (quantum → classical transition)

IOT Geometry

The IOT (Involuted Oblate Toroidal) metric provides geometric realization:

  • Critical ratio: r/R = 1/30 (derived from variational principle)
  • Toroidal embedding of factorization spaces
  • Geodesics and parallel transport
  • Connection to quantum field theory

Topological Structure

Factorization spaces have rich topological properties:

  • Galois groups: Gal_P(n) ≅ (ℤ₂)^(k-1) for k distinct primes
  • Euler characteristic: χ = 0 (toroidal topology)
  • Betti numbers capture dimensional structure
  • Homological algebra connections

API Documentation

Core Module

  • [FactorizationStateSpace]: The fundamental state space S(n)
  • [PFactorization]: Individual P-factorizations
  • [StateSpaceOperations]: Operations between state spaces
  • [CollapseInfo]: Information about quantum collapse events

Algebra Module

  • [StateSpaceIdeal]: Ideals IS(n) in the state space ring
  • [PPrimeSpectrum]: The spectrum of P-primes
  • [MultiplicationAlgebra]: Multiplicative structure
  • [HomologyGroups]: Homological computations

Topology Module

  • [FactorizationSimplex]: Simplicial complex K(n)
  • [PPFGaloisGroup]: Galois group Gal_P(n)
  • [BettiNumberComputer]: Topological invariants
  • [ComplexStatistics]: Complex analysis tools

Geometry Module

  • [IOTMetric]: The IOT metric tensor
  • [TautochroneOperator]: Geodesic and transport operators
  • [PPFHilbertSpace]: Quantum Hilbert space realization
  • [QuantumState]: Quantum states and operators

Research Applications

Machine Learning & NLP

PPF provides novel approaches to ML challenges:

  • Non-differentiable optimization: Use discrete factorization dynamics
  • Latent space topology: IOT-based embeddings with natural toroidal structure
  • Quantum-inspired algorithms: Leverage collapse dynamics for search/optimization
  • Semantic embeddings: Map linguistic structures to factorization spaces

See ideas.md for detailed ML/NLP integration strategies.

GPU Acceleration

Optimized for high-performance computing:

  • WGPU compute shaders: Pure Rust GPU kernels avoiding FFI overhead
  • Bit-parallel operations: Exploit factorization structure for parallelism
  • Lookup table optimizations: Precomputed prime tables and factorizations
  • Workgroup efficiency: Optimized for modern GPU architectures

See ideas2.md for GPU optimization details.

Contributing

Contributions are welcome! Please see our contributing guidelines.

Areas for Contribution

  • Performance optimization: Faster factorization algorithms
  • Documentation: More examples and tutorials
  • GPU kernels: WGPU compute shader implementations
  • ML integrations: TensorFlow/PyTorch bindings
  • Visualization: Tools for exploring state spaces

Mathematical Background

The PPF framework is based on research in:

  • Number Theory: Prime factorization and algebraic structures
  • Algebraic Topology: Simplicial complexes and homology
  • Differential Geometry: Riemannian metrics and geodesics
  • Quantum Mechanics: Hilbert spaces and operator theory
  • Group Theory: Galois groups and symmetries

For detailed mathematical exposition, see the papers in /docs.

Performance

ppflib is designed for performance:

  • Memory efficient: Lazy evaluation and caching strategies
  • Parallel ready: Thread-safe operations where applicable
  • GPU optimized: WGPU compute shader support planned
  • Asymptotic bounds: Theoretical complexity analysis available

Benchmarks coming soon with criterion integration.

License

Licensed under either of

at your option.

Citation

If you use ppflib in academic research, please cite:

@software{ppflib,
  title = {ppflib: Physics-Prime Factorization Library},
  author = {PPF Research Team},
  year = {2024},
  url = {https://github.com/your-org/ppflib},
  version = {0.1.0}
}

Explore the quantum structure hidden in numbers with ppflib! 🔢⚛️