tidy3d.plugins.ResonanceFinder
tidy3d.plugins.ResonanceFinder#
- class tidy3d.plugins.ResonanceFinder#
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 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 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
- 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 theEx
,Ey
, andEz
fields of all the supplied data, unless no electric fields are present at all, in which case it runs on the sum of theHx
,Hy
, andHz
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