phoxla 0.2.3

Differentiable photonics framework for hardware-agnostic inverse design and layout automation

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

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)

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

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

Daily checks

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

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

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

License

Apache-2.0 (LICENSE)