tidy3d.plugins.polyslab.ComplexPolySlab#

class tidy3d.plugins.polyslab.ComplexPolySlab(*, type: typing.Literal['ComplexPolySlab'] = 'ComplexPolySlab', axis: typing.Literal[0, 1, 2] = 2, sidewall_angle: pydantic.v1.types.ConstrainedFloatValue = 0.0, reference_plane: typing.Literal['bottom', 'middle', 'top'] = 'middle', slab_bounds: typing.Tuple[float, float], dilation: float = 0.0, vertices: tidy3d.components.types.ArrayLike[dtype=float, ndim=2])#

Bases: tidy3d.components.geometry.polyslab.ComplexPolySlabBase

Interface for dividing a complex polyslab where self-intersecting polygon can occur during extrusion.

Parameters

axis (Literal[0, 1, 2] = 2) – Specifies dimension of the planar axis (0,1,2) -> (x,y,z).
sidewall_angle (ConstrainedFloatValue = 0.0) – [units = rad]. Angle of the sidewall. sidewall_angle=0 (default) specifies a vertical wall; 0<sidewall_angle<np.pi/2 specifies a shrinking cross section along the axis direction; and -np.pi/2<sidewall_angle<0 specifies an expanding cross section along the axis direction.
reference_plane (Literal['bottom', 'middle', 'top'] = middle) – The position of the plane where the supplied cross section are defined. The plane is perpendicular to the axis. The plane is located at the bottom, middle, or top of the geometry with respect to the axis. E.g. if axis=1, bottom refers to the negative side of the y-axis, and top refers to the positive side of the y-axis.
slab_bounds (Tuple[float, float]) – [units = um]. Minimum and maximum positions of the slab along axis dimension.
dilation (float = 0.0) – [units = um]. Dilation of the supplied polygon by shifting each edge along its normal outwards direction by a distance; a negative value corresponds to erosion.
vertices (ArrayLike[dtype=float, ndim=2]) – [units = um]. List of (d1, d2) defining the 2 dimensional positions of the polygon face vertices at the reference_plane. The index of dimension should be in the ascending order: e.g. if the slab normal axis is axis=y, the coordinate of the vertices will be in (x, z)

Example

>>> vertices = ((0, 0), (1, 0), (1, 1), (0, 1), (0, 0.9), (0, 0.11))
>>> p = ComplexPolySlab(vertices=vertices, axis=2, slab_bounds=(0, 1), sidewall_angle=0.785)
>>> # To obtain the divided polyslabs, there are two approaches:
>>> # 1) a list of divided polyslabs
>>> geo_list = p.sub_polyslabs
>>> # 2) geometry group containing the divided polyslabs
>>> geo_group = p.geometry_group
>>> # Or directly obtain the structure with a user-specified medium
>>> mat = td.Medium(permittivity=2)
>>> structure = p.to_structure(mat)

Note

This version is limited to neighboring vertex-vertex crossing type of self-intersecting events. Extension to cover all types of self-intersecting events is expected in the future.

The algorithm is as follows (for the convenience of illustration, let’s consider the reference plane to lie at the bottom of the polyslab),

1. Starting from the reference plane, find out the critical extrusion distance for the first vertices degeneracy event when marching towards the top of the polyslab;

2. Construct a sub-polyslab whose base is the polygon at the reference plane and height to be the critical extrusion distance;

3. At the critical extrusion distance, constructing a new polygon that keeps only one of the degenerate vertices;

4. Set the reference plane to the position of the new polygon, and repeating 1-3 to construct sub-polyslabs until reaching the top of the polyslab, or all vertices collapsed into a 1D curve or a 0D point.

__init__(**kwargs)#: Init method, includes post-init validators.

Methods

