# 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`](https://docs.astral.sh/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:

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

```{admonition} Upstream package
:class: note

`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

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

```python
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](first_simulation.md).