Frequently Asked Questions

The Tidy3D client that is used for designing simulations and analyzing the results is free and open source. We only bill the run time of the solver on our server, taking only the compute time into account (as opposed to overhead, e.g., during uploading). When a task is uploaded to our servers, we will print the maximum incurred cost in FlexCredit. This cost is also displayed in the online interface for that task. This value is determined by the cost associated with simulating the entire time stepping specified. This cost will be pro-rated if early shutoff is detected and the simulation is completed before the time stepping period. For more questions or to purchase FlexCredit, please contact us at support@flexcompute.com. 

FlexCredit is Flexcompute’s way of measuring computing power. It’s a unit we created to make it easier to understand and buy computing power.

One FlexCredit is equivalent to about 50 hours of CPU core time when using the traditional FDTD method. That’s the equivalent of running a computer processor core for two days straight, just for one FlexCredit! If you have 60 FlexCredits, it’s like having a 4-core CPU (which is a pretty powerful computer) running non-stop, 24 hours a day, for a full month.

This makes it simple for our customers and employees. Instead of trying to communicate in terms of CPU hours or cores, they just need to know how many FlexCredits they need for their project. It’s like buying time on a supercomputer but in a more straightforward, more understandable way.

One FlexCredit is equivalent to about 50 hours of CPU core time when using the traditional FDTD method. That’s the equivalent of running a computer processor core for two days straight, just for one FlexCredit!

If you have 60 FlexCredits, it’s like having a 4-core CPU (which is a pretty powerful computer) running non-stop, 24 hours a day, for an entire month.

Tidy3D comes with a feature-rich graphical user interface (GUI) that offers many tools to create and run electromagnetic simulations with ease and intuitiveness. With Tidy3D GUI, you can quickly analyze simulation results, conduct parameter sweeps, perform mode analysis, access simulation information, and manage your account. Additionally, a complete Python notebook development environment is included, allowing you to utilize the flexibility of Tidy3D Python without installing the client interface.

Yes. Suppose you are new to Tidy3D and would like to experience ultrafast electromagnetic simulations. In that case, you can apply for a free trial, which allows you to test many small to medium-sized simulations. The free trial aims to familiarize you with Tidy3D and evaluate its capabilities for your project. During the trial period, we provide full technical support to answer any questions you might have about using Tidy3D.

If you need help with a Tidy3D object, you can run the command: help(<class name>) or <class name>.help() where <class name> is the name of the object class (e.g., Box). You can also refer to the Tidy3D Python documentation to find information on objects and their usage. Additionally, you can search for more details on object usage in the Learning Center.

If you want to try Tidy3D, you don’t need to install Python. First, you’ll need to   sign up for a free user account. Then you can try both, the feature-rich Tidy3D GUI interface and a pre-installed Tidy3D Python notebook development environment.

Submitting and monitoring jobs and downloading the results are all done through our web API. After a successful run, all data for all monitors can be downloaded in a single .hdf5 file using tidy3d.web.load(), and the raw data can be loaded into a SimulationData object.

From the SimulationData object, one can grab and plot the data for each monitor with square bracket indexing, inspect the original Simulation object, and view the log from the solver run. For more details, see this beginer tutorial and this advanced tutorial.

After the simulation is complete, you can load the results into a SimulationData object by its task_id using:

sim_data = web.load(task_id, path="outt/sim.hdf5", verbose=verbose)

The web.load() method is very convenient to load and postprocess results from simulations created using Tidy3D GUI.

The job container has a convenient method to save and load the results of a job that has already finished without needing to know the task_id, as below:

# Saves the job metadata to a single file.
job.to_file("data/job.json")

# You can exit the session, break here, or continue in new session.

# Load the job metadata from file.
job_loaded = web.Job.from_file("data/job.json")

# Download the data from the server and load it into a SimulationData object.
sim_data = job_loaded.load(path="data/sim.hdf5")

To access the original Simulation object that created the simulation data you can use 

# Run the simulation.
sim_data = web.run(simulation, task_name='task_name', path='out/sim.hdf5')

# Get a copy of the original simulation object.
sim_copy = sim_data.simulation

To get all the data in a Tidy3D object obj as a dictionary, you should use the command obj.dict().

We can get the cost estimate of running the task before running it. This prevents us from accidentally running large jobs we set up by mistake. The estimated cost is the maximum cost corresponding to running all the time steps. To do so, run  a code like below:

# initializes job, puts task on server (but doesnt run it)
job = web.Job(simulation=sim, task_name="job", verbose=verbose)

# estimate the maximum cost
estimated_cost = web.estimate_cost(job.task_id)

print(f'The estimated maximum cost is {estimated_cost:.3f} Flex Credits.')

See this notebook to obtain other details about submitting simulations to the server.

To obtain the cost of a simulation, you can use the function tidy3d.web.real_cost(task_id). In the example below, a job is created, and its cost is estimated. After running the simulation, the real cost can be obtained. It is important to note that the real cost may not be available immediately after the simulation is finished.

import time

# initializes job, puts task on server (but doesnt run it)
job = web.Job(simulation=sim, task_name="job", verbose=verbose)

# estimate the maximum cost
estimated_cost = web.estimate_cost(job.task_id)

print(f'The estimated maximum cost is {estimated_cost:.3f} Flex Credits.')

# Runs the simulation.
sim_data = job.run(path="data/sim_data.hdf5")

time.sleep(5)

# Get the billed FlexCredit cost after a simulation run.
cost = web.real_cost(job.task_id)

The cost of a simulation is primarily affected by the number of grid points and time steps. To reduce the simulation cost, you can take specific actions. However, it’s essential to gather relevant information about the simulation first to help you in this process.

# Initializes job, puts task on server (but doesn't run it).
job = tidy3d.web.Job(simulation=sim, task_name="job", verbose=verbose)

# Estimate the maximum cost before running the simulation.
estimated_cost = tidy3d.web.estimate_cost(job.task_id)
print(f'The estimated maximum cost is {estimated_cost:.3f} Flex Credits.')

# Run the simulation.
sim_data = tidy3d.web.run(simulation=sim, task_name="task", path="data/data.hdf5", verbose=True)

# Print simulation information such as grid points and time steps.
print(sim_data.log)

Symmetry

In Tidy3D simulations, field symmetries can significantly reduce computational time and FlexCredit cost, sometimes by factors of 1/2, 1/4, or even 1/8. Therefore, symmetry is preferred whenever applicable. However, it is crucial to set up the symmetry correctly to avoid inaccurate results. For a more detailed explanation of symmetry, please refer to the dedicated tutorial.

Meshing Strategy

To reduce the number of grid points (and time steps) in a simulation, you can adjust the GridSpec specifications. You have the option to choose between AutoGrid, UniformGrid, or CustomGrid for each simulation direction. Starting with the default object AutoGrid is generally a good strategy to discretize the entire simulation domain. You can then fine-tune the mesh by increasing grid resolution for directions or regions with smaller geometric features or high field gradients. You can also relax the discretization along directions of invariant geometry, such as the propagation direction of channel waveguides. Another way to enhance simulation accuracy while keeping the grid points small is by defining an override structure.

Shutoff

By default, Tidy3D periodically checks 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​​​ $10^{-5}$​​, the simulation is terminated as the fields remaining in the simulation are deemed negligible. The shutoff value can be controlled using the tidy3d.Simulation.shutoff 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. The Flex Unit cost of the simulation is also proportionally scaled down when early termination is encountered.

