TorchFDTD

https://github.com/user-attachments/assets/021d317c-bd63-4019-8391-9211d9be4166

Also on YouTube: TorchFDTD Explained: GPU-Accelerated FDTD for Inverse Design.

Open-source GPU FDTD for photonics, with PyTorch gradients and a browser workbench. MIT licensed.

Build a device in Python or in the browser, simulate its electromagnetic fields, and use discrete adjoints with PyTorch autograd for inverse design.

Quick start · Examples · Validation · Documentation · Paper

A pulse couples into a microring, circulates and leaks back into the bus waveguide. Actual 2D FDTD, showing optical-cycle RMS E_z with a fixed color scale. Full-resolution video · Model and reproduction.

• Run on your NVIDIA GPU. Fused CUDA kernels and CUDA Graphs accelerate field updates. CPU execution is available too.
• Differentiate your simulation. Discrete adjoints connect material, geometry and source parameters to PyTorch autograd.
• Work in Python or the browser. Both use the same project format. Save a browser-built device and run it from Python, or open a Python-built project in the workbench.

Quick start

Install and open the workbench

Use Python 3.10 or 3.12. The release wheel includes the browser workbench, so you do not need Node.js or a source checkout.

Windows / PowerShell, NVIDIA GPU:

python -m venv torchfdtd-env
torchfdtd-env/Scripts/python.exe -m pip install torch --index-url https://download.pytorch.org/whl/cu126
torchfdtd-env/Scripts/python.exe -m pip install "torchfdtd[cuda-kernels] @ https://github.com/hyoseokp/TorchFDTD/releases/download/v1.1.4/torchfdtd-1.1.4-py3-none-any.whl"
torchfdtd-env/Scripts/torchfdtd doctor
torchfdtd-env/Scripts/torchfdtd serve

Open http://127.0.0.1:8765 in your browser. torchfdtd doctor checks the installation, CUDA device and fused-kernel launch before you start.

For a CPU-only installation, use the PyTorch index https://download.pytorch.org/whl/cpu and omit [cuda-kernels] from the wheel command. The cuda-kernels extra installs CuPy for the fused CUDA path. See installation and tested versions for requirements and troubleshooting.

The server listens on loopback only. Use SSH forwarding for a remote GPU. The default workbench limit is 8 million resident cells. For larger local projects, see memory admission and server limits.

Run from Python

This example runs a 3D waveguide on the fused CUDA path and saves both the project and its result:

from torchfdtd import Project, Region, Structure, Source, Monitor, Simulation

project = Project(
    name="My waveguide",
    region=Region(dimension="3d", size=(8, 6, 2), mesh=0.05, steps=1000,
                  backend="cuda", cuda_kernel="fused"),
    structures=[Structure(name="core", size=(8, 0.65, 0.4))],
    sources=[Source(center=(-2.5, 0, 0), wavelength=1.55)],
    monitors=[Monitor(name="output", center=(2, 0, 0))],
)
project.save("project.json")          # opens in the browser
result = Simulation(project).run()
result.save("results/run.npz")

Lengths are in µm and time arrays in seconds. dimension defaults to "2d" and cuda_kernel to "torch", so this example selects both explicitly. It needs an NVIDIA GPU and the cuda-kernels extra. Project.load() runs browser-made scenes.

from torchfdtd import Project, Structure, Source, Monitor, Simulation, Result

project = Project(name="Any install", structures=[Structure(name="core", size=(8, 0.65, 0.4))],
                  sources=[Source(center=(-2.5, 0, 0), wavelength=1.55)],
                  monitors=[Monitor(name="output", center=(2, 0, 0))])
result = Simulation(project).run()    # 2D, on the CPU or the CUDA device torch reports
result.save("results/first.npz")
print(Result.load("results/first.npz").summary["backend"])

git clone https://github.com/hyoseokp/TorchFDTD.git
cd TorchFDTD
python -m venv --system-site-packages .venv
.venv/Scripts/python.exe -m pip install -e ".[dev,cuda-kernels]"
npm.cmd ci
npm.cmd run build
.venv/Scripts/python.exe -m torchfdtd.cli serve

Examples

Each example includes its geometry, run commands and comparison results.

For complete design studies, follow the installed-wheel application workflows: metagrating, finite metalens and photonic integrated circuit, with fixed seeds and acceptance criteria.

Photonic-crystal waveguide

A pulse in a photonic-crystal line-defect waveguide. Actual 2D FDTD, showing instantaneous signed E_z with the dielectric rods outlined in gray. Full-resolution video · Model and recording details.

3D metalens focusing

A pulse focusing above a silicon-pillar metalens. Full 3D FDTD, rendered as a translucent volume of instantaneous E_x. Red and blue indicate opposite field signs, with one fixed scale throughout. Full-resolution video · Model and reproduction.

For gradients and optimization, start with differentiable FDTD and shape gradients. For larger studies, see parameter sweeps and tensor batches.

Core features

Performance and validation

The repository includes analytical tests, convergence and gradient checks, and comparisons with Meep, FDTDX and RCWA. Start with the worked device comparisons or the cross-solver benchmarks. Hardware, precision and problem size are recorded alongside the results.

Documentation

• Python and batch API, tensor batches, differentiable FDTD, shape gradients
• Streamed execution, planner, restart journal, beyond-VRAM records, propagated case
• Mode ports, far field, GDS, materials, boundaries
• Measurements and feature record, cross-solver comparison with Meep and FDTDX, worked comparisons with Meep, feature checklist, acceptance record
• Security model, compatibility and support policy, changelog, third-party notices and SBOM

Verification

python -m pytest -q
npm run test:ui

Validation uses analytical solutions, independently authored CPU/CUDA references, and the open-source solver comparisons linked above. No commercial solver results are used.

Citing TorchFDTD

If TorchFDTD contributes to published work, please cite the paper and the software on Zenodo. The Zenodo link opens the latest archived release. Citation metadata is available in CITATION.cff, which GitHub offers as "Cite this repository".

@misc{park2026torchfdtd,
  author        = {Park, Hyoseok},
  title         = {{TorchFDTD}: {GPU}-accelerated finite-difference time-domain simulation with discrete adjoints and host-streamed execution for photonic inverse design},
  year          = {2026},
  eprint        = {2609.30039},
  archivePrefix = {arXiv},
  primaryClass  = {physics.optics},
  doi           = {10.48550/arXiv.2609.30039},
  url           = {https://arxiv.org/abs/2609.30039}
}

@software{park_torchfdtd,
  author    = {Park, Hyoseok},
  title     = {{TorchFDTD}},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22928834},
  url       = {https://github.com/hyoseokp/TorchFDTD}
}

AI-assisted development

During the development of TorchFDTD, OpenAI GPT-6 Astra and Anthropic Claude Fable 5.1 were used as AI-assisted programming tools to support code prototyping, implementation, refactoring, debugging, test generation, and documentation. The authors defined the numerical formulations, physical assumptions, validation criteria, benchmark protocols, and acceptance thresholds, and reviewed the resulting implementation and numerical results. Solver correctness was independently assessed using analytical reference solutions, numerical convergence studies, finite-difference and automatic-differentiation gradient checks, independently implemented reference calculations, and CPU–GPU parity tests. The authors take full responsibility for the software, methodology, and results reported in this work.

Attribution

flaport/fdtd (MIT) supplies the grid foundation. PyTorch, NumPy, FastAPI, Three.js, Lucide and Vite keep their licenses. Contributions are welcome; back numerical changes with CPU/GPU parity checks and reproducible benchmark conditions. TorchFDTD is not affiliated with Ansys.