1. What is a template ? For the observer - a form to interact with the instrument. For the programmer - two mandatory files : *.tsf : description of input parameters *.seq : description of operations. + two optional files *.obd : to test the template (bypassing P2PP). *.ref : initial instrument setup

2. Template Modules Templates files of an instrument are archived in a set of 4 cmm modules : xxoseq : observing template sequencer files xxotsf ; observing template signature files xxmseq : technical template sequencer files xxmtsf : technical template signature files examples: EFOSC: efoseq efotsf efmseq efmtsf FEROS: feoseq feotsf femseq femtsf

3. Naming Rules : _ _ [_ ].seq 1.INST = instrument name. 2.mode = name of instrument mode. 3.type = acq, obs, cal, tec 4.description = purpose of the template examples: EFOSC_img_acq_MoveToPixel.seq FEROS_ech_cal_wave.seq

4. A case: efoseq/tsf wefosc efomgr:~ 1006 > cd CURRENTLY_MOD/efoseq/ wefosc efomgr:~/CURRENTLY_MOD/efoseq 1007 > ls -1./../ ChangeLog bin/ config/ doc/ include/ lib/ object/ src/ wefosc efomgr:~/CURRENTLY_MOD/efoseq 1008 >

5. efoseq template list wefosc efomgr:~/CURRENTLY_MOD/efoseq/src 1012 > ls -1 *.seq EFOSC_img_acq_MOS.seq EFOSC_img_acq_MoveToPixel.seq EFOSC_img_acq_MoveToSlit.seq EFOSC_img_acq_Preset.seq …………………………………………………………… EFOSC_img_cal_Darks.seq EFOSC_img_cal_Flats.seq …………………………………………………………… EFOSC_img_obs_Image.seq EFOSC_img_obs_ImageJit.seq …………………………………………………………… EFOSC_spec_obs_MOS.seq EFOSC_spec_obs_Polarimetry.seq EFOSC_spec_obs_Spectrum.seq wefosc efomgr:~/CURRENTLY_MOD/efoseq/src 1013 >

6. Standard header wefosc efomgr: 1013 > more EFOSC_img_obs_Image.seq # -*- tcl -*- #************************************************************************ # E.S.O. - 3.6m upgrade project # # "@(#) $Id: EFOSC_img_obs_Image.seq,v 2.49+ 2009/07/07 15:54:36 vltsccm Exp $" # # EFOSC_img_obs_Image.seq # # who when what # ---------- -------- --------------------------------------------- # fpatat 10/07/98 Created #------------------------------------------------------------------ proc EFOSC_img_obs_Image { parArrays obsInfo } {

7. Standard observation sequence wlsops0 nttops:~/tmp/suoseq/src 510 > cat SUSI_img_obs_Exposures.seq #*************************************************************** proc SUSI_img_obs_Exposure { parArrays obsInfo } { global gvar env foreach parArray $parArrays { upvar $parArray $parArray } suoseqInit set cmdBuffer "-function \ DPR.TECH IMAGE \ INS.FILT1.NAME $INS(FILT1.NAME) \ OCS.DET.IMGNAME SUSI_i_o_Exposures.fits \ DET.EXP.TYPE Normal \ DET.WIN1.UIT1 $DET(EXPTIME)" suoseq_obs_Exposure "$cmdBuffer" return {} }

