phoxla 0.2.3
Differentiable photonics framework for hardware-agnostic inverse design and layout automation
Requires Python: >=3.11
Keywords: photonics, inverse-design, differentiable-physics, layout-automation, hardware-agnostic

# PHOXLA

> PHOXLA ("FOX-luh") - Differentiable photonics, hardware-agnostic by design.

`PHOXLA = PHOtonic Hardware-agnostic Optimization for eXtensible Layout Automation`

PHOXLA is a differentiable photonics framework for hardware-agnostic inverse design and extensible layout automation.
The goal is to treat differentiable physics as a first-class deep learning component, so photonic modules can be plugged into end-to-end trainable workflows.

## Vision

- Fast differentiable exploration with physics-grounded validation workflows.
- ASM-first optimization, FDTD-assisted verification/refinement, fabrication-aware export.
- Differentiable physics modules usable as model layers/loss terms.
- Hardware-agnostic execution via backend adapters (e.g., JAX or PyTorch on CPU/GPU/TPU).
- Extensible interoperability with external 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 (ASM-first operators and propagation)
- `src/phoxla/nn`: NN-facing modules and differentiable operators
- `src/phoxla/inv`: inverse-design workflows, optimization loops, and layout-automation hooks
- `src/phoxla/integrations/fdtdx`: verification/refinement 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/SEMVER_POLICY.md`
- `docs/ARCHITECTURE_BLUEPRINT.md`
- `docs/BINARY_DISTRIBUTION_NUITKA.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
```

## Binary Wheel Commands (Nuitka module mode)

```bash
make binary-wheel

# upload binary wheel only (no sdist)
make publish-pypi-binary
```

## 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

- `0.y.z` lane (conservative):
  - `feat:`, `fix:`, `perf:`, `refactor:` -> PATCH bump
  - `feat!:` / `fix!:` / `BREAKING CHANGE` -> MINOR bump
- `>=1.0.0` lane (standard SemVer):
  - `feat:` -> MINOR bump
  - `fix:`, `perf:`, `refactor:` -> PATCH bump
  - `feat!:` / `fix!:` / `BREAKING CHANGE` -> MAJOR bump
- `docs:`, `chore:`, `test:`, `ci:`, `style:` 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 SemVer tag and pushes `vX.Y.Z`
4. `release.yml` runs full quality/build checks on that tag
5. `release.yml` publishes GitHub Release notes + uploads binary wheel to PyPI (Trusted Publishing)

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

## Versioning Policy

PHOXLA uses Semantic Versioning 2.0.0.
See `docs/SEMVER_POLICY.md` for the normative policy, migration notes, and commit-to-version mapping.

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

For obfuscated distribution, use `make publish-pypi-binary` to avoid source sdist upload.

## License

Apache-2.0 (`LICENSE`)