API Reference#

Simulation#

Simulation#

Simulation(*[, type, center, medium, ...])

Contains all information about Tidy3d simulation.

Boundary Conditions#

BoundarySpec(*[, x, y, z, type])

Specifies boundary conditions on each side of the domain and along each dimension.

Boundary(*[, plus, minus, type])

Boundary conditions at the minus and plus extents along a dimension

BoundaryEdge(*[, name, type])

Electromagnetic boundary condition at a domain edge.

Types of Boundaries#

Periodic(*[, name, type])

Periodic boundary condition class.

PECBoundary(*[, name, type])

Perfect electric conductor boundary condition class.

PMCBoundary(*[, name, type])

Perfect magnetic conductor boundary condition class.

BlochBoundary(*[, name, type])

Specifies a Bloch boundary condition along a single dimension.

Absorbing Boundaries#

Types of Absorbers#

PML(*[, name, type, num_layers, parameters])

Specifies a standard PML along a single dimension.

StablePML(*[, name, type, num_layers, ...])

Specifies a 'stable' PML along a single dimension.

Absorber(*[, name, type, num_layers, parameters])

Specifies an adiabatic absorber along a single dimension.

Absorber Parameters#

AbsorberParams(*[, sigma_order, sigma_min, ...])

Specifies parameters common to Absorbers and PMLs.

PMLParams(*[, sigma_order, sigma_min, ...])

Specifies full set of parameters needed for complex, frequency-shifted PML.

Geometry#

Box(*[, type, center])

Rectangular prism.

Sphere(*[, type, center])

Spherical geometry.

Cylinder(*[, type, axis, sidewall_angle, ...])

Cylindrical geometry with optional sidewall angle along axis direction.

PolySlab(*, type, axis, 1, 2] = 2, ...[, ndim])

Polygon extruded with optional sidewall angle along axis direction.

TriangleMesh(*[, type])

Custom surface geometry given by a triangle mesh, as in the STL file format.

GeometryGroup(*[, type])

A collection of Geometry objects that can be called as a single geometry object.

ClipOperation(*[, type])

Class representing the result of a set operation between geometries.

Transformations#

RotationAroundAxis(*[, type, axis, angle])

Rotation of vectors and tensors around a given vector.

Mediums#

Non-Dispersive Medium#

Spatially uniform#

Medium(*[, name, frequency_range, ...])

Dispersionless medium.

PECMedium(*[, name, frequency_range, ...])

Perfect electrical conductor class.

FullyAnisotropicMedium(*, name, ...[, ndim, ...])

Fully anisotropic medium including all 9 components of the permittivity and conductivity tensors.

Spatially varying#

CustomMedium(*[, name, frequency_range, ...])

Medium with user-supplied permittivity distribution.

Dispersive Mediums#

Spatially uniform#

PoleResidue(*[, name, frequency_range, ...])

A dispersive medium described by the pole-residue pair model.

Lorentz(*[, name, frequency_range, ...])

A dispersive medium described by the Lorentz model.

Sellmeier(*[, name, frequency_range, ...])

A dispersive medium described by the Sellmeier model.

Drude(*[, name, frequency_range, ...])

A dispersive medium described by the Drude model.

Debye(*[, name, frequency_range, ...])

A dispersive medium described by the Debye model.

Spatially varying#

CustomPoleResidue(*[, name, ...])

A spatially varying dispersive medium described by the pole-residue pair model.

CustomLorentz(*[, name, frequency_range, ...])

A spatially varying dispersive medium described by the Lorentz model.

CustomSellmeier(*[, name, frequency_range, ...])

A spatially varying dispersive medium described by the Sellmeier model.

CustomDrude(*[, name, frequency_range, ...])

A spatially varying dispersive medium described by the Drude model.

CustomDebye(*[, name, frequency_range, ...])

A spatially varying dispersive medium described by the Debye model.

General Mediums (can be both dispersive and non-dispersive)#

Spatially uniform#

AnisotropicMedium(*[, name, ...])

Diagonally anisotropic medium.

Medium2D(*[, name, frequency_range, ...])

2D diagonally anisotropic medium.

Spatially varying#

CustomAnisotropicMedium(*[, name, ...])

