Fake Data

lsl.sim - Simulate various types of LWA data. The following follow DP format writers are avaliable:

• tbw
• tbn
• drx

In addition, there are two simulation modules to generate fake data sets::

• dp - generate DP-level data sets for basic signals and point source
• vis - generate visibility data sets for use with the aipy module

Writers

New in version 0.3.

TBW

Python module for creating creating, validating, and writing simulated TBW frames to a file.

class lsl.sim.tbw.SimFrame(stand=None, frameCount=None, dataBits=12, obsTime=None, xy=None)

Bases: lsl.reader.tbw.Frame

tbw.SimFrame extends the lsl.reader.tbw.Frame object to yield a method for easily creating DP ICD-compliant raw TBW frames. Frames created with this method can be written to a file via the methods writeRawFrame() function.

createRawFrame()

Re-express a simulated TBW frame as a numpy array of unsigned 8-bit integers. Returns a numpy array if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

isValid(raiseErrors=False)

Check if simulated TBW frame is valid or not. Valid frames return True and invalid frames False. If the ‘raiseErrors’ keyword is set, isValid() raises an error when a problem with the frame structure is encountered.

loadFrame(tbwFrame)

Populate the a tbw.SimFrame object with a pre-made frame.

writeRawFrame(fh)

Write a simulated TBW frame to a filehandle if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

lsl.sim.tbw.frame2frame(tbwFrame)

Convert a lsl.reader.tbw.Frame object to a raw DP TBW frame.

TBN

Python module for creating creating, validating, and writing simulated TBN frames to a file.

class lsl.sim.tbn.SimFrame(stand=None, pol=None, centralFreq=None, gain=None, frameCount=None, obsTime=None, iq=None)

Bases: lsl.reader.tbn.Frame

tbn.SimFrame extends the lsl.reader.tbn.Frame object to yield a method for easily creating DP ICD-compliant raw TBN frames. Frames created with this method can be written to a file via the methods writeRawFrame() function.

createRawFrame()

Re-express a simulated TBN frame as a numpy array of unsigned 8-bit integers. Returns a numpy array if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

isValid(raiseErrors=False)

Check if simulated TBN frame is valid or not. Valid frames return True and invalid frames False. If the ‘raiseErrors’ keyword is set, isValid raises an error when a problem is encountered.

loadFrame(tbnFrame)

Populate the a tbn.SimFrame object with a pre-made frame.

writeRawFrame(fh)

Write a simulated TBN frame to a filehandle if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

lsl.sim.tbn.frame2frame(tbnFrame)

Convert a lsl.reader.tbn.Frame object to a raw DP TBN frame.

DRX

Python module for creating creating, validating, and writing simulated DRX frames to a file.

class lsl.sim.drx.SimFrame(beam=None, tune=None, pol=None, filterCode=None, timeOffset=None, frameCount=None, obsTime=None, flags=None, iq=None)

Bases: lsl.reader.drx.Frame

drx.SimFrame extends the lsl.reader.drx.Frame object to yield a method for easily creating DP ICD-compliant raw DRX frames. Frames created with this method can be written to a file via the methods writeRawFrame() function.

createRawFrame()

Re-express a simulated DRX frame as a numpy array of unsigned 8-bit integers. Returns a numpy array if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

isValid(raiseErrors=False)

Check if simulated DRX frame is valid or not. Valid frames return True and invalid frames False. If the ‘raiseErrors’ keyword is set, isValid raises an error when a problem is encountered.

loadFrame(drxFrame)

Populate the a drx.SimFrame object with a pre-made frame.

writeRawFrame(fh)

Write a simulated DRX frame to a filehandle if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

lsl.sim.drx.frame2frame(drxFrame)

Convert a lsl.reader.drx.Frame object to a raw DP DRX frame.

Simulators

Digitial Processor Data

New in version 0.3.

Module to simulate observations made with the DP system.

lsl.sim.dp.basicSignal(fh, stands, nFrames, mode='DRX', filter=6, nTuning=2, bits=12, tStart=0, noiseStrength=0.1, verbose=False)

