Command file observing allows You to prepare a list of instructions in advance, which can then be executed automatically when You are observing. It is in principle possible to carry out a complete observing session from a command file. You should, however, have some experience of using CIMA before attempting command file observing.
Not all the observing modes in CIMA have been implemented for command file observing. However, the implementation is generally a fairly straight-forward process, so if You find that You want to use an observing mode that is not available on this page, don't hesitate to contact the CIMA administrator (see email address at bottom of this page) to ask if it can be added.
Command files should be given the suffix '.cmd' in order
for CIMA to recognise them as command files when browsing for command
files.
There has been some important syntactical changes. Continuation lines are no longer indicated by leading white space. Instead, a continuation is indicated by appending a '&'-sign at the end of a line that is going to be continued. This change allows the use of white space in the beginning of lines for indentation. The reason for this change is that CIMA now accepts long IF-statements containing multiple commands as well as nestled IF-statements.
There are new functions that can be used in IF-statements to check if a source is up, when it
is up and how long it will take to slew to it. The new functions are:
ISUP(source),
RISE(source),
SET(source),
SLEW(source) and
LSTSLEW(source).
The following commands have been modified, added or removed:
The following observing commands have new or modified options:
The first thing to do is to use the 'Load' button to select and load a
command file into CIMA. Command files should use the suffix
'.cmd' so that the file browser can identify them as
command files. If You don't use this suffix, You will have to tell the
browser to show You all files which will slow down the browser.
Once loaded, the command file will be listed in the window with line numbers added in front of each line. The listing is color-coded with valid command lines shown in blue and black, comments in green and invalid lines in olive. The line numbers refer to the physical lines in the command file, continuation lines will thus have line numbers as well, although they will be shown in yellow to indicate that they are continuation lines.
The start line is shown with yellow background. You can select another start line by typing a line number in the 'Start from line' entry or, more simply, by left-clicking on the line in the listing.
Another option available is to specify whether the command file should be run once, several times or indefinitely until stopped by the user.
It is not necessary to edit the command file if You want to exclude some lines in it. You can deactivate lines by middle-clicking on them in the listing. Deactivated lines will appear grayed out and will be ignored during execution of the command file. Middle-clicking a second time on a deactivated line reactivates it.
You can use the 'Reload' button to reload Your command file, if You have made changes to it. The file will be reloaded without the need to select it in the file selection window that pops up when using the 'Load' button.
Three other command buttons are enabled while the command file is executing: 'Skip', 'Abort' and 'Stop'. The 'Abort' button will aborting the execution immediately and return control to the observer. The 'Stop' button will stop the execution more gracefully by allowing the current command or observing loop to finish before stopping the execution. These buttons have the same funtion as the 'Abort' and 'Stop' buttons on the CIMA observation log display. The 'Skip' button, however, is different. The 'Skip' button works like the 'Abort' button in the sense that the current line is aborted immediately. However, after aborting the current line, CIMA will continue with the next line in the command file, thus skipping the line that was executed when You pressed the 'Skip' button.
When the command file stops executing there will be a big "bong" (only for on-site observers) and control will be returned to the observer. If the command file terminated normally, the original start line will be restored. However, if the execution was terminated by an 'Abort' or 'Stop' command or by an error, the command line where the termination came will be indicated by a red background and the following line will be selected as the new start line. Lines that are skipped with the 'Skip' command will also be indicated with a red background.
#' is also ignored,
and '#' can thus be used to
provide comments or to comment out lines of code. Spaces can be used
to indent lines for improved readability. A line starting with spaces
followed by a '#' is
considered a comment and will be ignored.
ON loops=1 secs=120 caltype=hcorcal calsecs=10 & dop=each adjpwr=first newfile=0
Some commands take one or more direct
options. For those commands the option value is given directly.
For example, the CATALOG command expects one direct option specifying the name of the catalog
file to use:
CATALOG monkeys.catHowever, many commands instead use specified options. Specified options removes the requirement that options are given in a certain order. They are also remembered so they do not need to be repeated unless they are changed. A specified option has the following general syntax (white space is allowed):
name = valuewhere
name is the name given
in lowercase and value is the
new value for the option. Multi-word values can be specified by using
{}-brackets or ""-signs. The following are some examples of valid
assignments of specified options:
calsecs=5
calmode=loopend
caltype = "hcorcal"
freqs= { 1410 1420 1430 }
In the following example, the first ONOFF is taken with the default
settings for all ONOFF options, while the second ONOFF is taken
according to the new options given. The third ONOFF is taken with the
same settings as the second ONOFF since the last assigned values for
all specified options are remembered. The fourth ONOFF also uses the
same settings as the second ONOFF with the only exception being the
number of loops that has been changed to five:
ONOFF ONOFF loops=1 secs = 120 caltype= "hcorcal" ONOFF ONOFF loops = 5Specified options are independent for each observing mode. The second ONOFF in the following example will thus use an integration time of 3 minutes since that was the last value specified for ONOFF-observations while the second ON observation will use an integration time of 1 minute:
ONOFF secs=180 ON secs=60 ONOFF ONSpecified options can be set up with the
SETUP command which takes an observing
mode as its first argument and then a list of specified options
belonging to that particular observing mode. The SETUP command allows a cleaner way of
writing command files where the options can be separated from the
actual observing commands. The following two examples are, however,
equivalent:
# Example 1 ON loops=5 secs=120 caltype="hcorcal" ON
# Example 2 SETUP ON loops=5 secs=120 caltype="hcorcal" ON ON
IF condition THEN commandwhere
command is any valid
command from the list below and condition is a valid Tcl/Tk
expression. Tcl/Tk accepts the following comparison operators: '==', '!=', '<', '<=', '>' and '>=' as well as
the following logical operators: '&&' for
AND, '||' for OR and '!' for NOT.
The second way is to embed commands in a long conditional statement which has the following syntax ('[ ]' denotes optional lines):
IF condition1 THEN [command1] [command2] [...] [ELSEIF condition2 THEN [command3] [command4] [...]] [ELSE [command5] [command6] [...]] ENDIFEach long conditional has to start with an IF-statement line ending with THEN and has to terminate with a line with an ENDIF-statement. It can contain an arbitrary number of ELSEIF-statements as well as an optional ELSE-statement. Long conditional statements can be nestled inside each other. It is also possible to use short conditional statements inside long conditional statements.
condition can thus include the word
LST (case doesn't matter)
which will be converted to the current LST. Any number given as a
comparison to LST should be a
time given either as decimal hours (23.955) or using hhmmss[.ss]
notation (235718.0). The LST will be automatically wrapped to avoid
problems at LST midnight roll-over --- thus, the condition LST < 001000 will evaluate as TRUE if the
current LST is 23:55, while LST >=
013000 will evaluate as FALSE at the same LST. The
following example will move the telescope to the source
baboon if
the current LST is within the range 23:30:00 and 00:15:42:
IF lst >= 23.5 && LST<001542 THEN SEEK baboonThere are also a set of functions that can be used to test whether a source is up,when it is up and how long it will take to slew to it:
ISUP(source),
RISE(source),
SET(source),
SLEW(source) and
LSTSLEW(source) (case
doesn't matter for the function names). All these functions take a
source name as their argument. The source should be a source in the catalog
specified with a previous CATALOG command
and has to be spelled exactly as in the catalog.
ISUP(source) returns '1'
if the source is up (including being in the zenith avoidance zone) and '0'
if it is not
RISE(source) gives the time
in decimal minutes until the specified source rises or '0' if the source is
currently up
SET(source) gives the time
in decimal minutes until the specified source sets the next time (even if
it is not up)
SLEW(source) gives the time
in decimal minutes it will take for the telescope to slew from the current
position to the specified source --- even if it is not up, in which case the
slew time will be the longest of the actual slew time or the time until the
source rises
LSTSLEW(source) which
behaves like SLEW(source) except that
the calculated slew time is added to the current LST --- LSTSLEW(source) is to be used in a similar way as
LST
ISUP(source) is a
boolean function, it is not necessary to explicitly test on any value;
the following example will move the telescope to the source gorilla if it is up:
IF isup(gorilla) THEN SEEK gorillaThe following is an example to check if the source baboon will be up for another 15 minutes and if the slew time to reach baboon is less than 5 minutes, in which case a 6-minute standard ON observation will be made:
IF SET(baboon) > 15 && SLEW(baboon) <= 5.0 THEN
GOTO baboon
ON secs = 360
ENDIF
The next example uses LSTSLEW(source) to
check whether the telescope can reach the start position orangutang-42 in time for a basketweave
observation to start from there:
IF LSTSLEW(orangutang-42) < 134245 THEN
SEEK orangutang-42
BASKETWEAVE source = orangutang-42 dec = +060000 lst = 134300
ENDIF
For more examples of conditional statements, see the command files at
the bottom of this page.
Save configuration' button in CIMA --- note that it is
important to apply the IF/LO setup as well as the back-end
setup before saving the configuration file, since some parameters are
set up only when You hit 'Accept' or 'Apply'
--- a 'Catalog' selection can be included in the configuration file in
which case it will be set up as the active source catalog --- note
that the configuration file should not contain anything else than a
'Signal path' and the optional 'Catalog' set-up --- anything else
stored in the configuration file (like ALFA rotation angle or observing
mode settings) will be ignored
Velocity frame Velocity type T[opocentric] v[elocity(optical)] G[eocentric] zo OR z(optical) H[eliocentric] zr OR z(radio) L[SR]
skyangle = 0.0 sky angle in degrees type = specified tracking type: "specified" or "equal" trackrate = 10 update rate in seconds maxdev = 2 max sky angle deviation in degrees method = both tracking method: "rate", "deviation" or "both" limithit1 = stay limit action: "stay", "wrap_60" or "wrap_180" limithit2 = stop limit action: "keep", "stop" or "abort"Options for TRACKSKYANGLE can be set up with SETUP
loops = 1 number of loops
caltype = hcorcal calibration type or "nocal"
calsecs = 5 calibration time in seconds
calmode = onoff calibration mode: "onoff" or "on"
adjpwr = first when to adjust power: "never", "first" or "each"
newfile = -1 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
loops = 1 number of loops
secs = 60 duration of scan in seconds
caltype = hcorcal calibration type or "nocal"
calsecs = 10 calibration time in seconds
dop = each when to update Doppler: "never", "first" or "each"
adjpwr = first when to adjust power: "never", "first" or "each"
newfile = 0 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
Some restrictions apply if the interim correlator is used: the scan
time (secs) has to be a multiple of 60
seconds and calsecs has to be "10".
loops = 1 number of loops
secs = 60 duration of scan in seconds
waitsecs = 60 wait time between ON and OFF in seconds
caltype = hcorcal calibration type or "nocal"
calsecs = 10 calibration time in seconds
dop = each when to update Doppler: "never", "first" or "each"
adjpwr = first when to adjust power: "never", "first" or "each"
newfile = 0 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
Some restrictions apply if the interim correlator is used: the scan
time (secs) has to be a multiple of 60
seconds and calsecs has to be "10".
mode = spider scan mode: "cross" or "spider"
loops = 1 number of loops
secs = 60 scan time in seconds
length = 6 scan length in beams
alfaangle = 0.0 ALFA rotation angle in degrees
caltype = hcorcal calibration type or "nocal"
calsecs = 5 calibration time in seconds
adjpwr = first when to adjust power: "never", "first", "eachloop" or "eachbeam"
newfile = 0 number of loops per file: "-2", "-1", "0", "1", "2", ...
"-2" = create a new file for each beam on each loop,
"-1" = use open file, "0" = create a new file before starting
beams = "0 1 2 3 4 5 6" list of beams to use (one cross on each)
mode = fixed type of drift: "fixed" or "follow" (Dec J2000)
loops = 1 number of loops
secs = 60 scan time in seconds
az = 180.0 azimuth in degrees
alfaangle = 19.0 ALFA rotation angle in degrees
caltype = hcorcal calibration type or "nocal"
calsecs = 1 calibration time in seconds
calwhen = loopend-ON+OFF calibration mode: "loopstart-ON", "loopstart-ON+OFF",
"loopend-ON", "loopend-ON+OFF" or "tracking"
extracal = no add extra calibration: "yes" or "no"
adjpwr = first when to adjust power: "never", "first" or "each"
newfile = 1 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
source = none source name or "none"
ra = 000000.0 source RA in hhmmss[.s] notation
dec = +100000.0 source DEC in ddmmss[.s] notation
epoch = J coordinate epoch: "J" or "B"
velocity = 0.0 source velocity in km/s or redshift
velframe = Topocentric velocity frame: "Topocentric", "Geocentric",
"Heliocentric" or "LSR"
veltype = velocity(optical) velocity type: "velocity(optical)", "z(optical)" or "z(radio)"
If source is set to "none",
then the values for source, ra, dec, epoch, velocity, velframe and veltype
are ignored. Instead the values for the last selected source is
used. This allows observers to select a source with SEEK or GOTO without
having to repeat those values when running FIXEDDRIFT --- NOTE, however, that FIXEDDRIFT changes those parameters when running,
so a new SEEK or GOTO command has to be issued before each call to
FIXEDDRIFT when run with source set to "none".
"traditional" mode runs the
telescope in RA/Dec with a negative sidereal rate, while the the
"azza" mode runs in Az/ZA
coordinates --- basketweave observations use the following specified
options with defaults indicated:
mode = traditional basketweave mode: "traditional" or "azza"
ra = 000000.0 start RA in hhmmss[.s] notation
dec = +100000.0 start DEC in ddmmss[.s] notation
lst = 000000.0 start LST in ddmmss[.s] notation
rarate = 15 RA rate in arcsecs/sec
declen = 2.0 DEC length in degrees
loops = 1 number of loops
secs = 60 scan time in seconds
turnsecs = 13 turn around time in seconds
caltype = hcorcal calibration type or "nocal"
cals = 1 number of calibrations
calsecs = 3 calibration time in seconds
calwhen = twice when to calibrate: "first", "each" or "twice"
dop = never when to update Doppler: "never", "first" or "each"
adjpwr = never when to adjust power: "never", "first" or "each"
newfile = 1 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
When mode is set to "azza",
the values for ra and rarate are ignored.
loops = 1 number of loops
caltype = hcorcal calibration type or "nocal"
secs = 5 observing time in seconds
adjpwr = never when to adjust power: "never", "first" or "each"
newfile = 0 number of loops per file: "-1", "0", "1", "2", ...
"-1" = use open file, "0" = create a new file before starting
freqs = 1420 list of frequencies to use
secs = 5 calibration time in seconds winkcal = off winking cal status: "on" or "off" caltype = hcorcal calibration type calmode = onoff calibration mode: "onoff" or "on"
loops = 1 number of loops secs = 60 calibration time in seconds winkcal = off winking cal status: "on" or "off" caltype = hcorcal calibration type
secs = 10 calibration time in seconds caltype = hcorcal calibration type offset = 4 offset to go off source in units of HPBW offsettype = azza offset coordinate type: "main" or "azza"
source = none name of source to observe
secs = 10 scan time in seconds
skyangle = 0 ALFA sky angle (only for ALFA)
timeoffset = 0 offset in seconds added to current LST when
calculating the sky angle (only for ALFA)
The option timeoffset is used to specify the
time for which the sky angle should be calculated counted as
seconds after the start of the scan. A value of zero indicates that
the sky angle should be set correctly for the beginning of the
scan. A typical use is to set it to half the value of the scan time in
order to have ALFA set to a sky angle that corresponds to the
mid-point of the scan.
source = none name of source to observe
secs = 240 scan time in seconds
calsecs = 10 calibration time in seconds
caltype = hcorcal calibration type
winkcal = off winking cal status: "on" or "off"
offsetsize = 4 cal offset in the unit given in 'offsetunit'
offsetdir = north cal offset direction: "north", "south",
"east" or "west"
offsetunit = beamwidths 'offsetsize' unit: "arcminutes" or "beamwidths"
offsettype = azza offset coordinate type: "main" or "azza"
skyangle = 0 ALFA sky angle (only for ALFA)
timeoffset = 0 offset in seconds added to current LST when
calculating the sky angle (only for ALFA)
The option timeoffset is used to specify the
time for which the sky angle should be calculated counted as
seconds after the start of the scan. A value of zero indicates that
the sky angle should be set correctly for the beginning of the
scan. A typical use is to set it to half the value of the scan time in
order to have ALFA set to a sky angle that corresponds to the
mid-point of the scan.
EXEC relies on the internal CIMA
syntax which may change without warning!
GOTO commands are used instead
of SEEK commands to allow the
ALFA rotation to take place in parallel with the slewing of the
telescope. The WAITTRACK
command is not needed since the ON observations don't start until the
telescope has reached the source.
# Command file example LOAD monkey_config.gui CATALOG monkey.cat GOTO baboon SKYANGLE 0 ON loops=1 secs=120 caltype=hcorcal calsecs=10 & dop=each adjpwr=first newfile=0 GOTO gorilla SKYANGLE 0 ON loops=1 secs=120 caltype=hcorcal calsecs=10 dop=each adjpwr=first newfile=0 # End of programIn this example, the
SETUP
command is used to set-up all options for ONOFF observations. There is
a shorter calibration observation on the bright source gorilla which only requires 1-minute
integrations, so the following ONOFF has to restore the longer
integration time required for the other sources. GOTO commands are used instead of
SEEK since ONOFF observations don't start until the
telescope is tracking. This actually saves a few seconds since the
check if the telescope is tracking is done once instead of two times.
# Example using SETUP CATALOG monkey.cat SETUP ONOFF loops=1 secs=300 waitsecs=60 caltype="hcorcal" calsecs=10 SETUP ONOFF dop="each" adjpwr="first" newfile=0 GOTO baboon ONOFF GOTO chimpanzee ONOFF GOTO gorilla ONOFF secs=60 GOTO orangutang ONOFF secs=300 GOTO mandrill ONOFFThe next example illustrates the use of conditional commands as well as the
SETUP command. It
consists of two scripts. The first one is a general script which
selects ALFA and sets up the system for basketweaving. This script is
intended to be run at the start up of each observing session and sets
up all basketweave parameters that are not going to change. The second
script contains the actual data taking commands. This script is
different for each session and uses conditional commands to select
where to take the data based on the current LST using positions given
in the catalog-file baboon.cat.
# Script 1 # Basketweave general set-up script LOAD monkey_config.gui ADJUSTPOWER CATALOG baboon.cat SETUP basketweave mode=azza rarate=15 declen=1.5 loops=5 secs=180 SETUP basketweave turntime=13 caltype=hcorcal ncals=1 calsecs=5 SETUP basketweave calmode=twice dop=never adjpwr=never newfile=1 # Script 2 # Basketweave session script with conditional commands IF lst < 235500 THEN SEEK baboon_2355 IF lst < 235500 THEN BASKETWEAVE source=baboon_2355 ra=234202 dec=+120342.1 lst=235515 IF lst < 235800 THEN SEEK baboon_2358 IF lst < 235800 THEN BASKETWEAVE source=baboon_2358 ra=234722 dec=+120513.7 lst=235815 IF lst < 000100 THEN SEEK baboon_0001 IF lst < 000100 THEN BASKETWEAVE source=baboon_0001 ra=235133 dec=+120759.0 lst=000115The following script is a calibration script to run two loops of smart frequency switching. It is supposed to run after another observation and in order not to waste time it uses the TRACKCURPOS command to ask the telescope to track the position it is currently commanded to. The script automatically selects the ALFA receiver, rotates it to 19 degrees and configures the WAPPs before the observation. The configuration file monkey_config.gui has been set up with the 'Retrack source' option set to 'No' to avoid having the telescope trying to retrack the last commanded source, which may be far away on the sky if the last observation was a drift observation.
# Smart frequency switching stand-alone calibration script
LOAD monkey_config.gui
TRACKCURPOS
ALFAANGLE 19
ADJUSTPOWER
SMARTFREQ freqs = {1415 1420 1425} secs = 10 loops = 2
The next script is an example of how to construct a program with long
conditional statements. It contains nestled IF-statements to print out of the approximate time
of the LST day. It also contains a short conditional statement inside
a long conditional statement.
# Print out the approximate time of the LST day
#
IF LST > 113000 && LST < 123000 THEN
# First do the noon
LOG "It is about LST noon."
IF LST > 115500 && LST < 120500 THEN LOG "Actually very close to noon."
ELSEIF LST < 113000 THEN
# Separate between night and morning
IF LST > 70000 THEN
LOG "It is LST morning."
ELSE
LOG "It is LST night."
ENDIF
ELSE
# Separate between afternoon and evening
IF LST > 190000 THEN
LOG "It is LST evening."
ELSE
LOG "It is LST afternoon."
ENDIF
ENDIF
The final example illustrates an ALFA pulsar observation where a
series of pulsars from the catalog
orangutang.cat are observed for 150 seconds
each. The sky angle is set to be 45 degrees at the mid-point of each
scan. ALFA has already been selected and the WAPPs have been
configured interactively from CIMA. There is a calibration done on
the source monkey and another one done on
the source mandrill just after it has been
observed.
# Pulsar observations
CATALOG orangutang.cat
ALFABEAM 0
SEEK monkey
PULSARCAL calsecs = 10 wincal = on &
caltype = hcorcal calmode = onoff
SETUP pulsarcatobs secs = 150 skyangle = 45 timeoffset = 75
PULSARCATOBS source = baboon
PULSARCATOBS source = gorilla
PULSARCATOBS source = mandrill
PULSARCAL
You can return to the main CIMA page by clicking here.