Populate a Resource Catalog

Creating a spectral line resource is similar to creating wide band resources as outlined in the previous section, except for the more advanced specification of the subbands and subband frequency tuning and possible Doppler setting of the frequencies.  Eventually, resources with the requested correlator settings will be pre-filled from information submitted to the PST during the observing time allocation procedure.  However, at this stage none of this has been implemented.

For how and when to use this observing mode, refer to the Spectral Line section of the VLA Observing Guide.

The NRAO Defaults resource catalog contains full polarization dual IF pair spectra-polarimetry resources (the wide band continuum resources). If they appeal to you, you can copy/paste them in a personal catalog just as for the wide band resources above and edit them as needed. Check the spectral line resource properties very carefully as the spectral line resources in the NRAO Defaults have a fixed sky frequency whereas you probably want to use a rest frequency in combination with Doppler setting.  Most likely, however, you will opt to create your own resource, just like creating a wide band resource previously.  Some items that need extra attention are described below, but first a small detour to outline the options for creating large numbers of narrow frequency channels.

Recirculation vs. Baseline Board Stacking

Spectral line observations are typically constrained by the requirement to have the best spectral resolution (i.e., narrowest spectral channel width) combined with the best velocity coverage (i.e., widest observing bandwidth), the latter perhaps also for calibration purposes (as gain calibration is done per subband).

The maximum subband bandwidth is 128 MHz and can be decreased by factors of 2 to 31.25 kHz(*). Total bandwidths wider than 128 MHz are achieved by placing subsequent bandwidths next to each other with the caveat that the few channels next to a subband edge should be considered lost for line work (on either side of the boundary, for continuum work as well). To obtain a contiguous bandwidth which is near-homogeneous in sensitivity and without any subband boundary gaps, another baseband would be placed some MHz offset (e.g., half a subband bandwidth) from the original baseband to enable subband stitching in post-processing. Note that this limits the number of available basebands for other line settings.

A single Baseline Board Pair (BlBP), out of 64 available BlBPs, can handle 256 spectral points divided over the polarization products (polProd). That is, it can deliver 256 spectral channels in single polarization, 128 spectral channels in dual polarization, or 64 spectral channels in full polarization. The channel width (which is slightly less than the spectral resolution) is then simply the subband width divided by the number of spectral channels.

With one BlBP per subband as standard, the selected subband bandwidth is thus limited to 256/polProd channels which may not be narrow enough to achieve the desired spectral resolution. There are two ways to overcome this limitation: Baseline Board Stacking uses more of the limited amount of hardware and Recirculation uses limiting the total bandwidth per subband and CPU cycles. Both have their disadvantages and the choice depends on the science requirements. If either can be used, we recommend using Recirculation.

Baseline Board Stacking uses additional BlBPs to compute extra channels in a subband (of any width up to 128 MHz). Each additional BlBP increases the number of spectral channels by 256/polProd. As there are only 64 BlBPs total, and as every subband uses a minimum of one BlBP, Baseline Board Stacking reduces the number of subbands that can be observed to less than 64, and in the extreme case to a single subband of 128 MHz or less. When most of the 64 BlBPs are being used and all of the subbands are required (instead of some being recognized as less important and thus "desired" versus "required"), the observations will not take place if one or more BlBPs are inoperable. The 3-bit NRAO default setups use 64 BlBPs with the subbands at the baseband edges "desired" to allow continuation of operations when not all BlBPs are available.

The Recirculation option uses software to compute extra channels. For this, CPU cycles are "freed up" by limiting the subband bandwidth fed to the BlBP to less than 128 MHz to obtain more lags (in factors of two), running the data through the board for a second, third, etc., time; hence Recirculation.  As subband bandwidths (and CPU cycles needed to process them) can be decreased by factors of 2, each halving thus allows a doubling of the number of channels in the subband, currently up to a factor of 64. This does not require additional BlBP hardware and thus retains the possibility of using all subbands, albeit at less subband and less total bandwidth. Currently, subbands of 128 MHz must use Baseline Board Stacking to achieve more than 256/polProd channels.

