`magnelio.signals`#

Signals — excitation waveforms and sampled time series.

A Waveform is the time function an Excitation binds to a port or source (unit peak, known bandwidth and duration); Signal1D is a sampled series on the result side, with its spectrum.

class magnelio.signals.Signal1D(t, values, dt, label='')#

Immutable time-domain signal.

Parameters:

t (np.ndarray) – Time axis [s], shape (N,).
values (np.ndarray) – Signal values, shape (N,).
dt (float) – Time step [s].
label (str) – Optional label for identification.

at_frequencies(f_target)#

Evaluate spectrum at arbitrary frequency points.

Two paths:

Direct DFT (default for small Nf · N): evaluates Σ_n x_n · e^{-2π j f t_n} · dt exactly at every requested frequency. Cost: O(Nf · N). Equivalent in scale to np.fft.rfft (rfft returns Σ_n x_n · e^{-2π j k n / N} without a dt factor; the direct DFT here returns the same magnitude after dividing the Riemann-sum form by dt, i.e. cancels the explicit dt factor).
Zero-padded rFFT + linear interp (fallback for large Nf · N): the historical path; pads so the FFT bin spacing is at most df_target / 2 and linear-interpolates real / imag. Faster for very dense f_target, but introduces a 1–3 % magnitude error when the inter-bin phase rotates significantly (~30° per bin) — manifests as a spurious |S|² < 1 floor in the modal-port S-parameter pipeline. Switching to the direct DFT for small Nf · N eliminates that floor down to floating-point precision.

Parameters:: f_target (np.ndarray) – Target frequencies [Hz].
Returns:: Complex spectrum values at f_target.
Return type:: np.ndarray

property f: ndarray#: Frequency axis [Hz].

property spectrum: ndarray#: Complex FFT spectrum (cached).

class magnelio.signals.Waveform#

Excitation waveform: a unit-peak time function with a bandwidth.

Every waveform is callable — w(t) for a float or an array of times [s] — and describes its own spectral occupancy and duration:

f_max: Upper band edge [Hz]; sizes the time step and the run-length estimate.
f_min: Lower band edge [Hz]; 0 for baseband forms.
f_center: Carrier frequency [Hz], or None for baseband forms. An Excitation may carry a phase only on a waveform with a carrier.
t_end: Time [s] after which the waveform is (effectively) zero; inf for continuous-wave forms, which need an explicit run duration.

The amplitude, delay and phase of a drive live on the Excitation, not here, so a single waveform can drive several ports and sources.

plot(ax=None, *, n=2000, t_max=None, **kwargs)#

Plot the waveform against time.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to draw on; a new figure otherwise.
n (int, default 2000) – Number of samples.
t_max (float, optional) – End of the time axis [s]. Default: t_end for finite forms, ten carrier periods (or ten rise times) for continuous-wave forms.
**kwargs – Forwarded to ax.plot.

Return type:

matplotlib.axes.Axes

sample(dt, n, label='')#

Sample the waveform on t = arange(n) · dt.

Parameters:

dt (float) – Time step [s].
n (int) – Number of samples.
label (str, optional) – Label of the returned signal.

Returns:

The sampled waveform.

Return type:

Signal1D

spectrum(f)#

Continuous-time spectrum ∫ w(t) e^{-2πj f t} dt at frequencies f [Hz].

The same sign convention as Signal1D.at_frequencies(). Closed-form where the waveform has one; otherwise the waveform is sampled to t_end at twenty points per 1/f_max and integrated numerically. Continuous-wave forms (t_end = inf) have no finite-energy spectrum and raise.

Parameters:: f (ndarray)
Return type:: ndarray

class magnelio.signals.WaveformFunction(fn, f_max, f_min=0.0, f_center=None, t_end=inf)#

Waveform from a user function fn(t).

The band edges cannot be read off a Python function, so f_max is required — it sizes the run-length estimate and the warning against exceeding the mesh’s design frequency. A function waveform cannot be stored in a project recipe, so a run driven by it cannot be resumed.

Parameters:

fn (callable) – fn(t) -> value for a float t [s]; may accept arrays.
f_max (float) – Upper band edge [Hz].
f_min (float, default 0.0) – Lower band edge [Hz].
f_center (float, optional) – Carrier frequency [Hz], if the function is a modulated form.
t_end (float, default inf) – Time [s] after which fn is effectively zero; inf marks a continuous-wave form.

class magnelio.signals.WaveformGaussian(f_max)#

