LuminaV Optimizer — Moved to luminamoon (PROJECT LUMI)

IMPORTANT MIGRATION NOTICE: LuminaV has officially graduated into the unified PROJECT LUMI (luminamoon) monorepo and native Rust + Python distribution!

Installing pip install luminav (v1.5.3.post4) now automatically installs luminamoon>=1.0.5 and forwards from luminamoon import LuminaV for 100% backward compatibility.

• New Official PyPI Package: pip install luminamoon
• Official GitHub Repository: https://github.com/cloverx-id/luminamoon
• Changelogs (Software & Algorithm v1.5.3): changelogs/

Quick Migration Guide

Replace luminav with luminamoon in your environment and imports:

pip install --upgrade luminamoon

# Recommended new import (zero deprecation warning):
from luminamoon import LuminaV

# Legacy import (still works automatically via this bridge package):
from luminav import LuminaV

Canonical LuminaV v1.5.3 Mathematical & Hardware Specification (luminamoon)

1. Multi-Backend Native Rust 2024 Execution Engine

• CPU SIMD (AVX-512 & AVX2): Parallelized via Rayon with 16-lane pairwise tree reductions (reduce_sum_16) and zero-copy buffer protocol support for both PyTorch Tensor and standalone NumPy ndarray.
• Vulkan 1.3/1.4 Compute Shaders (SPIR-V / Wave32 UMA): Native GPU acceleration across AMD, Intel, and NVIDIA GPUs without requiring CUDA.
• Triton AOT/JIT GPU Kernels: Fused single-pass (1P) and two-pass (2P) kernels for CUDA and ROCm.
• Free-Threaded Python (abi3t / No-GIL): Full support for Python 3.10 through 3.15t.

2. Dual-Buffer CLM (buffer=2) & Single-Buffer TD-CLM (buffer=1)

In LuminaV, CLM stands for Convex Lookahead Momentum—every word maps directly to the mathematical operator in the numerator $\tilde{m}t = \beta_1 m_t + (1 - \beta_1) g_t \equiv \beta_1^2 m{t-1} + (1 - \beta_1^2) g_t = w_1 m_{t-1} + w_2 g_t$, which forms a strict convex combination ($w_1 + w_2 = 1$) of Nesterov lookahead and first-order momentum—and TD-CLM stands for Triangle-Defect Convex Lookahead Momentum.

Let $\mu_d = \frac{1}{N}\sum_{i=1}^N (g_{t,i} - m_{t-1,i})$ denote the mean innovation defect when centered_defect=True ($\mathbb{I}{\text{cd}} = 1$), and $\epsilon{\text{eff}} = \max(\epsilon, 10^{-4})$ for float16 (or $\epsilon$ otherwise).

• LuminaV-2 (buffer=2 — Dual-Buffer Convex Lookahead Momentum / CLM): Tracks first-order momentum $m_t$ and centered innovation variance $v_t$ with lookahead bias correction ($\hat{\beta}{1,t} = 1 - \beta_1^{t+1}$, $\hat{\beta}{2,t} = \max(1 - \beta_2^t, 10^{-15})$) and rational Padé $[13/6]$ hyperbolic tangent bounding (tanh_pade_f32 clamped on $[-7.9988117, 7.9988117]$): $$m_t = \beta_1 m_{t-1} + (1 - \beta_1) g_t, \qquad \tilde{m}t = \beta_1 m_t + (1 - \beta_1) g_t$$ $$d_t^{(\text{B2})} = (g_t - m_t) - \mathbb{I}{\text{cd}} \beta_1 \mu_d, \qquad v_t = \beta_2 v_{t-1} + (1 - \beta_2)\left(d_t^{(\text{B2})}\right)^2$$ $$c_1 = \frac{\hat{\beta}{1,t} \tau}{\sqrt{\hat{\beta}{2,t}}}, \qquad c_2 = \epsilon_{\text{eff}} \hat{\beta}{1,t} \tau, \qquad \sigma_t = c_1 \sqrt{\max(v_t, 0)} + c_2$$ $$u_t^{(\text{B2})} = \tanh{\text{Padé}[13/6]}\left(\frac{\tilde{m}_t}{\max(\sigma_t, 10^{-12})}\right)$$