Boundary Conditions

When running simulations, it’s important to use appropriate boundary conditions to absorb incoming waves and minimize reflection accurately. The tidy3d.PML boundary condition is generally the best choice, as it can absorb waves from all angles with minimal reflection. However, in some instances where an angled structure or dispersive materials are present within the PML, you may need to use the tidy3d.Absorber instead. While the absorber performs a similar function to the PML, it has a slightly higher reflection rate and requires more computation, resulting in higher simulation costs.

See this notebook for more details on setting up boundary conditions.

To keep track of the details of a simulation, a log file is created that contains information about the simulation size, symmetries, number of computational grid points, time steps, shut-off condition, and the time taken for simulation setup and running. If you need to print out the log file of a simulation, you can use the command print(sim_data.log). 

We generally assume the following physical units in component definitions:

• Length: micron (μm, $10^{-6}$​​​ 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 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^{2}$​​​​​)
• Modal amplitude: Square root of watt ($W^{1/2}$​​​​​)

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^{2}$.

Depending on the size of the simulation task submitted, our cloud always tries to dynamically allocate the optimal amount of computational resources to run this task. When the server is busy, the resources could become limited, so a smaller amount of resources are assigned to run the task, making the simulation time slightly longer than usual. However, this should be relatively rare as we constantly monitor the status of our server and ensure ample hardware resources are available at all times.

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. So, you should run the simulation for enough time to allow the electromagnetic fields to decay to negligible values within the simulation domain.

When dealing with light propagation in a NON-RESONANT device, like a simple optical waveguide, a good initial guess to simulation run_time would be a few times the largest domain dimension ($L$) multiplied by the waveguide mode group index ($n_g$), divided by the speed of light in a vacuum ($c_0$), plus the source_time.

This repo offers a limited ability to convert .lsf project files to Tidy3D skeleton files in Python. Not every command in the lsf file is covered. The lsf project files often have default values/conventions that are not specified, so the created Tidy3D script will often need additional specification. Always be sure to check over the created Tidy3D script to see if any values are missing or if any objects have not been parsed.

When a batch is created, a batch.hdf5 file will be created automatically. Users can use this file to collect all the simulation results from the batch. First, load the batch.hdf5 file by

batch = web.Batch.from_file(“folder_name/batch.hdf5”)

Then download and load all simulations results into a BatchData object by

batch_results = batch.load(path_dir=“data”)

Then, you can further extract the result for each simulation from batch_results.

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.

• For dispersive materials with $\epsilon_{\infty} < 1$, decrease the value of the Courant stability factor to below $\sqrt{\epsilon_{\infty}}$.
• Move PML boundaries further away from structure interfaces inside the simulation domain, or from sources that may be injecting evanescent waves, like PointDipole, UniformCurrentSource, or CustomFieldSource.
• Make sure structures are translationally invariant into the PML, or if not possible, use Absorber boundaries.
• Remove dispersive materials extending into the PML, or if not possible, use Absorber boundaries.
• If using our fitter to fit your own material data, ensure you are using the plugins.StableDispersionFitter.
• If none of the above work, try using StablePML or Absorber boundaries anyway (note: these may introduce more reflections than in usual simulations with regular PML).

By default, Tidy3D periodically checks 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 $10^{-5}$, the simulation is terminated as the fields remaining in the simulation are deemed negligible. The shutoff value can be controlled using the Simulation.shutoff 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. The Flex Unit cost of the simulation is also proportionally scaled down when early termination is encountered.

When early termination happens, 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 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 are no longer 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.

The primary 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 ResonanceFinder 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.

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.

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 without worrying about the value becoming stale later, 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. Also, note you can use a convenience method obj_new = obj.updated_copy(param1=param1_new), which is just a shortcut to the obj.copy() call above.

The web-based Python notebook environment in tidy3d.simulation.cloud only has access to 4 GB of memory. When running a large simulation or complex optimizations, the memory needed to process the data could exceed the limit, causing the kernel to crash. In this case, we recommend installing Tidy3D on your local computer by following the installation guide and video. It will then use your computer memory, which is typically larger than 4 GB.

Dispersive materials are supported in Tidy3D, and we provide an extensive material library with pre-defined materials. Standard dispersive material models 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 $\mathrm{Re}(\epsilon_r)$ and electric conductivity $\sigma$ of a Medium, or through a real part $n$ and imaginary part $k$. The relationship between the two equivalent models is $\mathrm{Re}(\epsilon_r) = n^2 - k^2$, $\mathrm{Im}(\epsilon_r) = 2nk$, and $\sigma = 2 \pi f \epsilon_0 \mathrm{Im}(\epsilon_r)$.

In the case of (almost) lossless dielectrics, the dispersion could be negligible in a broad frequency window, but generally, it is importat 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 $\mathrm{d}n/\mathrm{d}\lambda$ in Sellmeier.from_dispersion(). 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.

Yes, users can import their own tabulated material data and fit it using one of Tidy3D’s dispersion fitting tools. The FastDispersionFitter 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 ($μm$), the real part of the refractive index ($n$), and the imaginary part of the refractive index ($k$). $k$ 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 ($μm$), $n$, and optionally $k$ data with the from_url utility function. URL can come from refractiveindex.

This notebook provides detailed instructions and examples of using the fitter.

To create a lossy material including conductivity, use the tidy3d.Medium object and set the conductivity parameter. For example:

lossy_medium = tidy3d.Medium(permittivity=2.0, conductivity=1.0)

To create a material from the real ($n$) and imaginary ($k$) parts of refractive index, use the tidy3d.Medium.from_nk(). For example:

nk_medium = tidy3d.Medium.from_nk(n=2.0, k=1.0, freq=freq0)

Negative $k$ value corresponds to a gain medium. It is only allowed when the parameter allow_gain is set to True.

You can import your own tabulated material data and fit it using one of Tidy3D’s dispersion fitting tools. The FastDispersionFitter 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 ($μm$), the real part of the refractive index ($n$), and the imaginary part of the refractive index ($k$). $k$ 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 ($μm$), $n$, and optionally $k$ data with the from_url utility function. URL can come from refractiveindex.

This notebook provides detailed instructions and examples on using the fitter.

To create a dispersive material from model parameters, you only need to instantiate the medium object and provide its parameters. For example, debye_medium = td.Debye(eps_inf=2.0, coeffs=[(1,2),(3,4)]).

To create fully anisotropic mediums including all 9 components of the permittivity and conductivity tensors, you can use the tidy3d.FullyAnisotropicMedium object. The provided permittivity tensor and the symmetric part of the conductivity tensor must have coinciding main directions. However, a non-symmetric conductivity tensor can be used to model magneto-optic effects. Note that dispersive properties and subpixel averaging are currently not supported for fully anisotropic materials.

perm = [[2, 0, 0], [0, 1, 0], [0, 0, 3]]
cond = [[0.1, 0, 0], [0, 0, 0], [0, 0, 0]]
anisotropic_dielectric = FullyAnisotropicMedium(permittivity=perm, conductivity=cond)

Alternatively, you can create a diagonally anisotropic material, using the tidy3d.AnisotropicMedium(xx=medium_xx, yy=medium_yy, zz=medium_zz) object, and then include three medium objects defining the diagonal elements of the permittivity tensor. In this case, the medium objects can be of type Medium, PoleResidue, Sellmeier, Lorentz, Debye, or Drude. For example:

