tidy3d.GridSpec

tidy3d.GridSpec#

class GridSpec[source]#

Bases: Tidy3dBaseModel

Collective grid specification for all three dimensions.

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

  • grid_x (Union[UniformGrid, CustomGrid, AutoGrid, CustomGridBoundaries, QuasiUniformGrid] = 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 specification along x-axis

  • grid_y (Union[UniformGrid, CustomGrid, AutoGrid, CustomGridBoundaries, QuasiUniformGrid] = 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 specification along y-axis

  • grid_z (Union[UniformGrid, CustomGrid, AutoGrid, CustomGridBoundaries, QuasiUniformGrid] = 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 specification along z-axis

  • wavelength (Optional[float] = None) – [units = um]. Free-space wavelength for automatic nonuniform grid. It can be None if there is at least one source in the simulation, in which case it is defined by the source central frequency. Note: it only takes effect when at least one of the three dimensions uses AutoGrid.

  • override_structures (Tuple[Annotated[Union[tidy3d.components.structure.Structure, tidy3d.components.structure.MeshOverrideStructure], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – A set of structures that is added on top of the simulation structures in the process of generating the grid. This can be used to refine the grid or make it coarser depending than the expected need for higher/lower resolution regions. Note: it only takes effect when at least one of the three dimensions uses AutoGrid or QuasiUniformGrid.

  • snapping_points (Tuple[tuple[Optional[float], Optional[float], Optional[float]], ...] = ()) – A set of points that enforce grid boundaries to pass through them. However, some points might be skipped if they are too close. When points are very close to override_structures, snapping_points have higher prioirty so that the structures might be skipped. Note: it only takes effect when at least one of the three dimensions uses AutoGrid or QuasiUniformGrid.

  • layer_refinement_specs (Tuple[LayerRefinementSpec, ...] = ()) – Automatic mesh refinement according to layer specifications. The material distribution is assumed to be uniform inside the layer along the layer axis. Mesh can be refined around corners on the layer cross section, and around upper and lower bounds of the layer.

Example

>>> uniform = UniformGrid(dl=0.1)
>>> custom = CustomGrid(dl=[0.2, 0.2, 0.1, 0.1, 0.1, 0.2, 0.2])
>>> auto = AutoGrid(min_steps_per_wvl=12)
>>> grid_spec = GridSpec(grid_x=uniform, grid_y=custom, grid_z=auto, wavelength=1.5)

See also

UniformGrid

Uniform 1D grid.

AutoGrid

Specification for non-uniform grid along a given dimension.

Notebooks:
Lectures:

Attributes

auto_grid_used

True if any of the three dimensions uses AutoGrid.

custom_grid_used

True if any of the three dimensions uses CustomGrid.

external_override_structures

External supplied override structure list.

layer_refinement_used

Whether layer_refiement_specs are applied.

override_structures_used

Along each axis, True if any override structure is used.

snapped_grid_used

True if any of the three dimensions uses AbstractAutoGrid that will adjust grid with snapping points and geometry boundaries.

snapping_points_used

Along each axis, True if any snapping point is used.

attrs

Methods

all_override_structures(structures, ...[, ...])

Internal and external mesh override structures sorted based on their priority.

all_snapping_points(structures, lumped_elements)

Internal and external snapping points.

auto([wavelength, min_steps_per_wvl, ...])

Use the same AutoGrid along each of the three directions.

from_grid(grid)

Import grid directly from another simulation, e.g. grid_spec = GridSpec.from_grid(sim.grid).

get_wavelength(sources)

Get wavelength for automatic mesh generation if needed.

internal_override_structures(structures, ...)

Internal mesh override structures.

internal_snapping_points(structures, ...[, ...])

Internal snapping points.

make_grid(structures, symmetry, periodic, ...)

Make the entire simulation grid based on some simulation parameters.

quasiuniform(dl[, max_scale, ...])

Use the same QuasiUniformGrid along each of the three directions.

uniform(dl)

Use the same UniformGrid along each of the three directions.

wavelength_from_sources(sources)

Define a wavelength based on supplied sources.

Inherited Common Usage

grid_x#
grid_y#
grid_z#
wavelength#
override_structures#
snapping_points#
layer_refinement_specs#
property snapped_grid_used#

True if any of the three dimensions uses AbstractAutoGrid that will adjust grid with snapping points and geometry boundaries.

property auto_grid_used#

True if any of the three dimensions uses AutoGrid.

property custom_grid_used#

True if any of the three dimensions uses CustomGrid.

static wavelength_from_sources(sources)[source]#

Define a wavelength based on supplied sources. Called if auto mesh is used and self.wavelength is None.

property layer_refinement_used#

Whether layer_refiement_specs are applied.

property snapping_points_used#

Along each axis, True if any snapping point is used. However, it is still False if all snapping points take value None along the axis.

property override_structures_used#

Along each axis, True if any override structure is used. However, it is still False if only MeshOverrideStructure is supplied, and their dl[axis] all take the None value.

internal_snapping_points(structures, lumped_elements, cached_corners_and_convexity=None)[source]#

Internal snapping points. So far, internal snapping points are generated by layer_refinement_specs and lumped element.

Parameters:

  • structures (List[Structure]) – List of physical structures.

  • lumped_elements (List[LumpedElementType]) – List of lumped elements.

  • cached_corners_and_convexity (Optional[list[CachedCornersAndConvexity]]) – Cached corners and convexity data.

Returns:

List of snapping points coordinates.

Return type:

List[CoordinateOptional]

all_snapping_points(structures, lumped_elements, internal_snapping_points=None)[source]#

Internal and external snapping points. External snapping points take higher priority. So far, internal snapping points are generated by layer_refinement_specs.

Parameters:

  • structures (List[Structure]) – List of physical structures.

  • lumped_elements (List[LumpedElementType]) – List of lumped elements.

  • internal_snapping_points (List[CoordinateOptional]) – If None, recomputes internal snapping points.

Returns:

List of snapping points coordinates.

Return type:

List[CoordinateOptional]

property external_override_structures#

External supplied override structure list.

internal_override_structures(structures, wavelength, sim_size, lumped_elements, cached_corners_and_convexity=None)[source]#

Internal mesh override structures. So far, internal override structures are generated by layer_refinement_specs and lumped element.

Parameters:

  • structures (List[Structure]) – List of structures, with the simulation structure being the first item.

  • wavelength (pd.PositiveFloat) – Wavelength to use for minimal step size in vaccum.

  • sim_size (Tuple[float, 3]) – Simulation domain size.

  • lumped_elements (List[LumpedElementType]) – List of lumped elements.

  • cached_corners_and_convexity (Optional[list[CachedCornersAndConvexity]]) – Cached corners and convexity data.

Returns:

List of override structures.

Return type:

List[StructureType]

all_override_structures(structures, wavelength, sim_size, lumped_elements, structure_priority_mode='equal', internal_override_structures=None)[source]#

Internal and external mesh override structures sorted based on their priority. By default, the priority of internal override structures is -1, and 0 for external ones.

Parameters:

  • structures (List[Structure]) – List of structures, with the simulation structure being the first item.

  • wavelength (pd.PositiveFloat) – Wavelength to use for minimal step size in vaccum.

  • sim_size (Tuple[float, 3]) – Simulation domain size.

  • lumped_elements (List[LumpedElementType]) – List of lumped elements.

  • structure_priority_mode (PriorityMode) – Structure priority setting.

  • internal_override_structures (List[MeshOverrideStructure]) – If None, recomputes internal override structures.

Returns:

List of sorted override structures.

Return type:

List[StructureType]

get_wavelength(sources)[source]#

Get wavelength for automatic mesh generation if needed.

make_grid(structures, symmetry, periodic, sources, num_pml_layers, lumped_elements=(), internal_override_structures=None, internal_snapping_points=None, boundary_types=[[None, None], [None, None], [None, None]], structure_priority_mode='equal')[source]#

Make the entire simulation grid based on some simulation parameters.

Parameters:

  • structures (List[Structure]) – List of structures present in the simulation. The first structure must be the simulation geometry with the simulation background medium.

  • symmetry (Tuple[Symmetry, Symmetry, Symmetry]) – Reflection symmetry across a plane bisecting the simulation domain normal to each of the three axes.

  • periodic (Tuple[bool, bool, bool]) – Apply periodic boundary condition or not along each of the dimensions. Only relevant for autogrids.

  • sources (List[SourceType]) – List of sources.

  • num_pml_layers (List[Tuple[float, float]]) – List containing the number of absorber layers in - and + boundaries.

  • lumped_elements (List[LumpedElementType]) – List of lumped elements.

  • internal_override_structures (List[MeshOverrideStructure]) – If None, recomputes internal override structures.

  • internal_snapping_points (List[CoordinateOptional]) – If None, recomputes internal snapping points.

  • boundary_types (Tuple[Tuple[str, str], Tuple[str, str], Tuple[str, str]] = [[None, None], [None, None], [None, None]]) – Type of boundary conditions along each dimension: “pec/pmc”, “periodic”, or None for any other. This is relevant only for gap meshing.

  • structure_priority_mode (PriorityMode) – Structure priority setting.

Returns:

Entire simulation grid.

Return type:

Grid

classmethod from_grid(grid)[source]#

Import grid directly from another simulation, e.g. grid_spec = GridSpec.from_grid(sim.grid).

classmethod auto(wavelength=None, min_steps_per_wvl=10.0, max_scale=1.4, override_structures=(), snapping_points=(), layer_refinement_specs=(), dl_min=0.0, min_steps_per_sim_size=10.0, mesher=<object object>)[source]#

Use the same AutoGrid along each of the three directions.

Parameters:

  • wavelength (pd.PositiveFloat, optional) – Free-space wavelength for automatic nonuniform grid. It can be ‘None’ if there is at least one source in the simulation, in which case it is defined by the source central frequency.

  • min_steps_per_wvl (pd.PositiveFloat, optional) – Minimal number of steps per wavelength in each medium.

  • max_scale (pd.PositiveFloat, optional) – Sets the maximum ratio between any two consecutive grid steps.

  • override_structures (List[StructureType]) – A list of structures that is added on top of the simulation structures in the process of generating the grid. This can be used to refine the grid or make it coarser depending than the expected need for higher/lower resolution regions.

  • snapping_points (Tuple[CoordinateOptional, ...]) – A set of points that enforce grid boundaries to pass through them.

  • layer_refinement_specs (List[LayerRefinementSpec]) – Mesh refinement according to layer specifications.

  • dl_min (pd.NonNegativeFloat) – Lower bound of grid size.

  • min_steps_per_sim_size (pd.PositiveFloat, optional) – Minimal number of steps per longest edge length of simulation domain.

  • mesher (MesherType = GradedMesher()) – The type of mesher to use to generate the grid automatically.

Returns:

GridSpec with the same automatic nonuniform grid settings in each direction.

Return type:

GridSpec

classmethod uniform(dl)[source]#

Use the same UniformGrid along each of the three directions.

Parameters:

dl (float) – Grid size for uniform grid generation.

Returns:

GridSpec with the same uniform grid size in each direction.

Return type:

GridSpec

classmethod quasiuniform(dl, max_scale=1.4, override_structures=(), snapping_points=(), mesher=<object object>)[source]#

Use the same QuasiUniformGrid along each of the three directions.

Parameters:

  • dl (float) – Grid size for quasi-uniform grid generation.

  • max_scale (pd.PositiveFloat, optional) – Sets the maximum ratio between any two consecutive grid steps.

  • override_structures (List[StructureType]) – A list of structures that is added on top of the simulation structures in the process of generating the grid. This can be used to snap grid points to the bounding box boundary.

  • snapping_points (Tuple[CoordinateOptional, ...]) – A set of points that enforce grid boundaries to pass through them.

  • mesher (MesherType = GradedMesher()) – The type of mesher to use to generate the grid automatically.

Returns:

GridSpec with the same uniform grid size in each direction.

Return type:

GridSpec

__hash__()#

Hash method.