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 anattr
obj.attrs['foo'] = bar
. Also note that Tidy3D` will raise aTypeError
ifattrs
contain objects that can not be serialized. One can check ifattrs
are serializable by callingobj.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.2) – 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 toSubpixelSpec()
, orFalse
to apply staircasing.simulation_type (Optional[Literal['autograd_fwd', 'autograd_bwd', None]] = None) – Tag used internally to distinguish types of simulations for
autograd
gradient processing.
Attributes
Simulation bounds including the PML regions.
FDTD grid spatial locations and information.
Number of cells in the simulation.
Number of absorbing layers in all three axes and directions (-, +).
Thicknesses (um) of absorbers in all three axes and directions (-, +)
Simulation bounds including the PML regions.
Generate a tuple of structures wherein any 2D materials are converted to 3D volumetric equivalents.
DO NOT EDIT: Modified automatically with .bump2version.cfg
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#
Supply
SubpixelSpec
to select subpixel averaging methods separately for dielectric, metal, and PEC material interfaces. Alternatively, supplyTrue
to use default subpixel averaging methods, orFalse
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}\]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
- 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
- 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
- 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. IfTrue
, 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.
- 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 thebox
, 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. Ifidentical
, 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.