GBT Command Line Proposal

This is a proposal for a command line interface for the GBT real-time control system.

by F.Ghigo, T.Minter, K.ONeil, R.Maddalena
May 19, 2003

Contents

1.0 Introduction.
1.1 Why command-line interface.
1.2 General Requirements.
1.3 Help facility.
1.4 Remarks on Implementation.
2.0 Users Manual A: Language features and syntax.
3.0 Users Manual B: Dictionary of keywords.
4.1 Users Manual C: Configuration commands.
4.2 Users Manual C: Balancing commands.
4.3 Observing Commands.
4.4 Lower Level Functions.

1.0 Introduction

Discussions among astronomers regarding improvements to the ease of use of the GBT led to the recommendation that a command line interface should be developed. The GUI interface will be built on top of the command line language. This has multiple advantages, including making the GUI more transparent, allowing observers to implement strategies not yet accounted for in the GUI, and acting as a back-up system for GUI failures.

1.1 Reasons why a command-line interface is important

An astronomer doing a series of experiments can save the command file used in the first session and use it again at a later date to assure that the system is set up just as it was before.
Experiments can be set up and run in batch mode -- switching from one experiment to the next just requires loading the right batch file.
An astronomer can develop his own library of observing setups and procedures.
A command-line interface is readily adapted to remote observing and dynamic scheduling.
Considerable flexibility in setup and observing is allowed: "cutting edge" observations can be set up without requiring software modifications.

It is important that the command-line system remain stable, or at least backward compatible, for decades: If an astronomer returns after an absence of several years, he should expect that his many-year-old batch file still works.

It should also be noted that the presently existing Cleo save/restore facility does not provide the needed capability because it is too thorough and too close to the hardware. Specifics of M&C managers may change from time to time. If one saves the system state with Cleo and then tries to restore it after a small manager change has happened, the restore may fail. This problem can be avoided by using configuration commands based on general keyword values. The command interpreter uses the high level keywords to command the M&C devices. Any changes in the hardware or the M&C managers must be dealt with by changes in the implementation of the command, but the commands and keywords stay the same.

1.2 General Requirements.

The system should provide commands for configuring the many GBT devices. There should be commands for setting parameters in individual devices as well as a general configuration command. Commands for all the standard observing procedures should be provided. The system should include the capabilities presently available in GO Tables.

There should be a capability for easily writing subroutines, or procedures, composed of any pre-exising commands or functions. The user should be able to create text files of commands and functions which can be loaded and executed. Any such text file should be able to include other text files.

A user should be able to easily create new observing procedures in this language (to add to standard ones such as "track", "onoff", etc). Loading a text file with these procedure definitions will add these procedures temporarily to the repertoire. Optionally, the name of the new observing procedure and its parameters will be recorded in the GO FITS file when the procedure is run.

Any command should know which of its keywords has changed since its last call. Any command should take actions based on its associated set of keywords, and should be able to do only the minimum actions required by recent changes in one or more keywords. See Section 2.10.

All commands should check their keywords for consistency and sanity and report any problems.

The routine which chooses the signal paths through the IF system, which we refer to as "findPaths", and which is described in Ghigo and Maddalena (April 9: "GBT Configuration") section 7.0, must consult three files: 1)the standard cabling file, 2)the module quality file, and 3)a temporary bad devices file. The first two are maintained by the Engineers or Operators and indicate the state of the IF cabling and hardware modules. The user can set devices in the temporary bad device file to temporarily override the module quality file and thus try using alternate modules for debugging purposes. A user can load his baddevices list from a file.

1.3 Help Facility

A help facility should be built into the command language. Although web-based documentation is useful, there should be some information available within the context of the command language where it will be immediately available. See section 2.10.

1.4 Remarks on Implementation

We do not suggest any specific implementation, but leave this to the software group. The command-line language needs to be an interpreted language, and it can be built out of some existing and well-known language, such as C++ or Python. Commands should be easily writable in the underlying language.

The capability of the existing GO Table system, allowing observing schedules in columnar form, should be retained.

The observer's GUI built on top of the command-line language should be able to save and restore the current configuration to and from a text file consisting of commands of the command-line language. One should be able to load any text file of commands and procedures, and have any new observing procedures appear in the GUI.

2.0 Users Manual A: Language and Syntax.

