tidy3d.GaussianBeam#

class tidy3d.GaussianBeam#

Bases: tidy3d.components.source.AngledFieldSource, tidy3d.components.source.PlanarSource, tidy3d.components.source.BroadbandSource

Guassian distribution on finite extent plane.

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.

  • source_time (Union[GaussianPulse, ContinuousWave]) – Specification of the source time-dependence.

  • name (Optional[str] = None) – Optional name for the source.

  • num_freqs (ConstrainedIntValue = 1) – Number of points used to approximate the frequency dependence of injected field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less than 20, is typically sufficient to obtain converged results.

  • direction (Literal['+', '-']) – Specifies propagation in the positive or negative direction of the injection axis.

  • angle_theta (float = 0.0) – [units = rad]. Polar angle of the propagation axis from the injection axis.

  • angle_phi (float = 0.0) – [units = rad]. Azimuth angle of the propagation axis in the plane orthogonal to the injection axis.

  • pol_angle (float = 0) – [units = rad]. Specifies the angle between the electric field polarization of the source and the plane defined by the injection axis and the propagation axis (rad). pol_angle=0 (default) specifies P polarization, while pol_angle=np.pi/2 specifies S polarization. At normal incidence when S and P are undefined, pol_angle=0 defines: - Ey polarization for propagation along x.- Ex polarization for propagation along y.- Ex polarization for propagation along z.

  • waist_radius (PositiveFloat = 1.0) – [units = um]. Radius of the beam at the waist.

  • waist_distance (float = 0.0) – [units = um]. Distance from the beam waist along the propagation direction.

Example

>>> pulse = GaussianPulse(freq0=200e12, fwidth=20e12)
>>> gauss = GaussianBeam(
...     size=(0,3,3),
...     source_time=pulse,
...     pol_angle=np.pi / 2,
...     direction='+',
...     waist_radius=1.0)

