tidy3d.Structure
tidy3d.Structure#
- class tidy3d.Structure#
Bases:
tidy3d.components.structure.AbstractStructureDefines a physical object that interacts with the electromagnetic fields. A
Structureis a combination of a material property (AbstractMedium) and aGeometry.- Parameters
geometry (Union[Box, Sphere, Cylinder, PolySlab, GeometryGroup]) – Defines geometric properties of the structure.
name (Optional[str] = None) – Optional name for the structure.
medium (Union[Medium, CustomMedium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude]) – Defines the electromagnetic properties of the structure’s medium.
Example
>>> from tidy3d import Box, Medium >>> box = Box(center=(0,0,1), size=(2, 2, 2)) >>> glass = Medium(permittivity=3.9) >>> struct = Structure(geometry=box, medium=glass, name='glass_box')
Show JSON schema
{ "title": "Structure", "description": "Defines a physical object that interacts with the electromagnetic fields.\nA :class:`Structure` is a combination of a material property (:class:`AbstractMedium`)\nand a :class:`Geometry`.\n\nParameters\n----------\ngeometry : Union[Box, Sphere, Cylinder, PolySlab, GeometryGroup]\n Defines geometric properties of the structure.\nname : Optional[str] = None\n Optional name for the structure.\nmedium : Union[Medium, CustomMedium, AnisotropicMedium, PECMedium, PoleResidue, Sellmeier, Lorentz, Debye, Drude]\n Defines the electromagnetic properties of the structure's medium.\n\nExample\n-------\n>>> from tidy3d import Box, Medium\n>>> box = Box(center=(0,0,1), size=(2, 2, 2))\n>>> glass = Medium(permittivity=3.9)\n>>> struct = Structure(geometry=box, medium=glass, name='glass_box')", "type": "object", "properties": { "geometry": { "title": "Geometry", "description": "Defines geometric properties of the structure.", "discriminator": { "propertyName": "type", "mapping": { "Box": "#/definitions/Box", "Sphere": "#/definitions/Sphere", "Cylinder": "#/definitions/Cylinder", "PolySlab": "#/definitions/PolySlab", "GeometryGroup": "#/definitions/GeometryGroup" } }, "oneOf": [ { "$ref": "#/definitions/Box" }, { "$ref": "#/definitions/Sphere" }, { "$ref": "#/definitions/Cylinder" }, { "$ref": "#/definitions/PolySlab" }, { "$ref": "#/definitions/GeometryGroup" } ] }, "name": { "title": "Name", "description": "Optional name for the structure.", "type": "string" }, "type": { "title": "Type", "default": "Structure", "enum": [ "Structure" ], "type": "string" }, "medium": { "title": "Medium", "description": "Defines the electromagnetic properties of the structure's medium.", "discriminator": { "propertyName": "type", "mapping": { "Medium": "#/definitions/Medium", "CustomMedium": "#/definitions/CustomMedium", "AnisotropicMedium": "#/definitions/AnisotropicMedium", "PECMedium": "#/definitions/PECMedium", "PoleResidue": "#/definitions/PoleResidue", "Sellmeier": "#/definitions/Sellmeier", "Lorentz": "#/definitions/Lorentz", "Debye": "#/definitions/Debye", "Drude": "#/definitions/Drude" } }, "oneOf": [ { "$ref": "#/definitions/Medium" }, { "$ref": "#/definitions/CustomMedium" }, { "$ref": "#/definitions/AnisotropicMedium" }, { "$ref": "#/definitions/PECMedium" }, { "$ref": "#/definitions/PoleResidue" }, { "$ref": "#/definitions/Sellmeier" }, { "$ref": "#/definitions/Lorentz" }, { "$ref": "#/definitions/Debye" }, { "$ref": "#/definitions/Drude" } ] } }, "required": [ "geometry", "medium" ], "additionalProperties": false, "definitions": { "Box": { "title": "Box", "description": "Rectangular prism.\n Also base class for :class:`Simulation`, :class:`Monitor`, and :class:`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.\n\nExample\n-------\n>>> b = Box(center=(1,2,3), size=(2,2,2))", "type": "object", "properties": { "type": { "title": "Type", "default": "Box", "enum": [ "Box" ], "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 } ] } }, "required": [ "size" ], "additionalProperties": false }, "Sphere": { "title": "Sphere", "description": "Spherical geometry.\n\nParameters\n----------\nradius : NonNegativeFloat\n [units = um]. Radius of geometry.\ncenter : Tuple[float, float, float] = (0.0, 0.0, 0.0)\n [units = um]. Center of object in x, y, and z.\n\nExample\n-------\n>>> b = Sphere(center=(1,2,3), radius=2)", "type": "object", "properties": { "type": { "title": "Type", "default": "Sphere", "enum": [ "Sphere" ], "type": "string" }, "radius": { "title": "Radius", "description": "Radius of geometry.", "units": "um", "minimum": 0, "type": "number" }, "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" } ] } }, "required": [ "radius" ], "additionalProperties": false }, "Cylinder": { "title": "Cylinder", "description": "Cylindrical geometry with optional sidewall angle along axis\ndirection. When ``sidewall_angle`` is nonzero, the shape is a\nconical frustum or a cone.\n\nParameters\n----------\naxis : Literal[0, 1, 2] = 2\n Specifies dimension of the planar axis (0,1,2) -> (x,y,z).\nsidewall_angle : ConstrainedFloatValue = 0.0\n [units = rad]. Angle of the sidewall. ``sidewall_angle=0`` (default) specifies a vertical wall; ``0<sidewall_angle<np.pi/2`` specifies a shrinking cross section along the ``axis`` direction; and ``-np.pi/2<sidewall_angle<0`` specifies an expanding cross section along the ``axis`` direction.\nreference_plane : Literal['bottom', 'middle', 'top'] = bottom\n The position of the plane where the supplied cross section are defined. The plane is perpendicular to the ``axis``. The plane is located at the ``bottom``, ``middle``, or ``top`` of the geometry with respect to the axis. E.g. if ``axis=1``, ``bottom`` refers to the negative side of the y-axis, and ``top`` refers to the positive side of the y-axis.\nradius : NonNegativeFloat\n [units = um]. Radius of geometry.\ncenter : Tuple[float, float, float] = (0.0, 0.0, 0.0)\n [units = um]. Center of object in x, y, and z.\nlength : NonNegativeFloat\n [units = um]. Defines thickness of cylinder along axis dimension.\n\nExample\n-------\n>>> c = Cylinder(center=(1,2,3), radius=2, length=5, axis=2)", "type": "object", "properties": { "type": { "title": "Type", "default": "Cylinder", "enum": [ "Cylinder" ], "type": "string" }, "axis": { "title": "Axis", "description": "Specifies dimension of the planar axis (0,1,2) -> (x,y,z).", "default": 2, "enum": [ 0, 1, 2 ], "type": "integer" }, "sidewall_angle": { "title": "Sidewall angle", "description": "Angle of the sidewall. ``sidewall_angle=0`` (default) specifies a vertical wall; ``0<sidewall_angle<np.pi/2`` specifies a shrinking cross section along the ``axis`` direction; and ``-np.pi/2<sidewall_angle<0`` specifies an expanding cross section along the ``axis`` direction.", "default": 0.0, "exclusiveMinimum": -1.5707963267948966, "exclusiveMaximum": 1.5707963267948966, "units": "rad", "type": "number" }, "reference_plane": { "title": "Reference plane for cross section", "description": "The position of the plane where the supplied cross section are defined. The plane is perpendicular to the ``axis``. The plane is located at the ``bottom``, ``middle``, or ``top`` of the geometry with respect to the axis. E.g. if ``axis=1``, ``bottom`` refers to the negative side of the y-axis, and ``top`` refers to the positive side of the y-axis.", "default": "bottom", "enum": [ "bottom", "middle", "top" ], "type": "string" }, "radius": { "title": "Radius", "description": "Radius of geometry.", "units": "um", "minimum": 0, "type": "number" }, "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" } ] }, "length": { "title": "Length", "description": "Defines thickness of cylinder along axis dimension.", "units": "um", "minimum": 0, "type": "number" } }, "required": [ "radius", "length" ], "additionalProperties": false }, "PolySlab": { "title": "PolySlab", "description": "Polygon extruded with optional sidewall angle along axis direction.\n\nParameters\n----------\naxis : Literal[0, 1, 2] = 2\n Specifies dimension of the planar axis (0,1,2) -> (x,y,z).\nsidewall_angle : ConstrainedFloatValue = 0.0\n [units = rad]. Angle of the sidewall. ``sidewall_angle=0`` (default) specifies a vertical wall; ``0<sidewall_angle<np.pi/2`` specifies a shrinking cross section along the ``axis`` direction; and ``-np.pi/2<sidewall_angle<0`` specifies an expanding cross section along the ``axis`` direction.\nreference_plane : Literal['bottom', 'middle', 'top'] = bottom\n The position of the plane where the supplied cross section are defined. The plane is perpendicular to the ``axis``. The plane is located at the ``bottom``, ``middle``, or ``top`` of the geometry with respect to the axis. E.g. if ``axis=1``, ``bottom`` refers to the negative side of the y-axis, and ``top`` refers to the positive side of the y-axis.\nslab_bounds : Tuple[float, float]\n [units = um]. Minimum and maximum positions of the slab along axis dimension.\ndilation : float = 0.0\n [units = um]. Dilation of the supplied polygon by shifting each edge along its normal outwards direction by a distance; a negative value corresponds to erosion.\nvertices : Union[Tuple[Tuple[float, float], ...], Array]\n [units = um]. List of (d1, d2) defining the 2 dimensional positions of the polygon face vertices at the ``reference_plane``. The index of dimension should be in the ascending order: e.g. if the slab normal axis is ``axis=y``, the coordinate of the vertices will be in (x, z)\n\nExample\n-------\n>>> vertices = np.array([(0,0), (1,0), (1,1)])\n>>> p = PolySlab(vertices=vertices, axis=2, slab_bounds=(-1, 1))", "type": "object", "properties": { "type": { "title": "Type", "default": "PolySlab", "enum": [ "PolySlab" ], "type": "string" }, "axis": { "title": "Axis", "description": "Specifies dimension of the planar axis (0,1,2) -> (x,y,z).", "default": 2, "enum": [ 0, 1, 2 ], "type": "integer" }, "sidewall_angle": { "title": "Sidewall angle", "description": "Angle of the sidewall. ``sidewall_angle=0`` (default) specifies a vertical wall; ``0<sidewall_angle<np.pi/2`` specifies a shrinking cross section along the ``axis`` direction; and ``-np.pi/2<sidewall_angle<0`` specifies an expanding cross section along the ``axis`` direction.", "default": 0.0, "exclusiveMinimum": -1.5707963267948966, "exclusiveMaximum": 1.5707963267948966, "units": "rad", "type": "number" }, "reference_plane": { "title": "Reference plane for cross section", "description": "The position of the plane where the supplied cross section are defined. The plane is perpendicular to the ``axis``. The plane is located at the ``bottom``, ``middle``, or ``top`` of the geometry with respect to the axis. E.g. if ``axis=1``, ``bottom`` refers to the negative side of the y-axis, and ``top`` refers to the positive side of the y-axis.", "default": "bottom", "enum": [ "bottom", "middle", "top" ], "type": "string" }, "slab_bounds": { "title": "Slab Bounds", "description": "Minimum and maximum positions of the slab along axis dimension.", "units": "um", "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "dilation": { "title": "Dilation", "description": "Dilation of the supplied polygon by shifting each edge along its normal outwards direction by a distance; a negative value corresponds to erosion.", "default": 0.0, "units": "um", "type": "number" }, "vertices": { "title": "Vertices", "description": "List of (d1, d2) defining the 2 dimensional positions of the polygon face vertices at the ``reference_plane``. The index of dimension should be in the ascending order: e.g. if the slab normal axis is ``axis=y``, the coordinate of the vertices will be in (x, z)", "units": "um", "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } }, { "title": "Array Like", "description": "Accepts sequence (tuple, list, numpy array) and converts to tuple.", "type": "tuple", "properties": {}, "required": [] } ] } }, "required": [ "slab_bounds", "vertices" ], "additionalProperties": false }, "GeometryGroup": { "title": "GeometryGroup", "description": "A collection of Geometry objects that can be called as a single geometry object.\n\nParameters\n----------\ngeometries : Tuple[Annotated[Union[tidy3d.components.geometry.Box, tidy3d.components.geometry.Sphere, tidy3d.components.geometry.Cylinder, tidy3d.components.geometry.PolySlab], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], ...]\n Tuple of geometries in a single grouping. Can provide significant performance enhancement in ``Structure`` when all geometries are assigned the same medium.", "type": "object", "properties": { "type": { "title": "Type", "default": "GeometryGroup", "enum": [ "GeometryGroup" ], "type": "string" }, "geometries": { "title": "Geometries", "description": "Tuple of geometries in a single grouping. Can provide significant performance enhancement in ``Structure`` when all geometries are assigned the same medium.", "type": "array", "items": { "discriminator": { "propertyName": "type", "mapping": { "Box": "#/definitions/Box", "Sphere": "#/definitions/Sphere", "Cylinder": "#/definitions/Cylinder", "PolySlab": "#/definitions/PolySlab" } }, "oneOf": [ { "$ref": "#/definitions/Box" }, { "$ref": "#/definitions/Sphere" }, { "$ref": "#/definitions/Cylinder" }, { "$ref": "#/definitions/PolySlab" } ] } } }, "required": [ "geometries" ], "additionalProperties": false }, "Medium": { "title": "Medium", "description": "Dispersionless medium.\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\npermittivity : ConstrainedFloatValue = 1.0\n [units = None (relative permittivity)]. Relative permittivity.\nconductivity : ConstrainedFloatValue = 0.0\n [units = S/um]. Electric conductivity. Defined such that the imaginary part of the complex permittivity at angular frequency omega is given by conductivity/omega.\n\nExample\n-------\n>>> dielectric = Medium(permittivity=4.0, name='my_medium')\n>>> eps = dielectric.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "Medium", "enum": [ "Medium" ], "type": "string" }, "permittivity": { "title": "Permittivity", "description": "Relative permittivity.", "default": 1.0, "minimum": 1.0, "units": "None (relative permittivity)", "type": "number" }, "conductivity": { "title": "Conductivity", "description": "Electric conductivity. Defined such that the imaginary part of the complex permittivity at angular frequency omega is given by conductivity/omega.", "default": 0.0, "minimum": 0.0, "units": "S/um", "type": "number" } }, "additionalProperties": false }, "PermittivityDataset": { "title": "PermittivityDataset", "description": "Dataset storing the diagonal components of the permittivity tensor.\n\nParameters\n----------\neps_xx : ScalarFieldDataArray\n Spatial distribution of the xx-component of the relative permittivity.\neps_yy : ScalarFieldDataArray\n Spatial distribution of the yy-component of the relative permittivity.\neps_zz : ScalarFieldDataArray\n Spatial distribution of the zz-component of the relative permittivity.\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>>> sclr_fld = ScalarFieldDataArray((1+1j) * np.random.random((2,3,4,2)), coords=coords)\n>>> data = PermittivityDataset(eps_xx=sclr_fld, eps_yy=sclr_fld, eps_zz=sclr_fld)", "type": "object", "properties": { "type": { "title": "Type", "default": "PermittivityDataset", "enum": [ "PermittivityDataset" ], "type": "string" }, "eps_xx": { "title": "DataArray", "description": "Spatial distribution of the xx-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] }, "eps_yy": { "title": "DataArray", "description": "Spatial distribution of the yy-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] }, "eps_zz": { "title": "DataArray", "description": "Spatial distribution of the zz-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] } }, "required": [ "eps_xx", "eps_yy", "eps_zz" ], "additionalProperties": false }, "CustomMedium": { "title": "CustomMedium", "description": ":class:`.Medium` with user-supplied permittivity distribution.\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_dataset : PermittivityDataset\n User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on ``interp_method``.\ninterp_method : Literal['nearest', 'linear'] = nearest\n Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.\n\nExample\n-------\n>>> Nx, Ny, Nz = 10, 9, 8\n>>> X = np.linspace(-1, 1, Nx)\n>>> Y = np.linspace(-1, 1, Ny)\n>>> Z = np.linspace(-1, 1, Nz)\n>>> freqs = [2e14]\n>>> data = np.ones((Nx, Ny, Nz, 1))\n>>> eps_diagonal_data = ScalarFieldDataArray(data, coords=dict(x=X, y=Y, z=Z, f=freqs))\n>>> eps_components = {f\"eps_{d}{d}\": eps_diagonal_data for d in \"xyz\"}\n>>> eps_dataset = PermittivityDataset(**eps_components)\n>>> dielectric = CustomMedium(eps_dataset=eps_dataset, name='my_medium')\n>>> eps = dielectric.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "CustomMedium", "enum": [ "CustomMedium" ], "type": "string" }, "eps_dataset": { "title": "Permittivity Dataset", "description": "User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on ``interp_method``.", "allOf": [ { "$ref": "#/definitions/PermittivityDataset" } ] }, "interp_method": { "title": "Interpolation method", "description": "Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.", "default": "nearest", "enum": [ "nearest", "linear" ], "type": "string" } }, "required": [ "eps_dataset" ], "additionalProperties": false }, "ComplexNumber": { "title": "ComplexNumber", "description": "Complex number with a well defined schema.", "type": "object", "properties": { "real": { "title": "Real", "type": "number" }, "imag": { "title": "Imag", "type": "number" } }, "required": [ "real", "imag" ] }, "PoleResidue": { "title": "PoleResidue", "description": "A dispersive medium described by the pole-residue pair model.\nThe frequency-dependence of the complex-valued permittivity is described by:\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_inf : float = 1.0\n [units = None (relative permittivity)]. Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).\npoles : Tuple[Tuple[Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber], Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = ()\n [units = (rad/sec, rad/sec)]. Tuple of complex-valued (:math:`a_i, c_i`) poles for the model.\n\nNote\n----\n.. math::\n\n \\epsilon(\\omega) = \\epsilon_\\infty - \\sum_i\n \\left[\\frac{c_i}{j \\omega + a_i} +\n \\frac{c_i^*}{j \\omega + a_i^*}\\right]\n\nExample\n-------\n>>> pole_res = PoleResidue(eps_inf=2.0, poles=[((1+2j), (3+4j)), ((5+6j), (7+8j))])\n>>> eps = pole_res.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "PoleResidue", "enum": [ "PoleResidue" ], "type": "string" }, "eps_inf": { "title": "Epsilon at Infinity", "description": "Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).", "default": 1.0, "units": "None (relative permittivity)", "type": "number" }, "poles": { "title": "Poles", "description": "Tuple of complex-valued (:math:`a_i, c_i`) poles for the model.", "default": [], "units": [ "rad/sec", "rad/sec" ], "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "anyOf": [ { "title": "ComplexNumber", "description": "Complex number with a well defined schema.", "type": "object", "properties": { "real": { "title": "Real", "type": "number" }, "imag": { "title": "Imag", "type": "number" } }, "required": [ "real", "imag" ] }, { "$ref": "#/definitions/ComplexNumber" } ] }, { "anyOf": [ { "title": "ComplexNumber", "description": "Complex number with a well defined schema.", "type": "object", "properties": { "real": { "title": "Real", "type": "number" }, "imag": { "title": "Imag", "type": "number" } }, "required": [ "real", "imag" ] }, { "$ref": "#/definitions/ComplexNumber" } ] } ] } } }, "additionalProperties": false }, "Sellmeier": { "title": "Sellmeier", "description": "A dispersive medium described by the Sellmeier model.\nThe frequency-dependence of the refractive index is described by:\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\ncoeffs : Tuple[Tuple[float, pydantic.types.PositiveFloat], ...]\n [units = (None, um^2)]. List of Sellmeier (:math:`B_i, C_i`) coefficients.\n\nNote\n----\n.. math::\n\n n(\\lambda)^2 = 1 + \\sum_i \\frac{B_i \\lambda^2}{\\lambda^2 - C_i}\n\nExample\n-------\n>>> sellmeier_medium = Sellmeier(coeffs=[(1,2), (3,4)])\n>>> eps = sellmeier_medium.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "Sellmeier", "enum": [ "Sellmeier" ], "type": "string" }, "coeffs": { "title": "Coefficients", "description": "List of Sellmeier (:math:`B_i, C_i`) coefficients.", "units": [ null, "um^2" ], "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number", "exclusiveMinimum": 0 } ] } } }, "required": [ "coeffs" ], "additionalProperties": false }, "Lorentz": { "title": "Lorentz", "description": "A dispersive medium described by the Lorentz model.\nThe frequency-dependence of the complex-valued permittivity is described by:\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_inf : float = 1.0\n [units = None (relative permittivity)]. Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).\ncoeffs : Tuple[Tuple[float, float, float], ...]\n [units = (None (relative permittivity), Hz, Hz)]. List of (:math:`\\Delta\\epsilon_i, f_i, \\delta_i`) values for model.\n\nNote\n----\n.. math::\n\n \\epsilon(f) = \\epsilon_\\infty + \\sum_i\n \\frac{\\Delta\\epsilon_i f_i^2}{f_i^2 - 2jf\\delta_i - f^2}\n\nExample\n-------\n>>> lorentz_medium = Lorentz(eps_inf=2.0, coeffs=[(1,2,3), (4,5,6)])\n>>> eps = lorentz_medium.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "Lorentz", "enum": [ "Lorentz" ], "type": "string" }, "eps_inf": { "title": "Epsilon at Infinity", "description": "Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).", "default": 1.0, "units": "None (relative permittivity)", "type": "number" }, "coeffs": { "title": "Coefficients", "description": "List of (:math:`\\Delta\\epsilon_i, f_i, \\delta_i`) values for model.", "units": [ "None (relative permittivity)", "Hz", "Hz" ], "type": "array", "items": { "type": "array", "minItems": 3, "maxItems": 3, "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] } } }, "required": [ "coeffs" ], "additionalProperties": false }, "Debye": { "title": "Debye", "description": "A dispersive medium described by the Debye model.\nThe frequency-dependence of the complex-valued permittivity is described by:\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_inf : float = 1.0\n [units = None (relative permittivity)]. Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).\ncoeffs : Tuple[Tuple[float, pydantic.types.PositiveFloat], ...]\n [units = (None (relative permittivity), sec)]. List of (:math:`\\Delta\\epsilon_i, \\tau_i`) values for model.\n\nNote\n----\n.. math::\n\n \\epsilon(f) = \\epsilon_\\infty + \\sum_i\n \\frac{\\Delta\\epsilon_i}{1 - jf\\tau_i}\n\nExample\n-------\n>>> debye_medium = Debye(eps_inf=2.0, coeffs=[(1,2),(3,4)])\n>>> eps = debye_medium.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "Debye", "enum": [ "Debye" ], "type": "string" }, "eps_inf": { "title": "Epsilon at Infinity", "description": "Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).", "default": 1.0, "units": "None (relative permittivity)", "type": "number" }, "coeffs": { "title": "Coefficients", "description": "List of (:math:`\\Delta\\epsilon_i, \\tau_i`) values for model.", "units": [ "None (relative permittivity)", "sec" ], "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number", "exclusiveMinimum": 0 } ] } } }, "required": [ "coeffs" ], "additionalProperties": false }, "Drude": { "title": "Drude", "description": "A dispersive medium described by the Drude model.\nThe frequency-dependence of the complex-valued permittivity is described by:\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_inf : float = 1.0\n [units = None (relative permittivity)]. Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).\ncoeffs : Tuple[Tuple[float, pydantic.types.PositiveFloat], ...]\n [units = (Hz, Hz)]. List of (:math:`f_i, \\delta_i`) values for model.\n\nNote\n----\n.. math::\n\n \\epsilon(f) = \\epsilon_\\infty - \\sum_i\n \\frac{ f_i^2}{f^2 + jf\\delta_i}\n\nExample\n-------\n>>> drude_medium = Drude(eps_inf=2.0, coeffs=[(1,2), (3,4)])\n>>> eps = drude_medium.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "Drude", "enum": [ "Drude" ], "type": "string" }, "eps_inf": { "title": "Epsilon at Infinity", "description": "Relative permittivity at infinite frequency (:math:`\\epsilon_\\infty`).", "default": 1.0, "units": "None (relative permittivity)", "type": "number" }, "coeffs": { "title": "Coefficients", "description": "List of (:math:`f_i, \\delta_i`) values for model.", "units": [ "Hz", "Hz" ], "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number", "exclusiveMinimum": 0 } ] } } }, "required": [ "coeffs" ], "additionalProperties": false }, "AnisotropicMedium": { "title": "AnisotropicMedium", "description": "Diagonally anisotropic medium.\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\nxx : Union[Medium, PoleResidue, Sellmeier, Lorentz, Debye, Drude]\n Medium describing the xx-component of the diagonal permittivity tensor.\nyy : Union[Medium, PoleResidue, Sellmeier, Lorentz, Debye, Drude]\n Medium describing the yy-component of the diagonal permittivity tensor.\nzz : Union[Medium, PoleResidue, Sellmeier, Lorentz, Debye, Drude]\n Medium describing the zz-component of the diagonal permittivity tensor.\n\nNote\n----\nOnly diagonal anisotropy is currently supported.\n\nExample\n-------\n>>> medium_xx = Medium(permittivity=4.0)\n>>> medium_yy = Medium(permittivity=4.1)\n>>> medium_zz = Medium(permittivity=3.9)\n>>> anisotropic_dielectric = AnisotropicMedium(xx=medium_xx, yy=medium_yy, zz=medium_zz)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "AnisotropicMedium", "enum": [ "AnisotropicMedium" ], "type": "string" }, "xx": { "title": "XX Component", "description": "Medium describing the xx-component of the diagonal permittivity tensor.", "discriminator": { "propertyName": "type", "mapping": { "Medium": "#/definitions/Medium", "PoleResidue": "#/definitions/PoleResidue", "Sellmeier": "#/definitions/Sellmeier", "Lorentz": "#/definitions/Lorentz", "Debye": "#/definitions/Debye", "Drude": "#/definitions/Drude" } }, "oneOf": [ { "$ref": "#/definitions/Medium" }, { "$ref": "#/definitions/PoleResidue" }, { "$ref": "#/definitions/Sellmeier" }, { "$ref": "#/definitions/Lorentz" }, { "$ref": "#/definitions/Debye" }, { "$ref": "#/definitions/Drude" } ] }, "yy": { "title": "YY Component", "description": "Medium describing the yy-component of the diagonal permittivity tensor.", "discriminator": { "propertyName": "type", "mapping": { "Medium": "#/definitions/Medium", "PoleResidue": "#/definitions/PoleResidue", "Sellmeier": "#/definitions/Sellmeier", "Lorentz": "#/definitions/Lorentz", "Debye": "#/definitions/Debye", "Drude": "#/definitions/Drude" } }, "oneOf": [ { "$ref": "#/definitions/Medium" }, { "$ref": "#/definitions/PoleResidue" }, { "$ref": "#/definitions/Sellmeier" }, { "$ref": "#/definitions/Lorentz" }, { "$ref": "#/definitions/Debye" }, { "$ref": "#/definitions/Drude" } ] }, "zz": { "title": "ZZ Component", "description": "Medium describing the zz-component of the diagonal permittivity tensor.", "discriminator": { "propertyName": "type", "mapping": { "Medium": "#/definitions/Medium", "PoleResidue": "#/definitions/PoleResidue", "Sellmeier": "#/definitions/Sellmeier", "Lorentz": "#/definitions/Lorentz", "Debye": "#/definitions/Debye", "Drude": "#/definitions/Drude" } }, "oneOf": [ { "$ref": "#/definitions/Medium" }, { "$ref": "#/definitions/PoleResidue" }, { "$ref": "#/definitions/Sellmeier" }, { "$ref": "#/definitions/Lorentz" }, { "$ref": "#/definitions/Debye" }, { "$ref": "#/definitions/Drude" } ] } }, "required": [ "xx", "yy", "zz" ], "additionalProperties": false }, "PECMedium": { "title": "PECMedium", "description": "Perfect electrical conductor class.\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\n\nNote\n----\nTo avoid confusion from duplicate PECs, should import ``tidy3d.PEC`` instance directly.", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "PECMedium", "enum": [ "PECMedium" ], "type": "string" } }, "additionalProperties": false } } }
- attribute geometry: Union[tidy3d.components.geometry.Box, tidy3d.components.geometry.Sphere, tidy3d.components.geometry.Cylinder, tidy3d.components.geometry.PolySlab, tidy3d.components.geometry.GeometryGroup] [Required]#
Defines geometric properties of the structure.
- attribute medium: Union[tidy3d.components.medium.Medium, tidy3d.components.medium.CustomMedium, 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] [Required]#
Defines the electromagnetic properties of the structure’s medium.
- attribute name: str = None#
Optional name for the structure.
- Validated by
field_has_unique_names
- classmethod add_type_field() None#
Automatically place “type” field with model name in the model field dictionary.
- 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=Trueas 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
Tidy3dBaseModelfrom.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
Tidy3dBaseModelfrom.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
Tidy3dBaseModelfrom.- 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
Tidy3dBaseModelfrom.- Returns
A dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_yaml(fname='folder/sim.yaml')
- eps_diagonal(frequency: float, coords: tidy3d.components.grid.grid.Coords) Tuple[complex, complex, complex]#
Main diagonal of the complex-valued permittivity tensor as a function of frequency.
- Parameters
frequency (float) – Frequency to evaluate permittivity at (Hz).
- Returns
The diagonal elements of the relative permittivity tensor evaluated at
frequency.- Return type
complex
- classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel#
Loads a
Tidy3dBaseModelfrom .yaml, .json, or .hdf5 file.- Parameters
fname (str) – Full path to the .yaml or .json file to load the
Tidy3dBaseModelfrom.group_path (str, optional) – Path to a group inside the file to use as the base level. Only for
.hdf5files. Starting / is optional.**parse_obj_kwargs – Keyword arguments passed to either pydantic’s
parse_objfunction 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
Tidy3dBaseModelinstance to .hdf5 file.- Parameters
fname (str) – Full path to the .hdf5 file to load the
Tidy3dBaseModelfrom.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_objmethod.
Example
>>> simulation.to_hdf5(fname='folder/sim.hdf5')
- classmethod from_json(fname: str, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel#
Load a
Tidy3dBaseModelfrom .json file.- Parameters
fname (str) – Full path to the .json file to load the
Tidy3dBaseModelfrom.- Returns
Tidy3dBaseModel– An instance of the component class calling load.**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_objmethod.
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
Tidy3dBaseModelfrom .yaml file.- Parameters
fname (str) – Full path to the .yaml file to load the
Tidy3dBaseModelfrom.**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_objmethod.
- 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)
- 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().
- 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#
- plot(x: float = None, y: float = None, z: float = None, ax: matplotlib.axes._axes.Axes = None, **patch_kwargs) matplotlib.axes._axes.Axes#
Plot structure’s geometric 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
- 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#
- to_file(fname: str) None#
Exports
Tidy3dBaseModelinstance to .yaml, .json, or .hdf5 file- Parameters
fname (str) – Full path to the .yaml or .json file to save the
Tidy3dBaseModelto.
Example
>>> simulation.to_file(fname='folder/sim.json')
- to_hdf5(fname: str) None#
Exports
Tidy3dBaseModelinstance to .hdf5 file.- Parameters
fname (str) – Full path to the .hdf5 file to save the
Tidy3dBaseModelto.
Example
>>> simulation.to_hdf5(fname='folder/sim.hdf5')
- to_json(fname: str) None#
Exports
Tidy3dBaseModelinstance to .json file- Parameters
fname (str) – Full path to the .json file to save the
Tidy3dBaseModelto.
Example
>>> simulation.to_json(fname='folder/sim.json')
- to_yaml(fname: str) None#
Exports
Tidy3dBaseModelinstance to .yaml file.- Parameters
fname (str) – Full path to the .yaml file to save the
Tidy3dBaseModelto.
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.
- 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
**kwargsindicating updated field values.
- classmethod validate(value: Any) Model#