The Tidy3D client that is used for designing simulations and analyzing the results is free and open source. A Tidy3D license is required to run simulations, either from FlexCredits (see What is a FlexCredit?) or from our virtual GPU option, which is a rented cluster dedicated to the customer. FlexCredits are based on the size of the simulation (in spatial size and physical simulation duration, as opposed to compute time). 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.

A FlexCredit reflects the size of a simulation, in both grid points and timesteps. It does NOT reflect the compute time required to run the simulation, as Flexcompute’s compute time is always improving, and keeps us motivated to keep compute time as fast as possible.

However, to benchmark in more concrete terms for a new user, at the time of writing, one FlexCredit is roughly 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 resources on a supercomputer but in a more straightforward, more understandable way.

Note that FlexCredits reflect the spatial size and physical duration of a simulation, not its compute time. See What is a FlexCredit? for more details.

However, at the time of writing, one FlexCredit is roughly 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.

When running simulations in Tidy3D, your cloud storage may eventually reach its limit. This FAQ explains how to clean up space, download your data, and manage simulation files using both the GUI and the Python API.

How do I free up storage space so I can continue running simulations?

You must delete older simulation files from your cloud storage. You can do this either through the GUI or the Python API.

How do I delete simulations using the GUI?

1. Go to your Workspace:
   https://tidy3d.simulation.cloud/folders

2. Select the simulation files you want to remove.

3. A bar will appear at the bottom of the page with options to download or delete the selected files.

4. Download anything you want to keep, then delete the files to free up cloud storage.

How do I download and delete simulations using the Python API?

Download simulation data

Use the method:
web.download(task_id)
API documentation:
https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.download.html

Delete simulation data

Use the method:
td.web.delete(task_id)
API documentation:
https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.delete.html

List recent simulations

Use:
web.get_tasks
Documentation:
https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.get_tasks.html

Automatically delete old simulations

Use:
web.delete_old
Documentation:
https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.delete_old.html

Where is simulation data saved when I run a simulation?

When you run a simulation using:
web.run
Documentation:
https://docs.flexcompute.com/projects/tidy3d/en/latest/api/_autosummary/tidy3d.web.run.html

Two things happen:

1. The data is saved automatically in the cloud in the folder specified by the folder_name argument.
2. A copy is saved locally on your machine at the path specified by the path argument.

What should I do if I still have issues?

If you’re unsure which files are taking up space or need help managing your tasks, feel free to contact Tidy3D Support.

Tidy3D licenses have three different storage/memory limits:

• Hosted notebook environment RAM: in our hosted notebook environment, this is the hosted environment’s working memory used to store data and objects while the notebook is running. This is found in the bottom left corner of the notebook page next to “Mem.”
• Hosted notebook environment storage: also in our hosted notebook environment, this is the hosted environment’s disk space, for storage of the notebook files themselves. This could include simulation data run from the environment, additional benchmarking data, etc. This can also be found in the bottom left corner of the notebook page next to “Storage.”
• Cloud storage: this is where all simulation data associated to the account is stored. All data computed by Tidy3D simulations on the account is saved here. This can be found at one’s account page. This page can also be found by clicking the user icon in the upper right corner of the Tidy3D account home page and selecting “My Plan and Storage”.

To clear cloud storage, it is recommended to use Tidy3D’s web.delete() function. Tidy3D can also delete all data older than a specified number of days. Alternatively, users can manually inspect and delete tasks on the Tidy3D account workspace.

Flexcompute also provides options to upgrade to more storage and memory. Please contact us at support@flexcompute.com if interested.

Why is my Tidy3D notebook storage full if I do not see large files?

Your notebook storage may be full because hidden files or cache directories are using space. These files may not appear in the notebook file browser.

How can I check what is using the space?

Run this command in the web notebook prompt:

find ~ -mindepth 1 -maxdepth 1 -exec du -sh {} + | sort -hr | head -n 10

This shows the largest files and folders in your notebook environment, including hidden folders.

How can I clear the Tidy3D local cache?

Run this in a notebook cell:

from tidy3d.web.cache import clear as clear_cache

clear_cache()

This clears the local Tidy3D cache, which is stored by default under:

~/.cache/tidy3d/simulations

This does not delete simulations from your cloud workspace.

Note: Notebook storage is separate from cloud workspace storage in Folders.

How do I control the local cache in Tidy3D?

You can control the local cache in Tidy3D by setting td.config.local_cache.enabled to True or False.

import tidy3d as td

td.config.local_cache.enabled = False  # Set to True to enable it again.

Without saving, this change only applies to the current Python session. To keep the setting for future sessions, save the configuration:

td.config.save()

The local cache stores reusable simulation artifacts on your machine to avoid recomputing or re-downloading them when possible.

What Are the Hidden Files in the Python Web Notebook?

When you open the storage popover in the Tidy3D Python Web Notebook, you’ll see your usage broken into:

• Notebook Total Usage — everything in your notebook environment.
• Simulation Files — your notebook, scripts, and other simulation files such as .hdf5 / .json files you’ve saved from web.run() and similar calls, visible in the file browser.
• Hidden Files — everything else in your home directory that doesn’t show up in the file browser by default.
• Notebook Storage Limit — your account’s storage quota for this notebook environment (separate from your cloud workspace).

This FAQ explains what those hidden files are, how to see them, and how to free space when they grow large.

What are hidden files?

Hidden files and folders are entries whose name starts with a dot (.cache, .jupyter, .local, .ipynb_checkpoints, .git, .config, …). The notebook file browser hides them by default to keep the view focused on your work.

They are created automatically by the notebook and by Tidy3D itself, and typically include:

• .cache/tidy3d/ — the local Tidy3D simulation cache. Stores results of web.run() so re-running the same simulation doesn’t re-download or re-execute it. This is usually the largest contributor.
• .ipynb_checkpoints/ — JupyterLab auto-save snapshots of your notebooks.
• .jupyter/, .local/, .config/ — JupyterLab and Python package settings.
• .git/ — if a folder is a git repository, this stores its history.

These files are normal — they’re not leftover junk and you don’t need to manage them day-to-day. But they do count toward your Notebook Storage Limit, which is why they appear in the storage popover.

How do I show or hide them?

In the notebook menu bar:

View → Show Hidden Files

Toggling it on shows all dotfiles and dotfolders in the file browser; toggling it off restores the default clean view. The setting is per-session.

How do I see what’s actually using my space?

Open a terminal in the notebook (File → New → Terminal) and run:

find ~ -mindepth 1 -maxdepth 1 -exec du -sh {} + | sort -hr | head -n 10

This lists the ten largest items in your home directory, including hidden folders, so you can see which one is responsible for the usage.

See: Why is my Tidy3D notebook storage full if I do not see large files?

How do I clear the Tidy3D local cache?

If .cache/tidy3d/ is large and you don’t need its contents, clear it from a notebook cell:

from tidy3d.web.cache import clear as clear_cache

clear_cache()

The cache lives at ~/.cache/tidy3d/simulations by default. Clearing it frees the corresponding Hidden Files space immediately.

This does not delete your cloud simulations. Your tasks in Folders are unaffected — only the local copies used to skip re-runs are removed.

You can also control whether the cache is used at all, set a size limit, or change its directory via td.config.local_cache. See: How do I control the local cache in Tidy3D?

Important to know

• Notebook storage ≠ cloud workspace storage. Hidden Files are on your notebook environment’s disk. Simulations you’ve submitted live separately in your cloud Folders and are governed by your cloud workspace quota.
• It’s safe to clear the Tidy3D cache. It only affects re-run speed for identical simulations; nothing about your results, notebooks, or cloud data is lost.
• It’s not always safe to delete other dotfolders. .jupyter/ and .local/ hold settings; .git/ holds your version history. Prefer the clear_cache() approach above unless you know what a folder is.

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 beginner tutorial and this advanced tutorial.

For a single-step simulation, create a web.Job and call job.upload(). Uploading creates the server task but does not start it, so you can inspect it before continuing:

from tidy3d import web

job = web.Job(simulation=sim, task_name="task_name", verbose=True)
job.upload()

# Inspect the uploaded task, then explicitly start it when ready.
job.start()
job.monitor()
sim_data = job.load(path="out/simulation.hdf5")

The separate upload(), start(), and monitor() methods are available only for single-step jobs. Multi-step Heat and HeatCharge jobs do not have one singular task_id; use job.step() to advance and inspect one workflow step at a time, read job.task_ids for the per-step server IDs, or use job.run() to execute the whole workflow.

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. For a multi-step Heat or HeatCharge job, this estimates the next incomplete step only; call job.step() and then estimate again before starting the following step.

# Initialize a job.
job = web.Job(simulation=sim, task_name="job", verbose=verbose)

# Estimate the maximum cost before running.
estimated_cost = job.estimate_cost()

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.

Use job.real_cost() to obtain the billed cost of a completed job. The method handles both single-step and multi-step workflows; for a completed multi-step Heat or HeatCharge job it returns the total billed cost of the workflow’s server tasks. The real cost may not be available immediately after the simulation finishes.

import time