Diagonally anisotropic medium with spatially varying permittivity in each component.

Medium Specifications (add properties to existing Medium)#

Nonlinear#

NonlinearSpec(*[, models, num_iters, type])

Abstract specification for adding nonlinearities to a medium.

NonlinearSusceptibility(*[, type, chi3, ...])

Model for an instantaneous nonlinear chi3 susceptibility.

KerrNonlinearity(*[, type, n2, n0])

Model for Kerr nonlinearity which gives an intensity-dependent refractive index of the form \(n = n_0 + n_2 I\).

TwoPhotonAbsorption(*[, type, beta, n0])

Model for two-photon absorption (TPA) nonlinearity which gives an intensity-dependent absorption of the form \(\alpha = \alpha_0 + \beta I\).

Time Modulation#

ModulationSpec(*[, permittivity, ...])

Specification adding space-time modulation to the non-dispersive part of medium including relative permittivity at infinite frequency and electric conductivity.

SpaceTimeModulation(*[, space_modulation, type])

Space-time modulation applied to a medium, adding on top of the time-independent part.

ContinuousWaveTimeModulation(*[, amplitude, ...])

Class describing modulation with a harmonic time dependence.

SpaceModulation(*[, type, amplitude, phase, ...])

The modulation profile with a user-supplied spatial distribution of amplitude and phase.

Medium Perturbations#

Mediums with Heat and Charge Perturbation Models#

PerturbationMedium(*[, subpixel, type, ...])

Dispersionless medium with perturbations.

PerturbationPoleResidue(*[, subpixel, type, ...])

A dispersive medium described by the pole-residue pair model with perturbations.

Perturbation Specifications of Individual Parameters#

ParameterPerturbation(*[, heat, charge, type])

Stores information about parameter perturbations due to different physical effect.

LinearHeatPerturbation(*[, type, ...])

Specifies parameter's perturbation due to thermal effects as a linear function of temperature:

CustomHeatPerturbation(*[, type, ...])

Specifies parameter's perturbation due to thermal effects as a custom function of temperature defined as an array of perturbation values at sample temperature points.

LinearChargePerturbation(*[, type, ...])

Specifies parameter's perturbation due to free carrier effects as a linear function of electron and hole densities:

CustomChargePerturbation(*[, type, ...])

Specifies parameter's perturbation due to free carrier effects as a custom function of electron and hole densities defined as a two-dimensional array of perturbation values at sample electron and hole density points.

Material Library#

Structures#

Structure(*, geometry[, name, type])

Defines a physical object that interacts with the electromagnetic fields.

MeshOverrideStructure(*, geometry[, name, ...])

Defines an object that is only used in the process of generating the mesh.

Sources#

Types of Sources#

PointDipole(*[, name, type, center, size, ...])

Uniform current source with a zero size.

UniformCurrentSource(*[, name, type, ...])

Source in a rectangular volume with uniform time dependence.

PlaneWave(*[, name, type, center, ...])

Uniform current distribution on an infinite extent plane.

ModeSource(*[, name, type, center, ...])

Injects current source to excite modal profile on finite extent plane.

GaussianBeam(*[, name, type, center, ...])

Guassian distribution on finite extent plane.

AstigmaticGaussianBeam(*[, name, type, ...])

This class implements the simple astigmatic Gaussian beam described in Kochkina et al., Applied Optics, vol.

CustomFieldSource(*[, name, type, center])

Implements a source corresponding to an input dataset containing E and H fields, using the equivalence principle to define the actual injected currents.

CustomCurrentSource(*[, name, type, center, ...])

Implements a source corresponding to an input dataset containing E and H fields.

TFSF(*[, name, type, center, angle_theta, ...])

Total-field scattered-field (TFSF) source that can inject a plane wave in a finite region.

Source Time Dependence#

GaussianPulse(*[, amplitude, phase, type, ...])

Source time dependence that describes a Gaussian pulse.

ContinuousWave(*[, amplitude, phase, type, ...])

Source time dependence that ramps up to continuous oscillation and holds until end of simulation.

CustomSourceTime(*[, amplitude, phase, ...])

