Atoms_Rust

Hydrogen Quantum Orbital Visualizer
Real-time 3D visualization of atomic orbitals in Rust

Features • Quick Start • Documentation • Physics • Contributing

---

Overview

Atoms_Rust is a high-performance Rust port of the Atoms_C++ project, providing interactive 3D visualization of hydrogen atomic orbitals. Built with macroquad for cross-platform rendering, it supports real-time visualization of 100,000+ particles with probability current flow animation.

graph TB
    subgraph "🎮 User Interface"
        UI[Interactive Controls<br/>W/S E/D R/F T/G]
        CAM[Orbit Camera<br/>Mouse Drag + Scroll]
        FPS[FPS & Status Display]
    end

    subgraph "🔬 Visualization Modes"
        R3D[3D Realtime<br/>100k-2M particles]
        RAY[Raytracer<br/>GPU Lighting & Shadows]
        A2D[2D Atom Sim<br/>Wave-Particle Physics]
        W2D[Wave 2D<br/>Energy Level Viz]
    end

    subgraph "⚙️ Core Engine"
        PHYS[Physics Module<br/>Laguerre & Legendre]
        REND[Render Module<br/>Shaders & Batches]
        SAMPL[Sampler<br/>CDF-based Sampling]
    end

    UI --> R3D
    UI --> RAY
    UI --> A2D
    UI --> W2D
    CAM --> R3D
    CAM --> RAY
    R3D --> PHYS
    RAY --> PHYS
    A2D --> PHYS
    W2D --> PHYS
    PHYS --> SAMPL
    R3D --> REND
    RAY --> REND

Loading

---

Features

Feature	Description
🌟 Real-time 3D	Interactive rendering of hydrogen orbital probability clouds
🌊 Probability Flow	Animated probability current for orbitals with m ≠ 0
🎨 Inferno Colormap	Professional scientific visualization colors
⚡ High Performance	Parallel processing with rayon, 60 FPS with 100k particles
🖥️ Cross-platform	Windows, Linux, macOS, and WebAssembly support
📊 Multiple Modes	4 visualization binaries for different use cases

---

Quick Start

# Clone and enter the repository
git clone https://github.com/your-repo/Atoms.git
cd Atoms/Atoms_Rust

# Run the 3D realtime visualizer (recommended first)
cargo run --bin realtime --release

# Other visualization modes
cargo run --bin raytracer --release    # GPU raytracing
cargo run --bin atom_2d --release      # 2D atom simulation
cargo run --bin wave_2d --release      # 2D wave visualization

📖 Platform-specific prerequisites

Linux

sudo apt install build-essential pkg-config libasound2-dev libssl-dev \
    libfreetype6-dev libexpat1-dev libxcb1-dev libgl1-mesa-dev

macOS

xcode-select --install

Windows

Install Visual Studio Build Tools with C++ development.

---

Visualization Modes

Binary	Description	Particles	Use Case
realtime	3D probability cloud with flow animation	100k-2M	Interactive exploration
raytracer	GPU point sprites with realistic lighting	1k-50k	High-quality rendering
atom_2d	Multi-atom Bohr model with wave physics	20 atoms	Understanding transitions
wave_2d	Electron wave function visualization	1 electron	Energy level education

---

Controls

3D Visualizers (realtime, raytracer)

Key	Action
W / S	Increase / Decrease principal quantum number n
E / D	Increase / Decrease angular momentum l
R / F	Increase / Decrease magnetic quantum number m
T / G	Add / Remove 100k particles
Space	Pause / Resume animation
Escape	Reset camera position
🖱️ Drag	Orbit camera around origin
🖱️ Scroll	Zoom in / out

2D Simulations (atom_2d, wave_2d)

Key / Action	Effect
W / S	Fine energy adjustment (±0.01 eV)
E / D	Medium energy adjustment (±0.1 eV)
R / F	Coarse energy adjustment (±1.0 eV)
Space	Pause / Resume
R / Escape	Reset simulation
🖱️ Click	Spawn energy waves (atom_2d only)

---

Physics

The visualization is based on the hydrogen wave function:

$$\psi_{nlm}(r,\theta,\phi) = R_{nl}(r) \cdot Y_l^m(\theta,\phi)$$

Radial Wave Function

$$R_{nl}(r) = \sqrt{\left(\frac{2}{na_0}\right)^3 \frac{(n-l-1)!}{2n[(n+l)!]}} e^{-\rho/2} \rho^l L_{n-l-1}^{2l+1}(\rho)$$

Where $L_k^\alpha$ are associated Laguerre polynomials and $\rho = \frac{2r}{na_0}$.

Probability Sampling

Particles are sampled from the probability density $|\psi|^2$ using CDF inversion:

flowchart LR
    A[Quantum Numbers<br/>n, l, m] --> B[Build CDF Tables]
    B --> C[Sample r]
    C --> D[Sample θ]
    D --> E[Sample φ]
    E --> F[Convert to<br/>Cartesian]
    F --> G[Calculate Color]
    G --> H[Render Particle]
    H --> C

Loading

📖 Full physics derivation: docs/PHYSICS.md

---

Architecture

src/
├── lib.rs                 # Library entry point
├── constants.rs           # Physical constants (a₀, ħ, mₑ)
│
├── physics/               # Quantum mechanics calculations
│   ├── polynomials.rs     # Laguerre & Legendre polynomials
│   ├── sampling.rs        # CDF-based probability sampling
│   └── color.rs           # Inferno colormap implementation
│
├── render/                # Rendering utilities
│   ├── instanced.rs       # Instanced particle rendering
│   └── shaders.rs         # GLSL shader code
│
├── camera/                # Camera controllers
│   └── orbit.rs           # Orbit camera implementation
│
└── bin/                   # Executables
    ├── realtime.rs        # 3D realtime visualizer
    ├── raytracer.rs       # GPU raytracing mode
    ├── atom_2d.rs         # 2D atom simulation
    └── wave_2d.rs         # 2D wave visualization

📖 Detailed architecture: docs/ARCHITECTURE.md

---

Performance

Binary	Target FPS	Particles	Memory
realtime	60	100,000	~200 MB
raytracer	30	10,000	~50 MB
atom_2d	60	20 atoms	~20 MB
wave_2d	60	1 electron	~10 MB

Key optimizations:

• Parallel processing: rayon for multi-core particle updates
• CDF caching: Reuse probability tables between frames
• Pre-allocation: Zero runtime allocations in render loop

📖 Optimization guide: docs/PERFORMANCE.md

---

Documentation

Document	Description
Getting Started	Installation and first run
User Guide	Complete usage documentation
Physics	Quantum mechanics derivation
Architecture	Code structure and design
Performance	Optimization techniques
API Reference	Library documentation

---

Building for Web

# Add WebAssembly target
rustup target add wasm32-unknown-unknown

# Build
cargo build --target wasm32-unknown-unknown --release

See macroquad WASM documentation for HTML setup.

---

Project Structure

Atoms/
├── Atoms_C++/           # Original C++ implementation
│   └── src/
│       ├── atom_realtime.cpp
│       ├── atom_raytracer.cpp
│       ├── atom.cpp
│       └── wave_atom_2d.cpp
│
└── Atoms_Rust/          # Rust port (this project)
    ├── src/
    ├── docs/
    └── examples/

---

Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Code style and conventions
• Pull request process
• Adding new features

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Original Atoms_C++ implementation
• macroquad - Cross-platform game framework
• rayon - Data parallelism library

---

Made with ❤️ for quantum physics education