# Frequently Asked Questions (FAQs)

# What is Tidy3D?

Tidy3D is Flexcompute's ultrafast electromagnetic (EM) solver. The solver is based on the finite-difference time-domain (FDTD) method. Thanks to the highly optimized co-design of software and hardware, Tidy3D runs simulations orders of magnitude faster than other EM solvers on the market. With the lightning fast speed, you can also solve problems hundreds of wavelength in size, which is often not feasible with conventional approaches.

# How can I install the Python client of Tidy3d?

We recommend using the Conda package management system to manage your Python virtual environment as well as installing Tidy3D. To avoid package version incapability issues, we recommend creating a new Conda environment and install Tidy3D via pip. Please follow the detailed installation instructions here (opens new window). If you encounter any issues during installation, please reach out to us and we will provide the necessary help to you in a timely manner.

# Can I do a free trial to evaluate the capabilities of Tidy3D before purchasing it?

Yes. If you are new to Tidy3D and would like to experience the ultrafast electromagnetic simulations, you can apply for a free trial which allows you to test a good number of small to medium sized simulations. The goal of the free trial is to get you familiarized with Tidy3D and evaluate its capabilities on your project. During the trial period, we provide full technical support to answer any questions you might have about using Tidy3D.

# Can I get a discount as a student or teacher?

Yes, we offer special pricing for graduate students, postdocs, and faculties of eligible universities. Go to your Account (opens new window) to apply.

# What are the advantages of Tidy3D compared to traditional EM simulators?

There are several unique advantages that set Tidy3D apart from other tradition EM simulators.

First of all, Tidy3D provides cloud-based simulation services. Our users do not need to purchase nor manage their own dedicated computer hardware, which is a great time and cost saving.

Secondly, Tidy3D utilizes a proprietary co-design of software and hardware. The end result is the lightning fast simulation speed and scalability. Compared to traditional CPU-based EM simulators, Tidy3D is orders of magnitude faster, which enables short R&D design cycle.

Lastly, Tidy3D not only has a feature-rich web GUI, but also fully embraces the flexible Python environment. Our users can construct simulations either using the GUI or Python scripts.

# How is using Tidy3D billed? what is a FlexCredit?

The Tidy3D Python client that is used for designing simulations and analyzing the results is free and open source. We only bill the simulations run on our server. When a simulation is uploaded to our servers, we will print the maximum estimated cost in FlexCredit. This cost is also displayed in the online interface for that simulation. This value is determined by the cost associated with simulating the entire time stepping specified. If early shutoff is detected and the simulation completes before the full time stepping period, this cost will be the greater of the pro-rated or 1/3 of the estimated cost.

# How to submit a simulation in Python to the server?

Submitting a simulation to our cloud server is very easily done by a simple web API call. First define a job by

job = web.Job(simulation, task_name)

Then submit the job by using the run method as

sim_data = job.run(path)

After the simulation is complete, result data will be automatically returned to sim_data.

# Do I have to know Python programming to use Tidy3D?

Tidy3D simulations can be defined in two ways: our web GUI or Python scripts. If you do not have Python programming experience, you can use our feature-rich web GUI to define simulation, submit simulation, and visualize simulation results.

Since defining simulation and performing post-processing in Python offers additional flexibity, we do recomment our users to learn to use Python, especially for more complex simulations. There are a lot of great free resources for learning Python online. You can also reference our Python API documentation as well as a variety of examples in our documentation site (opens new window).

# Why is my simulation diverging?

Sometimes, a simulation is numerically unstable and can result in divergence. All known cases where this may happen are related to PML boundaries and/or dispersive media. Below is a checklist of things to consider.

# What source bandwidth should I use for my simulation?

Tidy3D's broadband source feature is designed to produce the most accurate results in the frequency range of (freq0 - 1.5 * fwidth, freq0 + 1.5 * fwidth). Therefore, it is necessary to define the source center frequency freq0 and bandwidth fwidth to properly cover the desired application frequency range. For example, if the user wants to adjust the source bandwidth to cover a wavelength range between wl_min and wl_max, the source bandwidth can be defined as: fwidth = alpha * (C_0/wl_max - C_0/wl_min), where alpha is a constant typically chosen between 1/3 and 1/2 to ensure accurate results.

# Why did my simulation finish early?