8. Single observation procedure proc suoseq_obs_Exposure { cmdBuffer } { # cmdBuffer setup string for OS. # # get Exposure # global gvar env upvar TPL TPL upvar DET DET upvar SEQ SEQ set ID [sendCmd $gvar(suoseqSetupTimeOut) "SETUP -expoId 0 –file \ SUSI_img_obs_Exposures.ref ] sendCmd $gvar(suoseqSetupTimeOut) "SETUP -expoId $ID $cmdBuffer" sendCmd $gvar(suoseqStartTimeOut) "START -expoId $ID" sendCmd $gvar(suoseqWaitTimeOut) "WAIT -expoId $ID" return {} }

9. Object Oriented observation sequence proc EFOSC_img_obs_Image { parArrays obsInfo } { global env foreach parArray $parArrays { upvar $parArray $parArray } catch { delete object obs } efoseqOBS obs efo set setupBuf “INS.SLIT1.NAME $INS(SLIT1.NAME) \ INS.FILT1.NAME $INS(FILT1.NAME) \ INS.GRIS1.NAME Free \ DET.EXP.TYPE Normal \ DET.WIN1.UIT1 $DET(WIN1.UIT1) \ DET.WIN1.ST F\ OCS.${detId}.IMGNAME EFOSC_Image“ obs Setup "-file $TPL(REFSUP) -function $setupBuf" obs Start obs Wait return }

10. Template Signature Files wefosc efomgr:~/CURRENTLY_MOD/efotsf/config 1020 > ls -1./../ EFOSC2.isf EFOSC_img_acq_MOS.tsf EFOSC_img_acq_MoveToPixel.tsf EFOSC_img_acq_MoveToSlit.tsf ……………………………………………………………… EFOSC_img_obs_Image.tsf EFOSC_img_obs_ImageJit.tsf EFOSC_spec_cal_ArcFF.tsf EFOSC_spec_obs_Spectrum.tsf wefosc efomgr:~/CURRENTLY_MOD/efotsf/config 1021 >

11. Standard Observation template signature file (1) wlsops0 nttops:~/tmp/suotsf/config 518 > more EFOSC_img_obs_Image.tsf …………………………………………………………………………………………………………………………………………… # -------------------------------------------------------------------- TPL.PARAM "DET.WIN1.UIT1"; # Next template parameter DET.WIN1.UIT1.TYPE "number"; # Keyword type DET.WIN1.UIT1.RANGE "0.0..42300.0"; # Valid range DET.WIN1.UIT1.DEFAULT "0"; # Default value DET.WIN1.UIT1.LABEL "Exposure time"; # Label used in P2PP # -------------------------------------------------------------------- TPL.PARAM "DET.WIN1.ST"; # Next template parameter DET.WIN1.ST.TYPE "keyword"; # Keyword type DET.WIN1.ST.RANGE "T F"; # Valid range DET.WIN1.ST.DEFAULT "F"; # Default value DET.WIN1.ST.LABEL "CCD windowing flag"; # Label used in P2PP # ------------------------------------------------------------------- ……………………………………………………………………………………………………………………………………………

12. Standard Observation template signature file (2) # -------------------------------------------------------------------- TPL.PARAM "SEQ.TYPE"; # Next parameter SEQ.TYPE.TYPE "keyword"; # Keyword type SEQ.TYPE.RANGE "STANDARD SCIENCE"; # Valid range SEQ.TYPE.DEFAULT "SCIENCE"; # Default value SEQ.TYPE.LABEL "Standard Star flag"; # Label used in P2PP SEQ.TYPE.MINIHELP "Std star/science object"; # Short Help for keyword # -------------------------------------------------------------------- TPL.PARAM "INS.FILT1.NAME"; # Next parameter INS.FILT1.NAME.TYPE "keyword"; # Keyword type INS.FILT1.NAME.RANGE "ISF FILTERS"; # Valid range INS.FILT1.NAME.DEFAULT "NODEFAULT"; # Default value INS.FILT1.NAME.LABEL "Filter"; # Label used in P2PP INS.FILT1.NAME.MINIHELP "Filter"; # Short Help for keyword

13. Instrument Summary File This instrument summary file ( e.g EFOSC2.isf) describes the instrument functions and may be referred at by the tsf and tsfx files to describe the possible values that a parameter can take : ……………… CCD.CENTER "1024 1024"; # Coordinates of center CCD.WINDOW.XRANGE "1..2060" CCD.WINDOW.YRANGE "1..2060" DET.READ.SPEED.RANGE "slow normal fast"; # Range of readout speeds FILTERS "Free Empty U#640 B#639 V#641 R#642” STARPLATE "Free slit#1.0 slit#1.2” GRISMS "Free Gr#1 Gr#2 Gr#3” ………………………………………………

14. Standard Observation observing block descriptor wefosc efomgr: 1028 > cat EFOSC_img_obs_Image.obd..... TPL.ID "EFOSC_img_obs_Image"; TPL.NAME "Imaging"; DET.READ.SPEED "normal"; DET.WIN1.UIT1 "0"; DET.WIN1.ST "F"; DET.WIN1.STRX "1"; DET.WIN1.STRY "1"; DET.WIN1.NX "2060"; DET.WIN1.NY "2060"; DET.WIN1.BINX "2"; DET.WIN1.BINY "2"; SEQ.NEXPO "1"; INS.FILT1.NAME "Free"; INS.SLIT1.NAME "Free";

15. Standard Observation template reference file Wefosc efomgr: 1029 > cat EFOSC_img_obs_Image.ref PAF.HDR.START; # Start of PAF Header PAF.TYPE "Reference Setup"; # Type of PAF PAF.ID " "; # ID for PAF PAF.NAME " "; # Name of PAF PAF.DESC " "; # Short description of PAF PAF.CRTE.NAME " "; # Name of creator PAF.CRTE.DAYTIM " "; # Civil Time for creation PAF.LCHG.NAME " "; # Name of person/appl. changing PAF.LCHG.DAYTIM " "; # Timestamp of last change PAF.CHCK.NAME " "; # Name of appl. checking PAF.HDR.END; # End of PAF Header INS.MODE "DEFAULT"; # Instrument mode used INS.WP.ST "F"; DET1.EXP.NREP "1"; wefosc efomgr: 1030 >

16. Libraries Contain procedures common to: all VLT templates: tpl several templates of the same instrument (namely SOFI): istut

17. tpl tpl is a the general official VLT template library. It allows to interact with the following subsystems : OSObservation Software DCSDetector Control Software ACEACE CCD controller FIERAFIERA CCD controller IRACEInfrared Acquisition Control Electronics ICSInstrument Control Software TCSTelescope Control Software UIFUser InterFace DRDate Reduction

18. Library module(s) istut is the library module for sotpl src/istutUtils.tcl : all sooseq somseq procedures

19. Standard instrument libraries Library files may rather be stored in the /src subdirectory EFOSC2 -r--r--r-- 1 nttops vlt 46217 Dec 20 19:35 suoseqCommon.tcl -rw-r--r-- 1 efomgr vlt 9115 Jul 12 17:01 efoseqCompParal.tclparallax -rw-r--r-- 1 efomgr vlt 34872 Jul 12 17:01 efoseqDR.tclmidas -rw-r--r-- 1 efomgr vlt 33526 Jul 12 17:01 efoseqDomeFF.tcldome flats -rw-r--r-- 1 efomgr vlt 3975 Jul 12 17:01 efoseqFIERA.tclCCD -rw-r--r-- 1 efomgr vlt 3122 Jul 12 17:01 efoseqICS.tclICS -rw-r--r-- 1 efomgr vlt 12979 Jul 12 17:01 efoseqIntFF.tclinternal flats -rw-r--r-- 1 efomgr vlt 62726 Jul 12 17:01 efoseqOBS.tclsetup and expo -rw-r--r-- 1 efomgr vlt 37156 Jul 24 21:06 efoseqTCS.tclTCS -rw-r--r-- 1 efomgr vlt 17252 Jul 12 17:01 efoseqUIF.tcluser interfaces -

20. ConfigEnvInstall a library thru BOB

21. tcl/tk programming Templates are programmed in a VLT version of Tcl/Tk language which can be tested under seqWish (while BOB can only run full templates). set set z 211 Makes the content of variable z equal to 211 set y $z Copies the content of variable z into variable y set a abcd1234 Makes the content of a equal to string “abcd1234” set a “abcd1234” ditto

22. tcl/tk programming Variables 1.A tcl variable is declared implicitly by a set like command (set, scan, get etc.. ). 2.A tcl variable is always a character string. 3.Therefore it has no type. 4.If it contains only digits and at most one decimal point, it can be used as operand in an arithmetical expression. Arrays 1.Any variable of which name has the structure aaa(bbb) belongs to array aaa. 2.It can then be processed by any of the array commands. 3.From inside procedures it must be addressed thru the upvar command.

23. tcl/tk programming expr expr { arg1 op1 arg 2.. } Calculates the expresion arg1 op1 arg 2.. set tanx [expr {sin($x) / cos($x)}] string set index [ string first Ritz $lasilla ] set index value to the position of first character of first match of “Ritz” in $lasilla variable (first character of a string has index 0 set charnum [ string length $chain ] returns length of string contained in variable $chain into variable charnum

24. tcl/tk programming Control flow if { $insmode == “RILD“ } { puts “Red Imaging and Low Dispersion” } set i 1 ; set n 6 ; set fact 1 while { $i <= $n } { set fact [ expr { $fact * $i } ] ; incr i } for { set i 1 } { $i <= $n } { incr i } {.... }

25. tcl/tk programming Control flow foreach seqWish 101 > set z {Harps Efosc Timmi2 Ces } seqWish 102 > foreach j $z { puts "$j is a 3.6 tel. instrument" } Harps is a 3.6 tel. instrument Efosc is a 3.6 tel. instrument Timmi2 is a 3.6 tel. instrument Ces is a 3.6 tel. instrument seqWish 103 >

26. tcl/tk programming procedures proc proc fact { x } { if { $x <= 1 } { return 1 } expr $x * [ fact [ expr $x - 1 ] ] } >fact 4 =>24 >fact 0 =>1

27. tcl/tk programming procedures global allows to access a variable from inside a procedure without passing it as a parameter. In particular it allows to modify it while this is not possible with a normal input parameter. proc subprog { x } { global y z set z [ expr { $y + $x }] }

28. tcl/tk programming procedures upvar One cannot pass an array as parameter to a procedure because tcl procedures accept parameters by value and not by reference: upvar works around this impossibility. In particular as all OB parameters are passed by BOB as 4 tcl array names, SEQ TEL INS DET, all templates begin as follows : proc RILD_spec_cal_Arcs { parArrays obsInfo } {... foreach parArray $parArrays { upvar $parArray $parArray }...

29. tcl/tk programming File processing Example: copy content of file input.txt into new file output.txt until first empty line: set fileIdin [ open input.txt r ] set fileIdout [ open output.txt w ] set line “dummy” while { [ string length $line ] > 0 } { gets $fileIdin line puts $fileIdout $line } close $fileIdin close $fileIdout

30. tcl/tk programming exec : executes a UNIX/LINUX command : exec rm output.txt set directory [ exec ls -1 ] catch : avoids tcl script/template to abort in case of error : seqWish 100 > set a b b seqWish 101 > expr $a + 5 syntax error in expression "b + 5“ seqWish 102 > set error [catch {expr{$a + 5}} msg] 1 seqWish 103 > puts $msg syntax error in expression "b + 5“ seqWish 104 >

31. outside systems BOSS = interface between BOB and TCS/ICS/DCS) : TIF = Telescope Interface PCO = protocol converter ( interface to MIDAS)

32. interaction with outside systems BOSS (BOSS ( ex OS ) = interface between BOB and TCS/ICS/DCS) : sendCmd “ “ BOSS main commands are : 1.SETUPprepare telescope, instrument and or detector for exposure 2.STARTstart the exposure prepared by the previous setup commands 3.ENDclose the setup sequence without performing a detector exposure. 4.WAITwait for the end of the current exposure.

33. Syntax of BOSS commands SETUP prepares telescope, instrument and or detector for next exposure; set ID [sendCmd timeOut "SETUP -expoId 0 –function \ INS.MODE RILD"] sendCmd $timeOut "SETUP -expoId $ID -function \ TEL.TARG.DELTA $TEL(TARG.DELTA) \ TEL.TARG.ALPHA $TEL(TARG.ALPHA) “ To prepare a new exposure, first setup must get the $ID expoId number to refer to it in the next commands to BOSS : this is carried out setting the value after -expoId to 0 : afterwards it must be set to $ID until the end of the exposure ( WAIT –expoId $ID ).

34. Syntax of BOSS commands SETUP parameters are - expoId variable = exposure reference number while setup is active. -function [[ ]....] keywords are telescope/instrument/detector related and defined in Dictionaries. -file is a file containing keywords and values alike -function parameters or obd files.

35. Syntax of BOSS commands START starts the exposure prepared by the previous setup commands sendCmd $gvar(libtplStartTimeOut) "START -expoId $ID" END closes the setup sequence without performing a detector exposure. sendCmd $gvar(libtplStartTimeOut) "END -expoId $ID" WAIT waits for the end of the current exposure or END command. sendCmd $gvar(libtplWaitTimeOut) "WAIT -expoId $ID" After Wait is completed, $ID is released, next SETUP must be made with -expoId 0 and must include INS.MODE keyword if instrument has it defined (at La Silla only SUSI2 has no modes.)

36. Exposure sequence with BOSS commands set ID [sendCmd $gvar(suoseqSetupTimeOut) "SETUP -expoId 0 –file\ SUSI_img_obs_Exposures.ref ] sendCmd $gvar(suoseqSetupTimeOut) "SETUP -expoId $ID $cmdBuffer" sendCmd $gvar(suoseqStartTimeOut) "START -expoId $ID" sendCmd $gvar(suoseqWaitTimeOut) "WAIT -expoId $ID"

37. Exposure sequence Using TPL methods catch { delete object obs } efoseqOBS obs efo ……………………………………………………… obs Setup "-file $TPL(REFSUP)" obs Start obs Wait

38. interaction with outside systems TIF (Telescope InterFace) Some telescope functions are not accessible thru BOSS and must be addressed thru tif, as follows: Telescope offset: set cmd [seq_msgSendCommand wt5tcs tifNA OFFSAD "$RAoff,$DEoff" ] seq_msgRecvReply -last $gvar(tifNAtimeout) $cmd errFlag Calibration unit: set cmdId [seq_msgSendCommand wt5tcs tifNB CAIN ] seq_msgRecvReply -last $gvar(tifNBtimeout) $cmdId errFlag

39. interaction with outside systems PCO ( protocol converter ) pco is the tool to communicate with data reduction packages, namely MIDAS. FORWMSG sends a midas command to MIDAS: set cmS [ seq_msgSendCommand wsusi pco FORWMSG "MIDAS,11,$env(HOST),@@ EXT00loadImage lastFile.fits” ] seq_msgRecvReply -last $gvar(libtplMidasPCO) $cmS errFlag READKEY allows to read a MIDAS keyword as follows: set cmS [ seq_msgSendCommand wemmi pco READKEY \ "MIDAS,11,wemmi,outputr,REAL,0,1,4 " ] set Buffer [seq_msgRecvReply -last $gvar(libtplMidasPCO) $cmS errFlag] scan $Buffer "%d,%f,%f,%f,%f" a1 strx1 stry1 MEAN ny1 here Buffer is a string receiving the values of outputr(1) outputr(2) outputr(3) outputr(4) which are then splitted into strx1 stry1 MEAN ny1 thru scan command.

40. tsfx Different templates use common groups of parameters alike several programs call common procedures. The PAF.INCLUDE *.tsfx command allows to build the different template tsf files from the main groups of parameters : Wlsops0..575 > more SUSI_img_obs_Exposures.tsfx............. PAF.INCLUDE "suotsfSEQ_NEXPO.tsfx"; PAF.INCLUDE "suotsfDET_EXPTIME.tsfx"; PAF.INCLUDE "suotsfINS_FILT1.tsfx"; PAF.INCLUDE "suotsfDET.tsfx"; PAF.INCLUDE "suotsfSEQ_TYPE.tsfx"; Files called by PAF.INCLUDE must be stored in the /include subdirectory while the main tsfx files must be stored in the /src one.

41. Installation As all other vlt software modules, template modules are installed among several VLT standard sub­directories thru a make all install clean command referring to the file: /src/Makefile Specific parts of a template Makefile are: # TCL libraries (public and local) # ------------------------------ TCL_LIBRARIES = efoseq TCL_LIBRARIES_L = # efoseqTpl_OBJECTS = efoseqOBS efoseqTCS efoseqICS efoseqFIERA efoseqDR efoseqUIF efoseqDomeFF efoseqIntFF efoseq_OBJECTS = $(efoseqTpl_OBJECTS) # # INS_ROOT files to be installed #------------------------------- INS_ROOT_FILES = *.seq../config/*.ref../config/*.obd../config/*.prg

42. standard subdirectories After make install, template files are dispatched that way: $INS_ROOT/SYSTEM/COMMON/TEMPLATES/SEQ*.seq $INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF*.tsf $INS_ROOT/SYSTEM/COMMON/TEMPLATES/OBD*.obd $INS_ROOT/SYSTEM/COMMON/SETUPFILES*.ref $INS_ROOT/SYSTEM/COMMON/MIDAS/PROCS*.prg $INS_ROOT/SYSTEM/COMMON/CONFIGFILES shell scripts $INTROOT/lib/libefoseq/ efoseq*.tcl

43. Configuration control cmm reminder To modify a module: 1.login under a VLT environment manager account; (e.g. efomgr nttmgr ferosmgr wfimgr nttops etc..) 2.Verify that and are in ~/.cmmrc. 3.cd CURRENTLY_MOD 4.cmmModify -l 5.... modify... 6.Modify /Changelog 7.cmmCheckForArchive -l 8.if OK, 9.cmmArchive -l “ ”