Configure the GBT system

Configure the GBT system#

The routing of signals through the GBT system is controlled by many electronic switches which eliminate the need to physically change cables by hand. The GBT’s electronically configurable IF system allows many, and more complicated paths for the signals to co-exist at all times. Configuring the GBT IF system can usually be accomlished in under one minute.

Defining and executing a configuration#

Configurations are defined as sets of keyword-value pairs within a single string variable. To execute a configuration, this variable is passed as an argument into the Configure() command in an SB. For each configuration all keywords and values exist as line separated ‘keyword=value’ pairs, all enclosed within a single set of triple-quotes.

Configurations may be defined in two ways:

  1. The configuration definition may reside in a text file external to the SB. It can then be loaded into the SB via the execfile() command.

    # An SB to configure only -- Configuration is defined in an external file.

execfile('mypath/filename.py')
Configure(myconfiguration)

  2. The configuration may be explicitly defined with the SB.

    # An SB to configure only -- Configuration is defined here.

myconfiguration = '''
# This is a comment
primarykeyword1 = your primarykeyword value
primarykeyword2 = your primarykeyword value
...
...
primarykeywordN = your primarykeyword value
'''

Configure(myconfiguration)

We usually recommend that configuration definitions reside in text files external to the SB. This allows for configurations to be changed on the file without the need to re-validate and re-save the SB. It also allows for simple SBs without clutter.

Note

You should always use execfile rather than import, as import will not reread the file and miss any changes that you may have made.

Explicitely defining configurations within SBs allows you to easily edit and view your configuration from AstrID. If you chose this method, you must re-validate and re-save your SB if you make any changes.

If you use multiple configurations, we recommend that you define them all in one text file and load them into the SB via a single execfile() command. You may then use Configure() to execute each configuration as necessary.

Resetting the configuration#

The configuration tool in AstrID remembers all the keyword values defined during a session. This feature occasionally results in AstrID being unable to validate an otherwise correct configuration because of previously set values or hardware being configured improperly. To reset the configuration parameters to their default state, you can issue the ResetConfig() command in a script before another Configure().

Configuration keywords#

Required keywords#

The following keywords do not have default values and must be present in all configuration definitions.

receiver (str)#

Specifies the name of the GBT receiver to be used. The names and frequency ranges of the receivers can be found in Table 10 and Table 11.

backend (str)#

Specifies the name of the backend (data acquisition system) to be used. Valid backends are listed in Table XX

Todo

Add table reference.

obstype (str)#

Specifies the type of observing to be performed. The allowed values are one of the following strings:

  • 'Continuum'

  • 'Spectroscopy'

  • 'Pulsar'

  • 'Radar'

  • 'VLBI'

bandwidth (float)#

Specifies the bandwidth in MHz to be used by the specified backend. Possible values depend on the receiver and backend that are chosen. For VEGAS values are listed in Table 15.

Todo

Add reference to table 9.2 in observer guide (bandwidth per backend).

restfreq (depends)#

Specifies the rest frequencies for spectral line observations or the center frequencies for continuum observations. There are three available syntaxes for restfreq:

  1. Simple: list of comma separated float values (MHz)

    restfreq = 1420, 1661, 1667
deltafreq = 0, 5, 0

    This example sets three rest frequencies and offsets the second window (1661 MHz) by +5 MHz in the local (topocentric) frame using the deltafreq keyword. Rest frequencies may be specified as a list of comma separated float values in MHz. This syntax should be used when all beams (including single beam receivers) are configured to observe the same rest frequencies and VEGAS does not need to use an advanced configuration.

    Note

    • deltafreq can also be specified using the same syntax as restfreq, a single global offset, or omitted to use the default value of zero

    • if dopplertrackfreq is not set in the main configuration block, then the first rest frequency listed using this syntax will be doppler tracked by default

  2. Multi-beam: python dictionary

    restfreq = {24000: '1, 2, 3, 4',
            23400: '5, 6',
            25000: '7',
            'dopplertrackfreq': 24200}

 #deltafreq must be specified with this syntax - even when zero
 deltafreq = {24000: 0, 23400: 0, 25000: 0}

    This example specifies a rest frequency of 24000 MHz for beams 1-4, 23400 MHz for beams 5 and 6, and 25000 MHz for beam 7. Different feeds of multi-beam receivers may be tuned to different rest frequencies. Rest frequencies and delta frequencies are input as python dictionaries. Further information on this syntax and examples can be found in section Introduction to Spectral Windows.

    Note

    • deltafreq must always be specified as a separate python dictionary, even when zero

    • dopplertrackfreq must always be specified in the restfreq python dictionary

  3. Advanced: list of python dictionaries

    bandwidth = 23.44