By default, Tidy3D checks periodically the total field intensity left in the simulation, and compares that to the maximum total field intensity recorded at previous times. If it is found that the ratio of these two values is smaller than , the simulation is terminated as the fields remaining in the simulation are deemed negligible. The shutoff value can be controlled using the Simulation.shutoff (opens new window) parameter, or completely turned off by setting it to zero. In most cases, the default behavior ensures that results are correct, while avoiding unnecessarily long run times.

# Should I make sure that fields have fully decayed by the end of the simulation?

Conversely to early termination, you may sometimes get a warning that the fields remaining in the simulation at the end of the run have not decayed down to the pre-defined shutoff value. This should usually be avoided (that is to say, Simulation.run_time (opens new window) should be increased), but there are some cases in which it may be inevitable. The important thing to understand is that in such simulations, frequency-domain results cannot always be trusted. The frequency-domain response obtained in the FDTD simulation only accurately represents the continuous-wave response of the system if the fields at the beginning and at the end of the time stepping are (very close to) zero. That said, there could be non-negligible fields in the simulation yet the data recorded in a given monitor can still be accurate, if the leftover fields will no longer be passing through the monitor volume. From the point of view of that monitor, fields have already fully decayed. However, there is no way to automatically check this. The accuracy of frequency-domain monitors when fields have not fully decayed is also discussed in one of our FDTD 101 videos (opens new window).

The main use case in which you may want to ignore this warning is when you have high-Q modes in your simulation that would require an extremely long run time to decay. In that case, you can use the the ResonanceFinder (opens new window) plugin to analyze the modes, as well as field monitors with apodization to capture the modal profiles. The only thing to note is that the normalization of these modal profiles would be arbitrary, and would depend on the exact run time and apodization definition. An example of such a use case is presented in our high-Q photonic crystal cavity case study (opens new window).

# What are the units used in the simulation?

We generally assume the following physical units in component definitions:

  • Length: micron (μm, 10 meters)
  • Time: Second (s)
  • Frequency: Hertz (Hz)
  • Electric conductivity: Siemens per micron (S/μm)

Thus, the user should be careful, for example to use the speed of light in μm/s when converting between wavelength and frequency. The built-in speed of light C_0 (opens new window) has a unit of μm/s.

For example:

wavelength_um = 1.55
freq_Hz = td.C_0 / wavelength_um
wavelength_um = td.C_0 / freq_Hz

Currently, only linear evolution is supported, and so the output fields have an arbitrary normalization proportional to the amplitude of the current sources, which is also in arbitrary units. In the API Reference, the units are explicitly stated where applicable.

Output quantities are also returned in physical units, with the same base units as above. For time-domain outputs as well as frequency-domain outputs when the source spectrum is normalized out (default), the following units are used:

  • Electric field: Volt per micron (V/μm)
  • Magnetic field: Ampere per micron (A/μm)
  • Flux: Watt (W)
  • Poynting vector: Watt per micron squared (W/μm)
  • Modal amplitude: Sqare root of watt (W)

If the source normalization is not applied, the electric field, magnetic field, and modal amplitudes are divided by Hz, while the flux and Poynting vector are divided by Hz.

# How do I include material dispersion?

Dispersive materials are supported in Tidy3D and we provide an extensive material library (opens new window) with pre-defined materials. Standard dispersive material models (opens new window) can also be defined. If you need help inputting a custom material, let us know!

It is important to keep in mind that dispersive materials are inevitably slower to simulate than their dispersion-less counterparts, with complexity increasing with the number of poles included in the dispersion model. For simulations with a narrow range of frequencies of interest, it may sometimes be faster to define the material through its real and imaginary refractive index at the center frequency. This can be done by defining directly a value for the real part of the relative permittivity and electric conductivity of a Medium (opens new window), or through a real part and imaginary part . The relationship between the two equivalent models is , , and .

In the case of (almost) lossless dielectrics, the dispersion could be negligible in a broad frequency window, but generally, it is important to keep in mind that such a material definition is best suited for single-frequency results.

For lossless, weakly dispersive materials, the best way to incorporate the dispersion without doing complicated fits and without slowing the simulation down significantly is to provide the value of the refractive index dispersion in Sellmeier.from_dispersion() (opens new window). The value is assumed to be at the central frequency or wavelength (whichever is provided), and a one-pole model for the material is generated. These values are for example readily available from the refractive index database (opens new window).

