setigen.voltage API reference

setigen.voltage.backend module

class setigen.voltage.backend.RawVoltageBackend(antenna_source, digitizer, filterbank, requantizer, start_chan=0, num_chans=64, block_size=134217728, blocks_per_file=128, num_subblocks=32)

Bases: object

Central class that wraps around antenna sources and backend elements to facilitate the creation of GUPPI RAW voltage files from synthetic real voltages.

__init__(antenna_source, digitizer, filterbank, requantizer, start_chan=0, num_chans=64, block_size=134217728, blocks_per_file=128, num_subblocks=32)

Initialize a RawVoltageBackend object, with an input antenna source (either Antenna or MultiAntennaArray), and backend elements (digitizer, filterbank, requantizer). Also, details behind the RAW file format and recording are specified on initialization, such as which coarse channels are saved and the size of recording blocks.

Parameters:

• antenna_source (Antenna or MultiAntennaArray) – Antenna or MultiAntennaArray, from which real voltage data is created

• digitizer (RealQuantizer or ComplexQuantizer, or list) – Quantizer used to digitize input voltages. Either a single object to be used as a template for each antenna and polarization, or a 2D list of quantizers of shape (num_antennas, num_pols).

• filterbank (PolyphaseFilterbank, or list) – Polyphase filterbank object used to channelize voltages. Either a single object to be used as a template for each antenna and polarization, or a 2D list of filterbank objects of shape (num_antennas, num_pols).

• requantizer (ComplexQuantizer, or list) – Quantizer used on complex channelized voltages. Either a single object to be used as a template for each antenna and polarization, or a 2D list of quantizers of shape (num_antennas, num_pols).

• start_chan (int, optional) – Index of first coarse channel to be recorded

• num_chans (int, optional) – Number of coarse channels to be recorded

• block_size (int, optional) – Recording block size, in bytes

• blocks_per_file (int, optional) – Number of blocks to be saved per RAW file

• num_subblocks (int, optional) – Number of partitions per block, used for computation. If num_subblocks=1, one block’s worth of data will be passed through the pipeline and recorded at once. Use this parameter to reduce memory load, especially when using GPU acceleration.

classmethod from_data(input_file_stem, antenna_source, digitizer, filterbank, start_chan=0, num_subblocks=32)

Initialize a RawVoltageBackend object, using existing RAW data as a background for signal insertion and recording. Compared to normal initialization, some parameters are inferred from the input data.

Parameters:

• input_file_stem (str) – Filename or path stem to input RAW data

• antenna_source (Antenna or MultiAntennaArray) – Antenna or MultiAntennaArray, from which real voltage data is created

• digitizer (RealQuantizer or ComplexQuantizer, or list) – Quantizer used to digitize input voltages. Either a single object to be used as a template for each antenna and polarization, or a 2D list of quantizers of shape (num_antennas, num_pols).

• filterbank (PolyphaseFilterbank, or list) – Polyphase filterbank object used to channelize voltages. Either a single object to be used as a template for each antenna and polarization, or a 2D list of filterbank objects of shape (num_antennas, num_pols).

• start_chan (int, optional) – Index of first coarse channel to be recorded

• num_subblocks (int, optional) – Number of partitions per block, used for computation. If num_subblocks=1, one block’s worth of data will be passed through the pipeline and recorded at once. Use this parameter to reduce memory load, especially when using GPU acceleration.

Returns:

backend – Created backend object

Return type:

RawVoltageBackend

collect_data_block(digitize=True, requantize=True, verbose=True)

General function to actually collect data from the antenna source and return coarsely channelized complex voltages. Collects one block of data.

Parameters:

• digitize (bool, optional) – Whether to quantize input voltages before the PFB

• requantize (bool, optional) – Whether to quantize output complex voltages after the PFB

• verbose (bool, optional) – Control whether tqdm prints progress messages

Returns:

final_voltages – Complex voltages formatted according to GUPPI RAW specifications; array of shape (num_chans * num_antennas, block_size / (num_chans * num_antennas))

Return type:

array

get_num_blocks(obs_length)

Calculate the number of blocks required as a function of observation length, in seconds. Note that only an integer number of blocks will be recorded, so the actual observation length may be shorter than the obs_length provided.