Show JSON schema
{
   "title": "GaussianBeam",
   "description": "Guassian distribution on finite extent plane.\n\nParameters\n----------\ncenter : Tuple[float, float, float] = (0.0, 0.0, 0.0)\n    [units = um].  Center of object in x, y, and z.\nsize : Tuple[NonNegativeFloat, NonNegativeFloat, NonNegativeFloat]\n    [units = um].  Size in x, y, and z directions.\nsource_time : Union[GaussianPulse, ContinuousWave]\n    Specification of the source time-dependence.\nname : Optional[str] = None\n    Optional name for the source.\nnum_freqs : ConstrainedIntValue = 1\n    Number of points used to approximate the frequency dependence of injected field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less than 20, is typically sufficient to obtain converged results.\ndirection : Literal['+', '-']\n    Specifies propagation in the positive or negative direction of the injection axis.\nangle_theta : float = 0.0\n    [units = rad].  Polar angle of the propagation axis from the injection axis.\nangle_phi : float = 0.0\n    [units = rad].  Azimuth angle of the propagation axis in the plane orthogonal to the injection axis.\npol_angle : float = 0\n    [units = rad].  Specifies the angle between the electric field polarization of the source and the plane defined by the injection axis and the propagation axis (rad). ``pol_angle=0`` (default) specifies P polarization, while ``pol_angle=np.pi/2`` specifies S polarization. At normal incidence when S and P are undefined, ``pol_angle=0`` defines: - ``Ey`` polarization for propagation along ``x``.- ``Ex`` polarization for propagation along ``y``.- ``Ex`` polarization for propagation along ``z``.\nwaist_radius : PositiveFloat = 1.0\n    [units = um].  Radius of the beam at the waist.\nwaist_distance : float = 0.0\n    [units = um].  Distance from the beam waist along the propagation direction.\n\nExample\n-------\n>>> pulse = GaussianPulse(freq0=200e12, fwidth=20e12)\n>>> gauss = GaussianBeam(\n...     size=(0,3,3),\n...     source_time=pulse,\n...     pol_angle=np.pi / 2,\n...     direction='+',\n...     waist_radius=1.0)",
   "type": "object",
   "properties": {
      "type": {
         "title": "Type",
         "default": "GaussianBeam",
         "enum": [
            "GaussianBeam"
         ],
         "type": "string"
      },
      "center": {
         "title": "Center",
         "description": "Center of object in x, y, and z.",
         "default": [
            0.0,
            0.0,
            0.0
         ],
         "units": "um",
         "type": "array",
         "minItems": 3,
         "maxItems": 3,
         "items": [
            {
               "type": "number"
            },
            {
               "type": "number"
            },
            {
               "type": "number"
            }
         ]
      },
      "size": {
         "title": "Size",
         "description": "Size in x, y, and z directions.",
         "units": "um",
         "type": "array",
         "minItems": 3,
         "maxItems": 3,
         "items": [
            {
               "type": "number",
               "minimum": 0
            },
            {
               "type": "number",
               "minimum": 0
            },
            {
               "type": "number",
               "minimum": 0
            }
         ]
      },
      "source_time": {
         "title": "Source Time",
         "description": "Specification of the source time-dependence.",
         "anyOf": [
            {
               "$ref": "#/definitions/GaussianPulse"
            },
            {
               "$ref": "#/definitions/ContinuousWave"
            }
         ]
      },
      "name": {
         "title": "Name",
         "description": "Optional name for the source.",
         "type": "string"
      },
      "num_freqs": {
         "title": "Number of Frequency Points",
         "description": "Number of points used to approximate the frequency dependence of injected field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less than 20, is typically sufficient to obtain converged results.",
         "default": 1,
         "minimum": 1,
         "maximum": 99,
         "type": "integer"
      },
      "direction": {
         "title": "Direction",
         "description": "Specifies propagation in the positive or negative direction of the injection axis.",
         "enum": [
            "+",
            "-"
         ],
         "type": "string"
      },
      "angle_theta": {
         "title": "Polar Angle",
         "description": "Polar angle of the propagation axis from the injection axis.",
         "default": 0.0,
         "units": "rad",
         "type": "number"
      },
      "angle_phi": {
         "title": "Azimuth Angle",
         "description": "Azimuth angle of the propagation axis in the plane orthogonal to the injection axis.",
         "default": 0.0,
         "units": "rad",
         "type": "number"
      },
      "pol_angle": {
         "title": "Polarization Angle",
         "description": "Specifies the angle between the electric field polarization of the source and the plane defined by the injection axis and the propagation axis (rad). ``pol_angle=0`` (default) specifies P polarization, while ``pol_angle=np.pi/2`` specifies S polarization. At normal incidence when S and P are undefined, ``pol_angle=0`` defines: - ``Ey`` polarization for propagation along ``x``.- ``Ex`` polarization for propagation along ``y``.- ``Ex`` polarization for propagation along ``z``.",
         "default": 0,
         "units": "rad",
         "type": "number"
      },
      "waist_radius": {
         "title": "Waist Radius",
         "description": "Radius of the beam at the waist.",
         "default": 1.0,
         "units": "um",
         "exclusiveMinimum": 0,
         "type": "number"
      },
      "waist_distance": {
         "title": "Waist Distance",
         "description": "Distance from the beam waist along the propagation direction.",
         "default": 0.0,
         "units": "um",
         "type": "number"
      }
   },
   "required": [
      "size",
      "source_time",
      "direction"
   ],
   "additionalProperties": false,
   "definitions": {
      "GaussianPulse": {
         "title": "GaussianPulse",
         "description": "Source time dependence that describes a Gaussian pulse.\n\nParameters\n----------\namplitude : NonNegativeFloat = 1.0\n    Real-valued maximum amplitude of the time dependence.\nphase : float = 0.0\n    [units = rad].  Phase shift of the time dependence.\nfreq0 : PositiveFloat\n    [units = Hz].  Central frequency of the pulse.\nfwidth : PositiveFloat\n    [units = Hz].  Standard deviation of the frequency content of the pulse.\noffset : ConstrainedFloatValue = 5.0\n    Time delay of the maximum value of the pulse in units of 1 / (``2pi * fwidth``).\n\nExample\n-------\n>>> pulse = GaussianPulse(freq0=200e12, fwidth=20e12)",
         "type": "object",
         "properties": {
            "amplitude": {
               "title": "Amplitude",
               "description": "Real-valued maximum amplitude of the time dependence.",
               "default": 1.0,
               "minimum": 0,
               "type": "number"
            },
            "phase": {
               "title": "Phase",
               "description": "Phase shift of the time dependence.",
               "default": 0.0,
               "units": "rad",
               "type": "number"
            },
            "type": {
               "title": "Type",
               "default": "GaussianPulse",
               "enum": [
                  "GaussianPulse"
               ],
               "type": "string"
            },
            "freq0": {
               "title": "Central Frequency",
               "description": "Central frequency of the pulse.",
               "units": "Hz",
               "exclusiveMinimum": 0,
               "type": "number"
            },
            "fwidth": {
               "title": "Fwidth",
               "description": "Standard deviation of the frequency content of the pulse.",
               "units": "Hz",
               "exclusiveMinimum": 0,
               "type": "number"
            },
            "offset": {
               "title": "Offset",
               "description": "Time delay of the maximum value of the pulse in units of 1 / (``2pi * fwidth``).",
               "default": 5.0,
               "minimum": 2.5,
               "type": "number"
            }
         },
         "required": [
            "freq0",
            "fwidth"
         ],
         "additionalProperties": false
      },
      "ContinuousWave": {
         "title": "ContinuousWave",
         "description": "Source time dependence that ramps up to continuous oscillation\nand holds until end of simulation.\n\nParameters\n----------\namplitude : NonNegativeFloat = 1.0\n    Real-valued maximum amplitude of the time dependence.\nphase : float = 0.0\n    [units = rad].  Phase shift of the time dependence.\nfreq0 : PositiveFloat\n    [units = Hz].  Central frequency of the pulse.\nfwidth : PositiveFloat\n    [units = Hz].  Standard deviation of the frequency content of the pulse.\noffset : ConstrainedFloatValue = 5.0\n    Time delay of the maximum value of the pulse in units of 1 / (``2pi * fwidth``).\n\nExample\n-------\n>>> cw = ContinuousWave(freq0=200e12, fwidth=20e12)",
         "type": "object",
         "properties": {
            "amplitude": {
               "title": "Amplitude",
               "description": "Real-valued maximum amplitude of the time dependence.",
               "default": 1.0,
               "minimum": 0,
               "type": "number"
            },
            "phase": {
               "title": "Phase",
               "description": "Phase shift of the time dependence.",
               "default": 0.0,
               "units": "rad",
               "type": "number"
            },
            "type": {
               "title": "Type",
               "default": "ContinuousWave",
               "enum": [
                  "ContinuousWave"
               ],
               "type": "string"
            },
            "freq0": {
               "title": "Central Frequency",
               "description": "Central frequency of the pulse.",
               "units": "Hz",
               "exclusiveMinimum": 0,
               "type": "number"
            },
            "fwidth": {
               "title": "Fwidth",
               "description": "Standard deviation of the frequency content of the pulse.",
               "units": "Hz",
               "exclusiveMinimum": 0,
               "type": "number"
            },
            "offset": {
               "title": "Offset",
               "description": "Time delay of the maximum value of the pulse in units of 1 / (``2pi * fwidth``).",
               "default": 5.0,
               "minimum": 2.5,
               "type": "number"
            }
         },
         "required": [
            "freq0",
            "fwidth"
         ],
         "additionalProperties": false
      }
   }
}