# Can I import my own tabulated material data?

Yes, users can import their own tabulated material data and fit it using one of Tidy3D's dispersion fitting tools. The DispersionFitter (opens new window) tool performs an optimization to find a medium defined as a dispersive PoleResidue model that minimizes the RMS error between the model results and the data. The user can provide data through one of the following methods:

  • Numpy arrays directly by specifying wvl_um, n_data, and optionally k_data.

  • A data file with the from_file utility function. The data file has columns for wavelength (), the real part of the refractive index (), and the imaginary part of the refractive index (). data is optional. Note: from_file uses np.loadtxt under the hood, so additional keyword arguments for parsing the file follow the same format as np.loadtxt.

  • URL link to a CSV/TXT file that contains wavelength (), , and optionally data with the from_url utility function. URL can come from refractiveindex (opens new window). The StableDispersionFitter (opens new window) tool implements our proprietary stability criterion. Functionally speaking, it works identically to the previous tool, except the .fit() method is run on Flexcompute servers. Therefore, this tool requires signing in to a Tidy3D account. We observe consistently stable FDTD simulations when materials are fit using this method.This notebook (opens new window) provides detailed instructions and examples of using both DispersionFitter (opens new window) and StableDispersionFitter (opens new window) to create customized materials based on refractive index tabulated data.

# How are results normalized?

In many cases, Tidy3D simulations can be run and well-normalized results can be obtained without normalizing/empty runs. This is because care is taken internally to normalize the injected power, as well as the output results, in a meaningful way. To understand this, there are two separate normalizations that happen, outlined below. Both of those are discussed with respect to frequency-domain results, as those are the most commonly used.

# Source spectrum normalization

Every source has a spectrum associated to its particular time dependence that is imprinted on the fields injected in the simulation. Usually, this is somewhat arbitrary and it is most convenient for it to be taken out of the frequency-domain results. By default, after a run, Tidy3D normalizes all frequency-domain results by the spectrum of the first source in the list of sources in the simulation. This choice can be modified using the Simulation.normalize_index (opens new window) attribute, or normalization can be turned off by setting that to None. Results can even be renoramlized after the simulation run using SimulationData.renormalize() (opens new window). If multiple sources are used, but they all have the same time dependence, the default normalization is still meaningful. However, if different sources have a different time dependence, then it may not be possible to obtain well-normalized results without a normalizing run.

This type of normalization is applied directly to the frequency-domain results. The custom pulse amplitude and phase defined in SourceTime.amplitude (opens new window) and SourceTime.phase (opens new window), respectively, are not normalized out. This gives the user control over a (complex) prefactor that can be applied to scale any source. Additionally, the power injected by each type of source may have some special normalization, as outlined below.

# Source power normalization

Source power normalization is applied depending on the source type. In the cases where normalization is applied, the actual injected power may differ slightly from what is described below due to finite grid effects. The normalization should become exact with sufficiently high resolution. That said, in most cases the error is negligible even at default resolution.

The injected power values described below assume that the source spectrum normalization has also been applied.

The correct usage for a PlaneWave (opens new window) source is to span the whole simulation domain for a simulation with periodic (or Bloch) boundaries, in which case the normalization of this technically infinite source is equivalent to 1W per unit cell. For the other sources which have a finite extent, the normalization is correct provided that the source profile decays by the boundaries of the source plane. Verifying that this is the case is always advised, as otherwise results may be spurious beyond just the normalization (numerical artifacts will be present at the source boundary).

# How fine of a grid or mesh does my simulation need? How to choose grid spec?

The FDTD and other similar numerical methods will always give approximate results for a set of finite-difference equations. The accuracy of Maxwell's equations solution for any geometry can be arbitrarily increased by using smaller and smaller values of the space and time increments. This strategy often involves increased simulation time and memory, so it is essential to consider, for your application, what is the desired accuracy in results so that you can run your simulations as quickly as possible. As a gold rule of thumb, ten grid points per wavelength in the highest refractive index medium should be a good starting value for the grid resolution. However, other application specificities must be considered when defining the appropriate simulation mesh, such as very thin geometries or large electric field gradients, as usually occurs, for example, in the presence of resonances, highly confined fields, or at metal-dielectric interfaces.

