fdtdx.GDSLayerObject

class fdtdx.GDSLayerObject(*, partial_real_shape=(None, None, None), partial_real_position=(None, None, None), partial_grid_shape=(None, None, None), color=Color(r=0.8470588235294118, g=0.8627450980392157, b=0.8392156862745098), name=None, max_random_real_offsets=(0, 0, 0), max_random_grid_offsets=(0, 0, 0), placement_order=0, materials=null, subpixel_smoothing=False, subpixel_full_tensor=False, polygons=null, gds_center=null, material_name=null, axis=null, thickness=null, sidewall_angle=90.0, reference_plane='bottom', fill_supersample=8)

Bases: StaticMultiMaterialObject

A simulation object built from a set of GDS polygons extruded along one axis.

Each instance represents one GDS layer (layer/datatype pair) extruded uniformly along axis. The cross-sectional shape is described by polygons, given in GDS coordinate space (metres). The mapping from GDS space to the local grid is controlled by gds_center, which gives the GDS coordinate that coincides with the x/y centre of the placed object. For example, gds_center=(0.0, 0.0) maps the GDS origin to the object’s centre, while gds_center=(500e-9, 0.0) shifts the layout 500 nm to the left.

Quick Reference

Attributes

• axis

• color

• fill_supersample

• gds_center

• grid_shape

• grid_slice

• grid_slice_tuple

• horizontal_axis

• material_name

• materials

• max_random_grid_offsets

• max_random_real_offsets

• name

• partial_grid_shape

• partial_real_position

• partial_real_shape

• placement_order

• polygons

• real_shape

• reference_plane

• sidewall_angle

• subpixel_full_tensor

• subpixel_smoothing

• thickness

• vertical_axis

Methods

• apply

• aset

• check_overlap

• extend_to

• face_to_face_negative_direction

• face_to_face_positive_direction

• get_class_fields

• get_fill_fraction_for_shape

• get_geometry_size_hint

• get_interface_normal_for_shape

• get_material_mapping

• get_public_fields

• get_voxel_mask_for_shape

• place_above

• place_at_center

• place_below

• place_on_grid

• place_relative_to

• same_position

• same_position_and_size

• same_size

• set_grid_coordinates

• size_relative_to

• validate_placement

Attributes

GDSLayerObject.axis: int

The extrusion axis (0=x, 1=y, 2=z).

GDSLayerObject.color: Color | None

the color of the material

GDSLayerObject.fill_supersample: int

Number of sub-samples per axis used to estimate the in-plane fill fraction for sub-pixel smoothing (see get_fill_fraction_for_shape()). Higher values give a more accurate fill fraction / interface normal at a quadratic cost in this (CPU-side, one-time) rasterization step.

GDSLayerObject.gds_center: tuple[float, float]

GDS coordinate (horizontal, vertical) in metres that coincides with the x/y centre of the placed object.

GDSLayerObject.grid_shape

GDSLayerObject.grid_slice

GDSLayerObject.grid_slice_tuple

GDSLayerObject.horizontal_axis

Cross-section axis that is not the extrusion axis and not the vertical axis.

GDSLayerObject.material_name: str

Key into the materials dictionary used for this object.

GDSLayerObject.materials: dict[str, Material]

the static material

GDSLayerObject.max_random_grid_offsets: tuple[int, int, int]

Maximum random offset values that can be applied to the object’s position in grid coordinates for each axis (x, y, z). Defaults to (0, 0, 0) for no random offset.

GDSLayerObject.max_random_real_offsets: tuple[float, float, float]

Maximum random offset values that can be applied to the object’s position in real coordinates for each axis (x, y, z). Defaults to (0, 0, 0) for no random offset.

GDSLayerObject.name: str

Unique identifier for the object. Automatically enforced to be unique through the UniqueName validator. The user can also set a name manually.

GDSLayerObject.partial_grid_shape: PartialGridShape3D

The object’s shape in grid coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

GDSLayerObject.partial_real_position: PartialRealShape3D

