Transition Guide for New User Interface Program

H. Yoshida
Caltech Submillimeter Observatory

1 Introduction

We are going to transition to a new User Interface Program (UIP) within the next few months. The CSO community is requested to familialize themselves with the differences between the original UIP and new UIP and prepare for this transition in advance. The transition will affect:

Observing macros
Command definitions (DEFINE-END_DEFINEs in uip.ini)
Manuals and web pages
Data acquisition programs which communicate with the UIP

This memo provides a quick overview of what will be expected using examples, as well as some explanations for differences/changes. For more detailed information, please refer to Release Notes and User Guide.

2 Checklist

2.1 Observing Macros

Under the new UIP, observing macros, or procedures, can be executed using the SIC\@ command. It works like original UIP's INTERPRET command, not like the EXECUTE command. The EXECUTE command executed macros in the background using a separate instance of the UIP. The INTERPRET command on the other hand executed macros in the foreground. Commands in procedures executed by the SIC\@ command see the state of the system and observing parameters set before the SIC\@ command. Any change made or any symbol defined in procedures remains in effect after the SIC\@ command. Procedures can be interrupted cleanly by typing ^C (control-c). They can not be resumed once interrupted.

2.2 Command Definitions

Under the original UIP, you could define new commands by placing their definitions in your UIP initialization file uip.ini using the DEFINE command. For the new UIP, each command definition should be replaced with a procedure, or a procedure-command or procedure-symbol pair. A SIC procedure can be executed by using the SIC\@ command. It can be more easily executed by defining a new command using the SIC\DEFINE COMMAND command, or by defining a symbol using the SIC\SYMBOL command, in your (new) UIP initialization file, usually ~/.gag/init/init.uip.

2.3 Data Acquisition Programs

There are several TCP and UDP services associated with the new UIP. They may be utilized by data acquisition programs to nod the telescope, for example:

chicago - Chicago server (obsolete)
waspsb - Score board server for WASP
uip-net - Network UIP (version 1)
uip-net2 - Network UIP (version 2)
tel-esma - TEL interface for eSMA
uip-log - UIP message server

Their port numbers remain the same. The server address has to be changed from alpha1 to kilauea, however.

3 Examples

3.1 Observing Macros

The following example macro for the original UIP was taken from the Bolocam Web Page http://www.cso.caltech.edu/bolocam/PreparingForObserving.html. Without comments and blank lines, it looks like this:

FLSIGNAL/RESET 128
STARE 1
FLSIGNAL/SET 128
XRASTER_SCAN/STEP_SIZE=162/EQUATORIAL/ALTERNATE_DIRECTION/SETTLING_TIME=3 120 2280 15
FLSIGNAL/RESET 128

Here I intentionally changed spacing, order of parameters and qualifiers, etc., to make points clearer, but it is still a valid macro for the original UIP.

The macro has to be rewritten as follows in order for it to work under the new UIP:

FLSIGNAL 0 /BIT 7
STARE 1
FLSIGNAL 1 /BIT 7
RASTER_SCAN 120 2280 15 /STEP_SIZE 162 /EQUATORIAL /ALTERNATE_DIRECTION /SETTLING_TIME 3
FLSIGNAL 0 /BIT 7

It is apparent that:

The XRASTER_SCAN command is now called RASTER_SCAN.
The FLSIGNAL command takes different value and option.
Command identifier, command arguments, options, and option arguments are all separated by whitespace.
Command arguments immediately follow the command identifier.

Some changes are intentional, while others are due to design of underlying technologies utilized.

3.2 Command Definitions

The following example command definition for the original UIP was taken from Texas group's UIP initialization file uip.ini. The offpos command sets a default OFF position. It is defined as follows:

define offpos
c nje 12/18/98
c use offpos 600. -480. to use offpos of 10' E, 8' S
  oo /just /reset
  oo /just /nodesig /asym /nostep /nocoord /rao={p1} /deco={p2}
end_define

For the new UIP, the following procedure should be created:

! nje 12/18/98
! use offpos 600. -480. to use offpos of 10' E, 8' S
uip\off_position &1 &2 /equatorial /asymmetric

It should be named offpos.uip, and placed in the default procedure location ~/.uip/pro. Then it can be executed like this:

sic\@ ~/.uip/pro/offpos 600 -480

