tidy3d.Geometry

class Geometry

Bases: Tidy3dBaseModel, ABC

Abstract base class, defines where something exists in space.

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

Attributes

bounding_box	Returns Box representation of the bounding box of a Geometry.
bounds	Returns bounding box min and max coordinates.
plot_params	Default parameters for plotting a Geometry object.
zero_dims	A list of axes along which the Geometry is zero-sized based on its bounds.
attrs

Methods

add_ax_labels_lims(axis, ax[, buffer])	Sets the x,y labels based on axis and the extends based on self.bounds.
bounds_intersection(bounds1, bounds2)	Return the bounds that are the intersection of two bounds.
car_2_sph(x, y, z)	Convert Cartesian to spherical coordinates.
car_2_sph_field(f_x, f_y, f_z, theta, phi)	Convert vector field components in cartesian coordinates to spherical.
compute_derivatives(derivative_info)	Compute the adjoint derivatives for this object.
evaluate_inf_shape(shape)	Returns a copy of shape with inf vertices replaced by large numbers if polygon.
from_gds(gds_cell, axis, slab_bounds, gds_layer)	Import a gdstk.Cell or a gdspy.Cell and extrude it into a GeometryGroup.
from_shapely(shape, axis, slab_bounds[, ...])	Convert a shapely primitive into a geometry instance by extrusion.
inside(x, y, z)	For input arrays x, y, z of arbitrary but identical shape, return an array with the same shape which is True for every point in zip(x, y, z) that is inside the volume of the Geometry, and False otherwise.
inside_meshgrid(x, y, z)	Perform self.inside on a set of sorted 1D coordinates.
intersections_2dbox(plane)	Returns list of shapely geometries representing the intersections of the geometry with a 2D box.
intersections_plane([x, y, z])	Returns list of shapely geometries at plane specified by one non-None value of x,y,z.
intersections_tilted_plane(normal, origin, to_2D)	Return a list of shapely geometries at the plane specified by normal and origin.
intersects(other[, strict_inequality])	Returns True if two Geometry have intersecting .bounds.
intersects_axis_position(axis, position)	Whether self intersects plane specified by a given position along a normal axis.
intersects_plane([x, y, z])	Whether self intersects plane specified by one non-None value of x,y,z.
kspace_2_sph(ux, uy, axis)	Convert normalized k-space coordinates to angles.
load_gds_vertices_gdspy(gds_cell, gds_layer)	Load polygon vertices from a gdspy.Cell.
load_gds_vertices_gdstk(gds_cell, gds_layer)	Load polygon vertices from a gdstk.Cell.
make_shapely_box(minx, miny, maxx, maxy)	Make a shapely box ensuring everything untraced.
make_shapely_point(minx, miny)	Make a shapely Point ensuring everything untraced.
parse_xyz_kwargs(**xyz)	Turns x,y,z kwargs into index of the normal axis and position along that axis.
plot([x, y, z, ax])	Plot geometry cross section at single (x,y,z) coordinate.
plot_shape(shape, plot_params, ax)	Defines how a shape is plotted on a matplotlib axes.
pop_axis(coord, axis)	Separates coordinate at axis index from coordinates on the plane tangent to axis.
reflect_points(points, polar_axis, ...)	Reflect a set of points in 3D at a plane passing through the coordinate origin defined and normal to a given axis defined in polar coordinates (theta, phi) w.r.t.
rotate_points(points, axis, angle)	Rotate a set of points in 3D.
rotated(angle, axis)	Return a rotated copy of this geometry.
scaled([x, y, z])	Return a scaled copy of this geometry.
sph_2_car(r, theta, phi)	Convert spherical to Cartesian coordinates.
sph_2_car_field(f_r, f_theta, f_phi, theta, phi)	Convert vector field components in spherical coordinates to cartesian.
surface_area([bounds])	Returns object's surface area with optional bounds.
to_gds(cell[, x, y, z, gds_layer, gds_dtype])	Append a Geometry object's planar slice to a .gds cell.
to_gds_file(fname[, x, y, z, gds_layer, ...])	Export a Geometry object's planar slice to a .gds file.
to_gdspy([x, y, z, gds_layer, gds_dtype])	Convert a Geometry object's planar slice to a .gds type polygon.
to_gdstk([x, y, z, gds_layer, gds_dtype])	Convert a Geometry object's planar slice to a .gds type polygon.
translated(x, y, z)	Return a translated copy of this geometry.
unpop_axis(ax_coord, plane_coords, axis)	Combine coordinate along axis with coordinates on the plane tangent to the axis.
volume([bounds])	Returns object's volume with optional bounds.