record(output_file_stem, obs_length=None, num_blocks=None, length_mode='obs_length', header_dict={}, digitize=True, load_template=True, verbose=True)

General function to actually collect data from the antenna source and return coarsely channelized complex voltages. If input data is provided, only as much data as is in the input will be generated.

Parameters:

• output_file_stem (str) – Filename or path stem; the suffix will be automatically appended

• obs_length (float, optional) – Length of observation in seconds, if in ‘obs_length’ mode

• num_blocks (int, optional) – Number of data blocks to record, if in ‘num_blocks’ mode

• length_mode (str, optional) – Mode for specifying length of observation, either ‘obs_length’ in seconds or ‘num_blocks’ in data blocks

• header_dict (dict, optional) – Dictionary of header values to set. Use to overwrite non-essential header values or add custom ones.

• digitize (bool, optional) – Whether to quantize input voltages before the PFB

• verbose (bool, optional) – Control whether tqdm prints progress messages

• load_template (bool, optional) – Control whether the internal header template’s keys are used.

setigen.voltage.backend.get_block_size(num_antennas=1, tchans_per_block=128, num_bits=8, num_pols=2, num_branches=1024, num_chans=64, fftlength=1024, int_factor=4)

Calculate block size, given a desired number of time bins per RAW data block tchans_per_block. Takes in backend parameters, including fine channelization factors. Can be used to calculate reasonable block sizes for raw voltage recording.

Parameters:

• num_antennas (int) – Number of antennas

• tchans_per_block (int) – Final number of time bins in fine resolution product, per data block

• num_bits (int) – Number of bits in requantized data (for saving into file). Can be 8 or 4.

• num_pols (int) – Number of polarizations recorded

• num_branches (int) – Number of branches in polyphase filterbank

• num_chans (int) – Number of coarse channels written to file

• fftlength (int) – FFT length to be used in fine channelization

• int_factor (int, optional) – Integration factor to be used in fine channelization

Returns:

block_size – Block size, in bytes

Return type:

int

setigen.voltage.backend.get_total_obs_num_samples(obs_length=None, num_blocks=None, length_mode='obs_length', num_antennas=1, sample_rate=3000000000.0, block_size=134217728, num_bits=8, num_pols=2, num_branches=1024, num_chans=64)

Calculate number of required real voltage time samples for as given obs_length or num_blocks, without directly using a RawVoltageBackend object.

Parameters:

• obs_length (float, optional) – Length of observation in seconds, if in ‘obs_length’ mode

• num_blocks (int, optional) – Number of data blocks to record, if in ‘num_blocks’ mode

• length_mode (str, optional) – Mode for specifying length of observation, either ‘obs_length’ in seconds or ‘num_blocks’ in data blocks

• num_antennas (int) – Number of antennas

• sample_rate (float) – Sample rate in Hz

• block_size (int) – Block size used in recording GUPPI RAW files

• num_bits (int) – Number of bits in requantized data (for saving into file). Can be 8 or 4.

• num_pols (int) – Number of polarizations recorded

• num_branches (int) – Number of branches in polyphase filterbank

• num_chans (int) – Number of coarse channels written to file

Returns:

num_samples – Number of samples

Return type:

int

setigen.voltage.antenna module

class setigen.voltage.antenna.Antenna(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, num_pols=2, t_start=0, seed=None, **kwargs)

Bases: object

Models a radio antenna, with a DataStream per polarization (one or two).

__init__(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, num_pols=2, t_start=0, seed=None, **kwargs)

Initialize an Antenna object, which creates DataStreams for each polarization, under Antenna.x and Antenna.y (if there is a second polarization).

Parameters:

• sample_rate (float, optional) – Physical sample rate, in Hz, for collecting real voltage data

• fch1 (astropy.Quantity, optional) – Central frequency of the first coarse channel, in Hz. If ascending=True, fch1 is the minimum frequency; if ascending=False (default), fch1 is the maximum frequency.

• ascending (bool, optional) – Specify whether frequencies should be in ascending or descending order. Default is True, for which fch1 is the minimum frequency.

• num_pols (int, optional) – Number of polarizations, can be 1 or 2