• LuminaV-1 (buffer=1 — Single-Buffer Triangle-Defect Convex Lookahead Momentum / TD-CLM): Eliminates the second-moment buffer $v_t$ (50% optimizer state memory savings) by bounding the convex lookahead numerator $\tilde{m}t = w_1 m{t-1} + w_2 g_t$ directly via the Triangle Inequality ($\lvert w_1 m_{t-1} + w_2 g_t \rvert \le w_1 \lvert m_{t-1} \rvert + w_2 \lvert g_t \rvert$) and the Triangle Defect residual $d_t^{(\text{B1})}$, requiring zero global reductions and zero transcendental $\tanh$ evaluations: $$w_1 = \beta_1^2, \qquad w_2 = 1 - \beta_1^2, \qquad \tilde{m}t = w_1 m{t-1} + w_2 g_t$$ $$d_t^{(\text{B1})} = (g_t - m_{t-1}) - \mathbb{I}{\text{cd}} \mu_d, \qquad \mathcal{E}t = w_1 |m{t-1}| + w_2 |g_t| + \lambda \left|d_t^{(\text{B1})}\right| + \epsilon{\text{eff}}$$ $$u_t^{(\text{B1})} = \frac{\tilde{m}t}{\mathcal{E}t} = \frac{\beta_1^2 m{t-1} + (1 - \beta_1^2) g_t}{\beta_1^2 |m{t-1}| + (1 - \beta_1^2) |g_t| + \lambda \left|d_t^{(\text{B1})}\right| + \epsilon_{\text{eff}}} \in (-1, 1), \qquad m_t = \beta_1 m_{t-1} + (1 - \beta_1) g_t$$ where the default triangle defect ratio $\lambda = 0.30$ is calibrated to the analytical symmetric spike–reversal equilibrium $\lambda^* = \frac{2(1 - \beta_1^2)^2}{4\beta_1^2 - 3} \approx 0.3008$ (for $\beta_1 = 0.9$).

3. Cautious Masking, Trust-Region Bounding & Stochastic Rounding

• Cautious Alignment Gate (cautious=True): $$\mathcal{M}t = \mathbb{I}(u_t \odot g_t > 0), \qquad \gamma{\text{cautious}} = \frac{1}{\mathrm{clamp}(\bar{m}t, c{\min}, 1.0)}, \qquad \delta_t = (u_t \odot \mathcal{M}t) \cdot \gamma{\text{cautious}}$$
• Coordinate vs. Radial Trust-Region Bounding (bound=True):
  • bound_type="coordinate": $\Delta\theta_i = B_i \tanh_{\text{Padé}[13/6]}\left(\frac{\eta \delta_i}{B_i}\right)$ with $B_i = r_{\text{bound}}\sqrt{\theta_{0,i}^2 + 10^{-4}}$.
  • bound_type="radial": $\Delta\theta = \eta \delta \cdot \frac{\tanh_{\text{Padé}[13/6]}(r)}{\max(r, 10^{-8})}$ with $r = \frac{\eta |\delta|2}{r{\text{bound}}\max(|\theta_0|_2, 1.0)}$.
• Stateless 32-Bit MurmurHash3 Stochastic Rounding (stochastic_rounding=True): Unbiased bitwise stochastic quantization for bfloat16 and subnormal-aware float16 weights and momentum states.

Standard Instantiation (LuminaV v1.5.3)

import torch
from luminamoon import LuminaV

model = YourModel().to(device="cuda", dtype=torch.bfloat16)

optimizer = LuminaV(
    model.parameters(),
    lr=8e-4,                    # Learning rate
    betas=(0.9, 0.999),         # First-order (beta1) & second-order (beta2) decay coefficients
    eps=1e-8,                   # Numerical stability floor
    weight_decay=0.08,          # Decoupled weight decay
    tau=0.8,                    # Soft-projection temperature threshold (buffer=2)
    lam=0.3,                    # Triangle defect ratio weight (buffer=1 TD-CLM, equilibrium ~0.3008)
    cautious=True,              # Sign-aligned Traffic-Cop directional gate
    cautious_clamp_min=0.5,     # Minimum cautious density floor (max 2.0x boost)
    buffer=2,                   # 2 = Dual-Buffer CLM, 1 = Single-Buffer TD-CLM (50% less state RAM)
    centered_defect=False,      # Mean-centered innovation defect (buffer=1 & buffer=2)
    stochastic_rounding=True,   # Stateless 32-bit MurmurHash3 stochastic rounding for BF16/FP16
    bound=True,                 # Adaptive trust-region step bounding
    bound_type="coordinate",    # "coordinate" (zero collective sync) or "radial"
    bound_ratio=0.05,           # Maximum step displacement ratio relative to parameter scale
    master_weights="none",      # "none" (Master-Free), "semi", or "full" (FP32)
    execution="auto",           # "auto", "triton", "vulkan", "simd", or "scalar"
    fused_single_pass=True,     # Single-pass fused kernel via lagged EMA scalars
    ema_decay="auto",           # "auto" (0.80 for buffer=2, 0.95 for buffer=1)
    fsdp_sync=False,            # Distributed FSDP / ZeRO-3 scratch synchronization
    seed=1337,                  # Deterministic PRNG seed
)

For full documentation, formal Z3 SMT verification (LSO-Eval), and the LuminaMoon Data Engine, visit https://github.com/cloverx-id/luminamoon.