Tidy3D has many features to give the user a simple and flexible way to build the simulation mesh. The GridSpec (opens new window) object enables the user to chose between an AutoGrid (opens new window), a UniformGrid (opens new window), or a CustomGrid (opens new window), at each of the simulation x-, y-, z-direction. An example code snippet is shown below:

uniform = td.UniformGrid(dl=0.1)

custom = td.CustomGrid(dl=[0.2, 0.2, 0.1, 0.1, 0.1, 0.2, 0.2])
auto = td.AutoGrid(min_steps_per_wvl=12)
grid_spec = td.GridSpec(grid_x=uniform, grid_y=custom, grid_z=auto, wavelength=1.5)

More examples of setting up the simulation mesh are available on this notebook (opens new window).

In general, a good strategy is to start with the default object AutoGrid (opens new window) to discretize the whole simulation domain and fine-tune the mesh by increasing the grid resolution at directions or regions containing smallest geometric features or high field gradients or even relaxing the discretization along directions of invariant geometry, e.g., the propagation direction of channel waveguides. The definition of an override structure is an efficient way to improve simulation accuracy while keeping small the run time.

# How to use the automatic nonuniform meshing? What steps per wavelength will be sufficient?

By default, Tidy3D configures the GridSpec (opens new window) object to having AutoGrid (opens new window), which is an advanced meshing algorithm to automatically define a nonuniform grid, in all the three domain direction. The resolution of this grid is specified using the desired minimum steps per wavelength in each material (min_steps_per_wvl = 10 by default). This specification, therefore, requires a target wavelength, which can be either provided directly to grid_spec or inferred from any sources present in the simulation. Detailed examples on how to set up AutoGrid (opens new window) are present on this notebook (opens new window).

As a gold rule of thumb, the default value of 10 grid points per wavelength should be a good starting value for min_steps_per_wvl. However, other application-specific features must be considered when defining the appropriate simulation mesh, such as very thin geometries or large electric field gradients, as can usually occur, for example, in the presence of resonances, highly confined fields, or at metal-dielectric interfaces. Additional control over the mesh is obtained by the dl_min parameter, which imposes a lower bound of the grid size regardless of the structures present in the simulation, including override structures with enforced=True. This is, however, a soft bound, meaning that the actual minimal grid size might be slightly smaller. Finally, the max_scale sets the maximum ratio between two consecutive grid steps. Different grid configurations can be chosen for each direction, as illustrated bellow:

grid_spec = td.GridSpec(
grid_x=td.AutoGrid(min_steps_per_wvl=20,dl_min=0.01),
grid_y=td.AutoGrid(min_steps_per_wvl=15),
grid_z=td.AutoGrid(min_steps_per_wvl=10,max_scale=1.6),
wavelength=1.0,
)

# How to run a 2D simulation in Tidy3D?

To run 2D simulations in Tidy3D, set the simulation size in one dimension to 0 (td.Simulation(size=[size_x, size_y, 0])). Additionally, specify a Periodic (opens new window) boundary condition in that direction. For an example of running a 2D simulation in Tidy3D, see this 2D ring resonator example notebook (opens new window).

# Can I have structures larger than the simulation domain?

Structures can indeed be larger than the simulation domain in Tidy3D. In such cases, Tidy3D will automatically truncate the geometry that goes beyond the domain boundaries. For best results, structures that intersect with absorbing boundaries or simulation edges should extend all the way through. In many such cases, an "infinite" size td.inf can be used to define the size along that dimension.

# Why can I not change Tidy3D instances after they are created?

You may notice in Tidy3D versions 1.5 and above that it is no longer possible to modify instances of Tidy3D components after they are created. Making Tidy3D components immutable like this was an intentional design decision intended to make Tidy3D safer and more performant.

For example, Tidy3D contains several “validators” on input data. If models are mutated, we can’t always guarantee that the resulting instance will still satisfy our validations and the simulation may be invalid.

Furthermore, making the objects immutable allows us to cache the results of many expensive operations. For example, we can now compute and store the simulation grid once, without needing to worry about the value becoming stale at a later time, which significantly speeds up plotting and other operations.

If you have a Tidy3D component that you want to recreate with a new set of parameters, instead of obj.param1 = param1_new, you can call obj_new = obj.copy(update=dict(param1=param1_new)). Note that you may also pass more key value pairs to the dictionary in update.