tidy3d.plugins.resonance.ResonanceFinder#

class tidy3d.plugins.resonance.ResonanceFinder#

Bases: tidy3d.components.base.Tidy3dBaseModel

Tool that extracts resonance information from a time series of the form shown below. The resonance information consists of frequency \(f\), decay rate \(\alpha\), Q factor \(Q = \pi |f|/\alpha\), amplitude \(a\), and phase \(\phi\).

Parameters

freq_window (Tuple[float, float]) – [units = Hz]. Window [fmin, fmax] for the initial frequencies. The resonance finder is initialized with an even grid of frequencies between fmin and fmax. The resonance finder then iteratively optimizes and prunes these frequencies. Note that frequencies outside this window may be returned. A narrow frequency window that only contains a few resonances may give enhanced accuracy compared to a broad frequency window with many resonances.
init_num_freqs (PositiveInt = 200) – Number of frequencies with which the resonance finder is initialized. The resonance finder then iteratively optimizes and prunes these frequencies. The number of frequencies returned will be less than init_num_freqs. Making this larger can find more resonances, while making it smaller can speed up the resonance finder.
rcond (NonNegativeFloat = 0.0001) – Cutoff for eigenvalues, relative to the largest eigenvalue. The resonance finder solves a generalized eigenvalue problem of the form \(Ax = \lambda B x\). If B has small eigenvalues, this is poorly conditioned, so we eliminate eigenvalues of B less than rcond times the largest eigenvalue. Making this closer to zero will typically return more resonances.

Note

\[f(t) = \sum_k a_k e^{i \phi_k} e^{-2 \pi i f_k t - \alpha_k t}\]

Note

We use the algorithm described in

Vladimir A. Mandelshtam and Howard S. Taylor, “Harmonic inversion of time signals and its applications,” J. Chem. Phys. 107, 6756 (1997).

Example

>>> import numpy as np
>>> from tidy3d.plugins.resonance import ResonanceFinder
>>> t = np.linspace(0, 10000, 10000)
>>> f1 = 2*np.pi*0.1 - 1j*0.002
>>> f2 = 2*np.pi*0.2 - 1j*0.0005
>>> sig = 2*np.exp(-1j*f1*t) + 3*1j*np.exp(-1j*f2*t)
>>> resfinder = ResonanceFinder(freq_window=(0.05, 0.25))
>>> resdata = resfinder.run_raw_signal(signal=sig, time_step=1)
>>> resdata.to_dataframe()

Show JSON schema

{
   "title": "ResonanceFinder",
   "description": "Tool that extracts resonance information from a time series of the form shown below.\nThe resonance information consists of frequency :math:`f`, decay rate :math:`\\alpha`,\nQ factor :math:`Q = \\pi |f|/\\alpha`, amplitude :math:`a`, and phase :math:`\\phi`.\n\nParameters\n----------\nfreq_window : Tuple[float, float]\n    [units = Hz].  Window ``[fmin, fmax]`` for the initial frequencies. The resonance finder is initialized with an even grid of frequencies between fmin and fmax. The resonance finder then iteratively optimizes and prunes these frequencies. Note that frequencies outside this window may be returned. A narrow frequency window that only contains a few resonances may give enhanced accuracy compared to a broad frequency window with many resonances.\ninit_num_freqs : PositiveInt = 200\n    Number of frequencies with which the resonance finder is initialized. The resonance finder then iteratively optimizes and prunes these frequencies. The number of frequencies returned will be less than ``init_num_freqs``. Making this larger can find more resonances, while making it smaller can speed up the resonance finder.\nrcond : NonNegativeFloat = 0.0001\n    Cutoff for eigenvalues, relative to the largest eigenvalue. The resonance finder solves a generalized eigenvalue problem of the form :math:`Ax = \\lambda B x`. If B has small eigenvalues, this is poorly conditioned, so we eliminate eigenvalues of B less than ``rcond`` times the largest eigenvalue. Making this closer to zero will typically return more resonances.\n\nNote\n----\n.. math::\n\n    f(t) = \\sum_k a_k e^{i \\phi_k} e^{-2 \\pi i f_k t - \\alpha_k t}\n\nNote\n----\nWe use the algorithm described in\n\nVladimir A. Mandelshtam and Howard S. Taylor,\n\"Harmonic inversion of time signals and its applications,\"\nJ. Chem. Phys. 107, 6756 (1997).\n\nExample\n-------\n>>> import numpy as np\n>>> from tidy3d.plugins.resonance import ResonanceFinder\n>>> t = np.linspace(0, 10000, 10000)\n>>> f1 = 2*np.pi*0.1 - 1j*0.002\n>>> f2 = 2*np.pi*0.2 - 1j*0.0005\n>>> sig = 2*np.exp(-1j*f1*t) + 3*1j*np.exp(-1j*f2*t)\n>>> resfinder = ResonanceFinder(freq_window=(0.05, 0.25))\n>>> resdata = resfinder.run_raw_signal(signal=sig, time_step=1)\n>>> resdata.to_dataframe()",
   "type": "object",
   "properties": {
      "freq_window": {
         "title": "Window ``[fmin, fmax]``",
         "description": "Window ``[fmin, fmax]`` for the initial frequencies. The resonance finder is initialized with an even grid of frequencies between fmin and fmax. The resonance finder then iteratively optimizes and prunes these frequencies. Note that frequencies outside this window may be returned. A narrow frequency window that only contains a few resonances may give enhanced accuracy compared to a broad frequency window with many resonances.",
         "units": "Hz",
         "type": "array",
         "minItems": 2,
         "maxItems": 2,
         "items": [
            {
               "type": "number"
            },
            {
               "type": "number"
            }
         ]
      },
      "init_num_freqs": {
         "title": "Initial number of frequencies.",
         "description": "Number of frequencies with which the resonance finder is initialized. The resonance finder then iteratively optimizes and prunes these frequencies. The number of frequencies returned will be less than ``init_num_freqs``. Making this larger can find more resonances, while making it smaller can speed up the resonance finder.",
         "default": 200,
         "exclusiveMinimum": 0,
         "type": "integer"
      },
      "rcond": {
         "title": "Cutoff for eigenvalues",
         "description": "Cutoff for eigenvalues, relative to the largest eigenvalue. The resonance finder solves a generalized eigenvalue problem of the form :math:`Ax = \\lambda B x`. If B has small eigenvalues, this is poorly conditioned, so we eliminate eigenvalues of B less than ``rcond`` times the largest eigenvalue. Making this closer to zero will typically return more resonances.",
         "default": 0.0001,
         "minimum": 0,
         "type": "number"
      },
      "type": {
         "title": "Type",
         "default": "ResonanceFinder",
         "enum": [
            "ResonanceFinder"
         ],
         "type": "string"
      }
   },
   "required": [
      "freq_window"
   ],
   "additionalProperties": false
}