Generate a collection of frames with a basic test signal for TBW, TBN, and DRX. The signals for the three modes are:

TBW

• noise + 40 MHz signal for x-pol.
• noise + 60 MHz signal for y-pol. -> odd stands
• noise + 30 MHz signal for x-pol.
• noise + 50 MHz signal for ypol. -> even stands

TBN

• noise + (sampleRate/4) kHz signal for x-pol. and noise + (-sampleRate/4) for y-pol.

DRX

• noise + (sampleRate/4) kHz signal for x-pol. and noise + (-sampleRate/4) for y-pol. -> tuning 1
• noise + (-sampleRate/3) kHz signal for x-pol. and noise + (sampleRate/3) for y-pol. -> tuning 2

All modes need to have stands (beams in the case of DRX) and number of frames to generate. TBW also needs to ‘bits’ keyword set to generate either 12-bit or 4-bit data. The TBN and DRX frames need the ‘filter’ keyword set to specify the filter width. In addition, the ‘stands’ argument is interpreted as beam numbers for DRX.

Changed in version 0.4.4: Added the noiseStrength keyword to control how much noise is added to the data.

lsl.sim.dp.pointSource(fh, stands, src, nFrames, mode='TBN', CentralFreq=49000000.0, filter=7, bits=12, tStart=0, phaseCenter='z', noiseStrength=0.1, verbose=False)

Generate a collection of frames with a point source signal for TBW and TBN. The point source is specified as a aipy.src object.

All modes need to have stands (beams in the case of DRX) and number of frames to generate. TBW also needs to `bits’ keyword set to generate either 12-bit or 4-bit data. The TBN frames need the `filter’ keyword set to specify the filter width.

Changed in version 0.4.4: Added the noiseStrength keyword to control how much noise is added to the data.

Visibility Data

Module for generating simulated arrays and visibility data. The chief functions of this module are:

buildSimArray

given a station object, a list of stands, and a list of frequencies, build a AIPY AntennaArray-like object. This module can also generate AntennaArray objects with positional errors by setting the ‘PosError’ keyword to a positive value.

buildSimData

given a SimArray and a list of aipy.src sources, build up a collection of visibilities for a given set of Julian dates

scaleData

given a dictionary of simulated visibilities from buildSimData, apply antenna-based gains and delays to the visibilities

shiftData

given a dictionary of simulated visibilities from buildSimData, shift the uvw coordinates of the visibilities. .. note:

This only changes the uvw values and does not phase-shift the data.

The format of the data dictionaries mentioned above is:

primary keys

The primary keys store the major aspects of the visiblity data, e.g., frequency coverage, baseline pairs, uvw coordinates, etc. Valid keys are:

• freq - list of frequencies used in Hz
• isMasked - whether or not the visibility data have been masked (numpy.compress’d)
• bls - list of baselines in (stand 1, stand2) format
• uvw - list of uvw coordinates as 3-element numpy arrays
• vis - list of visibility numpy arrays
• wgt - list of weight arrays with the same length as the visilitity arrays
• msk - list of mask arrays used for the data. 1 = masked, 0 = valid
• jd - list of Julian dates associated with each list element

secondary keys

The bls, uvw, vis, wgt, msk, and jd primary keys also have secondary keys that indicate which polarizations are being stored. Valid keys are:

• xx
• yy
• xy
• yx

In addition to simulation functions, this module includes buildGriddedImage which takes a dictionary of visibilities and returns and aipy.im.ImgW object.

Changed in version 0.3.0: This module was formerly called lsl.sim.sim

Changed in version 0.5.0: Moved buildGriddedImage to the lsl.imaging.utils module.

Changed in version 1.0.1: Switched over to a new C-based simulation package

Changed in version 1.0.2: Added in a function, addBaselineNoise, to help bring noise into the simulations

Changed in version 1.0.3: Moved the calculateSEFD function into lsl.misc.rfutils Changed the meaning of the ForceGaussian parameter of the buildSimArray() function to be the Gaussian full width at half maximum in degrees

