tidy3d.plugins.DispersionFitter#

class tidy3d.plugins.DispersionFitter#

Bases: tidy3d.components.base.Tidy3dBaseModel

Tool for fitting refractive index data to get a dispersive medium described by PoleResidue model.

Parameters

wvl_um (Union[Tuple[float, ...], Array]) – [units = um]. Wavelength data in micrometers.
n_data (Union[Tuple[float, ...], Array]) – Real part of the complex index of refraction.
k_data (Union[Tuple[float, ...], Array] = None) – Imaginary part of the complex index of refraction.
wvl_range (Tuple[float, float] = (None, None)) – [units = um]. Truncate the wavelength-nk data to wavelength range [wvl_min,wvl_max] for fitting

Show JSON schema

{
   "title": "DispersionFitter",
   "description": "Tool for fitting refractive index data to get a\ndispersive medium described by :class:`.PoleResidue` model.\n\nParameters\n----------\nwvl_um : Union[Tuple[float, ...], Array]\n    [units = um].  Wavelength data in micrometers.\nn_data : Union[Tuple[float, ...], Array]\n    Real part of the complex index of refraction.\nk_data : Union[Tuple[float, ...], Array] = None\n    Imaginary part of the complex index of refraction.\nwvl_range : Tuple[float, float] = (None, None)\n    [units = um].  Truncate the wavelength-nk data to wavelength range [wvl_min,wvl_max] for fitting",
   "type": "object",
   "properties": {
      "wvl_um": {
         "title": "Wavelength data",
         "description": "Wavelength data in micrometers.",
         "units": "um",
         "anyOf": [
            {
               "type": "array",
               "items": {
                  "type": "number"
               }
            },
            {
               "title": "Array Like",
               "description": "Accepts sequence (tuple, list, numpy array) and converts to tuple.",
               "type": "tuple",
               "properties": {},
               "required": []
            }
         ]
      },
      "n_data": {
         "title": "Index of refraction data",
         "description": "Real part of the complex index of refraction.",
         "anyOf": [
            {
               "type": "array",
               "items": {
                  "type": "number"
               }
            },
            {
               "title": "Array Like",
               "description": "Accepts sequence (tuple, list, numpy array) and converts to tuple.",
               "type": "tuple",
               "properties": {},
               "required": []
            }
         ]
      },
      "k_data": {
         "title": "Extinction coefficient data",
         "description": "Imaginary part of the complex index of refraction.",
         "anyOf": [
            {
               "type": "array",
               "items": {
                  "type": "number"
               }
            },
            {
               "title": "Array Like",
               "description": "Accepts sequence (tuple, list, numpy array) and converts to tuple.",
               "type": "tuple",
               "properties": {},
               "required": []
            }
         ]
      },
      "wvl_range": {
         "title": "Wavelength range [wvl_min,wvl_max] for fitting",
         "description": "Truncate the wavelength-nk data to wavelength range [wvl_min,wvl_max] for fitting",
         "default": [
            null,
            null
         ],
         "units": "um",
         "type": "array",
         "minItems": 2,
         "maxItems": 2,
         "items": [
            {
               "type": "number"
            },
            {
               "type": "number"
            }
         ]
      },
      "type": {
         "title": "Type",
         "default": "DispersionFitter",
         "enum": [
            "DispersionFitter"
         ],
         "type": "string"
      }
   },
   "required": [
      "wvl_um",
      "n_data"
   ],
   "additionalProperties": false
}

attribute k_data: Union[Tuple[float, ...], tidy3d.components.types.Array] = None#

Imaginary part of the complex index of refraction.

Validated by

_kdata_setup_and_length_match

attribute n_data: Union[Tuple[float, ...], tidy3d.components.types.Array] [Required]#

Real part of the complex index of refraction.

Validated by

_ndata_length_match_wvl

attribute wvl_range: Tuple[Optional[float], Optional[float]] = (None, None)#: Truncate the wavelength-nk data to wavelength range [wvl_min,wvl_max] for fitting

