tidy3d.Box

class Box

Bases: SimplePlaneIntersection, Centered

Rectangular prism.

Also base class for Simulation, Monitor, and Source.

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.

Example

>>> b = Box(center=(1,2,3), size=(2,2,2))

Attributes

bounds	Returns bounding box min and max coordinates.
geometry	Box representation of self (used for subclasses of Box).
zero_dims	A list of axes along which the Box is zero-sized.
attrs

Methods

compute_derivatives(derivative_info)	Compute the adjoint derivatives for this object.
derivative_face(min_max_index, axis_normal, ...)	Compute the derivative w.r.t.
derivative_faces(derivative_info)	Derivative with respect to normal position of 6 faces of Box.
derivatives_center_size(vjps_faces)	Derivatives with respect to the center and size fields in the Box.
from_bounds(rmin, rmax, **kwargs)	Constructs a Box from minimum and maximum coordinate bounds
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.
intersections_plane([x, y, z])	Returns shapely geometry at plane specified by one non None value of x,y,z.
intersections_with(other)	Returns list of shapely geometries representing the intersections of the geometry with this 2D box.
surfaces(size, center, **kwargs)	Returns a list of 6 Box instances corresponding to each surface of a 3D volume.
surfaces_with_exclusion(size, center, **kwargs)	Returns a list of 6 Box instances corresponding to each surface of a 3D volume.

Inherited Common Usage

size

classmethod from_bounds(rmin, rmax, **kwargs)

Constructs a Box from minimum and maximum coordinate bounds

Parameters:

• rmin (Tuple[float, float, float]) – (x, y, z) coordinate of the minimum values.

• rmax (Tuple[float, float, float]) – (x, y, z) coordinate of the maximum values.

Example

>>> b = Box.from_bounds(rmin=(-1, -2, -3), rmax=(3, 2, 1))

classmethod surfaces(size, center, **kwargs)

Returns a list of 6 Box instances corresponding to each surface of a 3D volume. The output surfaces are stored in the order [x-, x+, y-, y+, z-, z+], where x, y, and z denote which axis is perpendicular to that surface, while “-” and “+” denote the direction of the normal vector of that surface. If a name is provided, each output surface’s name will be that of the provided name appended with the above symbols. E.g., if the provided name is “box”, the x+ surfaces’s name will be “box_x+”.

Parameters:

• size (Tuple[float, float, float]) – Size of object in x, y, and z directions.

• center (Tuple[float, float, float]) – Center of object in x, y, and z.

Example

>>> b = Box.surfaces(size=(1, 2, 3), center=(3, 2, 1))

classmethod surfaces_with_exclusion(size, center, **kwargs)

Returns a list of 6 Box instances corresponding to each surface of a 3D volume. The output surfaces are stored in the order [x-, x+, y-, y+, z-, z+], where x, y, and z denote which axis is perpendicular to that surface, while “-” and “+” denote the direction of the normal vector of that surface. If a name is provided, each output surface’s name will be that of the provided name appended with the above symbols. E.g., if the provided name is “box”, the x+ surfaces’s name will be “box_x+”. If kwargs contains an exclude_surfaces parameter, the returned list of surfaces will not include the excluded surfaces. Otherwise, the behavior is identical to that of surfaces().

Parameters:

• size (Tuple[float, float, float]) – Size of object in x, y, and z directions.

• center (Tuple[float, float, float]) – Center of object in x, y, and z.

Example

>>> b = Box.surfaces_with_exclusion(
...     size=(1, 2, 3), center=(3, 2, 1), exclude_surfaces=["x-"]
... )

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

Returns shapely geometry 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]

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]

intersections_with(other)

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

Returns:

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

Return type:

List[shapely.geometry.base.BaseGeometry]

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]

property geometry

Box representation of self (used for subclasses of Box).

Returns:

Instance of Box representing self’s geometry.

Return type:

Box

property zero_dims

A list of axes along which the Box is zero-sized.

compute_derivatives(derivative_info)

Compute the adjoint derivatives for this object.

static derivatives_center_size(vjps_faces)

Derivatives with respect to the center and size fields in the Box.

derivative_faces(derivative_info)

Derivative with respect to normal position of 6 faces of Box.

derivative_face(min_max_index, axis_normal, derivative_info)

Compute the derivative w.r.t. shifting a face in the normal direction.