`__init__`(**kwargs)	Init method, includes post-init validators.
`add_ax_labels_lims`(axis, ax[, buffer])	Sets the x,y labels based on `axis` and the extends based on `self.bounds`.
`add_type_field`()	Automatically place "type" field with model name in the model field dictionary.
`array_to_vertices`(arr_vertices)	Converts a numpy array of vertices to a list of tuples.
`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.
`construct`([_fields_set])	Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.
`copy`(**kwargs)	Copy a Tidy3dBaseModel.
`correct_shape`(val)	Makes sure vertices size is correct.
`dict`(*[, include, exclude, by_alias, ...])	Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
`dict_from_file`(fname[, group_path])	Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.
`dict_from_hdf5`(fname[, group_path, ...])	Loads a dictionary containing the model contents from a .hdf5 file.
`dict_from_hdf5_gz`(fname[, group_path, ...])	Loads a dictionary containing the model contents from a .hdf5.gz file.
`dict_from_json`(fname)	Load dictionary of the model from a .json file.
`dict_from_yaml`(fname)	Load dictionary of the model from a .yaml file.
`evaluate_inf_shape`(shape)	Returns a copy of shape with inf vertices replaced by large numbers if polygon.
`from_file`(fname[, group_path])	Loads a `Tidy3dBaseModel` from .yaml, .json, .hdf5, or .hdf5.gz file.
`from_gds`(gds_cell, axis, slab_bounds, gds_layer)	Import `PolySlab` from a `gdstk.Cell`.
`from_hdf5`(fname[, group_path, custom_decoders])	Loads `Tidy3dBaseModel` instance to .hdf5 file.
`from_hdf5_gz`(fname[, group_path, ...])	Loads `Tidy3dBaseModel` instance to .hdf5.gz file.
`from_json`(fname, **parse_obj_kwargs)	Load a `Tidy3dBaseModel` from .json file.
`from_orm`(obj)
`from_shapely`(shape, axis, slab_bounds[, ...])	Convert a shapely primitive into a geometry instance by extrusion.
`from_yaml`(fname, **parse_obj_kwargs)	Loads `Tidy3dBaseModel` from .yaml file.
`generate_docstring`()	Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.
`get_sub_model`(group_path, model_dict)	Get the sub model for a given group path.
`get_submodels_by_hash`()	Return a dictionary of this object's sub-models indexed by their hash values.
`get_tuple_group_name`(index)	Get the group name of a tuple element.
`get_tuple_index`(key_name)	Get the index into the tuple based on its group name.
`help`([methods])	Prints message describing the fields and methods of a `Tidy3dBaseModel`.
`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 shapely geometry 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)	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.
`json`(*[, include, exclude, by_alias, ...])	Generate a JSON representation of the model, include and exclude arguments as per dict().
`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`.
`no_complex_self_intersecting_polygon_at_reference_plane`(...)	At the reference plane, check if the polygon is self-intersecting.
`no_self_intersecting_polygon_during_extrusion`(...)	Turn off the validation for this class.
`parse_file`(path, *[, content_type, ...])
`parse_obj`(obj)
`parse_raw`(b, *[, content_type, encoding, ...])
`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.
`schema`([by_alias, ref_template])
`schema_json`(*[, by_alias, ref_template])
`slab_bounds_order`(val)	Maximum position of the slab should be no smaller than its minimal position.
`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_file`(fname)	Exports `Tidy3dBaseModel` instance to .yaml, .json, or .hdf5 file
`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.
`to_hdf5`(fname[, custom_encoders])	Exports `Tidy3dBaseModel` instance to .hdf5 file.
`to_hdf5_gz`(fname[, custom_encoders])	Exports `Tidy3dBaseModel` instance to .hdf5.gz file.
`to_json`(fname)	Exports `Tidy3dBaseModel` instance to .json file
`to_structure`(medium)	Construct a structure containing a user-specified medium and a GeometryGroup made of all the divided PolySlabs from this object.
`to_yaml`(fname)	Exports `Tidy3dBaseModel` instance to .yaml file.
`translated`(x, y, z)	Return a translated copy of this geometry.
`tuple_to_dict`(tuple_values)	How we generate a dictionary mapping new keys to tuple values for hdf5.
`unpop_axis`(ax_coord, plane_coords, axis)	Combine coordinate along axis with coordinates on the plane tangent to the axis.
`update_forward_refs`(**localns)	Try to update ForwardRefs on fields based on this Model, globalns and localns.
`updated_copy`(**kwargs)	Make copy of a component instance with `**kwargs` indicating updated field values.
`validate`(value)
`vertices_to_array`(vertices_tuple)	Converts a list of tuples (vertices) to a numpy array.
`volume`([bounds])	Returns object's volume with optional bounds.