attribute angle_phi: float = 0.0#

Azimuth angle of the propagation axis in the plane orthogonal to the injection axis.

attribute angle_theta: float = 0.0#

Polar angle of the propagation axis from the injection axis.

Validated by

  • glancing_incidence

attribute center: Coordinate = (0.0, 0.0, 0.0)#

Center of object in x, y, and z.

Validated by

  • _center_not_inf

attribute direction: Direction [Required]#

Specifies propagation in the positive or negative direction of the injection axis.

attribute name: str = None#

Optional name for the source.

Validated by

  • field_has_unique_names

attribute num_freqs: int = 1#

Number of points used to approximate the frequency dependence of injected field. A Chebyshev interpolation is used, thus, only a small number of points, i.e., less than 20, is typically sufficient to obtain converged results.

Constraints

  • minimum = 1

  • maximum = 99

Validated by

  • _warn_if_large_number_of_freqs

attribute pol_angle: float = 0#

Specifies the angle between the electric field polarization of the source and the plane defined by the injection axis and the propagation axis (rad). pol_angle=0 (default) specifies P polarization, while pol_angle=np.pi/2 specifies S polarization. At normal incidence when S and P are undefined, pol_angle=0 defines: - Ey polarization for propagation along x.- Ex polarization for propagation along y.- Ex polarization for propagation along z.

attribute size: Size [Required]#

Size in x, y, and z directions.

Validated by

  • is_plane

attribute source_time: SourceTimeType [Required]#

Specification of the source time-dependence.

attribute waist_distance: float = 0.0#

Distance from the beam waist along the propagation direction.

attribute waist_radius: pydantic.types.PositiveFloat = 1.0#

Radius of the beam at the waist.

Constraints

  • exclusiveMinimum = 0

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

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

Parameters

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

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

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

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

classmethod add_type_field() → None#