Custom source time dependence consisting of a real or complex envelope modulated at a central frequency, as shown below.

Monitors#

Monitor Types#

FieldMonitor(*, type, center, float, ...[, ndim])

Monitor that records electromagnetic fields in the frequency domain.

FieldTimeMonitor(*[, type, center, ...])

Monitor that records electromagnetic fields in the time domain.

FluxMonitor(*, type, center, float, ...[, ndim])

Monitor that records power flux in the frequency domain.

FluxTimeMonitor(*[, type, center, ...])

Monitor that records power flux in the time domain.

ModeMonitor(*, type, center, float, ...[, ndim])

Monitor that records amplitudes from modal decomposition of fields on plane.

ModeSolverMonitor(*, type, center, float, ...)

Monitor that stores the mode field profiles returned by the mode solver in the monitor plane.

PermittivityMonitor(*, type, center, float, ...)

Monitor that records the diagonal components of the complex-valued relative permittivity tensor in the frequency domain.

FieldProjectionCartesianMonitor(*, type, ...)

Monitor that samples electromagnetic near fields in the frequency domain and projects them on a Cartesian observation plane.

FieldProjectionAngleMonitor(*, type, center, ...)

Monitor that samples electromagnetic near fields in the frequency domain and projects them at given observation angles.

FieldProjectionKSpaceMonitor(*, type, ...[, ...])

Monitor that samples electromagnetic near fields in the frequency domain and projects them on an observation plane defined in k-space.

DiffractionMonitor(*, type, center, float, ...)

Monitor that uses a 2D Fourier transform to compute the diffraction amplitudes and efficiency for allowed diffraction orders.

Apodization Specification#

ApodizationSpec(*[, start, end, width, type])

Stores specifications for the apodizaton of frequency-domain monitors.

Mode Specifications#

ModeSpec(*[, num_modes, target_neff, ...])

Stores specifications for the mode solver to find an electromagntic mode.

Discretization#

GridSpec(*[, grid_x, grid_y, grid_z, ...])

Collective grid specification for all three dimensions.

AutoGrid(*[, type, min_steps_per_wvl, ...])

Specification for non-uniform grid along a given dimension.

UniformGrid(*[, type])

Uniform 1D grid.

CustomGrid(*[, type, custom_offset])

Custom 1D grid supplied as a list of grid cell sizes centered on the simulation center.

Coords(*, x[, ndim, ndim, ndim])

Holds data about a set of x,y,z positions on a grid.

FieldGrid(*, x, y, z[, type])

Holds the grid data for a single field.

YeeGrid(*, E, H[, type])

Holds the yee grid coordinates for each of the E and H positions.

Grid(*, boundaries[, type])

Contains all information about the spatial positions of the FDTD grid.

Field Projector#

FieldProjectionSurface(*, monitor, normal_dir)

Data structure to store surface monitors where near fields are recorded for field projections.

FieldProjector(*, sim_data, surfaces[, ...])

Projection of near fields to points on a given observation grid.

Output Data#

All Data for a Simulation#

SimulationData(*, simulation, data[, log, ...])

Stores data from a collection of Monitor objects in a Simulation.

Collections of Data from single monitor#

FieldData(*[, type, Ex, Ey, Ez, Hx, Hy, Hz, ...])

Data associated with a FieldMonitor: scalar components of E and H fields.

FieldTimeData(*[, type, Ex, Ey, Ez, Hx, Hy, ...])

Data associated with a FieldTimeMonitor: scalar components of E and H fields.

ModeSolverData(*[, type, symmetry, ...])

Data associated with a ModeSolverMonitor: scalar components of E and H fields.

PermittivityData(*[, type, symmetry, ...])

Data for a PermittivityMonitor: diagonal components of the permittivity tensor.

FluxData(*[, type])

Data associated with a FluxMonitor: flux data in the frequency-domain.

FluxTimeData(*[, type])

Data associated with a FluxTimeMonitor: flux data in the time-domain.

ModeData(*[, type, n_group, dispersion_raw])

Data associated with a ModeMonitor: modal amplitudes and propagation indices.

FieldProjectionAngleData(*[, type, medium])

Data associated with a FieldProjectionAngleMonitor: components of projected fields.