Inherited Common Usage

property plot_params

Default parameters for plotting a Geometry object.

inside(x, y, z)

For input arrays x, y, z of arbitrary but identical shape, return an array with the same shape which is True for every point in zip(x, y, z) that is inside the volume of the Geometry, and False otherwise.

Parameters:

• x (np.ndarray[float]) – Array of point positions in x direction.

• y (np.ndarray[float]) – Array of point positions in y direction.

• z (np.ndarray[float]) – Array of point positions in z direction.

Returns:

True for every point that is inside the geometry.

Return type:

np.ndarray[bool]

static make_shapely_box(minx, miny, maxx, maxy)

Make a shapely box ensuring everything untraced.

static make_shapely_point(minx, miny)

Make a shapely Point ensuring everything untraced.

inside_meshgrid(x, y, z)

Perform self.inside on a set of sorted 1D coordinates. Applies meshgrid to the supplied coordinates before checking inside.

Parameters:

• x (np.ndarray[float]) – 1D array of point positions in x direction.

• y (np.ndarray[float]) – 1D array of point positions in y direction.

• z (np.ndarray[float]) – 1D array of point positions in z direction.

Returns:

Array with shape (x.size, y.size, z.size), which is True for every point that is inside the geometry.

Return type:

np.ndarray[bool]

abstract intersections_tilted_plane(normal, origin, to_2D)

Return a list of shapely geometries at the plane specified by normal and origin.

Parameters:

• normal (Coordinate) – Vector defining the normal direction to the plane.

• origin (Coordinate) – Vector defining the plane origin.

• to_2D (MatrixReal4x4) – Transformation matrix to apply to resulting shapes.

Returns:

List of 2D shapes that intersect plane. For more details refer to Shapely’s Documentation.

Return type:

List[shapely.geometry.base.BaseGeometry]

intersections_plane(x=None, y=None, z=None)

Returns list of shapely geometries at plane specified by one non-None value of x,y,z.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

Returns:

List of 2D shapes that intersect plane. For more details refer to Shapely’s Documentation.

Return type:

List[shapely.geometry.base.BaseGeometry]

intersections_2dbox(plane)

Returns list of shapely geometries representing the intersections of the geometry with a 2D box.

Returns:

List of 2D shapes that intersect plane. For more details refer to Shapely’s Documentation.

Return type:

List[shapely.geometry.base.BaseGeometry]

intersects(other, strict_inequality=[False, False, False])

Returns True if two Geometry have intersecting .bounds.

Parameters:

• other (Geometry) – Geometry to check intersection with.

• strict_inequality (Tuple[bool, bool, bool] = [False, False, False]) – For each dimension, defines whether to include equality in the boundaries comparison. If False, equality is included, and two geometries that only intersect at their boundaries will evaluate as True. If True, such geometries will evaluate as False.

Returns:

Whether the rectangular bounding boxes of the two geometries intersect.

Return type:

bool

intersects_plane(x=None, y=None, z=None)

Whether self intersects plane specified by one non-None value of x,y,z.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

Returns:

Whether this geometry intersects the plane.

Return type:

bool

intersects_axis_position(axis, position)

Whether self intersects plane specified by a given position along a normal axis.

Parameters:

• axis (int = None) – Axis normal to the plane.

• position (float = None) – Position of plane along the normal axis.

Returns:

Whether this geometry intersects the plane.

Return type:

bool

abstract property bounds

Returns bounding box min and max coordinates.

Returns:

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

Return type:

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

static bounds_intersection(bounds1, bounds2)

Return the bounds that are the intersection of two bounds.

property bounding_box

Returns Box representation of the bounding box of a Geometry.

Returns:

Geometric object representing bounding box.

Return type:

Box

property zero_dims

A list of axes along which the Geometry is zero-sized based on its bounds.

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

Plot geometry cross section at single (x,y,z) coordinate.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

• **patch_kwargs – Optional keyword arguments passed to the matplotlib patch plotting of structure. For details on accepted values, refer to Matplotlib’s documentation.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

plot_shape(shape, plot_params, ax)

Defines how a shape is plotted on a matplotlib axes.

add_ax_labels_lims(axis, ax, buffer=0.3)

