phoxla 0.1.4a2

Differentiable photonic design and simulation on XLA accelerators

PHOXLA

PHOXLA ("FOX-luh") - Differentiable photonic design and simulation on XLA accelerators.

PHOXLA is a framework blueprint for building modern photonic inverse-design systems with JAX/Flax. The goal is to treat differentiable physics as a first-class deep learning component, so photonic simulation modules can be plugged into end-to-end trainable workflows.

Vision

• XLA-native photonic simulation and optimization (GPU/TPU first, CPU compatible)
• Differentiable physics modules usable as model layers/loss terms
• Inverse design pipelines integrated with standard deep learning tooling
• Extensible interoperability with JAX-based solvers (including FDTDX-style workflows)

Current Status

This repository is an initial blueprint and governance scaffold. Core simulation and training modules will be added incrementally.

Planned Package Layout

• src/phoxla/sim: differentiable photonic simulation core
• src/phoxla/nn: NN-facing modules and differentiable operators
• src/phoxla/inv: inverse design workflows and optimizers
• src/phoxla/integrations/fdtdx: interoperability layer

Repository Bootstrap

See:

• docs/REPO_LAUNCH_GUIDE.md
• docs/REPO_ABOUT_AND_TOPICS.md
• docs/PACKAGE_NAMESPACE_PLAN.md
• docs/PYPI_CLAIM_PLAYBOOK.md
• docs/NAMESPACE_PRIORITY.md
• docs/AUTOMATION_FLOW.md
• docs/ARCHITECTURE_BLUEPRINT.md
• docs/COMMIT_MESSAGE_GUIDE.md
• ROADMAP.md

Quick Release Commands

make venv
make qa
make next-tag
make release-check

# then with PyPI token in env:
make publish-pypi

Modern Tooling Stack

• Ruff: lint + format
• Pytest: test runner
• Mypy: static type checks
• pre-commit: local hook runner
• GitHub Actions: CI (ci.yml) + auto-tag (auto-tag.yml) + release publish (release.yml)

Local setup

make venv
. .venv/bin/activate
pre-commit install

Daily checks

make qa

Conventional commit -> version bump

• feat:, fix:, perf:, refactor: -> alpha bump (...aN)
• feat!: / fix!: / BREAKING CHANGE -> next major alpha (X+1.0.0a0)
• docs:, chore:, test:, ci: only -> no release

End-to-end Automation Flow

1. Push to main
2. ci.yml runs Ruff/Mypy/Pytest/build checks
3. auto-tag.yml computes next alpha tag from commit messages and pushes vX.Y.ZaN tag
4. release.yml runs full quality/build checks on that tag
5. release.yml publishes GitHub Release notes + uploads package to PyPI (Trusted Publishing)

auto-tag.yml writes the new version (e.g., 0.1.4a0) into pyproject.toml and src/phoxla/__init__.py, so manual a1/a2/a3 edits are not needed.

Push To GitHub

git add .
git commit -m "feat(core): add initial phoxla module scaffold"
git remote add origin [e-mail]:phoxla/phoxla.git
git push -u origin main

Publish To PyPI (name claim)

. .venv/bin/activate
python -m build --sdist --wheel --no-isolation
python -m twine check dist/*
read -s -p "PyPI token: " PYPI_TOKEN; echo
TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" python -m twine upload dist/*
unset PYPI_TOKEN

License

Apache-2.0 (LICENSE)