tidy3d.Scene

class Scene

Bases: Tidy3dBaseModel

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

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

• 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 scene, defaults to vacuum if not specified.

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

Example

>>> sim = Scene(
...     structures=[
...         Structure(
...             geometry=Box(size=(1, 1, 1), center=(0, 0, 0)),
...             medium=Medium(permittivity=2.0),
...         ),
...     ],
...     medium=Medium(permittivity=3.0),
... )

Attributes

background_structure	Returns structure representing the background of the Scene.
bounds	Automatically defined scene's bounds based on present structures.
box	Automatically defined scene's Box.
center	Automatically defined scene's center.
medium_map	Returns dict mapping medium to index in material.
mediums	Returns set of distinct AbstractMedium in scene.
size	Automatically defined scene's size.
attrs

Methods

eps_bounds([freq])	Compute range of (real) permittivity present in the scene at frequency "freq".
heat_conductivity_bounds()	Compute range of thermal conductivities present in the scene.
intersecting_media(test_object, structures)	From a given list of structures, returns a list of AbstractMedium associated with those structures that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.
intersecting_structures(test_object, structures)	From a given list of structures, returns a list of Structure that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.
perturbed_mediums_copy([temperature, ...])	Return a copy of the scene with heat and/or charge data applied to all mediums that have perturbation models specified.
plot([x, y, z, ax, hlim, vlim])	Plot each of scene's components on a plane defined by one nonzero x,y,z coordinate.
plot_eps([x, y, z, freq, alpha, ax, hlim, vlim])	Plot each of scene's components on a plane defined by one nonzero x,y,z coordinate.
plot_heat_conductivity([x, y, z, alpha, ...])	Plot each of scebe's components on a plane defined by one nonzero x,y,z coordinate.
plot_structures([x, y, z, ax, hlim, vlim])	Plot each of scene's structures on a plane defined by one nonzero x,y,z coordinate.
plot_structures_eps([x, y, z, freq, alpha, ...])	Plot each of scene's structures on a plane defined by one nonzero x,y,z coordinate.
plot_structures_heat_conductivity([x, y, z, ...])	Plot each of scene's structures on a plane defined by one nonzero x,y,z coordinate.

Inherited Common Usage

medium

structures

Validating setup

property bounds

Automatically defined scene’s bounds based on present structures. Infinite dimensions are ignored. If the scene contains no structures, the bounds are set to (-1, -1, -1), (1, 1, 1). Similarly, if along a given axis all structures extend infinitely, the bounds along that axis are set from -1 to 1.

Returns:

Min and max bounds packaged as (minx, miny, minz), (maxx, maxy, maxz).

Return type:

Tuple[float, float, float], Tuple[float, float, float]

property size

Automatically defined scene’s size.

Returns:

Scene’s size.

Return type:

Tuple[float, float, float]

property center

Automatically defined scene’s center.

Returns:

Scene’s center.

Return type:

Tuple[float, float, float]

property box

Automatically defined scene’s Box.

Returns:

Scene’s box.

Return type:

Box

property mediums

Returns set of distinct AbstractMedium in scene.

Returns:

Set of distinct mediums in the scene.

Return type:

List[AbstractMedium]

property medium_map

Returns dict mapping medium to index in material. medium_map[medium] returns unique global index of AbstractMedium in scene.

Returns:

Mapping between distinct mediums to index in scene.

Return type:

Dict[AbstractMedium, int]

property background_structure

Returns structure representing the background of the Scene.

static intersecting_media(test_object, structures)

From a given list of structures, returns a list of AbstractMedium associated with those structures that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.

Parameters:

• test_object (Box) – Object for which intersecting media are to be detected.

• structures (List[AbstractMedium]) – List of structures whose media will be tested.

Returns:

Set of distinct mediums that intersect with the given planar object.

Return type:

List[AbstractMedium]

static intersecting_structures(test_object, structures)

From a given list of structures, returns a list of Structure that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.

Parameters:

• test_object (Box) – Object for which intersecting media are to be detected.

• structures (List[AbstractMedium]) – List of structures whose media will be tested.

Returns:

Set of distinct structures that intersect with the given surface, or with the surfaces of the given volume.

Return type:

List[Structure]

plot(x=None, y=None, z=None, ax=None, hlim=None, vlim=None, **patch_kwargs)

Plot each of scene’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.

• 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_structures(x=None, y=None, z=None, ax=None, hlim=None, vlim=None)

Plot each of scene’s structures 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.

• 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_eps(x=None, y=None, z=None, freq=None, alpha=None, ax=None, hlim=None, vlim=None)

Plot each of scene’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.

• 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_structures_eps(x=None, y=None, z=None, freq=None, alpha=None, cbar=True, reverse=False, eps_lim=(None, None), ax=None, hlim=None, vlim=None, grid=None)

Plot each of scene’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.

• eps_lim (Tuple[float, float] = None) – Custom limits for eps coloring.

• 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

eps_bounds(freq=None)

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

Parameters:

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

Returns:

Minimal and maximal values of relative permittivity in scene.

Return type:

Tuple[float, float]

plot_heat_conductivity(x=None, y=None, z=None, alpha=None, cbar=True, ax=None, hlim=None, vlim=None)

Plot each of scebe’s components on a plane defined by one nonzero x,y,z coordinate. The thermal conductivity is plotted in grayscale based on its value.

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.

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

• 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_structures_heat_conductivity(x=None, y=None, z=None, alpha=None, cbar=True, reverse=False, ax=None, hlim=None, vlim=None)

Plot each of scene’s structures on a plane defined by one nonzero x,y,z coordinate. The thermal conductivity is plotted in grayscale based on its value.

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.

• 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

heat_conductivity_bounds()

Compute range of thermal conductivities present in the scene.

Returns:

Minimal and maximal values of thermal conductivity in scene.

Return type:

Tuple[float, float]

__hash__()

Hash method.

perturbed_mediums_copy(temperature=None, electron_density=None, hole_density=None, interp_method='linear')

Return a copy of the scene with heat and/or charge data applied to all mediums that have perturbation models specified. That is, such mediums will be replaced with spatially dependent custom mediums that reflect perturbation effects. Any of temperature, electron_density, and hole_density can be None. All provided fields must have identical coords.

Parameters:

• temperature (Union[) –

  SpatialDataArray,

  TriangularGridDataset, TetrahedralGridDataset,

  ] = None Temperature field data.

• electron_density (Union[) –

  SpatialDataArray,

  TriangularGridDataset, TetrahedralGridDataset,

  ] = None Electron density field data.

• hole_density (Union[) –

  SpatialDataArray,

  TriangularGridDataset, TetrahedralGridDataset,

  ] = None Hole density field data.

• interp_method (InterpMethod, optional) – Interpolation method to obtain heat and/or charge values that are not supplied at the Yee grids.

Returns:

Simulation after application of heat and/or charge data.

Return type:

Scene