Starting Proposal Cycle 2014A (deadline August 1, 2013) TUNE should no longer be used. Much of TUNE's functionality is now part of the OPT

"TUNE" - a tool for VLA spectral line setup

"TUNE" is a tool designed to help users find the optimum correlator setup for simultaneous observation of multiple lines with the VLA, visualize how spectral windows will be placed within the available correlator basebands and where the spectral lines are located within a spectral window. From line frequencies and subband bandwidths as inputs, TUNE can recommend a baseband center frequency and subband offsets from this center frequency.

TUNE is python-based and available either as a stand-alone python code or as a web-based utility. If you plan to submit a proposal to observe multiple lines within a single VLA baseband, we suggest that you use TUNE to check the feasibility of your proposed observations and include a note in your technical justification indicating that you have used TUNE to verify the setup.

Before using TUNE, please review the Spectral Line Observing Guide which provides baseband tuning restrictions, describes correlator capabilities offered, and discusses issues relevant to planning spectral line observations. In summary,

• 8-bit sampler provides
  • (up to) two tuneable 1 GHz basebands and (up to) 32 subbands
  • subband bandwidths from 31.25 kHz to 128 MHz (in step of factor of 2)
  • with "flexible tuning" mode of the correlator, each subband can have a different bandwidth and the subbands can be placed anywhere within the baseband (avoiding the 128 MHz boundaries)
  • without flexible tuning, all subbands have the same bandwidth and subband center frequencies must have discreet values F1+/-[N+(1/2)]*F2, where F1 is baseband center frequency, F2 is subband bandwidth, and N = 0, 1, 2, ...
• 3-bit sampler provides
  • (up to) four tuneable 2 GHz basebands and (up to) 64 subbands
  • subband bandwidths are limited to 128 MHz for general observing

The actual number of available subbands will depend on the resolution and bandwidth chosen (higher resolution will use up more correlator hardware resources, limiting the total number of subbands that can be used). For more information on the 3/8 bit sampler, and the current correlator capabilities, see the online documentation here.

Each baseband is comprised of a series of 8 or 16 "blocks" that are 128 MHz wide. An individual subband must fall entirely within one of these blocks, as subbands cannot cross the boundary between these blocks, known as a "128MHz suckout". We recommend that subband edges be at least a few MHz away from these 128 MHz suckouts to avoid regions of sensitivity falloff. Additionally, one should try to avoid placing line(s) too close to the subband edges where again, decreased sensitivity may become an issue. TUNE can help to find a baseband setup that avoids placing subbands close to the 128 MHz suckouts and avoids placing line(s) close to the subband edges.

After determining the target spectral lines and subband widths, use TUNE to find baseband center frequency and subband offsets. TUNE can be run for a single baseband at a time. So, if observing all target lines requires multiple basebands, you must run TUNE for each baseband separately. The stand-alone python tool, which can be downloaded and run locally from the command line, requires that python and matplotlib are pre-installed. The stand-alone tool was tested on Python 2.4.3 and matplotlib 1.0.1 on Red Hat Enterprise Linux. If you have compatibility issues with other versions of Python and matplotlib, please contact the NRAO helpdesk. The web-based utility offers ease of use, with inputs entered through an online form, but provides slightly lower flexibility than the stand-alone tool. A description of the required inputs, generated outputs, and examples of the command line input syntax follow.

NOTE: Depending on the spectral resolution requirements for your science, finite correlator resources may limit the available total number of subbands and/or polarization products. Once again, consult the Spectral Line Observing Guide. Another tool, called GOST (General Observing Setup Tool) can calculate the correlator resource budget given the lines and spectral resolutions desired. If you are at all in doubt, please check your line/subband selections using the GOST to make sure that you can observe all desired lines with adequate spectral resolution while using the set up suggested by TUNE. Otherwise, you may need to exclude one or more line(s) from your list.

Using TUNE:

(1) Select the output file style (either "Detailed" or "Summary"), and enter an output file name. TUNE outputs a pdf file that contains (i) images of the baseband positioning within the receiver band, (ii) images showing subband and line positions within the baseband, and (3) a summary of recommended baseband center frequency and subband offsets. The "Detailed" output, which also shows the position of each individual line within its subband, is recommended for the user when inspecting the correlator setup.

Note: The web-based tool uses the default browser settings for downloads. With the web-based tool, modify the output file name to prevent overwriting any existing file. For the stand-alone script, the output file name can be specified as the standard terminal input. Further, it will warn the user before overwriting an existing file.

(2) Select the correlator mode (i.e. 3- or 8-bit sampling, "flexible tuning" on or off).

(3) Specify the topocentric optical velocity and/or the redshift of the source.

Note: The topocentric velocity will change by up to 0.5 km/s over the course of a day and up to 30 km/s over the course of a year. If you plan to use a narrow subband bandwidth, it is important to consider whether your line may drift out of your subband. Input the topocentric velocity based on the time of day and year that you anticipate your observations will be conducted.

(4) Specify line frequencies and subband bandwidths. If a topocentric source velocity/redshift has already been entered, provide the line rest frequencies here. Alternatively, you may leave the velocity/redshift fields set to 0 and input the expected sky frequencies of the lines here. To convert rest frequency to appropriate sky frequency, you may use the Online Dopset Tool.

With the stand-alone python tool, frequencies and bandwidths can be specified from the command line or alternatively put into a text file that can be called from the command line. In the web-based tool, frequencies and subband bandwidths can be entered into a text box or selected from a dropdown menu.

Note: For the 8 bit "flexible tuning" mode, TUNE tries to center each line within the respective subband. There is no option to specify multiple lines for a single subband. Thus, you must calculate a single "effective" line frequency (e.g. an average between the line frequencies) for subbands with multiple lines. Remember to cross check that the true line frequencies fall within the subband upon receiving TUNE's output!

(5) Run TUNE and inspect the output. See here for an example of a typical output file from TUNE.

If you are not satisfied with the recommended correlator setup and the setup may be corrected by shifting the baseband center to higher or lower frequency, you can specify an optional frequency shift for the whole baseband. In the stand-alone tool, you will be prompted to add an optional frequency shift before the program completes. In the web-based version, you can specify the frequency shift and re-submit the form.

Note: TUNE output should be taken as a guideline rather than the final/best possible/optimum configuration for each case. Depending on your specific requirements, "the best" set up is subjective, and may be different from the setup recommended by TUNE.

Command line input syntax for the stand-alone tool:

Inputs are passed into the stand-alone tool through argument flags with the following syntax (the order of input options is not important):
python tune.py -s [3 or 8](-bit sampler) -f [0 or 1](flexible tuning N/Y) -n [Number](of spectral lines) -l [l1 l2 ...](line frequencies GHz) -b [b1 b2 ...](subband widths MHz) -v [velocity,optional](km/s) -z [redshift,optional] -i [input file,optional]

Example 1:
python tune.py -s 8 -f 0 -n 4 -l 23.694 23.723 23.870 24.139 -b 4.0 4.0 4.0 4.0 -z 0.1

will run TUNE specifying: the 8-bit samplers; no flexible tuning (so all subbands have the same resolution and bandwidth); 4 lines at frequencies of 23.694, 23.723, 23.870 and 24.139 GHz; 4 MHz subband bandwidths; and lines are at a red shift of 0.1

Example 2:
python tune.py -s 8 -f 0 -z 0.1 -i tune_input.txt

uses the 8-bit sampler without flexible tuning, at a redshift of 0.1 and uses the -i flag to retrieve line frequencies and bandwidths from the input file named tune_input.txt, which is a free format two column ascii file.

The input file (tune_input.txt) equivalent to the line input in Example 1 would contain:

     23.694    4.0
     23.723    4.0
     23.870    4.0
     24.139    4.0

Inline help for the stand-alone script is also available by typing
python tune.py

from the terminal (without any extra arguments).

Copyright © 2018 Associated Universities, Inc.
The National Radio Astronomy Observatory is a facility of the National Science Foundation operated under cooperative agreement by Associated Universities, Inc.