tidy3d.CustomFieldSource#

class tidy3d.CustomFieldSource#

Bases: tidy3d.components.source.FieldSource, tidy3d.components.source.PlanarSource

Implements a source corresponding to an input dataset containing E and H fields. For the injection to work as expected, the fields must decay by the edges of the source plane, or the source plane must span the entire simulation domain and the fields must match the simulation boundary conditions. The equivalent source currents are fully defined by the field components tangential to the source plane. The normal components (e.g. Ez and Hz) can be provided but will have no effect on the results, in accordance with the equivalence principle. At least one of the tangential components has to be defined. For example, for a z-normal source, at least one of Ex, Ey, Hx, and Hy has to be present in the provided dataset. The coordinates of all provided fields are assumed to be relative to the source center. Each provided field component must also span the size of the source.

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.
field_dataset (Optional[FieldDataset]) – FieldDataset containing the desired frequency-domain fields patterns to inject. At least one tangetial field component must be specified.

Note

If only the E or only the H fields are provided, the source will not be directional, but will inject equal power in both directions instead.

Example

>>> from tidy3d import ScalarFieldDataArray
>>> pulse = GaussianPulse(freq0=200e12, fwidth=20e12)
>>> x = np.linspace(-1, 1, 101)
>>> y = np.linspace(-1, 1, 101)
>>> z = np.array([0])
>>> f = [2e14]
>>> coords = dict(x=x, y=y, z=z, f=f)
>>> scalar_field = ScalarFieldDataArray(np.ones((101, 101, 1, 1)), coords=coords)
>>> dataset = FieldDataset(Ex=scalar_field)
>>> custom_source = CustomFieldSource(
...     center=(1, 1, 1),
...     size=(2, 2, 0),
...     source_time=pulse,
...     field_dataset=dataset)

Show JSON schema

{
   "title": "CustomFieldSource",
   "description": "Implements a source corresponding to an input dataset containing ``E`` and ``H`` fields.\nFor the injection to work as expected, the fields must decay by the edges of the source plane,\nor the source plane must span the entire simulation domain and the fields must match the\nsimulation boundary conditions. The equivalent source currents are fully defined by the field\ncomponents tangential to the source plane. The normal components (e.g. ``Ez`` and ``Hz``) can be\nprovided but will have no effect on the results, in accordance with the equivalence principle.\nAt least one of the tangential components has to be defined. For example, for a ``z``-normal\nsource, at least one of ``Ex``, ``Ey``, ``Hx``, and ``Hy`` has to be present in the provided\ndataset. The coordinates of all provided fields are assumed to be relative to the source\ncenter. Each provided field component must also span the size of the source.\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.\nfield_dataset : Optional[FieldDataset]\n    :class:`.FieldDataset` containing the desired frequency-domain fields patterns to inject. At least one tangetial field component must be specified.\n\nNote\n----\n    If only the ``E`` or only the ``H`` fields are provided, the source will not be directional,\n    but will inject equal power in both directions instead.\n\nExample\n-------\n>>> from tidy3d import ScalarFieldDataArray\n>>> pulse = GaussianPulse(freq0=200e12, fwidth=20e12)\n>>> x = np.linspace(-1, 1, 101)\n>>> y = np.linspace(-1, 1, 101)\n>>> z = np.array([0])\n>>> f = [2e14]\n>>> coords = dict(x=x, y=y, z=z, f=f)\n>>> scalar_field = ScalarFieldDataArray(np.ones((101, 101, 1, 1)), coords=coords)\n>>> dataset = FieldDataset(Ex=scalar_field)\n>>> custom_source = CustomFieldSource(\n...     center=(1, 1, 1),\n...     size=(2, 2, 0),\n...     source_time=pulse,\n...     field_dataset=dataset)",
   "type": "object",
   "properties": {
      "type": {
         "title": "Type",
         "default": "CustomFieldSource",
         "enum": [
            "CustomFieldSource"
         ],
         "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"
      },
      "field_dataset": {
         "title": "Field Dataset",
         "description": ":class:`.FieldDataset` containing the desired frequency-domain fields patterns to inject. At least one tangetial field component must be specified.",
         "allOf": [
            {
               "$ref": "#/definitions/FieldDataset"
            }
         ]
      }
   },
   "required": [
      "size",
      "source_time",
      "field_dataset"
   ],
   "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
      },
      "FieldDataset": {
         "title": "FieldDataset",
         "description": "Dataset storing a collection of the scalar components of E and H fields in the freq. domain\n\nParameters\n----------\nEx : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the x-component of the electric field.\nEy : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the y-component of the electric field.\nEz : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the z-component of the electric field.\nHx : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the x-component of the magnetic field.\nHy : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the y-component of the magnetic field.\nHz : Optional[ScalarFieldDataArray] = None\n    Spatial distribution of the z-component of the magnetic field.\n\nExample\n-------\n>>> x = [-1,1]\n>>> y = [-2,0,2]\n>>> z = [-3,-1,1,3]\n>>> f = [2e14, 3e14]\n>>> coords = dict(x=x, y=y, z=z, f=f)\n>>> scalar_field = ScalarFieldDataArray((1+1j) * np.random.random((2,3,4,2)), coords=coords)\n>>> data = FieldDataset(Ex=scalar_field, Hz=scalar_field)",
         "type": "object",
         "properties": {
            "type": {
               "title": "Type",
               "default": "FieldDataset",
               "enum": [
                  "FieldDataset"
               ],
               "type": "string"
            },
            "Ex": {
               "title": "DataArray",
               "description": "Spatial distribution of the x-component of the electric field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            },
            "Ey": {
               "title": "DataArray",
               "description": "Spatial distribution of the y-component of the electric field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            },
            "Ez": {
               "title": "DataArray",
               "description": "Spatial distribution of the z-component of the electric field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            },
            "Hx": {
               "title": "DataArray",
               "description": "Spatial distribution of the x-component of the magnetic field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            },
            "Hy": {
               "title": "DataArray",
               "description": "Spatial distribution of the y-component of the magnetic field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            },
            "Hz": {
               "title": "DataArray",
               "description": "Spatial distribution of the z-component of the magnetic field.",
               "type": "xr.DataArray",
               "properties": {
                  "_dims": {
                     "title": "_dims",
                     "type": "Tuple[str, ...]"
                  }
               },
               "required": [
                  "_dims"
               ]
            }
         },
         "additionalProperties": false
      }
   }
}

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

Center of object in x, y, and z.

Validated by

_center_not_inf

attribute field_dataset: Optional[tidy3d.components.data.dataset.FieldDataset] [Required]#

FieldDataset containing the desired frequency-domain fields patterns to inject. At least one tangetial field component must be specified.

Validated by

_single_frequency_in_range
_tangential_component_defined
_tangential_fields_span_source
_warn_if_none

attribute name: str = None#

Optional name for the source.

Validated by

field_has_unique_names

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.

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