medium_xx = Medium(permittivity=4.0)
medium_yy = Medium(permittivity=4.1)
medium_zz = Medium(permittivity=3.9)
anisotropic_dielectric = AnisotropicMedium(xx=medium_xx, yy=medium_yy, zz=medium_zz)

To export a spatially varying medium dataset to a HDF5 file you should use the to_hdf5(filename) method. In the example below, we illustrate how to do that after creating a tidy3d.CustomMedium.

# The coordinate for the refractive index data that includes x, y, z, and frequency
X = np.linspace(-20, 20, 100)  # x grid
Y = np.linspace(-20, 20, 100)  # y grid
Z = [0]  # z grid

# Create a permittivity dataset and a custom medium.
n_data = np.ones((100, 100, 1, 1)) * 12
n_dataset = tidy3d.SpatialDataArray(n_data, coords=dict(x=X, y=Y, z=Z, f=[freq0]))
data = tidy3d.PermittivityDataset(eps_xx=n_dataset, eps_yy=n_dataset, eps_zz=n_dataset)
mat_custom = tidy3d.CustomMedium(eps_dataset=data, interp_method="nearest")

# Export the custom medium dataset to HDF5.
mat_custom.to_hdf5(fname="CustomMedium.hdf5")

You can create a 2D material using the tidy3d.Medium2D object. This is especially helpful for building very thin materials, like metal layers.

t_copper = 0.0001  # Thickness of the copper layer.
sigma_copper = 50  # Copper conductivity in S/um.

# Define copper as a Medium2D.
copper = td.Medium2D.from_medium(
    td.Medium(conductivity=sigma_copper), thickness=t_copper
)

You can create a graphene medium using tidy3d.Graphene, which defines a parametric surface conductivity model for graphene. For example:

gamma = 0.0033  # Scattering rate (eV).
mu_c = 0.5  # Graphene chemical potential (eV).
temp = 300  # Temperature (K).
scaling = 2  # Number of graphene layers.

graphene = td.material_library["graphene"](
    gamma=gamma, mu_c=mu_c, temp=temp, scaling=scaling
).medium

# or
# graphene = tidy3d.Graphene(
#    gamma=gamma, mu_c=mu_c, temp=temp, scaling=scaling
# ).medium

To create nonlinear material, you should specify a tidy3d.NonlinearSusceptibility to the nonlinear_spec parameter of any medium. For example:

medium = tidy3d.Medium(permittivity=2, nonlinear_spec=tidy3d.NonlinearSusceptibility(chi3=1, numiters=5))

In Tidy3D, complex structures can be imported from GDSII files via the third-party gdstk package, which you can install running pip install gdstk. To load the geometry from a GDSII file, you should select the cell with the geometry you want. It is usually easier to verify that we can find the correct one by name first, for example:

# Load a GDSII library from the file.
lib_loaded = gdstk.read_gds(gds_path)

# Create a cell dictionary with all the cells in the file.
all_cells = {c.name: c for c in lib_loaded.cells}
print("Cell names: " + ", ".join(all_cells.keys()))

wg_height = 0.22
dilation = 0.02

geo = tidy3d.Geometry.from_gds(
    gds_cell=all_cells["TOP"],
    gds_layer=0,
    gds_dtype=0,
    axis=2,
    slab_bounds=(-0.11, 0.11),
    reference_plane="bottom",
)

To use the STL import functionality, you must install Tidy3D as pip install "tidy3d[trimesh]", which will install optional dependencies for processing surface meshes. Then you can use the tidy3d.TriangleMesh.from_stl() function. In the following example, we will import a simple box geometry from a STL file.

# Make the geometry object representing the STL solid from the STL file stored on disk
box = tidy3d.TriangleMesh.from_stl(
    filename="./misc/box.stl",
    scale=1,  # The units are already microns as desired, but this parameter can be used to change units [default: 1].
    origin=(
        0,
        0,
        0,
    ),  # This can be used to set a custom origin for the stl solid [default: (0, 0, 0)]
    solid_index=None,  # Sometimes, there may be more than one solid in the file; use this to select a specific one by index.
)

See this example for a complete reference on importing STL files.

In Tidy3D, you can export structures to GDSII file via the third-party gdstk package, which you can install running pip install gdstk. The example below creates a simple geometry and then exports it to GDSII:

# Create a gds cell to add the structures to.
geo_cell = gdstk.Cell("TOP")

# Make a box and add it to the cell.
box = gdstk.rectangle((-1, 1), (-1, 1), layer=0)
geo_cell.add(box)

# Create a library for the cell and save it.
gds_path = "box.gds"
lib = gdstk.Library()
lib.add(box_cell)
lib.write_gds(gds_path)

# Create a simulation object.
sim = td.Simulation(
    size=sim_size,
    grid_spec=td.GridSpec.uniform(dl=dl),
    structures=structures,
    boundary_spec=td.BoundarySpec.all_sides(boundary=td.PML()),
)

# Export the structure to GDSII.
sim.to_gds_file(fname="sim.gds",
  z=0,
  permittivity_threshold=5,
  frequency=f0,
)

You can create a box geometry using the tidy3d.Box object. You can specify the center and size parameters, as below:

box = tidy3d.Box(center=(1,2,3), size=(2,2,2))

Or you can use the tidy3d.Box.from_bounds() method, where you should define the rmin and rmax coordinates of the lower and upper box corners. For example:

box = tidy3d.Box.from_bounds(
  rmin=(-10, -1, -0.1),
  rmax=(10, 1, 0.1),
)

You can create a sphere using the tidy3d.Sphere object and specifying the center and radius parameters, as below:

box = tidy3d.Box.from_bounds(
  rmin=(-10, -1, -0.1),
  rmax=(10, 1, 0.1),
)

You can create a cylinder using the tidy3d.Cylinder object. In the example below we create a cylinder 2 $\mu$m in length, oriented along the z-axis, with a    0.5 $\mu$m radius, and positioned at (-1,1,0). To obtain a conical shape, set the parameters sidewall_angle and reference_plane. 

cyl = tidy3d.Cylinder(center=(-1,1,0), radius=0.5, length=2, axis=2)

Use the tidy3d.PolySlab object to create an extruded polygon with an optional sidewall angle along the axis direction. The polygon geometry is defined by the vertices parameter, which receives a list of (d1, d2) coordinates defining the geometry of the polygon face at the reference_plane. The slab_bounds parametere defines the minimum and maximum positions of the slab along the axis dimension. Set the sidewall_angle with respect to the reference_plane to create slanted sidewalls. In addition, you can dilate or erode the polygon by setting positive or negative values to dilation parameter.

vertices = np.array([(0,0), (1,0), (1,1)])
triangle = tidy3d.PolySlab(vertices=vertices, axis=2, slab_bounds=(-1, 1))

A geometry group is a convenient way to gather multiple geometry objects into one collection. It can significantly improve performance when all the geometries in the group are assigned to the same medium. To create a geometry group, use the tidy3d.GeometryGroup object and set the geometries parameter as below:

cylinders = []

for i in range(0, 4):
  c = tidy3d.Cylinder(
    axis=2, radius=0.3, center=(i, 0, 0), length=2,
  )
  cylinders.append(c)

structure = tidy3d.Structure(
  geometry=tidy3d.GeometryGroup(geometries=cylinders),
  medium=tidy3d.Medium(permittivity=4),
)