class lsl.sim.vis.RadioEarthSatellite(tle, tfreq, tpower=0.0, tbw=1000000.0, ionref=(0.0, 0.0))

Implement a aipy.amp.RadioBody-lime simulation object for an Earth- orbiting satellite using a two-line element set.

compute(observer)

Update coordinates relative to the provided observer. Must be called at each time step before accessing information.

get_crds(crdsys, ncrd=3)

Return the coordinates of this location in the desired coordinate system (‘eq’,’top’) in the current epoch. If ncrd=2, angular coordinates (ra/dec or az/alt) are returned, and if ncrd=3, xyz coordinates are returned.

get_jys()

Return the fluxes vs. freq that should be used for simulation.

update_jys(afreqs)

Update fluxes relative to the provided observer. Must be called at each time step before accessing information.

class lsl.sim.vis.BeamAlm(freqs, lmax=8, mmax=8, deg=7, nside=64, coeffs={})

AIPY-based representation of a beam model where each pointing has a response defined as a polynomial in frequency, and the spatial distributions of these coefficients decomposed into spherical harmonics.

This differs from the AIPY version in that the response() method accepts two and three-dimensions arrays of topocentric coordinates, similar to what aipy.img.ImgW.get_top() produces, and computes the beam response at all points.

response(top)

Return beam response across active band for specified topocentric coordinates (x=E,y=N,z=UP). x,y,z may be multiple coordinates. Returns ‘x’ pol (rotate pi/2 for ‘y’).

Note

This function also accepts two and three-dimensions arrays of topocentric coordinates, similar to what aipy.img.ImgW.get_top() produces, and computes the beam response at all points

class lsl.sim.vis.Antenna(x, y, z, beam, phsoff=[0.0, 0.0], bp_r=array([1]), bp_i=array([0]), amp=1, pointing=(0.0, 1.5707963267948966, 0), stand=0, **kwargs)

Modification to the aipy.amp.Antenna class to also store the stand ID number in the Antenna.stand attribute. This also add a getBeamShape attribute that pulls in the old vis.getBeamShape function.

bm_response(top, pol='x')

Return response of beam for specified polarization.

Note

This differs from the AIPY implementation in that the LWA X-pol. is oriented N-S, not E-W.

Note

This function also accepts two and three-dimensions arrays of topocentric coordinates, similar to what img.ImgW.get_top() produces, and computes the beam response at all points.

get_beam_shape(pol='x')

Return a 360 by 90 by nFreqs numpy array showing the beam pattern of a particular antenna in the array. The first two dimensions of the output array contain the azimuth (from 0 to 359 degrees in 1 degree steps) and altitude (from 0 to 89 degrees in 1 degree steps).

class lsl.sim.vis.AntennaArray(location, ants, **kwargs)

Modification to the aipy.ant.AntennaArray class to add a function to retrieve the stands stored in the AntennaArray.ants attribute. Also add a function to set the array time from a UNIX timestamp.

Changed in version 1.0.1: Added an option to set the ASP filter for simulation proposes. This updates the bandpasses used by AIPY to include the antenna impedance mis-match and the mean ARX response.

gen_phs_fast(src, i, j, mfreq=0.15, ionref=None, srcshape=None, resolve_src=False, u=None, v=None, w=None)

Return phasing that is multiplied to data to point to src - fast.

gen_uvw_fast(i, j, src='z', w_only=False, map=None)

Compute uvw coordinates of baseline relative to provided RadioBody, or ‘z’ for zenith uvw coordinates. If w_only is True, only w (instead of (u,v,w) will be returned) - fast.

get_baseline_fast(i, j, src='z', map=None)

Return the baseline corresponding to i,j in various coordinate projections: src=’e’ for current equatorial, ‘z’ for zenith topocentric, ‘r’ for unrotated equatorial, or a RadioBody for projection toward that source - fast.

get_stands()

Return a numpy array listing the stands found in the AntennaArray object.