Attributes

`base_polygon`	The polygon at the base, derived from the `middle_polygon`.
`bounding_box`	Returns `Box` representation of the bounding box of a `Geometry`.
`bounds`	Returns bounding box min and max coordinates.
`center_axis`	Gets the position of the center of the geometry in the out of plane dimension.
`finite_length_axis`	Gets the length of the geometry along the out of plane dimension.
`geometry_group`	Divide a complex polyslab into a list of simple polyslabs, which are assembled into a `GeometryGroup`.
`length_axis`	Gets the length of the geometry along the out of plane dimension.
`middle_polygon`	The polygon at the middle.
`plot_params`	Default parameters for plotting a Geometry object.
`reference_polygon`	The polygon at the reference plane.
`sub_polyslabs`	Divide a complex polyslab into a list of simple polyslabs.
`top_polygon`	The polygon at the top, derived from the `middle_polygon`.
`zero_dims`	A list of axes along which the `Geometry` is zero-sized based on its bounds.

class Config#

Bases: object

Sets config for all Tidy3dBaseModel objects.

allow_population_by_field_namebool = True: Allow properties to stand in for fields(?).
arbitrary_types_allowedbool = True: Allow types like numpy arrays.
extrastr = ‘forbid’: Forbid extra kwargs not specified in model.
json_encodersDict[type, Callable]: Defines how to encode type in json file.
validate_allbool = True: Validate default values just to be safe.
validate_assignmentbool: Re-validate after re-assignment of field in model.

__add__(other)#: Union of geometries

__and__(other)#: Intersection of geometries

__eq__(other)#: Define == for two Tidy3DBaseModels.

__ge__(other)#: define >= for getting unique indices based on hash.

__gt__(other)#: define > for getting unique indices based on hash.

__hash__() → int#: Hash method.

classmethod __init_subclass__() → None#: Things that are done to each of the models.

__invert__()#: Opposite of a geometry

__iter__() → TupleGenerator#: so dict(model) works

__le__(other)#: define <= for getting unique indices based on hash.

__lt__(other)#: define < for getting unique indices based on hash.

__mul__(other)#: Intersection of geometries

__neg__()#: Opposite of a geometry

__or__(other)#: Union of geometries

__pos__()#: No op

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any, None, None]#: Used by devtools (https://python-devtools.helpmanual.io/) to provide a human readable representations of objects

__radd__(other)#: Union of geometries

__repr_name__() → str#: Name of the instance’s class, used in __repr__.

__rich_repr__() → RichReprResult#: Get fields for Rich library

__sub__(other)#: Difference of geometries

classmethod __try_update_forward_refs__(**localns: Any) → None#: Same as update_forward_refs but will not raise exception when forward references are not defined.

__xor__(other)#: Symmetric difference of geometries

add_ax_labels_lims(axis: Literal[0, 1, 2], ax: matplotlib.axes._axes.Axes, buffer: float = 0.3) → matplotlib.axes._axes.Axes#

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

classmethod add_type_field() → None#: Automatically place “type” field with model name in the model field dictionary.

static array_to_vertices(arr_vertices: numpy.ndarray) → tidy3d.components.types.ArrayLike[dtype=float, ndim=2]#: Converts a numpy array of vertices to a list of tuples.

property base_polygon: numpy.ndarray#

The polygon at the base, derived from the middle_polygon.

Returns: The vertices of the polygon at the base.
Return type: ArrayLike[float, float]

property bounding_box#

Returns Box representation of the bounding box of a Geometry.

Returns: Geometric object representing bounding box.
Return type: Box

property bounds: Tuple[Tuple[float, float, float], Tuple[float, float, float]]#