You can combine multiple geometries using the tidy3d.ClipOperation object to perform ‘union’, ‘intersection’, ‘difference’, and ‘symmetric_difference’  operations. For example:

box = tidy3d.Box(center=(0,0,0), size=(1, 1, 2))
cyl = tidy3d.Cylinder(center=(1,0,0), radius=0.5, length=2, axis=2)

union = tidy3d.ClipOperation(
  operation='union', geometry_a=box, geometry_b=cyl
)

intersection = tidy3d.ClipOperation(
  operation='intersection', geometry_a=box, geometry_b=cyl
)

difference = tidy3d.ClipOperation(
  operation='difference', geometry_a=box, geometry_b=cyl
)

symmetric_difference = tidy3d.ClipOperation(
  operation='symmetric_difference', geometry_a=box, geometry_b=cyl
)

When two structures overlap, the last ones in the structures list will override the permittivities of the previous structures. This notebook illustrates how to use this rule to create a photonic crystal slab. The holes geometry with a refractive index of 1 overrides the slab permittivities in regions where they overlap, creating the air holes.

# Simulation
sim = td.Simulation(
    size=sim_size,
    grid_spec=grid_spec,
    structures=[slab, holes],
    sources=[source],
    monitors=[time_series_mnt, field_mnt, far_field_mnt],
    run_time=run_time,
    boundary_spec=td.BoundarySpec.all_sides(boundary=td.PML()),
    symmetry=(1, -1, 1),
    shutoff=0,
)

In Tidy3D, all geometries can be translated, rotated, and scaled. These methods create a new copy of the original geometry with a transformation applied. For example, you can start with a tidy3d.Box centered at the origin and create a copy of it rotated around the z-axis:

box = tidy3d.Box(size=(2, 1, 1))

rotated_box = box.rotated(np.pi / 6, axis=2)

_ = rotated_box.plot(z = 0)

See this example for more information.

In Tidy3D, all geometries can be translated, rotated, and scaled. These methods create a new copy of the original geometry with a transformation applied. For example, you can start with a tidy3d.Box centered at the origin and create a copy of it translated in the x-direction by 2 $\mu m$:

box = tidy3d.Box(size=(2, 1, 1))

box_translated = box.translated(x=2, y=0, z=0)

_ = box_translated.plot(z = 0)

See this example for more information.

In Tidy3D, all geometries can be translated, rotated, and scaled. These methods create a new copy of the original geometry with a transformation applied. For example, you can start with a tidy3d.Box centered at the origin and create a copy of it scaled by a factor of 2 in all directions:

box = tidy3d.Box(size=(2, 1, 1))

box_scaled = box.scaled(x=2.0, y=2.0, z=2.0)

_ = box_scaled.plot(z = 0)

See this example for more information.

In Tidy3D, all geometries can be translated, rotated, and scaled. These methods create a new copy of the original geometry with a transformation applied. For example, you can start with a tidy3d.Box centered at the origin and create a copy of it rotated around the z-axis:

box = tidy3d.Box(size=(2, 1, 1))

rotated_box = box.rotated(np.pi / 6, axis=2)

_ = rotated_box.plot(z = 0)

Transformed geometries can be further transformed. Composing transformations is as simple as cascading the method calls. In the following example, we create an ellipsoidal prism by scaling a primitive tidy3d.Cylinder and rotating it.

ellipsoid = tidy3d.Cylinder(radius=0.5, length=0.5, axis=1).scaled(x=2, y=1, z=1).rotated(np.pi / 4, axis=1)

_ = ellipsoid.plot(y=0)

A tidy3d.Transformed object contains an inner geometry and a transformation, written as a 4 x 4 matrix and applied to the (homogeneous) coordinates of the inner geometry. It is possible to define a Transformed object directly from the inner geometry and the transformation. To help create the most usual transformation matrices, the Transformed class has 3 static methods for translation, rotation, and scaling that can be used and combined (the @ operator can be used for matrix multiplication with numpy arrays).

rot = tidy3d.Transformed.rotation(np.pi / 3, axis=(1, 1, 1))
trans = tidy3d.Transformed.translation(1, 2, 0)
scale = tidy3d.Transformed.scaling(1, 1.25, 1)

# The box is first rotated, then translated, and finally scaled
transformed = td.Transformed(geometry=td.Box(size=(1, 1, 1)), transform=scale @ trans @ rot)

See this example for more information.

You can use the tidy3d.ClipOperation object to combine multiple geometries through ‘union’, ‘intersection’, ‘difference’, and ‘symmetric_difference’  operations. Simply define the geometry_a and the geometry_b and assign them to the clip object. For example:

box = tidy3d.Box(center=(0,0,0), size=(1, 1, 2))
cyl = tidy3d.Cylinder(center=(1,0,0), radius=0.5, length=2, axis=2)

union = tidy3d.ClipOperation(
  operation='union', geometry_a=box, geometry_b=cyl
)

intersection = tidy3d.ClipOperation(
  operation='intersection', geometry_a=box, geometry_b=cyl
)

difference = tidy3d.ClipOperation(
  operation='difference', geometry_a=box, geometry_b=cyl
)

symmetric_difference = tidy3d.ClipOperation(
  operation='symmetric_difference', geometry_a=box, geometry_b=cyl
)

Tidy3D offers four primitive geometric shapes: Box, Cylinder, Sphere, and PolySlab. An extensive array of intricate geometrical configurations can be defined from these fundamental building blocks by manipulating their properties and hierarchical arrangements. For instance, our tutorials on the Luneburg lens waveguide size converter and the Fresnel lens showcase the creation of curved surfaces through the strategic layering of cylindrical elements.

Beyond the in-built primitives, Tidy3D accommodates external geometrical specifications in either the GDS or STL file formats, allowing users to import custom geometries created in their preferred design tools. Additionally, compatibility with external libraries like gdstk and shapely opens the gateway to even more complex geometric possibilities. Using gdstk to create various waveguide structures has been demonstrated in various examples, such as thepolarization splitter and rotator based on 90-degree bends](https://www.flexcompute.com/tidy3d/examples/notebooks/90BendPolarizationSplitterRotator/?__hstc=197414576.85a08fc595b47d0b94ebfa20ba44cd6d.1696006513341.1701896316776.1701901226721.28&__hssc=197414576.3.1701901226721&__hsfp=3209960735). Additionally, you can create complex geometries using the Trimesh library, as demonstrated in this tutorial. 

To define complex geometries using the Trimesh library, you must install Tidy3D as pip install "tidy3d[trimesh]", which will install optional dependencies needed for processing surface meshes. The Trimesh library provides some built-in geometries such as ring (annulus), box, capsule, cone, cylinder, and so on. Let’s create a ring as an example.

n_sections = 100 # How many sections to discretize the mesh.

# Create a ring mesh.
ring_mesh = trimesh.creation.annulus(r_min=9, r_max=10, height=1, sections=n_sections)

# Plot the mesh.
ring_mesh.show()

To use this geometry in a Tidy3D simulation, you need to convert the mesh into a tidy3d.TriangleMesh geometry. Use the from_trimesh() method to conviently convert the mesh to a Tidy3D geometry. From there, you can further define the Tidy3D structure and put it into a simulation.

# Define a tidy3d geometry from a mesh.
ring_geo = td.TriangleMesh.from_trimesh(ring_mesh)

This example shows how to create many different complex geometries using Trimesh. 

The gdstk library offers a convenient and flexible way to construct commonly used photonic integrated circuit (PIC) components, such as straight waveguides, linear tapers, rings, race tracks, s-bends, circular bends, and directional couplers. This notebook contains pre-defined functions used to construct commonly used PIC components. Users can directly copy these pre-defined functions to their script and use them to build their simulations. More importantly, users can learn the workflow from these examples and create their own Tidy3D structures using the same principles.

Tidy3D provides four basic geometric shapes, namely, Box, Cylinder, Sphere, and PolySlab. These shapes can be used to create various periodic structures used in photonic crystals and other photonic devices such as square or hexagonal arrays of cylinders, slabs with square or hexagonal arrays of holes, rectangular grating, L and H cavities, wood pile, and FCC/BCC crystals. For this purpose, you can organize these geometries in a tidy3d.GeometryGroup. This notebook contains functions that can be used to build these popular periodic structures with ease. Moreover, users can learn from these examples and create their own periodic structures using the same principles.

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.

You can set the source frequency and bandwidth through the source_time parameter, which accepts a tidy3d.GaussianPulse object. In the example below, we create a tidy3d.PointDipole source to radiate power at a center wavelength of 1.55 $\mu$m over a bandwidth of 100 nm.

# Simulation wavelength and bandwidth.
wl = 1.55
bw = 0.1
wl_max = wl + bw / 2
wl_min = wl - bw / 2
freq0 = tidy3d.C_0 / wl
fwidth = 0.5 * (tidy3d.C_0 / wl_min - tidy3d.C_0 / wl_max)

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=freq0, fwidth=fwidth)

