PROJECT LOOMY

Loomy(luminamoon) is the official reference implementation and central monorepo of PROJECT LOOMY, providing low-precision numerical optimization, multimodal dataset streaming, and formal verification suites developed by Silver Moon (@cloverxion) and Lumina Moon (@cloverx-id) contributors.

Built with a modular architecture under the PROJECT LOOMY specification, luminamoon connects specialized components for CPU/GPU hardware execution, low-latency streaming, and verified numerical stability:

LSO-Eval v1.1.0 Empirical Benchmark Notebook: Open in Google Colab — Executed on LuminaV v1.5.3 (100% mathematically and bit-for-bit trajectory-equivalent to v1.5.4–v1.5.5 under native BF16 and centered_defect=False).

Projects & Components

Project / Component	Path	Status	Description	Documentation
LuminaV Optimizer	optimizer/	Active (Spec v1.5.5)	Canonical LuminaV v1.5.5 optimizer engine with CPU SIMD (AVX-512/AVX2), Vulkan UMA, Triton AOT/JIT kernels, contiguous bucket fusion, and zero-stall JIT pre-warmup.	Optimizer Guide
LuminaMoon Data Engine	data/	Active (v1.0.8.post1)	Modular preprocessing engine: AVX-512/AVX2/NEON SIMD text normalization, dual-layout StringTensor (CPU StringView & GPU contiguous buffers), heuristic Shannon quality filtering, MinHash/XXH3-64 deduplication, PII masking, and 128B Ping-Pong crash recovery.	Data Engine Guide
LSO-Eval Suite	eval/	Active (v1.1.0)	Algorithm-agnostic formal verification & qualification suite (LSO-Eval v1.1.0): Z3 SMT solver invariants, 2D trajectory benchmarks, numerical parity audits, and Two-Tiered Pareto 4B LLM qualification.	Eval Guide
Changelogs	changelogs/	Active	Dedicated version histories separating Software Package releases (v1.0.0–v1.0.8.post1) and LuminaV Algorithm Specifications (v1.0.0–v1.5.5).	Changelogs
Documentation	docs/	Active	Centralized documentation portal, developer internal blueprints (docs/optimize/, docs/dataloader/), and ecosystem version audits.	Docs Portal
Python Package	python/luminamoon/	Active (v1.0.8.post1)	Unified free-threaded (abi3t) Python namespace exposing LuminaV Optimizer, DataStreamLoader, and PyTorch/NumPy/HuggingFace interop.	API Reference

Quickstart

Installation

Install the compiled package wheel from PyPI:

pip install luminamoon

Or build from source using Maturin and the Rust 2024 toolchain:

git clone https://github.com/cloverx-id/luminamoon.git
cd luminamoon
pip install maturin
maturin develop --release

Basic Usage (LuminaV Optimizer)

import numpy as np
from luminamoon import LuminaV

# Initialize parameters
weights = np.random.randn(64, 10).astype(np.float32)
biases = np.zeros(10, dtype=np.float32)

# Instantiate LuminaV optimizer (uses calibrated default hyperparameters)
optimizer = LuminaV([weights, biases], lr=8e-4, weight_decay=0.08, buffer=2)

# Execute optimization step with explicit gradients
grad_w = np.random.randn(64, 10).astype(np.float32)
grad_b = np.random.randn(10, dtype=np.float32)
optimizer.step(grads=[grad_w, grad_b])

For PyTorch deep learning workflows, see the PyTorch Integration Guide.

LuminaV Hyperparameter Quick Reference

All default values below are exposed directly in IDE autocompletion and LuminaV.__init__ docstrings:

Parameter	Type	Default	Description
lr	float	8e-4 (0.0008)	Learning rate ($\eta$).
betas	Tuple[float, float]	(0.9, 0.999)	Exponential moving average factors $(\beta_1, \beta_2)$ for first moment and second moment / temporal defect.
eps	float	1e-8	Numerical stability constant ($\epsilon$) in the adaptive denominator.
weight_decay	float	0.08 (8e-2)	Decoupled weight decay coefficient.
tau	float	0.8	Soft-projection temperature threshold ($\tau$) for denominator damping.
lam	float	0.3	Temporal defect sensitivity weight ($\lambda$) in Single-Buffer TD-CLM (buffer=1).
cautious	bool	True	Enables sign-aligned cautious update masking and lagged EMA scaling.
cautious_clamp_min	float	0.5	Lower bound in (0.0, 1.0] for cautious alignment scaling.
buffer	int | str	2	State topology: 2 ("dual", "clm") for Dual-Buffer Convex Lookahead Momentum (CLM), or 1 ("single", "td-clm") for Single-Buffer Triangle-Defect Convex Lookahead Momentum (TD-CLM).
stochastic_rounding	bool	True	Applies stateless 32-bit MurmurHash3 bit-avalanche stochastic rounding when writing to bfloat16 / float16 weights.
bound	bool	True	Enables adaptive trust-region update bounding.
bound_type	str | int	"coordinate"	Trust-region geometry: "coordinate" (element-wise clip, zero collective sync) or "radial" (global norm ratio).
bound_ratio	float	0.05	Maximum update magnitude relative to parameter scale.
master_weights	str | bool	"none"	Mixed-precision master weight mode for bfloat16/float16: "none" (False), "semi", or "full" (True).
execution	str | int	"auto"	Hardware backend: "auto", "triton", "vulkan", "simd", or "scalar".
fused_single_pass	bool	True	Fuses parameter update and scalar reduction statistics into a single kernel pass.
fuse_tensors	bool	False	Coalesces parameters per (group, device, dtype) bucket into 1D contiguous storage with zero-copy views to eliminate kernel dispatch overhead on fragmented models.
bucket_cap_mb	float	500.0	Maximum memory capacity per contiguous bucket chunk in megabytes when fuse_tensors=True. Partitions large models (e.g. 4B+) into bounded chunks to prevent monolithic memory allocation spikes. Emits a UserWarning if explicitly specified when fuse_tensors=False.
prewarm_jit	bool	True	Pre-compiles Triton GPU kernels on 64-element dummy buffers (lr=0.0) during initialization to eliminate Step 1/Step 2 JIT compilation latency.
ema_decay	str | float	"auto"	EMA decay for lagged cautious/radial scalars ("auto" resolves to 0.80 for buffer=2 and 0.95 for buffer=1).
fsdp_sync	bool	False	Synchronizes global reduction scratch buffers across torch.distributed FSDP shards.
seed	int	1337	Deterministic PRNG seed for stateless stochastic rounding.
version	Optional[str]	"1.5.5"	Locks the active LuminaV mathematical specification version.