Here we give desirable characteristics of a user-friendly interpreted command language. Exact details of the language will be worked out by discussions between the software group and the staff astronomers. We do not expect the software group to provide all the configuration commands and all the observing commands described in subsequent sections. What we hope is that they can provide this interpreter system, some basic commands, and a means to create new commands in the context of an underlying programming language (e.g. Python). Given this, staff astronomers can write many of the configuration and observing commands.

2.1 Statements and delimiters.

Delimiters will be blanks, commas, or semicolons. Blanks can also be used to space out statements for readability. The underscore is treated as an ordinary alphabetic character.

For example, the following two statments mean the same:

        param1=17

        param1 = 17

One may put several statements on the same line:

        param1=17   param2 = 'Fred'  param3='weevils'

        param1=17,  param2 = 'Fred', param3='weevils'

New-line or end-of line is ignored within a statement, so one may write:

        param1 =

                14.2

Characters that are used as parts of numbers, such as period, decimal point, plus and minus signs, cannot be used as delimiters.

Any value that contains alphabetics is taken to be a string, for example, param1=A0045 means the same as param1='A0045' If a string contains blanks or all numbers, it must be in quotes.

Comments begin with a hash mark ( # ). Anything from the hash mark to the end of the line is ignored. These may be imbedded within statements, for example the following will work:

        param1 =      # comment 1

        14.2          # comment 2

2.2 Variables.

Assignment of a value to a variable is done with the equals ( = ) sign. Variables may be assigned a value which is a list or array of either numbers or strings. For example:

        param1=12

        param2= [2, 4, 6, 9 ]

        param3 = [ 'one', 'two', 'three']

Record structures are also available, for example:

        param4= [fred='one', sam= 17.33, olive=['primroses', 'catalpa'] ]

There are global variables corresponding to the configuration keywords. For example, the receiver keyword is set as follows:

        receiver = 'Rcvr1_2'

Variables associated with specific commands or procedures may be set with the syntax "command.variable=", for example:

        lo1.tolerance= 10

        proc.rarate = 40

The user can create a new variable "A" with the statement:

        define A

If a new variable is created outside a function definition, it is global. If it is created within a function definition, it is local to that function. If a new variable has the same name as a previously defined variable, a warning message is issued and the re-definition is allowed.

2.3 Tables.

Observing tables will work just as they do now in the GO Table system. For example, in GO tables:

header \

source             ra           dec             velocity procedure

I00070+6503        00:09:43.67    +65:20:09.3    -36.3    OffOn

I00117+6412        00:14:27.72    +64:28:46.2    -51.2    OffOn

I00420+5530        00:44:57.62    +55:47:18.1    -30.0    OffOn

is equivalent to:

source=I00070+6503  ra=00:09:43.67  dec=+65:20:09.3 velocity= -36.3  OffOn

source=I00117+6412  ra=00:14:27.72  dec=+64:28:46.2 velocity= -51.2  OffOn

source=I00420+5530  ra=00:44:57.62  dec=+55:47:18.1 velocity= -30.0  OffOn

Note here that "OffOn" is a command name which is executed simply by invoking it.

We need to eliminate the backslash (\) from the header syntax. Also, we need to permit the table to be interrupted with other statements, then resumed.

2.4 Other Existing GO Table Features.

Other useful features of the present GO table system will be retained, including:

query: a query function asks the user for a response.
alias: an alias can be created for any command, function, or variable.
everything case insensitive
a table or include file is parsed and checked for errors before it is used
If running from the GUI, one may select single lines or ranges of lines to execute.
array syntax is allowed as in Rick's writeup of GO tables.
time and angle formats recognized.

2.5 Arithmetic and logic.

Arithmetic expressions using the usual operators (* + - / % ^) and logical expressions using ( == <= >= != ) work as they do in C. Parentheses can be used to group compound expressions.

2.6 IF statements and loops

IF ... ELSE/ELSEIF, WHILE, FOR, and REPEAT constructs can be used. Statements may be grouped together with BEGIN ... END for use inside these constructs.

        IF 6h<lst<12h

               begin source='1022+33' scanlength=180 offon end

        ELSE begin source='1833+65' scanlength=240 offon end

        WHILE elevation>30d begin source='1833+333' ralongmap end

        REPEAT 5 offon

2.7 Functions

A function can be defined as follows:

        func newfunction( parameterlist )

        begin

        ....

        ....

        ....

end

Parameters in the call may be matched with parameters in the function either by order or by name.

2.8 Includes

A text file of any valid statements and function definitions may be executed by using the include command:

   include 'textfilename'

2.9 Executing lower level code

Code written in the underlying language (e.g. Python) can be loaded in a command line session. For this, use "run":

 run 'filename'

2.10 Commands.

By "commands", we mean both configuration and setup commands, and observing procedures. These commands have certain built-in features making them somewhat more sophisticated than ordinary functions.

A command uses a certain set of parameters which are keyword values either global or local to that command. It is possible to set all the parameters needed for a particular command prior to invoking the command. In that case one simply invokes the name of the command without any parameter list. For example, using the command "setReceiver" :

   receiver='Rcvr1_2'

   pol='circ'

   cal='lo-ext'

   setReceiver

The parameters may be given as in a traditional function call with the same effect:

   setReceiver(receiver='Rcvr1_2', pol='circ', cal='lo-ext')

A command knows the state of its keywords or other parameters; in particular, it can determine which of its parameters have changed since the last invocation. Different types of invokation are possible:

  commandname

        Performs only those actions required by any changes of

        parameters that have happened since the last invocation.

  commandname.init

        Performs all operations to implement all its parameters,

        regardless of whether any parameters have changed or not.

  commandname.check

        Simply reports whether any of its parameters have changed since

        the last invocation.

  commandname.list

        Lists the current values of its parameters.

  commandname.verify

        Verifies that the system is actually set up as specified

        by the keywords that this command knows about.

        Reports any discrepancies.

  commandname.default

        Sets everything to default values.

Not all commands will have all these abilities; only ones for which such capabilities are appropriate. Other options can be implemented if necessary. In particular, all commands should have a "help" option, invoked as:

     commandname.help

or

     commandname(help)

or

     help(commandname)

3.0 Users Manual B: Dictionary of Keywords.

The following two tables list the main keywords which are needed to configure the system. The chart in Figure 1 shows how the flow of information goes from keywords to hardware devices.


Primary Configuration Keywords

Primary Keyword	Options	Used by Commands	Description
Receiver	Rcvr_342 Rcvr_450 Rcvr_600 Rcvr_800 PF2 Rcvr1_2 Rcvr2_3 Rcvr4_6 Rcvr8_10 Rcvr12_18 Rcvr18_22 Rcvr22_26 Rcvr40_52 Holography	Configure findPaths calcLOBW setReceiver setLO1 setIFRack	Chooses the front-end of the system
Obstype	Spectroscopy Continuum Pulsar VLBI Radar	Configure setObstype setBackend	Choose the type of observing
Backend	DCR_IF DCR_AF DCR_PF SP SP/PT SP/PS ACS VLBI Radar BCPM Viable combinations can also be used (e.g. DCR+ACM, BCPM+SP)	Configure findPaths calcLOBW setObstype setBackend	Chooses the backend or viable combinations of backends. Note that the DCR has three input modes: the IF rack, the analog filter rack, and the Prime Focus receivers. The default should be the DCR_IF option.
Bandwidth	Spectrometer, DCR_AF: 800, 200, 50, 12.5 Spectral processor: 40, 20, 10, 5, 2.5, 1.25, 0.625, 0.312, 0.156, 0.078 VLBA:any multiple of 4MHz, up to 500MHz. Radar:20MHz (no options) BCPM:192 MHz (no options) DCRF_IF options are: PF1,PF2: 20,40,80,240 Rcvr1_2,Rcvr4_6,Rcvr8_10, Rcvr12_15: 20,80,320,1280 All other Rcvrs: 80,320,1280	Configure calcLOBW findPaths setBandwidth	This is the bandwidth of each spectral window. (This can be an array if more than 1 spectral window.)
Nwin	1,2,3,4,8	Configure findPaths calcLOBW setNwin	This simply lists the number of spectral windows available for observing. The number available is dependent on the backend, receiver, and bandwidth, as follows: Spectrometer, DCR_AF at <10GHz, w/ slow samp.: max=8; Spectrometer, DCR_AF at >10GHz, w/ slow samp.: max=4; Spectrometer, DCR_AF w/ fast samp.: max=4; Spectral Processor: max=4; DCR_IF:1
Restfreq	An array of frequencies	Configure calcLOBW setRestFreq	This is an array of frequencies, with one frequency for each spectral window. If more spectral windows are requested than frequencies given, the last frequency should be repeated to fill the windows. E.g. if Nwin=4 and Restfreq=[1420.5048] then each spectral window ends up with a center freq. of 1420.4058. The default should be one number equal to the center of the band for each receiver. The first frequency in the array is the one that is doppler tracked by the LO1 system.
Deltafreq	An array of frequencies	Configure calcLOBW	This is an array of offsets in the local frame for the spectral windows. As with the rest frequencies array, if more spectral windows are requested than frequency offsets given, the last offset should be repeated to fill the windows. The default is 0.


Secondary Configuration Keywords

Secondary Keyword	Options	used by commands	Description	Defaults
Balance	PF, IF, LO, SP, ACS, or any combination of these.	Configure Balance	This is a list of devices to balance, used by the Balance command.	IFRack
Beams	1, 2, 3, 4 12, 34, 1234	Configure findPaths setReceiver	Specify beam selection for multi-beam receivers.	1
Polarization	lin, circ	Configure setReceiver	Selects polarization mode.	"lin" (receivers < 7GHZ), else "circ"
Tuningfreq	a frequency in MHz	Configure setReceiver	Tuning frequency for the receiver. Used by the receiver manager to set gains and phases for the linear-to-circular polarization hybrid. Used by multi-beam receivers to set gains that balance beam powers. This value normally supplied by "calcLOBW".	Restfreq[1]
Noisecal	off on-ext lo-mcb lo-ext hi-mcb hi-ext	Configure setReceiver	Turns on and off the various noise cals, and set the cal control. The "ext" vs. "mcb" options control whether the switching is controlled externally or if the cal is simply turned on.	"lo-ext"
Xferswitch	thru cross ext	Configure setReceiver	Sets the state of the receiver transfer switch, if any.	"thru", unless Swtype is bsw or psw, in which case it is "ext".
Swmode	tp tp_nocal sp sp_nocal	Configure setSC	Defines the switching mode of the system: total or switched power.	"tp"
Swtype	fsw bsw psw none	Configure setSC setReceiver setLO1	This specifies frequency switching (fsw), beam switching (bsw) or polarization switching (fsw). Other options, such as tertiary switching, may be added in the future.	"none"
Swper	A time in seconds	Configure setSC	This defines the switching cycle period. The default depends on observing type.	Spectroscopy: 1s; Continuum: 0.2s; Pulsar: 0.04s; Anything Else: 1s;
Swfreq	An array of two frequencies (MHz).	Configure setLO1	The frequency offsets for frequency switching mode	[0, 0]
Velocity	One number (km/sec)	Configure calcLOBW setLO1	This is the velocity for the observation and sets the LOs/filters up accordingly. It is applied equally to all spectral windows.	0
Vlow, Vhigh	two velocities (km/sec)	Configure calcLOBW setLO1	These may be used to set up all the bandpass filters to encompass this range of velocities.	[0, 0]
Vdef	Radio Optical Relativistic	Configure calcLOBW setLO1	This specifies the velocity definition.	Radio
Vframe	Local Barycentric Heliocentric LSRK LSRD Galactocentric	Configure calcLOBW setLO1	This specifies the rest frame of the system.	Local
Nchannels	For spectrometer: 65536, 32768, 16384, 8192, 4096, 2048 (or Low, Medium, High) For spectral processor: 1024, 512, 256	Configure setSP setACS	Applicable only for the spectrometer and spectral processor.	max. number available for the desired bandwidth, backend, sampling level and number of beams.
Rcvrfilters	options depend on receiver	Configure setReceiver	Bandpass/notch filters available for each receiver. Default should be figured out from the receiver, bandwidth, and frequencies of interest. Normally the receiver filters are determined by the "calcLOBW" function from Nwin, Bandwidth, etc., but this keyword can be used to override the results of calcLOBW.
Nlevels	9- or 3-level	Configure setACS	Applicable only for spectrometer, with the slow samplers.	9
Tint	Spectrometer: 1 quadrant: 0.5s - 40s 2 quadrant: 0.7s - 40s 3 quadrant: 1.0s - 40s 4 quadrant: 1.2s - 40s SP:1s-60s? DCR: 0.01s - 60s	Configure setDCR setACS setSP	Backend integration time. For continuum mapping or pointing, the default can be set to Swper; otherwise set the default to 10 sec.
Crosspol	Cross Parallel Both	Configure setSP setACS	Set backend for cross products. Currently only applicable to the Spectral Processor. Eventually, the spectrometer will also do the cross products	parallel
Baddevs	[list of devices]	Configure setBadevice	List of devices to avoid. Temporarily overrides the module quality file.	none

4.0 Users Manual C: Dictionary of Commands.

4.1 Configuration Commands


Configuration Commands

Command	uses keywords	Description
Configure	all keywords	This sets up all devices as specified by the keywords. Later commands in this table let one re-set up the configuration due to a change of one keyword, or override the keywords and change the setup of individual devices.
calcLOBW	Nwin Restfreq Deltafreq Vlow,Vhigh,Vdef Receiver Beams Backend Bandwidth	Determines LO1 and IF1 for the LO1 manager, LO2s and filter selections, tuning frequency, IF bandpass filters, and RF filters. The results are used to set filters in the Receiver, IF Rack, Analog Filter Rack; the tuning frequency in the receiver; the LO1 and IF1 frequencies in the LO1 manager; the LO2 frequencies in the Converter Rack. The results are printed or displayed. The calculated parameters are global variables available to all commands that need them.
findPaths	Nwin Receiver Beams Backend Bandwidth	Select paths from receiver to backend for Nwin windows. Consult a)the cabling file, b)module quality file, c)temporary bad device file. The results are used to set switches in the IF Rack, Converter Rack, and analog filter rack, and select samplers in the backend. The results are printed or displayed. The path information is put into a global structure available to all commands that need it.
setBadevice	Baddevs	Lets the user set a bad device in the temporary bad device file.
setReceiver	Receiver Tuningfreq Noisecal Xferswitch Filters Beams	Change receiver selection and set receiver-specific options.
setBandwidth	Bandwidth	Changes selected back-end bandwidth: runs calcLOBW, findPaths, and changes setups to all devices as necessary.
setObstype	Obstype	Change Obstype and makes changes to setups as necessary.
setBackend	Backend	change backend selection. Needs to run calcLOBW, findPaths, and change setups of devices as necessary.
setNwin	Nwin	Change number of spectral windows. Runs findPaths and change devices setups as necessary.
setRestfreqs	restFreqs	Change Rest frequency array. Runs calcLOBW and makes changes to LO1 and Converter rack as necessary.
setDeltafreqs	deltaFreqs	Change frequency offset array. Runs calcLOBW and makes changes to LO1 and Converter rack as necessary.
setSC	Receiver Backend Swmode Swper	Set up the Scan Coordinator. Use this command to override how it was set up with the Configure command.
setLO1	Receiver Restfreq Velocity Vdef Vframe Tolerance Swfreq Swtype Phasecal Testtone	Set up LO1. Use this command to override the standard configuration, also to set oddball options such as phasecal and test tones.
setIFRack	Receiver Pathlist IF bandpass transfer switches balance levels	Set IF Rack-specific options.
setCNVRack	Pathlist Backend output select switches	Set converter rack options.
setAFR	Pathlist Bandwidth Backend filter settings	Set analog filter rack options.
setDCR	Pathlist Tint	Set DCR options.
setACS	Pathlist Nchannels Bandwidth Nlevels Tint	Set spectrometer options.
setSP	Pathlist pulsar/spectral mode Nchannels Tint Bandwidth pulsar-specific options	Set spectral processor options.
setBCPM	Pathlist channelBW sumpol other BCPM options.	Set BCPM options.