• t_start (float, optional) – Start time, in seconds

• seed (None, int, Generator, optional) – Random seed or seed generator

set_time(t)

Set start time before next set of samples.

add_time(t)

Add time before next set of samples.

reset_start()

Reset the boolean that tracks whether this is the start of an observation.

get_samples(num_samples)

Retrieve voltage samples from each polarization.

Parameters:

num_samples (int) – Number of samples to get

Returns:

samples – Array of voltage samples, of shape (1, num_pols, num_samples)

Return type:

array

class setigen.voltage.antenna.MultiAntennaArray(num_antennas, sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, num_pols=2, delays=None, t_start=0, seed=None, **kwargs)

Bases: object

Models a radio antenna array, with list of Antennas, subject to user-specified sample delays.

__init__(num_antennas, sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, num_pols=2, delays=None, t_start=0, seed=None, **kwargs)

Initialize a MultiAntennaArray object, which creates a list of Antenna objects, each with a specified relative integer sample delay. Also creates background DataStreams to model coherent noise present in each Antenna, subject to that Antenna’s delay.

Parameters:

• num_antennas (int) – Number of Antennas in the array

• sample_rate (float, optional) – Physical sample rate, in Hz, for collecting real voltage data

• fch1 (astropy.Quantity, optional) – Central frequency of the first coarse channel, in Hz. If ascending=True, fch1 is the minimum frequency; if ascending=False (default), fch1 is the maximum frequency.

• ascending (bool, optional) – Specify whether frequencies should be in ascending or descending order. Default is True, for which fch1 is the minimum frequency.

• num_pols (int, optional) – Number of polarizations, can be 1 or 2

• delays (array, optional) – Array of integers specifying relative delay offsets per array with respect to the coherent antenna array background. If None, uses 0 delay for all Antennas.

• t_start (float, optional) – Start time, in seconds

• seed (None, int, Generator, optional) – Random seed or seed generator

set_time(t)

Set start time before next set of samples.

add_time(t)

Add time before next set of samples.

reset_start()

Reset the boolean that tracks whether this is the start of an observation.

get_samples(num_samples)

Retrieve voltage samples from each antenna and polarization.

First, background data stream voltages are computed. Then, for each Antenna, voltages are retrieved per polarization and summed with the corresponding background voltages, subject to that Antenna’s sample delay. An appropriate number of background voltage samples are cached with the Antenna, according to the delay, so that regardless of num_samples, each Antenna data stream has enough background samples to add.

Parameters:

num_samples (int) – Number of samples to get

Returns:

samples – Array of voltage samples, of shape (num_antennas, num_pols, num_samples)

Return type:

array

setigen.voltage.data_stream module

class setigen.voltage.data_stream.DataStream(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, t_start=0, seed=None)

Bases: object

Facilitate noise and signal injection in a real voltage time series data stream, for a single polarization. Noise and signal sources are functions, saved as properties of the DataStream, so that individual samples can be queried using get_samples().

__init__(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, t_start=0, seed=None)

Initialize a DataStream object with a sampling rate and frequency range.

By default, setigen.voltage does not employ heterodyne mixing and filtering to focus on a frequency bandwidth. Instead, the sensitive range is determined by these parameters; starting at the frequency fch1 and spanning the Nyquist range sample_rate / 2 in the increasing or decreasing frequency direction, as specified by ascending. Note that accordingly, the spectral response will be susceptible to aliasing, so take care that the desired frequency range is correct and that signals are injected at appropriate frequencies.

Parameters:

• sample_rate (float, optional) – Physical sample rate, in Hz, for collecting real voltage data

• fch1 (astropy.Quantity, optional) – Central frequency of the first coarse channel, in Hz. If ascending=True, fch1 is the minimum frequency; if ascending=False (default), fch1 is the maximum frequency.

• ascending (bool, optional) – Specify whether frequencies should be in ascending or descending order. Default is True, for which fch1 is the minimum frequency.

• t_start (float, optional) – Start time, in seconds

• seed (None, int, Generator, optional) – Random seed or seed generator

rng

Random number generator

set_time(t)

Set start time before next set of samples.

add_time(t)

Add time before next set of samples.