nchan = 32768
dopplertrackfreq = 1420.0
restfreq = [{'restfreq': 1420.0},
            {'restfreq': 1420.0, 'deltafreq': -20.0},
            {'restfreq': 1667.0, 'bandwidth': 11.72, 'nchan': 65536}]

    This example will configure VEGAS to use 3 rest frequencies. The first two windows are centered o` 1420 MHz with mode 23 of VEGAS using bandwidth=23.44 and nchan=32768 from the main configuration block (8 subbands are selected by default for bandwidth=23.44). However, deltafreq has been used as a dictionary key to offset the second window by -20 MHz in the local topocentric frame. A third window is centered on 1667 MHz with mode 16 of VEGAS using the bandwidth and nchan dictionary keys to override values from the main configuration block.

    This syntax may be used to more precisely configure VEGAS observations and specifies restfreq as a list of python dictionaries.

    Available dictionary keys are:

    • 'restfreq': float in MHz

      only required key for each dictionary term

    • 'res': float in kHz

      spectral resolution, can be used as an alternative to the nchan restfreq dictionary key or the nchan keyword in the main configuration block to select the VEGAS mode (see Table 15).

    • 'bank': str ('A' \(\rightarrow\) 'H')

      specifies which VEGAS bank to use. The default is to let the configuration tool select which bank should be used (recommended).

    • 'bandwidth':

      same meaning as the standard configuration keyword

    • 'nchan'

      same meaning as the standard configuration keyword

    • 'deltafreq'

      same meaning as the standard configuration keyword

    • 'tint'

      same meaning as the standard configuration keyword

    • 'vpol'

      same meaning as the standard configuration keyword

    • 'beam'

      same meaning as the standard configuration keyword

    • 'subband'

      same meaning as the standard configuration keyword

    Note

    • Key-value pairs specified in the dictionary override configuration keywords specified in the main configuration block which in turn override any default values.

    • dopplertrackfreq must always be set in the main configuration block

    • deltafreq may still be specified as a single global offset in the main configuration block or ommitted to use the default value of zero.

    • nchan must always be set in the main configuration block, even if that value is overridden by nchan in the restfreq dictionary.

Optional keywords#

swmode (str)#

Specifies the switching mode to be used for the observations. The keyword’s value is given as a string. Te switching schemes are

  • ‘tp’: (Total Power With Cal) - The noise diode is periodically turned on and off for equal amounts of time.

  • ‘tp_nocal’: (Total Power Without Cal) - The noise diode is turned off for the entire scan.

  • ‘sp’: (Switched Power With Cal) - The noise diode is periodically turned on and off for equal amounts of time while another component is in a signal state and then again in a reference state. This is used in frequency switching, where the signal state is one frequency and the reference is another frequency. Similarly beam switching and polarization switching change the beams or polarizations so that their signals are sent down two different IF paths.

  • ‘sp_nocal’: (Switched Power Without Cal) - The noise diode is turned off while another component is switched between a signal and reference state.

Todo

Add instructions what to use for receivers that do not use a noise diode.

swtype (str)#

Only used when swmode='sp' or swmode='sp_nocal'. It specifies the type of switching to be performed. This keyword’s values are:

  • 'none'

  • 'fsw' - frequency-switching

  • 'bsw' - beam-switching

  • 'psw' - polarization-switching

The default value is 'fsw' for all receivers except receiver='Rcvr26_40', for which the default is 'bsw'.

swper (float)#

Defines the period in seconds over which the full switching cycle occurs. See Table 16 and Table 17 for recommended minimum switching periods for each VEGAS mode.

Default values are 0.2 for obstype='continuum', 0.04 for obstype='pulsar', and 1.0 for any other value for the obstype keyword.

swfreq (float, float)#

Defines the frequency offsets used in frequency switching (swtype='fsw'). The value consists of two comma separated floats which are the pair of frequencies in MHz. The best values for swfreq are bandwidth/2n where n is an integer, so that the frequency switch will be an integer number of channels giving less artifacts in data reduction. Default values are swfreq=-0.25*Bandwidth, +0.25*Bandwidth for swtype='fsw', and swfreq=0,0, otherwise.

tint (float)#

Specifies the backend’s integration (dump) time. The value is a float with units of seconds. See Table 15 for minimum integration times with VEGAS. Default values are

  • 10.0 for obstype='continuum'

  • tint=swper for obstype='spectroscopy'

  • 30.0 for any other value of the obstype keyword

beam (str of comma separated int)#

Specifies which beams are to be used for observations with multi-beam receivers. The keyword value is a string of comma separated integers. For example beam='2' would record data for the second beam and beam='3,7' would record data for beams 3 and 7. When using the KFPA, beam='all' can be used to record data from all seven beams. This beam configuration keyword has a different meaning to the beamName in observing scans, which usually specifies a tracking beam, not which beam to record data for. The default value is '1'.

Todo

Add that beam=’all’ does not only apply to the KFPA but also e.g. Argus.

nwin (int)#

Specifies the number of frequency windows that will be observed for backends other than VEGAS. The value for this keyword is an integer with a maximum value that is backend and receiver dependent. The number of values given for the restfreq keyword must be the same as nwin. The default value is 1.

Note

nwin does not need to be specified for VEGAS configurations.

deltafreq (depends)#

Specifies offsets in MHz for each spectral window so that restfreq is not centered in the middle of the spectral window. deltafreq can be specified as a single float offset which will be applied across all windows or in the same manner as restfreq. For example using deltafreq with different types of restfreq syntax as described here. The default value is 0.0.

vframe (str)#

Specifies the velocity frame (the inertial reference frame). The keyword value is a string. Allowed values are

  • 'topo' - topocentric, i.e. Earth’s surface

  • 'bary' - barycenter of solar system

  • 'lsrk' - Local Standard of Rest kinematical definition, i.e. typical LSR definition

  • 'lsrd' - Local Standard of Rest dynamical definition; rarely used

  • 'galac' - center of galaxy

  • 'cmb' - relative to Cosmic Microwave Background

The default value is 'topo'.

vdef (str)#

Specifies which mathematical equation (i.e. definition) is used to convert between frequency and velocity. The keyword value is a string. Allowed values are

  • 'Optical' - \(v_{\text{optical}} = c \left(\frac{\nu_0}{\nu} - 1\right)\)

  • 'Radio' - \(v_{\text{radio}} = c \left(1 - \frac{\nu}{\nu_0}\right)\)

  • 'Relativistic' - \(v_{\text{relativistic}} = c \left(\frac{\nu_0^2 - \nu^2}{\nu_0^2 + \nu^2}\right)\)

The default value is 'Radio'.

Hardware dependent keywords#

(in alphabetical order)

Some configuration keywords depend on which backends and receivers are being used. Some observations may require one of these keywords while for other observations none may be needed.

broadband (int)#

This keyword is used to activate the “broadband” 7.5 GHz maximum instantaneous mode of the KFPA by setting broadband=1. This may only be used with single beam configurations using either beam 1 or beam 2 of the KFPA.

Default

The default value is broadband=0, i.e. broadband mode is turned off.

dopplertrackfreq (float)#

Specifies the rest frequency in MHz used to compute the velocity for doppler tracking. When using the simple restfreq syntax, the default is the first listed restfreq value.

nchan (int)#

Used to determine the number of spectral channels that VEGAS will provide. Available values are listed in Table 15.

Note

The following string values designed for use with the now obsolete GBT spectrometer may still be used:

  • 'low'

  • 'medium-low'

  • 'medium'

  • 'medium-high'

  • 'high'

These string values may be used to distinguish between up to 5 levels of resolution for a given bandwidth. For example, mode 18 of VEGAS could be set by setting bandwidth=11.72 and nchan=262144 or nchan='medium-high'

noisecal (str)#

All receivers below 12 GHz have two noise diodes for calibration signals – one with an equivalent brightness temperature at roughly one tenth the system temperature ('lo' value). and one nearly equal to the system temperature ('hi' value). This keyword specifies which noise diode is to be used. Allowed values are 'low', 'hi', and 'off'.

Default

The default value is 'lo' except for the Radar backend, for which the default value is 'off'.

notchfilter (str)#

There is a notch filter covering roughly 1200-1310 MHz in the L-band receiver that filters out an Federal Aviation Administration (FAA) radar signal. This keyword determines if this notch filter is in place and used by the system or is removed from the receiver’s RF path. Allowed values are 'In' or 'Out'.

Default

The default value is 'In'.

pol (str)#

Each of the prime focus, L-band, S-band, and C-band receivers have a hybrid that can output either linear or circular polarization. Additionally the W-band receiver is linear when using two beams and circular when using one beam. The pol keyword specifies whether linear or circular polarization is desired for these receivers. Allowed values are 'Linear' and 'Circular'.

Default

The default is 'Circular' for the VLBI and Radar backends and 'Linear' otherwise.

vegas.dm (float)#

[VPM] Controls the DM used for coherent dedispersion fold and search modes. It is not used by any other modes.

vegas.fold_bins (int)#

[VPM] Controls the number of pulse phase bins used for either incoherent or coherent dedispersion fold- or cal-modes. Enough bins should be used to fully resolve fine profile structure. Typical values are 256 in incoherent dedispersion modes and 2048 in coherent dedispersion fold- or cal-modes.

vegas.fold_dumptime (int)#

[VPM] Controls the length of a sub-integration in either incoherent or coherent dedispersion fold- or cal-modes. The value is specified in seconds with 10 seconds being typical. It must be shorter than the total scan length.

vegas.fold_parfile#

[VPM] Specifies the path to the ephemeris (parfile) used for either incoherent or coherent dedispersion fold-modes.

Important

The parfile must be compatible with the TEMPO1 prediction mode.

vegas.numchan (int)#

[VPM] [Cyclic Spectroscopy] Sets the number of spectral channels. Note that this is the number of channels for a single spectral window. See Table 18 and Table 19.

Important

When using cyclic spectroscopy (CS), this sets the number of polyphase filterbank channels per spectral window used in the first-stage channelization.

vegas.obsmode (str)#

[VPM] [Cyclic Spectroscopy] Controls both the dedispersion and observing mode. Allowed values are: * "search": Incoherent dedispersion search-mode. * "fold": Incoherent dedispersion fold-mode. * "cal": Incoherent dedispersion cal-mode. * "coherent_search": Coherent dedispersion search-mode. * "coherent_fold": Coherent dedispersion fold-mode. * "coherent_cal": Coherent dedispersion cal-mode.

Important

When using CS the only allowable values are "coherent_fold" or "coherent_cal".

vegas.outbits (int)#

[VPM] Controls the number of bits used for output values. The only allowed value is 8.

vegas.polnmode (str)#

[VPM] Controls whether full Stokes or total intensity data are recorded. Allowed values are "full_stokes" and "total_intensity", though total intensity can only be used in incoherent search-mode.

vegas.scale (float)#

[VPM] Controls the VPM internal gain so that the output data is properly scaled for 8-bit values. These values are empirically measured and recommended values are listed in Table 18 and Table 19..

vegas.cycspec (int)#

[Cyclic Spectroscopy] A Boolean integer flag (i.e. 1 = True, 0 = False) that controls whether cyclic spectroscopy (CS) is enabled. It will always be 1 when using the CS backend.

Default

The default value is 0.

vegas.ncyc (int)#

[Cyclic Spectroscopy] The value of \(n_{\rm cyc}\). Allowable values depend on the value of vegas.cycspec_num_bins and vegas.numchan. See Table 20 for valid parameter combinations.

vegas.cycspec_num_bins (int)#

[Cyclic Spectroscopy] The number of pulse profile bins used by the CS backend. Allowable values depend on the value of vegas.ncyc and vegas.numchan. See Table 20 for valid parameter combinations.

vegas.cycspec_fold_dumptime (float)#

[Cyclic Spectroscopy] The sub-integration time in seconds used by the CS backend. 10 seconds is a typical value. It must be shorter than the scan length.

vegas.subband (int)#

Used by the config tool to select between 23.44 MHz VEGAS modes with single and multiple spectral windows (see Table 15). It assumes values 1 or 8.

Default

The default value is 8.

Important

This value is always 1 for pulsar observing.

vegas.vpol (str)#

Specifies which spectral product to record in the FITS file. It assumes the following values:

  • 'self': Record the total intensity polarization products.

  • 'cross': Record the full Stokes polarization products.

  • 'self1': Record the polarization from the first Analog to Digital Converter (ADC) card only. There are two ADCs per VEGAS bank, one for each polarization.

  • 'self2': Record the polarization from the second ADC only.

Default

The default value is 'self'

vlbi.phasecal (str)#

This expert keyword turns the VLBI phase cals on or off. The phase cals can run at 1 MHz ('M1') or 5 MHz ('M5'). Allowed values are 'off', 'M1' or 'M5'.

Todo

Add CCB configuration keywords to this list.

Expert keywords#

(in alphabetical order)

These keywords should only be used by very experienced observers who have expert knowledge of how a given backend works or in how the GBT IF system works.

if0freq (float)#

Used to set the center frequency of the IF after the mixing of the RF signal with the first LO. The keyword value is a float with units of MHz.

if3freq (comma-separated list of floats)#

Used to set the IF input frequency of the backend. The keyword value is a comma separated list of floats with units of MHz.

ifbw (float)#

Sets the minimum IF bandwidth to be used in filters within the receiver and in the IF rack. The keyword value is a float with units of MHz.

iftarget (float)#

Specifies the target voltage level to use when balancing the IF rack. The nominal range of the IF rack is 0.0 - 10.0 and the linear range is 0.1-5.0.

lo1bfreq (float)#

Used to set the center frequency of synthesizer used for the alternative first LO, LO1B in MHz. This keyword is only to be used with the Ka-band receiver.

lo2freq (comma-separated list of floats)#

Used to set the frequency values of the eight LO2 synthesizers within the Converter Rack in units of MHz.

polswitch (str)#

Sets the polarization switch for the L-band and X-band receivers. Allowed values are 'ext', 'thru', and 'cross'.

Default

The default value is 'ext' if swtype='psw' and 'thru' otherwise.

vhigh (float)#

Specifies the maximum velocity to be observed from a group of sources in units of km/s. The use of vhigh is not recommended for frequencies where there can be large amounts of RFI.

Default

The default value is 0.0

For more information on vhigh see here.

vlow (float)#

Specifies the minimum velocity to be observed from a group of sources in units of km/s. The use of vlow is not recommended for frequencies where there can be large amounts of RFI.

Default

The default value is 0.0

More information on vlow and vhigh

The configuration keywords vlow and vhigh give the range of velocities of all sources to be observed. This information is used to set various filters in the system that will simultaneously cover the required range of velocity. Setting the velocity for each specific source is done later in the SB. For galactic sources where the range of velocities is rather small it is usually best to set both vlow and vhigh to zero.

When strong RFI is present it is best not to use vlow and vhigh. The use of vlow and vhigh can cause the GBT IF system to have a larger IF bandwidth than is necessary for a single source. This can let parts of the IF system be unnecessarily affected by RFI. The observers might need to reconfigure after each source if the change in velocity is larger than the bandwidth of a filter.

An example of how vlow and vhigh can be used is as follows. Suppose that you are looking for water masers in extragalactic AGN. Furthermore, let’s say that you are looking at 100 candidates with velocities from 1,000 km/s to 40,000 km/s. Then you would set vlow=1000.0 and vhigh=40000 km/s and will not change the IF configuration when you change sources.

Note that if vdef='Red' (i.e., redshift), then you must give the redshift parameter “z” as the values for vlow and vhigh instead of velocity.

You GBT project friend can help you decide if you should use vlow and vhigh.

xfer (str)#

Sets the beam switch for the Ku-band, K-band and Ka-band receivers. Allowed values are 'ext', 'thru', or 'cross'.

Default

The default value is 'ext' when swtype='bsw' and 'thru' otherwise.

Example Configurations#

The best way to learn about how to define and perform configurations is through examples. Keywords available for use in a configuration definition have been discussed above. All examples have been placed in the directory /home/astro-util/projects/GBTog/configs/.

Todo

Check that those scripts are the same as the ones shown here.

Continuum Observations#

Listing 10 An example continuum configuration.# 
continuum_config='''
receiver  = 'Rcvr1_2'
beam      = '1'
obstype   = 'Continuum'
backend   = 'DCR'
nwin      = 1
restfreq  = 1400
bandwidth = 80
swmode    = 'tp'
swtype    = 'none'
swper     = 0.2
tint      = 0.2
vframe    = 'topo'
vdef      = 'Radio'
noisecal  =  'lo'
pol       = 'Linear'
'''

The above configuration definition has been given the name continuum_config and can be used for pointing and focusing observations or for continuum mapping. We have configured for the following:

  • The single beam L-band receiver [receiver='Rcvr1_2', beam='1']

  • Total power, continuum observations [obstype='Continuum', swmode='tp', swtype='none']

  • The DCR as the backend detector [backend='DCR']

  • Take data using a single band centered on 1400 MHz with a 80 MHz bandwidth [nwin=1, restfreq=1400, bandwidth=80]

  • Go through a full switching cycle in 0.2 seconds [swper=0.2]

  • Record data with the DCR every 0.2 seconds [tint=0.2]

  • Disable dopple tracking for continuum observations [vframe='topo', vdef='Radio']

  • Use a low-power noise diode [noisecal='lo']

  • Linear polarization [pol='Linear']

Spectral Line, Frequency Switching Observations#

Listing 11 An example frequency-switched, spectral line configuration.# 
fs_config='''
receiver  = 'Rcvr1_2'  
obstype   = 'Spectroscopy'
backend   = 'VEGAS'
restfreq  = 1420
bandwidth = 23.44 
nchan     = 65536
vegas.subband = 1
swmode    = 'sp' 
swtype    = 'fsw'
swper     = 2.0
swfreq    = 0, -5.0
tint      = 10 
vframe    = 'lsrk'
vdef      = 'Radio'
noisecal  = 'lo'
pol       = 'Linear'
'''

The above example will configure for the following:

  • The single beam L-band receiver [receiver='Rcvr1_2']

    Note

    Not specifying beam defaults to beam='1'.

  • fsw, spectral line observations [obstype='Spectroscopy', swmode='sp', swtype= 'fsw']

  • VEGAS as the backend detector using linear polarization without cross-polarization products [backend='VEGAS', pol='Linear'].

  • Take data using a single band using VEGAS mode 11 (see Table 15) defined by 23.44 MHz bandwidth, 65536 channels, and one band per spectrometer [bandwidth=23.44, nchan=65536, vegas.subband=1], centered on 1420 MHz [restfreq=1420].

  • Go through a full switching cycle in 2 seconds [swper=2.0]. Over one cycle, the fsw states will be centered on the line, and then be shifted by -5~MHz [swfreq=0,-5.0]

  • Record data with VEGAS every 10 seconds [tint=10]

  • Doppler track the spectral line with the rest frequency 1420 MHz in the commonly used Local Standard of Rest velocity with the radio definition of Doppler tracking [vframe='lsrk', vdef='Radio'].

  • Use a low-power noise diode [noisecal='lo']

Multiple Spectral Lines, Total Power Observations#

Listing 12 An example total power, spectral line configuration.# 
tp_config='''
receiver  = 'Rcvr8_10'
obstype   = 'Spectroscopy'
backend   = 'VEGAS'
restfreq  = 9816.867, 9487.824, 9173.323, 8872.571, 
            9820.9, 9821.5, 9822.6, 9823.4, 9824.6
dopplertrackfreq = 8873.1
bandwidth = 23.44 
nchan     = 8192
swmode    = 'tp'
swtype    = 'none'
swper     = 1.0
tint      = 30 
vframe    = 'lsrk'
vdef      = 'Radio'
noisecal  = 'lo'
pol       = 'Circular'
'''

The above example will configure for the following:

  • The single beam X-band receiver [receiver='Rcvr8_10]

    Note

    Not specifying beam defaults to beam='1'.

  • Total power, spectral line observations [obstype='Spectroscopy', swmode='tp', ``swtype='none']

  • VEGAS as the backend detector using circular polarization without cross-polarization products [backend='VEGAS', ``pol='Circular']

  • Mode 21 of VEGAS (see Table 15). This mode is defined by a bandwidth of 23.44 MHz, 8192 spectral channels in the eight subband mode of VEGAS [bandwidth=23.44, nchan=8192]

    Note

    Not specifying vegas.subband for a bandwidth of 23.44~MHz will default to vegas.subband=8.

  • 9 spectral windows, each of which centered on one of the 9 frequencies (in MHz) listed under restfreq [restfreq=9816.867, 9487.824, 9173.323, ....]

  • Go through a full switching cycle in 1 second [swper=1.0] and record data with VEGAS every 30 seconds [tint=30].

  • Doppler track the spectral line with the rest frequency 8873.1 MHz [dopplertrackfreq=8873.1] in the commonly used Local Standard of Rest velocity [vframe='lsrk'] with the radio definition of Doppler tracking [vdef='Radio']

  • Use a low-power noise diode [noisecal='lo']

Multiple Spectral Lines, Multi-beam, Total Power Observations#

Listing 13 An example total power, spectral line configuration for a multi-beam receiver.# 
tp_config_multi_beam = '''
receiver  = 'Rcvr40_52'
beam      = '1,2'
obstype   = 'Spectroscopy'
backend   = 'VEGAS'
restfreq  = 44580, 43751, 45410, 46250
deltafreq = 0,100,0,0
bandwidth = 1500
nchan     = 16384
swmode    = 'tp'
swtype    = 'none'
swper     = 1.0
tint      = 10
vframe    = 'lsrk'
vdef      = 'Radio'
noisecal  =  'lo'
pol       = 'Circular'
'''

The above example will configure for the following:

  • The dual beam Q-band receiver using both beams [receiver='Rcvr40_52', beam='1,2']

  • Total power, spectral line observations [obstype='Spectroscopy', swmode='tp', swtype='none']

  • VEGAS as the backend detector using circular polarization without cross-polarization products [backend='VEGAS', pol='Circular']

  • Mode 2 of VEGAS (see Table 15). This mode is defined by a bandwidth of 1500 MHz with 16384 spectral channels [bandwidth=1500, nchan=16384]

  • 4 spectral windows, each of which centered on one of the 4 frequencies (in MHz) listed under restfreq [restfreq=44580, 43751, 45410, 46250]

  • Shift the window centered on 43751 MHz by 100 MHz in the local (topocentric) frame. Thus, this window will now be centered on 43851 MHz [deltafreq=0,100,0,0]. deltafreq should be defined in the same manner as restfreq: This example uses 4 comma separated values.

  • Go through a full switching cycle in 1 second [swper=1.0] and record data with VEGAS every 10 seconds [tint=10].

  • Doppler track the spectral line with the rest frequency 44580 MHz (default is the first specified rest frequency) in the commonly used Local Standard of Rest velocity [vframe='lsrk'] with the radio definition of Doppler tracking [vdef='Radio'].

  • Use a low-power noise diode [noisecal='lo']

Multiple Spectral Lines, KFPA Observations#

Listing 14 An example total power, spectral line configuration for the KFPA.# 
kfpa_config='''
receiver  = 'RcvrArray18_26'
beam      = 'all'
obstype   = 'Spectroscopy'
backend   = 'VEGAS'
restfreq  = {24600:'1,2,3,4', 23900:'5,6,7', 25500 : '-1',
             'DopplerTrackFreq': 24700} 
deltafreq = {24600:-100, 23900:0, 25500:0} 
bandwidth = 187.5  
nchan     = 32768
swmode    = 'tp'
swtype    = 'none'
swper     = 1.0
tint      = 30 
vframe    = 'lsrk'
vdef      = 'Radio'
noisecal  = 'lo'
pol       = 'Circular'
vegas.vpol= 'cross'
'''

The above example will configure for the following:

  • The KFPA receiver using all 7 beams [receiver='RcvrArray18_26', beam='all']

  • Total power, spectral line observations [obstype='Spectroscopy', swmode='tp', ``swtype='none']

  • VEGAS as the backend detector with circular cross-polarization products [backend='VEGAS', vegas.vpol='cross', pol='Circular']

  • Mode 4 of VEGAS (see Table 15). This mode is defined by a bandwidth of 187.5 MHz with 32768 spectral channels [bandwidth=187.5, nchan=32768]

  • 3 spectral windows centered on 24600, 23900, and 25500 MHz. Data will be recorded for beams 1 \(\rightarrow\) 4 using the first window (24600 MHz) while beams 5 \(\rightarrow\) 7 will use the second window (23900 MHz). An additional IF path will be routed from beam 1 to the window centered on 25500 MHz. This is known as the “7+1” mode of the KFPA [restfreq={24600:'1,2,3,4', 23900:'5,6,7', 25500:'-1', 'DopplerTrackFreq': 24700}].

    Note

    Doppler tracking the center (24700 MHz) of the full frequency range (25500 - 23900 + bandwidth) is necessary in this example. The maximum frequency separation limitation of the KFPA is 1.8 GHz when using multiple beams.

  • The Radio definition of doppler tracking has been used in the Local Standard of Rest Velocity [vframe='lsrk', vdef='Radio']

  • Shift the window centered on 24600 MHz by -100 MHz in the local (topocentric) frame. Thus, this window will now be centered on 24500 MHz [deltafreq={24600:-100, 23900:0, 25500:0}]. deltafreq should be defined using the same syntax as restfreq: This example uses Python dictionary syntax.

  • Go through a full switching cycle in 1~second [swper=1.0] and record data with gls{VEGAS} every 30~seconds [tint=30].

  • Use a low-power noise diode [noisecal='lo']

Advanced Use of the restfreq Keyword#

Listing 15 An example showing advanced use of the restfreq keyword.# 
receiver = 'Rcvr12_18'
beam = '1,2'
obstype = 'Spectroscopy'
backend = 'VEGAS'
swmode = 'tp' 
swtype = 'none'
swper = 1.0
tint = 10 
vframe = 'lsrk'
vdef = 'Radio'
noisecal = 'lo'
pol = 'Circular'
bandwidth = 23.44
nchan = 32768
dopplertrackfreq = 13500.0
restfreq = [
 {'restfreq':14000,'bank':'A','bandwidth':1500,'nchan':1024,'beam':'1'},
 {'restfreq':14000,'bandwidth':1500,'nchan':1024,'beam':'2'},
 {'restfreq':13000,'bandwidth':187.5,'nchan':32768,'beam':'1'},
 {'restfreq':13100,'bandwidth':187.5,'nchan':32768,'beam':'2',
                    'vpol':'cross','deltafreq':1},
 {'restfreq':13200,'bank':'C','bandwidth':23.44,'res':0.7,'beam':'1',
                    'subband':8},
 {'restfreq':13300,'bank':'C','bandwidth':23.44,'res':0.7,'beam':'1',
                    'subband':8},
 {'restfreq':13400,'bank':'C','bandwidth':23.44,'res':0.7,'beam':'1',
                    'subband':8},
 {'restfreq':13400,'bandwidth':23.44,'res':0.7,'beam':'2',
                    'subband':1},
 {'restfreq':13500,'bandwidth':100,'nchan':32768,'beam':'1'},
 {'restfreq':13500,'bandwidth':100,'nchan':32768,'beam':'2'}]
'''

The above example uses the advanced restfreq syntax (an array of Python dictionary terms) to more precisely configure the GBT system.

Caution

Note that this is an example of usage only and it is not recommended that users attempt to manually route beams to specific VEGAS banks.

When using the advanced restfreq syntax, it is important to be aware of the following details in the main configuration block:

  • Key values specified in the restfreq dictionary term override key-values pairs in the main configuration. If no values for a key have been specified, a default value will be used if available.

  • bandwidth and nchan must always be specified in the main configuration block outside of restfreq. This is required for the configuration to pass validation, even if such values are redundant [bandwidth=23.44, nchan=32768]

  • dopplertrackfreq must be set by the user [dopplertrackfreq=13500.0] since there is no default doppler tracking frequency for the advanced restfreq syntax.

The following points give details on the usage of the advanced restfreq syntax in this example:

  • Multiple rest frequencies (or windows centered on a rest frequency) are input as an array of Python dictionary terms. The restfreq dictionary key is the minimum required entry for each dictionary term and specifies the center of each window. Each bank may also be configured with different resolution, bandwidth, and number of spectral windows. However, the integration time, switching period and frequency switch must be the same for all banks.

  • Each window may be routed to a specific bank (VEGAS spectrometer) with the bank dictionary key (see the first window of this example). By omitting bank, the system will attempt to route windows to available banks automatically (recommended). Note that certain restrictions exist when routing multi-beam receivers to VEGAS banks.

    Todo

    Add reference to VEGAS IF section and KFPA (also Argus?) for further information.

  • The beam dictionary key specifies which beam is used for the window. Omitting beam defaults to beam 1 ['beam': '1']

  • VEGAS modes are set for a window by defining valid combinations of bandwidth and resolution, and the number of sub-bands if using a 23.44~MHz bandwidth (see Table 15). If these values are not defined as dictionary keys, then values defined in the main configuration block or default values will be used. It is worth noting the following points in this example:

    • Bank C has been split into 3 subbands and uses VEGAS mode 23 defined by 23.44 MHz bandwidth, 8 subbands, and 0.7 kHz resolution ['bank': 'C', 'bandwidth': 23.44, 'res': 0.7, 'subband': 8]. The 3 windows are centered on 13200, 13300, and 13400 MHz.

      Note

      All sub-bands within a single bank must use identical VEGAS settings apart from the center frequency and offset.

    • A second window has been centered around 13400 MHz using a bandwidth of 23.44 MHz with 0.7 kHz resolution. However, this window is configured to use beam 2 and mode 10 of VEGAS with a single sub-bank ['restfreq': 13400, 'bandwidth': 23.44, 'res':0.7, 'beam': '2', 'subband':1]

    • The window centered at 13100 MHz gives an example of the other dictionary keys available. This window has been shifted +1 MHz in the local frame ['deltafreq': 1] to be centered on 13101 MHz. Data will be recorded with full Stokes polarization products ['vpol': 'cross']. All other windows will record data with total intensity polarization products [vegas.vpol='self' (the default setting)]

Introduction to Spectral Windows#

Several simultaneous frequency bands may be specified with a list of rest frequencies and offsets (keywords restfreq, deltafreq). If using a backend other than VEGAS, the nwin (number of spectral windows) keyword will also need to be specified. Each spectral window includes both polarizations. i.e., if you specify one window, you get two IF systems routed to the back end device, one for each polarization; if you specify two windows, you get IFs, and so forth.

The configuration software tries to put the midpoint of the total frequency range spanned by all windows at the center of the nominal IF1 band so as to use the narrowest IF bandpass filters that will pass the desired range of frequencies. In some uncommon cases this is not possible, so the IF bandwidth must be increased to pass the desired range of frequencies.

You specify the rest frequencies (restfreq keyword) and may also specify a range of radial velocities (vlow and vhigh keywords). The various IF filters are set to include the range of frequencies in the local frame required by the radial velocity range. The configuration software predicts the local frequency for each spectral window based on the rest frequencies and the radial velocity. During observing the tracking LO will correctly track the doppler tracking frequecy set by the dopplertrackfreq keyword. If dopplertrackfreq is not provided, the default value will be the first spectral window specified by the restfreq keyword (if not using the advanced restfreq syntax). Because there is only one tracking LO, the other spectral windows are set up with frequency offsets in the local frame with respect to the doppler tracking frequency. When observing at a variety of high velocities, one should run a configuration for each change of velocity (i.e., do not rely on just changing the velocity in the LO1 manager), and one should set vlow=vhigh.

Note that the deltafreq keyword gives frequency offsets that are applied in the local (or topocentric) frame i.e., it is applied as an offset in the IF system. For example, if \(V_{\text{frame}}\) is velocity of the reference frame, \(V\) is source velocity in that frame, \(\nu_{\text{rest}}\) is the rest frequency of the line and we use the Radio definition of velocity then the topocentric frequency will be

\[\nu_{\text{topo}} = \nu_{\text{rest}} \left( 1 - \frac{\left(V+V_{\text{frame}}\right)}{c} \right) + {\text{deltafreq}}\]

Finally note that the expert user may specify any of the IF system conversion frequencies and total IF system bandwidth, overriding the calculations done by the configuration software (ifbw, if0freq, lo1bfreq, lo2freq, and if3freq keywords). This option may be needed in some peculiar cases. Of course one needs a good knowledge of the gls{IFsys} to make use of this option.

Array Receiver Spectral Windows#

Array Receivers can be configured with a variety of spectral windows. The configtool, part of AstrID, sets up these spectral windows, and a new syntax was required to specify more complex configurations. Each feed has the potential to be tuned to a different rest frequency. For the K-Band Focal Plane Array (KFPA) receiver, a special 'all' beam mode is defined which uses all 7 beams, plus one beam tuned to a second, different spectral window. This stretches the syntax of the configtool restfreq and deltafreq keywords. In order to support these modes within the configtool, expanded values and intepretations of nwin, deltafreq and restfreq were implemented.

The syntax uses a python dictionary for the restfreq and deltafreq keyword values for KFPA configurations. The restfreq dictionary maps beams and frequencies of the spectral windows. The delta frequency is a map of deltafreq to restfreq. The list of values syntax continues to be supported for simpler modes. When the dictionary is used to specify the rest frequencies, this dictionary must contain a key named DopplerTrackFreq. The value assigned to this key is the rest frequency that will be used by the LO as the Doppler tracking frequency.

Todo

Double-check if this should be DopplerTrackFreq or dopplertrackfreq.

The following examples show how to specify configtool frequency settings:

  • Example 1

    Requests that beams 1,2,3 and 4 have a rest frequency of 24000~MHz, that beams 5,6,7 have a rest frequency of 23400 MHz and the 2nd beam 1 IF band has a rest frequency of 25000 MHz. There are no delta frequencies used in this observation. For non zero delta frequencies, the deltafreq values should be specified in the same manner as the restfreq.

    beam = 'all'
restfreq = {24000: '1,2,3,4', 
            23400: '5,6,7',
            25000: '-1',
            'DopplerTrackFreq': 24200}
deltafreq = {24000: 0,
             23400: 0,
             25000: 0}

  • Example 2

    For simple configurations the syntax for the existing receivers would also be supported. This results in the routing of 4 beams, 2 polarizations with each tuned to a rest frequency of 24000 MHz.

    beam     = '1,2,3,4'
restfreq = 24000

  • Example 3

    Comparison of two configtool inputs where restfreq is a list, and input with the dictionary syntax. The two configurations are equal.

    beam     = '1,2'
restfreq = 23706.3, 24139.417  
deltafreq= 0, 0


    beam     ='1,2'
restfreq ={23706.3: '1,2',
           24139.417: '1,2',
          'DopplerTrackFreq': 23706.3 }
deltafreq={23706.3: 0, 
           24139.417: 0}

  • Example 4

    8 different rest frequencies specified.

    restfreq = {23706.3: '1',
            24139.417: '2',
            24139.417: '3',
            24706.3: '4',
            24149.4: '5',
            24122: '6',
            23899: '7',
            24876.1: '-1',
            'DopplerTrackFreq': 24876}

  • Example 5

    A configuration that specifies delta frequencies.

    beam     = 'all'
restfreq = {24000: '1,2,3,4', 
            23400: '5,6,7',
            25500: '-1',
            'DopplerTrackFreq': 24876} 
deltafreq= {24000: 0, 
            23400: -500,
            25500: 0}