tidy3d.components.simulation.AbstractYeeGridSimulation

tidy3d.components.simulation.AbstractYeeGridSimulation#

class AbstractYeeGridSimulation[source]#

Bases: AbstractSimulation, ABC

Abstract class for a simulation involving electromagnetic fields defined on a Yee grid.

Parameters:

  • attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D` will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().

  • center (Union[tuple[Union[float, autograd.tracer.Box], Union[float, autograd.tracer.Box], Union[float, autograd.tracer.Box]], Box] = (0.0, 0.0, 0.0)) – [units = um]. Center of object in x, y, and z.

  • size (Union[tuple[Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box], Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box], Union[pydantic.v1.types.NonNegativeFloat, autograd.tracer.Box]], Box]) – [units = um]. Size in x, y, and z directions.

  • medium (Union[Medium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue] = Medium(attrs={}, name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, heat_spec=None, type='Medium', permittivity=1.0, conductivity=0.0)) – Background medium of simulation, defaults to vacuum if not specified.

  • structures (Tuple[Structure, ...] = ()) – Tuple of structures present in simulation. Note: Structures defined later in this list override the simulation material properties in regions of spatial overlap.

  • symmetry (Tuple[Literal[0, -1, 1], Literal[0, -1, 1], Literal[0, -1, 1]] = (0, 0, 0)) – Tuple of integers defining reflection symmetry across a plane bisecting the simulation domain normal to the x-, y-, and z-axis at the simulation center of each axis, respectively.

  • sources (Tuple[NoneType, ...] = ()) – Sources in the simulation.

  • boundary_spec (Optional[NoneType] = None) – Specification of boundary conditions.

  • monitors (Tuple[NoneType, ...] = ()) – Monitors in the simulation.

  • grid_spec (GridSpec = GridSpec(attrs={}, grid_x=AutoGrid(attrs={},, type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(attrs={},, type='GradedMesher')), grid_y=AutoGrid(attrs={},, type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(attrs={},, type='GradedMesher')), grid_z=AutoGrid(attrs={},, type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(attrs={},, type='GradedMesher')), wavelength=None, override_structures=(), snapping_points=(), type='GridSpec')) – Specifications for the simulation grid along each of the three directions.

  • version (str = 2.7.7) – String specifying the front end version number.

  • lumped_elements (Tuple[Union[LumpedResistor, CoaxialLumpedResistor], ...] = ()) – Tuple of lumped elements in the simulation. Note: only tidy3d.LumpedResistor is supported currently.

  • subpixel (Union[bool, SubpixelSpec] = SubpixelSpec(attrs={}, dielectric=PolarizedAveraging(attrs={},, type='PolarizedAveraging'), metal=Staircasing(attrs={},, type='Staircasing'), pec=PECConformal(attrs={},, type='PECConformal',, timestep_reduction=0.3), type='SubpixelSpec')) – Apply subpixel averaging methods of the permittivity on structure interfaces to result in much higher accuracy for a given grid size. Supply a SubpixelSpec to this field to select subpixel averaging methods separately on dielectric, metal, and PEC material interfaces. Alternatively, user may supply a boolean value: True to apply the default subpixel averaging methods corresponding to SubpixelSpec() , or False to apply staircasing.

  • simulation_type (Optional[Literal['autograd_fwd', 'autograd_bwd', 'tidy3d', None]] = tidy3d) – Tag used internally to distinguish types of simulations for autograd gradient processing.

  • post_norm (Union[float, FreqDataArray] = 1.0) – Factor to multiply the fields by after running, given the adjoint source pipeline used. Note: this is used internally only.

Attributes

bounds_pml

Simulation bounds including the PML regions.

grid

FDTD grid spatial locations and information.

num_cells

Number of cells in the simulation.

num_pml_layers

Number of absorbing layers in all three axes and directions (-, +).

pml_thicknesses

Thicknesses (um) of absorbers in all three axes and directions (-, +)

simulation_bounds

Simulation bounds including the PML regions.

volumetric_structures

Generate a tuple of structures wherein any 2D materials are converted to 3D volumetric equivalents.

attrs

Methods

discretize(box[, extend])

Grid containing only cells that intersect with a Box.

discretize_monitor(monitor)

Grid on which monitor data corresponding to a given monitor will be computed.

eps_bounds([freq])

Compute range of (real) permittivity present in the simulation at frequency "freq".

epsilon(box[, coord_key, freq])

Get array of permittivity at volume specified by box and freq.

epsilon_on_grid(grid[, coord_key, freq])

Get array of permittivity at a given freq on a given grid.

plot([x, y, z, ax, source_alpha, ...])

Plot each of simulation's components on a plane defined by one nonzero x,y,z coordinate.

plot_boundaries([x, y, z, ax])

Plot the simulation boundary conditions as lines on a plane

plot_eps([x, y, z, freq, alpha, ...])

Plot each of simulation's components on a plane defined by one nonzero x,y,z coordinate.

plot_grid([x, y, z, ax, hlim, vlim])

Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.

plot_lumped_elements([x, y, z, hlim, vlim, ...])

Plot each of simulation's lumped elements on a plane defined by one nonzero x,y,z coordinate.

plot_pml([x, y, z, hlim, vlim, ax])

Plot each of simulation's absorbing boundaries on a plane defined by one nonzero x,y,z coordinate.

plot_structures_eps([x, y, z, freq, alpha, ...])

Plot each of simulation's structures on a plane defined by one nonzero x,y,z coordinate.

subsection(region[, boundary_spec, ...])

Generate a simulation instance containing only the region.

suggest_mesh_overrides(**kwargs)

Generate a :class:.`MeshOverrideStructure` List which is automatically generated from structures in the simulation.

Inherited Common Usage

lumped_elements#

Tuple of lumped elements in the simulation.

grid_spec#

Specifications for the simulation grid along each of the three directions.

Example

Simple application reference:

Simulation(
   ...
    grid_spec=GridSpec(
       grid_x = AutoGrid(min_steps_per_wvl = 20),
       grid_y = AutoGrid(min_steps_per_wvl = 20),
       grid_z = AutoGrid(min_steps_per_wvl = 20)
   ),
   ...
)

See also

GridSpec

Collective grid specification for all three dimensions.

UniformGrid

Uniform 1D grid.

AutoGrid

Specification for non-uniform grid along a given dimension.

Notebooks:
subpixel#
simulation_type#
post_norm#

Supply SubpixelSpec to select subpixel averaging methods separately for dielectric, metal, and PEC material interfaces. Alternatively, supply True to use default subpixel averaging methods, or False to staircase all structure interfaces.

1D Illustration

For example, in the image below, two silicon slabs with thicknesses 150nm and 175nm centered in a grid with spatial discretization \(\Delta z = 25\text{nm}\) compute the effective permittivity of each grid point as the average permittivity between the grid points. A simplified equation based on the ratio \(\eta\) between the permittivity of the two materials at the interface in this case:

\[\epsilon_{eff} = \eta \epsilon_{si} + (1 - \eta) \epsilon_{air}\]
../../_images/subpixel_permittivity_1d.png

However, in this 1D case, this averaging is accurate because the dominant electric field is parallel to the dielectric grid points.

You can learn more about the subpixel averaging derivation from Maxwell’s equations in 1D in this lecture: Introduction to subpixel averaging.

2D & 3D Usage Caveats

  • In 2D, the subpixel averaging implementation depends on the polarization (\(s\) or \(p\)) of the incident electric field on the interface.

  • In 3D, the subpixel averaging is implemented with tensorial averaging due to arbitrary surface and field spatial orientations.

See also

Lectures:
plot(x=None, y=None, z=None, ax=None, source_alpha=None, monitor_alpha=None, lumped_element_alpha=None, hlim=None, vlim=None, **patch_kwargs)[source]#

Plot each of simulation’s components on a plane defined by one nonzero x,y,z coordinate.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • source_alpha (float = None) – Opacity of the sources. If None, uses Tidy3d default.

  • monitor_alpha (float = None) – Opacity of the monitors. If None, uses Tidy3d default.

  • lumped_element_alpha (float = None) – Opacity of the lumped elements. If None, uses Tidy3d default.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

See also

Notebooks
plot_eps(x=None, y=None, z=None, freq=None, alpha=None, source_alpha=None, monitor_alpha=None, lumped_element_alpha=None, hlim=None, vlim=None, ax=None)[source]#

Plot each of simulation’s components on a plane defined by one nonzero x,y,z coordinate. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • freq (float = None) – Frequency to evaluate the relative permittivity of all mediums. If not specified, evaluates at infinite frequency.

  • alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.

  • source_alpha (float = None) – Opacity of the sources. If None, uses Tidy3d default.

  • monitor_alpha (float = None) – Opacity of the monitors. If None, uses Tidy3d default.

  • lumped_element_alpha (float = None) – Opacity of the lumped elements. If None, uses Tidy3d default.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

See also

Notebooks
plot_structures_eps(x=None, y=None, z=None, freq=None, alpha=None, cbar=True, reverse=False, ax=None, hlim=None, vlim=None)[source]#

Plot each of simulation’s structures on a plane defined by one nonzero x,y,z coordinate. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • freq (float = None) – Frequency to evaluate the relative permittivity of all mediums. If not specified, evaluates at infinite frequency.

  • reverse (bool = False) – If False, the highest permittivity is plotted in black. If True, it is plotteed in white (suitable for black backgrounds).

  • cbar (bool = True) – Whether to plot a colorbar for the relative permittivity.

  • alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_pml(x=None, y=None, z=None, hlim=None, vlim=None, ax=None)[source]#

Plot each of simulation’s absorbing boundaries on a plane defined by one nonzero x,y,z coordinate.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

property bounds_pml#

Simulation bounds including the PML regions.

property simulation_bounds#

Simulation bounds including the PML regions.

eps_bounds(freq=None)[source]#

Compute range of (real) permittivity present in the simulation at frequency “freq”.

property pml_thicknesses#

Thicknesses (um) of absorbers in all three axes and directions (-, +)

Returns:

List containing the absorber thickness (micron) in - and + boundaries.

Return type:

List[Tuple[float, float]]

plot_lumped_elements(x=None, y=None, z=None, hlim=None, vlim=None, alpha=None, ax=None)[source]#

Plot each of simulation’s lumped elements on a plane defined by one nonzero x,y,z coordinate.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

  • alpha (float = None) – Opacity of the lumped element, If None uses Tidy3d default.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_grid(x=None, y=None, z=None, ax=None, hlim=None, vlim=None, **kwargs)[source]#

Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.

  • vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

  • **kwargs – Optional keyword arguments passed to the matplotlib LineCollection. For details on accepted values, refer to Matplotlib’s documentation.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_boundaries(x=None, y=None, z=None, ax=None, **kwargs)[source]#
Plot the simulation boundary conditions as lines on a plane

defined by one nonzero x,y,z coordinate.

Parameters:

  • x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.

  • y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.

  • z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.

  • ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

  • **kwargs –

    Optional keyword arguments passed to the matplotlib LineCollection. For details on accepted values, refer to Matplotlib’s documentation.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

property grid#

FDTD grid spatial locations and information.

Returns:

Grid storing the spatial locations relevant to the simulation.

Return type:

Grid

property num_cells#

Number of cells in the simulation.

Returns:

Number of yee cells in the simulation.

Return type:

int

property num_pml_layers#

Number of absorbing layers in all three axes and directions (-, +).

Returns:

List containing the number of absorber layers in - and + boundaries.

Return type:

List[Tuple[float, float]]

discretize_monitor(monitor)[source]#

Grid on which monitor data corresponding to a given monitor will be computed.

discretize(box, extend=False)[source]#

Grid containing only cells that intersect with a Box.

Parameters:

  • box (Box) – Rectangular geometry within simulation to discretize.

  • extend (bool = False) – If True, ensure that the returned indexes extend sufficiently in every direction to be able to interpolate any field component at any point within the box, for field components sampled on the Yee grid.

Returns:

The FDTD subgrid containing simulation points that intersect with box.

Return type:

Grid

epsilon(box, coord_key='centers', freq=None)[source]#

Get array of permittivity at volume specified by box and freq.

Parameters:

  • box (Box) – Rectangular geometry specifying where to measure the permittivity.

  • coord_key (str = 'centers') – Specifies at what part of the grid to return the permittivity at. Accepted values are {'centers', 'boundaries', 'Ex', 'Ey', 'Ez', 'Exy', 'Exz', 'Eyx', 'Eyz', 'Ezx', Ezy'}. The field values (eg. 'Ex') correspond to the corresponding field locations on the yee lattice. If field values are selected, the corresponding diagonal (eg. eps_xx in case of 'Ex') or off-diagonal (eg. eps_xy in case of 'Exy') epsilon component from the epsilon tensor is returned. Otherwise, the average of the main values is returned.

  • freq (float = None) – The frequency to evaluate the mediums at. If not specified, evaluates at infinite frequency.

Returns:

Datastructure containing the relative permittivity values and location coordinates. For details on xarray DataArray objects, refer to xarray’s Documentation.

Return type:

xarray.DataArray

See also

Notebooks
epsilon_on_grid(grid, coord_key='centers', freq=None)[source]#

Get array of permittivity at a given freq on a given grid.

Parameters:

  • grid (Grid) – Grid specifying where to measure the permittivity.

  • coord_key (str = 'centers') – Specifies at what part of the grid to return the permittivity at. Accepted values are {'centers', 'boundaries', 'Ex', 'Ey', 'Ez', 'Exy', 'Exz', 'Eyx', 'Eyz', 'Ezx', Ezy'}. The field values (eg. 'Ex') correspond to the corresponding field locations on the yee lattice. If field values are selected, the corresponding diagonal (eg. eps_xx in case of 'Ex') or off-diagonal (eg. eps_xy in case of 'Exy') epsilon component from the epsilon tensor is returned. Otherwise, the average of the main values is returned.

  • freq (float = None) – The frequency to evaluate the mediums at. If not specified, evaluates at infinite frequency.

Returns:

Datastructure containing the relative permittivity values and location coordinates. For details on xarray DataArray objects, refer to xarray’s Documentation.

Return type:

xarray.DataArray

property volumetric_structures#

Generate a tuple of structures wherein any 2D materials are converted to 3D volumetric equivalents.

suggest_mesh_overrides(**kwargs)[source]#

Generate a :class:.`MeshOverrideStructure` List which is automatically generated from structures in the simulation.

subsection(region, boundary_spec=None, grid_spec=None, symmetry=None, sources=None, monitors=None, remove_outside_structures=True, remove_outside_custom_mediums=False, include_pml_cells=False, **kwargs)[source]#

Generate a simulation instance containing only the region.

Parameters:

  • region (:class:.`Box`) – New simulation domain.

  • boundary_spec (:class:.`BoundarySpec` = None) – New boundary specification. If None, then it is inherited from the original simulation.

  • grid_spec (:class:.`GridSpec` = None) – New grid specification. If None, then it is inherited from the original simulation. If identical, then the original grid is transferred directly as a :class:.`CustomGrid`. Note that in the latter case the region of the new simulation is snapped to the original grid lines.

  • symmetry (Tuple[Literal[0, -1, 1], Literal[0, -1, 1], Literal[0, -1, 1]] = None) – New simulation symmetry. If None, then it is inherited from the original simulation. Note that in this case the size and placement of new simulation domain must be commensurate with the original symmetry.

  • sources (Tuple[SourceType, ...] = None) – New list of sources. If None, then the sources intersecting the new simulation domain are inherited from the original simulation.

  • monitors (Tuple[MonitorType, ...] = None) – New list of monitors. If None, then the monitors intersecting the new simulation domain are inherited from the original simulation.

  • remove_outside_structures (bool = True) – Remove structures outside of the new simulation domain.

  • remove_outside_custom_mediums (bool = True) – Remove custom medium data outside of the new simulation domain.

  • include_pml_cells (bool = False) – Keep PML cells in simulation boundaries. Note that retained PML cells will be converted to regular cells, and the simulation domain boundary will be moved accordingly.

  • **kwargs – Other arguments passed to new simulation instance.

__hash__()#

Hash method.