Returns bounding box min and max coordinates. The dilation and slant angle are not taken into account exactly for speed. Instead, the polygon may be slightly smaller than the returned bounds, but it should always be fully contained.

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: Tuple[Tuple[float, float, float], Tuple[float, float, float]], bounds2: Tuple[Tuple[float, float, float], Tuple[float, float, float]]) → Tuple[Tuple[float, float, float], Tuple[float, float, float]]#: Return the bounds that are the intersection of two bounds.

static car_2_sph(x: float, y: float, z: float) → Tuple[float, float, float]#

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 car_2_sph_field(f_x: float, f_y: float, f_z: float, theta: float, phi: float) → Tuple[complex, complex, complex]#

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]

property center_axis: float#: Gets the position of the center of the geometry in the out of plane dimension.

classmethod construct(_fields_set: Optional[SetStr] = None, **values: Any) → Model#: Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy(**kwargs) → tidy3d.components.base.Tidy3dBaseModel#: Copy a Tidy3dBaseModel. With deep=True as default.

classmethod correct_shape(val)#: Makes sure vertices size is correct. Make sure no intersecting edges.

dict(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → DictStrAny#: Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

classmethod dict_from_file(fname: str, group_path: Optional[str] = None) → dict#

Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.

Parameters

fname (str) – Full path to the file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to use as the base level.

Returns

A dictionary containing the model.

Return type

dict

Example

>>> simulation = Simulation.from_file(fname='folder/sim.json') 

classmethod dict_from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) → dict#

Loads a dictionary containing the model contents from a .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.

Returns

Dictionary containing the model.

Return type

dict

Example

>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5') 

classmethod dict_from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) → dict#

Loads a dictionary containing the model contents from a .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.

Returns

Dictionary containing the model.

Return type

dict

Example

>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5.gz') 

classmethod dict_from_json(fname: str) → dict#

Load dictionary of the model from a .json file.

Parameters: fname (str) – Full path to the .json file to load the Tidy3dBaseModel from.
Returns: A dictionary containing the model.
Return type: dict

Example

>>> sim_dict = Simulation.dict_from_json(fname='folder/sim.json') 

classmethod dict_from_yaml(fname: str) → dict#

Load dictionary of the model from a .yaml file.

Parameters: fname (str) – Full path to the .yaml file to load the Tidy3dBaseModel from.
Returns: A dictionary containing the model.
Return type: dict

Example

>>> sim_dict = Simulation.dict_from_yaml(fname='folder/sim.yaml') 

static evaluate_inf_shape(shape: shapely.geometry.base.BaseGeometry) → shapely.geometry.base.BaseGeometry#: Returns a copy of shape with inf vertices replaced by large numbers if polygon.

property finite_length_axis: float#: Gets the length of the geometry along the out of plane dimension. If the length is td.inf, return LARGE_NUMBER

classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads a Tidy3dBaseModel from .yaml, .json, .hdf5, or .hdf5.gz file.

Parameters

fname (str) – Full path to the file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to use as the base level. Only for hdf5 files. Starting / is optional.
**parse_obj_kwargs – Keyword arguments passed to either pydantic’s parse_obj function when loading model.

Returns

An instance of the component class calling load.

Return type

Tidy3dBaseModel

Example

>>> simulation = Simulation.from_file(fname='folder/sim.json') 

classmethod from_gds(gds_cell, axis: Literal[0, 1, 2], slab_bounds: Tuple[float, float], gds_layer: int, gds_dtype: Optional[int] = None, gds_scale: pydantic.v1.types.PositiveFloat = 1.0, dilation: float = 0.0, sidewall_angle: float = 0, reference_plane: Literal['bottom', 'middle', 'top'] = 'middle') → List[tidy3d.components.geometry.polyslab.PolySlab]#

Import PolySlab from a gdstk.Cell.

Parameters