Automatically place “type” field with model name in the model field dictionary.

static 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 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, or .hdf5 file.

Parameters

  • fname (str) – Full path to the .yaml or .json 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 = '') → 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.

Returns

Dictionary containing the model.

Return type

dict

Example

>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5')
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 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.

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, or .hdf5 file.

Parameters

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

  • group_path (str, optional) – Path to a group inside the file to use as the base level. Only for .hdf5 files. Starting / is optional.

  • **parse_obj_kwargs – Keyword arguments passed to either pydantic’s parse_obj function when loading model.

Returns

An instance of the component class calling load.

Return type

Tidy3dBaseModel

Example

>>> simulation = Simulation.from_file(fname='folder/sim.json')
classmethod from_hdf5(fname: str, group_path: str = '', **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.

  • **parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation.to_hdf5(fname='folder/sim.hdf5')
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_orm(obj: Any) → Model#
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.

classmethod get_sub_model(group_path: str, model_dict: dict | list) → dict#

Get the sub model for a given group path.

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, y, z) → bool#

Returns True if point (x,y,z) inside volume of geometry.

Parameters

  • x (float) – Position of point in x direction.

  • y (float) – Position of point in y direction.

  • z (float) – Position of point in z direction.

Returns

Whether point (x,y,z) is inside geometry.

Return type

bool

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

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_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) → unicode#

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]

classmethod map_to_coords(func: Callable[[float], float], shape: shapely.geometry.base.BaseGeometry) → shapely.geometry.base.BaseGeometry#

Maps a function to each coordinate in shape.

Parameters

  • func (Callable[[float], float]) – Takes old coordinate and returns new coordinate.

  • shape (shapely.geometry.base.BaseGeometry) – The shape to map this function to.

Returns

A new copy of the input shape with the mapping applied to the coordinates.

Return type

shapely.geometry.base.BaseGeometry

classmethod parse_file(path: Union[str, pathlib.Path], *, content_type: unicode = None, encoding: unicode = 'utf8', proto: pydantic.parse.Protocol = None, allow_pickle: bool = False) → Model#
classmethod parse_obj(obj: Any) → Model#
classmethod parse_raw(b: Union[str, bytes], *, content_type: unicode = None, encoding: unicode = 'utf8', proto: pydantic.parse.Protocol = None, allow_pickle: bool = False) → Model#
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: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, ax: Optional[matplotlib.axes._axes.Axes] = None, sim_bounds: Optional[Tuple[Tuple[float, float, float], Tuple[float, float, float]]] = 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

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]

reflect_points(points: tidy3d.components.types.Array, polar_axis: Literal[0, 1, 2], angle_theta: float, angle_phi: float) → tidy3d.components.types.Array#

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.Array, axis: Tuple[float, float, float], angle: float) → tidy3d.components.types.Array#

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

classmethod schema(by_alias: bool = True, ref_template: unicode = '#/definitions/{model}') → DictStrAny#
classmethod schema_json(*, by_alias: bool = True, ref_template: unicode = '#/definitions/{model}', **dumps_kwargs: Any) → unicode#
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 strip_coords(shape: shapely.geometry.base.BaseGeometry) → Tuple[List[float], List[float], Tuple[List[float], List[float]]]#

Get the exterior and list of interior xy coords for a shape.

Parameters

shape (shapely.geometry.base.BaseGeometry) – The shape that you want to strip coordinates from.

Returns

List of exterior xy coordinates and a list of lists of the interior xy coordinates of the “holes” in the shape.

Return type

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

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.

Return type

float

classmethod surfaces(size: Tuple[pydantic.types.NonNegativeFloat, pydantic.types.NonNegativeFloat, pydantic.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))
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_hdf5(fname: str) → None#

Exports Tidy3dBaseModel instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to save the Tidy3dBaseModel to.

Example

>>> simulation.to_hdf5(fname='folder/sim.hdf5')
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')
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.

classmethod validate(value: Any) → Model#
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.

Return type

float

property bounding_box#

Returns Box representation of the bounding box of a Geometry.

Returns

Geometric object representing bounding box.

Return type

Box

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

Returns bounding box min and max coordinates.

Returns

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

Return type

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

property frequency_grid: numpy.ndarray#

A Chebyshev grid used to approximate frequency dependence.

property geometry: tidy3d.components.geometry.Box#

Box representation of source.

property injection_axis#

Injection axis of the source.

property plot_params: tidy3d.components.viz.PlotParams#

Default parameters for plotting a Source object.

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

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