attribute wvl_um: Union[Tuple[float, ...], tidy3d.components.types.Array] [Required]#

Wavelength data in micrometers.

Validated by

_setup_wvl

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

fit(num_poles: int = 1, num_tries: int = 50, tolerance_rms: float = 0.01) → Tuple[tidy3d.components.medium.PoleResidue, float]#

Fits data a number of times and returns best results.

Parameters

num_poles (int, optional) – Number of poles in the model.
num_tries (int, optional) – Number of optimizations to run with random initial guess.
tolerance_rms (float, optional) – RMS error below which the fit is successful and the result is returned.

Returns

Best results of multiple fits: (dispersive medium, RMS error).

Return type

Tuple[PoleResidue, float]

classmethod from_file(fname: str, **loadtxt_kwargs)#

Loads DispersionFitter from file containing wavelength, n, k data.

Parameters

fname (str) – Path to file containing wavelength (um), n, k (optional) data in columns.
**loadtxt_kwargs – Kwargs passed to np.loadtxt, such as skiprows, delimiter.

Hint

The data file should be in this format (delimiter and skiprows can be customized in **loadtxt_kwargs):

For lossless media:

wl       n
[float] [float]
.       .
.       .
.       .

For lossy media:

wl       n       k
[float] [float] [float]
.       .       .
.       .       .
.       .       .

Returns: A DispersionFitter instance.
Return type: DispersionFitter

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_url(url_file: str, delimiter: str = ',', ignore_k: bool = False, **kwargs)#

loads DispersionFitter from url linked to a csv/txt file that contains wavelength (micron), n, and optionally k data. Preferred from refractiveindex.info.

Hint

The data file from url should be in this format (delimiter not displayed here, and note that the strings such as “wl”, “n” need to be included in the file):

For lossless media:

wl       n
[float] [float]
.       .
.       .
.       .

For lossy media:

wl       n
[float] [float]
.       .
.       .
.       .
wl       k
[float] [float]
.       .
.       .
.       .

Parameters

url_file (str) – Url link to the data file. e.g. “https://refractiveindex.info/data_csv.php?datafile=data/main/Ag/Johnson.yml”
delimiter (str = ",") – E.g. in refractiveindex.info, it’ll be “,” for csv file, and “\t” for txt file.
ignore_k (bool = False) – Ignore the k data if they are present, so the fitted material is lossless.

Returns

A DispersionFitter instance.

Return type

DispersionFitter

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) 

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(medium: tidy3d.components.medium.PoleResidue = None, wvl_um: Tuple[float, ...] = None, ax: matplotlib.axes._axes.Axes = None) → matplotlib.axes._axes.Axes#

Make plot of model vs data, at a set of wavelengths (if supplied).

Parameters

medium (PoleResidue = None) – medium containing model to plot against data
wvl_um (Tuple[float, ...] = None) – Wavelengths to evaluate model at for plot in micrometers.
ax (matplotlib.axes._subplots.Axes = None) – Axes to plot the data on, if None, a new one is created.

Returns

Matplotlib axis corresponding to plot.

Return type

matplotlib.axis.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') 

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 **kwargs indicating updated field values.

classmethod validate(value: Any) → Model#

property eps_data: complex#

Convert filtered input n(k) data into complex permittivity.

Returns: Complex-valued relative permittivty.
Return type: complex

property freqs: Tuple[float, ...]#

Convert filtered input wavelength data to frequency.

Returns: Frequency array converted from filtered input wavelength data
Return type: Tuple[float, …]

property frequency_range: Tuple[float, float]#

Frequency range of filtered input data

Returns: The minimal frequency and the maximal frequency
Return type: Tuple[float, float]

property lossy: bool#

Find out if the medium is lossy or lossless based on the filtered input data.

Returns: True for lossy medium; False for lossless medium
Return type: bool