Installation¶

Requirements¶

Python 3.12, 3.13 or 3.14.
A fresh virtual environment (see the warning on gdsfactory below).
For simulations of any size, an accelerator that JAX supports, such as a GPU or TPU (see JAX setup). A CPU is enough for the live demo, for building devices and for the viewer.

Basic installation¶

pip install bifrost-photonics

The latest development version, from GitHub:

pip install "bifrost-photonics @ git+https://github.com/Sephiram591/bifrost.git"

gdsfactoryx cannot share an environment with upstream gdsfactory

bifrost builds on gdsfactoryx, the JAX port of gdsfactory, installed from PyPI as the gdsfactoryx distribution. It provides the same gdsfactory import package as upstream gdsfactory, so the two overwrite each other's files and upstream gdsfactory in the same environment breaks bifrost. Remove an existing upstream gdsfactory first (pip uninstall -y gdsfactory). If import gdsfactory raises an error saying both distributions are installed, run pip uninstall -y gdsfactory gdsfactoryx && pip install gdsfactoryx. Your code does not change: import gdsfactory as gf works as before.

Check the installation¶

In the new environment, run:

import importlib.metadata as metadata
import platform

import jax

print(f"{'python':18}", platform.python_version())
for name in ("bifrost-photonics", "gdsfactoryx", "fdtdx", "jax", "jaxlib"):  # distribution names, as pip lists them
    print(f"{name:18}", metadata.version(name))
print(f"{'devices':18}", jax.devices())  # the devices of JAX's backend, e.g. [CudaDevice(id=0)] or [CpuDevice(id=0)]

Expected output (the versions will differ, and devices lists your JAX backend's devices, here one CUDA GPU):

python             3.12.14
bifrost-photonics  0.2.0
gdsfactoryx        9.51.0.post2
fdtdx              0.6.3
jax                0.11.2
jaxlib             0.11.2
devices            [CudaDevice(id=0)]

JAX setup¶

bifrost works with any JAX backend and needs no backend-specific configuration. pip installs JAX's default build, which runs on the CPU. For a GPU, TPU or other accelerator, set up JAX for your hardware with the JAX installation guide, then run the installation check again: devices should list your accelerator.

Contributor installation¶

git clone https://github.com/Sephiram591/bifrost.git
cd bifrost
pip install -e ".[dev,docs]"

Command	What it does
`make test`	the Python tests (`pytest tests`)
`make test-js`	the viewer's JavaScript tests and typecheck
`make test-docs`	checks of the docs and the live demo, including browser tests (run `playwright install chromium` once first)
`make test-hardware`	the tutorial's full simulations (needs a GPU)
`make viewer-js`	rebuilds the viewer bundle in `bifrost/viewer/static/` after editing `js/viewer/*.ts`
`make docs`	builds this documentation with strict checks
`make docs-serve`	serves it at `localhost:8080`

Conventions: Contributing and tests.