The object’s position in real-world coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

GDSLayerObject.partial_real_shape: PartialRealShape3D

The object’s shape in real-world coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

GDSLayerObject.placement_order: int

Field placeholder for autoinit.

GDSLayerObject.polygons: Sequence[np.ndarray]

Sequence of (N, 2) vertex arrays for each polygon, in GDS metres.

GDSLayerObject.real_shape

Physical side lengths covered by this object’s placed grid slice.

The value is derived from SimulationConfig.grid when available. That keeps object geometry tied to physical edge coordinates instead of a global scalar resolution. During early placement, before a concrete grid has been attached to the config, the legacy uniform-resolution fallback is still used for compatibility.

GDSLayerObject.reference_plane: Literal['bottom', 'middle', 'top']

"bottom", "middle" or "top".

Type:

Face that keeps the nominal footprint

GDSLayerObject.sidewall_angle: float

Sidewall angle in degrees between the wall and the substrate (foundry convention). 90.0 extrudes a vertical wall; other values produce a trapezoidal cross-section by eroding (angle < 90) or dilating (angle > 90) each z-slice laterally by an offset offset(z) = (z - z_ref) * tan(90deg - sidewall_angle) measured from reference_plane.

GDSLayerObject.subpixel_full_tensor: bool

Selects the smoothing tensor representation when subpixel_smoothing is on. False (default) keeps only the DIAGONAL of the Farjadpour tensor (eps_ii = eps_bar - (eps_bar - eps_h)*n_i**2), allocating a cheap 3-component array that runs on the elementwise Yee update. This is EXACT for axis-aligned interfaces (their normal lies on one axis, so the off-diagonal terms vanish) and is the recommended production path for Manhattan geometries. True allocates the full 9-component tensor (keeps the off-diagonal -(eps_bar - eps_h)*n_i*n_j terms), which is more accurate for tilted interfaces (slanted sidewalls, diagonal edges) but ~3x heavier per step and forces the anisotropic update kernel. Ignored when subpixel_smoothing is False.

GDSLayerObject.subpixel_smoothing: bool

Enable sub-pixel (sub-cell) dielectric smoothing for this object. When True the assembler replaces the binary voxel occupancy with an analytic fill-fraction and builds a smoothed, anisotropic (full 3x3 tensor) effective permittivity at interface cells following Farjadpour et al. (Meep): arithmetic mean of eps for the field components tangential to the interface and harmonic mean of eps for the component normal to it. This removes the first-order staircasing error of the Yee grid at strong dielectric jumps (2nd-order accuracy). Forces the whole simulation to allocate an anisotropic permittivity tensor (3-component diagonal by default, or a full 9-component tensor when subpixel_full_tensor is set). Requires the object to provide a fractional get_fill_fraction_for_shape (the default falls back to the binary mask, which still yields a valid but only cell-wide normal). See issue #373.

GDSLayerObject.thickness: float

Extrusion thickness in metres.

GDSLayerObject.vertical_axis

Second cross-section axis perpendicular to the extrusion axis.

Methods

GDSLayerObject.apply(key, inv_permittivities, inv_permeabilities, dispersive_c1=None, dispersive_c2=None, dispersive_c3=None, electric_conductivity=None, dispersive_c4=None)

Return type:

Self

GDSLayerObject.aset(attr_name, val, create_new_ok=False)

Sets an attribute of this class. In contrast to the classical .at[].set(), this method updates the class attribute directly and does not only operate on jax pytree leaf nodes. Instead, replaces the full attribute with the new value.

The attribute can either be the attribute name of this class, or for nested classes it can also be the attribute name of a class, which itself is an attribute of this class. The syntax for this operation could look like this: “a->b->[0]->[‘name’]”. Here, the current class has an attribute a, which has an attribute b, which is a list, which we index at index 0, which is an element of type dictionary, which we index using the dictionary key ‘name’.

Note that dictionary keys cannot contain square brackets or single quotes (even if they are escaped).

Parameters:

• attr_name (str) – Name of attribute to set