# Initialize a job.
job = web.Job(simulation=sim, task_name="job", verbose=verbose)

# Estimate the maximum cost before running.
estimated_cost = job.estimate_cost()

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 = job.real_cost()

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. For a multi-step Heat or HeatCharge job, job.estimate_cost() estimates the next incomplete step only; call it again after completing that step with job.step().

# Initialize a job.
job = tidy3d.web.Job(simulation=sim, task_name="job", verbose=verbose)

# Estimate the maximum cost before running the simulation.
estimated_cost = job.estimate_cost()
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.

How do I run a parameter sweep?

web.run is the unified interface for running simulations on the Tidy3D cloud.

For parameter sweeps and multi-simulation workflows, web.run accepts not only a single simulation, but also dictionaries, lists, tuples, and nested combinations of these.

As shown in ParameterScanWebRun.ipynb, using a dictionary is convenient because each dictionary key is retained in the returned results mapping.

When should I use it?

• Parameter sweeps
• Design of experiments workflows
• Any scripted workflow involving many related simulations

Running many simulations

Create a dictionary of simulations and pass it directly to web.run:

import tidy3d as td
from tidy3d import web

sims = {
    "run_a": sim_a,
    "run_b": sim_b,
}

results = web.run(sims, path = 'sweep')

Here, web.run handles submission, monitoring, and loading of all simulations in one call.

Accessing results

The returned object can be indexed by task name or iterated over:

sim_data_a = results["run_a"]

for simulation_key, sim_data in results.items():
    print(simulation_key, sim_data)

This makes web.run a natural choice for parameter sweeps where result keys are derived from parameter values.

Related note

Older workflows may use tidy3d.web.Batch for multi-simulation execution. web.run provides a simpler unified interface for the workflow shown in ParameterScanWebRun.ipynb.

How do I reuse structural preprocessing in a source sweep?

When many FDTD simulations use the same geometry, materials, grid, and boundaries, Tidy3D can store the structural preprocessing from one simulation and reuse it in compatible child simulations. This is most useful when preprocessing complex geometry, such as a detailed STL, is expensive compared with time stepping.

The producer is an ordinary FDTD task: it still runs to completion and returns normal SimulationData. Set store_preprocess_cache=True on a web.Job, run it, and retain its task ID:

from tidy3d import web

producer = web.Job(
    simulation=base_simulation,
    task_name="cache_producer",
    store_preprocess_cache=True,
)
producer_data = producer.run()
producer_task_id = producer.task_id

Pass that task ID as the single parent of each compatible child. The same parent can serve an entire sweep:

simulations = {
    "x_pol": base_simulation.updated_copy(sources=[source_x]),
    "y_pol": base_simulation.updated_copy(sources=[source_y]),
}

batch = web.Batch(
    simulations=simulations,
    parent_tasks={name: (producer_task_id,) for name in simulations},
)
results = batch.run(path_dir="source_sweep_results")

Each child repeats source setup, monitor setup, and time stepping, but skips the reusable C++ structural preprocessing. Children may use different compute resources or MPI chunking from the producer. Their results remain ordinary SimulationData objects.

Tidy3D checks compatibility before starting a child. Audited source controls such as position, polarization, amplitude, phase, waveform timing, and custom waveform or spatial-profile data may differ. Run time, shutoff, result normalization, low-frequency smoothing, and eligible monitor definitions may also differ. Inputs that determine structural preprocessing must remain compatible, including geometry, media, grid, boundaries, source classes and order, and source frequency support. The center of a mode source with a PEC frame is structural and therefore cannot change. Producer and child simulations must also use the same Tidy3D client version. Upgrading Tidy3D changes the compatibility signature, even when the physical inputs are unchanged.

Preprocessing caches currently support only ordinary, non-autograd FDTD simulations. Custom media, surface-field monitors, monitors that require medium-output preprocessing, and point-cloud field monitors requesting displacement fields are not supported. The client reports these eligibility or compatibility problems before allocating the child solver task.

The cache is an internal task artifact rather than a downloadable simulation result. The producer must finish successfully before its children are submitted, and the artifact must still be retained when a child runs.

How do I submit multiple simulations?

web.run is the unified interface for running simulations on the Tidy3D cloud.

For parameter scans and multi-simulation workflows, web.run accepts not only a single simulation, but also dictionaries, lists, tuples, and nested combinations of these.

As shown in ParameterScanWebRun.ipynb, using a dictionary is convenient because each dictionary key is retained in the returned results mapping.

When should I use it?

• Parameter sweeps
• Design-of-experiments workflows
• Any scripted workflow involving many related simulations

Running many simulations

Create a dictionary of simulations and pass it directly to web.run:

import tidy3d as td
from tidy3d import web

sims = {
    "run_a": sim_a,
    "run_b": sim_b,
}

results = web.run(sims, verbose=True)

Here, web.run handles submission, monitoring, and loading of all simulations in one call.

Accessing results

The returned object can be indexed by task name or iterated over:

sim_data_a = results["run_a"]

for simulation_key, sim_data in results.items():
    print(simulation_key, sim_data)

This makes web.run a natural choice for parameter scans where result keys are derived from parameter values.

Related note

Older workflows may use tidy3d.web.Batch for multi-simulation execution. web.run provides a simpler, unified interface for the workflow shown in ParameterScanWebRun.ipynb.

How to iterate through results from a multi-simulation web.run workflow?

When using web.run on multiple simulations, the returned object preserves the same input structure. This works for dictionaries, lists, tuples, and nested combinations of them.

For example, when web.run is called on a dictionary of simulations, the returned object can be iterated over by the original dictionary key:

from tidy3d import web

sims = {
    "sim_1": sim_1,
    "sim_2": sim_2,
    "sim_3": sim_3,
}

results = web.run(sims, verbose=True)

for simulation_key, sim_data in results.items():
    print(simulation_key)
    print(sim_data)

This gives access to each SimulationData object for postprocessing.

web.run also supports other input structures. For example, if the input is a list of simulations, the output is a list of results in the same order. If the input is a nested combination, such as a list of dictionaries or a nested list, the output keeps that same structure, making it straightforward to iterate through each group in a way that matches the original parameter scan.

You can find more examples on this tutorial.

How do I abort a job with multiple simulations?

When using web.run on multiple simulations, the path argument specifies an output directory. The batch checkpoint is saved as <path>/batch.hdf5; by default, it is saved as batch.hdf5 in the current working directory.

To stop selected unfinished tasks while retaining the other results, load the web.Batch object and call web.abort with each task ID you intend to cancel:

batch = web.Batch.from_file('path/batch.hdf5')

# Inspect the server task IDs and statuses stored in this checkpoint.
for batch_name, job in batch.jobs.items():
    print(batch_name, job.status, job.task_ids)

# Paste the server task IDs for unfinished tasks from the output above.
task_ids_to_abort = input("Server task IDs to abort (space-separated): ").split()
for task_id in task_ids_to_abort:
    web.abort(task_id)

Each job.task_ids mapping contains the server task ID for every resolved workflow step. This works for both single-step simulations and multi-step workflows such as Heat or HeatCharge; skip any step whose task ID is still None.

The checkpoint created by web.run does not retain the caller’s original dictionary keys or nesting, so use the server task IDs printed from batch.jobs, not the original input keys. If you need stable caller-defined names for selective cancellation, construct and save a web.Batch directly.

Batch.delete() is not a cancellation-only operation: it permanently deletes every server-side task associated with the batch, including completed results and their data. Use it only when you intend to discard the entire batch.

How do I save or load a multi-simulation task?

When using web.run on multiple simulations, the path argument specifies an output directory. The batch checkpoint is saved as <path>/batch.hdf5; by default, it is saved as batch.hdf5 in the current working directory.

You can load the object and data by calling the web.Batch.from_file and load methods:

batch = web.Batch.from_file("path/batch.hdf5")
batch_data = batch.load(path_dir="path")

When web.run is called with a dictionary, list, tuple, or nested combination, its direct return value preserves that structure. The accompanying batch.hdf5 checkpoint records the submitted tasks, but reloading it does not recreate the caller’s original keys, indices, or nesting. If you need the original structure later, save the direct web.run result or store your own mapping alongside the checkpoint.

A Batch that you construct directly from a nested simulation container behaves differently: its Batch.to_file() and Batch.from_file() round trip preserves that Batch container structure.

How can I estimate the cost of a parameter sweep?

When running multiple simulations, you can estimate the total cost before submission using web.Batch(...).estimate_cost().

web.Batch accepts simulations in nested lists, tuples, and dictionaries with string keys, so you can keep the structure used to define your sweep.

Example

from tidy3d import web

cost = web.Batch(simulations=sims).estimate_cost()
print(cost)

Manual flattening is optional and is only needed when you want to assign custom flat task names.

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.

Tidy3D resolves material overlap by their priority - see here for details.

If the priority matches what is needed and the material overlap still does not appear, be sure to check symmetry settings, as the specified symmetry must match the structure symmetry of the simulation.

The web-based Python notebook environment in tidy3d.simulation.cloud only has access to 8 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 8 GB.

