tidy3d.plugins.adjoint.JaxSimulation#

class tidy3d.plugins.adjoint.JaxSimulation(*, type: Literal['JaxSimulation'] = 'JaxSimulation', center: Tuple[float, float, float] = (0.0, 0.0, 0.0), size: Tuple[pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat, pydantic.v1.types.NonNegativeFloat], medium: 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] = Medium(name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, heat_spec=None, type='Medium', permittivity=1.0, conductivity=0.0), structures: Tuple[tidy3d.components.structure.Structure, ...] = (), symmetry: Tuple[typing.Literal[0, - 1, 1], typing.Literal[0, - 1, 1], typing.Literal[0, - 1, 1]] = (0, 0, 0), sources: Tuple[Union[tidy3d.components.source.UniformCurrentSource, tidy3d.components.source.PointDipole, tidy3d.components.source.GaussianBeam, tidy3d.components.source.AstigmaticGaussianBeam, tidy3d.components.source.ModeSource, tidy3d.components.source.PlaneWave, tidy3d.components.source.CustomFieldSource, tidy3d.components.source.CustomCurrentSource, tidy3d.components.source.TFSF], ...] = (), boundary_spec: tidy3d.components.boundary.BoundarySpec = BoundarySpec(x=Boundary(plus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), minus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), type='Boundary'), y=Boundary(plus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), minus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), type='Boundary'), z=Boundary(plus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), minus=PML(name=None, type='PML', num_layers=12, parameters=PMLParams(sigma_order=3, sigma_min=0.0, sigma_max=1.5, type='PMLParams', kappa_order=3, kappa_min=1.0, kappa_max=3.0, alpha_order=1, alpha_min=0.0, alpha_max=0.0)), type='Boundary'), type='BoundarySpec'), monitors: Tuple[Union[tidy3d.components.monitor.FieldMonitor, tidy3d.components.monitor.FieldTimeMonitor, tidy3d.components.monitor.PermittivityMonitor, tidy3d.components.monitor.FluxMonitor, tidy3d.components.monitor.FluxTimeMonitor, tidy3d.components.monitor.ModeMonitor, tidy3d.components.monitor.ModeSolverMonitor, tidy3d.components.monitor.FieldProjectionAngleMonitor, tidy3d.components.monitor.FieldProjectionCartesianMonitor, tidy3d.components.monitor.FieldProjectionKSpaceMonitor, tidy3d.components.monitor.DiffractionMonitor], ...] = (), grid_spec: tidy3d.components.grid.grid_spec.GridSpec = GridSpec(grid_x=AutoGrid(type='AutoGrid', min_steps_per_wvl=10.0, max_scale=1.4, dl_min=0.0, mesher=GradedMesher(type='GradedMesher')), grid_y=AutoGrid(type='AutoGrid', min_steps_per_wvl=10.0, max_scale=1.4, dl_min=0.0, mesher=GradedMesher(type='GradedMesher')), grid_z=AutoGrid(type='AutoGrid', min_steps_per_wvl=10.0, max_scale=1.4, dl_min=0.0, mesher=GradedMesher(type='GradedMesher')), wavelength=None, override_structures=(), type='GridSpec'), version: str = '2.5.2', run_time: pydantic.v1.types.PositiveFloat, shutoff: pydantic.v1.types.NonNegativeFloat = 1e-05, subpixel: bool = True, normalize_index: Optional[pydantic.v1.types.NonNegativeInt] = 0, courant: pydantic.v1.types.ConstrainedFloatValue = 0.99, input_structures: Tuple[Union[tidy3d.plugins.adjoint.components.structure.JaxStructure, tidy3d.plugins.adjoint.components.structure.JaxStructureStaticMedium, tidy3d.plugins.adjoint.components.structure.JaxStructureStaticGeometry], ...] = (), output_monitors: Tuple[Union[tidy3d.components.monitor.DiffractionMonitor, tidy3d.components.monitor.FieldMonitor, tidy3d.components.monitor.ModeMonitor], ...] = (), grad_monitors: Tuple[tidy3d.components.monitor.FieldMonitor, ...] = (), grad_eps_monitors: Tuple[tidy3d.components.monitor.PermittivityMonitor, ...] = (), fwidth_adjoint: pydantic.v1.types.PositiveFloat = None, run_time_adjoint: pydantic.v1.types.PositiveFloat = None)#

Bases: tidy3d.components.simulation.Simulation, tidy3d.plugins.adjoint.components.base.JaxObject

