terra_dsp package¶
Terra-DSP contains utilities for signal processing used in Terra receivers. In particular, it provides several functions for channelization and abstractions for a variety of radio interfaces.
Subpackages¶
Submodules¶
terra_dsp.Feature module¶
terra_dsp.Station module¶
terra_dsp.channelizer module¶
- terra_dsp.channelizer.compute_pfb_channelizer(chunk_length, ntaps, channels)¶
Designs the prototype low-pass filter for a uniform polyphase filter bank and returns the per-channel tap matrix. The stopband transition width is set to 0.02 / channels (as a fraction of the Nyquist rate) around each channel edge. The filter is designed with scipy.signal.remez (equiripple), then reshaped into a (channels, ntaps // channels) matrix with columns reversed for convolution ordering.
- Parameters:
chunk_length (int) – Length of each input data chunk. Not used.
ntaps (int) – Total number of prototype filter taps. Should be a multiple of channels.
channels (int) – Number of output channels.
- Returns:
polyphase tap matrix
- Return type:
np.ndarray
- terra_dsp.channelizer.cpu_arbfreq_channelizer(data, freqs, fs, stime, rate=15)¶
Runs freq_shift_filter_cpu over a list of arbitrary center frequencies, returning one decimated baseband channel per frequency. Channels are processed sequentially.
- Parameters:
data (array-like complex) – Wideband input IQ block.
freqs (list[float]) – Center frequencies to extract (Hz). One output channel per entry.
fs (float) – Input sample rate.
stime (float) – Start time of block in seconds.
rate (int, optional) – Decimation factor. Defaults to 15.
- Returns:
2D array of baseband data with shape (len(freqs), (N/rate))
- Return type:
np.ndarray, dtype=complex64
- terra_dsp.channelizer.freq_shift_filter_cpu(raw_data, f_bb, fs, stime, rate=15)¶
Pure NumPy/SciPy reference implementation of a single-channel frequency shift and decimation. Generates a time vector from stime, multiplies by the complex LO, then calls scipy.signal.resample_poly for 1:rate downsampling. Useful for validation against the GPU path.
- Parameters:
raw_data (array-like complex) – Input IQ samples.
f_bb (float) – Frequency offset to shift to baseband (Hz).
fs (float) – Input sample rate (Hz).
stime (float) – Absolute start time of block. Used to compute LO phase.
rate (int, optional) – Decimation factor. Defaults to 15.
- Returns:
Decimated baseband data.
- Return type:
np.ndarray, dtype=complex64
- terra_dsp.channelizer.freq_shift_filter_gpu(raw_data, f_bb, fs, stime, ctx=None, queue=None, kernels=None, rate=15)¶
Frequency-shifts a complex IQ signal to baseband and decimates it using a GPU.
- Parameters:
raw_data (array-like complex) – Input IQ samples.
f_bb (float)
f_bb – Baseband frequency offset in Hz.
fs (float) – sample rate.
stime (float) – Block start time. Not currently used
ctx (cl.Context, optional) – Existing OpenCL context. Created from first available platform if None.
queue (cl.CommandQueue, optional) – Existing command queue. Created from ctx if None.
kernels (list[cl.Kernel], optional) – Pre-compiled kernels. Compiled on first call if None.
rate (int, optional) – Integer decimation factor. Defaults to 15.
- Returns:
Decimated, frequency shifted IQ data.
- Return type:
np.ndarray, dtype=complex64
- terra_dsp.channelizer.get_gpu_channelizer_kernel(ctx)¶
Compiles and returns the two OpenCL kernels used by freq_shift_filter_gpu. Call once per context and cache the result to avoid repeated JIT compilation.
- Parameters:
ctx (cl.Context) – An initialized OpenCL context targeting the desired device.
- Returns:
[freq_shift_kernel, polyphase_resample_kernel]
- Return type:
list[cl.Kernel]
- terra_dsp.channelizer.get_pfb_channelizer(taps, channels, channel_mask)¶
Returns a closure that wraps pfb_channelizer with pre-bound taps, channels, and channel_mask arguments. The returned callable has the signature (data, freqs, fs, stime), making it a drop-in replacement for the arbitrary-frequency channelizers, though freqs, fs, and stime are ignored by the PFB implementation.
- Parameters:
taps (np.ndarray) – Polyphase filter bank taps, one row per channel. Typically produced by compute_pfb_channelizer.
channels (int) – Number of uniform frequency channels (FFT size).
channel_mask (array-like int) – Indices of channels to return from the full FFT output.
- Returns:
PFB channelizing function.
- Return type:
callable(data, freqs, fs, stime) -> np.ndarray
- terra_dsp.channelizer.gpu_arbfreq_channelizer(data, freqs, fs, stime, ctx=None, queue=None, kernels=None, rate=15)¶
Runs freq_shift_filter_gpu over a list of arbitrary center frequencies, returning one decimated baseband channel per frequency. Channels are processed sequentially.
- Parameters:
data (array-like complex) – Wideband input IQ block.
freqs (list[float]) – Center frequencies to extract (Hz). One output channel per entry.
fs (float) – Input sample rate.
stime (float) – Start time of block in seconds.
ctx (cl.Context, optional) – OpenCL context, created if None. Defaults to None.
queue (cl.CommandQueue, optional) – Command queue. Not used. Defaults to None.
kernels (list[cl.Kernel], optional) – Pre-compiled kernels; see get_gpu_channelizer_kernel. Defaults to None.
rate (int, optional) – Decimation factor. Defaults to 15.
- Returns:
2D array of baseband data with shape (len(freqs), (N/rate))
- Return type:
np.ndarray, dtype=complex64
- terra_dsp.channelizer.pfb_channelizer(data, taps, channels, channel_mask)¶
Implements a uniform polyphase filter bank channelizer. The input is zero-padded by the filter group delay, split into channels polyphase branches, each branch is filtered with its corresponding row of taps via scipy.signal.lfilter, then a per-branch phase correction is applied before an FFT collapses the branches into channels uniform frequency bins. Only the bins indexed by channel_mask are returned.
- Parameters:
data (np.ndarray) – Wideband input IQ block. Length should be a multiple of channels after padding.
taps (np.ndarray) – Polyphase tap matrix from compute_pfb_channelizer.
channels (int) – Number of frequency channels / FFT size.
channel_mask (array-like int) – Indices into the full FFT output selecting which channels to return.
- Returns:
Complex channel outputs.
- Return type:
np.ndarray
terra_dsp.visualization_tools module¶
- terra_dsp.visualization_tools.plot_prop(center, locations, x=None, y=None, t=None, ref_location=None, pseudoranges=None, prop_delays=None)¶
Function for plotting solutions on a blank map.
- Parameters:
center (list[Latitude, Longitude]) – reference location for plotting
locations (list[list[Latitude, Longitude]]) – List of station locations
x (float, optional) – Horizontal distance between solution and center in meters. Defaults to None.
y (float, optional) – Vertical distance between solution and center in meters. Defaults to None.
t (float, optional) – Time offset between client and reference receiver clocks. Defaults to None.
ref_location (list[Latitude, Longitude], optional) – Location of the reference receiver. Defaults to None.
pseudoranges (list[float], optional) – Pseudoranges in the same order as locations. Defaults to None.
prop_delays (list[float], optional) – For plotting propagation without a solve. Propagation length from station to reference receiver. Defaults to None.
- terra_dsp.visualization_tools.plot_signal_timing(features, rx_length, fs, rx_start, ax=None, show=True)¶
Plots a graph showing the received signal section and the position of features.
- Parameters:
features (dict) – Dictionary mapping StationIDs to Feature objects
rx_length (float) – Received signal length in seconds.
fs (float) – Sample rate
rx_start (float) – Start of rx window.
ax (matplotlib.axes, optional) – Axes for plotting. Created if None.
show (bool, optional) – If True, call plt.show(). Defaults to True.