gds_cell (gdstk.Cell) – gdstk.Cell containing 2D geometric data.
axis (int) – Integer index into the polygon’s slab axis. (0,1,2) -> (x,y,z).
slab_bounds (Tuple[float, float]) – Minimum and maximum positions of the 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 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 sidewall. sidewall_angle=0 (default) specifies vertical wall, while 0<sidewall_angle<np.pi/2 for the base to be larger than the top.
reference_plane (PlanePosition = "middle") – The position of the GDS layer. It can be at the bottom, middle, or top of the PolySlab. E.g. if axis=1, bottom refers to the negative side of y-axis, and top refers to the positive side of y-axis.

Returns

List of PolySlab objects sharing axis and slab bound properties.

Return type

List[PolySlab]

classmethod from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_hdf5(fname='folder/sim.hdf5') 

classmethod from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel instance to .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_hdf5_gz(fname='folder/sim.hdf5.gz') 

classmethod from_json(fname: str, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Load a Tidy3dBaseModel from .json file.

Parameters

fname (str) – Full path to the .json file to load the Tidy3dBaseModel from.

Returns

Tidy3dBaseModel – An instance of the component class calling load.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_json(fname='folder/sim.json') 

static from_shapely(shape: shapely.geometry.base.BaseGeometry, axis: Literal[0, 1, 2], slab_bounds: Tuple[float, float], dilation: float = 0.0, sidewall_angle: float = 0, reference_plane: Literal['bottom', 'middle', 'top'] = 'middle') → tidy3d.components.geometry.base.Geometry#

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

classmethod from_yaml(fname: str, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel from .yaml file.

Parameters

fname (str) – Full path to the .yaml file to load the Tidy3dBaseModel from.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Returns

An instance of the component class calling from_yaml.

Return type

Tidy3dBaseModel

Example

>>> simulation = Simulation.from_yaml(fname='folder/sim.yaml') 

classmethod generate_docstring() → str#: Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.

property geometry_group: tidy3d.components.geometry.base.GeometryGroup#

Divide a complex polyslab into a list of simple polyslabs, which are assembled into a GeometryGroup.

Returns: GeometryGroup for a list of simple polyslabs divided from the complex polyslab.
Return type: GeometryGroup

classmethod get_sub_model(group_path: str, model_dict: dict | list) → dict#: Get the sub model for a given group path.

get_submodels_by_hash() → Dict[int, List[Union[str, Tuple[str, int]]]]#: Return a dictionary of this object’s sub-models indexed by their hash values.

static get_tuple_group_name(index: int) → str#: Get the group name of a tuple element.

static get_tuple_index(key_name: str) → int#: Get the index into the tuple based on its group name.

help(methods: bool = False) → None#

Prints message describing the fields and methods of a Tidy3dBaseModel.

Parameters: methods (bool = False) – Whether to also print out information about object’s methods.

Example

>>> simulation.help(methods=True) 

inside(x: numpy.ndarray[float], y: numpy.ndarray[float], z: numpy.ndarray[float]) → numpy.ndarray[bool]#

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]

inside_meshgrid(x: numpy.ndarray[float], y: numpy.ndarray[float], z: numpy.ndarray[float]) → numpy.ndarray[bool]#

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]

intersections_2dbox(plane: tidy3d.components.geometry.base.Box) → List[shapely.geometry.base.BaseGeometry]#

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 Documentaton.
Return type: List[shapely.geometry.base.BaseGeometry]

intersections_plane(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None)#

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

Parameters

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

Returns

List[shapely.geometry.base.BaseGeometry] – List of 2D shapes that intersect plane. For more details refer to
`Shapely’s Documentaton <https (//shapely.readthedocs.io/en/stable/project.html>`_.)

intersections_tilted_plane(normal: typing.Tuple[float, float, float], origin: typing.Tuple[float, float, float], to_2D: tidy3d.components.types.ArrayLike[dtype=float, ndim=2, shape=(4, 4)]) → List[shapely.geometry.base.BaseGeometry]#

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 Documentaton.

Return type

List[shapely.geometry.base.BaseGeometry]

intersects(other) → bool#

Returns True if two Geometry have intersecting .bounds.

Parameters: other (Geometry) – Geometry to check intersection with.
Returns: Whether the rectangular bounding boxes of the two geometries intersect.
Return type: bool

