tidy3d.FieldProjectionKSpaceMonitor#

class tidy3d.FieldProjectionKSpaceMonitor(*, type: typing.Literal['FieldProjectionKSpaceMonitor'] = 'FieldProjectionKSpaceMonitor', center: typing.Tuple[float, float, float] = (0.0, 0.0, 0.0), size: typing.Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], name: pydantic.v1.types.ConstrainedStrValue, interval_space: typing.Tuple[pydantic.v1.types.PositiveInt, pydantic.v1.types.PositiveInt, pydantic.v1.types.PositiveInt] = (1, 1, 1), colocate: typing.Literal[True] = True, freqs: typing.Union[typing.Tuple[float, ...], tidy3d.components.types.ArrayLike[dtype=float, ndim=1]], apodization: tidy3d.components.apodization.ApodizationSpec = ApodizationSpec(start=None, end=None, width=None, type='ApodizationSpec'), normal_dir: typing.Literal['+', '-'] = None, exclude_surfaces: typing.Tuple[typing.Literal['x-', 'x+', 'y-', 'y+', 'z-', 'z+'], ...] = None, custom_origin: typing.Tuple[float, float, float] = None, far_field_approx: bool = True, window_size: typing.Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat] = (0, 0), medium: typing.Union[tidy3d.components.medium.Medium, tidy3d.components.medium.AnisotropicMedium, tidy3d.components.medium.PECMedium, tidy3d.components.medium.PoleResidue, tidy3d.components.medium.Sellmeier, tidy3d.components.medium.Lorentz, tidy3d.components.medium.Debye, tidy3d.components.medium.Drude, tidy3d.components.medium.FullyAnisotropicMedium, tidy3d.components.medium.CustomMedium, tidy3d.components.medium.CustomPoleResidue, tidy3d.components.medium.CustomSellmeier, tidy3d.components.medium.CustomLorentz, tidy3d.components.medium.CustomDebye, tidy3d.components.medium.CustomDrude, tidy3d.components.medium.CustomAnisotropicMedium, tidy3d.components.medium.PerturbationMedium, tidy3d.components.medium.PerturbationPoleResidue, tidy3d.components.medium.Medium2D] = None, proj_axis: typing.Literal[0, 1, 2], proj_distance: float = 1000000.0, ux: typing.Union[typing.Tuple[float, ...], tidy3d.components.types.ArrayLike[dtype=float, ndim=1]], uy: typing.Union[typing.Tuple[float, ...], tidy3d.components.types.ArrayLike[dtype=float, ndim=1]])#

Bases: tidy3d.components.monitor.AbstractFieldProjectionMonitor

Monitor that samples electromagnetic near fields in the frequency domain and projects them on an observation plane defined in k-space. The center and size fields define where the monitor will be placed in order to record near fields, typically very close to the structure of interest. The near fields are then projected to far-field locations defined in k-space by ux, uy, and proj_distance, relative to the custom_origin. Here, ux and uy are associated with a local coordinate system where the local ‘z’ axis is defined by proj_axis: which is the axis normal to this monitor. If the distance between the near and far field locations is much larger than the size of the device, one can typically set far_field_approx to True, which will make use of the far-field approximation to speed up calculations. If the projection distance is comparable to the size of the device, we recommend setting far_field_approx to False, so that the approximations are not used, and the projection is accurate even just a few wavelengths away from the near field locations. For applications where the monitor is an open surface rather than a box that encloses the device, it is advisable to pick the size of the monitor such that the recorded near fields decay to negligible values near the edges of the monitor.