# Source definition
pt_dipole = tidy3d.PointDipole(
  center=(1,2,3),
  source_time=pulse,
  polarization='Ex',
  interpolate=True,
  name="dipole",
)

The tidy3d.GaussianPulse object has the built-in functions plot_spectrum and plot that allow users to visualize the source spectrum and time-dependence, respectively. For example:

# Simulation wavelength and bandwidth.
wl = 1.55
bw = 0.1
wl_max = wl + bw / 2
wl_min = wl - bw / 2
freq0 = td.C_0 / wl
fwidth = 0.5 * (td.C_0 / wl_min - td.C_0 / wl_max)
run_time = 1e-12

# Source bandwidth.
pulse = td.GaussianPulse(freq0=freq0, fwidth=fwidth)

# Source definition
pt_dipole = td.PointDipole(
  center=(1,2,3),
  source_time=pulse,
  polarization='Ex',
  interpolate=True,
  name="dipole",
)

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4), tight_layout=True)

# Plot the source spectrum.
pt_dipole.source_time.plot_spectrum(
    times=np.linspace(0, run_time, 2000), val="abs", ax=ax1,
)

# Plot the source time-dependence.
pt_dipole.source_time.plot(
    times=np.linspace(0, run_time / 3, 2000), val='real', ax=ax2,
)

plt.show()

When defining a source, you must specify a source time profile, typically Gaussian. For example, we can define a plane wave as

plane_wave = td.PlaneWave(
  source_time=td.GaussianPulse(freq0=freq0, fwidth=0.5 * freqw),
  size=(td.inf, td.inf, 0),
  center=(0, 0, 0.3 * lda0),
  direction="-",
  pol_angle=0,
)

Here, the source time is a Gaussian pulse with central frequency freq0 and frequency width 0.5 * freqw. To visualize the spectrum it gives, we can use the plot_spectrum method by

plane_wave.source_time.plot_spectrum(
  times=np.linspace(0, sim.run_time, 2000), val="abs"
)
plt.show()

Here, we need to specify the sampled time instances. To ensure the source spectrum is plotted correctly, we need to ensure the time sampling is sufficiently fine and the end time is sufficiently long compared to the pulse width.

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 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 to take it 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 attribute, or normalization can be turned off by setting that to None. Results can even be renormalized after the simulation run using SimulationData.renormalize(). 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 and SourceTime.phase, 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.

• PointDipole: The point dipole source represents an infinitesimal antenna with a fixed current density. The normalization is such that the power injected by the source in a homogeneous material of refractive index $n$ at frequency $\omega = 2\pi f$ is approximately given as follows

  • $\frac{\omega^2}{12\pi}\frac{\mu_0 n}{c}$, 3D simulation, electric current
  • $\frac{\omega^2}{12\pi}\frac{\epsilon_0 n^3}{c}$, 3D simulation, magnetic current
  • $\frac{\omega \mu_0}{16}$, 2D TE simulation, electric current
  • $\frac{\omega \mu_0}{8}$, 2D TM simulation, electric current
  • $\frac{\omega \epsilon_0 n^2}{8}$, 2D TE simulation, magnetic current
  • $\frac{\omega \epsilon_0 n^2}{16}$, 2D TM simulation, magnetic current

  There can be a small difference in the true power compared to the analytical values above due to the finite grid. Note that the current source definition used in Tidy3D is different from the definition of an electric dipole composed of two separated, oscillating electric charges, which is also common. The power normalization differs by a factor of $\omega^2$ for electric dipoles, and $\mu_0^2 \omega^2$ for magnetic dipoles.

• UniformCurrentSource: No extra normalization applied.

• CustomFieldSource: No extra normalization applied.

• ModeSource, PlaneWave, GaussianBeam, AstigmaticGaussianBeam: Normalized to inject 1W power at every frequency. If supplied SourceTime.num_freqs is 1, this normalization is only exact at the central frequency of the associated SourceTime pulse but should still be very close to 1W at nearby frequencies too. Increasing num_freqs can be used to make sure the normalization works well for a broadband source. The correct usage for a PlaneWave 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).

• TFSFSource: Normalized to inject $1W/μm^{2}$ in the direction of the source injection axis. This is convenient for computing scattering and absorption cross-sections without the need for additional normalization. Note that for angled incidence, a factor of $1/\cos(\theta)$ needs to be applied to convert to the power carried by the plane wave in the propagation direction, which is at an angle $\theta$ with respect to the injection axis. Note also that when the source spans the entire simulation domain with periodic or Bloch boundaries, the conversion between the normalization of a TFSFSource and a PlaneWave is just the area of the simulation domain in the plane normal to the injection axis.

The tidy3d.PointDipole is a zero-dimensional uniform current source. The example below illustrates how to define tidy3d.PointDipole within a simulation.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
pt_dipole = tidy3d.PointDipole(
  center=(1,2,3),
  source_time=pulse,
  polarization='Ex',
  interpolate=True,
  name="dipole",
)

Use the center parameter to set the dipole position, then adjust the source_time dependence using tidy3d.GaussianPulse. The source polarization defines the direction and type of the current component. Finally, the parameter interpolate handles reverse interpolation of zero-size dimensions of the source. If False, the source data is snapped to the nearest Yee grid point. If True, equivalent source data is applied on the surrounding Yee grid points to emulate placement at the specified location using linear interpolation.

See this notebook to an example on setting up a tidy3d.PointDipole source.

The tidy3d.PointDipole source placed in a lossless homogeneous material injects power close to the analytically expected result for an infinitesimal antenna with oscillating current. There can be a small difference from the analytical result due to the finite grid, which disappears in the limit of high resolution. To calculate the radiated power of a dipole in the presence of dispersive, lossy, or non-homogeneous materials, you can use a tidy3d.FluxMonitor box. Refer to this notebook for an example.

