# Mode Sort Specification

Mode Sort Specification defines how modes are filtered, sorted, and tracked within each frequency.

This object corresponds to tidy3d.ModeSortSpec (opens new window).

Mode sorting is applied in three steps:

  • Filtering: split modes into two groups using filter_key, filter_reference, and filter_order.
  • Sorting: sort modes inside each group using sort_key, sort_reference, and sort_order.
  • Tracking: optionally track the sorted modes across frequency using track_freq.

# Enable Sorting

enable sorting: Toggle whether custom mode sorting controls are used.

  • Options:
    • False: Use the default mode ordering.
    • True: Enable the filter, sort, and tracking controls.

# Mode Sorting Keys

The following keys can be used by both filter_key and sort_key:

  • Options:
    • n_eff: Effective index.
    • k_eff: Effective extinction coefficient.
    • TE_fraction: TE polarization fraction.
    • TM_fraction: TM polarization fraction.
    • wg_TE_fraction: Waveguide TE fraction.
    • wg_TM_fraction: Waveguide TM fraction.
    • mode_area: Mode area.
    • fill_fraction_box: Fraction associated with a specified box.

# Filter Key

filter_key: Quantity used to split modes into two groups before sorting.

# Filter Reference

filter_reference: Reference value used in the filtering stage.

  • Type: float number
  • Default: 0

# Filter Order

filter_order: Select which filtered group is placed first.

  • Options:
    • over: Modes with filter_key values over filter_reference are placed first.
    • under: Modes with filter_key values under filter_reference are placed first.
  • Default: over

# Bounding Box

bounding_box: Box used by metrics such as fill_fraction_box.

  • Default: None

When filter_key or sort_key uses fill_fraction_box, the bounding box is required.

# Keep Modes

keep_modes: Select which modes are kept after filtering.

  • Options:
    • all: Keep all modes. Modes that do not satisfy the filter are appended after the filtered group.
    • filtered: Keep only modes that satisfy the filter.
    • Positive integer: Keep the specified number of modes.
  • Default: all

# Sort Key

sort_key: Quantity used to sort modes within each filtered group.

# Sort Reference

sort_reference: Reference value used for sorting by distance from a target value.

  • Type: float number
  • Default: None

If provided, modes are sorted by the absolute difference between the selected sort_key value and sort_reference.

# Sort Order

sort_order: Sort order for the selected key or for the distance to sort_reference.

  • Options:
    • ascending: Smaller values are placed first.
    • descending: Larger values are placed first.
  • Default: determined by sort_key and sort_reference

If sort_reference is provided, the default is ascending, which places modes closest to the reference first. Otherwise, the default is descending for n_eff, polarization fractions, and fill_fraction_box, and ascending for k_eff and mode_area.

# Track Frequency

track_freq: Frequency used for mode tracking.

  • Options:
    • None: Do not track modes across frequency.
    • central: Track modes using the central frequency as the reference.
    • lowest: Track modes using the lowest frequency as the reference.
    • highest: Track modes using the highest frequency as the reference.
  • Default: central

When tracking is enabled, sorting is exact at the selected reference frequency. At other frequencies, mode order can change according to mode tracking.

← Impedance and Calibration →