4.2 Balancing Commands


Balancing Commands

Command	uses keyword	Description
Balance	Balance	Adjusts power levels as specified by the Balance keyword.
Balance_PF	Balance	Adjusts power levels in the prime focus receiver.
Balance_IF	Balance	Adjusts power in the IF Rack.
Balance_LO	Balance	Adjusts the LO power.
Balance_SP	Balance	Adjusts the power in the Spectral Processor.
Balance_ACS	Balance	Adjusts the power in the Spectrometer (ACS).

4.3 Observing Commands

Observing commands run observing procedures such as the existing "track", "offon", "pointmap", etc. These commands have the properties of commands in general as described in section 2.10. In addition, these commands will cause the generation of a GO FITS file when they run a scan. The name of the observing procedure and its parameters will be written to the FITS file. New observing commands can be written in terms of existing commands.

All of the existing observing procedures available in GO will become observing commands and will have a similar format and properties as the previously discussed commands. We will not describe them here.

4.4 Lower Level Functions

Commands are built out of lower level functions that provide access to the YGOR system. Basic functions that get and set YGOR parameters need to be provided. Something of the following sort would be used to set and get manager parameters:

         setygor( managername, parametername, value)

            getygor( managername, parametername)

A repertoire of manager control functions, similar to what is available in ygor_g and segeste, will be available. For example, some of these function might look like this:

        start( managername, time)

        stop(managername)

        regchange( managername)

        mstate = getstate( managername)