How do I …#

Work with the Tidy3d Package#

How do I…


See the version of tidy3d I am using?

In python, after importing tidy3d, run print(tidy3d.__version__). Or, do this through the command line via python -c “import tidy3d; print(tidy3d.__version__)”.

Work with Tidy3d Components#

How do I…


Get help related to a Tidy3d object (obj)? or help(Obj) if Obj is the class name (eg. help(td.Box)).

Save and load any Tidy3d object?

If the object obj is an instance of ObjClass, save and load with obj.to_file(fname='path/to/file.json') and obj = ObjClass.from_file(fname='path/to/file.json'), respectively.

Get all data in a Tidy3d object as a dictionary.


Plot Tidy3D Components#

How do I…


Plot an object with a spatial definition? (Simulation, Structure, etc.)

obj.plot(x=0) will plot the object on the x=0 plane, but y and z are alternatively accepted to specify other planar axes. If ax argument will plot to an existing axis, ie. obj.plot(y=0, ax=ax).

Change the object plotting characteristics (facecolor, edgecolor, etc).

Plotting keyword arguments can be supplied to plot(), for example obj.plot(x=0, edgecolor='blue', fill=False). These keyword arguments correspond to those fed to Matplotlib Patches.

Change the global plot characteristics (title, size, etc).

The plotting function return a matplotlib Axes, wihch can be manipulated, for example ax = obj.plot(x=0);  ax.set_title('my_title').

Create Geometries#

How do I…


Load a structure from GDS format?

From a cell in the gdstk package, the ps = td.PolySlab.from_gds(gds_cell, ...) method will load the geometry into a PolySlab.

Create a complex geometry, such as a ring?

While many complex geometries can be created by supplying the vertices to PolySlab, simple geometries, such as rings, can be constructed by overlaying two structures with Cylinder geomety with the inner cylinder defined with medium of air. Note that structures later in the structures list will override previous structures, which can be leveraged to make more complex geometries.


How do I…


Create a lossy material (with a conductivity)?

td.Medium(permittivity=2.0, conductivity=1.0)

Create a material from n, k values at a given frequency?

td.Medium.from_nk(n=2.0, k=1.0, freq=200e12)

Create an anisotropic material?

td.AnisotropicMedium(xx=medium_xx, yy=medium_yy, zz=medium_zz) for three td.Medium objects defining the diagonal elements of the permittivity tensor.

Create a dispersive material from model parameters?

Call one of the dispersive models with your parameters, for example debye_medium = td.Debye(eps_inf=2.0, coeffs=[(1,2),(3,4)]).

Create an active material?

Tidy3D by default will not allow medium specifications that give rise to active materials to avoid potential divergence. However, you can override this by setting the field allow_gain=True in any medium, e.g. td.Medium(permittivity=2.0, conductivity=-1.0, allow_gain=True)

Create a spatially varying material?

Call one of the “Custom-” materials, e.g. CustomMedium for a spatially varying non-dispersive medium.

Load a commonly-used dispersive material?

Import one of several material models from our td.material_library.

Work with Simulation Data#

How do I…


Load the data from a simulation task id task_id into the python client?

Using the web API import tidy3d.web as web, you can load into a SimulationData object through sim_data = web.load(task_id, path='path/to/file.hdf5').

Access the original Simulation that created the data?

sim_data.simulation returns a copy of the original Simulation.

Print the log file of the task?


Save and load the SimulationData object?

sim_data.to_file(fname='path/to/file.hdf5') to save and sim_data = SimulationData.from_file(fname='path/to/file.hdf5') to load.

Access the data for a specific Monitor?


Interpolate the electromagnetic field data at the Yee cell centers?

sim_data.at_centers(monitor_name) if monitor_name corresponds to a FieldMonitor or FieldTimeMonitor.

Work with Monitor Data#

How do I…


Get my monitor’s data from a SimulationData object?

mon_data = sim_data[monitor_name] where monitor_name was the .name of the original monitor.

Select the data at a certain coordinate value (ie. x=0.0, f=200e12?

mon_data.sel(z=0, f=200e12).

Get the data at certin index into a coordinate (ie t=3 for the 4th measured time step)?


Interpolate the data at various coordinate values, eg. field data at the origin (x=y=z=0)?

mon_data.interp(x=0, y=0, z=0) performs linear interpolation of the data, where the values must be within the range recorded by the original monitor specification.

Get the real part, imagninary part, or absolute value of complex-valued data.

mon_data.real, mon_data.imag, abs(mon_data), respectively.

Get the raw data values as a numpy array?


Get a specific field component (eg. 'Hy') for a FieldMonitor or FieldTimeMonitor?

component_data = sim_data[monitor_name].Hy or, to access by string: component_data = sim_data[monitor_name].data_dict['Hy'].

Plot Data#

How do I…


Plot the MonitorData as a function of one of its coordinates.

mon_data.plot() if the data is already 1D. To select x axis explicitly or plot all the data on same plot, mon_data.plot.line(x='f', ax=ax). Note, for all plotting, if ax not supplied, will be created.

Plot the MonitorData as a function of two of its coordinates?

mon_data.plot() if data is 2D, otherwise one can use mon_data.plot.pcolormesh(x='x', y='y') to specify the x and y coordinates explicitly.

Plot the simulation structure on top of my field plot?

sim_data.plot_field(monitor_name, component, z=3, val='real', **kwargs) to plot the real part of the fields on the z=3 plane.

Submit Jobs to Server#

How do I…


Submit my simulation to run on Flexcompute’s servers?

sim_data =, task_name='my_task', path='out/data.hdf5') or job = web.Job(simulation, task_name='my_task');'out/data.hdf5').

Upload a job to the web without running it so I can inspect it first?

Once you’ve created a tidy3d.web.container.Job, you can upload it to our servers with job.upload() and it will not run until you excplicitly tell it to with job.start().

Monitor the progress of a simulation?

web.monitor(task_id), job.monitor(), or batch.monitor() will display the progress of your simulation(s).

Load the results of a simulation?

sim_data = job.load(path) will download the results to path and load them as SimulationData object.

See information about my tidy3d.web.container.Job, such as how many credits it will take?

After uploading your job with job.upload() you can get a host of information about it through task_info = job.get_info().

Submit multiple simulations?

The tidy3d.web.container.Batch interface was created to manage multiple tidy3d.web.container.Job instances and gives a similar interface with large number of jobs in mind.

Loop through tidy3d.web.container.BatchData without loading all of the data into memory?

for task_name, sim_data in batch_data.items(): will give access to a SimulationData instance for each tidy3d.web.container.Job in the batch one by one, so you can perform your postprocessing in the loop body without loading each of the simulations’ data into memory at once.

Save or load a tidy3d.web.container.Job or tidy3d.web.container.Batch so I can work with it later?

Like most other tidy3d objects, tidy3d.web.container.Job and tidy3d.web.container.Batch instances have .to_file(path) and .from_file(path) methods that will export and load thier metadata as .json files. This is especially useful for loading batches for analysis long after they have run.


How do I…


Create a material from optical n,k data?

Refer to the Dispersion tutorial on the tidy3d.plugins.DispersionFitter plugin.

Specify the modes for a ModeMonitor or ModeSource?

Refer to the Mode Solver tutorial on the tidy3d.plugins.ModeSolver plugin.

Projet electromagnetic near field data to the far field?

Refer to the FieldProjections tutorial.

Compute scattering matrix parameters for modeling my device?

Refer to the S Matrix tutorial on the tidy3d.plugins.ComponentModeler plugin.