fdtdx.ModeOverlapDetector

class fdtdx.ModeOverlapDetector(*, partial_real_shape=(None, None, None), partial_real_position=(None, None, None), partial_grid_shape=(None, None, None), color=Color(r=0.5882352941176471, g=0.9764705882352941, b=0.4823529411764706), name=None, max_random_real_offsets=(0, 0, 0), max_random_grid_offsets=(0, 0, 0), dtype=<class 'jax.numpy.complex64'>, exact_interpolation=True, inverse=False, switch=OnOffSwitch(   start_time=#None, start_after_periods=#None, end_time=#None, end_after_periods=#None, on_for_time=#None, on_for_periods=#None, period=#None, fixed_on_time_steps=#None, is_always_off=#False, interval=#1 ), if_inverse_plot_backwards=True, num_video_workers=None, plot_interpolation='gaussian', plot_dpi=None, wave_characters=null, reduce_volume=False, scaling_mode='continuous', direction=null, mode_index=0, filter_pol=None, bend_radius=None, bend_axis=None)

Bases: PhasorDetector

Detector for measuring the overlap of a waveguide mode with the simulation fields. This detector computes the overlap of a mode with the phasor fields at a specified frequency, enabling frequency-domain analysis of the electromagnetic fields.

The mode overlap is calculated by integrating the cross product of the mode fields with the simulation fields over a cross-sectional plane. This is useful for analyzing waveguide coupling efficiency, transmission coefficients, and modal decomposition of electromagnetic fields.

Quick Reference

Attributes

• bend_axis

• bend_radius

• color

• components

• direction

• dtype

• exact_interpolation

• filter_pol

• grid_shape

• grid_slice

• grid_slice_tuple

• if_inverse_plot_backwards

• inverse

• max_random_grid_offsets

• max_random_real_offsets

• mode_index

• name

• num_time_steps_recorded

• num_video_workers

• partial_grid_shape

• partial_real_position

• partial_real_shape

• plot

• plot_dpi

• plot_interpolation

• propagation_axis

• real_shape

• reduce_volume

• scaling_mode

• switch

• wave_characters

Methods

• apply

• aset

• check_overlap

• compute_overlap

• compute_overlap_to_mode

• draw_plot

• extend_to

• face_to_face_negative_direction

• face_to_face_positive_direction

• get_class_fields

• get_public_fields

• init_state

• place_above

• place_at_center

• place_below

• place_on_grid

• place_relative_to

• same_position

• same_position_and_size

• same_size

• set_grid_coordinates

• size_relative_to

• update

Attributes

ModeOverlapDetector.bend_axis: int | None

Physical axis index (0=x, 1=y, 2=z) pointing from the waveguide center toward the center of curvature. Must differ from the propagation axis. Required when bend_radius is set.

ModeOverlapDetector.bend_radius: float | None

Bend radius of the waveguide in meters. When set, the mode solver accounts for the conformal transformation introduced by the bend. Must be set together with bend_axis. Defaults to None (straight waveguide).

ModeOverlapDetector.color: Color | None

RGB color for plotting. Defaults to light green.

ModeOverlapDetector.components: Sequence[Literal['Ex', 'Ey', 'Ez', 'Hx', 'Hy', 'Hz']]

Cannot be specified here since the detector needs all components.

ModeOverlapDetector.direction: Literal['+', '-']

Direction of mode propagation, either “+” (forward) or “-” (backward). Determines which direction along the waveguide axis the mode is assumed to propagate.

ModeOverlapDetector.dtype: jnp.dtype

Data type for detector arrays, defaults to float32.

ModeOverlapDetector.exact_interpolation: bool

Whether to use exact field interpolation. Defaults to True.

ModeOverlapDetector.filter_pol: Optional[Literal['te', 'tm']]

Optional polarization filter for the mode calculation. Can be “te” (transverse electric), “tm” (transverse magnetic), or None (no filtering). When specified, only modes of the given polarization type are considered. Defaults to None.

ModeOverlapDetector.grid_shape

ModeOverlapDetector.grid_slice

ModeOverlapDetector.grid_slice_tuple

ModeOverlapDetector.if_inverse_plot_backwards: bool

Plot inverse data in reverse time order.

ModeOverlapDetector.inverse: bool

Whether to record fields in inverse time order. Defaults to false.

ModeOverlapDetector.max_random_grid_offsets: tuple[int, int, int]

Maximum random offset values that can be applied to the object’s position in grid coordinates for each axis (x, y, z). Defaults to (0, 0, 0) for no random offset.

ModeOverlapDetector.max_random_real_offsets: tuple[float, float, float]

Maximum random offset values that can be applied to the object’s position in real coordinates for each axis (x, y, z). Defaults to (0, 0, 0) for no random offset.

ModeOverlapDetector.mode_index: int

Index of the waveguide mode to use for overlap calculation. Defaults to 0 (fundamental mode). Higher indices correspond to higher-order modes.

ModeOverlapDetector.name: str

Unique identifier for the object. Automatically enforced to be unique through the UniqueName validator. The user can also set a name manually.

ModeOverlapDetector.num_time_steps_recorded

Gets the total number of time steps that will be recorded.

Returns:

Number of time steps where detector will record data.

Return type:

int

Raises:

Exception – If detector is not yet initialized.

ModeOverlapDetector.num_video_workers: int | None

Number of workers for video generation. If None (default), then no multiprocessing is used. Note that the combination of multiprocessing and matplotlib is known to produce problems and can cause the entire system to freeze. It does make the video generation much faster though.

ModeOverlapDetector.partial_grid_shape: PartialGridShape3D

The object’s shape in grid coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

ModeOverlapDetector.partial_real_position: PartialRealShape3D

The object’s position in real-world coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

ModeOverlapDetector.partial_real_shape: PartialRealShape3D

The object’s shape in real-world coordinates. Defaults to UNDEFINED_SHAPE_3D if not specified.

ModeOverlapDetector.plot: bool

Cannot be specified here since plotting a single scalar is useless.

ModeOverlapDetector.plot_dpi: int | None

DPI resolution for plots. Defaults to None.

ModeOverlapDetector.plot_interpolation: str

Interpolation method for plots. Defualts to “gaussian”.

ModeOverlapDetector.propagation_axis

ModeOverlapDetector.real_shape

Physical side lengths covered by this object’s placed grid slice.

The value is derived from SimulationConfig.grid when available. That keeps object geometry tied to physical edge coordinates instead of a global scalar resolution. During early placement, before a concrete grid has been attached to the config, the legacy uniform-resolution fallback is still used for compatibility.

ModeOverlapDetector.reduce_volume: bool

If True, reduces the volume of recorded data. Defaults to False.

ModeOverlapDetector.scaling_mode: Literal['continuous', 'pulse']

Scaling of the resulting phasor. In continuous mode, the result is scaled by a factor of 2 / N, where N is the number of time steps recorded. This allows accurate reconstruction of a continuous signal. In pulse mode, the result is not scaled.

ModeOverlapDetector.switch: OnOffSwitch

This switch controls the time steps that the detector is on, i.e. records data. Defaults to all time steps.

ModeOverlapDetector.wave_characters: Sequence[WaveCharacter]

WaveCharacters to analyze.

Methods

ModeOverlapDetector.apply(key, inv_permittivities, inv_permeabilities, dispersive_c1=None, dispersive_c2=None, dispersive_c3=None)

Return type:

Self

ModeOverlapDetector.aset(attr_name, val, create_new_ok=False)

Sets an attribute of this class. In contrast to the classical .at[].set(), this method updates the class attribute directly and does not only operate on jax pytree leaf nodes. Instead, replaces the full attribute with the new value.

The attribute can either be the attribute name of this class, or for nested classes it can also be the attribute name of a class, which itself is an attribute of this class. The syntax for this operation could look like this: “a->b->[0]->[‘name’]”. Here, the current class has an attribute a, which has an attribute b, which is a list, which we index at index 0, which is an element of type dictionary, which we index using the dictionary key ‘name’.

Note that dictionary keys cannot contain square brackets or single quotes (even if they are escaped).

Parameters:

• attr_name (str) – Name of attribute to set

• val (Any) – Value to set the attribute to

• create_new_ok (bool, optional) – If false (default), throw an error if the attribute does not exist. If true, creates a new attribute if the attribute name does not exist yet.

Returns:

Updated instance with new attribute value

Return type:

Self

ModeOverlapDetector.check_overlap(other)

Return type:

bool

ModeOverlapDetector.compute_overlap(state)

Return type:

Array

ModeOverlapDetector.compute_overlap_to_mode(state, mode_E, mode_H)

Return type:

Array

ModeOverlapDetector.draw_plot(state, progress=None)

Generates plots or videos from recorded detector data.

Creates visualizations based on dimensionality of recorded data and detector configuration. Supports 1D line plots, 2D heatmaps, and video generation for time-varying data.

Parameters:

• state (dict[str, np.ndarray]) – Dictionary containing recorded field data arrays.

• progress (Progress | None, optional) – Optional progress bar for video generation.

Returns:

Dictionary mapping plot names to either

matplotlib Figure objects or paths to generated video files.

Return type:

dict[str, Figure | str]

ModeOverlapDetector.extend_to(other, axis, direction, other_position=None, offset=0, grid_offset=0)

Creates a SizeExtensionConstraint that extends this object along a specified axis until it reaches another object or the simulation boundary. The extension can be in either positive or negative direction.

Parameters:

• other (str | None) – Target object to extend to, or None to extend to simulation boundary

• axis (int) – Which axis to extend along (0, 1, or 2)

• direction (Literal["+", "-"]) – Direction to extend in (‘+’ or ‘-‘)

• other_position (float | None, optional) – Relative position on target object (-1 to 1) to extend to. If None, defaults to the corresponding side (-1 for ‘+’ direction, 1 for ‘-’ direction). Defaults to None.

• offset (float, optional) – Additional offset in meters to apply after extension. Ignored when extending to simulation boundary. Defaults to zero.

• grid_offset (int, optional) – Additional offset in Yee-grid voxels to apply after extension. Ignored when extending to simulation boundary. Defaults to zero.

Returns:

Constraint defining how the object extends

Return type:

SizeExtensionConstraint

ModeOverlapDetector.face_to_face_negative_direction(other, axes, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object facing another object in the negative direction of specified axes. The objects will touch at their facing boundaries unless margins are specified.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to align on

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint aligning objects face-to-face in negative direction

Return type:

PositionConstraint

ModeOverlapDetector.face_to_face_positive_direction(other, axes, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object facing another object in the positive direction of specified axes. The objects will touch at their facing boundaries unless margins are specified.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to align on

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between the facing surfaces. Must have same length as axes. If None, no margin is used. Defaults to None

Returns:

Position constraint aligning objects face-to-face in positive direction

Return type:

PositionConstraint

ModeOverlapDetector.get_class_fields()

Return type:

list[TreeClassField]

ModeOverlapDetector.get_public_fields()

Return type:

list[TreeClassField]

ModeOverlapDetector.init_state()

Return type:

dict[str, Array]

ModeOverlapDetector.place_above(other, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object above another object along the z-axis. This is a convenience wrapper around face_to_face_positive_direction() for axis 2 (z-axis).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• margins (tuple[float, ...] | float | None, optional) – Additional vertical margins in meters between objects. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional vertical margins in Yee-grid voxels between objects. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing this object above the other

Return type:

PositionConstraint

ModeOverlapDetector.place_at_center(other, axes=(0, 1, 2), own_positions=None, other_positions=None, margins=None, grid_margins=None)

Creates a PositionConstraint that centers this object relative to another object along specified axes. This is a convenience wrapper around place_relative_to() with default positions at the center (0).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to center on. Defaults to all axes (0, 1, 2).

• own_positions (tuple[float, ...] | float | None, optional) – Relative positions on this object (-1 to 1). If None, uses center (0). Defaults to None.

• other_positions (tuple[float, ...] | float | None, optional) – Relative positions on other object (-1 to 1). If None, uses center (0). Defaults to None.

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint centering objects relative to each other

Return type:

PositionConstraint

ModeOverlapDetector.place_below(other, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object below another object along the z-axis. This is a convenience wrapper around face_to_face_negative_direction() for axis 2 (z-axis).

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• margins (tuple[float, ...] | float | None, optional) – Additional vertical margins in meters between objects. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional vertical margins in Yee-grid voxels between objects. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing this object below the other

Return type:

PositionConstraint

ModeOverlapDetector.place_on_grid(grid_slice_tuple, config, key)

Return type:

Self

ModeOverlapDetector.place_relative_to(other, axes, own_positions, other_positions, margins=None, grid_margins=None)

Creates a PositionalConstraint between two objects. The constraint is defined by anchor points on both objects, which are constrained to be at the same position. Anchors are defined in relative coordinates, i.e. a position of -1 is the left object boundary in the respective axis and a position of +1 the right boundary.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Eiter a single integer or a tuple describing the axes of the constraints

• own_positions (tuple[float, ...] | float) – The positions of the own anchor in the axes. Must have the same lengths as axes

• other_positions (tuple[float, ...] | float) – The positions of the other objects’ anchor in the axes. Must have the same lengths as axes

• margins (tuple[float, ...] | float | None, optional) – The margins between the anchors of both objects in meters. Must have the same lengths as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – The margins between the anchors of both objects in Yee-grid voxels. Must have the same lengths as axes. If none, no margin is used. Defaults to None.

Returns:

Positional constraint between this object and the other

Return type:

PositionConstraint

ModeOverlapDetector.same_position(other, axes=(0, 1, 2), own_positions=None, other_positions=None, margins=None, grid_margins=None)

Creates a PositionConstraint that places this object at the same position as another object. This is a convenience wrapper around place_at_center() for more intuitive naming.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to match position on. Defaults to all axes (0, 1, 2).

• own_positions (tuple[float, ...] | float | None, optional) – Relative positions on this object (-1 to 1). If None, uses center (0). Defaults to None.

• other_positions (tuple[float, ...] | float | None, optional) – Relative positions on other object (-1 to 1). If None, uses center (0). Defaults to None.

• margins (tuple[float, ...] | float | None, optional) – Additional margins in meters between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

• grid_margins (tuple[int, ...] | int | None, optional) – Additional margins in Yee-grid voxels between objects. Must have same length as axes. If None, no margin is used. Defaults to None.

Returns:

Position constraint placing objects at the same position

Return type:

PositionConstraint

ModeOverlapDetector.same_position_and_size(other, axes=(0, 1, 2))

Creates both position and size constraints to make this object match another object’s position and size. This is a convenience wrapper combining place_at_center() and same_size().

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes to match. Defaults to all axes (0, 1, 2).

Returns:

Position and size constraints for matching objects

Return type:

tuple[PositionConstraint, SizeConstraint]

ModeOverlapDetector.same_size(other, axes=(0, 1, 2), offsets=None, grid_offsets=None)

Creates a SizeConstraint that makes this object the same size as another object along specified axes. This is a convenience wrapper around size_relative_to() with proportions set to 1.0.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int, optional) – Either a single integer or a tuple describing which axes should have the same size. Defaults to all axes (0, 1, 2).

• offsets (tuple[float, ...] | float | None, optional) – Additional size offsets in meters to apply. Must have same length as axes. If None, no offset is used. Defaults to None.

• grid_offsets (tuple[int, ...] | int | None, optional) – Additional size offsets in Yee-grid voxels to apply. Must have same length as axes. If None, no offset is used. Defaults to None.

Returns:

Size constraint ensuring equal sizes between objects

Return type:

SizeConstraint

ModeOverlapDetector.set_grid_coordinates(axes, sides, coordinates)

Creates a GridCoordinateConstraint that forces specific sides of this object to align with given grid coordinates. Used for precise positioning in the discretized simulation space.

Parameters:

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes to constrain

• sides (tuple[Literal["+", "-"], ...] | Literal["+", "-"]) – Either a single string or a tuple of strings (‘+’ or ‘-’) indicating which side of each axis to constrain. Must have same length as axes.

• coordinates (tuple[int, ...] | int) – Either a single integer or a tuple of integers specifying the grid coordinates to align with. Must have same length as axes.

Returns:

Constraint forcing alignment with specific grid coordinates

Return type:

GridCoordinateConstraint

ModeOverlapDetector.size_relative_to(other, axes, other_axes=None, proportions=None, offsets=None, grid_offsets=None)

Creates a SizeConstraint between two objects. The constraint defines the size of this object relative to another object, allowing for proportional scaling and offsets in specified axes.

Parameters:

• other (SimulationObject) – Another object in the simulation scene

• axes (tuple[int, ...] | int) – Either a single integer or a tuple describing which axes of this object to constrain.

• other_axes (tuple[int, ...] | int | None, optional) – Either a single integer or a tuple describing which axes of the other object to reference. If None, uses the same axes as specified in ‘axes’. Defaults to None.

• proportions (tuple[float, ...] | float | None, optional) – Scale factors to apply to the other object’s dimensions. Must have same length as axes. If None, uses 1.0 (same size). Defaults to None.

• offsets (tuple[float, ...] | float | None, optional) – Additional size offsets in meters to apply after scaling. Must have same length as axes. If None, no offset is used. Defaults to None.

• grid_offsets (tuple[int, ...] | int | None, optional) – Additional size offsets in Yee-grid voxels to apply after scaling. Must have same length as axes. If None, no offset is used. Defaults to None.

Returns:

Size constraint between this object and the other

Return type:

SizeConstraint

ModeOverlapDetector.update(time_step, E, H, state, inv_permittivity, inv_permeability)

Updates detector state with current field values.

Parameters:

• time_step (jax.Array) – Current simulation time step.

• E (jax.Array) – Electric field array.

• H (jax.Array) – Magnetic field array.

• state (DetectorState) – Current detector state.

• inv_permittivity (jax.Array) – Inverse permittivity array.

• inv_permeability (jax.Array | float) – Inverse permeability array.

Returns:

Updated detector state.

Return type:

DetectorState

If you find any errors in the documentation, please report them in the Github Issues!