The tidy3d.UniformCurrentSource is a rectangular volume source with uniform time dependence. The example below illustrates how to define a tidy3d.UniformCurrentSource within a simulation.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
source = tidy3d.UniformCurrentSource(
  center=(1,2,3),
  size=(0,2,1),
  source_time=pulse,
  polarization='Ex',
  interpolate=True,
  name="uniform_source",
)

Use the center and size parameters to set the source position and volume, then adjust the source_time dependence using tidy3d.GaussianPulse. The source polarization defines the direction and type of the current component. Finally, the parameter interpolate handles reverse interpolation of zero-size dimensions of the source. If False, the source data is snapped to the nearest Yee grid point. If True, equivalent source data is applied on the surrounding Yee grid points to emulate placement at the specified location using linear interpolation. Note that making size=(0, 0, 0) is equivalent to including a tidy3d.PointDipole source.

The tidy3d.PlaneWave is a uniform current distribution on an infinite extent plane. The example below illustrates how to define a tidy3d.PlaneWave within a simulation.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
source = tidy3d.PlaneWave(
  center=(0, 0, 5),
  size=(tidy3d.inf, tidy3d.inf, 0),
  source_time=pulse,
  direction='-',
  pol_angle=np.pi/2,
  angle_theta=0,
  angle_phi=0,
  name="plane_wave",
)

Use the center and size parameters to set the source position and dimension, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction parameter specifies propagation in the positive or negative direction of the injection axis. You can change the light polarization using pol_angle, and  adjust the propagation axis direction with angle_theta and angle_phito control the polar and azimuth angles.

This example illustrates setting up a tidy3d.PlaneWave source at normal and off-normal incidences.

The tidy3d.ModeSource injects a current source in the simulation to excite a modal profile in a finite extent plane. It is commonly used to excite specific waveguide modes in photonic integrated circuits. To illustrate how to set up a tidy3d.ModeSource, let’s consider the case of injecting the first-order transverse electric (TE) mode in a silicon-on-insulator (SOI) waveguide operating at 1.55 $\mu$m.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=1.934e14, fwidth=6.245e12)

# Mode specification.
mode_spec = tidy3d.ModeSpec(target_neff=3.47, filter_pol='te', num_modes = 2)

# Source definition
source = tidy3d.ModeSource(
  center=(0, 0, -2),
  size=(0, 2, 1.5),
  source_time=pulse,
  direction='+',
  mode_spec=mode_spec,
  mode_index=1,
  name="mode_source",
)

