PROJECT LOOMY

Loomy (luminamoon) is the reference implementation and central repository of PROJECT LOOMY, providing low-precision numerical optimization, dataset text preprocessing and data processing utilities, and an evaluation suite developed by Silver Moon (@cloverxion) and Lumina Moon (@cloverx-id) contributors.

Built with a modular Rust and Python architecture under PROJECT LOOMY, luminamoon provides components for CPU/GPU parameter updates, text dataset preprocessing, and numerical verification:

LSO-Eval v1.1.0 Evaluation & Verification Notebook: Open in Google Colab — Empirical Stage II–IV benchmarks executed on LuminaV v1.5.3 under native torch.bfloat16 (centered_defect=False).

Projects & Components

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 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 in IDE autocompletion and LuminaV.__init__ docstrings:

Software vs. Algorithm Versioning (v1.0.9 / Spec v1.6.0)

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

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

All version resolution operates offline using local compatibility profiles:

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

# 1. Inspect Software Package Version vs. Algorithm Specification Version
print(luminamoon.__version__)    # "1.0.9" (Software distribution)
print(lmd.get_version())         # "1.0.9" (Data Engine module)
print(LuminaV.ALGORITHM_SPEC)    # "1.6.0" (Mathematical specification)
print(LuminaV.getVersion())      # "1.6.0"

# 2. 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 selection
LuminaV.setVersion("1.5.5")      # Class-level default

# 3. Default specification (Note: Specifications prior to v1.5.0 are deprecated)
opt_default = LuminaV([weights, biases], version="1.6.0")

Basic Usage (LuminaMoon Data Engine: Fused Text Preprocessing Pipeline)

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

# 1. Fused single-pass text preprocessing 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. Export to Apache Arrow, Polars, and 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 background prefetching & 128B Ping-Pong checkpointing
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()  # Saves Dual-Slot A/B checkpoint and deduplication WAL

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

Verification & CI/CD

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

# Run static analysis across the Rust workspace
cargo clippy --workspace --all-targets -- -D warnings

# Run Rust workspace unit and parity tests (Optimizer + Data Engine)
cargo test --workspace

# Run Python static type check
npx pyright python/luminamoon

# Run standalone NumPy, PyTorch, and Data Engine test 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 verification suite
python -m eval

Developer Resources

For contributors working on 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 developed and maintained by:

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

License

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