Spectral Line Resources

by Gustaaf Van Moorsel last modified Mar 10, 2017 by Lorant Sjouwerman

Creating a spectral line resource is similar to creating wide band resources as outlined above, 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 not much of this has been implemented.

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 from scratch, just like creating a wide band resource previously.  Some items that need extra attention are described below, step-by-step, but first a small detour to outline the options for creating large numbers of narrow frequency channels.

Recirculation versus 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 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.

Creating a new Resource

First, navigate to the Resource Catalog Tool (RCT).  Then:

  • From the top menu strip, select FILE - CREATE NEW - CATALOG or select an existing personal catalog.
  • Your new catalog with the default name [New Catalog] appears in the main editing window. Change the name of the catalog to something useful (to remind you of its purpose).
  • Optionally add the names of co-workers who you want to share the catalog resources with and can edit the resources in the catalog.
  • At this stage you can opt to group your resources. This is not necessary, but convenient if you are going to have many resources. If you want to group resources in this catalog, select FILE - CREATE NEW - GROUP, and name your group under the Properties tab.
  • From the top menu strip, select FILE - CREATE NEW - INSTRUMENT CONFIGURATION. You will be presented with a resource page an example of which is shown in Figure 3.8 below.

    Defining the newly created Resource

    The instrument configuration is built up by going through 6 steps, represented by the 6 tabs in Figure 3.8, and summarized in the table below. If you know what you want exactly, e.g. because you have a fixed (sky) frequency for your line or have calculated your Doppler frequency by hand and want to include that in a fixed frequency resource, skip the Line and Line Placement tabs and tune the basebands (with Doppler setting switched off) and subbands directly in the Basics, Basebands and Subbands tabs. Before continuing you may want to read up on Doppler Setting and Dynamic Scheduling.

    Basics Name resource, specify band and integration time
    Lines Enter all lines and their properties that you'd like to cover
    Basebands Tune basebands to opimize your line coverage
    Line Placement Generate template subbands to cover the lines
    Subbands Inspect subbands from previous step and modify if necessary
    Validation Validate for correctness



    • Choose a correlator visibility integration time; the default integration times are given here, where the larger values will reduce the size of the data set. The correlator integration time may be adjusted later (upward) to remain within the maximum data rate for the specific setup you are creating.

    Figure 3.8 - Screenshot of the RCT in the 8-bit case, Basic Tab.  Note the two independently tunable basebands.  The 3-bit equivalent has four such basebands


    • Specify the sky position for which your observations should be Doppler set (tracked); you can use the Import Source Position button to use a predefined source from one of your source catalogs in the SCT. Note that any velocity specified for a source is not used in the resource; this is specified here in the Lines and Baseband tabs. If you have more than one source, you can specify an average velocity, a separate line for each source velocity or create a new resource per source. Do not specify a position if you are specifying an exact sky frequency for your lines.
    • In the Lines table, click on Add Line. A row with label L1 will appear. The next step is to specify the specifics of the subband that will cover this line.
    • Name your line and specify the line rest frequency, line-of-sight velocity at which the line should be observed and the rest frame and convention to be used in Doppler calculations. Furthermore, specify the minimum velocity range that should be covered. Note that a first order bandwidth for this range will be calculated using the line frequency and displayed below the input field. This will set the subband bandwidth to the next wider possible value. Try to keep the bandwidth for the range as narrow as possible for your science to maximize flexibility in placing the 128 MHz boundaries between your anticipated subbands; you can widen them later. In general pre-defining subbands wider than 32 MHz will often give problems in the initial placing of the subbands as the final baseband center frequencies are not well determined. Similarly the (maximum) channel separation input field will display the velocity width converted to frequency below the input field, and set the channel separation in the subband to the next possible narrower value. Finally choose the polarization products required for this line. By default the option to use Recirculation when possible (over Baseline Board Stacking) is switched on, and unchecking the box will consider Baseline Board Stacking only when configuring the subband for this line setting.
    • Build your list of lines by adding additional lines and repeating the previous step. You can copy the last line to copy the items and make your editing easier using the Copy Last Line button. If there is a specific frequency that you want to Doppler set (track) on, but is not a line that you want to observe as such, e.g., a baseband center frequency, include it in this list. To remove an unwanted line click the delete icon (delete) to the right of the row that needs to be deleted.
    • Note the summary of the baseline board pairs (Bl.BPs) in the top table next to the baseband graph. Only 64 baseline board pairs can be used and this number will be updated in the following steps when generating and updating subbands.

    To prevent having to do the work again for a next resource with similar lines there is an option to download or import the line details at the bottom of the lines tab. See Section 6.5 in the OPT manual for the syntax.

      Figure 3.9 - The Line Tab of the RCT after adding two lines.  Note how neither baseband covers a line



      • For the high frequency bands (K, Ka, and Q) the default is to use 3-bit samplers covering 8 GHz bandwidth using four 2 GHz basebands, but you may select the 8-bit system to use two 1 GHz basebands. For all other bands the default is to use the 8-bit setup. If 3-bit selection is not possible, copy (and edit) a resource from the NRAO Defaults catalog. Ignore the message that there are no subbands defined yet (which is done in a next step).
      • For each baseband select the baseband center frequency if the defaults won't work for you. Remember that the exact baseband center itself cannot be observed as it falls on one of the 128 MHz boundaries. Try to place your lines as much as possible in the middle of the available basebands, or alternatively in as few basebands (i.e., one if possible) as long as your lines are not very close to the baseband edges and not close to the 128 MHz intervals within each baseband. If you plan on doing this, remember the restrictions: for 3-bit the baseband centers for A1C1 and A2C2 must be well within 2.5-3 GHz (same for B1D1 and B2D2) to pass through the 5 GHz down-converted frequency bandwidth at the antennas. In cases where AC and BD are spread over a large range (>4 GHz) usually AC needs to have the upper center frequencies and the maximum span of all frequencies in any band must be less than 12 GHz. Ka band has extra restrictions (see below or the OSS).
      • Once the baseband centers are set, typically after the subband step below, select for each baseband the Doppler setting characteristics. That is, from the list of lines specified in the Lines tab define the line that will be used to calculate the Doppler shift of the entire baseband for the sky position entered in the Lines tab. Formally your Doppler frequency will be correct for only one line per baseband at the start of your observation, but in practice the differences between the lines in a baseband usually are small enough to correct for in post-processing. This Doppler setting "line" does not have to be observed as that line, but it needs to be specified as a line option (with velocity and definitions) in the Lines tab. For example, one can specify a pseudo-line which is the baseband center frequency, skip generating a subband for it (as that won't fly because it falls on a 128 MHz boundary), but select it as the Doppler setting frequency.

      Figure 3.10 - The Baselines Tab of the RCT after shifting both basebands such that both lines are covered


      Line Placement

      • The lines you specified earlier will show up in a summary table. For each of the lines you want to observe hit the Generate button, which will pop-up a dialog window for confirmation. This will generate a subband with a subband bandwidth which covers at least the velocity range requested, with enough baseline board pairs assigned (within the recirculation factor allowed). It aims to cover the bandwidth with spectral channels that are at least as narrow as the requested separation with the specified polarization characteristics. When created, the part of the baseband around the line will be shaded lighter to show the allocation in the baseband (though it may be too narrow to be distinguished). If a line can be observed with more than one baseband, there is the option to select the baseband. If you hit the Generate button more than once you will generate identical subbands without actually increasing the sensitivity for that line.

      Figure 3.11 - The Line Placement Tab.  Clicking Generate creates a suggested subband setup which can be inspected in the following tab: Subbands



      • Every baseband tab will now show a table with the subbands that were generated during the Line Placement step which covers each individual line. The color assigned to a subband indicates which of the four correlator quadrant's baseline board pairs are assigned to it (in continuum typically 16 subbands have the same quadrant color) and currently for 8-bit setups you may generate up to 32 subbands in either baseband.  You have the freedom to modify the subband bandwidths, but note that each doubling of the bandwidth requires a doubling of the number of baseline board pairs or recirculation factor to retain the channel frequency width (the default behavior is to keep the number of baselineboard pairs and recirculation constant, doubling your channel separation with each doubling of the subband bandwidth). Changing the number of polarization products has a similar effect. If subband bandwidths of less than 128 MHz are used, enable Recirculation to reduce the use of the limited amount of baseline board pairs (see above).
      • The Snap to Grid and Fix to Baseband checkboxes are unchecked and/or checked by default, depending on the situation. Unchecking Snap to Grid allows for using more correlator resources to define a flatter bandpass filter and unchecking Fix to Baseband keeps the subband tuned if you decide to recenter the baseband respectively. For now, the best option is to keep them with the default at generaton: both unchecked for line work and both checked for subbands intended as continuum. Note that these items are tools to figure out the best placement of the baseband center frequency for your lines and do not really do anything during the observations and will be ignored after the frequencies are defined.
      • Under every baseband-tab (i.e., repeat this four or two times) you want to make sure you have enough continuum sensitivity (subband frequency coverage) to be able to calibrate your gains. You would want to include extra subbands you can use for this by clicking Add/Fill Subbands and placing them in a part of the observing band away from strong lines; whether they are your bright targets or RFI (for 8-bit samplers you may only generate 32 subbands). Each defined subband will fade a fraction of the color of the baseband in the graph on top so you can see whether they are avoiding your line. By default these subbands have the Snap to Grid and Fix to Baseband options reversed compared to the subbands containing your lines for flexibility.
      • If you are unhappy with any of the subbands you can delete individual subbands with the delete icon (delete) at the right hand side of the subband table. Multiple subbands can be selected and deleted with the Delete Selected Subbands button.
      • Subbands can be changed individually, or be selected and bulk-edited using Bulk Edit Selected Subbands. Note that editing is limited to the current baseband tab only; if you, e.g., want to change the polarization of the whole observation you have to repeat the editing in each of the baseband tabs. You can only enter the center frequency for subbands of 16 MHz and narrower, provided that they do not cross a 128 MHz boundary; wider subbands can only be selected from a fixed drop-down list.
      • You may limit the number of subbands (i.e., less than 64 total, 16 per baseband) in favor of more correlator products in another subband. The number of correlator products in a baseband is the number of spectral channels × the number of polarization products and each baseline board pair can produce 256 products. Doubling the number of baseline board pairs doubles the number of products at the cost of a subband per baseline board pair, but see above how to counter that with Recirculation. Keep an eye on the total number of baseline board pairs used in the top table (next to the graph); only 64 baseline boards are available. Also make sure that you do not exceed the maximum data rate (25 MB/s) for the sum of all subband resources.
      • If you want to start anew (using the already specified baseband centers), click Clear All Subbands to remove all subbands in all basebands, or delete the resource (or Group, Catalog) completely using the menu strip or icon menu.
        • Finally, judge the subbands: can they be merged, are they too close to a 128 MHz edge, are there left-over resources (baseline board pairs) to include more (e.g., continuum) subbands, to double the number of channels to increase the spectral resolution for one or more subbands, etc.?
          • The automatically generated subbands are made on a best effort basis; check the output!
          • When a subband is very close to a 128 MHz baseband edge (hover with your mouse over the yellow triangle to see how much), you may want to shift the baseband in question to a new center by returning to step 2; when doing so you should not have (any of) the generated subbands fixed to the baseband so they will not stay fixed close to the 128 MHz edge of the baseband (the default for "Fix to Baseband").
          • Adding 128 MHz continuum bands and/or switching on Doppler setting should be done after the baseband center frequencies are determined.
          • Each doubling of the subband bandwidth (e.g., when merging subbands seems useful) requires a doubling of the number of allocated baseline board pairs to retain the channel width originally requested.
          • Changing the individual subbands invalidates the input given earlier; in principle no information stays correct when stepping backward but more lines can be added to step 1 and be generated in the following steps when baseband and subband centers were calculated previously.
          • If your science has the flexibility, assign some subbands a priority other than "Required". This will allow a scheduling block with this resource to run on the telescope even if some of the hardware is inoperable or if one or more baseline boards cannot be configured at the cost of missing those subbands. The larger the number in the label, the less desired a subband is in case there are more choices that can be traded off. That is, the subband with the highest desired-number (64) will be left out first if such a need arises, the lowest (1) last, but Required subbands are never skipped.

        Figure 3.12 - The Subband Tab of the RCT, in this case showing baseband A0/C0. Note in the bottom panel where the selected bandwidth falls in the baseband



        • This allows you to inspect your setup in terms of frequencies and correlator resources (i.e., baseline board pair allocations). Check your resource, from top to bottom. If you create more than one resource, check each of the resource properties using the Show/Edit icon for each catalog entry. You can also reorganize your resources by adding groups (FILE - CREATE NEW - GROUP) and by moving your resources around using the column icon menu, or using EDIT in the top menu strip. Unwanted resources can be deleted using Cut.
        • If you are unhappy with the name of the catalog or group you can always rename it by highlighting it and then clicking on the Properties tab.

        If there is a need to modify the existing resource, after generating a resource and attaching it to scans in a scheduling block in the OPT, rename or copy it to a new name and make the modifications in the resource with the new name. This adjusted resource has to be re-attached to the scans in the scheduling blocks, replacing the faulty resource. The easiest way to do this is with the Bulk Edit Scans tab on the selected scheduling block. Having a different name for the two resources is extremely useful in checking whether the edit was successful and whether scans with the old resource have been overlooked.

        Final Check

        After all this data entering, make sure you check your catalogs for correctness. It is important that your frequencies (with Doppler definitions) are correct before creating scans in the OPT, and before storing to disk or sharing your catalogs with your collaborators.