Start Here

This page will get you set up with Tidy3D and running a simple example.

Before using Tidy3D, you must first sign up for a user account.

Quick Start (Colab Notebook)

To get started right away without any installation or software setup, this google colab link will take you to a simple example of a Tidy3D simulation of a 3D box.

To run the example, click the arrow immediately to the left of the code block.

You will first be prompted to log in using the email and passord you used for your user account.

Then the notebook will create a simulation and upload it to our server, where it will run for a few minutes before downloading the results and plotting the field patterns.


To play around with the simulation parameters, create your own editable copy of the notebook by navigating to [File -> Save a Copy in Drive] from that file and running the same way.

Python Installation

If you have python set up on your computer and wish to run the python API locally, installation is simple.

Tidy3D and its dependencies can be installed from the command line by

$ pip install tidy3d

To test whether the code is working, one can download and run an example script

$ curl --output
$ python

If you wish, the same example script can be downloaded at this link or simply copied and pasted from the following block of code.

# External package import
import numpy as np
import matplotlib.pyplot as plt

# tidy3d import
import tidy3d as td
from tidy3d import web

# set up parameters of simulation
resolution = 20
sim_size = [4, 4, 4]
pml_layers = [resolution, resolution, resolution]
fcen = 3e14
fwidth = 1e13
run_time = 2/fwidth

# create structure
material = td.Medium(n=2.0, k=0.2, freq=fcen)
square = td.Box(center=[0, 0, 0], size=[1.5, 1.5, 1.5], material=material)

# create source
source = td.PlaneWave(
    source_time = td.GaussianPulse(

# create monitor
freq_mnt = td.FreqMonitor(center=[0, 0, 0], size=[6, 0, 6], freqs=[fcen], name='xz plane')

# Initialize simulation
sim = td.Simulation(size=sim_size,

# run simulation
project = web.new_project(sim.export(), task_name='quickstart')

# download results
web.download_results(project['taskId'], target_folder='out/')

# plot results
clim = (1, 3)
fig, (ax_top, ax_bot) = plt.subplots(2, 2, figsize=(9, 7), tight_layout=True)

sim.viz_eps_2D(normal='y', ax=ax_top[0], cbar=True, clim=clim, monitor_alpha=0)
im_re = sim.viz_field_2D(freq_mnt, ax=ax_top[1], cbar=True, comp='y', val='re')

im_ab = sim.viz_field_2D(freq_mnt, ax=ax_bot[0], cbar=True, comp='y', val='abs')
im_int = sim.viz_field_2D(freq_mnt, ax=ax_bot[1], cbar=True, comp='y', val='int')

The same plots should be produced.

Next Steps

That should get you started!

To see some other examples of Tidy3D being used in large scale photonics simulations, see Examples

To learn more about the many features of Tidy3D, check out our Feature Walkthrough

Or, if you’re interested in the API documentation, see API Reference