intersects_axis_position(axis: int, position: float) → bool#

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

Parameters

axis (int = None) – Axis nomral to the plane.
position (float = None) – Position of plane along the normal axis.

Returns

Whether this geometry intersects the plane.

Return type

bool

intersects_plane(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None) → bool#

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

json(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Optional[Callable[[Any], Any]] = None, models_as_dict: bool = True, **dumps_kwargs: Any) → str#

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

static kspace_2_sph(ux: float, uy: float, axis: Literal[0, 1, 2]) → Tuple[float, float]#

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]

property length_axis: float#: Gets the length of the geometry along the out of plane dimension.

static load_gds_vertices_gdspy(gds_cell, gds_layer: int, gds_dtype: Optional[int] = None, gds_scale: pydantic.v1.types.PositiveFloat = 1.0) → List[tidy3d.components.types.ArrayLike[dtype=float, ndim=2]]#

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 load_gds_vertices_gdstk(gds_cell, gds_layer: int, gds_dtype: Optional[int] = None, gds_scale: pydantic.v1.types.PositiveFloat = 1.0) → List[tidy3d.components.types.ArrayLike[dtype=float, ndim=2]]#

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]

property middle_polygon: numpy.ndarray#

The polygon at the middle.

Returns: The vertices of the polygon at the middle.
Return type: ArrayLike[float, float]

classmethod no_complex_self_intersecting_polygon_at_reference_plane(val, values)#

At the reference plane, check if the polygon is self-intersecting.

There are two types of self-intersection that can occur during dilation: 1) the one that creates holes/islands, or splits polygons, or removes everything; 2) the one that does not.

For 1), we issue an error since it is yet to be supported; For 2), we heal the polygon, and warn that the polygon has been cleaned up.

classmethod no_self_intersecting_polygon_during_extrusion(val, values)#: Turn off the validation for this class.

static parse_xyz_kwargs(**xyz) → Tuple[Literal[0, 1, 2], float]#

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

plot(x: float = None, y: float = None, z: float = None, ax: matplotlib.axes._axes.Axes = None, **patch_kwargs) → matplotlib.axes._axes.Axes#

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

property plot_params#: Default parameters for plotting a Geometry object.

plot_shape(shape: shapely.geometry.base.BaseGeometry, plot_params: tidy3d.components.viz.PlotParams, ax: matplotlib.axes._axes.Axes) → matplotlib.axes._axes.Axes#: Defines how a shape is plotted on a matplotlib axes.

static pop_axis(coord: Tuple[Any, Any, Any], axis: int) → Tuple[Any, Tuple[Any, Any]]#

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]

property reference_polygon: numpy.ndarray#

The polygon at the reference plane.

Returns: The vertices of the polygon at the reference plane.
Return type: ArrayLike[float, float]

reflect_points(points: tidy3d.components.types.ArrayLike[dtype=float, ndim=3], polar_axis: typing.Literal[0, 1, 2], angle_theta: float, angle_phi: float) → tidy3d.components.types.ArrayLike[dtype=float, ndim=3]#

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.

static rotate_points(points: tidy3d.components.types.ArrayLike[dtype=float, ndim=3], axis: typing.Tuple[float, float, float], angle: float) → tidy3d.components.types.ArrayLike[dtype=float, ndim=3]#

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

rotated(angle: float, axis: Union[Literal[0, 1, 2], Tuple[float, float, float]]) → tidy3d.components.geometry.base.Geometry#

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

scaled(x: float = 1.0, y: float = 1.0, z: float = 1.0) → tidy3d.components.geometry.base.Geometry#

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

classmethod slab_bounds_order(val)#: Maximum position of the slab should be no smaller than its minimal position.

static sph_2_car(r: float, theta: float, phi: float) → Tuple[float, float, float]#

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: float, f_theta: float, f_phi: float, theta: float, phi: float) → Tuple[complex, complex, complex]#

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]

property sub_polyslabs: List[tidy3d.components.geometry.polyslab.PolySlab]#

