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

Template Modules

• Templates files of an instrument are archived in a set of 4 cmm modules :xxoseq : observing template sequencer filesxxotsf ; observing template signature files xxmseq : technical template sequencer files xxmtsf : technical template signature files• examples:EFOSC: efoseq efotsf efmseq efmtsfFEROS: feoseq feotsf femseq femtsf

Naming Rules:• <INST>_<mode>_<type>[_<description>].seq1. INST = instrument name.2. mode = name of instrument mode. 3. type = acq , obs , cal , tec4. description = purpose of the template

• examples:EFOSC_img_acq_MoveToPixel.seqFEROS_ech_cal_wave.seq

A case: efoseq/tsf

wefosc efomgr:~ 1006 > cd CURRENTLY_MOD/efoseq/wefosc efomgr:~/CURRENTLY_MOD/efoseq 1007 > ls -1./../ChangeLogbin/config/doc/include/lib/object/src/wefosc efomgr:~/CURRENTLY_MOD/efoseq 1008 >

efoseq template list

wefosc efomgr:~/CURRENTLY_MOD/efoseq/src 1012 > ls -1 *.seq

EFOSC_img_acq_MOS.seqEFOSC_img_acq_MoveToPixel.seqEFOSC_img_acq_MoveToSlit.seqEFOSC_img_acq_Preset.seq……………………………………………………………EFOSC_img_cal_Darks.seqEFOSC_img_cal_Flats.seq……………………………………………………………EFOSC_img_obs_Image.seqEFOSC_img_obs_ImageJit.seq……………………………………………………………EFOSC_spec_obs_MOS.seqEFOSC_spec_obs_Polarimetry.seqEFOSC_spec_obs_Spectrum.seqwefosc efomgr:~/CURRENTLY_MOD/efoseq/src 1013 >

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 } {

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 {}}

Single observation procedureproc 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 {}}

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}

Template Signature Fileswefosc efomgr:~/CURRENTLY_MOD/efotsf/config 1020 > ls -1./../EFOSC2.isfEFOSC_img_acq_MOS.tsfEFOSC_img_acq_MoveToPixel.tsfEFOSC_img_acq_MoveToSlit.tsf………………………………………………………………EFOSC_img_obs_Image.tsfEFOSC_img_obs_ImageJit.tsfEFOSC_spec_cal_ArcFF.tsfEFOSC_spec_obs_Spectrum.tsfwefosc efomgr:~/CURRENTLY_MOD/efotsf/config 1021 >

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 parameterDET.WIN1.UIT1.TYPE "number"; # Keyword typeDET.WIN1.UIT1.RANGE "0.0..42300.0"; # Valid rangeDET.WIN1.UIT1.DEFAULT "0"; # Default valueDET.WIN1.UIT1.LABEL "Exposure time"; # Label used in P2PP# --------------------------------------------------------------------TPL.PARAM "DET.WIN1.ST"; # Next template parameterDET.WIN1.ST.TYPE "keyword"; # Keyword typeDET.WIN1.ST.RANGE "T F"; # Valid rangeDET.WIN1.ST.DEFAULT "F"; # Default valueDET.WIN1.ST.LABEL "CCD windowing flag"; # Label used in P2PP# -------------------------------------------------------------------……………………………………………………………………………………………………………………………………………

Standard Observation template signature file (2)

# --------------------------------------------------------------------TPL.PARAM "SEQ.TYPE"; # Next parameterSEQ.TYPE.TYPE "keyword"; # Keyword typeSEQ.TYPE.RANGE "STANDARD SCIENCE"; # Valid rangeSEQ.TYPE.DEFAULT "SCIENCE"; # Default valueSEQ.TYPE.LABEL "Standard Star flag"; # Label used in P2PPSEQ.TYPE.MINIHELP "Std star/science object"; # Short Help for keyword# --------------------------------------------------------------------TPL.PARAM "INS.FILT1.NAME"; # Next parameterINS.FILT1.NAME.TYPE "keyword"; # Keyword typeINS.FILT1.NAME.RANGE "ISF FILTERS"; # Valid rangeINS.FILT1.NAME.DEFAULT "NODEFAULT"; # Default valueINS.FILT1.NAME.LABEL "Filter"; # Label used in P2PPINS.FILT1.NAME.MINIHELP "Filter"; # Short Help for keyword

Instrument Summary FileThis 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 centerCCD.WINDOW.XRANGE "1..2060"CCD.WINDOW.YRANGE "1..2060"DET.READ.SPEED.RANGE "slow normal fast"; # Range of readout speedsFILTERS "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”………………………………………………

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";

Standard Observation template reference file

Wefosc efomgr: 1029 > cat EFOSC_img_obs_Image.refPAF.HDR.START; # Start of PAF HeaderPAF.TYPE "Reference Setup"; # Type of PAFPAF.ID " "; # ID for PAFPAF.NAME " "; # Name of PAFPAF.DESC " "; # Short description of PAFPAF.CRTE.NAME " "; # Name of creatorPAF.CRTE.DAYTIM " "; # Civil Time for creationPAF.LCHG.NAME " "; # Name of person/appl. changingPAF.LCHG.DAYTIM " "; # Timestamp of last changePAF.CHCK.NAME " "; # Name of appl. checkingPAF.HDR.END; # End of PAF Header

INS.MODE "DEFAULT"; # Instrument mode usedINS.WP.ST "F";DET1.EXP.NREP "1";wefosc efomgr: 1030 >

Libraries

Contain procedures common to:

• all VLT templates: tpl

• several templates of the same instrument(namely SOFI):

