GR-ATA Tutorial

On this page we'll walk through a few scenarios of running observations (both real and simulated) on the Allen Telescope Array with GNU Radio and the gr-ata module.

Step 0: Before you start...

In order to run an observation on the ATA, please know that you must coordinate with ATA staff to avoid interfering with science observing campaigns onsite.

Please find a catalog of astronomical sources recognized by the gr-ata module here: https://github.com/SETIatHCRO/gr-ata/blob/master/docs/ata-catalog.txt

Before beginning this tutorial, please make sure that you have installed GNU Radio version 3.8, gr-ata, and the ATA-Utils library, following the instructions here: Setting up the software

Tutorial 1: A Simulated ATA Observation

In this first tutorial, we will run through a simulated offline "observing" session -- although in this tutorial we won't be conducting real observations, it is a good idea to start here to make sure you understand what the gr-ata blocks are doing and get familiar with the system and terminology before starting your real observation. This mode of running the gr-ata blocks does not require you to be able to connect to the ATA computers, either, so it is a good place to start.

Simulated Track Scan observation

Let's first try a very simple test. Drag and drop an ATA Track Scan block and an ATA Control block into an empty flowgraph and connect their message ports as shown below.

Make sure you have changed the ID field in the automatically-populated Options block to something besides default or the program won't run. Now double click the Control block to bring up the Properties window. Enter your username (for the offline tutorial this field doesn't matter, just type anything), then select Offline Mode from the Mode drop-down list, as shown. Click OK to apply your changes and close the Properties window.

