fdtdx.ModePlaneSource

class fdtdx.ModePlaneSource(temporal_profile=SingleFrequencyProfile(phase_shift=#3.141592653589793, num_startup_periods=4), *, partial_real_shape=(None, None, None), partial_real_position=(None, None, None), partial_grid_shape=(None, None, None), color=Color(r=0.7764705882352941, g=0.3176470588235294, b=0.00784313725490196), name=None, max_random_real_offsets=(0, 0, 0), max_random_grid_offsets=(0, 0, 0), wave_character=null, static_amplitude_factor=1.0, 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 ), direction=null, azimuth_angle=0.0, elevation_angle=0.0, max_angle_random_offset=0.0, max_vertical_offset=0.0, max_horizontal_offset=0.0, mode_index=0, filter_pol=None, symmetry=(0, 0))

Bases: TFSFPlaneSource

Quick Reference

Attributes

• azimuth_angle

• azimuth_radians

• color

• direction

• elevation_angle

• elevation_radians

• filter_pol

• grid_shape

• grid_slice

• grid_slice_tuple

• horizontal_axis

• max_angle_random_offset

• max_angle_random_offset_radians

• max_horizontal_offset

• max_horizontal_offset_grid

• max_random_grid_offsets

• max_random_real_offsets

• max_vertical_offset

• max_vertical_offset_grid

• mode_index

• name

• partial_grid_shape

• partial_real_position

• partial_real_shape

• propagation_axis

• real_shape

• static_amplitude_factor

• straddled_symmetry_axes

• switch

• symmetry

• symmetry_profile_multiplicity

• temporal_profile

• transverse_axes

• unreduced_grid_shape

• unreduced_grid_slice_tuple

• vertical_axis

• wave_character

Methods

• adjust_time_step_by_on_off

• apply

• aset

• check_overlap

• extend_to

• face_to_face_negative_direction

• face_to_face_positive_direction

• frequency_spectrum

• get_class_fields

• get_public_fields

• is_on_at_time_step

• place_above

• place_at_center

• place_below

• place_on_grid

• place_relative_to

• plot

• plot_time_signal_and_spectrum

• same_position

• same_position_and_size

• same_size

• sample_time_signal

• set_grid_coordinates

• size_relative_to

• straddles_symmetry_plane

• symmetry_mirror_axes

• touches_symmetry_plane

• update_E

• update_H

• validate_placement

Attributes

ModePlaneSource.azimuth_angle: float

the azimuth angle

ModePlaneSource.azimuth_radians

Convert azimuth angle from degrees to radians.

Returns:

Azimuth angle in radians.

Return type:

float

ModePlaneSource.color: Color | None

color of the object

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

Direction of propagation (‘+’ or ‘-’ along propagation axis).

ModePlaneSource.elevation_angle: float

the elevation angle

ModePlaneSource.elevation_radians

Convert elevation angle from degrees to radians.

Returns:

Elevation angle in radians.

Return type:

float

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

a literal value ‘te’, ‘tm’ to filter

ModePlaneSource.grid_shape

ModePlaneSource.grid_slice

ModePlaneSource.grid_slice_tuple

ModePlaneSource.horizontal_axis

ModePlaneSource.max_angle_random_offset: float

the max angle random offset

ModePlaneSource.max_angle_random_offset_radians

Convert maximum random angle offset from degrees to radians.

Returns:

Maximum random angle offset in radians.

Return type:

float

ModePlaneSource.max_horizontal_offset: float

the max horizontal offset

ModePlaneSource.max_horizontal_offset_grid

Return the maximum horizontal random offset in source-center units.

Returns:

On uniform grids this is the legacy grid-index offset. On non-uniform grids source centers are represented in physical transverse coordinates, so the returned value is the requested physical offset in metres.

ModePlaneSource.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.

ModePlaneSource.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.

ModePlaneSource.max_vertical_offset: float

the max vertical offset

ModePlaneSource.max_vertical_offset_grid

Return the maximum vertical random offset in source-center units.

Returns:

On uniform grids this is the legacy grid-index offset. On non-uniform grids source centers are represented in physical transverse coordinates, so the returned value is the requested physical offset in metres.

ModePlaneSource.mode_index: int

index of the mode

ModePlaneSource.name: str

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

ModePlaneSource.partial_grid_shape: PartialGridShape3D

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

ModePlaneSource.partial_real_position: PartialRealShape3D

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

ModePlaneSource.partial_real_shape: PartialRealShape3D

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

ModePlaneSource.propagation_axis

ModePlaneSource.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.

ModePlaneSource.static_amplitude_factor: float

the static amplitude factor

ModePlaneSource.straddled_symmetry_axes

Axes on which this object was clipped by a symmetry plane (see straddles_symmetry_plane).

ModePlaneSource.switch: OnOffSwitch

the on-off switch

ModePlaneSource.symmetry: tuple[int, int]

Symmetry-plane condition at the min edge of each transverse axis (the two non-propagation physical axes, in increasing-index order): 0 = PEC mirror (electric wall, the default), 1 = PMC mirror (magnetic wall). Set this only for a hand-built half/quarter domain (your own PEC/PMC boundary at the min edge), where it asks the mode solver for its own symmetric solve. It is not needed - and is ignored - when config.symmetry performs the reduction: there the mode is solved on the mirrored full cross-section and restricted, which reproduces the full-domain mode exactly (the mode solver’s symmetric solve does not, because FDTDX rasterizes materials per cell while the solver samples them on its staggered grid).

ModePlaneSource.symmetry_profile_multiplicity

Number of copies of this source’s plane in the full domain, 2**k.

k counts the transverse symmetry planes the source straddles. Amplitude normalizations that sum over the source plane (the Gaussian profile normalization, normalize_by_energy) must divide by the full-domain sum, which for a profile that is mirror-symmetric about each of those planes is this factor times the reduced-plane sum. Without it, a symmetry-reduced run would inject 2**(k/2) times the amplitude of the equivalent full-domain run.

ModePlaneSource.temporal_profile: TemporalProfile

the temporal profile, uses single frequency

ModePlaneSource.transverse_axes

The (horizontal, vertical) axis pair of this source’s plane.

ModePlaneSource.unreduced_grid_shape

Grid shape this object would have without mirror-symmetry reduction.

ModePlaneSource.unreduced_grid_slice_tuple

Full-domain slice of this object, in the reduced grid’s coordinate frame.

Identical to grid_slice_tuple unless config.symmetry clipped this object. Where the object crossed a symmetry plane the start index is negative: the plane sits at reduced index 0, so an object that straddled it extends to negative coordinates. Object contents that depend on the object’s full extent (e.g. a Gaussian beam’s centre) must be derived from this slice, not from the clipped one.

Returns:

Per-axis (start, stop) in reduced-grid coordinates.

Return type:

SliceTuple3D

ModePlaneSource.vertical_axis

ModePlaneSource.wave_character: WaveCharacter

the wave-character

Methods

ModePlaneSource.adjust_time_step_by_on_off(time_step)

Return type:

Array

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

Return type:

Self

ModePlaneSource.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

ModePlaneSource.check_overlap(other)

Return type:

bool

ModePlaneSource.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

ModePlaneSource.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

ModePlaneSource.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

ModePlaneSource.frequency_spectrum(config=None, normalize=True)

Return the one-sided FFT magnitude of this source’s sampled time signal.

This is intended for analyzing or visualizing its frequency spectrum.

ModePlaneSource.get_class_fields()

Return type:

list[TreeClassField]

ModePlaneSource.get_public_fields()

Return type:

list[TreeClassField]

ModePlaneSource.is_on_at_time_step(time_step)

Return type:

Array

ModePlaneSource.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

ModePlaneSource.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

ModePlaneSource.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

ModePlaneSource.place_on_grid(grid_slice_tuple, config, key)

Return type:

Self

ModePlaneSource.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

ModePlaneSource.plot(save_path)

ModePlaneSource.plot_time_signal_and_spectrum(config=None, filename=None, **kwargs)

Plot this source’s sampled time signal and one-sided frequency spectrum.

ModePlaneSource.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

ModePlaneSource.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]

ModePlaneSource.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

ModePlaneSource.sample_time_signal(config=None)

Sample this source’s time signal for plotting or analysis.

The returned signal uses the FDTD time grid from the supplied config, or from self._config if the source has already been placed.

ModePlaneSource.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

ModePlaneSource.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

ModePlaneSource.straddles_symmetry_plane(axis)

Whether config.symmetry clipped this object on axis because it crossed the plane.

This is strictly stronger than “the clipped slice starts at index 0”: an object that happens to begin exactly at the symmetry plane but lies entirely inside the kept half was not clipped and must not be treated as mirror-extended.

Parameters:

axis (int) – Physical axis (0=x, 1=y, 2=z).

Returns:

True if the object extends past the symmetry plane into the discarded half.

Return type:

bool

ModePlaneSource.symmetry_mirror_axes(exclude_axis=None)

Axes that must be mirrored to reconstruct this object’s full-domain extent.

Parameters:

exclude_axis (int | None) – Axis to skip, e.g. a plane object’s propagation axis, which is one cell thick and therefore never split by a plane.

Returns:

Straddled symmetry axes, excluding exclude_axis.

Return type:

tuple[int, …]

ModePlaneSource.touches_symmetry_plane(axis)

Whether this object’s placed slice begins on the symmetry plane of axis.

True both for objects clipped by the plane and for objects that merely start there; use straddles_symmetry_plane() to distinguish the two.

Parameters:

axis (int) – Physical axis (0=x, 1=y, 2=z).

Returns:

True if config.symmetry is active on axis and the object sits at its reduced min edge, where the PEC/PMC mirror wall lives.

Return type:

bool

ModePlaneSource.update_E(E, inv_permittivities, inv_permeabilities, time_step, inverse)

Update the electric field component.

Parameters:

• E (jax.Array) – Current electric field array.

• inv_permittivities (jax.Array) – Inverse permittivity values.

• inv_permeabilities (jax.Array | float) – Inverse permeability values.

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

• inverse (bool) – Whether to perform inverse update for backpropagation.

Returns:

Updated electric field array.

Return type:

jax.Array

ModePlaneSource.update_H(H, inv_permittivities, inv_permeabilities, time_step, inverse)

Update the magnetic field component.

Parameters:

• H (jax.Array) – Current magnetic field array.

• inv_permittivities (jax.Array) – Inverse permittivity values.

• inv_permeabilities (jax.Array | float) – Inverse permeability values.

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

• inverse (bool) – Whether to perform inverse update for backpropagation.

Returns:

Updated magnetic field array.

Return type:

jax.Array

ModePlaneSource.validate_placement(objects)

Reject source configurations that a symmetry-reduced domain cannot represent.

A reduced simulation replaces the discarded half by the mirror image of the kept half, so a source clipped by a symmetry plane must itself be mirror-symmetric about it. An off-normal (tilted) beam and a randomly displaced beam both break that, and a plane source sitting on a symmetry plane normal to its own propagation axis would inject into the mirror wall.

Return type:

list[str]

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