CIMA Command File Observing

A brief guide to CIMA command file observing

This page gives a brief description of the possibilities to make command file observations with CIMA version 3.1 or later.

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.

Differences compared to earlier CIMA versions

Notice that there are some differences between this version and earlier versions. The four main changes are addition and modification of some observing mode options to support new functionality introduced with the Mock spectrometer, the addition of the possibility to include an ALFA set-up in a configuration file used with the LOAD command, the addition of the possibility to include a command file from another command file and the addition of the new smart basketweave observing mode and its support commands. You will have to check and modify old command files if You want to use them with CIMA version 3.1 or later!

The following commands have been modified or added:

Two new functions related to the SELECTBASKETTRACK command have been added that can be used in IF-statements to check whether there is time to perform a smart frequency switching observation before a smart basketweave observation or not. The new functions are: RUNPRESFS and RUNPOSTSFS. There are also two new functions that tells the horizontal position of a source: AZ(source) and ZA(source), as well as a new function to check if a source is going to be available for observations during the next minutes: ISOK(source, minutes).

The following observing commands have new or modified options:

NOTE that the change of newfile may require modifications to older command files, since this option has been changed from using pure numerical values to also using words --- especially for some of the most commonly used values! For details on the use of newfile, see the CIMA data taking mode web page.

The CIMA command file interface

Command file observing is done from the Command file observing window in CIMA. This window contains a box where the command file is listed once it has been loaded, a couple of status boxes, some options as well as a set of control buttons. The control buttons will only be enabled when they are needed. You will thus always see some buttons being disabled.

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.

Running a CIMA command file

Once a command file has been loaded into CIMA, the 'Run' button in the command file observing window will be enabled. Clicking on the 'Run' button starts the execution of the command file. While the command file is being executed, all functions to load a command file, select start lines and deactivate/reactivate lines are disabled as well as the 'Close' button that otherwise allows You to close the command file observing window. The yellow-colored line indicating the start line is replaced with a blue-colored line indicating which command file line is currently being executed.

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.

CIMA command file syntax

The CIMA command files are simple line-based text-files. There should be one command per line. Blank lines are ignored. Any line starting with a '#' 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.

Continuation lines

Long commands can be split up on several lines to make a command file more readable. The requirement is that each line that is continued should have a '&'-sign at the end of the line. The following two lines thus constitute a single command:
ON loops=1 secs=120 caltype=hcorcal calsecs=10 &
   dop=each adjpwr=first newfile=0

Command options

NOTE that most command option values are NOT checked by the executive! You must make sure that the options contain sensible values and that options consisting of words are spelled exactly as listed on this page including case.

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.cat
However, 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 = value
where 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 = 5
Specified 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
ON
Specified 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

Conditional commands

It is possible to execute commands conditionally. There are two ways to achieve this --- the first is by preceding them with a conditional test. This is called a short conditional statement and the syntax is:
IF condition THEN command
where 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]
   [...]]
ENDIF
Each 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.

Conditional tests