• val (Any) – Value to set the attribute to

• create_new_ok (bool, optional) – If false (default), throw an error if the attribute does not exist. If true, creates a new attribute if the attribute name does not exist yet.

Returns:

Updated instance with new attribute value

Return type:

Self

GDSLayerObject.check_overlap(other)

Return type:

bool

GDSLayerObject.extend_to(other, axis, direction, other_position=None, offset=0, grid_offset=0)

Creates a SizeExtensionConstraint that extends this object along a specified axis until it reaches another object or the simulation boundary. The extension can be in either positive or negative direction.

Parameters:

• other (str | None) – Target object to extend to, or None to extend to simulation boundary

• axis (int) – Which axis to extend along (0, 1, or 2)

• direction (Literal["+", "-"]) – Direction to extend in (‘+’ or ‘-‘)

• other_position (float | None, optional) – Relative position on target object (-1 to 1) to extend to. If None, defaults to the corresponding side (-1 for ‘+’ direction, 1 for ‘-’ direction). Defaults to None.

• offset (float, optional) – Additional offset in meters to apply after extension. Ignored when extending to simulation boundary. Defaults to zero.

• grid_offset (int, optional) – Additional offset in Yee-grid voxels to apply after extension. Ignored when extending to simulation boundary. Defaults to zero.

Returns:

Constraint defining how the object extends

Return type:

SizeExtensionConstraint