update_noise(stats_calc_num_samples=10000)

Replace self.noise_std by calculating out a few samples and estimating the standard deviation of the voltages.

Parameters:

stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise standard deviation

get_total_noise_std()

Get the standard deviation of the noise. If this DataStream is part of an array of Antennas, this will account for the background noise in the corresponding polarization.

Note that if this DataStream has custom signals or noise, it might not ‘know’ what the noise standard deviation is. In this case, one should run update_noise() to update the DataStream’s estimate for the noise. Note that this actually runs get_samples() for the calculation, so if your custom signal functions have mutable properties, make sure to reset these (if necessary) before saving out data.

add_noise(v_mean, v_std)

Add Gaussian noise source to data stream. This essentially adds a lambda function that gets the appropriate number of noise samples to add to the voltage array when get_samples() is called. Updates noise property to reflect added noise.

Parameters:

• v_mean (float) – Noise mean

• v_std (float) – Noise standard deviation

add_constant_signal(f_start, drift_rate, level, phase=0)

Adds a drifting cosine signal (linear chirp) as a signal source function.

Parameters:

• f_start (float) – Starting signal frequency

• drift_rate (float) – Drift rate in Hz / s

• level (float) – Signal level or amplitude

• phase (float) – Phase, in radiations

add_signal(signal_func)

Wrapper function to add a custom signal source function.

get_samples(num_samples)

Retrieve voltage samples, based on noise and signal source functions.

If custom signals add complex voltages, the voltage array will be cast to complex type.

Parameters:

num_samples (int) – Number of samples to get

Returns:

v – Array of voltage samples

Return type:

array

class setigen.voltage.data_stream.BackgroundDataStream(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, t_start=0, seed=None, antenna_streams=[])

Bases: DataStream

Extends DataStream for background data in Antenna arrays.

__init__(sample_rate=<Quantity 3. GHz>, fch1=<Quantity 0. GHz>, ascending=True, t_start=0, seed=None, antenna_streams=[])

Initialize a BackgroundDataStream object with a sampling rate and frequency range. The main extension is that we also pass in a list of DataStreams, belonging to all the Antennas within a MultiAntennaArray, for the same corresponding polarization. When noise is added to a BackgroundDataStream, the noise standard deviation gets propagated to each Antenna DataStream via the DataStream.bg_noise_std property.

Parameters:

• sample_rate (float, optional) – Physical sample rate, in Hz, for collecting real voltage data

• fch1 (astropy.Quantity, optional) – Central frequency of the first coarse channel, in Hz. If ascending=True, fch1 is the minimum frequency; if ascending=False (default), fch1 is the maximum frequency.

• ascending (bool, optional) – Specify whether frequencies should be in ascending or descending order. Default is True, for which fch1 is the minimum frequency.

• t_start (float, optional) – Start time, in seconds

• seed (int, optional) – Integer seed between 0 and 2**32. If None, the random number generator will use a random seed.

• antenna_streams (list of DataStream objects) – List of DataStreams, which belong to the Antennas in a MultiAntennaArray, all corresponding to the same polarization

update_noise(stats_calc_num_samples=10000)

Replace self.noise_std by calculating out a few samples and estimating the standard deviation of the voltages. Further, set all child antenna background noise values.

Parameters:

stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise standard deviation

add_noise(v_mean, v_std)

Add Gaussian noise source to data stream. This essentially adds a lambda function that gets the appropriate number of noise samples to add to the voltage array when get_samples() is called. Updates noise property to reflect added noise. Further, set all child antenna background noise values.

Parameters:

• v_mean (float) – Noise mean

• v_std (float) – Noise standard deviation

setigen.voltage.data_stream.estimate_stats(voltages, stats_calc_num_samples=10000)

Estimate mean and standard deviation, truncating to at most stats_calc_num_samples samples to reduce computation.

Parameters:

• voltages (array) – Array of voltages

• stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise statistics

Returns:

• data_mean (float) – Mean of voltages

• data_sigma (float) – Standard deviation of voltages

setigen.voltage.polyphase_filterbank module

class setigen.voltage.polyphase_filterbank.PolyphaseFilterbank(num_taps=8, num_branches=1024, window_fn='hamming')

