Installation

Installation#

The validated Hood Lab fork currently installs from a source checkout. The package imported in Python is still named fdtdx; fdtdx-hoodlab names this repository and its validation program.

Requirements#

  • Python 3.12 or 3.13

  • uv for the reproducible project environment

  • Linux is the primary tested platform

  • an NVIDIA GPU and CUDA-compatible driver for the GPU profile; CPU execution is useful for setup and small tests

Install the validated fork#

From a checkout of this repository:

uv sync --extra gpu --extra dev
uv run python scripts/gpu_smoke.py

The first command installs solver/ as the editable fdtdx package and selects JAX’s CUDA 13 wheel. The smoke script prints the selected JAX backend and runs a small array operation. If you need CPU-only setup or documentation work, omit --extra gpu.

Upstream package

pip install fdtdx installs the upstream release from PyPI. That is the right choice for upstream-stable functionality, but it does not include every extension and validation fix described on this fork’s site.

Verify physics and the benchmark harness#

uv run fdtdx-bench smoke
uv run fdtdx-bench status

The smoke suite exercises fast solver invariants without accessing Tidy3D or spending FlexCredits. The status command reads the checked-in validation record.

Confirm the runtime#

import fdtdx
import jax

print("JAX backend:", jax.default_backend())
print("devices:", jax.devices())
print("FDTDX:", fdtdx.__file__)

For multi-GPU work, start with one device until the scene and objective are correct. Compilation cost and array sharding are separate concerns from electromagnetic convergence.

Keep the JAX cache warm#

Large differentiable simulations can take minutes to compile. The project supports a persistent compilation cache; keep its directory on fast local storage and avoid changing static shapes between optimization steps. A changed grid shape or Python control-flow structure triggers a new compilation.

Next: run a first simulation.