Optionally, a new command offpos can be defined in the UIP initialization file ~/.gag/init/init.uip as follows:

sic\define command offpos "sic\@ ~/.uip/pro/offpos.uip"

Or, alternatively, a symbol offpos can be defined in the UIP initialization file ~/.gag/init/init.uip as follows:

sic\symbol offpos "sic\@ ~/.uip/pro/offpos.uip"

Then the procedure can be executed like this:

offpos 600 -480

3.3 Manuals and Web Pages

The following example documentation was taken from the SHARC II Web Page http://www.submm.caltech.edu/~sharc/operating/observingmodes.htm:

Sample Lissajous Commands

We tend to always use 10 minute integration times for lissajous scans. The UIP command and format is:

SWEEP AX TX /YAMP=AY /YPER=TY [/ALT,/EQU,/GAL]

Size of uniform coverage	Size of uniform area in	UIP command	Comment
(arcseconds)	units of # of 9^′′ beams
115 x 38	13 x 4	`SWEEP 20 20 /YAMP=10 /YPER=14.142`	Our standard scan
77 x 29	8 x 3	`SWEEP 38.8 20 /YAMP=14.6 /YPER=14.142`	Sweeps over 1/2 of the array
38 x 14	4 x 2	`SWEEP 58.2 20 /YAMP=21.8 /YPER=14.142`	Sweeps over 2/3 of the array

Under the new UIP, the SWEEP command has /Y_COORDINATE option which takes three arguments Y_AMPLITUDE, Y_PERIOD, and Y_PHASE (Y_PERIOD and Y_PHASE are optional), instead of three separate options /YAMPLITUDE, /YPERIOD, and /YPHASE. Thus the documentation needs to be updated as follows:

Sample Lissajous Commands

We tend to always use 10 minute integration times for lissajous scans. The UIP command and format is:

SWEEP AX TX /Y AY TY [/EQU]

Size of uniform coverage	Size of uniform area in	UIP command	Comment
(arcseconds)	units of # of 9^′′ beams
115 x 38	13 x 4	`SWEEP 20 20 /Y 10 14.142`	Our standard scan
77 x 29	8 x 3	`SWEEP 38.8 20 /Y 14.6 14.142`	Sweeps over 1/2 of the array
38 x 14	4 x 2	`SWEEP 58.2 20 /Y 21.8 14.142`	Sweeps over 2/3 of the array

3.4 Data Acquisition Programs

SHARP observing/data taking scripts utilize the UIP-NET service to nod the telescope. The service runs on kilauea under the new UIP. Its TCP port number remains unchanged. Therefore only the server address needs to be updated.

4 Recommendations

Since changes like the FLSIGNAL command in the above example are involved, it will be necessary in most cases to edit/modify macros, programs, etc. to make them work under the new UIP. However the following practices will help minimize such a edit/modification:

Always separate command identifier, command arguments (parameters), and options (qualifiers) from each other by whitespace. Write like this:

COMMAND PARAMETER1 PARAMETER2 /QUALIFIER1 = VALUE1 /QUALIFIER2

instead of like this:

COMMAND PARAMETER1 PARAMETER2/QUALIFIER1=VALUE1/QUALIFIER2
Always place command arguments (parameters) immediately after the command identifier. Write like this:

COMMAND PARAMETER1 PARAMETER2 /QUALIFIER1 /QUALIFIER2 = VALUE2

instead of like this:

COMMAND /QUALIFIER1 /QUALIFIER2 = VALUE2 PARAMETER1 PARAMETER2

Please refer to Release Notes and User Guide to determine if your instrument setup will be affected by transition to the new UIP.

A References

B Revision History

1.0 (July 1, 2009) HY - Initial release.
1.1 (July 2, 2009) HY - Added recommendations.
1.2 (July 2, 2009) HY - Added the second example.
1.3 (July 8, 2009) HY - Added references to Release Notes.
1.4 (August 31, 2009) HY - Cosmetic changes.
1.5 (September 8, 2009) HY - Command definitions.
1.6 (June 20, 2011) HY - User defined commands.
1.7 (June 30, 2011) HY - Favors user defined commands over plain symbols.

File translated from T_EX by T_TH, version 4.03.
On 21 Feb 2012, 13:20.