fdtdx.CustomTimeSignalProfile

fdtdx.CustomTimeSignalProfile#

class fdtdx.CustomTimeSignalProfile(*, signal=null, time_step_duration=null, start_time=0.0, interpolation='linear', outside_value=0.0)[source]#

Bases: TemporalProfile

Sampled waveform temporal profile for arbitrary time signals.

Stores the source waveform as a pre-computed JAX array and interpolates it at each time step inside the FDTD loop. All signal shaping is done outside JIT before constructing this object.

The sampled signal fully defines the injected time waveform, so the FDTD loop does not apply an additional source-level phase_shift.

Unlike GaussianPulseProfile, this profile does not accept a center_wave or spectral-width parameter. For an arbitrary waveform the spectral centre is not a free parameter — it is an emergent property of the signal (see, e.g., Gedeon et al., IEEE Trans. Antennas Propag. 73(5), 2025). Instead, get_reference_frequency() computes the magnitude-weighted spectral centroid directly from signal, and the frequency axis of any plot is determined automatically from the actual spectrum content via _auto_range().

Quick Reference#

Attributes

Methods

Attributes#

CustomTimeSignalProfile.interpolation: Literal['linear', 'nearest']#

"linear" (default) or "nearest".

Type:

Interpolation mode

CustomTimeSignalProfile.outside_value: float#

Value returned for times outside the sampled window.

CustomTimeSignalProfile.signal: Array#

Pre-sampled waveform, shape (N,). Lives in the pytree so JAX can differentiate through the interpolation if needed.

CustomTimeSignalProfile.start_time: float#

Simulation time at which signal[0] was sampled (seconds).

CustomTimeSignalProfile.time_step_duration: float#

Duration of a single simulation time step (seconds).

Methods#

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

CustomTimeSignalProfile.frequency_spectrum(period, time_step_duration, num_time_steps, phase_shift=0.0, normalize=True)#

Return the one-sided FFT magnitude of the sampled source signal.

Return type:

tuple[ndarray, ndarray]

CustomTimeSignalProfile.get_amplitude(time, period, phase_shift=0.0)[source]#

Calculate the temporal amplitude at given time points.

Parameters:

  • time (jax.Array) – Time points to evaluate amplitude at

  • period (float) – Period of the carrier wave (1/frequency)

  • phase_shift (float) – Phase shift of the carrier wave

Returns:

Amplitude values at the given time points

Return type:

jax.Array

CustomTimeSignalProfile.get_class_fields()#
Return type:

list[TreeClassField]

CustomTimeSignalProfile.get_frequency_plot_range(period, frequencies, spectrum)#

Return a profile-specific frequency plot range, or None to use automatic range detection.

Subclasses may override this hook when the profile has known physical frequency properties (e.g. a Gaussian pulse).

Return type:

tuple[float, float] | None

CustomTimeSignalProfile.get_public_fields()#
Return type:

list[TreeClassField]

CustomTimeSignalProfile.get_reference_frequency(period)[source]#

Return the magnitude-weighted spectral centroid of the stored signal.

The reference frequency is computed as the weighted mean of the non-negative FFT frequency bins, using the magnitude spectrum as weights (G. Peeters, IRCAM Technical Report, 2004). It is used by _auto_range() to anchor the frequency axis of spectrum plots.

Return type:

float

CustomTimeSignalProfile.get_time_plot_range(period, total_time)#

Return a profile-specific time plot range, or None to use automatic range detection.

Subclasses may override this hook when the profile has known physical time properties (e.g. a Gaussian pulse).

Return type:

tuple[float, float] | None

CustomTimeSignalProfile.plot_time_signal_and_spectrum(period, time_step_duration, num_time_steps, phase_shift=0.0, axs=None, filename=None, time_range='auto', frequency_range='auto', relative_threshold=0.01, normalize_spectrum=True)#

Plot the sampled source time signal and its one-sided frequency spectrum.

CustomTimeSignalProfile.sample_time_signal(period, time_step_duration, num_time_steps, phase_shift=0.0)#

Sample this temporal profile at the same cadence as an FDTD simulation.

Return type:

tuple[ndarray, ndarray]

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