The basic building block of all observations is the setup; all observations are driven by setups. A setup is a collection of keyword-value pairs (for example, source=venus). The concept of a setup means that everything pertinent to the observing of a particular source is kept in one concise location. The concept of setups is potentially very powerful. Because a setup contains all the information regarding a source, it is self contained, easier to maintain, to debug, and to control under what conditions observations will be permitted. Most importantly, it allows the user to create observing files based on the characteristics of the source rather than as a collection of various commands.

To create a setup, the user calls the setup command. The setup commands should be the first commands in the observing script because a setup must be defined before it is used. The setup command has the following syntax:

  setup name=A key=value ...

Only one keyword name is reserved by the command setup. It is the keyword name and it is used to specify the name of the new setup. The other keyword names for use in the setup command and their meanings (as well as their likely defaults) are described below. Most of these keywords are derived from and are analogous to the keywords used by the setfreq, setcorr, and mint commands. For further descriptions of these keywords, the reader might want to look at the documentation for these tasks. Keywords followed by task name(s) in parenthesis identify keywords that are only used by these specific tasks and do not apply to any other task.

setup

The value of this keyword is used to include other setups. Multiple setups may be included and may also be nested.

maxobs

This value specifies the maximum number of times a setup can be observed during a project. If this is not set (or is set to 0), then there is no limit to the number of times this setup is run. This parameter affects an internal variable which is initialized only once at the start of a project. If the project script needs to be stopped early for some reason and then is restarted, the value of this internal parameter is still retained (not reset). Hence, judicial use of this keyword provides the user with the control necessary to limit the number of times a setup is run (no matter how many times a script is restarted).

An obvious example of usage is for passband calibration. This is often done at the beginning of observing a project. If a script were to be restarted after the passband observation had been observed, the user would not want the script to re-observe it; that would waste value source observing time. Properly setting the maxobs keyword would limit the passband observation so it is done only once.

source

The source name of this setup. There is no default value for this keyword. If no source is specified, then the observation task will not be run (correlator and tuning modifications may, however, still happen). Multiple sources may be specified for many of the observing tasks. These sources should be separated by commas.

catalog

The catalog for source. If this is not defined, then it defaults to $HATCAT/j2000.cat. Multiple catalogs may be specified whenever multiple sources may be provided. These catalogs should be separated by commas.

ants

Antennas to be used in observing. A value of "*" means to use all available antennas; "xyz" means to use just antennas 'x', 'y', and 'z'; and "*-xyz" means to use every available antenna except 'x', 'y', and 'z'. If this is not present, it defaults to "*". This keyword should generally be omitted.

task

This specifies which observing task will be executed. If this is not present, it defaults to mint. The acceptable choices for this keyword are mint, int, and qint. Any other choice results in an error message and no observing task is called.

corrtask

This specifies which correlator setting task will be executed. If this is not present, it defaults to setcorr. Currently, the only acceptable choice for this keyword is setcorr.

tunetask

This specifies which tuning task will be executed. If this is not present, it defaults to setfreq. Currently, the only acceptable choice for this keyword is setfreq.

checktask

This specifies which tuning task will be executed. If this is not present, it defaults to cksrc. Currently, the only acceptable choice for this keyword is cksrc.

elevlim

The lower and upper source elevation limit in degrees. This range is used to limit the valid source elevations over which a setup may be observed. If not defined, this defaults to 10 and 85 degrees. Note: the value of this keyword corresponds to the source elevation, not the antenna elevation.

lstrange

The time ranges over which a setup is considered observable. If the current LST is not within the window specified by this keyword, then the source is not considered visible and observing of this setup will not continue. Up to 4 time ranges can be entered as:
lstrange=lstmin1,lstmax1,lstmin2,lstmax2,lstmin3,lstmax3,lstmin4,lstmax4
The format for each of these values is in the hhmm time format . Only the time ranges specified will be tested. If the minimum value is later (greater) than the the maximum value, then the time range is considered to wrap around the 24 hour mark. The default time value for the minimum time range is one hour before the current LST and the default for the maximum time range is two hours after the corresponding minimum time range. If this keyword is not present, then no time range testing will be done.