Parameters

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

  • size (Tuple[NonNegativeFloat, NonNegativeFloat, NonNegativeFloat]) – [units = um]. Size in x, y, and z directions.

  • name (ConstrainedStrValue) – Unique name for monitor.

  • interval_space (Tuple[PositiveInt, PositiveInt, PositiveInt] = (1, 1, 1)) – Number of grid step intervals at which near fields are recorded for projection to the far field, along each direction. If equal to 1, there will be no downsampling. If greater than 1, the step will be applied, but the first and last point of the monitor grid are always included. Using values greater than 1 can help speed up server-side far field projections with minimal accuracy loss, especially in cases where it is necessary for the grid resolution to be high for the FDTD simulation, but such a high resolution is unnecessary for the purpose of projecting the recorded near fields to the far field.

  • colocate (Literal[True] = True) – Defines whether fields are colocated to grid cell boundaries (i.e. to the primal grid) on-the-fly during a solver run. Can be toggled for field recording monitors and is hard-coded for other monitors depending on their specific function.

  • freqs (Union[Tuple[float, ...], ArrayLike[dtype=float, ndim=1]]) – [units = Hz]. Array or list of frequencies stored by the field monitor.

  • apodization (ApodizationSpec = ApodizationSpec(start=None, end=None, width=None, type='ApodizationSpec')) – Sets parameters of (optional) apodization. Apodization applies a windowing function to the Fourier transform of the time-domain fields into frequency-domain ones, and can be used to truncate the beginning and/or end of the time signal, for example to eliminate the source pulse when studying the eigenmodes of a system. Note: apodization affects the normalization of the frequency-domain fields.

  • normal_dir (Optional[Literal['+', '-']] = None) – Direction of the surface monitor’s normal vector w.r.t. the positive x, y or z unit vectors. Must be one of '+' or '-'. Applies to surface monitors only, and defaults to '+' if not provided.

  • exclude_surfaces (Optional[Tuple[Literal['x-', 'x+', 'y-', 'y+', 'z-', 'z+'], ...]] = None) – Surfaces to exclude in the integration, if a volume monitor.

  • custom_origin (Optional[Tuple[float, float, float]] = None) – [units = um]. Local origin used for defining observation points. If None, uses the monitor’s center.

  • far_field_approx (bool = True) – Whether to enable the far field approximation when projecting fields. If True, terms that decay as O(1/r^2) are ignored, as are the radial components of fields. Typically, this should be set to True only when the projection distance is much larger than the size of the device being modeled, and the projected points are in the far field of the device.

  • window_size (Tuple[NonNegativeFloat, NonNegativeFloat] = (0, 0)) – Size of the transition region of the windowing function used to ensure that the recorded near fields decay to zero near the edges of the monitor. The two components refer to the two tangential directions associated with each surface. For surfaces with the normal along x, the two components are (y, z). For surfaces with the normal along y, the two components are (x, z). For surfaces with the normal along z, the two components are (x, y). Each value must be between 0 and 1, inclusive, and denotes the size of the transition region over which fields are scaled to less than a thousandth of the original amplitude, relative to half the size of the monitor in that direction. A value of 0 turns windowing off in that direction, while a value of 1 indicates that the window will be applied to the entire monitor in that direction. This field is applicable for surface monitors only, and otherwise must remain (0, 0).

  • medium (Union[Medium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue, Medium2D] = None) – Medium through which to project fields. Generally, the fields should be projected through the same medium as the one in which this monitor is placed, and this is the default behavior when medium=None. A custom medium can be useful in some situations for advanced users, but we recommend trying to avoid using a non-default medium.

  • proj_axis (Literal[0, 1, 2]) – Axis along which the observation plane is oriented.

  • proj_distance (float = 1000000.0) – [units = um]. Radial distance of the projection points from local_origin.

  • ux (Union[Tuple[float, ...], ArrayLike[dtype=float, ndim=1]]) – Local x component of wave vectors on the observation plane, relative to local_origin and oriented with respect to proj_axis, normalized by (2*pi/lambda) where lambda is the wavelength associated with the background medium. Must be in the range [-1, 1].

  • uy (Union[Tuple[float, ...], ArrayLike[dtype=float, ndim=1]]) – Local y component of wave vectors on the observation plane, relative to local_origin and oriented with respect to proj_axis, normalized by (2*pi/lambda) where lambda is the wavelength associated with the background medium. Must be in the range [-1, 1].

Example

>>> monitor = FieldProjectionKSpaceMonitor(
...     center=(1,2,3),
...     size=(2,2,2),
...     freqs=[250e12, 300e12],
...     name='n2f_monitor',
...     custom_origin=(1,2,3),
...     proj_axis=2,
...     ux=[0.1,0.2],
...     uy=[0.3,0.4,0.5]
...     )
__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.

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.

check_excluded_surfaces(values)

Error if exclude_surfaces is provided for a surface monitor.

construct([_fields_set])

Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.

copy(**kwargs)

Copy a Tidy3dBaseModel.

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.

downsample(arr, axis)

Downsample a 1D array making sure to keep the first and last entries, based on the spatial interval defined for the axis.

downsampled_num_cells(num_cells)

Given a tuple of the number of cells spanned by the monitor along each dimension, return the number of cells one would have after downsampling based on interval_space.

evaluate_inf_shape(shape)

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

from_bounds(rmin, rmax, **kwargs)

Constructs a Box from minimum and maximum coordinate bounds

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 a gdstk.Cell or a gdspy.Cell and extrude it into a GeometryGroup.

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.

intersections_with(other)

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

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.

normal_dir_exists_for_surface(values)

If the monitor is a surface, set default normal_dir if not provided.

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.

reciprocal_vector_range(values)

Ensure that ux, uy are in [-1, 1].

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

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.

storage_size(num_cells, tmesh)