GDSLayerObject.face_to_face_negative_direction(other, axes, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object facing another object in the negative direction of specified axes. The objects will touch at their facing boundaries unless margins are specified.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to align on

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint aligning objects face-to-face in negative direction

Return type:

PositionConstraint

GDSLayerObject.face_to_face_positive_direction(other, axes, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object facing another object in the positive direction of specified axes. The objects will touch at their facing boundaries unless margins are specified.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to align on

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None

Returns:

Position constraint aligning objects face-to-face in positive direction

Return type:

PositionConstraint

GDSLayerObject.get_class_fields()

Return type:

list[TreeClassField]

GDSLayerObject.get_fill_fraction_for_shape()

Analytic per-cell fill fraction of the extruded (optionally trapezoidal) polygon, in [0, 1].

The fraction is the product of an in-plane footprint coverage and the z-extent coverage:

• f_xy — the in-plane fraction of each cell covered by the polygon footprint, estimated by super-sampling polygon_to_mask_at_points() on an N x N grid inside every cell; and

• f_z — the fraction of each z-cell overlapped by the layer’s physical z-extent [z_base, z_base + thickness] (partial coverage at the top and bottom faces).

When sidewall_angle != 90 the footprint shrinks/grows with height, so f_xy is recomputed per z-slice on the laterally offset polygon (offset(z) = (z - z_ref) * tan(90deg - angle), matching _extrude_with_sidewall()), giving a sub-cell-accurate trapezoidal profile whose interface normal (recovered from the fill gradient) tilts with the wall. For a vertical wall, or when the total lateral taper stays below half a cell (the common sub-cell case), the cheaper separable f_xy(x, y) * f_z(z) form on the nominal footprint is used — it is identical there.

Returns:

Float array of shape self.grid_shape with values in [0, 1].

Return type:

jax.Array

GDSLayerObject.get_geometry_size_hint()

Return type:

tuple[float | None, float | None, float | None]

GDSLayerObject.get_interface_normal_for_shape()

Return a per-cell unit interface normal derived from the fill-fraction gradient.

The normal is n = -grad(fill) / |grad(fill)| (the sign is irrelevant downstream because only the symmetric outer product n ⊗ n is used). The gradient is taken with the object’s physical cell pitch on each axis, so the direction is geometrically correct on anisotropic grids. Cells away from an interface (|grad(fill)| ~ 0) get a zero normal, which makes the smoothed tensor collapse back to the isotropic bulk value. Computed in NumPy at initialisation (static geometry, not a traced quantity).

Returns:

Float array of shape (3, *self.grid_shape) with the per-cell unit normal.

Return type:

jax.Array

GDSLayerObject.get_material_mapping()

Return an integer array filled with the index of material_name in the sorted material list.

Returns:

Integer array of shape self.grid_shape where every voxel has the same value — the position of material_name in the sorted material name list.

Return type:

jax.Array

GDSLayerObject.get_public_fields()

Return type:

list[TreeClassField]

GDSLayerObject.get_voxel_mask_for_shape()

Compute a 3-D boolean mask for the extruded polygon shape.

When sidewall_angle is 90 deg the polygon footprint is extruded vertically and every z-slice is identical. Otherwise each z-slice is offset laterally by (z_center - z_ref) * tan(90deg - sidewall_angle) (erosion for an angle < 90, dilation for an angle > 90), giving a trapezoidal cross-section that approximates Tidy3D.PolySlab with the equivalent angle / reference_plane. The per-slice offset is applied in physical (metre) units via a Euclidean distance transform; on a non-uniform cross-section grid it uses a constant per-axis pitch (the minimum cell width), which is an approximation.

Note

Only axis=2 (z-extrusion) is supported. GDS layouts encode x/y coordinates only, so extruding along x or y would require a z-coordinate that does not exist in the GDS file.

Returns:

Boolean array of shape self.grid_shape.

Return type:

jax.Array

Raises:

ValueError – If self.axis != 2.

GDSLayerObject.place_above(other, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object above another object along the z-axis. This is a convenience wrapper around face_to_face_positive_direction() for axis 2 (z-axis).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• margins (tuple[float, ...] | float | None, optional) – Additional vertical margins in meters between objects. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional vertical margins in Yee-grid voxels between objects. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing this object above the other

Return type:

PositionConstraint

GDSLayerObject.place_at_center(other, axes=(0, 1, 2), own_positions=None, other_positions=None, margins=None, grid_margins=None)

Creates a PositionConstraint that centers this object relative to another object along specified axes. This is a convenience wrapper around place_relative_to() with default positions at the center (0).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to center on. Defaults to all axes (0, 1, 2).

• own_positions (tuple[float, ...] | float | None, optional) – Relative positions on this object (-1 to 1). If None, uses center (0). Defaults to None.

• other_positions (tuple[float, ...] | float | None, optional) – Relative positions on other object (-1 to 1). If None, uses center (0). Defaults to None.

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint centering objects relative to each other

Return type:

PositionConstraint

GDSLayerObject.place_below(other, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object below another object along the z-axis. This is a convenience wrapper around face_to_face_negative_direction() for axis 2 (z-axis).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• margins (tuple[float, ...] | float | None, optional) – Additional vertical margins in meters between objects. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional vertical margins in Yee-grid voxels between objects. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing this object below the other

Return type:

PositionConstraint

GDSLayerObject.place_on_grid(grid_slice_tuple, config, key)

Return type:

Self

GDSLayerObject.place_relative_to(other, axes, own_positions, other_positions, margins=None, grid_margins=None)

Creates a PositionalConstraint between two objects. The constraint is defined by anchor points on both objects, which are constrained to be at the same position. Anchors are defined in relative coordinates, i.e. a position of -1 is the left object boundary in the respective axis and a position of +1 the right boundary.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Eiter a single integer or a tuple describing the axes of the constraints

• own_positions (tuple[float, ...] | float) – The positions of the own anchor in the axes. Must have the same lengths as axes

• other_positions (tuple[float, ...] | float) – The positions of the other objects’ anchor in the axes. Must have the same lengths as axes

• margins (tuple[float, ...] | float | None, optional) – The margins between the anchors of both objects in meters. Must have the same lengths as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – The margins between the anchors of both objects in Yee-grid voxels. Must have the same lengths as axes. If none, no margin is used. Defaults to None.

Returns:

Positional constraint between this object and the other

Return type:

PositionConstraint

GDSLayerObject.same_position(other, axes=(0, 1, 2), own_positions=None, other_positions=None, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object at the same position as another object. This is a convenience wrapper around place_at_center() for more intuitive naming.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to match position on. Defaults to all axes (0, 1, 2).

• own_positions (tuple[float, ...] | float | None, optional) – Relative positions on this object (-1 to 1). If None, uses center (0). Defaults to None.

• other_positions (tuple[float, ...] | float | None, optional) – Relative positions on other object (-1 to 1). If None, uses center (0). Defaults to None.

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing objects at the same position

Return type:

PositionConstraint

GDSLayerObject.same_position_and_size(other, axes=(0, 1, 2))

Creates both position and size constraints to make this object match another object’s position and size. This is a convenience wrapper combining place_at_center() and same_size().

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to match. Defaults to all axes (0, 1, 2).

Returns:

Position and size constraints for matching objects

Return type:

tuple[PositionConstraint, SizeConstraint]

GDSLayerObject.same_size(other, axes=(0, 1, 2), offsets=None, grid_offsets=None)

Creates a SizeConstraint that makes this object the same size as another object along specified axes. This is a convenience wrapper around size_relative_to() with proportions set to 1.0.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes should have the same size. Defaults to all axes (0, 1, 2).

• offsets (tuple[float, ...] | float | None, optional) – Additional size offsets in meters to apply. Must have same length as axes. If None, no offset is used. Defaults to None.

• grid_offsets (tuple[int, ...] | int | None, optional) – Additional size offsets in Yee-grid voxels to apply. Must have same length as axes. If None, no offset is used. Defaults to None.

Returns:

Size constraint ensuring equal sizes between objects

Return type:

SizeConstraint

GDSLayerObject.set_grid_coordinates(axes, sides, coordinates)

Creates a GridCoordinateConstraint that forces specific sides of this object to align with given grid coordinates. Used for precise positioning in the discretized simulation space.

Parameters:

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to constrain

• sides (tuple[Literal["+", "-"], ...] | Literal["+", "-"]) – Either a single string or a tuple of strings (‘+’ or ‘-’) indicating which side of each axis to constrain. Must have same length as axes.

• coordinates (tuple[int, ...] | int) – Either a single integer or a tuple of integers specifying the grid coordinates to align with. Must have same length as axes.

Returns:

Constraint forcing alignment with specific grid coordinates

Return type:

GridCoordinateConstraint

GDSLayerObject.size_relative_to(other, axes, other_axes=None, proportions=None, offsets=None, grid_offsets=None)

Creates a SizeConstraint between two objects. The constraint defines the size of this object relative to another object, allowing for proportional scaling and offsets in specified axes.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes of this object to constrain.

• other_axes (tuple[int, ...] | int | None, optional) – Either a single integer or a tuple describing which axes of the other object to reference. If None, uses the same axes as specified in ‘axes’. Defaults to None.

• proportions (tuple[float, ...] | float | None, optional) – Scale factors to apply to the other object’s dimensions. Must have same length as axes. If None, uses 1.0 (same size). Defaults to None.

• offsets (tuple[float, ...] | float | None, optional) – Additional size offsets in meters to apply after scaling. Must have same length as axes. If None, no offset is used. Defaults to None.

• grid_offsets (tuple[int, ...] | int | None, optional) – Additional size offsets in Yee-grid voxels to apply after scaling. Must have same length as axes. If None, no offset is used. Defaults to None.

Returns:

Size constraint between this object and the other

Return type:

SizeConstraint

GDSLayerObject.validate_placement(objects)

Validate this object against the fully-resolved object container.

Called once by place_objects() after every object has been placed and the container built, giving cross-object checks (e.g. a source verifying the boundaries around it) a place to run. Returns a list of human-readable error messages; an empty list means the placement is valid. The default implementation performs no checks.

Parameters:

objects (ObjectContainer) – The fully-resolved container of all placed objects (exposes .volume, .boundary_objects, .sources, …).

Returns:

Error messages describing invalid placement, or [].

Return type:

list[str]

If you find any errors in the documentation, please report them in the Github Issues!