cormode

This describes the correlator configuration and the number of correlator spectral windows. Each mode also determines how the correlator frequency (corf) will be arranged. This keyword defaults to 8 (i.e. 8 windows).

corf

The correlator LO settings (4 numbers in the range: 90 -- 900 MHz). The default is corf=200,400,600,800. Setting keywords cormode=8 and corbw=100 gives the maximum contiguous bandwidth from 100 to 900 MHz.

Missing values should be inserted but the values assigned do not matter. For example, with cormode=3 one might assign corf=200,400,100,600. The 100 value is a bogus value but is necessary so that the value of 600 MHz gets assigned properly.

corbw

The correlator filter widths. Up to 4 numbers, depending on the value of cormode, may be specified. Only the values 6.25, 12.5, 25, 50, and 100 MHz are considered valid. The default is corbw=100.0,100.0,100.0,100.0. The first and the third widths use the same shift rate (likewise for the second and the forth widths). Widths of 25, 50, and 100 may be paired, but the first and third (and second and forth) inputs should be the same for the smaller bandwidths. Missing values should be inserted. For example, if cormode=6, the user might specify corbw=25,100,25. The 100 MHz value is ignored but is necessary so the second 25 MHz value gets properly read. Note that the fourth value may be omitted if not used.

corspec

Select which correlator spectral windows are written into uv-data. corspec has nspect values: 1 or 0, to write, or omit each spectral window respectively. For example, for cormode=5 cross-correlation, corspec=1,0,0,0,0,1,0,0,1,1 writes lsb window 1 and usb windows 1, 4, and 5. The default is to write all spectral windows. The wideband average of each window is always written (excluding flagged channels). The wideband currently written is the average lsb, average usb, followed by nspect=2*cormode averages for each spectral window.

corbits

The number of bits used to digitize the signal. This value may only take on values of 1 or 2 and defaults to 2 if this keyword is not present.

maxcorr

Two values used to specify the maximum correlation coefficient. The spectral window is flagged if the measured correlation is greater than these values. The first value applies to the whole correlation function. The second value applies outside the central 10 correlation function. If this keyword is not used, then it defaults to maxcorr=1,1. The second value defaults to the first if it is not present. The appropriate values depend on the source flux density and system noise. For a source flux density, S Jy, the expected correlation is

S / (Jy/K x Tsys) = 2.0E-5 x S,

for an antenna gain of 140 Jy/K and Tsys = 300 K. For Gaussian noise the rms correlation is

dT / Tsys = 1 / sqrt(2 x bw x inttime) = 1.0E-5

for bw=100 MHz and inttime=50 sec.

Set maxcorr greater than the expected correlation by at least 5-6 times the rms to avoid flagging random noise. For a continuum source, the correlation function falls rapidly, so a smaller value for maxcorr can be set outside the central 10%. For spectral line emission use the default that the second value equals the first. For example, for a 10 Jy quasar maxcorr=2.0E-3 will flag data which is ten times the expected correlation, or 20 times the expected noise.

coptions

Several processing options that may be given (separated by commas) to enhance how the correlator is set up. Possible options include:

auto

Set the correlator up in auto-correlation mode. The default is cross-correlation mode.

hanning

Hanning smoothing reduces the resolution and suppresses the ringing due to sharp edges. By default, there is no Hanning smoothing applied.

nocal

No antenna temperature calibration. The default is to perform antenna temperature calibration.

nopass

No on-line passband calibration. The default is to include passband calibration.

nocable

No cable length calibration. The default is to include cable length calibration.

restfqs

Specifies 1 to 16 rest frequencies used to calculate the velocities for each spectral window (in GHz). The spectral windows are defined by the correlator characteristics (described by the correlator keywords above). There should be nspect values in GHz, corresponding to the order defined by cormode, not just the ones selected for writing by corspec. The rest frequency is set equal to the value of freq in any windows for which restfqs = 0 or the input value lies outside the acceptable range (50 -- 300 GHz for mm observing).