The most typical application for a conditional test is to check what to do depending on the current LST. The 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 baboon
There are also a set of functions that can be used to test whether a source is up, where it is, when it is up and how long it will take to slew to it: ISUP(source), ISOK(source, minutes), AZ(source), ZA(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. There are two other special functions RUNPRESFS and RUNPOSTSFS that can ONLY be used together with the SELECTBASKETTRACK command. Since ISUP(source) and ISOK(source, minutes) are boolean functions, 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 and will be available for the next 10 minutes (excluding slew time):
IF isok(gorilla, 10) THEN SEEK gorilla 
The 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 including how to use RUNPRESFS and RUNPOSTSFS, see the command files at the bottom of this page.

CIMA command file commands

This is a list of the commands currently recognized by CIMA. Options and option values must be given in lowercase unless otherwise stated. It is important to type option values consisting of words exactly as indicated on this page, since results may be unpredictable otherwise. Most options values are NOT checked by CIMA; it is thus the responsibility of the observer to make sure that any command file contains proper and sensible option values! The commands themselves can be typed in either case. A good convention is to type them in uppercase.

INCLUDE command-file
include command-file into the current command file --- this is done when the command file is loaded into CIMA: when an INCLUDE command is found, the contents of command-file will be read and inserted in the place where the INCLUDE command was specified --- INCLUDE commands will thus not show up in the command file observing window (unless there is a problem with the specified command file) since the substitution is done before the loaded file is shown --- nested INCLUDE commands are allowed as long as they don't form an infinite loop

LOAD if/lo-file
load and apply a receiver selection, IF/LO set-up and backend configuration from a CIMA configuration file created with the '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 --- an 'ALFA' set-up can also be included in the configuration file (thus replacing the need to use the commands ALFABEAM, ALFAANGLE, SKYANGLE, TRACKSKYANGLE and STOPSKYANGLE) --- note that the configuration file should not contain anything else than a 'Signal path' and the optional 'Catalog' and/or 'ALFA' set-up --- anything else stored in the configuration file (like observing mode settings) will be ignored

ADJUSTPOWER
adjust the power at all places: IF1, IF2 and the selected correlator

CATALOG catalogfile
selects catalogfile as the active source catalog --- note that catalog files used for command file observations must have the velocity frame and the velocity type specified for all objects unless the default settings of 'Topocentric' and 'velocity(optical)' are OK --- velocity specifications can be given either individually on each line or with a general 'DEFAULT' line in the catalog --- velocity specifications are not case sensitive and can usually be abbreviated to one character --- the following values are accepted (characters in square brackets can be omitted):
   Velocity frame            Velocity type

   T[opocentric]             v[elocity(optical)]
   G[eocentric]              zo   OR   z(optical)
   H[eliocentric]            zr   OR   z(radio)
   L[SR]

GOTO object [offset1 offset2 units type]
SEEK object [offset1 offset2 units type]
look in the catalog file specified by CATALOG and move the telescope to object setting the velocity parameters --- GOTO will finish as soon as the telscope command has been sent while SEEK will wait until the telescope gets to the source --- GOTO is usually used together with WAITTRACK or with one of the observing modes (ON, ONOFF and PULSARON) that don't start until the telescope is tracking --- requires that a catalog file has been specified with the CATALOG command or loaded with a LOAD command --- offsets can be added to the source position found in the catalog by adding the four options offset1 offset2 units type where units is either "main" or "azza" and type is either "small" or "great" --- "main" indicates that the offset is given in the same coordinate system used to specify the source position in the catalog while "azza" indicates that the offset is given in horizontal coordinates --- "small" indicates that the offsets should be treated as small circle values while "great" indicates that they should be treated as great circle values --- offset1 and offset2 should always be specified in arcminutes

TRACKCURPOS
start tracking the currently commanded position --- this command gets the current commanded position of the telescope whatever it is, tells the telescope to start tracking that position and waits until it does so --- the velocity system is set to be topocentric with a zero velocity --- note that this is a special command developed for scripts that are used to make a calibration with the telescope in tracking mode but without caring about what the telescope actually is tracking; it should not be used in any script that uses GOTO or SEEK to select what to track

WAITTRACK
wait until the telescope is tracking the commanded position

ALFABEAM beam
set the specified ALFA beam to be the new reference beam and wait until the telescope has moved the specified beam into position --- beam should be a digit between 0 and 6 --- only works with ALFA

ALFAANGLE angle
rotate ALFA and wait until ALFA has reached the specified angle which should be within +/-99 degrees --- only works with ALFA

SKYANGLE angle [timeoffset]
set the sky angle for ALFA and wait until ALFA has been rotated to the proper angle --- the sky angle is calculated from the current commanded telescope position and the current LST unless timeoffset is specified; in that case the time used is the current LST plus timeoffset --- angle should be given in degrees and timeoffset in seconds --- NOTE that this command does not tell ALFA to track the specified sky angle; it just sets the ALFA rotation angle to the sky angle calculated for the given time --- for continuous sky angle tracking, use the TRACKSKYANGLE command --- only works with ALFA

TRACKSKYANGLE [options]
start ALFA sky angle tracking --- only works with ALFA and uses the following specified options with defaults indicated:
   skyangle  = 0.0         sky angle in degrees
   type      = specified   tracking type: "specified", "equal" or "aligned"
   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 --- the value "aligned" for type was added in CIMA version 3.1

STOPSKYANGLE
stop ALFA sky angle tracking --- only works with ALFA

NEWFILE
start a new data file for spectral line observations --- note that this command rarely is needed since the proper way to control the creation of new files is with the newfile option

SETUP obsmode options
set up parameters for the specified obsmode where obsmode has to be the name of one of the observing or calibrating modes below (case doesn't matter) and options is a set of one or more specifed options that belong to that observing mode --- SETUP can also be used for the TRACKSKYANGLE command

CAL [options]
perform a spectral line calibration --- calibrations use the following specified options with defaults indicated:
   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 = open          number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                              "open" = use open file, "one" = create a new file before starting
                              "contloop" = one continuous file per loop, "continuous" = one continuous file
Note that the interim correlator doesn't accept the newfile values "contloop" or "continuous". If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. For a more detailed description of how to use newfile, click here.

ON [options]
perform a standard ON spectral line observation --- standard ONs use the following specified options with defaults indicated:
   loops       = 1         number of loops
   secs        = 60        duration of scan in seconds
   caltype     = hcorcal   calibration type or "nocal"
   calsecs     = 10        calibration time in seconds
   winkcal     = off       winking cal on during data taking: "on" or "off"
   winkcaltype = lcorcal   type of winking cal
   dop         = each      when to update Doppler: "never", "first" or "each"
   adjpwr      = first     when to adjust power: "never", "first" or "each"
   newfile     = one       number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                              "open" = use open file, "one" = create a new file before starting
                              "contloop" = one continuous file per loop, "continuous" = one continuous file
Note that winkcal and winkcaltype ONLY can be used with the Mock spectrometer. Some additional restrictions also 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". Note that the interim correlator doesn't accept the newfile values "contloop" or "continuous". If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. For a more detailed description of how to use newfile, click here.

ONOFF [options]
perform a standard ON-OFF spectral line observation --- standard ON-OFFs use the following specified options with defaults indicated:
   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
   winkcal     = off       winking cal on during data taking: "on" or "off"
   winkcaltype = lcorcal   type of winking cal
   dop         = each      when to update Doppler: "never", "first" or "each"
   adjpwr      = first     when to adjust power: "never", "first" or "each"
   newfile     = one       number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                              "open" = use open file, "one" = create a new file before starting
                              "contloop" = one continuous file per loop, "continuous" = one continuous file
Note that winkcal and winkcaltype ONLY can be used with the Mock spectrometer. Some additional restrictions also 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". Note that the interim correlator doesn't accept the newfile values "contloop" or "continuous". If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. For a more detailed description of how to use newfile, click here.

ALFACROSS [options]
perform an ALFA cross map spectral line observation --- ALFA cross maps use the following specified options with defaults indicated:
   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
   winkcal     = off              winking cal on during data taking: "on" or "off"
   winkcaltype = lcorcal          type of winking cal
   adjpwr      = first            when to adjust power: "never", "first", "eachloop" or "eachbeam"
   newfile     = one              number of loops per file: "open", "one", "eachbeam",
                                                            "contbeam", "contloop", "continuous", "1", "2", ...
                                     "open" = use open file, "one" = create a new file before starting
                                     "eachbeam" = create a new file for each beam on each loop
                                     "contbeam" = one continuous file per beam and loop
                                     "contloop" = one continuous file per loop, "continuous" = one continuous file
   beams       = "0 1 2 3 4 5 6"  list of beams to use (one cross on each)
Note that winkcal and winkcaltype ONLY can be used with the Mock spectrometer. If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contbeam", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr values "eachloop" and "eachbeam" can't be used. When setting newfile to "contloop", the adjpwr value "eachbeam" can't be used. For a more detailed description of how to use newfile, click here.

FIXEDDRIFT [options]
perform a fixed azimuth drift map spectral line observation --- fixed azimuth drift maps use the following specified options with defaults indicated:
   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"
   winkcal     = off                winking cal on during data taking: "on" or "off"
   winkcaltype = lcorcal            type of winking cal
   adjpwr      = first              when to adjust power: "never", "first" or "each"
   newfile     = 1                  number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                                       "open" = use open file, "one" = create a new file before starting
                                       "contloop" = one continuous file per loop, "continuous" = one continuous file
   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". Note that winkcal and winkcaltype ONLY can be used with the Mock spectrometer. If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. For a more detailed description of how to use newfile, click here.

BASKETWEAVE [options]
perform a basketweave spectral line observation --- the "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"
   winkcal     = off           winking cal on during data taking: "on" or "off"
   winkcaltype = lcorcal       type of winking cal
   dop         = never         when to update Doppler: "never", "first", "each" or "twice"
   adjpwr      = never         when to adjust power: "never", "first" or "each"
   newfile     = 1             number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                                  "open" = use open file, "one" = create a new file before starting
                                  "contloop" = one continuous file per loop, "continuous" = one continuous file
When mode is set to "azza", the values for ra and rarate are ignored. Note that winkcal and winkcaltype ONLY can be used with the Mock spectrometer. If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. The value "twice" for dop was added in CIMA version 3.1. For a more detailed description of how to use newfile, click here.

SMARTBASKET [options]
perform a smart basketweave observation --- smart basketweaving can be used both in spectral line and in pulsar mode --- the parameters have to be set up in a track file --- smart basketweave observation use the following specified options with defaults indicated:
   file    = none        name of track file
   track   = auto        track number to observe or "auto" or "selected"
The track option can either be a specified track to observe or one of the words "auto" or "selected"; the word "auto" will automatically select a track that hasn't been observed so far, while the word "selected" will use a track that has already been selected. The typical way to select a track is with the SELECTBASKETTRACK command, but track can be set to "selected" even if SELECTBASKETTRACK is not used. In that case, SMARTBASKET will select a track that hasn't been observed so far just like "auto" --- the difference appears if You restart the command file: "selected" will then continue on the already selected track, while "auto" will choose another track that hasn't been observed.

SELECTBASKETTRACK [options]
select a track for a smart basketweave observation from the specified track file --- SELECTBASKETTRACK will set up the conditional test RUNPRESFS to be true if there is enough time to slew to the start position and perform a smart frequency observation before the start LST of the smart basketweaving is reached --- if this is the case, the conditional test RUNPOSTSFS will be set to false, otherwise it will be set to true --- SELECTBASKETTRACK use the following specified options with defaults indicated:
   file    = none        name of track file
   track   = auto        track number to observe or "auto"
   mins    = 5           time in minutes that SMARTFREQ needs (excluding slew time)
The time specified should be the estimated time the smart frequency switching will take excluding the slew time. It can be given as a decimal value. If SELECTBASKETTRACK determines that there is enough time to do a smart frequency switching, then the telescope will be slewed to the start position of the smart basketweaving and left in a tracking mode from that point. If there isn't enough time, then nothing will be done and the track selection and telescope movement will instead be done by SMARTBASKET.

SMARTFREQ [options]
perform a smart frequency switching spectral line observation --- smart frequency switching observations use the following specified options with defaults indicated:
   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 = one         number of loops per file: "open", "one", "contloop", "continuous", "1", "2", ...
                            "open" = use open file, "one" = create a new file before starting
                            "contloop" = one continuous file per loop, "continuous" = one continuous file
   freqs   = 1420        list of frequencies to use
If the Mock spectrometer is used without the WAPPs, the only allowed values for newfile are: "1", "contloop" or "continuous". When setting newfile to "continuous", the adjpwr value "each" can't be used. For a more detailed description of how to use newfile, click here.

PULSARCAL [options]
perform a pulsar calibration --- pulsar calibrations use the following specified options with defaults indicated:
   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"

PULSARON [options]
perform a pulsar ON observation --- pulsar ONs use the following specified options with defaults indicated:
   loops   = 1           number of loops
   secs    = 60          calibration time in seconds
   winkcal = off         winking cal status: "on" or "off"
   caltype = hcorcal     calibration type

PULSARCROSSCAL [options]
perform a pulsar cross calibration measuring on four sides of the source as well as five times on the source --- pulsar cross calibrations use the following specified options with defaults indicated:
   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"

PULSARCATOBS [options]
perform a pulsar catalog observation --- pulsar catalog observations use the following specified options with defaults indicated:
   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.

PULSARCATCALOBS [options]
perform an off-source/on-source calibration followed by a pulsar catalog observation --- pulsar catalog calibration observations use the following specified options with defaults indicated:
   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.

WAIT seconds
wait for the specified amount of time --- seconds can be any real value between 0.1 and 3600

STOP
sends a stop request to the CIMA executive telling it to stop what it currently is doing at a conveniant time, usually wait until the current observing loop is finished before stopping. Same as the 'STOP' button.

ABORT
sends a stop request to the CIMA executive telling it to stop what it currently is doing NOW. Same as the 'ABORT' button

LOG message

ALERT message
add message to the CIMA log --- LOG will just add the message to the log while ALERT also will alert the observer with a sound --- message must be enclosed either with '{}'-brackets or ""-signs

EXEC command
evaluate command which can be any internal command for the CIMA 'executive' or any valid Tcl/Tk command. This is a fall-back solution allowing command files to do things which do not have proper commands defined, and this solution should be avoided as much as possible! If You find that You need to use EXEC in a command file, please, contact the CIMA administrator (see email address at bottom of this page) to discuss possible solutions!
Note that any command using EXEC relies on the internal CIMA syntax which may change without warning!

CIMA command file examples

This is a small example to set up and make 2-minute standard on observations of a couple of sources with ALFA and the WAPPs. The desired setup for ALFA, the IF/LO system and the WAPPs have been made in CIMA and saved to the configuration file monkey_config.gui and the sources (baboon and gorilla) are given in the catalog file monkey.cat. 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 program
In 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
ONOFF
The 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=000115
The 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 following example illustrates the use of smart basketweaving together with a smart frequency switching calibration that is to be done before the smart basketweaving if there is enough time for it or otherwise afterwards. The time allocated for the smart frequency switching is 5.5 minutes excluding slew time. The script will automatically select a track that hasn't been observed from the track file baboon.track, make a smart frequency calibration before the smart basketweaving if there is time for it, run the smart basketweaving from the start RA or from the first possible RA if started too late, update the track file and finish with a smart frequency calibration if it wasn't done before the smart basketweaving.
SETUP SMARTFREQ loops=2 secs=10 caltype=hcorcal adjpwr=first newfile=continuous
SETUP SMARTFREQ freqs={1375 1390 1405 1420}
SELECTBASKETTRACK file=baboon.track track=auto mins=5.5
IF RUNPRESFS THEN SMARTFREQ
SMARTBASKET file=baboon.track track=selected
IF RUNPOSTSFS THEN
  TRACKCURPOS
  SMARTFREQ
ENDIF
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.

This page is administered by Prakash Atreya ( patreya (a) naic . edu ) and was last updated on 5 December 2008.