FieldProjectionCartesianData(*[, type, medium])

Data associated with a FieldProjectionCartesianMonitor: components of projected fields.

FieldProjectionKSpaceData(*[, type, medium])

Data associated with a FieldProjectionKSpaceMonitor: components of projected fields.

DiffractionData(*[, type, medium])

Data for a DiffractionMonitor: complex components of diffracted far fields.

Individual Datasets#

SpatialDataArray(data, coords, ...)

Spatial distribution.

PermittivityDataset(*[, type])

Dataset storing the diagonal components of the permittivity tensor.

ScalarFieldDataArray(data, coords, ...)

Spatial distribution in the frequency-domain.

ScalarModeFieldDataArray(data, coords, ...)

Spatial distribution of a mode in frequency-domain as a function of mode index.

ScalarFieldTimeDataArray(data, coords, ...)

Spatial distribution in the time-domain.

ModeAmpsDataArray(data, coords, ...)

Forward and backward propagating complex-valued mode amplitudes.

ModeIndexDataArray(data, coords, ...)

Complex-valued effective propagation index of a mode.

FluxDataArray(data, coords, ...)

Flux through a surface in the frequency-domain.

FluxTimeDataArray(data, coords, ...)

Flux through a surface in the time-domain.

FieldProjectionAngleDataArray(data, coords, ...)

Far fields in frequency domain as a function of angles theta and phi.

FieldProjectionCartesianDataArray(data, ...)

Far fields in frequency domain as a function of local x and y coordinates.

FieldProjectionKSpaceDataArray(data, coords, ...)

Far fields in frequency domain as a function of normalized kx and ky vectors on the observation plane.

DiffractionDataArray(data, coords, ...)

Diffraction power amplitudes as a function of diffraction orders and frequency.

Scene#

Scene#

Scene(*[, medium, structures, type])

Contains generic information about the geometry and medium properties common to all types of simulations.

Heat Solver#

Heat Simulation#

HeatSimulation(*[, type, center, medium, ...])

Contains all information about heat simulation.

Material Thermal Specification#

FluidSpec(*[, type])

Fluid medium.

SolidSpec(*[, type])

Solid medium.

Boundary Conditions Specification#

HeatBoundarySpec(*, placement, condition[, type])

Heat boundary conditions specification.

Boundary Conditions Types#

TemperatureBC(*[, type])

Constant temperature thermal boundary conditions.

ConvectionBC(*[, type])

Convective thermal boundary conditions.

HeatFluxBC(*[, type])

Constant flux thermal boundary conditions.

Boundary Conditions Placement#

StructureStructureInterface(*[, type])

Placement of boundary conditions between two structures.

StructureBoundary(*[, type])

Placement of boundary conditions on the structure's boundary.

MediumMediumInterface(*[, type])

Placement of boundary conditions between two mediums.

StructureSimulationBoundary(*[, type, surfaces])

Placement of boundary conditions on the simulation box boundary covered by the structure.

SimulationBoundary(*[, type, surfaces])

Placement of boundary conditions on the simulation box boundary.

Sources#

UniformHeatSource(*[, name, type])

Volumetric heat source.

Grid Specification#

UniformUnstructuredGrid(*, dl[, ...])

Uniform grid.

DistanceUnstructuredGrid(*, dl_interface, ...)

Adaptive grid based on distance to material interfaces.

Monitors#

TemperatureMonitor(*[, type, center, ...])

Temperature monitor.

Monitor Data#

TemperatureData(*[, type, symmetry, ...])

Data associated with a TemperatureMonitor: spatial temperature field.

Heat Simulation Data#

HeatSimulationData(*, simulation, data[, ...])

Stores results of a heat simulation.

Logging#

log

Custom logger to avoid the complexities of the logging module

set_logging_level(level)

Raise a warning here instead of setting the logging level.

set_logging_file(fname[, filemode, level])

Set a file to write log to, independently from the stdout and stderr output chosen using set_logging_level().

Submitting Simulations#

Through python API#

tidy3d.web.run(simulation, task_name[, ...])

Submits a simulation to the server, starts running, monitors progress, downloads, and loads results as a corresponding data object.