Rest frequencies are meant to be a convenience for data reduction when observing more than one molecule in different windows, and do not affect the observations. For convenience, one can set restfqs so that each window has a header parameter written with a rest frequency for that window. The default is to set restfqs equal to freq, which is just what is wanted if only one molecular line is being observed.

If there is more than one line in a window, or the correct rest frequencies were not specified using the restfqs keyword, then the Miriad task puthd will permit the user (during post-processing) to override ALL of the rest frequencies.

As an example, suppose the correlator setup was chosen to observe HCN in windows 5 and 6 (88.63 GHz rest frequency) and HCO+ in windows 7 and 8 (89.1 GHz rest frequency). Also suppose that the source has a VLSR of 1000 km/s. Now, if the setup used freq=88.63, then the velocity scale of the whole correlator would be set up so that the doppler shifted 88.63 GHz would correspond to a velocity of 1000 km/s. This means that the HCO+ line, which is at a frequency 500 MHz higher than the HCN line, would correspond to a velocity higher by about (500 MHz / 89 GHz)*c or a velocity of 1685 km/s. Note: the correlator is observing HCO+ at the 1000 km/s redshift; but because the rest frequency has been set to HCN, the reduction software assumes that 89.1 GHz corresponds to HCN at 1685 km/s, rather than HCO+ at 1000 km/s.

passfile

Cache file for passband (created in the project directory). If this is named and contains data, it will be used for the passband. Use different names for different correlator setups. If it is missing, passbands will be measured for each source. Note: common variable PRESET = Y overrides this variable.

conffile

Cache file for correlator setups (created in the project directory). If this is named and contains data, it will be used for the basic correlator settings. Use different names for the different correlator setups. If it is missing, new correlator settings will be loaded from common and detector tweaking will occur. Note: common variable CRESET = Y overrides this variable.

tsysfile

Cache file for TSYS/Gains (created in the project directory). If this is named and contains data, it will be used for the Calibration values. Use different names for the different correlator setups. If it is missing, The TSYS measurement will be remeasured. Note: common variable TRESET = Y overrides this variable.

freq

The observing frequency (in GHz). The nominal range for this value is between 82 and 116 GHz (but might be different depending on the doppler velocity of the source). Normally this will be the rest frequency of a spectral line. If the freq and iffreq keywords are not both present in the setup, then no frequency adjustment or tuning will take place.

iffreq