Baseline Board Stacking and Recirculation can be used simultaneously in the same subband (if less than 128 MHz), and configurations with multiple subbands configured with either or both are allowed. Note that here a correlator setup can still request all 64 BlBPs and thus designating some subbands as "desired" is still highly recommended, but Recirculation gives the option to use less than 64 to achieve the number of spectral channels.  However, requesting a large number of channels, whether or not with Baseline Board Stacking and/or Recirculation, yields higher data rates than normal with the default integration times. To remain within the limits set by the observatory, longer integration may be needed which has an impact on time averaging smearing in the larger array configurations and thus on the field of view.

The choice for one or the other, or even for less channels than anticipated, depends on the trade-offs that can be made for the science goals and remain a responsibility of the observer.

(*) When observing at such narrow subband bandwidths it is good to check with the NRAO Science helpdesk. There are other operational constraints, in particular the F-shift in bringing down the baseband, that need to be considered and that may decrease the usable subband bandwidth to much more than a (symmetric) few channels compared to the general case described above.

On November 8, 2023, a new Resource Catalog Tool was introduced which changes the way custom resources are created. This section will cover the creation of a custom spectral line resource.  If you have questions or issues, please contact us through the NRAO Science Helpdesk.

Create a Spectral Line Resource

After choosing to create a new instrument configuration, the New Resource Wizard pop-up box will appear with several options.

To create a spectral line resource select:

• Spectral Line
• Array Configuration: This will set the recommended default correlator integration time, which can be changed later in the tool if desired.
• Name: This should match the name of the resource entered in the PST.
• Finally, select the Generate button.

Basics Table

Near the top you will find the Basics info table (Figure 3.7) which is common across all tabs. This is where you can change the name of the resource and the correlator integration time.

Figure 3.7: Spectral line Basics info table.

Below is a description of the parameters in the Basics table.

Doppler Position Tab

You must enter the coordinates of the science target (or near a grouping of science targets) in RA and Dec. This will unlock the proceeding tabs so you may continue with the creation of the resource. You can also import the RA and Dec from a source in your Source catalog.

Lines Tab

In the Lines tab, you may either enter in the line information one-at-a-time by selecting Add Line or import a text file containing a list of lines by selecting:

Import Spectral Lines → Browse (select the txt file containing the lines you want to import/upload) → Upload → Done (if using Firefox)

(Note, if you are using Firefox you will be required to select the Done button after selecting Upload to complete the import. It has been determined that other browsers such as Safari (Mac), Opera (Linux / Mac / Windows), Chrome (Linux / Mac / Windows), or Microsoft Edge (Windows) do not need the Done button to be selected to complete the upload.)

Example of a spectral line added to the Lines tab can be seen in Figure 3.8.

Figure 3.8: Example of a spectral line added to the Lines tab.

For each line you will need to provide the following information:

Below is an example of a line text file for a Spectral Line resource. For more details, refer to the OPT manual. You may also export a set of lines from an existing resource.

#Line name; Rest frequency; Rest frame; Velocity convention; Velocity; Minimum range; Channel separation; Polarization products; Additional specifications
L1; 38.293GHz; Lsr Kinematic; Radio; -10.5km/s; 31.0km/s; 0.01km/s; DUAL; USE_RECIRCULATION=true
L2; 38.452629GHz; Lsr Kinematic; Radio; -10.5km/s; 31.0km/s; 0.01km/s; DUAL; USE_RECIRCULATION=true

Basebands Tab

There are two options for generating the spectral lines in their respective basebands, automated and manual.

Automated Setup

This will automatically generate the line coverage in their respective subbands and properly center the basebands. Only one receiver band will be activated when your lines are spread over frequencies spanning more than one band.

• If all your lines fall below 4 GHz, i.e., up to the S-band frequency range, you will only be permitted to use the 8-bit system.
• If all your lines fall within the 4-50 GHz frequency range, the RCT will select the system which best covers all of the lines. It will default to using the more line-sensitive 8-bit samplers, but in cases where necessary to cover all lines with the desired velocity coverage, it will use the 3-bit system.
• You may manually make adjustments if you do not like what the RCT has selected. However, this may result in missing some lines if you choose the 8-bit system. Keep in mind, the mixed-mode 3/8-bit system may be manually selected.