tidy3d.web.upload(simulation, task_name[, ...])

Upload a simulation to the server, but do not start running.

tidy3d.web.estimate_cost(task_id[, verbose])

Compute the maximum FlexCredit charge for a given task.

tidy3d.web.real_cost(task_id[, verbose])

Get the billed cost for given task after it has been run.

tidy3d.web.get_info(task_id[, verbose])

Return information about a task.

tidy3d.web.start(task_id[, solver_version, ...])

Start running the simulation associated with task.

tidy3d.web.monitor(task_id[, verbose])

Print the real time task progress until completion.

tidy3d.web.download(task_id[, path, ...])

Download results of task to file.

tidy3d.web.load(task_id[, path, ...])

Download and load simulation results into a data object.

tidy3d.web.delete(task_id)

Delete server-side data associated with task.

tidy3d.web.download_log(task_id[, path, ...])

Download the tidy3d log file associated with a task.

tidy3d.web.download_json(task_id[, path, ...])

Download the .json file associated with the Simulation of a given task.

tidy3d.web.load_simulation(task_id[, path, ...])

Download the .json file of a task and load the associated simulation.

tidy3d.web.run_async(simulations[, ...])

Submits a set of Union[Simulation, HeatSimulation] objects to server, starts running, monitors progress, downloads, and loads results as a BatchData object.

Convenience for Single and Batch#

tidy3d.web.Job(*[, type, folder_name, ...])

Interface for managing the task runs on the server.

tidy3d.web.Batch(*[, type, folder_name, ...])

Interface for submitting multiple simulations to the sever.

tidy3d.web.BatchData(*, task_paths, task_ids)

Holds a collection of data objects returned by Batch.

Information Containers#

tidy3d.web.core.task_info.TaskInfo(*, taskId)

General information about task.

tidy3d.web.core.task_info.TaskStatus(value)

The statuses that the task can be in.

Plugins#

Mode Solver#

tidy3d.plugins.mode.ModeSolver(*, ...[, ndim])

Interface for solving electromagnetic eigenmodes in a 2D plane with translational invariance in the third dimension.

tidy3d.plugins.mode.ModeSolverData(*[, ...])

Data associated with a ModeSolverMonitor: scalar components of E and H fields.

Dispersive Model Fitting#

tidy3d.plugins.dispersion.FastDispersionFitter(*, ...)

Tool for fitting refractive index data to get a dispersive medium described by PoleResidue model.

tidy3d.plugins.dispersion.AdvancedFastFitterParam(*)

Advanced fast fitter parameters.

tidy3d.plugins.dispersion.DispersionFitter(*, ...)

Tool for fitting refractive index data to get a dispersive medium described by PoleResidue model.

tidy3d.plugins.dispersion.AdvancedFitterParam(*)

Advanced fitter parameters

tidy3d.plugins.dispersion.web.run(fitter[, ...])

Execute the data fit using the stable fitter in the server.

tidy3d.plugins.dispersion.StableDispersionFitter(*, ...)

Deprecated.

Self-intersecting Polyslab#

tidy3d.plugins.polyslab.ComplexPolySlab(*, ...)

Interface for dividing a complex polyslab where self-intersecting polygon can occur during extrusion.

Scattering Matrix Calculator#

tidy3d.plugins.smatrix.ComponentModeler(*, ...)

Tool for modeling devices and computing scattering matrix elements.

tidy3d.plugins.smatrix.Port(*[, type, ...])

Specifies a port in the scattering matrix.

tidy3d.plugins.smatrix.SMatrixDataArray(...)

Scattering matrix elements.

Resonance Finder#

tidy3d.plugins.resonance.ResonanceFinder(*, ...)

Tool that extracts resonance information from a time series of the form shown below.

Adjoint#

tidy3d.plugins.adjoint.web.run

Submits a JaxSimulation to server, starts running, monitors progress, downloads, and loads results as a JaxSimulationData object.

tidy3d.plugins.adjoint.web.run_async

Submits a set of JaxSimulation objects to server, starts running, monitors progress, downloads, and loads results as a tuple of JaxSimulationData objects.

tidy3d.plugins.adjoint.JaxBox(*[, type])

A Box registered with jax.