Sets the x,y labels based on axis and the extends based on self.bounds.

Parameters:

• axis (int) – Integer index into ‘xyz’ (0,1,2).

• ax (matplotlib.axes._subplots.Axes) – Matplotlib axes to add labels and limits on.

• buffer (float = 0.3) – Amount of space to place around the limits on the + and - sides.

Returns:

The supplied or created matplotlib axes.

Return type:

matplotlib.axes._subplots.Axes

static evaluate_inf_shape(shape)

Returns a copy of shape with inf vertices replaced by large numbers if polygon.

static pop_axis(coord, axis)

Separates coordinate at axis index from coordinates on the plane tangent to axis.

Parameters:

• coord (Tuple[Any, Any, Any]) – Tuple of three values in original coordinate system.

• axis (int) – Integer index into ‘xyz’ (0,1,2).

Returns:

The input coordinates are separated into the one along the axis provided and the two on the planar coordinates, like axis_coord, (planar_coord1, planar_coord2).

Return type:

Any, Tuple[Any, Any]

static unpop_axis(ax_coord, plane_coords, axis)

Combine coordinate along axis with coordinates on the plane tangent to the axis.

Parameters:

• ax_coord (Any) – Value along axis direction.

• plane_coords (Tuple[Any, Any]) – Values along ordered planar directions.

• axis (int) – Integer index into ‘xyz’ (0,1,2).

Returns:

The three values in the xyz coordinate system.

Return type:

Tuple[Any, Any, Any]

static parse_xyz_kwargs(**xyz)

Turns x,y,z kwargs into index of the normal axis and position along that axis.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

Returns:

Index into xyz axis (0,1,2) and position along that axis.

Return type:

int, float

static rotate_points(points, axis, angle)

Rotate a set of points in 3D.

Parameters:

• points (ArrayLike[float]) – Array of shape (3, ...).

• axis (Coordinate) – Axis of rotation

• angle (float) – Angle of rotation counter-clockwise around the axis (rad).

reflect_points(points, polar_axis, angle_theta, angle_phi)

Reflect a set of points in 3D at a plane passing through the coordinate origin defined and normal to a given axis defined in polar coordinates (theta, phi) w.r.t. the polar_axis which can be 0, 1, or 2.

Parameters:

• points (ArrayLike[float]) – Array of shape (3, ...).

• polar_axis (Axis) – Cartesian axis w.r.t. which the normal axis angles are defined.

• angle_theta (float) – Polar angle w.r.t. the polar axis.

• angle_phi (float) – Azimuth angle around the polar axis.

volume(bounds=None)

Returns object’s volume with optional bounds.

Parameters:

bounds (Tuple[Tuple[float, float, float], Tuple[float, float, float]] = None) – Min and max bounds packaged as (minx, miny, minz), (maxx, maxy, maxz).

Returns:

Volume in um^3.

Return type:

float

surface_area(bounds=None)

Returns object’s surface area with optional bounds.

Parameters:

bounds (Tuple[Tuple[float, float, float], Tuple[float, float, float]] = None) – Min and max bounds packaged as (minx, miny, minz), (maxx, maxy, maxz).

Returns:

Surface area in um^2.

Return type:

float

translated(x, y, z)

Return a translated copy of this geometry.

Parameters:

• x (float) – Translation along x.

• y (float) – Translation along y.

• z (float) – Translation along z.

Returns:

Translated copy of this geometry.

Return type:

Geometry

scaled(x=1.0, y=1.0, z=1.0)

Return a scaled copy of this geometry.

Parameters:

• x (float = 1.0) – Scaling factor along x.

• y (float = 1.0) – Scaling factor along y.

• z (float = 1.0) – Scaling factor along z.

Returns:

Scaled copy of this geometry.

Return type:

Geometry

rotated(angle, axis)

Return a rotated copy of this geometry.

Parameters:

• angle (float) – Rotation angle (in radians).

• axis (Union[int, Tuple[float, float, float]]) – Axis of rotation: 0, 1, or 2 for x, y, and z, respectively, or a 3D vector.

Returns:

Rotated copy of this geometry.

Return type:

Geometry

static car_2_sph(x, y, z)

Convert Cartesian to spherical coordinates.

Parameters:

• x (float) – x coordinate relative to local_origin.

• y (float) – y coordinate relative to local_origin.

• z (float) – z coordinate relative to local_origin.

Returns:

r, theta, and phi coordinates relative to local_origin.

