setigen

setigen is a Python library for generating and injecting artificial narrow-band signals into radio frequency data, by way of data formats used extensively by the Breakthrough Listen (BL) team @ Berkeley.

The main module of setigen is based on creating synthetic spectrogram (dynamic spectra) data, showing intensity as a function of time and frequency. Observational data saved in filterbank files can be loaded into setigen, and synthetic signals can be easily injected on top and saved out to file. setigen works well with file handling via BL's blimpy package.

The setigen.voltage module enables the synthesis of GUPPI RAW files via synthetic real voltage “observations” and a software signal processing pipeline that implements a polyphase filterbank, mirroring actual BL hardware. The voltage module supports single and multi-antenna RAW files, and can be GPU accelerated via CuPy.

Table of Contents

• Installation
• Spectrogram Format - setigen.Frame
  • Guiding Principles
  • Minimal Working Example
• Cadences
• Raw Voltage Format - setigen.voltage

Installation

You can use pip to install the package automatically:

pip install setigen

Alternately, you can clone the repository and install it directly. At the command line, execute:

git clone git@github.com:bbrzycki/setigen.git python setup.py install

The setigen.voltage module specifically can be GPU accelerated, via CuPy (https://docs.cupy.dev/en/stable/install.html). CuPy is not strictly required to use the voltage module, but it reduces compute time significantly. If CuPy is installed, enable setigen GPU usage either by setting the SETIGEN_ENABLE_GPU environmental variable to 1 or doing so in Python:

import os os.environ['SETIGEN_ENABLE_GPU'] = '1' os.environ['CUDA_VISIBLE_DEVICES'] = '0'

While it isn’t used directly by setigen, you may also find it helpful to install cusignal for access to CUDA-enabled versions of scipy functions when writing custom voltage signal source functions.

Spectrogram Format - setigen.Frame

Guiding Principles

Injecting an artificial signal is as simple as adding it to the data. To fully describe an artificial signal, we need the following:

• Start and stop times (in most cases, this would probably be the beginning and end of the observation, assuming the signal is "on" continuously)
• Frequency center of signal as a function of time sample
• Intensity modulation of signal as a function of time sample
• Frequency structure within each time sample
• Overall intensity modulation as a function of frequency (bandpass)

setigen provides sample functions and shapes for each of these parameters. These all contribute to the final structure of the signal - the goal is to empower the user to generate artificial signals that are as simple or complex as one would like.

Minimal Working Example

Here's an example of synthetic signal generation, using astropy.units to express frame parameters:

``` from astropy import units as u import setigen as stg import matplotlib.pyplot as plt

frame = stg.Frame(fchans=1024, tchans=32, df=2.7939677238464355u.Hz, dt=18.253611008u.s, fch1=6095.214842353016u.MHz) noise = frame.addnoise(xmean=10, noisetype='chi2') signal = frame.addsignal(stg.constantpath(fstart=frame.getfrequency(index=200), driftrate=2u.Hz/u.s), stg.constanttprofile(level=frame.getintensity(snr=30)), stg.gaussianfprofile(width=40*u.Hz), stg.constantbp_profile(level=1))

fig = plt.figure(figsize=(10, 6)) frame.plot() plt.savefig('example.png', bbox_inches='tight') plt.show() ```

This first adds chi-squared noise to the frame, and adds a constant intensity signal at 30 SNR (relative to the background noise). The result is:

Another example, using values found in real observations and visualized in the style of blimpy:

``` from astropy import units as u import setigen as stg import matplotlib.pyplot as plt

frame = stg.Frame(fchans=1024, tchans=16, df=2.7939677238464355u.Hz, dt=18.253611008u.s, fch1=6095.214842353016u.MHz) noise = frame.addnoisefromobs() signal = frame.addsignal(stg.constantpath(fstart=frame.getfrequency(index=200), driftrate=2u.Hz/u.s), stg.constanttprofile(level=frame.getintensity(snr=30)), stg.gaussianfprofile(width=40*u.Hz), stg.constantbp_profile(level=1))

fig = plt.figure(figsize=(10, 6)) frame.plot() plt.show() ```

Cadences

We can arrange a collection of frames as a setigen.Cadence object. This allows one to add noise and signals to multiple frames conveniently and to create publication-ready plots of observational cadences.

Cadence objects support list operations such as slicing and appending. This can be used to manage injection and analysis steps.

As a simple example with fully synthetic frames:

``` mjdstart = 56789 obslength = 300 slew_time = 15

tstartarr = [Time(mjdstart, format='mjd').unix] for i in range(1, 6): tstartarr.append(tstartarr[i - 1] + obslength + slewtime) framelist = [stg.Frame(tchans=16, fchans=256, tstart=tstart_arr[i]) for i in range(6)]

c = stg.Cadence(framelist=framelist) c.apply(lambda fr: fr.addnoise(4e6)) c[0::2].addsignal(stg.constantpath(fstart=c[0].getfrequency(index=128), driftrate=0.2u.Hz/u.s), stg.constanttprofile(level=c[0].getintensity(snr=30)), stg.sinc2f_profile(width=2c[0].df*u.Hz), stg.constantbpprofile(level=1), doppler_smearing=True)

fig = plt.figure(figsize=(10, 10)) c.plot() plt.show() ```

Note that cadence objects don't have an imposed order -- they serve as a bare-bones organizational structure for frames. If you would like to impose an order, use the OrderedCadence:

c = stg.OrderedCadence(frame_list, order="ABACAD")

Ordered cadences additionally allow you to slice cadences by order label:

c.by_label("A")

If cadence frames are in chronological order, when plotting, you may spread subplots in the vertical direction proportionally to slew time with:

c.plot(slew_times=True)

Raw Voltage Format - setigen.voltage

The setigen.voltage module extends setigen to the voltage regime. Instead of directly synthesizing spectrogram data, we can produce real voltages, pass them through a software pipeline based on a polyphase filterbank, and record to file in GUPPI RAW format. In turn, this data can then be reduced as usual using rawspec. As this process models actual hardware used by Breakthrough Listen for recording raw voltages, this enables lower level testing and experimentation. The basic layout of a setigen.voltage pipeline is shown above.

A simple example implementation may be written as follows. For more information, check out the docs.

``` from astropy import units as u import setigen as stg

antenna = stg.voltage.Antenna(samplerate=3e9u.Hz, fch1=6000e6u.Hz, ascending=True, numpols=1)

antenna.x.addnoise(vmean=0, v_std=1)

antenna.x.addconstantsignal(fstart=6002.2e6*u.Hz, driftrate=-2*u.Hz/u.s, level=0.002)

digitizer = stg.voltage.RealQuantizer(targetfwhm=32, numbits=8)

filterbank = stg.voltage.PolyphaseFilterbank(numtaps=8, numbranches=1024)

requantizer = stg.voltage.ComplexQuantizer(targetfwhm=32, numbits=8)

rvb = stg.voltage.RawVoltageBackend(antenna, digitizer=digitizer, filterbank=filterbank, requantizer=requantizer, startchan=0, numchans=64, blocksize=134217728, blocksperfile=128, numsubblocks=32)

rvb.record(outputfilestem='example1block', numblocks=1, lengthmode='numblocks', headerdict={'HELLO': 'testvalue', 'TELESCOP': 'GBT'}, verbose=True) ```

A set of tutorial walkthroughs can be found at: https://github.com/bbrzycki/setigen/tree/main/jupyter-notebooks/voltage.

One unique application of the setigen.voltage pipeline is to ingest IQ data collected from an RTL-SDR dongle and create GUPPI RAW files accordingly: https://github.com/bbrzycki/rtlsdr-to-setigen.