Manual Setup

This is essentially the same implementation as the original RCT and will require you to select the desired system (if applicable), set the baseband centers and generate each line/subband one-at-a-time. To see the table of lines and their respective Generate button, scroll down in the Basebands tab.

• Shifting the baseband center frequencies can be done in two ways:
• Use the '+' or '-' buttons next to the displayed baseband center frequency.  This will shift the baseband center frequency by multiples of +/- 128 MHz without changing the relative location of the subbands between the 128 MHz boundaries, or;
• Manually enter the desired center frequency, with the caveat of undoing the optimization for placing the subbands away from the 128 MHz boundaries.
• If you shift the baseband center frequency or change the system after using the automated setup, you will need to manually generate a line if it resides in a different baseband.
• Be aware of subbands that "hug" a 128 MHz boundary, which is a common symptom that may indicate an unwanted (and generally unnoticed) subband shift due to changing the baseband center. Unless using the Automated Setup and possibly the +/- buttons, if a subband and 128 MHz boundary "touch" after manually shifting the subband, that subband should be regenerated manually and subsequently may issue new warning messages.

Redo Automated Setup 

If you do not like the changes you made after the automated setup, you may select "Redo Automated Setup" and it will remove all manual edits to the resource. Basically, starting over with the automated setup.

Undo Manual Setup

If you wish to start over with the manual setup, then you will need to manually remove all subbands and lines from the Subbands tab.  The same as you would with the original RCT; note that this can be done in bulk from the Subbands tab.

Subbands Tab

In the Subbands tab you may add continuum subbands and/or make any adjustments to the lines, i.e., bandwidth (BW), polarization, Bl.BPs (baseline board pair stacking), and Recirculation.

Spectral Line Resolution

The generated lines will appear in their respective basebands. When you see a line without a generated subband associated with it, that is simply a line guide to show you where it may overlap in that baseband. The actual generated line will be in the neighboring baseband with a similar frequency range. The user may make adjustments to the bandwidth (BW), polarization, and the resolution of a line by adjusting the number of BlBPs and recirculation. For more details on stacking BlBPs and increasing recirculation, please refer to the Recirculation vs Baselineboard Pairs section.

• If subbands overlap or are very close to each other, it may be beneficial to merge the subbands into one with a new subband center frequency and a wider bandwidth that covers the frequency ranges of the overlapping subbands — note that this typically requires to also change the recirculation factor and/or the number of baseline board pairs to keep the channel separation the same as in the original subbands.
• You may also shift the baseband center frequency by +/- 128MHz from within the Subbands tab. (Again, you may need to manually generate a line if it resides in a new baseband.)

Add Continuum Subbands

For each baseband, continuum subbands can be added one-at-a-time or use the recommended Fill button at the "Subbands in Basebands" level (see Figure 3.9). Note, the bulk edit mode of the Fill option will not alter the generated spectral lines.

Manually adding subbands one-at-a-time will require the user to select the Add button, then select the central frequency range of each continuum subband by choosing the desired range in the drop-down menu located in the subbands table.

Figure 3.9: Adding continuum subbands in the Subbands tab using Fill.

After selecting Fill, the user will be presented with a pop-up box containing the following parameters:

Doppler Tuning Tab

You are required to enable the Doppler tuning for at least one baseband doing so will also enable a Doppler Report located below the Doppler tuning settings (see Figure 3.10).

Figure 3.10: Doppler Tuning tab showing an example of a Doppler Report.

You may update the report to view the setup for a given VLA LST day and time. This will recalculate the values in the baseband tables below and will allow you to see what the on-the-sky values ("Script Computed Center Frequency" column) will be on the set day and time. The default values are 58288 01:31:38 LST which translates to 2000Feb01 00:00:00 UT.

Special Modes Tab