Return type:

Tuple[float, float, float]

static sph_2_car(r, theta, phi)

Convert spherical to Cartesian coordinates.

Parameters:

• r (float) – radius.

• theta (float) – polar angle (rad) downward from x=y=0 line.

• phi (float) – azimuthal (rad) angle from y=z=0 line.

Returns:

x, y, and z coordinates relative to local_origin.

Return type:

Tuple[float, float, float]

static sph_2_car_field(f_r, f_theta, f_phi, theta, phi)

Convert vector field components in spherical coordinates to cartesian.

Parameters:

• f_r (float) – radial component of the vector field.

• f_theta (float) – polar angle component of the vector fielf.

• f_phi (float) – azimuthal angle component of the vector field.

• theta (float) – polar angle (rad) of location of the vector field.

• phi (float) – azimuthal angle (rad) of location of the vector field.

Returns:

x, y, and z components of the vector field in cartesian coordinates.

Return type:

Tuple[float, float, float]

static car_2_sph_field(f_x, f_y, f_z, theta, phi)

Convert vector field components in cartesian coordinates to spherical.

Parameters:

• f_x (float) – x component of the vector field.

• f_y (float) – y component of the vector fielf.

• f_z (float) – z component of the vector field.

• theta (float) – polar angle (rad) of location of the vector field.

• phi (float) – azimuthal angle (rad) of location of the vector field.

Returns:

radial (s), elevation (theta), and azimuthal (phi) components of the vector field in spherical coordinates.

Return type:

Tuple[float, float, float]

static kspace_2_sph(ux, uy, axis)

Convert normalized k-space coordinates to angles.

Parameters:

• ux (float) – normalized kx coordinate.

• uy (float) – normalized ky coordinate.

• axis (int) – axis along which the observation plane is oriented.

Returns:

theta and phi coordinates relative to local_origin.

Return type:

Tuple[float, float]

static load_gds_vertices_gdstk(gds_cell, gds_layer, gds_dtype=None, gds_scale=1.0)

Load polygon vertices from a gdstk.Cell.

Parameters:

• gds_cell (gdstk.Cell) – gdstk.Cell or gdspy.Cell containing 2D geometric data.

• gds_layer (int) – Layer index in the gds_cell.

• gds_dtype (int = None) – Data-type index in the gds_cell. If None, imports all data for this layer into the returned list.

• gds_scale (float = 1.0) – Length scale used in GDS file in units of micrometer. For example, if gds file uses nanometers, set gds_scale=1e-3. Must be positive.

Returns:

List of polygon vertices

Return type:

List[ArrayFloat2D]

static load_gds_vertices_gdspy(gds_cell, gds_layer, gds_dtype=None, gds_scale=1.0)

Load polygon vertices from a gdspy.Cell.

Parameters:

• gds_cell (gdspy.Cell) – gdstk.Cell or gdspy.Cell containing 2D geometric data.

• gds_layer (int) – Layer index in the gds_cell.

• gds_dtype (int = None) – Data-type index in the gds_cell. If None, imports all data for this layer into the returned list.

• gds_scale (float = 1.0) – Length scale used in GDS file in units of micrometer. For example, if gds file uses nanometers, set gds_scale=1e-3. Must be positive.

Returns:

List of polygon vertices

Return type:

List[ArrayFloat2D]

static from_gds(gds_cell, axis, slab_bounds, gds_layer, gds_dtype=None, gds_scale=1.0, dilation=0.0, sidewall_angle=0, reference_plane='middle')

Import a gdstk.Cell or a gdspy.Cell and extrude it into a GeometryGroup.

Parameters:

• gds_cell (Union[gdstk.Cell, gdspy.Cell]) – gdstk.Cell or gdspy.Cell containing 2D geometric data.

• axis (int) – Integer index defining the extrusion axis: 0 (x), 1 (y), or 2 (z).

• slab_bounds (Tuple[float, float]) – Minimal and maximal positions of the extruded slab along axis.

• gds_layer (int) – Layer index in the gds_cell.

• gds_dtype (int = None) – Data-type index in the gds_cell. If None, imports all data for this layer into the returned list.

• gds_scale (float = 1.0) – Length scale used in GDS file in units of micrometer. For example, if gds file uses nanometers, set gds_scale=1e-3. Must be positive.

• dilation (float = 0.0) – Dilation (positive) or erosion (negative) amount to be applied to the original polygons.