You should use the center and size parameters to define a source plane surrounding the waveguide, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction='+' parameter specifies propagation in the positive waveguide axis. The tidy3d.ModeSpec object includes all the specifications of a mode solver, which calculates the optical modes given the material distribution within the source plane. The modes calculated by the mode solver are sorted by their effective indices in descending order. So, we have set the initial mode solver guess to the core refractive index (target_neff=3.47) and chosen filter_pol='te' to make sure it will return first in the list of the TE waveguide modes, starting from the fundamental one. Finally,  to inject the first-order TE mode in the waveguide, we setmode_index=1`.

This example illustrates setting up a tidy3d.ModeSource source.

To inject a specific optical mode in the waveguide, you can use the tidy3d.ModeSource source. Let’s consider the case of injecting the first-order transverse electric (TE) mode in a silicon-on-insulator (SOI) waveguide operating at 1.55 $\mu$m as an example:

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=1.934e14, fwidth=6.245e12)

# Mode specification.
mode_spec = tidy3d.ModeSpec(target_neff=3.47, filter_pol='te', num_modes = 2)

# Source definition
source = tidy3d.ModeSource(
  center=(0, 0, -2),
  size=(0, 2, 1.5),
  source_time=pulse,
  direction='+',
  mode_spec=mode_spec,
  mode_index=1,
  name="mode_source",
)

You should use the center and size parameters to define a source plane surrounding the waveguide, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction='+' parameter specifies propagation in the positive waveguide axis. The tidy3d.ModeSpec object includes all the specifications of a mode solver, which calculates the optical modes given the material distribution within the source plane. The modes calculated by the mode solver are sorted by their effective indices in descending order. So, we have set the initial mode solver guess to the core refractive index (target_neff=3.47) and chosen filter_pol='te' to make sure it will return first in the list of the TE waveguide modes, starting from the fundamental one. Finally,  to inject the first-order TE mode in the waveguide, we set mode_index=1.

This example illustrates setting up a tidy3d.ModeSource source.

To inject an optical mode in a waveguide bend, you must set the bend_radius and bend_axis parameters of tidy3d.ModeSpec. For example:

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=1.934e14, fwidth=6.245e12)

# Mode specification.
mode_spec = tidy3d.ModeSpec(target_neff=2.5, bend_radius=-5, bend_axis=1)

# Source definition
source = tidy3d.ModeSource(
  center=(0, 0, -2),
  size=(0, 2, 1.5),
  source_time=pulse,
  direction='+',
  mode_spec=mode_spec,
  mode_index=0,
  name="mode_source",
)

You can find a detailed example in this notebook.

The source tidy3d.GaussianBeam is a Guassian distribution on a finite extent plane. The example below illustrates how to define the tidy3d.GaussianBeam within a simulation.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
gauss_source = tidy3d.GaussianBeam(
  center=(0, -5, 0),
  size=(0, 3, 3),
  source_time=pulse,
  direction='+',
  pol_angle=0,
  angle_theta=0,
  angle_phi=0,
  waist_radius=1.0,
  waist_distance=-2.5,
  name="gauss_source",
)

Use the center and size parameters to set the source position and dimension, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction parameter specifies propagation in the positive or negative direction of the injection axis. You can change the light polarization using pol_angle, and  adjust the propagation axis direction with angle_theta and angle_phito control the polar and azimuth angles. In this example, the beam’s radius at the waist position was adjusted to 1$\mu$m using the waist_radius parameter. When waist_distance is positive (negative), the waist is behind (front) the source plane.

See this notebook to an example on setting up a tidy3d.GaussianBeam source.

To simulate an optical fiber mode source, you can use the tidy3d.ModeSource. This object allows you to solve for the optical modes of a fiber cross-section. You can then include this in your simulation by following the steps outlined in the example.

If you prefer, you can also use the tidy3d.GaussianBeam source instead to approximate the optical mode of the fiber with a Gaussian distribution, as explained in more detail in another example.

To create a converging Gaussian beam, include a tidy3d.GaussianBeam source in the simulation, and set the waist_distance to negative values. This way, the beam waist will lie in the front of the source plane, as illustrated in the following example

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
gauss_source = tidy3d.GaussianBeam(
  center=(0, -5, 0),
  size=(0, 3, 3),
  source_time=pulse,
  direction='+',
  pol_angle=0,
  angle_theta=0,
  angle_phi=0,
  waist_radius=1.0,
  waist_distance=-2.5,
  name="gauss_source",
)

See this notebook to an example on setting up a tidy3d.GaussianBeam source.

To create a diverging Gaussian beam, include a tidy3d.GaussianBeam source in the simulation, and set them waist_distance to positive values. This way, the beam waist will lie behind the source plane, as illustrated in the following example

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
gauss_source = tidy3d.GaussianBeam(
  center=(0, -5, 0),
  size=(0, 3, 3),
  source_time=pulse,
  direction='+',
  pol_angle=0,
  angle_theta=0,
  angle_phi=0,
  waist_radius=1.0,
  waist_distance=2.5,
  name="gauss_source",
)

See this notebook to an example on setting up a tidy3d.GaussianBeam source.

The tidy3d.AstigmaticGaussianBeam class implements the simple astigmatic Gaussian beam described in Kochkina et al., Applied Optics, vol. 52, issue 24, (2013). The simple astigmatic Guassian distribution allows both an elliptical intensity profile and different waist locations for the two principal axes of the ellipse. The following example illustrates how to set up a tidy3d.AstigmaticGaussianBeam.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
gauss_source = tidy3d.AstigmaticGaussianBeam(
  center=(0, -5, 0),
  size=(0, 3, 3),
  source_time=pulse,
  direction='+',
  pol_angle=0,
  angle_theta=0,
  angle_phi=0,
  waist_sizes=(1.0, 2.0),
  waist_distances=(-1.0, -2.0),
  name="gauss_source",
)

Use the center and size parameters to set the source position and dimension, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction parameter specifies propagation in the positive or negative direction of the injection axis. You can change the light polarization using pol_angle, and  adjust the propagation axis direction with angle_theta and angle_phi to control the polar and azimuth angles. In this example, different waist_sizes and waist_distances were specified in the x- and y-directions.

The total-field scattered-field (TFSF) source injects a plane wave in a finite region. The example below illustrates how to define the tidy3d.TFSF within a simulation.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Source definition
tfsf_source = tidy3d.TFSF(
  center=(0, 0, 5),
  size=(3, 3, 0),
  source_time=pulse,
  direction='-',
  pol_angle=np.pi / 2,
  angle_theta=np.pi / 4,
  angle_phi=0,
  injection_axis=2,
  name="tfsf_source",
)

Use the center and size parameters to set the source position and dimension, then adjust the source_time dependence using tidy3d.GaussianPulse. The direction parameter specifies propagation in the positive or negative direction of the injection axis. You can change the light polarization using pol_angle, and  adjust the propagation axis direction with angle_theta and angle_phito control the polar and azimuth angles. The injection_axis parameter specifies injection along the x (0), y (1), or z (2) direction.

See this notebook to an example on setting up a tidy3d.TFSF source.

The tidy3d.CustomFieldSource source can be used to inject a specific (E, H) field distribution on a plane, e.g. coming from another simulation. Internally, we use the equivalence principle to compute the actual source currents (all sources in FDTD have to be converted to current sources). Because of this, the custom field source will only produce reliable results if the provided fields decay by the edges of the source plane, or if they extend through the simulation boundaries and are well-matched to those boundaries.

The example below illustrates how to define the tidy3d.CustomFieldSource using a dataset containing the E and H fields to describe a Gaussian field profile.

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=200e12, fwidth=20e12)

# Scalar gaussian field.
waist_radius = 2
ys, zs = np.linspace(-4, 4, 101), np.linspace(-4, 4, 101)
y_grid, z_grid = np.meshgrid(ys, zs)
scalar_gaussian = np.exp(-(y_grid**2 + z_grid**2) / waist_radius**2)

# Field dataset defining both E and H
dataset_EH = tidy3d.FieldDataset(
    Ey=tidy3d.ScalarFieldDataArray(
        scalar_gaussian[None, ..., None],
        coords={
            "x": [0],
            "y": ys,
            "z": zs,
            "f": [200e12],
        },
    ),
    Hz=tidy3d.ScalarFieldDataArray(
        scalar_gaussian[None, ..., None] / td.ETA_0,
        coords={
            "x": [0],
            "y": ys,
            "z": zs,
            "f": [200e12],
        },
    ),
)

# Source definition
custom_field_src = tidy3d.CustomFieldSource(
    source_time=pulse,
    center=(-1, 1, 0),
    size=(0, 8, 8),
    field_dataset=dataset_EH,
)

See this notebook to an example on setting up a tidy3d.CustomFieldSource source.

The tidy3d.CustomCurrentSource source can be used to inject a raw electric and magnetic current distribution within the simulation. Its syntax is very similar to that of CustomFieldSource, except the source accepts a current_dataset instead of a field_dataset, and it can be volumetric or planar without requiring tangential components. This dataset still contains the E{x,y,z} and H{x,y,z} field components, which correspond to J and M components, respectively.

See this notebook to an example on setting up a tidy3d.CustomCurrentSource source.

To inject an optical mode in an angled waveguide, you must set the angle_theta and angle_phi parameters of tidy3d.ModeSpec. For example:

# Source bandwidth.
pulse = tidy3d.GaussianPulse(freq0=1.934e14, fwidth=6.245e12)

# Mode specification.
mode_spec = tidy3d.ModeSpec(target_neff=2.5, angle_theta=1.5, angle_phi=0)

# Source definition
source = tidy3d.ModeSource(
  center=(0, 0, -2),
  size=(0, 2, 1.5),
  source_time=pulse,
  direction='+',
  mode_spec=mode_spec,
  mode_index=0,
  name="mode_source",
)

You can find a detailed example in this notebook.

Tidy3D tries to provide an illusion of continuity as much as possible, but at the level of the solver, a finite numerical grid is used, which can have some implications that advanced users may want to be aware of.

The FDTD method for electromagnetic simulations uses what is called the Yee grid, in which every field component is defined at a different spatial location, as illustrated in the figure, as well as in our FDTD video tutorial FDTD 101 videos. On the left, we show one cell of the full 3D Yee grid and where the various E and H field components live. On the right, we show a cross-section in the xy plane and the locations of the Ez and Hz field components in that plane (note that these field components are not in the same cross-section along z but rather also offset by half a cell size). This illustrates a duality between the grids on which E and H fields live, which is related to the duality between the fields themselves. There is a primal grid, shown with solid lines, and a dual grid, shown with dashed lines, with the Ez and Hz fields living at the primal/dual vertices in the xy-palne, respectively. In some literature on the FDTD method, the primal and dual grids may even be switched as the definitions are interchangeable. In Tidy3D, the primal grid is as defined by the solid lines in the Figure.

When computing results that involve multiple field components, like Poynting vector, flux, or total field intensity, it is important to use fields that are defined at the same locations for best numerical accuracy. The field components thus need to be interpolated, or colocated, to some common coordinates. All this is already done under the hood when using Tidy3D in-built methods to compute such quantities. When using field data directly, Tidy3D provides several conveniences to handle this. Firstly, field monitors have a colocate option, set to True by default, which will automatically return the field data interpolated to the primal grid vertices. The data is then ready to be used directly for computing quantities derived from any combination of the field components. The colocate option can be turned off by advanced users, in which case each field component will have different coordinates as defined by the Yee grid. In some cases, this can lead to more accurate results, as discussed, for example, in the custom source example. In that example, when using data generated by one simulation as a source in another, it is best to use the fields as recorded on the Yee grid.

Regardless of whether the colocate option is on or off for a given monitor, the data can also be easily colocated after the solver run. In principle, if colocating to locations other than the primal grid in post-processing, it is more accurate to set colocate=False in the monitor to avoid double interpolation (first to the primal grid in the solver, then to new locations). Regardless, the following methods work for both Yee grid data and data that has already been previously colocated:

• data_at_boundaries = sim_data.at_boundaries(monitor_name) to colocate all fields of a monitor to the Yee grid cell boundaries (i.e. the primal grid vertexes).
• data_at_centers = sim_data.at_centers(monitor_name) to colocate all fields of a monitor to the Yee grid cell centers (i.e. the dual grid vertexes).
• data_at_coords = sim_data[monitor_name].colocate(x=x_points, y=y_points, z=z_points) to colocate all fields to a custom set of coordinates. Any or all of x, y, and z can be supplied; if some are not, the original data coordinates are kept along that dimension.

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, 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 that give users a simple and flexible way to build the simulation mesh. The GridSpec object enables the user to chose between an AutoGrid, a UniformGrid, or a CustomGrid, at each of the simulation x-, y-, z-direction. An example code snippet is shown below:

uniform = tidy3d.UniformGrid(dl=0.1)

custom = tidy3d.CustomGrid(dl=[0.2, 0.2, 0.1, 0.1, 0.1, 0.2, 0.2])

auto = tidy3d.AutoGrid(min_steps_per_wvl=12)

grid_spec = tidy3d.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.

In general, a good strategy is to start with the default object AutoGrid 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 the run time small.

By default, Tidy3D configures the GridSpec object to having AutoGrid, which is an advanced meshing algorithm to automatically define a nonuniform grid in all three domain directions. 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 provided directly to grid_spec or inferred from any sources present in the simulation. Detailed examples on how to set up AutoGrid are present on this notebook.

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 below:

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,
)

The most standard way to define a simulation is to use a constant grid size in each of the three directions. This can be achieved simply using tidy3d.GridSpec.uniform(dl=...) as shown below.

# Setting a uniform grid size of 0.02 microns.
sim_uniform = tidy3d.Simulation(
    size=(5, 5, 5),
    grid_spec=tidy3d.GridSpec.uniform(dl=0.02),
    medium=tidy3d.Medium(permittivity=4),
    structures=[structure],
    boundary_spec=tidy3d.BoundarySpec.all_sides(boundary=td.PML())
    run_time=1e-12,
)

In some problems, the user may want to refine the grid mesh locally around specific geometry features, such as the gap between two very close waveguides where we expect the fields to be strongest. This can be achieved by adding override_structures to the simulation grid_spec. The override structures is a list of Tidy3D structures, each with an arbitrary geometry, used exclusively for the meshing. It is added on top of any physical simulation structures. There are two types of Tidy3D structures that can be added to  override_structures list. The first type defines a fictitious medium inside the override structure so that the grid size is decided by the minimum steps per wavelength in the medium. The second type is more straightforward: one can directly define the grid size along each axis inside the override structures.

Fictitious Medium

The first type is identical to the Structure object that consists of a Geometry and a Medium. The grid step in the override_structure region is decided by the minimum steps per wavelength in this medium.

# Define a "dummy" box with a refractive index 5 around the central location of a slot waveguide.
refine_box = tidy3d.Structure(
    geometry=tidy3d.Box(center=(0, 0, 0), size=(td.inf, 0.4, 0.4)),
    medium=tidy3d.Medium(permittivity=5**2),
)

# Use the box as a grid refinement structure.
sim_refined = tidy3d.Simulation(
    size=[5, 3, 3],
    grid_spec=tidy3d.GridSpec.auto(
        wavelength=1.55,
        min_steps_per_wvl=20,
        override_structures=[refine_box],
    ),
    medium=tidy3d.Medium(permittivity=1.44**2),
    structures=[wave_guide_1, wave_guide_2],
    boundary_spec=tidy3d.BoundarySpec.all_sides(boundary=tidy3d.PML()),
    run_time=1e-12,
)

Override Structure

The second type is the tidy3d.MeshOverrideStructure object that consists of a Geometry, and a tuple dl specifying the grid sizes along x, y, and z-directions. We can override the grid sizes just along a few selected directions by setting the value to be None in the dl tuple along the other directions. E.g., if we only plan to refine the grid size along x-direction with grid size 0.01 $\mu$m, we can apply dl=(0.01, None, None). In the following, we override the grid size along y and z to be 15.5nm.

# Define a MeshOverrideStructure.
refine_box = tidy3d.MeshOverrideStructure(
    geometry=tidy3d.Box(center=(0, 0, 0), size=(td.inf, 0.4, 0.4)),
    dl=[None, 0.015, 0.015],
)

# Use the box as a grid refinement structure.
sim_refined = tidy3d.Simulation(
    size=[5, 3, 3],
    grid_spec=tidy3d.GridSpec.auto(
        wavelength=1.55,
        min_steps_per_wvl=20,
        override_structures=[refine_box],
    ),
    medium=tidy3d.Medium(permittivity=1.44**2),
    structures=[wave_guide_1, wave_guide_2],
    boundary_spec=tidy3d.BoundarySpec.all_sides(boundary=tidy3d.PML()),
    run_time=1e-12,
)

Tidy3D includes the following boundary condition types: Periodic, PECBoundary, PMCBoundary, BlochBoundary, PML, StablePML, and Absorber.

You should use tidy3d.PML boundary condition to enclose the simulation domain with layers of a special lossy material designed to absorb incoming waves from all angles with minimal reflection. Tidy3D uses PML boundary conditions by default, but you can also set the boundaries explicitly using the all_sides() method. For example:

# Define PML boundary conditions in all sides.
bspec = tidy3d.BoundarySpec.all_sides(boundary=tidy3d.PML())

# Alternatively, you can apply the boundary at specific directions.
# bspec = tidy3d.BoundarySpec.pml(x=True, y=True)

# Build the simulation.
sim = tidy3d.Simulation(
    center=(0, 0, 0),
    size=(10, 4, 4),
    boundary_spec=bspec,
    grid_spec=tidy3d.GridSpec.auto(min_steps_per_wvl=20, wavelength=1.55),
    structures=[waveguide],
    sources=[mode_source],
    monitors=[mode_monitor],
    run_time=1e-12,
)

See this notebook for more details on setting up boundary conditions.

You should use tidy3d.PECBoundary to enclose the simulation domain using perfect electric conductors. For example:

# Define PML boundary conditions in all sides.
bspec = tidy3d.BoundarySpec.all_sides(boundary=tidy3d.PECBoundary())

# Alternatively, you can apply the boundary at specific directions.
# bspec = tidy3d.BoundarySpec.pec(x=True, y=True)

# Build the simulation.
sim = tidy3d.Simulation(
    center=(0, 0, 0),
    size=(10, 4, 4),
    boundary_spec=bspec,
    grid_spec=tidy3d.GridSpec.auto(min_steps_per_wvl=20, wavelength=1.55),
    structures=[waveguide],
    sources=[mode_source],
    monitors=[mode_monitor],
    run_time=1e-12,
)

See this notebook for more details on setting up boundary conditions.

You should use tidy3d.PMCBoundary to enclose the simulation domain using perfect magnetic conductors. For example:

# Define PML boundary conditions in all sides.
bspec = tidy3d.BoundarySpec.all_sides(boundary=tidy3d.PMCBoundary())

# Alternatively, you can apply the boundary at specific directions.
# bspec = tidy3d.BoundarySpec.pmc(x=True, y=True)

# Build the simulation.
sim = tidy3d.Simulation(
    center=(0, 0, 0),
    size=(10, 4, 4),
    boundary_spec=bspec,
    grid_spec=tidy3d.GridSpec.auto(min_steps_per_wvl=20, wavelength=1.55),
    structures=[waveguide],
    sources=[mode_source],
    monitors=[mode_monitor],
    run_time=1e-12,
)