set_asp_filter(filter='split')

Update the bandpasses for the antennas to include the effect of the antenna impedance mis-match (IMM) and the mean LWA1 ARX response.

Valid filters are:

• split
• full
• reduced
• none

None is a special case where both the IMM and ARX response are removed, i.e., the bandpass is unity for all frequencies.

New in version 1.0.1.

set_unixtime(timestamp)

Set the array time using a UNIX timestamp (epoch 1970).

sim(i, j, pol='xx')

Simulate visibilities for the specified (i,j) baseline and polarization. sim_cache() must be called at each time step before this will return valid results.

This function differs from aipy.amp.AntennaArray.sim in the fact that ionref and srcshape are both None in the call to gen_phs and that resolve_src is set to False.

lsl.sim.vis.buildSimArray(station, antennas, freq, jd=None, PosError=0.0, ForceFlat=False, ForceGaussian=False, verbose=False)

Build a AIPY AntennaArray for simulation purposes. Inputs are a station object defined from the lwa_common module, a numpy array of stand numbers, and a numpy array of frequencies in either Hz of GHz. Optional inputs are a Julian Date to set the array to and a positional error terms that perturbs each of the stands in x, y, and z. The output of this module is an AIPY AntennaArray object.

The shape of the antenna response is either flat (gain of 1 in all directions), modeled by a 2-D Gaussian with the specified full width at half maximum in degrees, or modeled by a collection of spherical harmonics that are polynomials in frequency. The spherical harmonics are used if the file ‘beam_shape.npz’ is found in the current directory.

Changed in version 1.0.3: Changed the meaning of the ForceGaussian parameters so that the Gaussian full width at half maximum in degrees is passed in.

Changed in version 1.0.1: Moved the simulation code over from AIPY to the new _simFast module. This should be much faster but under the caveats that the bandpass and antenna gain patterns are the same for all antennas. This should be a reasonable assumption for large-N arrays.

Added an option to use a 2-D Gaussian beam pattern via the ForceGaussian keyword.

Changed in version 0.4.0: Switched over to passing in Antenna instances generated by the lsl.common.station module instead of a list of stand ID numbers.

lsl.sim.vis.buildSimData(aa, srcs, pols=['xx', 'yy', 'xy', 'yx'], jd=None, chan=None, phaseCenter='z', baselines=None, mask=None, flatResponse=False, resolve_src=False, verbose=False)

Given an AIPY AntennaArray object and a dictionary of sources from aipy.src.get_catalog, returned a data dictionary of simulated data taken at zenith. Optinally, the data can be masked using some referenced (observed) data set or only a specific sub-set of baselines.

Changed in version 1.0.1: * Added a ‘flatResponse’ keyword to make it easy to toggle on and off the spectral and spatial response of the array for the simulation * Added a ‘resolve_src’ keyword to turn on source resolution effects

..versionchanged:: 0.4.0

Added the ‘pols’ keyword to only compute certain polarization components

lsl.sim.vis.scaleData(dataDict, amps, delays, phaseOffsets=None)

Apply a set of antenna-based real gain values and phase delays in ns to a data dictionary. Returned the new scaled and delayed dictionary.

..versionchanged:: 0.6.3

Added a keyword so that phase offsets (in radians) can also be specified

..versionchanged:: 0.4.0

The delays are now expected to be in nanoseconds rather than radians.

lsl.sim.vis.shiftData(dataDict, aa)

Shift the uvw coordinates in one data dictionary to a new set of uvw coordinates that correspond to a new AntennaArray object. This is useful for looking at how positional errors in the array affect the data.

lsl.sim.vis.addBaselineNoise(dataDict, SEFD, tInt, bandwidth=None, efficiency=1.0)

Given a data dictionary of visibilities, an SEFD or array SEFDs in Jy, and an integration time in seconds, add noise to the visibilities assuming that the “weak source” limit.

This function implements Equation 9-15 from Chapter 9 of “Synthesis Imaging in Radio Astronomy II”.

New in version 1.0.2.