## B.6. cacor Commands

Observers can interact with cacor through the text input box located at the bottom of the GUI, between the “Command:” label, and the “QUIT” button. We call this the “Command” entry box. The full list of commands that can be issued through this interface is below.

abphase n m

Set the desired phase offset (in degrees) to insert between the A and B polarisations of each antenna, where n is the desired offset in IF1, and m is the desired offset in IF2. The phase offset will not be inserted however until a “pcal” command is issued.

The most useful purpose for this command is to switch between linear polarisation (for which n and m are both 0) and circular polarisation, which requires a phase shift of ±90° between the linear feeds, depending on the sideband. This is most commonly used for VLBI experiments, which record circular polarisation.

Example: The command “abph -90 -90” will produce circular polarisation output from the tied array units, for USB frequencies.

Related commands: pcal, catie pol

acal n m [a-z]

Tells the correlator that the average flux density of the source currently being observed is n Jy over the tvchannels set in IF1, and m Jy over the tvchannels set in IF2. The correlator uses this information when calculating the system temperature that it writes into the RPFITS files.

If the command is given with or without a trailing “a” option, then the correlator will apply the calibration. If the trailing option is specified as any letter other than “a”, the correlator will display the corrections it would make, but will not apply them.

Related commands: dcal, pcal, tvchannels, reset acal, calband

attf ca0# n m

Set the amount of CABB attenuation on IF1 (“att1”) or IF2 (“att2”), for antenna CA0#, to be n dB for polarisation A and m dB for polarisation B.

The current CABB attenuator settings are shown in the “Sampler Levels” tab in the data panel.

There is an attenuator servoing command that will adjust the CABB attenuation automatically to equalise signal levels across antennas and polarisations. This command is “attservo”.

Related commands: attservo, tattservo

attservo [on|off]

Attenuator servoing will make the correlator attempt to bring the sampler/GTP statistics into line with the target that was set with the “tatts” command. It does this by adding or removing CABB attenuation on a per-antenna, per-polarisation, per-IF basis. It may take a relatively large number of cycles (more than 5) to accomplish this, and may not be able to precisely meet the target specified.

Without arguments, this command returns the current state of the attenuator servoing mechanism (which can also be found in the status panel). To start/stop the servoing mechanism, issue this command with the “on/off” argument respectively. It is important to check the resultant attenuation levels (shown on the "Sampler Levels" tab in the data panel) for potential problems during this process.

Related commands: tattservo, userms, usegtp

calband [n m]

This command changes the IFs that the correlator uses to determine the delays, phases and amplitudes. The setting that you can make here depends on the cacor version, and the correlator configuration.

While observing with a configuration that provides the 2 GHz continuum IFs with 1 MHz resolution (eg. “ca_2048_2048_2f”), these quantities should be calculated from the continuum IFs at all times. To ensure this, n and m should both be set to “f” if the cacor version is not one designated for VLBI use, or “0” otherwise.

If the frequency resolution of the 2 GHz continuum IFs is worse than 1 MHz (eg. “cfb_64_32_2f_zm16”), or if the correlator configuration does not provide the 2 GHz continuum IFs (eg. “cfb64_vlbi”), then it may be necessary to use the zoom bands to compute and/or correct the delays and phases. In this case, both n and m should be set to “z” in non-VLBI cacor versions, or n=3 (the first zoom IF) and m=4 (the second zoom IF) otherwise.

All the commands that affect the computation of delay, phase and amplitude (eg. tvchannels, dcal, pcal, acal, delavg) will apply to the IF that is specified by this command.

Note: When in a non-VLBI cacor version, the “z” setting for n or m can only be used if the first specified zoom in that IF has a width of 1 (i.e. the zoom band is not a composite zoom). If this is not the case, the correlator will return an error message.

Related commands: acal, dcal, pcal, tvchannels, abphase, delavg

calfreq [f]

Specify which IF (1 or 2) to use when manually correcting the delay with the “doffset” command. Without arguments, this command will return the currently selected IF.

Related commands: calpol, doffset

calpol [p]

Specify the polarisation (a or b) to use when manually correcting the delay with the “doffset” command. Without arguments, this command will return the currently selected polarisation.

Related commands: calfreq, doffset

