Tidy3D

2.11.1 verified Mon Apr 27 auth: no python

A fast FDTD solver for electromagnetic simulations, developed by Flexcompute. Current version is 2.11.1, with a rapid release cadence (multiple minor versions per month). Requires Python >=3.10, <3.15.

pip install tidy3d

Common errors

error ModuleNotFoundError: No module named 'tidy3d' ↓

cause Tidy3D not installed or installed in a different environment.

fix

Run 'pip install tidy3d' in your active environment.

error pydantic.error_wrappers.ValidationError: 1 validation error for Simulation size field required (type=value_error.missing) ↓

cause Missing required parameter in simulation constructor.

fix

Ensure all required parameters (size, run_time, etc.) are provided. Check documentation for defaults.

error web.RunError: Authentication failed. Check your API key. ↓

cause Invalid or missing TIDY3D_API_KEY.

fix

Set environment variable TIDY3D_API_KEY or run 'tidy3d configure' to set credentials.

error ValueError: Grid size too small: at least 10 grid steps per wavelength are recommended. ↓

cause GridSpec.auto() with too few steps per wavelength.

fix

Increase min_steps_per_wvl (e.g., 20) or manually specify a finer grid.

Warnings

gotcha Default units are micrometers (um), but frequencies are in Hz. Ensure size, center, and wavelength-related parameters are consistent. ↓

fix Use si_units=True in simulation constructor to switch to meters, or manually convert.

deprecated The 'adjoint' plugin API changed with pydantic v2 migration in 2.10.0rc3. Old code using 'td.adjoint' may break. ↓

fix Use the new API via tidy3d.plugins.adjoint. Refer to migration guide.

gotcha When using cloud execution, you must set the TIDY3D_API_KEY environment variable or configure credentials via 'tidy3d configure'. ↓

fix Run 'tidy3d configure' or set environment variable TIDY3D_API_KEY=your_api_key.

breaking numpy>=2.4 is not supported (as of 2.10.1). Installing tidy3d with numpy 2.4 may cause errors. ↓

fix Downgrade numpy to <2.4, or upgrade tidy3d to 2.10.2+ which includes a patch.

gotcha The 'run_time' parameter must be long enough for the pulse to decay; otherwise, the simulation may error. ↓

fix Estimate run_time as n_periods / fwidth where n_periods is at least 10-20.

Install

pip install tidy3d[all]

Imports

Simulation
```
import tidy3d as td
sim = td.Simulation(...)
```
All components are accessible via the tidy3d namespace.

web

from tidy3d import web
web.run(simulation, task_name='my_task')

web is a submodule for cloud execution.

adjoint

import tidy3d as td
import tidy3d.plugins.adjoint as tda
# or: from tidy3d.plugins.adjoint import ...

Adjoint plugin is in tidy3d.plugins.adjoint.

plugins

from tidy3d.plugins import dispersion, mode, ...

Various plugins live under tidy3d.plugins.

Quickstart

Creates a basic waveguide with a point dipole source and field monitor. For cloud execution, uncomment the web.run() call and set your API key via environment variable TIDY3D_API_KEY.

import tidy3d as td
import numpy as np

# Define a simple waveguide simulation
sim = td.Simulation(
    size=(4.0, 2.5, 2.0),
    grid_spec=td.GridSpec.auto(min_steps_per_wvl=10),
    boundary_spec=td.BoundarySpec.pml(x=False, y=True, z=True),
    structures=[
        td.Structure(
            geometry=td.Box(center=(0, 0, 0), size=(td.inf, 0.5, 0.22)),
            medium=td.Medium(permittivity=2.0)
        )
    ],
    sources=[
        td.PointDipole(
            center=(-1.5, 0, 0),
            polarization='Ex',
            source_time=td.GaussianPulse(freq0=200e12, fwidth=40e12)
        )
    ],
    monitors=[
        td.FieldMonitor(center=(0,0,0), size=(0,0,0), freqs=[200e12], name='point')
    ],
    run_time=1e-12
)

# Run locally (requires solver; for cloud use: web.run(sim, task_name='test'))
# data = web.run(sim, task_name='quickstart')
print('Simulation created successfully.')