Baseband Gaussian pulse (DC-inclusive), unit peak at t = 4 / f_max.

The pulse for TEM and lumped ports and for any source that may carry DC. Its spectrum is a Gaussian of width f_max (the e^{-4} point), so f_max is the useful upper band edge.

Parameters:: f_max (float) – Upper band edge [Hz].

Examples

>>> from magnelio import signals
>>> w = signals.WaveformGaussian(f_max=10e9)
>>> w(4.0 / 10e9)
1.0

spectrum(f)#

Continuous-time spectrum ∫ w(t) e^{-2πj f t} dt at frequencies f [Hz].

The same sign convention as Signal1D.at_frequencies(). Closed-form where the waveform has one; otherwise the waveform is sampled to t_end at twenty points per 1/f_max and integrated numerically. Continuous-wave forms (t_end = inf) have no finite-energy spectrum and raise.

property t_end: float#: Twice the peak time — the pulse is below 1e-17 of its peak there.

class magnelio.signals.WaveformGaussianModulated(f_min, f_max)#

Gaussian envelope on a carrier at the band centre, unit peak.

The band-limited pulse for TE/TM modes and any drive whose lower band edge matters: the envelope’s sigma follows the passband f_max − f_min, so almost no energy leaks below f_min. The carrier sits at (f_min + f_max) / 2, which makes this the waveform an Excitation may phase-shift.

Parameters:

f_min (float) – Lower band edge [Hz].
f_max (float) – Upper band edge [Hz]; must exceed f_min.

Examples

>>> from magnelio import signals
>>> w = signals.WaveformGaussianModulated(f_min=8.2e9, f_max=12.4e9)
>>> w.f_center
10300000000.0

spectrum(f)#

Continuous-time spectrum ∫ w(t) e^{-2πj f t} dt at frequencies f [Hz].

The same sign convention as Signal1D.at_frequencies(). Closed-form where the waveform has one; otherwise the waveform is sampled to t_end at twenty points per 1/f_max and integrated numerically. Continuous-wave forms (t_end = inf) have no finite-energy spectrum and raise.

property f_center: float#

the centre of [f_min, f_max].

Type:: Carrier frequency [Hz]

property t_end: float#: Twice the peak time — the envelope is below 1e-17 of its peak there.

class magnelio.signals.WaveformSine(f, phase=0.0, rise_time=None)#

Continuous-wave sinusoid sin(2π f t + phase), unit amplitude.

A single-frequency drive; zero for t < 0. Its duration is infinite (t_end = inf), so a run driven by it needs an explicit duration and cannot stop on energy decay. With rise_time the amplitude ramps in with a raised-cosine envelope, which keeps the switch-on from exciting the whole band.

Parameters:

f (float) – Frequency [Hz].
phase (float, default 0.0) – Phase [degrees].
rise_time (float, optional) – Length of the raised-cosine switch-on [s]. None (default) switches on hard at t = 0.

class magnelio.signals.WaveformStep(rise_time, hold=None, fall_time=None)#

Raised-cosine step (or pulse), unit plateau.

Rises from 0 to 1 over rise_time; with hold it stays at 1 for that long and falls back over fall_time — a smooth rectangular pulse for time-domain reflectometry. Without hold the plateau lasts forever (t_end = inf), so the run needs an explicit duration. Zero for t < 0.

Parameters:

rise_time (float) – Length of the raised-cosine rise [s]. f_max is 1 / rise_time, the bandwidth the edge occupies.
hold (float, optional) – Plateau duration [s]. None (default) never falls.
fall_time (float, optional) – Length of the fall [s]; defaults to rise_time when hold is given, ignored otherwise.

class magnelio.signals.WaveformTable(t, values, f_max=None, f_min=0.0, f_center=None)#

Tabulated waveform, linearly interpolated between its samples.

Zero outside [t[0], t[-1]]. The band edges default to what the table’s own spectrum shows: f_max is the highest frequency at which the magnitude is still within 40 dB of its peak; give it explicitly when the table is short or noisy.

Parameters:

t (array_like) – Sample times [s], strictly increasing, starting at or after 0.
values (array_like) – Sample values, same length as t.
f_max (float, optional) – Upper band edge [Hz]; estimated from the samples by default.
f_min (float, default 0.0) – Lower band edge [Hz].
f_center (float, optional) – Carrier frequency [Hz] when the table holds a modulated pulse.

magnelio.signals#

`magnelio.signals`#