attribute freq_window: Tuple[float, float] [Required]#

Window [fmin, fmax] for the initial frequencies. The resonance finder is initialized with an even grid of frequencies between fmin and fmax. The resonance finder then iteratively optimizes and prunes these frequencies. Note that frequencies outside this window may be returned. A narrow frequency window that only contains a few resonances may give enhanced accuracy compared to a broad frequency window with many resonances.

Validated by

_check_freq_window

attribute init_num_freqs: pydantic.types.PositiveInt = 200#

Number of frequencies with which the resonance finder is initialized. The resonance finder then iteratively optimizes and prunes these frequencies. The number of frequencies returned will be less than init_num_freqs. Making this larger can find more resonances, while making it smaller can speed up the resonance finder.

Constraints

exclusiveMinimum = 0

attribute rcond: pydantic.types.NonNegativeFloat = 0.0001#

Cutoff for eigenvalues, relative to the largest eigenvalue. The resonance finder solves a generalized eigenvalue problem of the form \(Ax = \lambda B x\). If B has small eigenvalues, this is poorly conditioned, so we eliminate eigenvalues of B less than rcond times the largest eigenvalue. Making this closer to zero will typically return more resonances.

Constraints

minimum = 0

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

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) 

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#

run(signals: Union[tidy3d.components.data.monitor_data.FieldTimeData, Tuple[tidy3d.components.data.monitor_data.FieldTimeData, ...]]) → xarray.core.dataset.Dataset#

Finds resonances in a FieldTimeData or a Tuple of such. The time coordinates must be uniformly spaced, and the spacing must be the same across all supplied data. The resonance finder runs on the sum of the Ex, Ey, and Ez fields of all the supplied data, unless no electric fields are present at all, in which case it runs on the sum of the Hx, Hy, and Hz fields. Note that the signal should start after the sources have turned off.

Parameters: signals (FieldTimeData) – Data to search for resonances
Returns: Dataset containing the decay rate, Q, amplitude, phase, and estimation error of the resonances as a function of frequency. Modes with low Q, small amplitude, or high estimation error are likely to be spurious.
Return type: xr.Dataset

run_raw_signal(signal: List[complex], time_step: float) → xarray.core.dataset.Dataset#

Finds resonances in a time series. Note that the signal should start after the sources have turned off.

Parameters

signal (List[complex]) – One-dimensional array holding the complex-valued time series data to search for resonances.
time_step (float) – Time step / sampling rate of the data (in seconds).

Returns

Dataset containing the decay rate, Q, amplitude, phase, and estimation error of the resonances as a function of frequency. Modes with low Q, small amplitude, or high estimation error are likely to be spurious.

Return type

xr.Dataset

run_scalar_field_time(signal: tidy3d.components.data.data_array.ScalarFieldTimeDataArray) → xarray.core.dataset.Dataset#

Finds resonances in a ScalarFieldTimeDataArray. The time coordinates must be uniformly spaced to use the resonance finder; the time step is calculated automatically. Note that the signal should start after the sources have turned off.

Parameters: signal (ScalarFieldTimeDataArray) – Time series to search for resonances
Returns: Dataset containing the decay rate, Q, amplitude, phase, and estimation error of the resonances as a function of frequency. Modes with low Q, small amplitude, or high estimation error are likely to be spurious.
Return type: xr.Dataset

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#