Bases: object

Implement a polyphase filterbank (PFB) for coarse channelization of real voltage input data.

Follows description in Danny C. Price, Spectrometers and Polyphase Filterbanks in Radio Astronomy, 2016. Available online at: http://arxiv.org/abs/1607.03579.

__init__(num_taps=8, num_branches=1024, window_fn='hamming')

Initialize a polyphase filterbank object, with a voltage sample cache that ensures that consecutive sample retrievals get contiguous data (i.e. without introduced time delays).

Parameters:

• num_taps (int, optional) – Number of PFB taps

• num_branches (int, optional) – Number of PFB branches. Note that this results in num_branches / 2 coarse channels.

• window_fn (str, optional) – Windowing function used for the PFB

estimate_channelized_stds(factor=10000, seed=None)

Estimate standard deviations in real and imaginary components after channelizing a zero-mean Gaussian distribution with variance 1.

Parameters:

• factor (int, default : 10000) – Use factor * num_branches samples for estimation

• seed (None, int, Generator, optional) – Random seed or seed generator

Returns:

channelized_stds – Array of standard deviation estimates

Return type:

array

get_response(fftlength=512)

Saves frequency response shape and ratio of maximum to mean of the frequency response.

Parameters:

fftlength (int, default : 512) – FFT length used in fine channelization, which must be a multiple of num_taps (fftlength = factor * num_taps)

Returns:

response – Half-coarse channel frequency response

Return type:

array

tile_response(num_chans, fftlength=512)

Construct tiled PFB frequency response.

Parameters:

• num_chans (int) – Number of coarse channels to tile

• fftlength (int, default : 512) – FFT length used in fine channelization, which must be a multiple of num_taps (fftlength = factor * num_taps)

Returns:

response – Multiple coarse channel frequency response

Return type:

array

channelize(x, cache=True)

Channelize input voltages by applying the PFB and taking a normalized FFT.

Parameters:

• x (array) – Array of voltages

• cache (bool, default : True) – Option to cache last section of data, which is excluded in PFB step

Returns:

X_pfb – Post-FFT complex voltages

Return type:

array

setigen.voltage.polyphase_filterbank.pfb_frontend(x, pfb_window, num_taps, num_branches)

Apply windowing function to create polyphase filterbank frontend.

Follows description in Danny C. Price, Spectrometers and Polyphase Filterbanks in Radio Astronomy, 2016. Available online at: http://arxiv.org/abs/1607.03579.

Parameters:

• x (array) – Array of voltages

• pfb_window (array) – Array of PFB windowing coefficients

• num_taps (int) – Number of PFB taps

• num_branches (int) – Number of PFB branches. Note that this results in num_branches / 2 coarse channels.

Returns:

x_summed – Array of voltages post-PFB weighting

Return type:

array

setigen.voltage.polyphase_filterbank.get_pfb_window(num_taps, num_branches, window_fn='hamming')

Get windowing function to multiply to time series data according to a finite impulse response (FIR) filter.

Parameters:

• num_taps (int) – Number of PFB taps

• num_branches (int) – Number of PFB branches. Note that this results in num_branches / 2 coarse channels.

• window_fn (str, optional) – Windowing function used for the PFB

Returns:

window – Array of PFB windowing coefficients

Return type:

array

setigen.voltage.polyphase_filterbank.get_pfb_voltages(x, num_taps, num_branches, window_fn='hamming')

Produce complex raw voltage data as a function of time and coarse channel.

Parameters:

• x (array) – Array of voltages

• num_taps (int) – Number of PFB taps

• num_branches (int) – Number of PFB branches. Note that this results in num_branches / 2 coarse channels.

• window_fn (str, optional) – Windowing function used for the PFB

Returns:

X_pfb – Post-FFT complex voltages

Return type:

array

setigen.voltage.quantization module

class setigen.voltage.quantization.RealQuantizer(target_mean=0, target_fwhm=32, num_bits=8, stats_calc_period=1, stats_calc_num_samples=10000)

Bases: object

Implement a quantizer for input voltages.

__init__(target_mean=0, target_fwhm=32, num_bits=8, stats_calc_period=1, stats_calc_num_samples=10000)

