Math Explorer

Math Explorer is a comprehensive Rust library that bridges the gap between rigorous academic theory and executable code. From simulating Quantum Mechanics to modeling Social Favoritism, this repository serves as a verifiable playground for complex algorithms.

"Code explains HOW; Docs explain WHY."

---

⚡ Quickstart (30 Seconds)

Get up and running immediately.

1. Install

Add math_explorer to your project (or clone the repo):

git clone https://github.com/fderuiter/math-explorer.git
cd math-explorer/math_explorer
cargo build --release

2. Run "Hello World" (Quantum Physics)

Calculate Clebsch-Gordan coefficients for angular momentum coupling:

use math_explorer::physics::quantum::clebsch_gordan;

fn main() {
    // Coupling j1=1.5, m1=-0.5 with j2=1.0, m2=1.0 to J=2.5, M=0.5
    let coeff = clebsch_gordan(1.5, -0.5, 1.0, 1.0, 2.5, 0.5);
    println!("Clebsch-Gordan Coefficient: {:.4}", coeff);
}

---

📚 Table of Contents

• Features
• Deep Dive: Modules
• Testing
• Contributing
• License

🚀 Features

Math Explorer is organized into high-level domains, each solving specific problems:

graph TD
    Root[Math Explorer] --> AI[🤖 AI]
    Root --> Applied[🛠️ Applied]
    Root --> Bio[🧬 Biology]
    Root --> Climate[🌍 Climate]
    Root --> Epi[🦠 Epidemiology]
    Root --> Phys[🌌 Physics]
    Root --> Pure[📐 Pure Math]

    AI --> Trans[Transformers] & NeRF[NeRF-Diffusion]
    Applied --> Fav[Favoritism] & Clinical[Clinical Trials]
    Bio --> Neuro[Neuroscience] & Morph[Morphogenesis]
    Epi --> SIR[SIR/SEIR Models] & Net[Network Spread]
    Phys --> Quant[Quantum] & Chaos[Chaos Theory]
    Pure --> Num[Number Theory] & Geo[Diff Geometry]

    style Root fill:#f9f,stroke:#333,stroke-width:2px

Loading

Domain	Module	Description
🤖 AI	math_explorer::ai	Transformers (Attention, Encoders), NeRF-Diffusion (SDS), and Self-Calibration loops.
🛠️ Applied	math_explorer::applied	Favoritism (Satirical modeling), Clinical Trials (Win Ratio), and LoraHub.
🧬 Biology	math_explorer::biology	Neuroscience (Hodgkin-Huxley), Morphogenesis (Turing Patterns), and Evolutionary Dynamics.
🌍 Climate	math_explorer::climate	CERA Framework (Climate-invariant Encoding through Representation Alignment).
🦠 Epidemiology	math_explorer::epidemiology	Compartmental Models (SIR/SEIR), Network Spread, and Stochastic Dynamics.
🌌 Physics	math_explorer::physics	Quantum Mechanics (Clebsch-Gordan), Astrophysics, Chaos Theory (Lorenz System), and Fluid Dynamics.
📐 Pure Math	math_explorer::pure_math	Number Theory (Partitions), Graph Theory, and Differential Geometry.

---

🔍 Deep Dive: Modules

🧬 Biology & Neuroscience

Simulate the electrical characteristics of excitable cells using the Hodgkin-Huxley model.

use math_explorer::biology::neuroscience::HodgkinHuxleyNeuron;

// Initialize a neuron at resting potential (-65.0 mV)
let mut neuron = HodgkinHuxleyNeuron::new(-65.0);
let dt = 0.01; // 0.01 ms time step

// Simulate for 10ms with 10 uA/cm^2 current injection
for _ in 0..1000 {
    neuron.update(dt, 10.0);
    if neuron.v > 0.0 {
        println!("Action Potential Generated!");
        break;
    }
}

🤖 Artificial Intelligence

Implement state-of-the-art architectures from scratch.

Example: Transformer Encoder

use math_explorer::ai::transformer::Encoder;
use nalgebra::DMatrix;

// Initialize an Encoder stack: 2 layers, 512 embedding dim, 8 heads, 2048 FF dim
let encoder = Encoder::new(2, 512, 8, 2048);

// Dummy input: Sequence length 10
let input = DMatrix::zeros(10, 512);
let encoded = encoder.forward(input, None);

🛠️ Applied Mathematics: Favoritism

A "rigorous" mathematical model to determine who the favorite child is.

use math_explorer::applied::favoritism::{FavoritismInputs, calculate_favoritism_score};

let mut inputs = FavoritismInputs::default();
inputs.personality.wealth = 10.0;          // High wealth factor
inputs.social.helped_during_crisis = true; // High social utility

let score = calculate_favoritism_score(&inputs);
println!("Favoritism Score: {}", score); // Higher is better

🌌 Physics: Chaos Theory

Explore the Lorenz System and Lyapunov exponents.

(See math_explorer/src/physics/chaos/mod.rs for implementation details)

---

🧪 Testing

We rely on standard Rust testing frameworks. To verify the integrity of all mathematical implementations:

cd math_explorer
cargo test

This runs unit tests for everything from Prime Number generation to NeRF rendering logic.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for our style guide and process.

The Golden Rule: If you add code, you must add documentation and tests.

📄 License

This project is open-source. See the LICENSE file for details.