# 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

```bash
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

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

### Daily checks

```bash
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

```bash
git add .
git commit -m "feat(core): add initial phoxla module scaffold"
git remote add origin git@github.com:phoxla/phoxla.git
git push -u origin main
```

## Publish To PyPI (name claim)

```bash
. .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`)
