tidy3d.ModeData

tidy3d.ModeData#

class ModeData[source]#

Bases: ModeSolverDataset, ElectromagneticFieldData

Data associated with a ModeMonitor: modal amplitudes, propagation indices and mode profiles.

Parameters:

attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().
Ex (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the x-component of the electric field of the mode.
Ey (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the y-component of the electric field of the mode.
Ez (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the z-component of the electric field of the mode.
Hx (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the x-component of the magnetic field of the mode.
Hy (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the y-component of the magnetic field of the mode.
Hz (Optional[ScalarModeFieldDataArray] = None) – Spatial distribution of the z-component of the magnetic field of the mode.
monitor (ModeMonitor) – Mode monitor associated with the data.
symmetry (Tuple[Literal[0, -1, 1], Literal[0, -1, 1], Literal[0, -1, 1]] = (0, 0, 0)) – Symmetry eigenvalues of the original simulation in x, y, and z.
symmetry_center (Optional[Tuple[float, float, float]] = None) – Center of the symmetry planes of the original simulation in x, y, and z. Required only if any of the symmetry field are non-zero.
grid_expanded (Optional[Grid] = None) – Grid discretization of the associated monitor in the simulation which created the data. Required if symmetries are present, as well as in order to use some functionalities like getting Poynting vector and flux.
grid_primal_correction (Union[float, FreqDataArray, TimeDataArray, FreqModeDataArray, EMEFreqModeDataArray] = 1.0) – Correction factor that needs to be applied for data corresponding to a 2D monitor to take into account the finite grid in the normal direction in the simulation in which the data was computed. The factor is applied to fields defined on the primal grid locations along the normal direction.
grid_dual_correction (Union[float, FreqDataArray, TimeDataArray, FreqModeDataArray, EMEFreqModeDataArray] = 1.0) – Correction factor that needs to be applied for data corresponding to a 2D monitor to take into account the finite grid in the normal direction in the simulation in which the data was computed. The factor is applied to fields defined on the dual grid locations along the normal direction.
n_complex (ModeIndexDataArray) – Complex-valued effective propagation constants associated with the mode.
n_group_raw (Optional[GroupIndexDataArray] = None) – Index associated with group velocity of the mode.
dispersion_raw (Optional[ModeDispersionDataArray] = None) – [units = ps/(nm km)]. Dispersion parameter for the mode.
amps (ModeAmpsDataArray) – Complex-valued amplitudes associated with the mode.
eps_spec (Optional[List[Literal['diagonal', 'tensorial_real', 'tensorial_complex']]] = None) – Characterization of the permittivity profile on the plane where modes are computed. Possible values are ‘diagonal’, ‘tensorial_real’, ‘tensorial_complex’.

Notes

The data is stored as a DataArray object using the xarray package.

The mode monitor data contains the complex effective indices and the complex mode amplitudes at the monitor position calculated by mode decomposition. The data structure of the complex effective indices :attr`n_complex` contains two coordinates: f and mode_index, both of which are specified when defining the :class:ModeMonitor in the simulation.

Besides the effective index, :class:ModeMonitor is primarily used to calculate the transmission of certain modes in certain directions. We can extract the complex amplitude and square it to compute the mode transmission power.

Example

>>> from tidy3d import ModeSpec
>>> from tidy3d import ModeAmpsDataArray, ModeIndexDataArray
>>> direction = ["+", "-"]
>>> f = [1e14, 2e14, 3e14]
>>> mode_index = np.arange(5)
>>> index_coords = dict(f=f, mode_index=mode_index)
>>> index_data = ModeIndexDataArray((1+1j) * np.random.random((3, 5)), coords=index_coords)
>>> amp_coords = dict(direction=direction, f=f, mode_index=mode_index)
>>> amp_data = ModeAmpsDataArray((1+1j) * np.random.random((2, 3, 5)), coords=amp_coords)
>>> monitor = ModeMonitor(
...    size=(2,0,6),
...    freqs=[2e14, 3e14],
...    mode_spec=ModeSpec(num_modes=5),
...    name='mode',
... )
>>> data = ModeData(monitor=monitor, amps=amp_data, n_complex=index_data)

Attributes

`TE_fraction`	Alias for `pol_fraction.te`.
`TM_fraction`	Alias for `pol_fraction.tm`.
`modes_info`	Dataset collecting various properties of the stored modes.
`pol_fraction`	Compute the TE and TM polarization fraction defined as the field intensity along the first or the second of the two tangential axes.
`pol_fraction_waveguide`	Compute the TE and TM polarization fraction using the waveguide definition.
`time_reversed_copy`	Make a copy of the data with direction-reversed fields.
`wg_TE_fraction`	Alias for `pol_fraction_waveguide.te`.
`wg_TM_fraction`	Alias for `pol_fraction_waveguide.tm`.
`attrs`

Methods

`eps_spec_match_mode_spec`(val, values)	Raise validation error if frequencies in eps_spec does not match frequency list
`normalize`(source_spectrum_fn)	Return copy of self after normalization is applied using source spectrum function.
`overlap_sort`(track_freq[, overlap_thresh])	Starting from the base frequency defined by parameter `track_freq`, sort modes at each frequency according to their overlap values with the modes at the previous frequency.
`sort_modes`([sort_spec, track_freq])	Sort modes per frequency according to `sort_spec`.
`to_dataframe`()	xarray-like method to export the `modes_info` into a pandas dataframe which is e.g. simple to visualize as a table.

Inherited Common Usage

monitor#

amps#

eps_spec#

classmethod eps_spec_match_mode_spec(val, values)[source]#: Raise validation error if frequencies in eps_spec does not match frequency list

normalize(source_spectrum_fn)[source]#: Return copy of self after normalization is applied using source spectrum function.

overlap_sort(track_freq, overlap_thresh=0.9)[source]#

Starting from the base frequency defined by parameter track_freq, sort modes at each frequency according to their overlap values with the modes at the previous frequency. That is, it attempts to rearrange modes in such a way that a given mode_index corresponds to physically the same mode at all frequencies. Modes with overlap values over overlap_thresh are considered matching and not rearranged.

Note

The monitor associated to this data is updated so that the deprecated monitor.mode_spec.track_freq is set to None, while monitor.mode_spec.sort_spec.track_freq is set to the provided track_freq.

Parameters:

track_freq (Literal["central", "lowest", "highest"]) – Parameter that specifies which frequency will serve as a starting point in the reordering process.
overlap_thresh (float = 0.9) – Modal overlap threshold above which two modes are considered to be the same and are not rearranged. If after the sorting procedure the overlap value between two corresponding modes is less than this threshold, a warning about a possible discontinuity is displayed.

property time_reversed_copy#: Make a copy of the data with direction-reversed fields. In lossy or gyrotropic systems, the time-reversed fields will not be the same as the backward-propagating modes.

property pol_fraction#

Compute the TE and TM polarization fraction defined as the field intensity along the first or the second of the two tangential axes. More precisely, if $E_1$ and $E_2$ are the electric field components along the two tangential axes, the TE fraction is defined as:

\[\frac{\int |E_1|^2 \, {\rm d}S}{\int \left(|E_1|^2 + |E_2|^2\right) \, {\rm d}S}\]

and the TM fraction is equal to one minus the TE fraction. The tangential axes are defined by popping the normal axis from the list of x, y, z, so e.g. x and z for propagation in the y direction.

property pol_fraction_waveguide#

Compute the TE and TM polarization fraction using the waveguide definition. If $n$ is the propagation direction, the TE fraction is defined as:

\[1 - \frac{\int |E \cdot n|^2 \, {\rm d}S}{\int |E|^2 \, {\rm d}S}\]

and the TM fraction is defined as

\[1 - \frac{\int |H \cdot n|^2 \, {\rm d}S}{\int |H|^2 \, {\rm d}S}\]

Note

The waveguide TE and TM fractions do not sum to one. For example, TEM modes that are completely transverse (zero electric and magnetic field in the propagation direction) have TE fraction and TM fraction both equal to one.

property TE_fraction#: Alias for pol_fraction.te.

property TM_fraction#: Alias for pol_fraction.tm.

property wg_TE_fraction#: Alias for pol_fraction_waveguide.te.

property wg_TM_fraction#: Alias for pol_fraction_waveguide.tm.

property modes_info#: Dataset collecting various properties of the stored modes.

to_dataframe()[source]#: xarray-like method to export the modes_info into a pandas dataframe which is e.g. simple to visualize as a table.

sort_modes(sort_spec=None, track_freq=None)[source]#

Sort modes per frequency according to sort_spec.

The modes are first filtered if sort_spec.filter_key is provided. They are then sorted within each filtered group according to sort_spec.sort_key. if provided. Finally, if a tracking frequency is also provided either in sort_spec or as a separate argument, the tracking is applied . The tracking could reshuffle the filter/sort criteria at frequencies away from the tracking frequency.

Parameters:

sort_spec (Optional[ModeSortSpec]) – Specification of how to sort the modes.
track_freq (Optional[Literal["central", "lowest", "highest"]]) – Specifies that modes should be tracked across frequencies. Overrides sort_spec.track_freq, but the returned data will have monitor.mode_spec.sort_spec.track_freq set to the provided value, while self.monitor.mode_spec.track_freq will be set to None.

Returns:

Copy of self with modes sorted according to sort_spec.

Return type:

ModeSolverData

__hash__()#: Hash method.

tidy3d.ModeData

Contents

tidy3d.ModeData#