Software vs. Algorithm Versioning (v1.0.8.post1 / Spec v1.5.5)

luminamoon maintains two orthogonal version tracks (documented in changelogs/):

• Software Package Version (1.0.8.post1): Tracks the unified Rust + Python wheel distribution (luminamoon.__version__ and luminamoon.data.get_version()). See changelogs/SOFTWARE_CHANGELOG.md.
• LuminaV Algorithm Specification (1.5.5): Tracks the canonical mathematical update rules (LuminaV.ALGORITHM_SPEC and LuminaV.getVersion()). See changelogs/LUMINAV_ALGORITHM_CHANGELOG.md.

All version resolution operates 100% offline using local compatibility profiles:

import luminamoon
from luminamoon import LuminaV
import luminamoon.data as lmd

# 1. Introspect Software Package Version vs. Algorithm Specification Version
print(luminamoon.__version__)    # "1.0.8.post1" (Software distribution)
print(lmd.get_version())         # "1.0.8.post1" (Data Engine module)
print(LuminaV.ALGORITHM_SPEC)    # "1.5.5" (Canonical mathematical specification)
print(LuminaV.getVersion())      # "1.5.5"

# 2. Lock or select a specific algorithm version per-instance or globally
opt = LuminaV([weights, biases], lr=8e-4, version="1.5.5")
opt.setVersion("1.5.5")          # Instance-level version lock
LuminaV.setVersion("1.5.5")      # Class-level default

# 3. Canonical specification lock (Note: Specifications prior to v1.5.0 are deprecated)
# LuminaV v1.5.5 TD-CLM is the canonical mathematical specification across CPU/GPU runtimes.
opt_canonical = LuminaV([weights, biases], version="1.5.5")

Basic Usage (LuminaMoon Data Engine: Fused Preprocessing & Zero-Copy Pipeline)

from luminamoon.data import FusedPipeline, StringTensor, create_resumable_collate, ResumablePipeline

# 1. Ultra-fast fused single-pass preprocessing (>400k records/s) in Rust
pipeline = FusedPipeline(
    trim_whitespace=True,
    normalize_newlines=True,  # AVX-512 / AVX2 / NEON SIMD
    min_chars=10,
    min_entropy=2.0,
)
string_tensor = pipeline(["  sample 1\r\n", "sample 2 with proper prose text"])

# 2. Zero-copy export to Apache Arrow, Polars, and GPU-ready PyTorch buffers
polars_series = string_tensor.to_polars()
arrow_array = string_tensor.to_arrow()
offsets_tensor, payload_tensor = string_tensor.to_torch_gpu(device="cuda")

# 3. Stream dataset with async prefetching & 128B Ping-Pong crash-recovery
pipe = ResumablePipeline(
    source=raw_data,
    fused_pipeline=pipeline,
    batch_size=64,
    prefetch_batches=4,
    checkpoint_path="./cache/checkpoint.meta",
)
for batch in pipe:
    # Training step...
    pipe.commit()  # Atomically persists Dual-Slot A/B checkpoint and deduplication WAL

For detailed architecture, Shannon entropy heuristics, MinHash deduplication, and PyTorch collate_fn adapters, see the Data Engine Guide.

Verification & CI/CD

All pull requests and releases are validated across Linux, Windows, and macOS:

# Enforce zero-warning static analysis across the Rust workspace
cargo clippy --workspace --all-targets -- -D warnings

# Run Rust workspace unit and differential parity tests (Optimizer + DataLoader)
cargo test --workspace

# Run Python static type check
npx pyright python/luminamoon

# Run standalone NumPy, PyTorch, and DataLoader verification suites
python optimizer/tests/test_standalone_numpy.py
python optimizer/tests/test_end_to_end_training.py
python -B tests/test_data_modular.py
python -B tests/test_gpu_vs_cpu_strings.py

# Run LSO-Eval formal verification suite
python -m eval

Developer Resources

For contributors and systems engineers building on or extending PROJECT LOOMY (luminamoon):

• Changelogs (Software & Algorithm): changelogs/
• Optimizer Modular Documentation: docs/optimize/
• Data Engine Modular Documentation: data/
• Optimizer Library Audits: docs/library_audit/
• Data Standalone Library Audits: data/docs/library_audit/
• Data Engine Architecture & User Guide: data/README.md
• User Documentation: docs/en/

Authors & Maintenance

PROJECT LOOMY (luminamoon) is engineered and maintained by:

• Silver Moon (@cloverxion)
• Lumina Moon (@cloverx-id) contributors

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.