Initialize a quantizer, which maps real input voltages to integers between -2**(num_bits - 1) and 2**(num_bits - 1) - 1, inclusive. Specifically, it estimates the mean and standard deviation of the voltages, and maps to 0 mean and a target full width at half maximum (FWHM). Voltages that extend past the quantized voltage range are clipped accordingly.

The mean and standard deviation calculations can be limited to save computation using the stats_calc_period and stats_calc_num_samples parameters. The former is an integer that specifies the period of computation; if 1, it computes the stats every time. If set to a non-positive integer, like -1, the computation will run once during the first call and never again. The latter specifies the maximum number of voltage samples to use in calculating the statistics; depending on the nature of the input voltages, a relatively small number of samples may be sufficient for capturing the general distribution of voltages.

Parameters:

• target_fwhm (float, optional) – Target FWHM

• num_bits (int, optional) – Number of bits to quantize to. Quantized voltages will span -2**(num_bits - 1) to 2**(num_bits - 1) - 1, inclusive.

• stats_calc_period (int, optional) – Sets the period for computing the mean and standard deviation of input voltages

• stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise statistics

quantize(voltages, custom_std=None)

Quantize input voltages. Cache voltage mean and standard deviation, per polarization and per antenna.

Parameters:

• voltages (array) – Array of real voltages

• custom_std (float) – Custom standard deviation to use for scaling, instead of automatic calculation. The quantizer will go from custom_std to self.target_std.

Returns:

q_voltages – Array of quantized voltages

Return type:

array

digitize(voltages, custom_std=None)

Quantize input voltages. Wrapper for quantize().

class setigen.voltage.quantization.ComplexQuantizer(target_mean=0, target_fwhm=32, num_bits=8, stats_calc_period=1, stats_calc_num_samples=10000)

Bases: object

Implement a quantizer for complex voltages, using a pair of RealQuantizers.

__init__(target_mean=0, target_fwhm=32, num_bits=8, stats_calc_period=1, stats_calc_num_samples=10000)

Initialize a complex quantizer, which maps complex input voltage components to integers between -2**(num_bits - 1) and 2**(num_bits - 1) - 1, inclusive. Uses a pair of RealQuantizers to quantize real and imaginary components separately.

Parameters:

• target_fwhm (float, optional) – Target FWHM

• num_bits (int, optional) – Number of bits to quantize to. Quantized voltages will span -2**(num_bits - 1) to 2**(num_bits - 1) - 1, inclusive.

• stats_calc_period (int, optional) – Sets the period for computing the mean and standard deviation of input voltages

• stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise statistics

quantize(voltages, custom_stds=None)

Quantize input complex voltages. Cache voltage means and standard deviations, per polarization and per antenna.

Parameters:

• voltages (array) – Array of complex voltages

• custom_stds (float, list, or array) – Custom standard deviation to use for scaling, instead of automatic calculation. Each quantizer will go from custom_stds values to self.target_std. Can either be a single value or an array-like object of length 2, to set the custom standard deviation for real and imaginary parts.

Returns:

q_voltages – Array of complex quantized voltages

Return type:

array

setigen.voltage.quantization.quantize_real(x, target_mean=0, target_std=13.589148804608305, num_bits=8, data_mean=None, data_std=None, stats_calc_num_samples=10000)

Quantize real voltage data to integers with specified number of bits and target statistics.

Parameters:

• x (array) – Array of voltages

• target_mean (float, optional) – Target mean for voltages

• target_std (float, optional) – Target standard deviation for voltages

• num_bits (int, optional) – Number of bits to quantize to. Quantized voltages will span -2**(num_bits - 1) to 2**(num_bits - 1) - 1, inclusive.

• data_mean (float, optional) – Mean of input voltages, if already known

• data_std (float, optional) – Standard deviation of input voltages, if already known. If None, estimates mean and standard deviation automatically.

• stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise statistics

Returns:

q_voltages – Array of quantized voltages

Return type:

array

setigen.voltage.quantization.quantize_complex(x, target_mean=0, target_std=13.589148804608305, num_bits=8, stats_calc_num_samples=10000)

Quantize complex voltage data to integers with specified number of bits and target FWHM range.