istut

tpltpl is a the general official VLT template library.

It allows to interact with the following subsystems :OS Observation SoftwareDCS Detector Control Software

ACE ACE CCD controllerFIERA FIERA CCD controllerIRACE Infrared Acquisition Control Electronics

ICS Instrument Control SoftwareTCS Telescope Control SoftwareUIF User InterFaceDR Date Reduction

Library module(s)

• istut is the library module for sotplsrc/istutUtils.tcl : all sooseq somseq procedures

Standard instrument libraries

Library files may rather be stored in the <module>/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.tcl parallax

-rw-r--r-- 1 efomgr vlt 34872 Jul 12 17:01 efoseqDR.tcl midas

-rw-r--r-- 1 efomgr vlt 33526 Jul 12 17:01 efoseqDomeFF.tcl dome flats

-rw-r--r-- 1 efomgr vlt 3975 Jul 12 17:01 efoseqFIERA.tcl CCD

-rw-r--r-- 1 efomgr vlt 3122 Jul 12 17:01 efoseqICS.tcl ICS

-rw-r--r-- 1 efomgr vlt 12979 Jul 12 17:01 efoseqIntFF.tcl internal flats

-rw-r--r-- 1 efomgr vlt 62726 Jul 12 17:01 efoseqOBS.tcl setup and expo

-rw-r--r-- 1 efomgr vlt 37156 Jul 24 21:06 efoseqTCS.tcl TCS

-rw-r--r-- 1 efomgr vlt 17252 Jul 12 17:01 efoseqUIF.tcl user interfaces

-

ConfigEnvInstall a library thru BOB

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).

• setset z 211Makes the content of variable z equal to 211set y $zCopies the content of variable z into variable yset a abcd1234Makes the content of a equal to string “abcd1234”set a “abcd1234”ditto

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.

tcl/tk programming• expr expr { arg1 op1 arg 2 .. }

Calculates the expresion arg1 op1 arg 2 .. set tanx [expr {sin($x) / cos($x)}]

• stringset 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 0set charnum [ string length $chain ]returns length of string contained in variable $chain into variable charnum

tcl/tk programmingControl flow

• if { $insmode == “RILD“ } { puts “Red Imaging and Low Dispersion”

}

• set i 1 ; set n 6 ; set fact 1while { $i <= $n } {

set fact [ expr { $fact * $i } ] ; incr i }

• for { set i 1 } { $i <= $n } { incr i } {....

}

tcl/tk programmingControl flow

• foreachseqWish 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. instrumentEfosc is a 3.6 tel. instrumentTimmi2 is a 3.6 tel. instrumentCes is a 3.6 tel. instrumentseqWish 103 >

tcl/tk programmingprocedures

• proc proc fact { x } {

if { $x <= 1 } {return 1

}expr $x * [ fact [ expr $x - 1 ] ]

}

>fact 4=>24>fact 0=>1

tcl/tk programmingprocedures

• globalallows 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 zset z [ expr { $y + $x }]}

tcl/tk programmingprocedures

• upvarOne cannot pass an array as parameter to a procedure because tcl proceduresaccept 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 }. . .

tcl/tk programmingFile 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 $fileIdinclose $fileIdout

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

outside systems

• BOSS = interface between BOB and TCS/ICS/DCS) :

• TIF = Telescope Interface

• PCO = protocol converter ( interface to MIDAS)

interaction with outside systems

• BOSS (BOSS ( ex OS ) = interface between BOB and TCS/ICS/DCS) :

sendCmd <time out> “<BOSS command>“

BOSS main commands are :

1. SETUP prepare telescope, instrument and or detector for exposure2. START start the exposure prepared by the previous setup commands3. END close the setup sequence without performing a detector

exposure.4. WAIT wait for the end of the current exposure.

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 ).

Syntax of BOSS commands

SETUP parameters are

-expoId <$variable>variable = exposure reference number while setup

is active.

-function <keyword1> <value1> [[<keyword2> <value2>] ....]keywords are telescope/instrument/detector relatedand defined in Dictionaries.

-file <Setupfile.ref><Setupfile.ref> is a file containing keywords and

values alike -function parameters or obd files.

Syntax of BOSS commands• START

starts the exposure prepared by the previous setup commands

sendCmd $gvar(libtplStartTimeOut) "START -expoId $ID"

• ENDcloses the setup sequence without performing a detector exposure.

sendCmd $gvar(libtplStartTimeOut) "END -expoId $ID"

• WAITwaits 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.)

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"

Exposure sequence Using TPL methods

catch { delete object obs } efoseqOBS obs efo ……………………………………………………… obs Setup "-file $TPL(REFSUP)" obs Start obs Wait

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

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.

tsfxDifferent 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 <module>/include subdirectory while the main tsfx files must be stored in the <module>/src one.

InstallationAs 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: <module>/src/Makefile

Specific parts of a template Makefile are:

# TCL libraries (public and local)# ------------------------------TCL_LIBRARIES = efoseqTCL_LIBRARIES_L =# <brief description of lllll library>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

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

Configuration controlcmm reminder

To modify a module:

1. login under a VLT environment manager account;(e.g. efomgr nttmgr ferosmgr wfimgr nttops etc..)

2. Verify that <your name> and <your cmm code> are in ~/.cmmrc.3. cd CURRENTLY_MOD4. cmmModify -l <you name> <module>5. ... modify ...6. Modify <module>/Changelog7. cmmCheckForArchive -l <you name> <module>8. if OK,9. cmmArchive -l <you name> <module> “<reason and/or description

of the change>”