tidy3d.ModeSimulation

tidy3d.ModeSimulation#

class ModeSimulation[source]#

Bases: AbstractYeeGridSimulation

Simulation class for solving electromagnetic eigenmodes in a 2D plane with translational invariance in the third dimension. If the field plane is specified, the domain for mode solving is the intersection between the plane and the simulation geometry. If the simulation geometry is 2D (has zero size in one dimension) and the plane is None, then the domain for mode solving is the entire 2D geometry.

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, PMCMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue, LossyMetalMedium] = Medium(attrs={}, name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, viz_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[] = ()) – Sources in the simulation. Note: sources are not supported in mode simulations.

  • boundary_spec (BoundarySpec = BoundarySpec(attrs={}, x=Boundary(attrs={},, plus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), y=Boundary(attrs={},, plus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), z=Boundary(attrs={},, plus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(attrs={},, name=None,, type='PML',, num_layers=12,, parameters=PMLParams(attrs={},, sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), type='BoundarySpec')) – Specification of boundary conditions along each dimension. If None, PML boundary conditions are applied on all sides. This behavior is for consistency with FDTD simulations; however, please note that the mode solver terminates the mode plane with PEC boundary. The ‘ModeSpec’ can be used to apply PML layers in the mode solver.

  • monitors (Tuple[Union[PermittivityMonitor, MediumMonitor], ...] = ()) – Tuple of monitors in the simulation. Note: monitor names are used to access data after simulation is run.

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

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

  • plot_length_units (Optional[Literal['nm', 'μm', 'um', 'mm', 'cm', 'm', 'mil', 'in']] = μm) – When set to a supported LengthUnit, plots will be produced with proper scaling of axes and include the desired unit specifier in labels.

  • structure_priority_mode (Literal['equal', 'conductor'] = equal) – This field only affects structures of priority=None. If equal, the priority of those structures is set to 0; if conductor, the priority of structures made of LossyMetalMedium is set to 90, PECMedium to 100, and others to 0.

  • lumped_elements (Tuple[Annotated[Union[tidy3d.components.lumped_element.LumpedResistor, tidy3d.components.lumped_element.CoaxialLumpedResistor, tidy3d.components.lumped_element.LinearLumpedElement], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – 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,, edge_singularity_correction=True), pmc=Staircasing(attrs={},, type='Staircasing'), lossy_metal=SurfaceImpedance(attrs={},, type='SurfaceImpedance',, timestep_reduction=0.0,, edge_singularity_correction=True), 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.

  • internal_absorbers (Tuple[] = ()) – Planes with the first order absorbing boundary conditions placed inside the computational domain. Note: absorbers are not supported in mode simulations.

  • mode_spec (Union[ModeSpec, MicrowaveModeSpec]) – Container with specifications about the modes to be solved for.

  • freqs (Union[tuple[float, ...], ArrayLike[dtype=float, ndim=1]]) – A list of frequencies at which to solve.

  • direction (Literal['+', '-'] = +) – Direction of waveguide mode propagation along the axis defined by its normal dimension.

  • colocate (bool = True) – Toggle whether fields should be colocated to grid cell boundaries (i.e. primal grid nodes). Default is True.

  • conjugated_dot_product (bool = True) – Use conjugated or non-conjugated dot product for mode decomposition.

  • fields (Tuple[Literal['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz'], ...] = ['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz']) – Collection of field components to store in the monitor. Note that some methods like flux, dot require all tangential field components, while others like mode_area require all E-field components.

  • plane (Union[Box, ModeSource, ModeMonitor, ModeSolverMonitor] = None) – Cross-sectional plane in which the mode will be computed. If provided, the computational domain will be the intersection between the provided plane and the simulation geometry. If None, the simulation must be 2D, and the plane will be the entire simulation geometry.

  • planes (The symmetry field can be used to enforce reflection symmetry across)

  • field (through the center of the simulation. Each component of the symmetry)

  • geometry (is only used if the center of the plane and the simulation)

  • no (coincide in that component. Symmetry normal to the mode solving domain has)

:param effect; the field filter_pol in ModeSpec can be used here instead.:

Example

>>> from tidy3d import C_0, ModeSpec, BoundarySpec, Boundary
>>> lambda0 = 1550e-9
>>> freq0 = C_0 / lambda0
>>> freqs = [freq0]
>>> sim_size = lambda0, lambda0, 0
>>> mode_spec = ModeSpec(num_modes=4)
>>> boundary_spec = BoundarySpec(
...     x=Boundary.pec(),
...     y=Boundary.pec(),
...     z=Boundary.periodic()
... )
>>> sim = ModeSimulation(
...     size=sim_size,
...     freqs=freqs,
...     mode_spec=mode_spec,
...     boundary_spec=boundary_spec
... )

See also

ModeSource:

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

Notebooks:
Lectures:

Attributes

grid

Grid spatial locations and information as defined by grid_spec.

reduced_simulation_copy

Strip objects not used by the mode solver from simulation object.

version

attrs

Methods

from_mode_solver(mode_solver[, wavelength])

Creates ModeSimulation from a ModeSolver.

from_simulation(simulation[, wavelength])

Creates ModeSimulation from a AbstractYeeGridSimulation.

is_plane(val, values)

Raise validation error if not planar.

plane_in_sim_bounds(val, values)

Check that the plane is at least partially inside the simulation bounds.

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

Plot the mode simulation.

plot_eps_mode_plane([freq, alpha, ax])

Plot the mode plane simulation's components.

plot_grid_mode_plane([ax])

Plot the mode plane cell boundaries as lines.

plot_mode_plane([ax])

Plot the mode plane simulation's components.

plot_pml_mode_plane([ax])

Plot the mode plane absorbing boundaries.

plot_structures_eps_mode_plane([freq, ...])

Plot the mode plane simulation's components.

run_local()

Run locally.

validate_pre_upload()

Validate the fully initialized simulation is ok for upload to our servers.

Inherited Common Usage

mode_spec#
freqs#
direction#
colocate#
conjugated_dot_product#
fields#
boundary_spec#
monitors#
sources#
internal_absorbers#
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:
plane#
classmethod is_plane(val, values)[source]#

Raise validation error if not planar.

classmethod plane_in_sim_bounds(val, values)[source]#

Check that the plane is at least partially inside the simulation bounds.

run_local()[source]#

Run locally.

property grid#

Grid spatial locations and information as defined by grid_spec.

Returns:

Grid storing the spatial locations relevant to the simulation.

Return type:

Grid

classmethod from_simulation(simulation, wavelength=None, **kwargs)[source]#

Creates ModeSimulation from a AbstractYeeGridSimulation.

Parameters:

  • simulation (AbstractYeeGridSimulation) – Starting simulation defining structures, grid, etc.

  • wavelength (Optional[pd.PositiveFloat]) – Wavelength used for automatic grid generation. Required if auto grid is used in grid_spec.

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

Returns:

Mode simulation reproducing the material and grid properties of the original simulation.

Return type:

ModeSimulation

property reduced_simulation_copy#

Strip objects not used by the mode solver from simulation object. This might significantly reduce upload time in the presence of custom mediums.

classmethod from_mode_solver(mode_solver, wavelength=None)[source]#

Creates ModeSimulation from a ModeSolver.

Parameters:

  • simulation (AbstractYeeGridSimulation) – Starting simulation defining structures, grid, etc.

  • wavelength (Optional[pd.PositiveFloat]) – Wavelength used for automatic grid generation. Required if auto grid is used in grid_spec.

Returns:

Mode simulation reproducing the material and grid properties of the original simulation.

Return type:

ModeSimulation

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

Plot the mode simulation. If any of x, y, or z is provided, the potentially larger FDTD simulation containing the mode plane is plotted at the desired location. Otherwise, the mode plane is plotted by default.

Parameters:

  • fill_structures (bool = True) – Whether to fill structures with color or just draw outlines.

  • 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 = 0) – Opacity of the sources. If None, uses Tidy3d default.

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

  • lumped_element_alpha (float = 0) – 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

plot_mode_plane(ax=None, **patch_kwargs)[source]#

Plot the mode plane simulation’s components.

Parameters:

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

See also

Notebooks
plot_eps_mode_plane(freq=None, alpha=None, ax=None)[source]#

Plot the mode plane simulation’s components. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters:

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

  • 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

See also

Notebooks
plot_structures_eps_mode_plane(freq=None, alpha=None, cbar=True, reverse=False, ax=None)[source]#

Plot the mode plane simulation’s components. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters:

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

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

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

  • 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

See also

Notebooks
plot_grid_mode_plane(ax=None, **kwargs)[source]#

Plot the mode plane cell boundaries as lines.

Parameters:

  • 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_pml_mode_plane(ax=None)[source]#

Plot the mode plane absorbing boundaries.

Parameters:

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

validate_pre_upload()[source]#

Validate the fully initialized simulation is ok for upload to our servers.

__hash__()#

Hash method.