C Extensions¶

Warning

The modules documented before are compiled C extensions and are subject to change. It is recommended that users use the standard modules detailed in the previous sections over directly using these modules.

Go-Fast! Readers¶

Go Fast! (TM) - TBW, TBN, DRX, DR Spectrometer, and VDIF readers written in C

exception lsl.reader._gofast.EOFError¶: Exception raised when a reader encounters the end-of-file while reading.

exception lsl.reader._gofast.SyncError¶: Exception raised when a reader encounters an error with one or more of the four sync. words.

lsl.reader._gofast.read_cor()¶: Function to read in a single COR frame (header+payload) and store the contents as a Frame object.

Changed in version 1.2.1: Updated readCOR for the switch over to 72 channels, complex64 data, and no data weights

New in version 1.2.0.

lsl.reader._gofast.read_drspec()¶: Function to read in a DR spectrometer header structure and data and return a drspec.Frame instance.

Note

This function normalizes the spectra by the number of relevant fills. For products that are a function of more than one primary input, i.e., XY* or I, the minimum fill of X and Y are used for normalization.

lsl.reader._gofast.read_drx()¶: Function to read in a single DRX frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_tbf()¶: Function to read in a single TBW frame (header+data) and store the contents as a Frame object.

New in version 1.2.0.

lsl.reader._gofast.read_tbn()¶: Function to read in a single TBN frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_tbw()¶: Function to read in a single TBW frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_vdif()¶: Function to read in a single VDIF frame (header+payload) and store the contents as a Frame object.

exception lsl.reader._gofast.EOFError¶: Exception raised when a reader encounters the end-of-file while reading.

exception lsl.reader._gofast.SyncError¶: Exception raised when a reader encounters an error with one or more of the four sync. words.

Power Spectral Density Calculation¶

Linear Polarization¶

Extension to take timeseries data and convert it to the frequency domain.

The functions defined in this module are:

FPSD - FFT and integrate function for computing a series of overlapped
Fourier transforms for a real-valued (TBW) or complex-valued (TBN and DRX) signals from a collection of stands all at once.
PFBPSD - Similar to FPSD, but using a 4-tap + Hanning windowed polyphase
filter bank.

See the inidividual functions for more details.

Changed in version 1.3.0: Merged FPSDR and FPSDC into the new FPSD

Changed in version 1.0.1: Removed the polyphase filterbank versions of the four core functions.

lsl.correlator._spec.FPSD()¶

Perform a series of Fourier transforms with windows on data to get the PSD.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 2-D numpy.double (stands by channels) of PSD data

lsl.correlator._spec.PFBPSD()¶

Perform a series of polyphase filter bank transforms (4-tap plus a Hanning window) on data to get the PSD.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 2-D numpy.double (stands by channels) of PSD data

Stokes Parameters¶

Extension to take X and Y timeseries data and create the four Stokes parameters.

The functions defined in this module are:

FPSDR - FFT and integrate function for computing a series of overlapped
Fourier transforms for a real-valued (TBW) or complex-valued (TBN and DRX) signals from a collection of stands all at once.
PFBPSD - Similar to FPSD, but using a 4-tap + Hanning windowed polyphase
filter bank.
XEngine3 - Similar to XEngine2, but works with all linear polarization products at
once to compute all four Stokes parameters.

Also included is an X-Engine for use with the lsl.correlator._core module to perform cross-correlations for the stokes parameters.

See the inidividual functions for more details.

lsl.correlator._stokes.FPSD()¶

Perform a series of Fourier transforms with windows on data to get the PSD for the four Stokes parameters: I, Q, U, and V.

Input arguments are:

signals: 2-D numpy.int16 (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 3-D numpy.double (Stokes parameter (I,Q,U,V) by stands by channels)
of PSD data

lsl.correlator._stokes.PFBPSD()¶

Perform a series of polyphase filter bank transforms (4-tap plus a Hanning window) on data to get the PSD for the four Stokes parameters: I, Q, U, and V.

Input arguments are:

signals: 2-D numpy.int16 (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 3-D numpy.double (Stokes parameter (I,Q,U,V) by stands by channels)
of PSD data

lsl.correlator._stokes.XEngine3()¶

Perform all XMACs for a data stream out of the F engine using OpenMP that creates the four Stokes parameters: I, Q, U, and V.

Input arguments are:

fsignalsX: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignalsY: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
sigValidX: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValidY: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 3-D numpy.cdouble (Stokes parameter (I,Q,U,V by baseline by
channel) array of cross-correlated and averaged visibility data.

FX Correlator Core¶

C-based F and X engines for the LWA software FX correlator. These function are meant to provide an alternative to the lsl.correlator.fx.correlate function and provide a much-needed speed boost to cross-correlation.

The function defined in this module are:

FEngine - F-engine for computing a series of overlapped Fourier transforms with
delay corrections for a real-valued (TBW) or complex valued (TBN or DRX) signals from a collection of stands all at once.
PFBEngine - Similar to FEngine, but using a 4-tap + Hanning windowed polyphase
filter bank.
XEngine2 - Cross multiply a single polarization stream created by FEngine or
PFBEngine
XEngine3 - Similar to XEngine2, but works with all linear polarization products at
once.

See the inidividual functions for more details.

lsl.correlator._core.FEngine()¶

Perform a series of overlapped Fourier transforms on real-valued data using OpenMP and windows.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT
frequency: 1-D numpy.double array of frequency values in Hz for the
FFT channels
delays: 1-D numpy.double array of delays to apply to each stand

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
sample_rate: sample rate of the data (default=196e6)
window: Callable Python function for generating the window or None for no
window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLeve to zero disables time-domain blanking

Outputs:

fsignals: 3-D numpy.complex64 (stands by channels by FFT_set) of FFTd
data
valid: 2-D numpy.uint8 (stands by FFT_set) of whether or not the FFT
set is valid (1) or not (0)

lsl.correlator._core.PFBEngine()¶

Perform a series of overlapped polyphase filter bank transforms (4-tap plus a Hanning window) on real-valued data using OpenMP and windows.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT
frequency: 1-D numpy.double array of frequency values in Hz for the
FFT channels
delays: 1-D numpy.double array of delays to apply to each stand

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
sample_rate: sample rate of the data (default=196e6)
window: Callable Python function for generating the window or None for no
window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLeve to zero disables time-domain blanking

Outputs:

fsignals: 3-D numpy.complex64 (stands by channels by FFT_set) of FFTd
data
valid: 2-D numpy.uint8 (stands by FFT_set) of whether or not the FFT
set is valid (1) or not (0)

lsl.correlator._core.XEngine2()¶

Perform all XMACs for a data stream out of the F engine using OpenMP.

Changed in version 0.5: The second signal is not longer input as a conjugated array. Rather the conjucation is performed as part of the cross-correlation.

Input arguments are:

fsignals1: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignals2: 3-D numpy.complex64 (stand by channels by FFT_set) array of
FFTd data from an F engine.
sigValid1: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValid2: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 2-D numpy.complex64 (baseline by channel) array of cross-
correlated and averaged visibility data.

lsl.correlator._core.XEngine3()¶

Perform all XMACs for a data stream out of the F engine using OpenMP that creates the four linear polarization products

New in version 1.1.2.

Input arguments are:

fsignals1: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignals2: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
sigValid1: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValid2: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 3-D numpy.complex64 (Stokes parameter (XX,XY,YX,YY) by baseline by
channel) array of cross-correlated and averaged visibility data.

DP-Style Signal Processing¶

This module contains a collection of function to speed up FIR filtering of TBW data (represented as numpy.int16 arrays) and the SoftwareDP class. The funtions provided in this module are:

integer16: Apply a FIR filter to numpy.int16 data,

integer16Delayed: Apply a FIFO delay and a FIR filter to numpy.int16 data, and

integerBeamformer: Software implementation of the DP beamformer.

lsl.common._fir.integer16()¶

Given a 1-D numpy.int16 array of data values and a numpy.int16 array of FIR coefficients, apply the coefficients to the data.

Inputs arguments are:

data: 1-D numpy.int16 array of data
coeffs: 1-D numpy.int16 array of FIR coefficients

Outputs:

result: 1-D numpy.float32 array of the filtered data

lsl.common._fir.integer16Delayed()¶

Given a 1-D numpy.int16 array of data values, a numpy.int16 array of FIR coefficients, and a FIFO sample delay, delay the signal and apply the coefficients to the data.

Inputs arguments are:

data: 1-D numpy.int16 array of data
coeffs: 1-D numpy.int16 array of FIR coefficients
sampleDelay: interger number of samples to delay the signal (must be >=0)

Outputs:

result: 1-D numpy.float32 array of the delayed and filtered data

lsl.common._fir.integerBeamformer()¶

Given a 2-D numpy.int16 array (stands by samples) of data values, 3-D array of FIR filter coefficients (stands by filters by taps), a 1-D numpy.int16 array of course (FIFO) delays, a 1-D numpy.int16 array of fine delay FIR filters, and a 2-D array of gains (stands by [XX, XY, YX, YY]), apply the delays and sum the signals.

Inputs arguments are:

data: 2-D numpy.int16 array of data (stands by samples)
coeffs: 3-D numpy.int16 array of FIR coefficients (stands by filters by taps)
course: 1-D numpy.int16 array of FIFO delays in samples
fine: 1-D numpy.int16 array of which FIR filter to apply for fine delay
gain: 2-D numpy.int16 arry of gains (stands by [XX, XY, YX, YY]), where XX is the X
contribution to the output X pol., XY is the X contribution to the output Y pol., YX is the Y contribtion to the output X pol., and YY is the Y contribu- tion to the output Y pol.

Outputs:

results: two element tuple (output X, outpuY) of the beamformer sum. Each element is
a 1-D numpy.float32 array.

Note

The structure of data is assumed to be that the polarizations are ordered, e.g., the X polarization of stand 1 is immediately followed by the Y polarization.