Parameters:

• x (array) – Array of complex voltages

• target_mean (float, optional) – Target mean for voltages

• target_std (float, optional) – Target standard deviation for voltages

• num_bits (int, optional) – Number of bits to quantize to. Quantized voltages will span -2**(num_bits - 1) to 2**(num_bits - 1) - 1, inclusive.

• stats_calc_num_samples (int, optional) – Maximum number of samples for use in estimating noise statistics

Returns:

q_c – Array of complex quantized voltages

Return type:

array

setigen.voltage.level_utils module

setigen.voltage.level_utils.get_unit_drift_rate(raw_voltage_backend, fftlength, int_factor=1)

Calculate drift rate corresponding to a 1x1 pixel shift in the final data product. This is equivalent to dividing the fine channelized frequency resolution with the time resolution.

Parameters:

• raw_voltage_backend (RawVoltageBackend) – Backend object to infer observation parameters

• fftlength (int) – FFT length to be used in fine channelization

• int_factor (int, optional) – Integration factor to be used in fine channelization

Returns:

unit_drift_rate – Drift rate in Hz / s

Return type:

float

setigen.voltage.level_utils.get_level(snr, raw_voltage_backend, fftlength, obs_length=None, num_blocks=None, length_mode='obs_length')

Calculate required signal level as a function of desired SNR, assuming initial noise variance of 1. This is calculated for a single polarization. This further assumes the signal is non-drifting and centered on a finely channelized bin.

Parameters:

• snr (float) – Signal-to-noise ratio (SNR)

• raw_voltage_backend (RawVoltageBackend) – Backend object to infer observation parameters

• fftlength (int, optional) – FFT length to be used in fine channelization

• obs_length (float, optional) – Length of observation in seconds, if in ‘obs_length’ mode

• num_blocks (int, optional) – Number of data blocks to record, if in ‘num_blocks’ mode

• length_mode (str, optional) – Mode for specifying length of observation, either ‘obs_length’ in seconds or ‘num_blocks’ in data blocks

Returns:

level – Level, or amplitude, for a real voltage cosine signal

Return type:

float

setigen.voltage.level_utils.get_leakage_factor(f_start, raw_voltage_backend, fftlength)

Get factor to scale up signal amplitude from spectral leakage based on the position of a signal in a fine channel. This calculates an inverse normalized sinc value based on the position of the signal with respect to finely channelized bins. Since intensity goes as voltage squared, this gives a scaling proportional to 1/sinc^2 in finely channelized data products; this is the standard fine channel spectral response.

Parameters:

• f_start (float) – Signal frequency, in Hz

• raw_voltage_backend (RawVoltageBackend) – Backend object to infer observation parameters

• fftlength (int, optional) – FFT length to be used in fine channelization

Returns:

leakage_factor – Factor to multiply to signal level / amplitude

Return type:

float

setigen.voltage.waterfall module

setigen.voltage.waterfall.get_pfb_waterfall(pfb_voltages_x, pfb_voltages_y=None, fftlength=256, int_factor=1)

Perform fine channelization on input complex voltages after filterbank, for single or dual polarizations.

Parameters:

• pfb_voltages_x (array) – Complex voltages in first polarization, of shape (time_samples, num_chans)

• pfb_voltages_y (array, optional) – Complex voltages in second polarization, of shape (time_samples, num_chans)

• fftlength (int) – FFT length to be used in fine channelization

• int_factor (int, optional) – Integration factor to be used in fine channelization

Returns:

XX_psd – Finely channelized voltages

Return type:

array

setigen.voltage.waterfall.get_waterfall_from_raw(raw_filename, block_size, num_chans, int_factor=1, fftlength=256)

Produces waterfall data array from the first block of a dual-polarized, 8 bit RAW file. Lightweight function mainly for testing.

Parameters:

• raw_filename (str) – Filename of GUPPI RAW file

• block_size (int) – Number of bytes in a data block

• num_chans (int) – Number of coarse channels saved in RAW file

• fftlength (int) – FFT length to be used in fine channelization

• int_factor (int, optional) – Integration factor to be used in fine channelization

Returns:

XX_psd – Finely channelized voltages

Return type:

array