The second IF frequency (in MHz). The nominal range is +/-(90 -- 900) MHz. If iffreq is negative, then the spectral line will appear in the lower sideband of the first local oscillator (LO1). This sets nominal frequency at which the spectral line appears at the correlator input (the actual frequency differs slightly because the source's doppler shift is not fully removed by correcting LO1. A value of zero for this keyword sets LO1 = freq x (1 - Vsource/c). If the freq and iffreq keywords are not both present in the setup, then no frequency adjustment or tuning will take place.

dopsrc

The name of the source used for the doppler correction. If this keyword is not present, then, when tuning is done, the doppler correction applied will be with respect to a VLSR of 0.

dopcat

The catalog for dopsrc. If this is not defined, then it defaults to $HATCAT/j2000.cat.

harm

An optional override for the harmonic number. By definition, harm = (LO1 - 0.07) / Xfreq, where Xfreq must lie between 8.0 and 12.5 GHz. The default (0) is to use the lowest odd harmonic. Note: This is useful only if the mm-oscillator on an antenna fails to lock to the default harmonic.

obsline

A descriptive name of the observed line (there is a maximum of 24 characters for this value).

options

Several processing options that may be given (separated by commas) to describe what should be done after the frequency is set. Possible options include:

nohcheck

does not perform a harmonic check. By default, a harmonic check is performed after tuning (i.e. confirms that the mm-oscillator is correctly phase locked to frequency LO1).

allants

tune rcvr even if antenna is "off".

lockonly

phaselock the mm osc, then exit.

musttune

performs all receiver tuning steps whether needed or not.

If none of these tuning options are present, then the default action is to only perform tuning as necessary.

start

The starting time to begin this particular observation of this source. It is typical to omit this keyword. If it is not present, the default implies to begin observing "now". This keyword differs from the lstrange keyword in that this time represents the earliest an observation can begin on this source and if the current LST has not yet past this time, the scan command will wait until it is reached. The value for this keyword is specified in the hhmm time format .

stop

Specifies the length of a single task observation. Typical values are generally on the order of a few minutes or up to 30 minutes or so. If this keyword is not present, it defaults to one hour after the start of the observation. The value for this keyword is specified in the hhmm time format .

vis

The name of the output Miriad visibility dataset. If this keyword is not present, then no observing will be done for this source.

itime

The integration time per grid field in seconds. The default value is 50 seconds.

grid

The grid selector. This applies to all observing tasks except the int task. This can be a file name from the directory $UGRID, a file name from the directory $HATGRID, or it can be a direct field descriptor of the form:
grid="DRA(min,...),DDEC(min,...),NS(1,2,...),DATE(yyMONdd:hh:mm:ss.s)"
where DRA and DDEC are right ascension and declination offsets measured in arcminutes on the sky. They are added onto the position of the source specified for the grid point. The index in the NS array identifies which entry in the source and catalog array will be observed. Use 1 to identify the first source in the list, 2 the second, and so on. If the number used is negative, then doppler tracking is turned off for that source; otherwise doppler tracking is turned on. Each grid point is observed after each nreps integrations and then back to the first point after all have been observed and continues until the stop time is reached. The DATE descriptor is used for solar offsets only and gives the epoch of the DRA and DDEC offsets. If a file name is given, it will point to a file containing a descriptor similar to the one above. Newlines are permitted in the grid file. The (0,0) offset must be included in the grid if observing of the source is wanted. By default (if this keyword is omitted), only the main source position is observed (i.e. there is no grid).

Note: Newlines are allowed in the grid file, but a comma must be included at the end of each line.

scale

A scale factor which is multiplied into each of the offsets defined by the grid keyword. This is most commonly used with the generic grid files found in $HATGRID. The default value is 1 which means the values in the DRA and DDEC arrays are actual arcminute offsets. This keyword applies to all observing tasks except the int task.

polar

Polarization patterns; 1-20 strings separated by commas consisting of one of the following characters for each antenna: R(right circular polarization); L(left circular polarization); or Y (or -) standard polarization. The pattern is changed each polrep integrations and the sequence is then repeated. If any characters other than RLYrly- are present, the field is treated as the name of a file (which is in either the current directory, $UGRID, or $HATGRID) and contains the Polarization patterns. The default is: YYYYYYYYYY.

polrep

The number of times to cycle through the polarization pattern. For example, to cycle through 7 pointing positions for each polarization pattern, set polrep=7. The default is 1.

nreps

Up to two numeric arguments may be provided for this keyword. The first argument specifies the number of integrations performed at each grid position defined by the grid keyword. The second specifies the number of times to go through the grand grid/polarization loop. {\sc Warning: this can supersede the stop time if the grand cycle takes less time!} For example, to cycle through 16 polarization patterns at each grid point, and stop after 2 complete loops of pointing and polarization, set nreps=16,2. The default is 1 for the first value and 0 (ignored) for the second. This keyword applies to all observing tasks except the int task.

nchan

A flag to identify the number of channels. If nchan is 0, it means only wideband data should be generated; +1 means both spectral and wideband are written; and -1 means both spectral and wideband data are gathered but are not doppler tracked. The actual number of channels is determined by the correlator keywords. If not present, this keyword defaults to +1.

trakopt

Tracking option specifier. This defaults to CH for the int task and CH+ for the other tasks.

cabint

Interval of time (in seconds) between cable phase (or line-length) measurements. The measurement will take place at the first opportunity (break between integrations) cabint seconds after the previous measurement. The default value is 100 seconds for the mint task; 90 seconds for the qint task; and does not apply to the int task.

dbon (qint)

A flag that permits observation of sources with 10 dB in the second IF turned on (this is mandatory for the Sun). Use a value of 1 to turn on the attenuation; use 0 to turn it off. The default is off; but defaults to on for the sources SUN and TEST.