tidy3d.plugins.adjoint.JaxPolySlab(*[, ...])

A PolySlab registered with jax.

tidy3d.plugins.adjoint.JaxMedium(*[, type, ...])

A Medium registered with jax.

tidy3d.plugins.adjoint.JaxAnisotropicMedium(*)

A Medium registered with jax.

tidy3d.plugins.adjoint.JaxCustomMedium(*[, ...])

A CustomMedium registered with jax.

tidy3d.plugins.adjoint.JaxStructure(*[, ...])

A Structure registered with jax.

tidy3d.plugins.adjoint.JaxSimulation(*[, ...])

A Simulation registered with jax.

tidy3d.plugins.adjoint.JaxSimulationData(*)

A SimulationData registered with jax.

tidy3d.plugins.adjoint.JaxModeData(*[, ...])

A ModeData registered with jax.

tidy3d.plugins.adjoint.JaxPermittivityDataset(*)

A PermittivityDataset registered with jax.

tidy3d.plugins.adjoint.JaxDataArray(*, ...)

A DataArray-like class that only wraps xarray for jax compability.

tidy3d.plugins.adjoint.utils.filter.ConicFilter(*)

Filter that convolves an image with a conical mask, used for larger feature sizes.

tidy3d.plugins.adjoint.utils.filter.BinaryProjector(*)

Projects a grayscale image towards min and max values using a smooth tanh function.

tidy3d.plugins.adjoint.utils.penalty.RadiusPenalty(*)

Generates a penalty for radius of curvature of set of points.

Waveguide#

tidy3d.plugins.waveguide.RectangularDielectric(*, ...)

General rectangular dielectric waveguide

Constants#

Physical Constants#

tidy3d.C_0

Convert a string or number to a floating point number, if possible.

tidy3d.HBAR

Convert a string or number to a floating point number, if possible.

tidy3d.Q_e

Convert a string or number to a floating point number, if possible.

tidy3d.ETA_0

Double-precision floating-point number type, compatible with Python float and C double.

tidy3d.EPSILON_0

Convert a string or number to a floating point number, if possible.

tidy3d.MU_0

Convert a string or number to a floating point number, if possible.

Tidy3D Special Constants#

tidy3d.inf

Convert a string or number to a floating point number, if possible.

tidy3d.PEC

Perfect electrical conductor class.

Tidy3D Configuration#

tidy3d.config.Tidy3dConfig(*[, ...])

configuration of tidy3d

Default Absorber Parameters#

tidy3d.DefaultPMLParameters

Specifies full set of parameters needed for complex, frequency-shifted PML.

tidy3d.DefaultStablePMLParameters

Specifies full set of parameters needed for complex, frequency-shifted PML.

tidy3d.DefaultAbsorberParameters

Specifies parameters common to Absorbers and PMLs.

Abstract Models#

These are some classes that are used to organize the tidy3d components, but aren’t to be used directly in the code. Documented here mainly for reference.

tidy3d.components.base.Tidy3dBaseModel()

Base pydantic model that all Tidy3d components inherit from.

tidy3d.components.boundary.AbsorberSpec(*[, ...])

Specifies the generic absorber properties along a single dimension.

tidy3d.components.medium.AbstractMedium(*[, ...])

A medium within which electromagnetic waves propagate.

tidy3d.components.medium.DispersiveMedium(*)

A Medium with dispersion (propagation characteristics depend on frequency)

tidy3d.NonlinearModel(*[, type])

Abstract model for a nonlinear material response.

tidy3d.Geometry(*[, type])

Abstract base class, defines where something exists in space.

tidy3d.components.geometry.base.Planar(*[, ...])

Geometry with one axis that is slab-like with thickness height.

tidy3d.components.geometry.base.Circular(*)

Geometry with circular characteristics (specified by a radius).

tidy3d.components.source.SourceTime(*[, ...])

Base class describing the time dependence of a source.

tidy3d.components.source.Source(*[, name, ...])

Abstract base class for all sources.

tidy3d.components.source.FieldSource(*[, ...])

A Source defined by the desired E and/or H fields.

tidy3d.components.monitor.Monitor(*[, type, ...])

Abstract base class for monitors.