If symmetries are not used in the simulation, memory usage can be reduced by calling data = sim_data.monitor_data['monitor_name'] instead of data = sim_data['monitor_name']. The latter creates a copy of the monitor data and expands it to include the symmetric parts, if applicable.

However, if symmetries are used in the simulation, data = sim_data.monitor_data['monitor_name'] will return data only for the simulated portion of the volume, and not the symmetric extensions. For example, if symmetry is applied in the x-plane, only half of the data will be returned.

Note that many analyses can still be performed with this partial data. For instance, the mode volume can be computed using the non-expanded monitor and then multiplied by the appropriate factor (2, 4, or 8 for 1, 2, or 3 symmetry planes, respectively). An example of this approach can be seen in this example.

How to debug SSL communication issues?

Users operating within corporate networks, through a VPN, or behind a proxy server may sometimes encounter SSL errors when running the tidy3d python client in their local machines. Note you can always use the python client with our cloud-hosted notebook server.

These errors can occur because the corporate network’s security measures, intercepts, and re-encrypts HTTPS traffic.

A common error message looks like this:

requests.exceptions.SSLError: HTTPSConnectionPool(host='tidy3d-api.simulation.cloud', port=443): Max retries exceeded with url: ... (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate ...')))

Note that sometimes, SSL errors can also manifest as authentication errors, or communication timeout errors.

In this FAQ, we will overview some steps to help you debug and resolve this issue.

Step 0: Windows quick fix

Sometimes on Windows running the following will resolve the problem right away. Try this first:

pip install pip-system-certs

If this doesn’t work, proceed with the rest of this guide.

Step 1: The Recommended & Most Secure Solution

The most robust and secure solution is to have your IT department add the Tidy3D SSL certificate to your system’s trust store. This allows your machine to verify our servers’ identity correctly without disabling security features.

Action: Please ask your network administrator to whitelist the API endpoint https://tidy3d-api.simulation.cloud and install the following root certificate https://github.com/flexcompute/tidy3d/blob/develop/tidy3d/web/api/cacert.pem

If these steps do not resolve your issue, please contact our support team and provide the logs from the commands you have tried.

Step 2: Verify Your Environment and Connectivity

Before changing any settings, let’s make sure you can reach the Tidy3D servers.

Test connectivity using ping. This helps confirm if the issue is with SSL verification or basic network access. You should run these commands from your command line (Terminal, PowerShell, or the Anaconda Prompt).

• Test connection to the web server:

  ○ → ping -c 3 tidy3d.simulation.cloud
  PING tidy3d.simulation.cloud (3.160.231.60) 56(84) bytes of data.
  64 bytes from server-3-160-231-60.mad53.r.cloudfront.net (3.160.231.60): icmp_seq=1 ttl=245 time=58.7 ms
  64 bytes from server-3-160-231-60.mad53.r.cloudfront.net (3.160.231.60): icmp_seq=2 ttl=245 time=77.9 ms
  64 bytes from server-3-160-231-60.mad53.r.cloudfront.net (3.160.231.60): icmp_seq=3 ttl=245 time=69.2 ms
  
  --- tidy3d.simulation.cloud ping statistics ---
  3 packets transmitted, 3 received, 0% packet loss, time 2002ms
  rtt min/avg/max/mdev = 58.661/68.594/77.930/7.877 ms
  

• Test connection to the API endpoints:

  ○ → curl -X GET https://tidy3d-api.simulation.cloud
  {
    "error" : "Unauthorized",
    "detail" : "Access is denied",
    "code" : "401",
    "httpStatus" : "401 UNAUTHORIZED",
    "warning" : ""
  }
  

  Expected output: A 401 Unauthorized error message. This is good news; it means you can reach our API server, and the problem is likely with authentication or SSL certificate verification.

Note that many networks can block ping messages so this is not a foolproof check.

Step 3: Disable SSL Verification (Quick Workaround)

As a temporary solution, you can instruct tidy3d to bypass SSL certificate verification. This is not ideal for security but is useful for confirming the source of the problem.

This is done by setting the TIDY3D_SSL_VERIFY environment variable to false.

Setting the Environment Variable:

• On Windows (in Command Prompt):

  set TIDY3D_SSL_VERIFY=false
  

  To set it permanently, use setx TIDY3D_SSL_VERIFY false.

• On macOS or Linux (in a bash terminal):

  export TIDY3D_SSL_VERIFY="false"
  

Note thet the user could run into unexpected server communication issues by disabling SSL. This is not recommended.

Verifying the Environment Variable:

It is essential to ensure the variable is set correctly within the environment where you run your script.

• In your terminal, run the following command.

  • Windows: echo %TIDY3D_SSL_VERIFY%
  • macOS/Linux: echo $TIDY3D_SSL_VERIFY
  • The output should be false.

• Inside your Python script, add these lines to the top to see what value the script is reading:

import os
print(f"TIDY3D_SSL_VERIFY is set to: {os.getenv('TIDY3D_SSL_VERIFY')}")

When you run your script, you should see the confirmation printed. If you see None or an empty string, the variable was not set correctly in your current session.

Step 4: Run a Diagnostic Script

If the issue persists, running a minimal script can help isolate the problem to the requests library, which tidy3d uses for communication.

1. Save the following code as a Python file (e.g., test_connection.py).
2. Set the TIDY3D_API_KEY and TIDY3D_SSL_VERIFY environment variables in your terminal as shown in Step 2.
3. Run the script with python test_connection.py.

# test_connection.py
import os
import requests
from tidy3d.web.core.constants import HEADER_APIKEY
from tidy3d.web.core.environment import Env

def auth(req):
    """Adds the API key to the request header."""
    # Ensure TIDY3D_API_KEY is set in your environment
    req.headers[HEADER_APIKEY] = os.getenv("TIDY3D_API_KEY")
    return req

# Let tidy3d's environment configuration read the SSL variable
# It reads from the TIDY3D_SSL_VERIFY environment variable.
ssl_verify_setting = Env.current.ssl_verify

print(f"API Endpoint: {Env.current.web_api_endpoint}")
print(f"SSL Verification Enabled: {ssl_verify_setting}")

if not ssl_verify_setting:
    # Suppress the warning that will be printed for unverified requests
    requests.packages.urllib3.disable_warnings(requests.packages.urllib3.exceptions.InsecureRequestWarning)
    print("InsecureRequestWarning suppressed.")

try:
    req = requests.Request("GET", f"{Env.current.web_api_endpoint}/apikey")
    auth(req)
    resp = requests.get(req.url, headers=req.headers, verify=ssl_verify_setting)
    
    print(f"Response: {resp}")
    print(f"Status Code: {resp.status_code}")
    print(f"Response Content: {resp.content}")

except requests.exceptions.SSLError as e:
    print(f"\nCaught an SSLError. This is the core issue.\nDetails: {e}")

except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")

With TIDY3D_SSL_VERIFY set to false and TIDY3D_API_KEY set correctly, the expected output is a status code: 200 and content containing your API key. You will also see an InsecureRequestWarning if you don’t suppress it.

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.

from tidy3d import FullyAnisotropicMedium

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. Because these diagonal entries are standard medium models, they follow the usual material preprocessing path, including subpixel averaging where the relevant solver or workflow supports it. For example:

from tidy3d import AnisotropicMedium, Medium

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.

import tidy3d as td

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:

import tidy3d as td

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 = td.Graphene(
#    gamma=gamma, mu_c=mu_c, temp=temp, scaling=scaling
# ).medium

To create a nonlinear material, define one or more nonlinear models, collect them in a tidy3d.NonlinearSpec, and pass that specification to the nonlinear_spec parameter of the medium. For example:

import tidy3d

nonlinear_model = tidy3d.NonlinearSusceptibility(chi3=1)
nonlinear_spec = tidy3d.NonlinearSpec(models=[nonlinear_model], num_iters=5)
medium = tidy3d.Medium(permittivity=2, nonlinear_spec=nonlinear_spec)

After fitting a medium, as described here, it is possible to save the fitted medium as an hdf5 file and save time when using it in another model. To save the file, just use the .to_file method:

fitted_medium.to_file('medium_name.hdf5')

Now, the saved medium can be loaded with the PoleResidue .from_file method:

loaded_medium = td.PoleResidue.from_file('medium_name.hdf5')

To use this medium via the web GUI, you have two options:

(a): open the “Material Utilities”, select the “Private Library”, and click the “Upload Material” button;

(b): in the workbench, create a new medium and choose the “Import Material” option in the “Add Medium” panel.

Starting with tidy3d 2.12, the pole-residue fits behind seven metal variants of the material library were replaced, because the previous coefficients did not match their own reference datasets: Al 'Rakic1995', Cr 'Rakic1998BB', Be 'Rakic1998BB', Au 'Olmon2012evaporated', Ag 'Rakic1998BB', Pt 'Werner2009', and Ti 'Werner2009'. Each of these is also the default variant for its material, so simulation results change wherever these materials are used — whether the variant is selected explicitly or via the default — across their entire (unchanged) validity ranges. The worst cases were large: aluminum returned a non-physical real index (n’ of 5–7.5 across the visible and near-IR, where it should be roughly 0.8–1.8), and default gold had no interband response (n = 0.04 at 400 nm where its dataset gives 1.59).

Old vs. new values

Refractive index (n, k) at representative wavelengths — reference data vs. the old and new fits:

The pattern: the old fits were fine in the infrared but wrong in the ultraviolet/visible. The new fits track the reference data at every tabulated point over each variant’s full validity range, and all fits (old and new) are passive and stable.

Full-range comparison (data = circles, old fit = dashed, new fit = solid):

Why the old fits were wrong

The aluminum, chromium, and beryllium coefficients regressed in a 2023 bulk re-fit of the library: fitting each dataset’s full tabulated range with globally weighted least squares lets the infrared tail of a metal’s permittivity (which is thousands of times larger than its visible value) dominate the objective, so the visible-band fit collapses while remaining perfectly passive — no physicality check could catch it. The gold, silver, platinum, and titanium fits were older, low-order fits that under-resolved the visible/interband structure of their datasets. The replacements were fit with an improved vector-fitting backend and are verified against the reference data at every tabulated point, with library-wide accuracy regression tests added so this cannot recur silently.

Am I seeing old or new values? (quick check)

Evaluate the material at a probe wavelength and compare with the table above. The sharpest signatures:

• Al: n’ greater than ~3 anywhere in 500–1700 nm means old (broken) coefficients; new gives n’ = 0.82 / 1.59 at 500 / 1550 nm.
• Au (default): n = 0.04 at 400 nm means old; new gives 1.67.
• Pt: n = 0.33 at 451 nm means old; new gives 0.63.
• Cr: n = 2.86 at 637 nm means old; new gives 3.35.

Simulating only in the infrared? Use the _IR variants

The corrected fits need more poles (up to twice as many), and FDTD cost grows with pole count. Where the previous coefficients matched the reference data to within 2% at every tabulated point over a contiguous infrared band, they remain in the library as lower-cost _IR variants, with validity ranges narrowed to exactly those bands:

Inside these bands the _IR variants are as accurate as the new defaults and match pre-update results, so they double as a reproducibility path for infrared studies. There is no _IR variant for Al (the old fit was inaccurate at all wavelengths, infrared included), nor for Pt/Ti (their dataset ends at 2.48 µm, so there is no infrared band to certify). Using a variant outside its valid band produces the standard validity-range warning.

Reproducing results computed with the old coefficients

The recommended way to keep a study self-consistent is to pin the tidy3d version it started with. For infrared-band studies of Au, Ag, Cr, or Be, the _IR variants above are the old coefficients. Otherwise, the old coefficients can be used directly as custom media (they remain valid PoleResidue models — inaccurate against the reference data, but passive and stable):

import tidy3d as td

# Pre-update ('legacy') coefficients of the re-fit variants. These do NOT match
# the reference data (that is why they were replaced); use them only to
# reproduce results computed before the update.
LEGACY_MEDIUMS = {
    ("Al", "Rakic1995"): td.PoleResidue(
        eps_inf=1.0,
        poles=[
            ((-176076476399307.25-0j), (-2.0497198166085053e+17-0j)),
            ((-55958309702844.36-0j), (-1.9328759376610138e+18-0j)),
            ((-32886941985772.406-0j), (2.985600009810314e+17-0j)),
            ((-836904963.7321033-0j), (1.9664479588602982e+18-0j)),
        ],
        frequency_range=(151926744799612.75, 1.5192674479961274e+16),
    ),
    ("Cr", "Rakic1998BB"): td.PoleResidue(
        eps_inf=1.0,
        poles=[
            ((-73056488139432.73-0j), (-2.7457982793225763e+17-0j)),
            ((-145384800564.84518-0j), (2.8558672134946093e+17-0j)),
            ((-2137728163059224-740097502616341.5j), (5846984237158586+9.545555973191486e+16j)),
        ],
        frequency_range=(4835362227919.29, 1208840556979822.5),
    ),
    ("Be", "Rakic1998BB"): td.PoleResidue(
        eps_inf=1.0,
        poles=[
            ((-1737739552967275.2-0j), (2.3924381023090224e+16-0j)),
            ((-151352273074186.28-0j), (4367049766016236.5-0j)),
            ((-53296876831178.09-0j), (-6.001139611206947e+17-0j)),
            ((-20238020062.550835-0j), (6.055916356024831e+17-0j)),
        ],
        frequency_range=(4835978484543.8545, 1208994621135963.5),
    ),
    ("Au", "Olmon2012evaporated"): td.PoleResidue(
        eps_inf=5.632132676065586,
        poles=[
            ((-208702733035001.06-205285605362650.1j), (-5278287093117479+1877992342820785.5j)),
            ((-5802337384288.284-6750566414892.662j), (4391102400709820+6.164348337888482e+18j)),
            ((-56597670698540.76-8080114483410.944j), (895004078070708.5+5.346045584373232e+18j)),
        ],
        frequency_range=(12025369359446.29, 999308193769986.8),
    ),
    ("Ag", "Rakic1998BB"): td.PoleResidue(
        eps_inf=2.080628548409516,
        poles=[
            ((-74116405167315.4-0j), (-1.0385354711010449e+18-0j)),
            ((-199290207342.26654-0j), (1.0396417727844411e+18-0j)),
            ((-622425347820110.2-6539570627133650j), (936046890626063+1966533189396127.8j)),
        ],
        frequency_range=(24179892422719.273, 1208994621135963.5),
    ),
    ("Pt", "Werner2009"): td.PoleResidue(
        eps_inf=1.0,
        poles=[
            ((-9288886703545810-1.9809701816539028e+16j), (-2559720539992317+2.619854823299511e+16j)),
            ((-113303296165008.06-132666543091888.84j), (5059991338597539+1.459321906232765e+18j)),
            ((-525913270217765.06-4665172268701287j), (4280438237239983.5+1882099733932914.8j)),
        ],
        frequency_range=(120884055879414.03, 2997924585809468.0),
    ),
    ("Ti", "Werner2009"): td.PoleResidue(
        eps_inf=1.0,
        poles=[
            ((-1316659173032264.2-4853426451943540j), (6846803510207887+3451315459947241.5j)),
            ((-234898849175817.28-1643952885872075.5j), (-1039094910406333.4+2786587583155544.5j)),
            ((-9631968003009.37-107553157768951.47j), (5856843593653923+1.1954179403843133e+18j)),
        ],
        frequency_range=(120884055879414.03, 2997924585809468.0),
    ),
}
# example: reproduce pre-2.12 default aluminum
old_al = LEGACY_MEDIUMS[("Al", "Rakic1995")]

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(geo_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:

sphere = tidy3d.Sphere(
    center=(0, 0, 0),
    radius=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:

import numpy as np
import tidy3d

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.

import numpy as np
import tidy3d

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

import numpy as np
import tidy3d

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 = tidy3d.Transformed(
    geometry=tidy3d.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/). 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.

For oblique incidence, there are two possible settings: fixed in-plane k-vector and fixed-angle mode. The first requires Bloch periodic boundary conditions, and the incidence angle is exact only at the central wavelength. The latter requires periodic boundary conditions and maintains a constant propagation angle over a broadband spectrum. For more information and important notes, refer to this example: Broadband PlaneWave With Constant Oblique Incident Angle.

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. The example below asks for two modes in a silicon-on-insulator (SOI) waveguide operating at 1.55 $\mu$m, groups TE-like modes first, and injects the second returned mode.

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

# Mode specification. Group TE-like modes first, then verify the returned modes.
mode_spec = tidy3d.ModeSpec(
    target_neff=3.47,
    num_modes=2,
    sort_spec=tidy3d.ModeSortSpec(
        filter_key="TE_fraction",
        filter_reference=0.5,
    ),
)

# 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,  # Select the second returned mode (zero-based).
    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 decreasing effective index by default. Here, sort_spec uses tidy3d.ModeSortSpec to place TE-like modes first by filtering on TE_fraction >= 0.5; within each group, modes use the default ordering by decreasing effective index. The zero-based mode_index=1 selects the second returned mode, but TE-like grouping does not by itself identify that mode as TE1. Solve and inspect the modal fields and polarization fractions for your specific geometry before choosing the index.

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. The example below asks for two modes in a silicon-on-insulator (SOI) waveguide operating at 1.55 $\mu$m, groups TE-like modes first, and injects the second returned mode:

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

# Mode specification. Group TE-like modes first, then verify the returned modes.
mode_spec = tidy3d.ModeSpec(
    target_neff=3.47,
    num_modes=2,
    sort_spec=tidy3d.ModeSortSpec(
        filter_key="TE_fraction",
        filter_reference=0.5,
    ),
)

# 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,  # Select the second returned mode (zero-based).
    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 decreasing effective index by default. Here, sort_spec uses tidy3d.ModeSortSpec to place TE-like modes first by filtering on TE_fraction >= 0.5; within each group, modes use the default ordering by decreasing effective index. The zero-based mode_index=1 selects the second returned mode, but TE-like grouping does not by itself identify that mode as TE1. Solve and inspect the modal fields and polarization fractions for your specific geometry before choosing the index.

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