A Simulation registered with jax.

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.
medium (Union[Medium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude, FullyAnisotropicMedium, CustomMedium, CustomPoleResidue, CustomSellmeier, CustomLorentz, CustomDebye, CustomDrude, CustomAnisotropicMedium, PerturbationMedium, PerturbationPoleResidue] = Medium(name=None, frequency_range=None, allow_gain=False, nonlinear_spec=None, modulation_spec=None, heat_spec=None, type='Medium', permittivity=1.0, conductivity=0.0)) – Background medium of simulation, defaults to vacuum if not specified.
structures (Tuple[Structure, ...] = ()) – Tuple of structures present in simulation. Note: Structures defined later in this list override the simulation material properties in regions of spatial overlap.
symmetry (Tuple[Literal[0, -1, 1], Literal[0, -1, 1], Literal[0, -1, 1]] = (0, 0, 0)) – Tuple of integers defining reflection symmetry across a plane bisecting the simulation domain normal to the x-, y-, and z-axis at the simulation center of each axis, respectively. Each element can be 0 (no symmetry), 1 (even, i.e. ‘PMC’ symmetry) or -1 (odd, i.e. ‘PEC’ symmetry). Note that the vectorial nature of the fields must be taken into account to correctly determine the symmetry value.
sources (Tuple[Annotated[Union[tidy3d.components.source.UniformCurrentSource, tidy3d.components.source.PointDipole, tidy3d.components.source.GaussianBeam, tidy3d.components.source.AstigmaticGaussianBeam, tidy3d.components.source.ModeSource, tidy3d.components.source.PlaneWave, tidy3d.components.source.CustomFieldSource, tidy3d.components.source.CustomCurrentSource, tidy3d.components.source.TFSF], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – Tuple of electric current sources injecting fields into the simulation.
boundary_spec (BoundarySpec = BoundarySpec(x=Boundary(plus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), y=Boundary(plus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), z=Boundary(plus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, minus=PML(name=None,, type='PML',, num_layers=12,, parameters=PMLParams(sigma_order=3,, sigma_min=0.0,, sigma_max=1.5,, type='PMLParams',, kappa_order=3,, kappa_min=1.0,, kappa_max=3.0,, alpha_order=1,, alpha_min=0.0,, alpha_max=0.0)),, type='Boundary'), type='BoundarySpec')) – Specification of boundary conditions along each dimension. If None, PML boundary conditions are applied on all sides.
monitors (Tuple[Annotated[Union[tidy3d.components.monitor.FieldMonitor, tidy3d.components.monitor.FieldTimeMonitor, tidy3d.components.monitor.PermittivityMonitor, tidy3d.components.monitor.FluxMonitor, tidy3d.components.monitor.FluxTimeMonitor, tidy3d.components.monitor.ModeMonitor, tidy3d.components.monitor.ModeSolverMonitor, tidy3d.components.monitor.FieldProjectionAngleMonitor, tidy3d.components.monitor.FieldProjectionCartesianMonitor, tidy3d.components.monitor.FieldProjectionKSpaceMonitor, tidy3d.components.monitor.DiffractionMonitor], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – Tuple of monitors in the simulation. Note: monitor names are used to access data after simulation is run.
grid_spec (GridSpec = GridSpec(grid_x=AutoGrid(type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(type='GradedMesher')), grid_y=AutoGrid(type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(type='GradedMesher')), grid_z=AutoGrid(type='AutoGrid',, min_steps_per_wvl=10.0,, max_scale=1.4,, dl_min=0.0,, mesher=GradedMesher(type='GradedMesher')), wavelength=None, override_structures=(), type='GridSpec')) – Specifications for the simulation grid along each of the three directions.
version (str = 2.5.2) – String specifying the front end version number.
run_time (PositiveFloat) – [units = sec]. Total electromagnetic evolution time in seconds. Note: If simulation ‘shutoff’ is specified, simulation will terminate early when shutoff condition met.
shutoff (NonNegativeFloat = 1e-05) – Ratio of the instantaneous integrated E-field intensity to the maximum value at which the simulation will automatically terminate time stepping. Used to prevent extraneous run time of simulations with fully decayed fields. Set to 0 to disable this feature.
subpixel (bool = True) – If True, uses subpixel averaging of the permittivity based on structure definition, resulting in much higher accuracy for a given grid size.
normalize_index (Optional[NonNegativeInt] = 0) – Index of the source in the tuple of sources whose spectrum will be used to normalize the frequency-dependent data. If None, the raw field data is returned unnormalized.
courant (ConstrainedFloatValue = 0.99) – Courant stability factor, controls time step to spatial step ratio. Lower values lead to more stable simulations for dispersive materials, but result in longer simulation times. This factor is normalized to no larger than 1 when CFL stability condition is met in 3D.
input_structures (Tuple[Annotated[Union[tidy3d.plugins.adjoint.components.structure.JaxStructure, tidy3d.plugins.adjoint.components.structure.JaxStructureStaticMedium, tidy3d.plugins.adjoint.components.structure.JaxStructureStaticGeometry], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – Tuple of jax-compatible structures that may depend on differentiable parameters.
output_monitors (Tuple[Annotated[Union[tidy3d.components.monitor.DiffractionMonitor, tidy3d.components.monitor.FieldMonitor, tidy3d.components.monitor.ModeMonitor], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...] = ()) – Tuple of monitors whose data the differentiable output depends on.
grad_monitors (Tuple[FieldMonitor, ...] = ()) – Tuple of monitors used for storing fields, used internally for gradients.
grad_eps_monitors (Tuple[PermittivityMonitor, ...] = ()) – Tuple of monitors used for storing epsilon, used internally for gradients.
fwidth_adjoint (Optional[PositiveFloat] = None) – [units = Hz]. Custom frequency width to use for source_time of adjoint sources. If not supplied or None, uses the average fwidth of the original simulation’s sources.
run_time_adjoint (Optional[PositiveFloat] = None) – [units = sec]. Custom run_time to use for adjoint simulation. If not supplied or None, uses a factor times the adjoint source fwidth.

__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.
`bloch_with_symmetry`(val, values)	Error if a Bloch boundary is applied with symmetry
`boundaries_for_zero_dims`(val, values)	Error if absorbing boundaries, unmatching pec/pmc, or symmetry is used along a zero dimension.
`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.
`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.
`diffraction_monitor_boundaries`(val, values)	If any `DiffractionMonitor` exists, ensure boundary conditions in the transverse directions are periodic or Bloch.
`diffraction_monitor_medium`(val, values)	If any `DiffractionMonitor` exists, ensure is does not lie in a lossy medium.
`discretize`(box[, extend])	Grid containing only cells that intersect with a `Box`.
`discretize_monitor`(monitor)	Grid on which monitor data corresponding to a given monitor will be computed.
`eps_bounds`([freq])	Compute range of (real) permittivity present in the simulation at frequency "freq".
`epsilon`(box[, coord_key, freq])	Get array of permittivity at volume specified by box and freq.
`epsilon_on_grid`(grid[, coord_key, freq])	Get array of permittivity at a given freq on a given grid.
`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_scene`(scene, **kwargs)	Create a simulation from a `Scene` instance.
`from_shapely`(shape, axis, slab_bounds[, ...])	Convert a shapely primitive into a geometry instance by extrusion.
`from_simulation`(simulation, jax_info)	Convert `Simulation` to `JaxSimulation` with extra info.
`from_tidy3d`(tidy3d_obj)	Convert `Tidy3dBaseModel` instance to `JaxObject`.
`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_freqs_adjoint`(output_monitors)	Return sorted list of unique frequencies stripped from a collection of monitors.
`get_grad_monitors`(input_structures, ...[, ...])	Return dictionary of gradient monitors for simulation.
`get_jax_field_names`()	Returns list of field names that have a `jax_field_type`.
`get_monitor_by_name`(name)	Return monitor named 'name'.
`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.
`intersecting_media`(test_object, structures)	From a given list of structures, returns a list of `AbstractMedium` associated with those structures that intersect with the `test_object`, if it is a surface, or its surfaces, if it is a volume.
`intersecting_structures`(test_object, structures)	From a given list of structures, returns a list of `Structure` that intersect with the `test_object`, if it is a surface, or its surfaces, if it is a volume.
`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`.
`make_sim_fwd`(simulation, jax_info)	Make the forward `JaxSimulation` from the supplied `Simulation`.
`monitor_medium`(monitor)	Return the medium in which the given monitor resides.
`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.
`perturbed_mediums_copy`([temperature, ...])	Return a copy of the simulation with heat and/or charge data applied to all mediums that have perturbation models specified.
`plane_wave_boundaries`(val, values)	Error if there are plane wave sources incompatible with boundary conditions.
`plot`([x, y, z, ax, source_alpha, ...])	Wrapper around regular `Simulation` structure plotting.
`plot_3d`([width, height])	Render 3D plot of `Simulation` (in jupyter notebook only).
`plot_boundaries`([x, y, z, ax])	Plot the simulation boundary conditions as lines on a plane
`plot_eps`([x, y, z, freq, alpha, ...])	Wrapper around regular `Simulation` permittivity plotting.
`plot_grid`([x, y, z, ax, hlim, vlim])	Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.
`plot_monitors`([x, y, z, hlim, vlim, alpha, ax])	Plot each of simulation's monitors on a plane defined by one nonzero x,y,z coordinate.
`plot_pml`([x, y, z, hlim, vlim, ax])	Plot each of simulation's absorbing boundaries on a plane defined by one nonzero x,y,z coordinate.
`plot_shape`(shape, plot_params, ax)	Defines how a shape is plotted on a matplotlib axes.
`plot_sources`([x, y, z, hlim, vlim, alpha, ax])	Plot each of simulation's sources on a plane defined by one nonzero x,y,z coordinate.
`plot_structures`([x, y, z, ax, hlim, vlim])	Plot each of simulation's structures on a plane defined by one nonzero x,y,z coordinate.
`plot_structures_eps`([x, y, z, freq, alpha, ...])	Plot each of simulation's structures on a plane defined by one nonzero x,y,z coordinate.
`plot_structures_heat_conductivity`([x, y, z, ...])	Plot each of simulation's structures on a plane defined by one nonzero x,y,z coordinate.
`plot_symmetries`([x, y, z, hlim, vlim, ax])	Plot each of simulation's symmetries on a plane defined by one nonzero x,y,z coordinate.
`pop_axis`(coord, axis)	Separates coordinate at `axis` index from coordinates on the plane tangent to `axis`.
`proj_distance_for_approx`(val, values)	Warn if projection distance for projection monitors is not large compared to monitor or, simulation size, yet far_field_approx is True.
`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.
`split_monitors`(monitors, jax_info)	Split monitors into user and adjoint required based on jax info.
`split_structures`(structures, jax_info)	Split structures into regular and input based on jax info.
`store_vjp`(grad_data_fwd, grad_data_adj, ...)	Store the vjp w.r.t.
`store_vjp_parallel`(grad_data_fwd, ...)	Store the vjp w.r.t.
`store_vjp_sequential`(grad_data_fwd, ...)	Store the vjp w.r.t.
`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.
`tfsf_boundaries`(val, values)	Error if the boundary conditions are compatible with TFSF sources, if any.
`tfsf_with_symmetry`(val, values)	Error if a TFSF source is applied with symmetry
`to_file`(fname)	Exports `Tidy3dBaseModel` instance to .yaml, .json, or .hdf5 file
`to_gds`(cell[, x, y, z, ...])	Append the simulation structures to a .gds cell.
`to_gds_file`(fname[, x, y, z, ...])	Append the simulation structures to a .gds cell.
`to_gdspy`([x, y, z, gds_layer_dtype_map])	Convert a simulation's planar slice to a .gds type polygon list.
`to_gdstk`([x, y, z, permittivity_threshold, ...])	Convert a simulation's planar slice to a .gds type polygon list.
`to_hdf5`(fname[, custom_encoders])	Exports `JaxObject` 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_simulation`()	Convert `JaxSimulation` instance to `Simulation` with an info dict.
`to_simulation_fwd`()	Like `to_simulation()` but the gradient monitors are included.
`to_yaml`(fname)	Exports `Tidy3dBaseModel` instance to .yaml file.
`translated`(x, y, z)	Return a translated copy of this geometry.
`tree_flatten`()	How to flatten a `JaxObject` instance into a pytree.
`tree_unflatten`(aux_data, children)	How to unflatten a pytree into a `JaxObject` instance.
`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)
`validate_pre_upload`([source_required])	Validate the fully initialized simulation is ok for upload to our servers.
`volume`([bounds])	Returns object's volume with optional bounds.

Attributes

`allow_gain`	`True` if any of the mediums in the simulation allows gain.
`background_structure`	Returns structure representing the background of the `Simulation`.
`bounding_box`	Returns `Box` representation of the bounding box of a `Geometry`.
`bounds`	Returns bounding box min and max coordinates.
`bounds_pml`	Simulation bounds including the PML regions.
`complex_fields`	Whether complex fields are used in the simulation.
`custom_datasets`	List of custom datasets for verification purposes.
`dt`	Simulation time step (distance).
`freqs_adjoint`	Return sorted list of frequencies stripped from the output monitors.
`frequency_range`	Range of frequencies spanning all sources' frequency dependence.
`geometry`	`Box` representation of self (used for subclasses of Box).
`grid`	FDTD grid spatial locations and information.
`medium_map`	Returns dict mapping medium to index in material.
`mediums`	Returns set of distinct `AbstractMedium` in simulation.
`monitors_data_size`	Dictionary mapping monitor names to their estimated storage size in bytes.
`num_cells`	Number of cells in the simulation.
`num_pml_layers`	Number of absorbing layers in all three axes and directions (-, +).
`num_time_steps`	Number of time steps in simulation.
`nyquist_step`	Maximum number of discrete time steps to keep sampling below Nyquist limit.
`plot_params`	Default parameters for plotting a Geometry object.
`pml_thicknesses`	Thicknesses (um) of absorbers in all three axes and directions (-, +)
`scene`	Scene instance associated with the simulation.
`simulation_bounds`	Simulation bounds including the PML regions.
`simulation_geometry`	The entire simulation domain including auxiliary boundary zones such as PML layers.
`simulation_structure`	Returns structure representing the domain of the simulation.
`tmesh`	FDTD time stepping points.
`volumetric_structures`	Generate a tuple of structures wherein any 2D materials are converted to 3D volumetric equivalents.
`wvl_mat_min`	Minimum wavelength in the material.
`zero_dims`	A list of axes along which the `Box` is zero-sized.
`input_structures`
`output_monitors`
`grad_monitors`
`grad_eps_monitors`
`fwidth_adjoint`
`run_time_adjoint`

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: tidy3d.plugins.adjoint.components.simulation.JaxSimulation) → bool#: Are two JaxSimulation objects equal?

__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 allow_gain: bool#: True if any of the mediums in the simulation allows gain.

property background_structure: tidy3d.components.structure.Structure#: Returns structure representing the background of the Simulation.

classmethod bloch_with_symmetry(val, values)#: Error if a Bloch boundary is applied with symmetry

classmethod boundaries_for_zero_dims(val, values)#: Error if absorbing boundaries, unmatching pec/pmc, or symmetry is used along a zero dimension.

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.

property bounds_pml: Tuple[Tuple[float, float, float], Tuple[float, float, float]]#: Simulation bounds including the PML regions.

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 complex_fields: bool#

Whether complex fields are used in the simulation. Currently this only happens when there are Bloch boundaries.

Returns: Whether the time-stepping fields are real or complex.
Return type: bool

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.

courant: float#: Validating setup

property custom_datasets: List[tidy3d.components.data.dataset.Dataset]#: List of custom datasets for verification purposes. If the list is not empty, then the simulation needs to be exported to hdf5 to store the data.

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 JaxObject 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') 

classmethod diffraction_monitor_boundaries(val, values)#: If any DiffractionMonitor exists, ensure boundary conditions in the transverse directions are periodic or Bloch.

classmethod diffraction_monitor_medium(val, values)#: If any DiffractionMonitor exists, ensure is does not lie in a lossy medium.

discretize(box: tidy3d.components.geometry.base.Box, extend: bool = False) → tidy3d.components.grid.grid.Grid#

Grid containing only cells that intersect with a Box.

Parameters

box (Box) – Rectangular geometry within simulation to discretize.
extend (bool = False) – If True, ensure that the returned indexes extend sufficiently in every direction to be able to interpolate any field component at any point within the box, for field components sampled on the Yee grid.

Returns

The FDTD subgrid containing simulation points that intersect with box.

Return type

Grid

discretize_monitor(monitor: tidy3d.components.monitor.Monitor) → tidy3d.components.grid.grid.Grid#: Grid on which monitor data corresponding to a given monitor will be computed.

property dt: float#

Simulation time step (distance).

Returns: Time step (seconds).
Return type: float

eps_bounds(freq: Optional[float] = None) → Tuple[float, float]#: Compute range of (real) permittivity present in the simulation at frequency “freq”.

epsilon(box: tidy3d.components.geometry.base.Box, coord_key: str = 'centers', freq: Optional[float] = None) → xarray.core.dataarray.DataArray#

Get array of permittivity at volume specified by box and freq.

Parameters

box (Box) – Rectangular geometry specifying where to measure the permittivity.
coord_key (str = 'centers') – Specifies at what part of the grid to return the permittivity at. Accepted values are {'centers', 'boundaries', 'Ex', 'Ey', 'Ez', 'Exy', 'Exz', 'Eyx', 'Eyz', 'Ezx', Ezy'}. The field values (eg. ‘Ex’) correspond to the correponding field locations on the yee lattice. If field values are selected, the corresponding diagonal (eg. eps_xx in case of Ex) or off-diagonal (eg. eps_xy in case of Exy) epsilon component from the epsilon tensor is returned. Otherwise, the average of the main values is returned.
freq (float = None) – The frequency to evaluate the mediums at. If not specified, evaluates at infinite frequency.

Returns

Datastructure containing the relative permittivity values and location coordinates. For details on xarray DataArray objects, refer to xarray’s Documentaton.

Return type

xarray.DataArray

epsilon_on_grid(grid: tidy3d.components.grid.grid.Grid, coord_key: str = 'centers', freq: Optional[float] = None) → xarray.core.dataarray.DataArray#

Get array of permittivity at a given freq on a given grid.

Parameters

grid (Grid) – Grid specifying where to measure the permittivity.
coord_key (str = 'centers') – Specifies at what part of the grid to return the permittivity at. Accepted values are {'centers', 'boundaries', 'Ex', 'Ey', 'Ez', 'Exy', 'Exz', 'Eyx', 'Eyz', 'Ezx', Ezy'}. The field values (eg. ‘Ex’) correspond to the correponding field locations on the yee lattice. If field values are selected, the corresponding diagonal (eg. eps_xx in case of Ex) or off-diagonal (eg. eps_xy in case of Exy) epsilon component from the epsilon tensor is returned. Otherwise, the average of the main values is returned.
freq (float = None) – The frequency to evaluate the mediums at. If not specified, evaluates at infinite frequency.

Returns

Datastructure containing the relative permittivity values and location coordinates. For details on xarray DataArray objects, refer to xarray’s Documentaton.

Return type

xarray.DataArray

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 freqs_adjoint: List[float]#: Return sorted list of frequencies stripped from the output monitors.

property frequency_range: Tuple[float, float]#

Range of frequencies spanning all sources’ frequency dependence.

Returns: Minumum and maximum frequencies of the power spectrum of the sources.
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') 

classmethod from_scene(scene: tidy3d.components.scene.Scene, **kwargs) → tidy3d.components.simulation.Simulation#

Create a simulation from a Scene instance. Must provide additional parameters to define a valid simulation (for example, run_time, grid_spec, etc).

Parameters

scene (Scene) – Size of object in x, y, and z directions.
**kwargs – Other arguments

Example

>>> from tidy3d import Scene, Medium, Box, Structure, GridSpec
>>> box = Structure(
...     geometry=Box(center=(0, 0, 0), size=(1, 2, 3)),
...     medium=Medium(permittivity=5),
... )
>>> scene = Scene(
...     structures=[box],
...     medium=Medium(permittivity=3),
... )
>>> sim = Simulation.from_scene(
...     scene=scene,
...     center=(0, 0, 0),
...     size=(5, 6, 7),
...     run_time=1e-12,
...     grid_spec=GridSpec.uniform(dl=0.4),
... )

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_simulation(simulation: tidy3d.components.simulation.Simulation, jax_info: tidy3d.plugins.adjoint.components.simulation.JaxInfo) → tidy3d.plugins.adjoint.components.simulation.JaxSimulation#: Convert Simulation to JaxSimulation with extra info.

classmethod from_tidy3d(tidy3d_obj: tidy3d.components.base.Tidy3dBaseModel) → tidy3d.plugins.adjoint.components.base.JaxObject#: Convert Tidy3dBaseModel instance to JaxObject.

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#

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

Returns: Instance of Box representing self’s geometry.
Return type: Box

static get_freqs_adjoint(output_monitors: List[tidy3d.components.monitor.Monitor]) → List[float]#: Return sorted list of unique frequencies stripped from a collection of monitors.

static get_grad_monitors(input_structures: List[tidy3d.components.structure.Structure], freqs_adjoint: List[float], include_eps_mnts: bool = True) → dict#: Return dictionary of gradient monitors for simulation.

classmethod get_jax_field_names() → List[str]#: Returns list of field names that have a jax_field_type.

get_monitor_by_name(name: str) → tidy3d.components.base_sim.monitor.AbstractMonitor#: Return monitor named ‘name’.

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.

property grid: tidy3d.components.grid.grid.Grid#

FDTD grid spatial locations and information.

Returns: Grid storing the spatial locations relevant to the simulation.
Return type: Grid

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]

From a given list of structures, returns a list of AbstractMedium associated with those structures that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.

Parameters

test_object (Box) – Object for which intersecting media are to be detected.
structures (List[AbstractMedium]) – List of structures whose media will be tested.

Returns

Set of distinct mediums that intersect with the given planar object.

Return type

List[AbstractMedium]

static intersecting_structures(test_object: tidy3d.components.geometry.base.Box, structures: Tuple[tidy3d.components.structure.Structure, ...]) → Tuple[tidy3d.components.structure.Structure, ...]#

From a given list of structures, returns a list of Structure that intersect with the test_object, if it is a surface, or its surfaces, if it is a volume.

Parameters

test_object (Box) – Object for which intersecting media are to be detected.
structures (List[AbstractMedium]) – List of structures whose media will be tested.

Returns

Set of distinct structures that intersect with the given surface, or with the surfaces of the given volume.

Return type

List[Structure]

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]

classmethod make_sim_fwd(simulation: tidy3d.components.simulation.Simulation, jax_info: tidy3d.plugins.adjoint.components.simulation.JaxInfo) → Tuple[tidy3d.components.simulation.Simulation, tidy3d.plugins.adjoint.components.simulation.JaxInfo]#: Make the forward JaxSimulation from the supplied Simulation.

Returns dict mapping medium to index in material. medium_map[medium] returns unique global index of AbstractMedium in simulation.

Returns: Mapping between distinct mediums to index in simulation.
Return type: Dict[AbstractMedium, int]

Returns set of distinct AbstractMedium in simulation.

Returns: Set of distinct mediums in the simulation.
Return type: List[AbstractMedium]

Return the medium in which the given monitor resides.

Parameters: monitor (Monitor) – Monitor whose associated medium is to be returned.
Returns: Medium associated with the given Monitor.
Return type: AbstractMedium

property monitors_data_size: Dict[str, float]#: Dictionary mapping monitor names to their estimated storage size in bytes.

property num_cells: int#

Number of cells in the simulation.

Returns: Number of yee cells in the simulation.
Return type: int

property num_pml_layers: List[Tuple[float, float]]#

Number of absorbing layers in all three axes and directions (-, +).

Returns: List containing the number of absorber layers in - and + boundaries.
Return type: List[Tuple[float, float]]

property num_time_steps: int#: Number of time steps in simulation.

property nyquist_step: int#

Maximum number of discrete time steps to keep sampling below Nyquist limit.

Returns: The largest N such that N * self.dt is below the Nyquist limit.
Return type: int

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

perturbed_mediums_copy(temperature: Optional[tidy3d.components.data.data_array.SpatialDataArray] = None, electron_density: Optional[tidy3d.components.data.data_array.SpatialDataArray] = None, hole_density: Optional[tidy3d.components.data.data_array.SpatialDataArray] = None, interp_method: Literal['nearest', 'linear'] = 'linear') → tidy3d.components.simulation.Simulation#

Return a copy of the simulation with heat and/or charge data applied to all mediums that have perturbation models specified. That is, such mediums will be replaced with spatially dependent custom mediums that reflect perturbation effects. Any of temperature, electron_density, and hole_density can be None. All provided fields must have identical coords.

Parameters

temperature (SpatialDataArray = None) – Temperature field data.
electron_density (SpatialDataArray = None) – Electron density field data.
hole_density (SpatialDataArray = None) – Hole density field data.
interp_method (InterpMethod, optional) – Interpolation method to obtain heat and/or charge values that are not supplied at the Yee grids.

Returns

Simulation after application of heat and/or charge data.

Return type

Simulation

classmethod plane_wave_boundaries(val, values)#: Error if there are plane wave sources incompatible with boundary conditions.

plot(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, ax: Optional[matplotlib.axes._axes.Axes] = None, source_alpha: Optional[float] = None, monitor_alpha: Optional[float] = None, hlim: Optional[Tuple[float, float]] = None, vlim: Optional[Tuple[float, float]] = None, **patch_kwargs) → matplotlib.axes._axes.Axes#: Wrapper around regular Simulation structure plotting.

plot_3d(width=800, height=800) → None#: Render 3D plot of Simulation (in jupyter notebook only). :param width: width of the 3d view dom’s size :type width: float = 800 :param height: height of the 3d view dom’s size :type height: float = 800

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

Plot the simulation boundary conditions as lines on a plane: defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
**kwargs – Optional keyword arguments passed to the matplotlib LineCollection. For details on accepted values, refer to Matplotlib’s documentation.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_eps(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, freq: Optional[float] = None, alpha: Optional[float] = None, source_alpha: Optional[float] = None, monitor_alpha: Optional[float] = None, hlim: Optional[Tuple[float, float]] = None, vlim: Optional[Tuple[float, float]] = None, ax: Optional[matplotlib.axes._axes.Axes] = None) → matplotlib.axes._axes.Axes#: Wrapper around regular Simulation permittivity plotting.

plot_grid(x: float = None, y: float = None, z: float = None, ax: matplotlib.axes._axes.Axes = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None, **kwargs) → matplotlib.axes._axes.Axes#

Plot the cell boundaries as lines on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
**kwargs –
Optional keyword arguments passed to the matplotlib LineCollection. For details on accepted values, refer to Matplotlib’s documentation.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_monitors(x: float = None, y: float = None, z: float = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None, alpha: float = None, ax: matplotlib.axes._axes.Axes = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s monitors on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
alpha (float = None) – Opacity of the sources, If None uses Tidy3d default.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

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

plot_pml(x: float = None, y: float = None, z: float = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None, ax: matplotlib.axes._axes.Axes = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s absorbing boundaries on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

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.

plot_sources(x: float = None, y: float = None, z: float = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None, alpha: float = None, ax: matplotlib.axes._axes.Axes = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s sources on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
alpha (float = None) – Opacity of the sources, If None uses Tidy3d default.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_structures(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, ax: Optional[matplotlib.axes._axes.Axes] = None, hlim: Optional[Tuple[float, float]] = None, vlim: Optional[Tuple[float, float]] = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s structures on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_structures_eps(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, freq: Optional[float] = None, alpha: Optional[float] = None, cbar: bool = True, reverse: bool = False, ax: Optional[matplotlib.axes._axes.Axes] = None, hlim: Optional[Tuple[float, float]] = None, vlim: Optional[Tuple[float, float]] = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s structures on a plane defined by one nonzero x,y,z coordinate. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
freq (float = None) – Frequency to evaluate the relative permittivity of all mediums. If not specified, evaluates at infinite frequency.
reverse (bool = False) – If False, the highest permittivity is plotted in black. If True, it is plotteed in white (suitable for black backgrounds).
cbar (bool = True) – Whether to plot a colorbar for the relative permittivity.
alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_structures_heat_conductivity(x: float = None, y: float = None, z: float = None, alpha: float = None, cbar: bool = True, reverse: bool = False, ax: matplotlib.axes._axes.Axes = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s structures on a plane defined by one nonzero x,y,z coordinate. The permittivity is plotted in grayscale based on its value at the specified frequency.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
freq (float = None) – Frequency to evaluate the relative permittivity of all mediums. If not specified, evaluates at infinite frequency.
reverse (bool = False) – If False, the highest permittivity is plotted in black. If True, it is plotteed in white (suitable for black backgrounds).
cbar (bool = True) – Whether to plot a colorbar for the relative permittivity.
alpha (float = None) – Opacity of the structures being plotted. Defaults to the structure default alpha.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

plot_symmetries(x: float = None, y: float = None, z: float = None, hlim: Tuple[float, float] = None, vlim: Tuple[float, float] = None, ax: matplotlib.axes._axes.Axes = None) → matplotlib.axes._axes.Axes#

Plot each of simulation’s symmetries on a plane defined by one nonzero x,y,z coordinate.

Parameters

x (float = None) – position of plane in x direction, only one of x, y, z must be specified to define plane.
y (float = None) – position of plane in y direction, only one of x, y, z must be specified to define plane.
z (float = None) – position of plane in z direction, only one of x, y, z must be specified to define plane.
hlim (Tuple[float, float] = None) – The x range if plotting on xy or xz planes, y range if plotting on yz plane.
vlim (Tuple[float, float] = None) – The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

property pml_thicknesses: List[Tuple[float, float]]#

Thicknesses (um) of absorbers in all three axes and directions (-, +)

Returns: List containing the absorber thickness (micron) in - and + boundaries.
Return type: List[Tuple[float, float]]

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]

classmethod proj_distance_for_approx(val, values)#: Warn if projection distance for projection monitors is not large compared to monitor or, simulation size, yet far_field_approx is True.

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

property scene: tidy3d.components.scene.Scene#: Scene instance associated with the simulation.

property simulation_bounds: Tuple[Tuple[float, float, float], Tuple[float, float, float]]#: Simulation bounds including the PML regions.

property simulation_geometry: tidy3d.components.geometry.base.Box#: The entire simulation domain including auxiliary boundary zones such as PML layers. It is identical to Simulation.geometry in the absence of such auxiliary zones.

property simulation_structure: tidy3d.components.structure.Structure#: Returns structure representing the domain of the simulation. This differs from Simulation.scene.background_structure in that it has finite extent.

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]

classmethod split_monitors(monitors: List[tidy3d.components.monitor.Monitor], jax_info: tidy3d.plugins.adjoint.components.simulation.JaxInfo) → Dict[str, tidy3d.components.monitor.Monitor]#: Split monitors into user and adjoint required based on jax info.

classmethod split_structures(structures: List[tidy3d.components.structure.Structure], jax_info: tidy3d.plugins.adjoint.components.simulation.JaxInfo) → Dict[str, tidy3d.components.structure.Structure]#: Split structures into regular and input based on jax info.

store_vjp(grad_data_fwd: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_data_adj: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_eps_data: Tuple[tidy3d.components.data.monitor_data.PermittivityData], num_proc: int = 1) → tidy3d.plugins.adjoint.components.simulation.JaxSimulation#: Store the vjp w.r.t. each input_structure as a sim using fwd and adj grad_data.

store_vjp_parallel(grad_data_fwd: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_data_adj: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_eps_data: Tuple[tidy3d.components.data.monitor_data.PermittivityData], num_proc: int) → tidy3d.plugins.adjoint.components.simulation.JaxSimulation#: Store the vjp w.r.t. each input_structure as a sim using fwd and adj grad_data, and parallel processing over num_proc processes.

store_vjp_sequential(grad_data_fwd: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_data_adj: Tuple[tidy3d.components.data.monitor_data.FieldData], grad_eps_data: Tuple[tidy3d.components.data.monitor_data.PermittivityData]) → tidy3d.plugins.adjoint.components.simulation.JaxSimulation#: Store the vjp w.r.t. each input_structure without multiprocessing.

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

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

classmethod tfsf_boundaries(val, values)#: Error if the boundary conditions are compatible with TFSF sources, if any.

classmethod tfsf_with_symmetry(val, values)#: Error if a TFSF source is applied with symmetry

property tmesh: tidy3d.components.types.ArrayLike[dtype=float, ndim=1]#

FDTD time stepping points.

Returns: Times (seconds) that the simulation time steps through.
Return type: np.ndarray

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, permittivity_threshold: pydantic.v1.types.NonNegativeFloat = 1, frequency: pydantic.v1.types.PositiveFloat = 0, gds_layer_dtype_map: Optional[Dict[tidy3d.components.medium.AbstractMedium, Tuple[pydantic.v1.types.NonNegativeInt, pydantic.v1.types.NonNegativeInt]]] = None) → None#

Append the simulation structures 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.
permittivity_threshold (float = 1.001) – Permitivitty value used to define the shape boundaries for structures with custom medim
frequency (float = 0) – Frequency for permittivity evaluaiton in case of custom medium (Hz).
gds_layer_dtype_map (Dict) – Dictionary mapping mediums to GDSII layer and data type tuples.

to_gds_file(fname: str, x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, permittivity_threshold: pydantic.v1.types.NonNegativeFloat = 1, frequency: pydantic.v1.types.PositiveFloat = 0, gds_layer_dtype_map: Optional[Dict[tidy3d.components.medium.AbstractMedium, Tuple[pydantic.v1.types.NonNegativeInt, pydantic.v1.types.NonNegativeInt]]] = None, gds_cell_name: str = 'MAIN') → None#

Append the simulation structures to a .gds cell.

Parameters

fname (str) – Full path to the .gds file to save the Simulation 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.
permittivity_threshold (float = 1.001) – Permitivitty value used to define the shape boundaries for structures with custom medim
frequency (float = 0) – Frequency for permittivity evaluaiton in case of custom medium (Hz).
gds_layer_dtype_map (Dict) – Dictionary mapping mediums to GDSII layer and data type tuples.
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_dtype_map: Optional[Dict[tidy3d.components.medium.AbstractMedium, Tuple[pydantic.v1.types.NonNegativeInt, pydantic.v1.types.NonNegativeInt]]] = None) → List#

Convert a simulation’s planar slice to a .gds type polygon list.

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_dtype_map (Dict) – Dictionary mapping mediums to GDSII layer and data type tuples.

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, permittivity_threshold: pydantic.v1.types.NonNegativeFloat = 1, frequency: pydantic.v1.types.PositiveFloat = 0, gds_layer_dtype_map: Optional[Dict[tidy3d.components.medium.AbstractMedium, Tuple[pydantic.v1.types.NonNegativeInt, pydantic.v1.types.NonNegativeInt]]] = None) → List#

Convert a simulation’s planar slice to a .gds type polygon list.

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.
permittivity_threshold (float = 1.001) – Permitivitty value used to define the shape boundaries for structures with custom medim
frequency (float = 0) – Frequency for permittivity evaluaiton in case of custom medium (Hz).
gds_layer_dtype_map (Dict) – Dictionary mapping mediums to GDSII layer and data type tuples.

Returns

List of gdstk.Polygon.

Return type

List

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

Exports JaxObject instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to save the JaxObject 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_simulation() → Tuple[tidy3d.components.simulation.Simulation, tidy3d.plugins.adjoint.components.simulation.JaxInfo]#: Convert JaxSimulation instance to Simulation with an info dict.

to_simulation_fwd() → Tuple[tidy3d.components.simulation.Simulation, tidy3d.plugins.adjoint.components.simulation.JaxInfo, tidy3d.plugins.adjoint.components.simulation.JaxInfo]#: Like to_simulation() but the gradient monitors are included.

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

tree_flatten() → Tuple[list, dict]#: How to flatten a JaxObject instance into a pytree.

classmethod tree_unflatten(aux_data: dict, children: list) → tidy3d.plugins.adjoint.components.base.JaxObject#: How to unflatten a pytree into a JaxObject instance.

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.

validate_pre_upload(source_required: bool = True) → None#

Validate the fully initialized simulation is ok for upload to our servers.

Parameters: source_required (bool = True) – If True, validation will fail in case no sources are found in the simulation.

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 volumetric_structures: Tuple[tidy3d.components.structure.Structure]#: Generate a tuple of structures wherein any 2D materials are converted to 3D volumetric equivalents.

property wvl_mat_min: float#

Minimum wavelength in the material.

Returns: Minimum wavelength in the material (microns).
Return type: float

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