Installation

Install Maxwell from PyPI with a CUDA build of PyTorch, then check that the native FDTD kernels load on your GPU.

Maxwell is published on PyPI as witwin-maxwell. The release wheels carry a prebuilt native CUDA library, so you do not need a CUDA toolkit or a compiler.

Requirements#

RequirementSupported
Operating systemWindows x86_64, Linux x86_64 (manylinux_2_28)
PythonCPython 3.10 to 3.14
PyTorch2.10 or newer, CUDA build (tested with 2.10 and 2.11 on CUDA 12.8, 2.12 and 2.13 on CUDA 12.6)
GPUNVIDIA, compute capability 7.0 or newer (Volta, Turing, Ampere, Ada, Hopper, Blackwell)
NVIDIA driverOne that supports the CUDA 12.x runtime of your PyTorch build. For full CUDA 12.8 and Blackwell support use at least 570.26 (Linux) or 570.65 (Windows).
Base packagewitwin 0.4.x, installed automatically

macOS and CPU-only machines are not supported: FDTD and FDFD raise an error when the scene device is not CUDA.

Install#

  1. Install a CUDA build of PyTorch

    Install PyTorch first, from the PyTorch index that matches your driver. Installing witwin-maxwell alone can pull a CPU-only PyTorch from PyPI on Windows.

    pip install torch --index-url https://download.pytorch.org/whl/cu128

  2. Install Maxwell

    pip install witwin-maxwell

    This installs witwin-maxwell 0.5.1 and its dependencies: witwin (0.4.x), NumPy, SciPy, Matplotlib, tqdm and IPython.

  3. Optional: install the direct sparse solver for FDFD

    FDFD uses an iterative GMRES solver by default. The direct extras add NVIDIA cuDSS through nvmath-python for a direct sparse solve.

    pip install "witwin-maxwell[direct]"

    Use witwin-maxwell[direct-cu13] on a CUDA 13 stack.

Verify the install#

Run this script. It prints the installed versions, confirms PyTorch sees your GPU, and runs a tiny FDTD simulation, which loads the native CUDA library.

import importlib.metadata as md
 
import torch
import witwin.maxwell as mw
 
print("witwin-maxwell", md.version("witwin-maxwell"), "| witwin", md.version("witwin"))
print("torch", torch.__version__, "| CUDA available:", torch.cuda.is_available())
 
scene = mw.Scene(
    domain=mw.Domain(bounds=((-0.3, 0.3), (-0.3, 0.3), (-0.3, 0.3))),
    grid=mw.GridSpec.uniform(0.03),
    boundary=mw.BoundarySpec.pml(num_layers=6),
    device="cuda",
)
scene.add_source(mw.PointDipole(position=(0.0, 0.0, 0.0), polarization="Ez", source_time=mw.GaussianPulse(frequency=1e9, fwidth=0.3e9)))
scene.add_monitor(mw.PointMonitor("probe", (0.1, 0.0, 0.0), fields=("Ez",)))
result = mw.Simulation.fdtd(scene, frequencies=[1e9], run_time=mw.TimeConfig(time_steps=200)).run()
print("probe Ez:", result.monitor("probe")["data"])

Expected output on a working machine (versions and the probe value differ):

witwin-maxwell 0.5.1 | witwin 0.4.0
torch 2.11.0+cu128 | CUDA available: True
probe Ez: tensor(...+...j, device='cuda:0')

Troubleshooting#

SymptomCause and fix
Simulation.fdtd(...) requires CUDA, but torch.cuda.is_available() is False.PyTorch is a CPU build, or the process cannot see the GPU. Reinstall PyTorch from a CUDA index, and check CUDA_VISIBLE_DEVICES and container device access.
Simulation.fdtd(...) requires scene.device to be CUDA, got cpu.The scene was built with device="cpu". Pass device="cuda" (the default) to Scene.
No module named 'witwin.maxwell'witwin-maxwell is not installed in the active environment. pip show witwin-maxwell tells you.
The first run tries to compile CUDA codeThe prebuilt library was skipped or does not match. This happens when WITWIN_MAXWELL_FDTD_CUDA_SKIP_PREBUILT=1 is set, or with a source install. A source build needs the CUDA toolkit (nvcc) and, on Windows, Visual Studio build tools.

Install from source#

Clone the repository and install it in editable mode when you want to change Maxwell itself:

git clone https://github.com/witwin-ai/witwin-maxwell.git
cd witwin-maxwell
pip install -e .

A source checkout has no prebuilt library, so the first FDTD run compiles the CUDA extension with PyTorch's JIT build into your temp folder (witwin_maxwell_fdtd_cuda). Set WITWIN_MAXWELL_FDTD_CUDA_BUILD_DIR to choose another folder.

Next steps#

Quickstart

Run a full simulation and take a gradient.

GPU backends

How the native CUDA library is loaded and which GPUs it targets.