calrefant [#]

Set the reference antenna for calibration purposes to be CA0#. As with “refant”, this is usually best set to antenna 2, if it is included in the array. If this command is issued without arguments, it returns the current setting of this variable.

Related commands: refant, dcal, pcal

[ca]tie [command [##]]

The correlator can be take the signals from each of the ATCA antennas and combine them in real time to form a single output phased up towards a nominated phase centre: this is called the “tied array”, and is usually configured for VLBI observations. The “catie” commands configure this tied array.

The tied array commands can be prefixed with “catie”, or, in a slight reversal of the usual minimum-match pattern recognition, it can be shortened to “tie”. When issued without an argument, cacor will return the current configuration of the tied array.

The tied array commands and their optional arguments are described below. Each of the tied array commands take two optional arguments, which control each of the two IFs. It is not possible however to control one IF with these commands without simultaneously having to set the state of the other IF.

[ca]tie array [## ##]

Tie the signals from antenna(s) ## into the tied array output, per IF.

Example: The command “tie array 123 245” ties the signals from CA01, CA02 and CA03 into the IF1 tied array output, and from CA02, CA04 and CA05 into the IF2 tied array output.

[ca]tie pol [t t]

Configures the tied array to either output directly the two linear polarisations (t=l), or to combine the two linear polarisations together to output circular polarisations (t=c).

Example: The command “tie pol l c” would leave the linear pols as is for the tied array output of IF1, and form circular polarisations for the tied array output of IF2.

Note: The “circular” polarisation setting here does not automatically form circular polarisations; it simply combines the two linear polarisations together with the current cross-polarisation phases. This command must be used together with the “abphase” command to properly form circular polarisations.

Related commands: abphase

[ca]tie gain [n n|auto]

Sets the gain for the tied array output for each IF to be n, where 0 < n ≤ 1. This gain setting, combined with the GTP sampler statistics, is able to vary the amount of power fed into the DAS units.

If all antennas are tied, and the GTP statistics are around 30, then a gain of 0.1 is recommended.

Example: The command “tie gain 0.1 0.09” will set the tied array gains to 0.1 and 0.09 on IF1 and IF2 respectively.

The gain can be set to change automatically by supplying the auto argument instead of the IF gains. Automatic gain control can only be set to work for both IFs simultaneously; it cannot work for a single IF only.

Related commands: tattservo, attservo

[ca]tie reset

Resets the output from the tied array output module in the correlator. The configuration of the tied array outputs will not change.

cf [n m]

The CABB system's primary frequency band corresponds exactly to the 4cm band, where 3904 MHz ≤ ν ≤ 11952 MHz; all other frequency bands are mixed into this range using front-end LOs. To select the two 2048 MHz intermediate frequency ranges (the CABB IFs), we use the CL1 LO modules, which can be tuned between 4928 MHz ≤ ν ≤ 10928 MHz.

This command either lists (if no arguments are supplied), or sets the CL1 frequency to n MHz for IF1, and m MHz for IF2.

You must set the CL1 frequency for both IFs when you issue this command. If one or both of the frequencies are out of the accepted range, the command will not work. cacor will output the new LO frequencies after this command is given.

Note: The IF frequencies are set by caobs, not cacor, so changes to the centre frequencies using this command will not be reflected in the output data file.

[no]czabs

This command enables (with “czabs”) or disables (with “noczabs”) the correlator's auto-correction and online application of the zoom bandpasses. Since the zoom bands are digitally constructed, their bandpass shapes can be accurately determined during the observation, and corrected before being written out to the data file.

Use this command to disable this behaviour, as it is enabled by default.

dcal [a-z]

Tells the correlator to estimate the delay in each of the IFs set with the “calband” command, using the data in the “tvchannels” range, boxcar averaged over “delavg” channels, for the previous “nncal” cycles, with respect to the reference antenna set by the “calrefant” command.

If the command is given with or without a trailing “a” option, then the correlator will apply a correction to compensate for the calculated delays. If the trailing option is specified as any letter other than “a”, the correlator will display the calculated delays, but will not apply them.

Related commands: acal, pcal, tvchannels, delavg, calband, nncal, reset delays, calrefant

delavg [n]

To calculate the delay in any particular IF, cacor looks at the phase in each channel in the “tvchannels” range and fits a line to the phase as a function of frequency; the slope of this line is the delay.

If the noise on the phase is high (due to a faint source or poor weather, for example), or there is some strong unavoidable RFI in the “tvchannels” range, then the least-squares line of best fit may not accurately represent the real slope due to the delay.

To reduce the noise, or to average out the effect of the RFI, you can use this command. This command tells cacor to first average together each n channels in the “tvchannels” range before calculating the slope.

Example: Suppose the “tvchannels” are set to include channels 513 to 1537 (a total of 1025 channels). With a “delavg” of 1, the delay fit would use 1025 points. If you set “delavg” to 4, then the delay fit would use only 256 points, and each point would have a signal-to-noise ratio 2 times better than with “delavg”=1.

This command is especially useful at higher frequencies, and is almost necessary in the 3mm band, due to the lower sensitivity of that receiver. It is also very useful when doing the delay calibration using a single 64 MHz zoom, since the bandwidth of each channel is greatly reduced.

Related commands: tvchannels, dcal, calband

[no]delscan ff offset,incr

If it isn't possible for some reason to have cacor automatically compute delay corrections, it is possible to use this command in order to manually determine the delay between each antenna and the reference.

This command makes cacor cycle through a range of delay offsets for IFf, starting at -offset ns (compared to the current setting per antenna), and adding incr ns of delay to each antenna at each subsequent cycle.

By looking at the amplitudes at each cycle, it is then possible to determine which offset is closest to the systemic delay for each antenna. These offsets can be added into the correlator with the “doffset” command.

This command will continue to operate until the “nodelscan” command is issued.

Example: The command “delscan f1 -40 4” will make cacor subtract 40ns of delay from each antenna (except the reference antenna as set by “calrefant”), and then add 4ns of delay every subsequent cycle.

Note: This command is not usually necessary during normal setup procedures. There is almost always a way to use “dcal” to perform delay corrections.

Related commands: doffset, dcal, calrefant

diginit {all|ca0# [fp]}

Resynchronises the specified digitisers; the more information you supply to this command, the more specific the specification. To select one specific digitiser you must supply the antenna number #, the IF f (either 1 or 2) and the polarisation p (either a or b). If you don't specify the polarisation, then both digitisers for that antenna and IF will be resynchronised. If you don't specify the IF, all four digitisers on the antenna will be resynchronised.

If you want to select all digitisers on all the antennas, use the argument “all”.

The state of the antenna in caobs (eg. off-line, disabled) does not affect this command; the digitisers in an antenna can be resynchronised at any time.

Note: Resynchronising a digitiser will almost always change the delay to that antenna and polarisation in that IF. It is not recommended to use this command unless you know what you are doing. This command is most appropriately used if the input shown in the "Data Links" tab is coloured red, and an “rtminit” of that input has failed to restore it. That is, it is generally advisable to attempt an “rtminit” before attempting a “diginit”.

Related commands: rtminit

doffset [ca0#=d]

Allows for manual correction of delay offsets. Without arguments, this command will print all the current delay offset numbers for the current IF (selected by “calfreq”) and polarisation (selected by “calpol”). This command allows you to directly set these delay offsets with respect to the reference antenna; the reference antenna will always have a delay offset of 0. A positive offset then means that the correlator will receive a particular wavefront from that antenna before the reference antenna, and a negative offset means that the correlator will receive the same wavefront from that antenna after the reference antenna.

Example: Giving cacor the following commands:

calfreq 1
calpol b
doffset ca01=-432


tells the correlator to expect the signal from CA01, IF1, B polarisation 432 ns after that of the reference antenna.

Note: The delay is not merely a function of geometric delay, but will also include the travel time along the cables from the antenna to the correlator, etc. It is therefore not easily apriori calculable by non-experts.

Note: This command is most useful for rough correction of delay if the phase is wrapping too quickly for the correlator to determine the appropriate delay correction automatically with the “dcal” command. It is not usually necessary for this command to be used. Instead, you may find success by using the “rtminit” and “diginit” commands to bring the delays into a range that cacor can correct automatically.

Related commands: calfreq, calpol, dcal, delscan, diginit, rtminit

f[un]flag [ff [{n|n-m|default|birdies}]]

Flag (“fflag”) or unflag (“funflag”) channel n, or channel range n-m (inclusive) from IFf.

By flagging a channel, it no longer contributes to the phase, delay or amplitude calculated by the correlator, even if it lies within the “tvchannels” range. A flagged channel also is written out to the RPFITS file as having precisely 0 real and imaginary components, and has its flagged bit set.

Example: The command “fflag f1 1187 2001” would flag out channels 1187 and 2001 from IF1.

Example: The command “funflag f2 1800-1840 would unflag all channels between 1800 and 1840 inclusive.

There are two arguments – “default” and “birdies” – that flag specific channels that are known to often or always be bad. For “default” these channels are 513, 1025 and 1537. For “birdies” these channels are 129, 157, 257, 641, 769, 1153, 1177, 1281, 1409, 1793 and 1921. The “default” argument is normally not required to be issued, but can be useful when you want to reset the flagging. The “birdies” argument is always recommended in any 2 GHz continuum band with 1 MHz frequency resolution.

Without arguments, this command returns the current number of unflagged channels in both IFs, which should never be more than 2047 (2049 channels total - 3 always flagged default channels).

Related commands: tvchannels

nncal [n]

When commanded to calculate the delays, phases or amplitude calibration offsets with one of the “dcal”, “pcal” or “acal” commands, cacor uses the average over the most recent n cycles for computation. By default, n=3, but you can use this command to change this number.

When self-calibration of the phases is required, it is more accurate to only consider the latest cycle, so n should usually be set to 1 in this case.

Note: This command is rarely useful, and increasing “delavg” is probably a better option if more signal-to-noise is required for calibration.

Related commands: selfcal, delavg

pcal [a-z]

Tells the correlator to estimate the phase in each of the IFs set with the “calband” command, using the data in the “tvchannels” range, for the previous “nncal” cycles, with respect to the reference antenna set by the “calrefant” command.

If the command is given with or without a trailing “a” option, then the correlator will apply a correction to compensate for the calculated phases. If the trailing option is specified as any letter other than “a”, the correlator will display the calculated phases, but will not apply them.

Note: cacor will always attempt to make phase corrections such that a single wavefront from a point source will arrive at 0 phase on each antenna. For the phase between the A and B polarisations on a single antenna however, this command will use the current setting of “abphase” when choosing the corrections.

Related commands: acal, dcal, tvchannels, calband, nncal, abphase, calrefant

phoffset [ca0#=p]

Allows for manual correction of phase offsets. Without arguments, this command will print all the current phase offset numbers for the current IF (selected by “calfreq”) and polarisation (selected by “calpol”). This command allows you to directly set these phase offsets with respect to the reference antenna; the reference antenna will always have a phase offset of 0.

Example: Giving cacor the following commands:

calfreq 1
calpol b
phoffset ca01=18


tells the correlator to make the phase offset on antenna 1, IF1, B polarisation, 18 degrees.

Note: This command is most useful for rough correction of phase. It is not usually necessary for this command to be used as automatic correction with the “pcal” command should almost always work.

Related commands: calfreq, calpol, pcal

refant [#]

Make antenna CA0# the reference antenna. This command also simultaneously sets the calibration reference antenna in the same way as “calrefant”.

If the argument is not given, the current reference antenna is displayed.

Note: The reference antenna in this context is actually only useful when forming the tied array output, as the tied array signal will appear to be coming from the location of this reference antenna. If you want to set the antenna to use as the calibration reference antenna, use the “calrefant” command separately.

Related commands: calrefant

reset [command]

Sometimes the correlator can get into a state that is not easy to recover from. The “reset” commands can be used to put the correlator back to a default state, from which you should be able to redo the calibration successfully.

Each of the available reset commands are described below. None of the commands take arguments.

reset

DO NOT ISSUE THIS COMMAND WITHOUT ARGUMENTS. THIS WILL CAUSE THE CORRELATOR GUI TO FAIL (REQUIRING A RESTART) AND THE UNIVERSE TO MORPH INTO A CATERPILLAR.

reset abdelay

Reset only the cross-polarisation delays.

Related commands: reset delays, dcal

reset acal

Reset the gain to amplitude scaling factors (essentially the strength of the noise diode on each antenna) that are set after doing an “acal”.

Related commands: acal

reset delays

Reset the correlator delay offsets back to their geometric default. This command can be useful if a “dcal” has apparently made the delay worse, to the point that it has become very difficult or impossible for the correlator to calculate the remaining delay.

Related commands: reset abdelay, dcal

reset mem

This command resets the memory chips on the correlator blocks. When observing with the correlator configured to use the pulsar binning mode, this command can be used to fix a problem that manifests itself as large numbers of bad channels in alternate cycles.

Note: This command can only be used while the correlator is stopped, and may need to be used several times before the problem goes away.

rtminit {all|ca0# [fp]}

Resynchronises the “rear transition module” (RTM); the more information you supply to this command, the more specific the specification. To select one specific RTM you must supply the antenna number #, the IF f (either 1 or 2) and the polarisation p (either a or b). If you don't specify the polarisation, then both RTMs for that antenna and IF will be resynchronised. If you don't specify the IF, all four RTMs for the antenna will be resynchronised.

If you want to select all RTMs on all the antennas, use the argument “all”.

The state of the antenna in caobs (eg. off-line, disabled) does not affect this command; the RTMs for an antenna can be resynchronised at any time.

Note: Resynchronising an RTM will almost always change the delay to that antenna and polarisation in that IF. It is not recommended to use this command unless you know what you are doing. This command is most appropriately used if the input shown in the "Data Links" tab is coloured red, but if the “rtminit” for that input fails to restore it you may need to consider doing a “diginit” before reattempting an “rtminit” again.

This command is also useful if the “1ms” values for some of the input(s) shown in the “Data Links” tabs are very much different from the expected values.

Related commands: rtmreset, diginit

rtmreset

Reset the sync error counts in the “Data Links” tabs in the data panel. This can be useful if the error counts are high, but it is not clear whether they are continuing to increase. This command will immediately (ie. on the next cycle) reset the counts to 0, so if any counts remain non-zero after this command, errors are still present.

Related commands: rtminit, diginit

selfcal [{f g|{on|off}}]

The correlator is able to continuously adjust the phases on a cycle-by-cycle basis in order to keep them as close to zero as possible. This is only possible while observing a bright calibrator or spacecraft, and is only really useful for VLBI and NASA spacecraft tracking.

By default, the correlator will determine the average phase over the most recent “nncal” cycles in each IF, and then apply an opposite phase offset to that same IF. It is possible though to use the phase measured in one IF to correct the phase in another IF. This command requires two arguments in that case, one for each IF, and each being the IF used to correct the phase. That is, f is the IF to use to correct IF1, and g is the IF to use to correct IF2.

Example: The command “selfcal 1 1” will use the phase observed in IF1 to correct both IF1 and 2.

Once the command is configured, you can enable or disable self calibration by supplying either “on” or “off” as the argument to this command respectively.

Issuing the command without arguments will return the current self-calibration state.

Related commands: nncal, tvchannels, calband

tatts [t]

Sets the target sampler RMS/GTP levels to be t for IF1 and IF2. After these targets have been altered, the command “attservo” should be given to have cacor change the CABB attenuation in order to reach this target.

Using “tatts” without arguments will return the current target. The default sampler level target is 20.0 for each IF.

Related commands: attservo, calband, userms, usegtp

tvchannels [ff] {n m [o p]|default}

The data in the “tvchannels” range are used by cacor to calculate the average amplitudes and phases on each baseline, and to measure the delay. These quantities are displayed on vis, are checked by assistance, and are used by catag for pointing corrections. The data is also used to calculate the sampler GTP values, and of course any corrections made by the commands “dcal”, “pcal” or “acal” are calculated using this data.

You can change the “tvchannels” for a single IF by specifying the IF number f and then the start and end channels (inclusive) n and m respectively. Or you can set the “tvchannels” for both IFs at the same time by specifying the start and end channels n and m respectively for IF1, and o and p respectively for IF2.

Example: The command “tvchannels f1 500 1600” will set the IF1 “tvchannels” to cover the range 500-1600 inclusive.

Example: The command “tvchannels 500 1600 900 1400” will set the IF1 “tvchannels” to cover the range 500-1600 inclusive, and the IF2 “tvchannels” to cover the range 900-1400 inclusive.

The default “tvchannels” usually cover the entire central half of the band (ie. channels 513-1537 in the 1 MHz continuum bands or 64 MHz zoom bands, or 9-25 in the 64 MHz continuum bands). To reset the “tvchannels” to this, substitute the channel specification with “default”.

To determine what the “tvchannels” are currently set to, either look at the status panel, or issue this command without arguments.

Related commands: calband, delavg

usegtp

This command makes cacor display the gated total power (GTP) in the “tvchannels” range for each input (antenna, IF, polarisation) in the “Sampler Levels” tab in the data panel.

Related commands: userms, tatts, attservo

userms

This command makes cacor display the voltage RMS value from the digitisers on each input (antenna, IF, polarisation) in the “Sampler Levels” tab in the data panel.

Related commands: usegtp, tatts, attservo

where {filterbank|channel|zoom} {f|z}f c

When the correlator develops a problem in a zoom or continuum channel, you may need to identify which correlator block is responsible for computing the bad channel so it can be reprogrammed and fixed. This command lets you specify the bad channel location and it will return the block responsible.

Example: To find the block responsible for channel 430 in the continuum band IF1, you would use the command: “where channel f1 430”. It will return something like: “WHERE CHANNEL F1 430 - processed in block 8 (block on-line)”. This tells you that CABB block 8 is responsible for the channel, and that the block is still on-line and active.

Example: To find the block responsible for channel 912 in the zoom band z11, you would use the command: “where zoom z11 912”. It will return something like: “WHERE ZOOM Z11 912 - processed in block 15 (block on-line)”. This tells you that CABB block 11 is responsible for the channel, and that the block is still on-line and active.