Metadata-Version: 2.4
Name: luminav
Version: 1.5.3.post4
Summary: LuminaV Optimizer (Moved to 'luminamoon' - Official PROJECT LUMI Package)
Author: Lumina Moon (cloverx-id) Contributors
Author-email: Silver Moon <leafmoon.idn@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/cloverx-id/luminamoon
Project-URL: Repository, https://github.com/cloverx-id/luminamoon
Project-URL: Official PyPI (luminamoon), https://pypi.org/project/luminamoon/
Project-URL: Documentation, https://github.com/cloverx-id/luminamoon#readme
Project-URL: Changelog, https://github.com/cloverx-id/luminamoon/tree/main/changelogs
Project-URL: Bug Tracker, https://github.com/cloverx-id/luminamoon/issues
Project-URL: Organization, https://github.com/cloverx-id
Keywords: optimizer,deep-learning,pytorch,vulkan,simd,triton,luminamoon
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: luminamoon>=1.0.5
Dynamic: license-file

# 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`**](https://pypi.org/project/luminamoon/)
> - **Official GitHub Repository**: [**`https://github.com/cloverx-id/luminamoon`**](https://github.com/cloverx-id/luminamoon)
> - **Changelogs (Software & Algorithm v1.5.3)**: [**`changelogs/`**](https://github.com/cloverx-id/luminamoon/tree/main/changelogs)

---

## Quick Migration Guide

Replace `luminav` with `luminamoon` in your environment and imports:

```bash
pip install --upgrade luminamoon
```

```python
# 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)

```python
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`**](https://github.com/cloverx-id/luminamoon).