• sidewall_angle (float = 0) – Angle of the extrusion sidewalls, away from the vertical direction, in radians. Positive (negative) values result in slabs larger (smaller) at the base than at the top.

• reference_plane (PlanePosition = "middle") – Reference position of the (dilated/eroded) polygons along the slab axis. One of "middle" (polygons correspond to the center of the slab bounds), "bottom" (minimal slab bound position), or "top" (maximal slab bound position). This value has no effect if sidewall_angle == 0.

Returns:

Geometries created from the 2D data.

Return type:

Geometry

static from_shapely(shape, axis, slab_bounds, dilation=0.0, sidewall_angle=0, reference_plane='middle')

Convert a shapely primitive into a geometry instance by extrusion.

Parameters:

• shape (shapely.geometry.base.BaseGeometry) – Shapely primitive to be converted. It must be a linear ring, a polygon or a collection of any of those.

• axis (int) – Integer index defining the extrusion axis: 0 (x), 1 (y), or 2 (z).

• slab_bounds (Tuple[float, float]) – Minimal and maximal positions of the extruded slab along axis.

• dilation (float) – Dilation of the polygon in the base by shifting each edge along its normal outwards direction by a distance; a negative value corresponds to erosion.

• sidewall_angle (float = 0) – Angle of the extrusion sidewalls, away from the vertical direction, in radians. Positive (negative) values result in slabs larger (smaller) at the base than at the top.

• reference_plane (PlanePosition = "middle") – Reference position of the (dilated/eroded) polygons along the slab axis. One of "middle" (polygons correspond to the center of the slab bounds), "bottom" (minimal slab bound position), or "top" (maximal slab bound position). This value has no effect if sidewall_angle == 0.

Returns:

Geometry extruded from the 2D data.

Return type:

Geometry

to_gdstk(x=None, y=None, z=None, gds_layer=0, gds_dtype=0)

Convert a Geometry object’s planar slice to a .gds type polygon.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

• gds_layer (int = 0) – Layer index to use for the shapes stored in the .gds file.

• gds_dtype (int = 0) – Data-type index to use for the shapes stored in the .gds file.

Returns:

List of gdstk.Polygon.

Return type:

List

to_gdspy(x=None, y=None, z=None, gds_layer=0, gds_dtype=0)

Convert a Geometry object’s planar slice to a .gds type polygon.

Parameters:

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

• gds_layer (int = 0) – Layer index to use for the shapes stored in the .gds file.

• gds_dtype (int = 0) – Data-type index to use for the shapes stored in the .gds file.

Returns:

List of gdspy.Polygon and gdspy.PolygonSet.

Return type:

List

to_gds(cell, x=None, y=None, z=None, gds_layer=0, gds_dtype=0)

Append a Geometry object’s planar slice to a .gds cell.

Parameters:

• cell (gdstk.Cell or gdspy.Cell) – Cell object to which the generated polygons are added.

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

• gds_layer (int = 0) – Layer index to use for the shapes stored in the .gds file.

• gds_dtype (int = 0) – Data-type index to use for the shapes stored in the .gds file.

to_gds_file(fname, x=None, y=None, z=None, gds_layer=0, gds_dtype=0, gds_cell_name='MAIN')

Export a Geometry object’s planar slice to a .gds file.

Parameters:

• fname (str) – Full path to the .gds file to save the Geometry slice to.

• x (float = None) – Position of plane in x direction, only one of x,y,z can be specified to define plane.

• y (float = None) – Position of plane in y direction, only one of x,y,z can be specified to define plane.

• z (float = None) – Position of plane in z direction, only one of x,y,z can be specified to define plane.

• gds_layer (int = 0) – Layer index to use for the shapes stored in the .gds file.

• gds_dtype (int = 0) – Data-type index to use for the shapes stored in the .gds file.

• gds_cell_name (str = 'MAIN') – Name of the cell created in the .gds file to store the geometry.

compute_derivatives(derivative_info)

Compute the adjoint derivatives for this object.

__add__(other)

Union of geometries

__radd__(other)

Union of geometries

__or__(other)

Union of geometries

__mul__(other)

Intersection of geometries

__and__(other)

Intersection of geometries

__sub__(other)

Difference of geometries

__xor__(other)

Symmetric difference of geometries

__pos__()

No op

__neg__()

Opposite of a geometry

__invert__()

Opposite of a geometry

__hash__()

Hash method.