# tidy3d.PoleResidue#

class tidy3d.PoleResidue#

A dispersive medium described by the pole-residue pair model. The frequency-dependence of the complex-valued permittivity is described by:

Parameters
• name (Optional[str] = None) – Optional unique name for medium.

• frequency_range (Optional[Tuple[float, float]] = None) – [units = (Hz, Hz)]. Optional range of validity for the medium.

• eps_inf (float = 1.0) – [units = None (relative permittivity)]. Relative permittivity at infinite frequency ($$\epsilon_\infty$$).

• poles (Tuple[Tuple[Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber], Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = ()) – [units = (rad/sec, rad/sec)]. Tuple of complex-valued ($$a_i, c_i$$) poles for the model.

Note

$\epsilon(\omega) = \epsilon_\infty - \sum_i \left[\frac{c_i}{j \omega + a_i} + \frac{c_i^*}{j \omega + a_i^*}\right]$

Example

>>> pole_res = PoleResidue(eps_inf=2.0, poles=[((1+2j), (3+4j)), ((5+6j), (7+8j))])
>>> eps = pole_res.eps_model(200e12)

Show JSON schema
{
"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": [
],
"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"
}
]
}
]
}
}
},
"definitions": {
"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"
]
}
}
}

attribute eps_inf: float = 1.0#

Relative permittivity at infinite frequency ($$\epsilon_\infty$$).

attribute frequency_range: Tuple[float, float] = None#

Optional range of validity for the medium.

attribute name: str = None#

Optional unique name for medium.

Validated by
• field_has_unique_names

attribute poles: Tuple[Tuple[Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber], Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = ()#

Tuple of complex-valued ($$a_i, c_i$$) poles for the model.

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

static complex_to_tuple(value: complex) Tuple[float, float]#

Convert a complex number to a tuple of real and imaginary parts.

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

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')
static eps_complex_to_eps_sigma(eps_complex: complex, freq: float) Tuple[float, float]#

Convert complex permittivity at frequency freq to permittivity and conductivity values.

Parameters
• eps_complex (complex) – Complex-valued relative permittivity.

• freq (float) – Frequency to evaluate permittivity at (Hz).

Returns

Real part of relative permittivity & electric conductivity.

Return type

Tuple[float, float]

static eps_complex_to_nk(eps_c: complex) Tuple[float, float]#

Convert complex permittivity to n, k values.

Parameters

eps_c (complex) – Complex-valued relative permittivity.

Returns

Real and imaginary parts of refractive index (n & k).

Return type

Tuple[float, float]

eps_diagonal(frequency: float) 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

eps_model(frequency: float) complex#

Complex-valued permittivity as a function of frequency.

static eps_sigma_to_eps_complex(eps_real: float, sigma: float, freq: float) complex#

convert permittivity and conductivity to complex permittivity at freq

Parameters
• eps_real (float) – Real-valued relative permittivity.

• sigma (float) – Conductivity.

• freq (float) – Frequency to evaluate permittivity at (Hz). If not supplied, returns real part of permittivity (limit as frequency -> infinity.)

Returns

Complex-valued relative permittivity.

Return type

complex

classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) #

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

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

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

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

nk_model(frequency: float) Tuple[float, float]#

Real and imaginary parts of the refactive index as a function of frequency.

Parameters

frequency (float) – Frequency to evaluate permittivity at (Hz).

Returns

Real part (n) and imaginary part (k) of refractive index of medium.

Return type

Tuple[float, float]

static nk_to_eps_complex(n: float, k: float = 0.0) complex#

Convert n, k to complex permittivity.

Parameters
• n (float) – Real part of refractive index.

• k (float = 0.0) – Imaginary part of refrative index.

Returns

Complex-valued relative permittivty.

Return type

complex

static nk_to_eps_sigma(n: float, k: float, freq: float) Tuple[float, float]#

Convert n, k at frequency freq to permittivity and conductivity values.

Parameters
• n (float) – Real part of refractive index.

• k (float = 0.0) – Imaginary part of refrative index.

• frequency (float) – Frequency to evaluate permittivity at (Hz).

Returns

Real part of relative permittivity & electric conductivity.

Return type

Tuple[float, float]

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(freqs: float, ax: matplotlib.axes._axes.Axes = None) matplotlib.axes._axes.Axes#

Plot n, k of a Medium as a function of frequency.

Parameters
• freqs (float) – Frequencies (Hz) to evaluate the medium properties at.

• ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.

Returns

The supplied or created matplotlib axes.

Return type

matplotlib.axes._subplots.Axes

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 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')
static tuple_to_complex(value: Tuple[float, float]) complex#

Convert a tuple of real and imaginary parts to complex number.

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

Make copy of a component instance with **kwargs indicating updated field values.

classmethod validate(value: Any) Model#
property pole_residue#

Representation of Medium as a pole-residue model.