Size of monitor storage given the number of points after discretization.

surface_area([bounds])

Returns object's surface area with optional bounds.

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.

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

volume([bounds])

Returns object's volume with optional bounds.

window_function(points, window_size, ...)

Get the windowing function along a given direction for a given set of points.

window_parameters([custom_bounds])

Return the physical size of the window transition region based on the monitor's size and optional custom bounds (useful in case the monitor has infinite dimensions).

window_size_for_surface(val, values)

Ensures that windowing is applied for surface monitors only.

window_size_leq_one(val, values)

Ensures that each component of the window size is less than or equal to 1.

Attributes

bounding_box

Returns Box representation of the bounding box of a Geometry.

bounds

Returns bounding box min and max coordinates.

frequency_range

Frequency range of the array self.freqs.

geometry

Box representation of monitor.

integration_surfaces

Surfaces of the monitor where fields will be recorded for subsequent integration.

local_origin

Returns the local origin associated with this monitor.

plot_params

Default parameters for plotting a Monitor object.

projection_surfaces

Surfaces of the monitor where near fields will be recorded for subsequent projection.

zero_dims

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

proj_axis

proj_distance

ux

uy

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.

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.

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]

classmethod check_excluded_surfaces(values)#

Error if exclude_surfaces is provided for a surface monitor.

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.

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')
downsample(arr: numpy.ndarray, axis: Literal[0, 1, 2]) → numpy.ndarray#

Downsample a 1D array making sure to keep the first and last entries, based on the spatial interval defined for the axis.

Parameters

  • arr (Numpy) – A 1D array of arbitrary type.

  • axis (Axis) – Axis for which to select the interval_space defined for the monitor.

Returns

Downsampled array.

Return type

Numpy

downsampled_num_cells(num_cells: Tuple[int, int, int]) → Tuple[int, int, int]#

Given a tuple of the number of cells spanned by the monitor along each dimension, return the number of cells one would have after downsampling based on interval_space.

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 frequency_range: Tuple[float, float]#

Frequency range of the array self.freqs.

Returns

Minimum and maximum frequencies of the frequency array.

Return type

Tuple[float, float]

classmethod from_bounds(rmin: Tuple[float, float, float], rmax: Tuple[float, float, float], **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 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')
static 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') → tidy3d.components.geometry.base.Geometry#

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

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: tidy3d.components.geometry.base.Box#

Box representation of monitor.

Returns

Representation of the monitor geometry as a Box.

Return type

Box

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]

property integration_surfaces#

Surfaces of the monitor where fields will be recorded for subsequent integration.

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

Return type

List[shapely.geometry.base.BaseGeometry]

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]

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 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]

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 local_origin: Tuple[float, float, float]#

Returns the local origin associated with this monitor.

classmethod normal_dir_exists_for_surface(values)#

If the monitor is a surface, set default normal_dir if not provided. If the monitor is a box, warn that normal_dir is relevant only for surfaces.

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: tidy3d.components.viz.PlotParams#

Default parameters for plotting a Monitor 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 projection_surfaces: Tuple[tidy3d.components.monitor.FieldProjectionSurface, ...]#

Surfaces of the monitor where near fields will be recorded for subsequent projection.

classmethod reciprocal_vector_range(values)#

Ensure that ux, uy are in [-1, 1].

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

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]

storage_size(num_cells: int, tmesh: tidy3d.components.types.ArrayLike[dtype=float, ndim=1]) → int#

Size of monitor storage given the number of points after discretization.

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

classmethod surfaces(size: Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], center: Tuple[float, float, float], **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: Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], center: Tuple[float, float, float], **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-"]
... )
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')
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')
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.

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

static window_function(points: tidy3d.components.types.ArrayLike[dtype=float, ndim=1], window_size: typing.Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], window_minus: typing.Tuple[float, float, float], window_plus: typing.Tuple[float, float, float], dim: int) → tidy3d.components.types.ArrayLike[dtype=float, ndim=1]#

Get the windowing function along a given direction for a given set of points.

window_parameters(custom_bounds: Optional[Tuple[Tuple[float, float, float], Tuple[float, float, float]]] = None) → Tuple[Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], Tuple[float, float, float], Tuple[float, float, float]]#

Return the physical size of the window transition region based on the monitor’s size and optional custom bounds (useful in case the monitor has infinite dimensions). The window size is returned in 3D. Also returns the coordinate where the transition region beings on the minus and plus side of the monitor.

classmethod window_size_for_surface(val, values)#

Ensures that windowing is applied for surface monitors only.

classmethod window_size_leq_one(val, values)#

Ensures that each component of the window size is less than or equal to 1.

property zero_dims: List[Literal[0, 1, 2]]#

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