Divide a complex polyslab into a list of simple polyslabs. Only neighboring vertex-vertex crossing events are treated in this version.

Returns: A list of simple polyslabs.
Return type: List[PolySlab]

surface_area(bounds: Optional[Tuple[Tuple[float, float, float], Tuple[float, float, float]]] = 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

to_file(fname: str) → None#

Exports Tidy3dBaseModel instance to .yaml, .json, or .hdf5 file

Parameters: fname (str) – Full path to the .yaml or .json file to save the Tidy3dBaseModel to.

Example

>>> simulation.to_file(fname='folder/sim.json') 

to_gds(cell, x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, gds_layer: pydantic.v1.types.NonNegativeInt = 0, gds_dtype: pydantic.v1.types.NonNegativeInt = 0) → None#

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: str, x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, gds_layer: pydantic.v1.types.NonNegativeInt = 0, gds_dtype: pydantic.v1.types.NonNegativeInt = 0, gds_cell_name: str = 'MAIN') → None#

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.

to_gdspy(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, gds_layer: pydantic.v1.types.NonNegativeInt = 0, gds_dtype: pydantic.v1.types.NonNegativeInt = 0) → List#

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_gdstk(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, gds_layer: pydantic.v1.types.NonNegativeInt = 0, gds_dtype: pydantic.v1.types.NonNegativeInt = 0) → List#

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_hdf5(fname: str, custom_encoders: Optional[List[Callable]] = None) → None#

Exports Tidy3dBaseModel instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to save the Tidy3dBaseModel to.
custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the value supplied and write it to the hdf5 fname at group_path.

Example

>>> simulation.to_hdf5(fname='folder/sim.hdf5') 

to_hdf5_gz(fname: str, custom_encoders: Optional[List[Callable]] = None) → None#

Exports Tidy3dBaseModel instance to .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to save the Tidy3dBaseModel to.
custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the value supplied and write it to the hdf5 fname at group_path.

Example

>>> simulation.to_hdf5_gz(fname='folder/sim.hdf5.gz') 

to_json(fname: str) → None#

Exports Tidy3dBaseModel instance to .json file

Parameters: fname (str) – Full path to the .json file to save the Tidy3dBaseModel to.

Example

>>> simulation.to_json(fname='folder/sim.json') 

Construct a structure containing a user-specified medium and a GeometryGroup made of all the divided PolySlabs from this object.

Parameters: medium (MediumType) – Medium for the complex polyslab.
Returns: The structure containing all divided polyslabs made of a user-specified medium.
Return type: Structure

to_yaml(fname: str) → None#

Exports Tidy3dBaseModel instance to .yaml file.

Parameters: fname (str) – Full path to the .yaml file to save the Tidy3dBaseModel to.

Example

>>> simulation.to_yaml(fname='folder/sim.yaml') 

property top_polygon: numpy.ndarray#

The polygon at the top, derived from the middle_polygon.

Returns: The vertices of the polygon at the top.
Return type: ArrayLike[float, float]

translated(x: float, y: float, z: float) → tidy3d.components.geometry.base.Geometry#

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

classmethod tuple_to_dict(tuple_values: tuple) → dict#: How we generate a dictionary mapping new keys to tuple values for hdf5.

static unpop_axis(ax_coord: Any, plane_coords: Tuple[Any, Any], axis: int) → Tuple[Any, Any, Any]#

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]

classmethod update_forward_refs(**localns: Any) → None#: Try to update ForwardRefs on fields based on this Model, globalns and localns.

updated_copy(**kwargs) → tidy3d.components.base.Tidy3dBaseModel#: Make copy of a component instance with **kwargs indicating updated field values.

static vertices_to_array(vertices_tuple: tidy3d.components.types.ArrayLike[dtype=float, ndim=2]) → numpy.ndarray#: Converts a list of tuples (vertices) to a numpy array.

volume(bounds: Optional[Tuple[Tuple[float, float, float], Tuple[float, float, float]]] = 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

property zero_dims: List[Literal[0, 1, 2]]#: A list of axes along which the Geometry is zero-sized based on its bounds.