Skip to content

LuminaV Optimizer: Developer Architecture & Engineering Guide

This portal serves as the primary internal technical specification for systems engineers, kernel programmers, and researchers contributing to the LuminaV Optimizer subsystem within the LuminaMoon workspace.

1. Subsystem Architecture & Modularity

The optimizer compute engine is structured as a layered, decoupled system consisting of an outer Python framework interface and a low-level Rust Cargo workspace (optimizer/crates/):

flowchart TD
    PyTorch["PyTorch Tensors (FP32 / BF16 / FP16)"] --> FFI["LuminaV PyO3 abi3t FFI (Zero-Copy)"]
    NumPy["NumPy 2.x Arrays (Buffer Protocol)"] --> FFI
    FFI --> Dispatcher["Runtime Capability Router"]
    Dispatcher --> Triton["Triton AOT/JIT GPU (CUDA / ROCm)"]
    Dispatcher --> Vulkan["Vulkan 1.3/1.4 SPIR-V (UMA, N >= 16,384)"]
    Dispatcher --> SIMD["Rayon CPU SIMD (x86_64, N < 16,384)"]
    Dispatcher --> Scalar["Reference Scalar Core (Fallback)"]
    Triton & Vulkan & SIMD & Scalar --> Math["CLM (2-Buffer) & TD-CLM (1-Buffer) Update"]

2. Directory Navigation & Technical Specs

Module Crate / Path Focus & Core Invariants Spec Document
Core Math luminav-core Analytical CLM/TD-CLM, PCG/XORShift PRNG, bias correction proofs, bounding 01. Core & Math
SIMD Vectorization luminav-simd x86_64 AVX-512 / AVX2 intrinsics, tail masks, Rayon chunking, cache alignment 02. SIMD
Vulkan Compute luminav-vulkan Ash Vulkan 1.3/1.4, SPIR-V shaders, zero-copy UMA host memory, Wave32 subgroups 03. Vulkan
Triton AOT & Drivers luminav-triton-aot AOT compilation, ELF64 magic header validation, dynamic CUDA/HIP drivers, C-API 04. Triton AOT
Hardware Dispatch luminav-dispatch Runtime capability probing (detector.rs), 16,384-element threshold, routing 05. Dispatch
Python FFI Bridge optimizer/src/ PyO3 0.30+, py.detach(), pointer anti-aliasing validation, zero-copy buffers 06. Python FFI
Python Engine & GPU python/luminamoon/ PyTorch/NumPy interop, Triton JIT AST kernels, FSDP collective sync, state dict 07. Python Runtime

3. Developer Invariants & Coding Standards

  1. Memory Safety & Zero-Copy Execution:
  2. Pointers passed across the FFI boundary must be verified for 64-byte or native type alignment.
  3. Pointers are guarded against anti-aliasing: mutable parameter pointers, gradient pointers, and accumulator buffers must never overlap.
  4. Deterministic Stochastic Rounding:
  5. Every parameter maintains a distinct PRNG seed derived via derive_kernel_seeds(base_seed, param_idx, step) to ensure complete reproducibility across threads.
  6. Low-Precision State Integrity:
  7. Single-buffer TD-CLM (Triangle-Defect Convex Lookahead Momentum) uses the triangle inequality envelope \(\mathcal{E}_t = \beta_1^2 |m_{t-1}| + (1 - \beta_1^2) |g_t| + \lambda |g_t - m_{t-1}| + \epsilon_{\text{eff}}\) to eliminate the second-moment accumulator buffer (\(v\)), slashing state VRAM footprint by 50% without numerical instability.
  8. GIL Control:
  9. All multi-core Rust operations MUST execute inside py.detach(), yielding the CPython GIL to enable true concurrent scaling on free-threaded Python (PEP 703).

4. Local Build & Test Verification

# Build release extension locally
maturin develop --release

# Run all Rust crate unit and differential parity tests
cargo test --workspace

# Run standalone NumPy test suite
python optimizer/tests/test_standalone_numpy.py

# Run PyTorch deep learning integration test suite
python optimizer/tests/test_end_to_end_training.py