🚀 kbeta-pinn3d v1.0.1

Companion code for the paper "Kourkoutas-β: A Sunspike-Driven Adam Optimizer with Desert Flair" (arXiv:2508.12996).

This release delivers the full 3D cylindrical PINN for heat conduction (Heat3D) workload used in the experiments, packaged for easy installation via PyPI and reproducibility in research.

✨ Highlights

• New PyPI package: kbeta-pinn3d (semantic versioning).
• Extras for flexible installs:
  • viz → matplotlib, seaborn, pandas.
  • dev → pytest, ruff, mypy, pre-commit, build, twine.
• Pure‑MLX backend (no PyTorch/TensorFlow). Depends on mlx>=0.27.1.
• Command‑line driver kbeta_pinn3d.pinn3d with options:
  • --optimizer {adam95, adam999, kourkoutas}
  • --epochs, --seed, --viz
  • --kour_diagnostics, --collect_spikes, --window, --stride
• Plotting utilities for Sun‑spike / β₂ violin & heatmaps and field visualization.
• Typed package (PEP 561 py.typed included).
• CI on macOS/arm64 and smoke tests covering imports and a tiny forward pass.
• Packaging cleanup (modern pyproject.toml, minimal MANIFEST).

Heads‑up: a previous accidental upload 1.0.0 was yanked. Please use 1.0.1 or newer.

📦 Installation

Option 1 — PyPI wheels (end‑users)

pip install kbeta-pinn3d
# add visuals
pip install "kbeta-pinn3d[viz]"
# dev tools & tests
pip install "kbeta-pinn3d[dev]"

Option 2 — Editable from source (research / contrib)

git clone https://github.com/sck-at-ucy/kbeta-pinn3d.git
cd kbeta-pinn3d
python -m venv .venv && source .venv/bin/activate
pip install -e ".[viz,dev]"
pytest -q  # smoke tests should pass

✅ What's changed since 1.0.0 (yanked)

• Overhauled README with clear wheel + editable install paths.
• Added extras: viz, dev.
• Added tests (tests/test_smoke.py, tests/test_forward.py) and GitHub Actions matrix job (macOS/arm64).
• Included py.typed for downstream type checkers.
• Trimmed distribution via MANIFEST (exclude repo clutter).
• Local release validation script (build wheel, install wheel, editable install, run tests).

🔧 Compatibility

• Python: 3.11+ (tested in CI).
• Platform: Apple Silicon / macOS (MLX backend).
  Other platforms are untested for this release.

🧪 Validation

Local and CI checks performed before tagging:

• python -m build → sdist + wheel
• twine check → metadata OK
• Wheel install/import smoke test
• Editable install/import smoke test
• pytest -q → smoke suite passes

⚠️ Known issues / Next steps

• PyPI README images may not render due to relative paths. This will be fixed by switching to absolute, tag‑pinned URLs in v1.0.2.
• DOI badge is a placeholder; final Zenodo DOI will land in v1.0.2.

📂 Project layout

kbeta-pinn3d
├── src/kbeta_pinn3d/         # source (pinn3d.py, __init__.py, py.typed)
│   └── utils/                # plotting & visualization helpers
├── tests/                    # smoke & forward tests
├── assets/                   # figures used in README
├── .github/workflows/ci.yml  # macOS/MLX CI
└── pyproject.toml            # build config & extras

🔗 Related resources

• Core optimizer: kbeta
• Transformer2D benchmark: kbeta-transformer2d
• MLX Beyond Language: MLX_BeyondLanguage

🙌 Citation (preprint)

@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}
}

📄 License

MIT — see LICENSE in the repo.