Now double click on the Track Scan block to view its properties. The first field is Frequency (MHz) -- enter any number of your choice here (it doesn't really matter what you enter in Offline Mode, just so long as it is a number). The next field is List of antennas; this field requires a string or list of strings as input, entered as shown. To simulate a real observing session, you could enter one or more of the actual antenna names of ATA antennas by choosing from the following list: 1a, 1b, 1c, 1d, 1e, 1f, 1g, 1h, 1j, 1k, 2a, 2b, 2c, 2d, 2e, 2f, 2g, 2h, 2j, 2k, 2l, 2m, 3c, 3d, 3e, 3f, 3g, 3h, 3j, 3l, 4e, 4f, 4g, 4h, 4j, 4k, 4l, 5b, 5c, 5e, 5g, 5h as shown. Next, select how you want to enter your target source in the Coordinate Type drop-down -- you can choose Catalog Identifier (as in the example below), RA / Dec, or Az / El. If you choose Catalog Identifier, a Source ID field will be displayed, where you can enter a source name -- in Offline Mode this source name can be anything, but in Observing Mode you must select an identifier from this catalog. If you select RA / Dec, separate RA and Dec fields will be displayed where you can enter your coordinates in decimal degrees; similarly if you select Az / El, Az and El fields will be displayed as well.

Now that you have connected the two blocks and filled out the required fields, you can save your flowgraph then hit Run. You should see output in the terminal window as shown:

Once the text has printed, you can stop the flowgraph, and an exit message will be printed:

Changing the target source during a simulated observation

Another thing you can do is test out the real-time message passing capability of the Track Scan block. First, drag and drop a QT GUI Message Edit Box and connect it to the Track Scan block's msg_in port as shown:

Edit the Properties of the Message Edit box so they match what's shown below:

Then run the flowgraph again. Now, the QT GUI message edit box should show up as in the image below; to slew to a new source, simply type source_id in the left-hand box and the name of the source you want to slew to in the right-hand box, then hit the Enter key and the text in the GNU Radio terminal window should update to say slewing on-source to {source name}. Alternatively, if you'd like to enter an RA / Dec or Az / El pair in the message box, type "radec" in the left-hand box and then your right ascension, declination pair separated by a comma in the right-hand box (like: ra,dec). Similarly, for Az / El, you can type "azel" in the left-hand box, then the coordinate pair (like: az,el) in the right-hand box. If you type non-number symbols in the right-hand box when trying to slew to a target given by an RA / Dec or Az / El pair, it will print an error message, so just be mindful of that.

Simulated On-Off observation

If you wish to use the On-Off block instead of the Track Scan block, almost all of the instructions above are equally applicable. However, in addition to setting the center frequency, antennas list, and source location as you did in the Track Scan block, you will also need to indicate your on-source duration and the amount of offsets which you wish for the antenna to slew away from the source for the off-source part of the observation:

When you play the flowgraph with the On-Off block in place of the Track Scan block, a message will be printed that says the (imaginary) antennas have "slewed" on source, then after the given duration has elapsed, it will print that the array has "slewed" off source. The On-Off block is also compatible with accepting input from the QT GUI Message Edit block.

Tutorial 2: Observing with the ATA

Although in many ways performing a real observation with the ATA is similar to the simulated observation described above, there are some subtle differences that are worth noting, and which I will describe in this tutorial.

Track Scan Observation

Let's start, as before, with a simple track scan observation. In this case you will, again, drag and drop a Track Scan block and a Control block and connect them as shown:

You will need to update the properties of the Control block. In the Username space, type in the username you were assigned when you were given an account on the ATA computer, and make sure you have selected Observing Mode. The purpose of entering your username here is to check what permissions you have on the array. If you have spoken with ATA staff and have explicit permission to change the entire array's operating frequency (there is only 1 LO so even if you think you are changing the frequency for just your antennas, without a safety check you could change the frequency of the entire array and disrupt another observer's session), and have subsequently locked out the array under your username, the flowgraph will be able to change the LO center frequency. However, if you are not the primary user and have not locked out the array, the flowgraph will not allow you to change the LO frequency (though it will still let you change the frequency tuning on your antenna to the value indicated in the Frequency box, so you can, e.g., "zoom in" on a particular frequency within the larger passband even if you can't change the LO).

As before, now open the Track Scan block's properties. This time, for the Frequency, you must enter a value between 1000 MHz and 15000 MHz, as these are the lower and upper bounds of the array's operating frequencies. Note that the observing band is xx MHz wide, and this band will be centered on whatever frequency you indicate in the box (again, if you have LO permissions -- if not you'll just be tuning your antenna to that center frequency). In the case where you do not have LO permissions, it is a good idea to check what the center frequency of the array is set to and pick your center frequency somewhere within the current observing band.

For the antennas list, make sure to select antennas from the following list: 1a, 1b, 1c, 1d, 1e, 1f, 1g, 1h, 1j, 1k, 2a, 2b, 2c, 2d, 2e, 2f, 2g, 2h, 2j, 2k, 2l, 2m, 3c, 3d, 3e, 3f, 3g, 3h, 3j, 3l, 4e, 4f, 4g, 4h, 4j, 4k, 4l, 5b, 5c, 5e, 5g, 5h. Note that only [antennas xyz] are capable of acquiring data via a USRP at this moment; the other antennas are in the process of being refurbished.

Coordinate type is the same as before -- you can choose Catalog Identifier, RA / Dec, or Az / El. In Offline Mode it really doesn't matter what source ID you enter if you select Catalog Identifier, but in Observing Mode you must put in an identifier from the catalog, if you put in an unknown source the program will throw an error. RA / Dec and Az / El fields must be numbers. When the observation begins, the software will check if your source location of interest is above the horizon; if not it will tell you so and will not attempt to observe your source.

Now, if you run your flowgraph, you should see various messages printed in the terminal window indicating the progress of your observation. This may take awhile depending the speed of your connection to the ATA machine so be patient, practice meditation, pet your dog / cat / iguana, etc. for a bit while you wait. Best not to interrupt the observation if you can avoid it -- although in most cases even if you do the deconstructor will clean things up, in some cases if you interrupt it hard enough the antennas are not released and stowed and you are left in a messy state when you try to start back up; see General Debugging - Error reserving antennas for more info on how to handle this situation.

image here

Changing the target source during an observing run

As in offline mode, if you'd like to change your target source during an observation, you can use the QT GUI Message Edit box. The instructions below are nearly identical to the instructions for the simulated version of this type of observation, but I've repeated them below for completeness.

Make sure that Static Mode is set to False on the QT GUI Message Edit box and that it is connected to the Track Scan block as shown below.

Then run the flowgraph again. Now, the QT GUI message edit box should show up; to slew to a new source, type source_id in the left-hand box and the name of the source you want to slew to (again, it must be from the catalog linked in the last section) in the right-hand box, then hit the Enter key and after a bit the antennas should start slewing to the new target. Alternatively, if you'd like to enter an RA / Dec or Az / El pair in the message box, type "radec" in the left-hand box and then your right ascension, declination pair separated by a comma in the right-hand box (like: ra,dec). Similarly, for Az / El, you can type "azel" in the left-hand box, then the coordinate pair (like: az,el) in the right-hand box. Recall the prior warning that if you type non-number symbols in the right-hand box when trying to slew to a target given by an RA / Dec or Az / El pair, it will print an error message.

image here

General Debugging

Error reserving antennas

If you run an observation and get an error message that the antennas you have requested can't be reserved, a couple of things could be happening -- (a) you don't have permission to use these antennas and someone else is in control; (b) you do have permission to use them but it appears someone else is using them, (c) your program crashed after you had already reserved the antennas, so now it thinks someone else has reserved them. In the case of (a), just wait your turn until your assigned observing slot, or until someone from the ATA gives you the OK. If (b), contact the ATA staff -- it is possible the array had to quickly track to a target that is fleeting in nature on a moment's notice, so please do not try to force the antennas to release. If, however, you are certain that your problem is (c), there is a workaround -- go into the directory where you cloned gr-ata into, and then go into the python folder. Open up control.py and scroll to the bottom to find the reserve function. Change force=False to force=True. Then move into gr-ata and enter your build directory, and run cmake .., make, sudo make install, and sudo ldconfig. Start up an observation and you should be able to reserve the antennas. Once you have gotten everything into a cleaner state you should go back in and change back to force=False.