tidy3d.ModeSortSpec

class ModeSortSpec

Bases: Tidy3dBaseModel

Specification for filtering and sorting modes within each frequency.

Parameters:

• filter_key (Optional[Literal['n_eff', 'k_eff', 'TE_fraction', 'TM_fraction', 'wg_TE_fraction', 'wg_TM_fraction', 'mode_area', 'fill_fraction_box']] = None) – Quantity used to filter modes into two groups before sorting.

• filter_reference (float = 0.0) – Reference value used in the filtering stage.

• filter_order (Literal['over', 'under'] = over) – Select whether the first group contains values over or under the reference.

• bounding_box (Optional[Box] = None) – Regular 3D tidy3d Box used by metrics such as 'fill_fraction_box'. The extent along the propagation axis is ignored for the metric, but the box must still intersect the monitor plane. Required when filtering or sorting with that key.

• keep_modes (Union[Literal['all'], Literal['filtered'], PositiveInt] = all) – If filtered, modes that do not satisfy the filter criterion are removed entirely instead of being appended after the filtered group. Only modes passing the filter at every tracked frequency are kept. If a positive integer is given, that is the number of modes which will be kept.

• sort_key (Literal['n_eff', 'k_eff', 'TE_fraction', 'TM_fraction', 'wg_TE_fraction', 'wg_TM_fraction', 'mode_area', 'fill_fraction_box'] = n_eff) – Quantity used to sort modes within each filtered group.

• sort_reference (Optional[float] = None) – If provided, sorting is based on the absolute difference to this reference value.

• sort_order (Optional[Literal['ascending', 'descending']] = None) – Sort order for the selected key or difference to reference value. If None, the default depends on sort_key and sort_reference. When sort_reference is provided, defaults to 'ascending' (closest to reference first). Otherwise, defaults to the natural order for each key: 'descending' for n_eff, TE_fraction, TM_fraction, wg_TE_fraction, wg_TM_fraction, fill_fraction_box (higher values first); 'ascending' for k_eff, mode_area (lower values first).

• track_freq (Optional[Literal['central', 'lowest', 'highest']] = central) – If provided, enables cross-frequency mode tracking. Can be ‘lowest’, ‘central’, or ‘highest’, which refers to the frequency index in the list of frequencies. The mode sorting would then be exact at the specified frequency, while at other frequencies it can change depending on the mode tracking.

Notes

First, an optional filtering step splits the modes into two groups based on a threshold applied to filter_key: modes “over” or “under” filter_reference are placed first, with the remaining modes placed next. Second, an optional sorting step orders modes within each group according to sort_key, optionally with respect to sort_reference and in the specified sort_order. If keep_modes is set to “filtered”, the modes that do not meet the filter criterion are removed instead of being appended as a second group. If keep_modes is set to an integer, that is the number of modes that will be kept.

Attributes

has_custom_sort_or_filter	Whether this sort spec has custom sorting/filtering beyond the default.
filter_key
filter_reference
filter_order
bounding_box
keep_modes
sort_key
sort_reference
sort_order
track_freq

filter_key

filter_reference

filter_order

bounding_box

keep_modes

sort_key

sort_reference

sort_order

track_freq

property has_custom_sort_or_filter

Whether this sort spec has custom sorting/filtering beyond the default.

Returns True if any of the following differ from defaults: - filter_key is not None - sort_key is not 'n_eff' - sort_reference is not None - sort_order is not 'descending' - keep_modes is not 'all'

This is used to check compatibility with the deprecated filter_pol field.