RFI blanking can be enabled for the entire resource. For more details, refer to the RFI Blanking section.

Validation Tab

If the resource does not validate and it's not clear why, contact the NRAO Science Helpdesk via the RCT. Contacting us via the RCT will append a log file to the ticket so we can take a deeper dive into the resource errors.

Comments Tab

You may provide comments as notes to yourself for future reference.

On November 8, 2023, a new Resource Catalog Tool was introduced which changes the way custom resources are created. This section will cover the creation of a custom Frequency Sweep resource.  If you have questions or issues, please contact us through the NRAO Science Helpdesk.

Create a Frequency Sweep Resource

After selecting to create a new instrument configuration, the New Resource Wizard pop-up box will appear with several options.

To create a frequency sweep resource select,

• Frequency Sweep
• Array Configuration: This will set the recommended default correlator integration time, which can be changed later if needed.
• Observing Band: Be sure to select the correct observing band since it cannot be changed at a later step.
• Sampler Input Mode: 8-bit or 3-bit, mixed mode can be chosen in the Basebands tab
• Name: This should match the name of the resource entered in the PST.
• Finally, select the Generate button.

Basics Table

Near the top you will find the Basics info table (see Figure 3.11) were you can change the name of the resource and the correlator integration time.

Figure 3.11: Frequency Sweep Basics info table.

Below is a description of the parameters in the Basics table.

Lines Tab

In the Lines tab, you may either enter the line information one-at-a-time by selecting Add Line or import a text file containing a list of lines by selecting:

Import Spectral Lines → Browse (select the txt file containing the lines you want to import/upload) → Upload  → Done (if using Firefox)

(Note, if you are using Firefox you will be required to select the Done button after selecting Upload to complete the import. Otherwise, selecting Upload will complete the import.)

Figure 3.12: Frequency Sweep Lines tab.

 For each line you will need to provide the following information:

Below is an example of a line text file for a Frequency Sweep resource. For more details, refer to the OPT manual. Note, you may also use the same syntax you would use for a spectral line text file. This means you may export a set of lines from an existing resource in the RCT-observing (this is the RCT used in conjunction with the OPT when setting up observations).

#Line name; Rest frequency; Rest frame; Velocity convention; Velocity; Minimum range; Channel separation; Polarization products
HI-1; 1.420405751GHz; Barycentric; Radio; 3000.0km/s; 100.0km/s; 1.0km/s; FULL
HI-2; 1.420405751GHz; Barycentric; Radio; 9000.0km/s; 100.0km/s; 1.0km/s; FULL
HI-3; 1.420405751GHz; Barycentric; Radio; 15000.0km/s; 100.0km/s; 1.0km/s; FULL

Basebands Tab

Set the baseband center frequencies and sampler input mode.

Subbands Tab

The lines added to the Lines tab will appear as a guide for placing continuum subbands with more correlator resources, e.g., BlBP stacking and recirculation. For more details on stacking BlBPs and increasing recirculation, please refer to the Recirculation vs Baselineboard Pairs section.

For each baseband, continuum subbands can be added one-at-a-time by selecting Add or use the recommended Fill button at the "Subbands in Basebands" level (see Figure 3.13). Manually adding subbands one-at-a-time will require the user to select the Add button, then select the central frequency range of each continuum subband by choosing the desired range in the drop-down menu located in the subbands table. With either option, bulk filling the subbands or manually adding the subbands, the user can edit individual subbands as needed.

Figure 3.13: Subbands tab.

Selecting Fill, the user will be presented with a pop-up box containing the following parameters:

Doppler Settings Tab

This is optional. For more details, refer to the Doppler Tuning Tab portion of the Spectral Line Setup section.

Special Modes Tab

RFI blanking can be enabled for the entire resource. For more details, refer to the RFI Blanking section.

Validation Tab

If the resource does not validate and it's not clear why, contact the NRAO Science Helpdesk via the RCT. Contacting us via the RCT will append a log file to the ticket so we can take a deeper dive into the resource errors. 

Comments Tab

You may provide comments as notes to yourself for future reference.