🚀 Release v1.0.0 – kbeta-transformer2d Companion code for the paper "Kourkoutas-β: A Sunspike-Driven Adam Optimizer with Desert Flair" (arXiv:2508.12996). This release delivers the full 2-D Heat-Diffusion Transformer workload used in the experiments, packaged for easy installation via PyPI and reproducibility in research. Note: This release is identical to v1.0.0. Published only to trigger Zenodo archiving and DOI minting. ✨ Highlights End-to-end Transformer benchmark for spatial–temporal diffusion problems. Tight integration with Kourkoutas-β (see kbeta): Drop-in optimizer swap with --optimizer=kourkoutas. Sun-spike / β₂ diagnostics enabled via CLI flags (--collect_spikes). Dual masking modes: autoregressive (causal) and full-context (block). RoPE positional encoding option for better long-horizon extrapolation. Quantization-ready: all dense/conv projections use mlx.nn.quantize_lin. Lightweight footprint: Paper config ≈ 32 M parameters (24 layers, 16 heads). Runs comfortably on a single Apple Silicon GPU (Mac Studio). Configurable learning-rate schedules: Explicit step schedule via learning_rate_schedule (used in the paper). Fallback to cosine schedule controlled by init_lr, target_lr, and ramp_steps. 📦 Installation Option 1 — PyPI wheels (end-users): pip install kbeta-transformer2d Dev extras: pip install "kbeta-transformer2d[dev]" Exact paper reproducibility (pinned deps, MLX 0.26.3): pip install "kbeta-transformer2d[repro]" Option 2 — Clone for research/contribution: git clone https://github.com/sck-at-ucy/kbeta-transformer2d.git cd kbeta-transformer2d python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" 🛠 Quick start Run smoke-tests: pytest -q Train with packaged defaults: python -m kbeta_transformer2d.demo_heat2d heat2d.yml --epochs=5 --optimizer=adam95 Use explicit output directory: python -m kbeta_transformer2d.demo_heat2d heat2d.yml --epochs=5 --optimizer=kourkoutas --override storage.outdir="./OUTPUTS/run_demo" 📂 Project layout kbeta-transformer2d ├── src/kbeta_transformer2d/ # source ├── configs/ # YAML configs (default, paper, quick-test) ├── tests/ # smoke tests └── assets/ # figures for README 🔗 Related resources Core optimizer: kbeta PINN benchmark: kbeta-pinn3d MLX Beyond Language: MLX_BeyondLanguage 📖 Citation If you use this work, please cite: Paper: @article{Kassinos2025Kourkoutas, title = {Kourkoutas-β: A Sunspike-Driven Adam Optimizer with Desert Flair}, author = {Stavros Kassinos}, journal = {arXiv preprint arXiv:2508.12996}, year = {2025}, url = {https://arxiv.org/abs/2508.12996} } Software (Zenodo DOI once minted): @software{kassinos2025transformer2d, author = {Stavros Kassinos}, title = {kbeta-transformer2d: 2-D Heat-Diffusion Transformer – Companion Code}, year = 2025, publisher = {Zenodo}, version = {1.0.0}, doi = {10.5281/zenodo.xxxxxxx}, url = {https://doi.org/10.5281/zenodo.xxxxxxx} } ⚡️ v1.0.0 is the first public release — stable, tested (wheel + editable installs), and ready for both research reproduction and practical experimentation.