The "Automated Functions" view is are designed as to perform a container for a series of functions actions that mimic the idea of a script. These functions will actions will run automatically without any or very little interaction from the user. It is important to remember that these are NOT tcl scripts running within LOIS. It is more like a LOUI macro.

...

We currently support only one such automated function that allows slewing and/or dithering based on a pattern file.

• Slew-Dither Pattern

Anchor
SlewDitherPattern SlewDitherPattern

Slew-Dither Pattern

Introduction

The first This function that is implemented within this view is the dither function:

Image Removed

is a generic implementation of a slew and/or dither pattern. The format of the input file will determine the command issued to the TCS. 

Image Added

Each input row, whether it is a slew or dither, is generally The dithering is composed of three independent actions; TCS move (slew or offset) command, filter move, and an exposure. The input is a pattern file:

"TYC 2531-01739-1" 2.0 0.0 30.0 U "first dither (0,30) - U"
"TYC 2531-01739-1" 2.0 30.0 0.0 B "second dither (30,0) - B"
"TYC 2531-01739-1" 2.0 0.0 -30.0 V "third dither (0,-30) - V"
"TYC 2531-01739-1" 2.0 -30.0 0.0 R "fourth dither (-30,0) - R"
"TYC 2531-01739-1" 2.0 30.0 30.0 I "fifth dither (30,30) - I"
"TYC 2531-01739-1" 2.0 0.0 0.0 OPEN "origin"

#title=true ra=true dec=true exposureTime=true numExposures=true filter=true subframe=false muRA=true muDec=true epoch=false dRA=true dDec=true rotatorPA=true rotatorFrame=true xi=true eta=true comment=true commandOption=false
#
"Vega - Alpha Lyrae" 18:36:56.336 +38:47:01.28  10.0  3  V 10 5  2 1 0.0 Target 30 60 "Comment 1"
"Vega - Alpha Lyrae" 18:36:56.3   +38:47:1.3    20.0  3  R 10 5  2 1 0.0 Fixed  10 20 "Comment 2"

Each input line may be Each input line is composed of 

• object title - string composed of any valid ASCII character surrounded by double quotation (")
• exposure time - float/double (seconds)
• - default = most recent science target
• Right Ascension (hh:mm:ss.sss)
• Declination (+dd:mm:ss.ss)
• exposure time offset 1 (xi)  - float/double (arc-seconds)offset 2 (eta) - float/double (arc-seconds)default=0.0
• number of exposures - integer - default=1
• filter name - string that has to match the display filter name (no spaces allowed - see LMI Filter Information.)
• comment - string composed of any valid ASCII character surrounded by double quotation (") - optional

The input is not fixed width and is validated when loaded. The validation checks for correct number of parameters, correct numerical format and correct filter names. The offset command is an absolute TCS offset command in TPLANE mode. Both parameters are in arc-seconds with a maximum allowed value that is set in the configuration file:

<tcs-dither-limit>900.0</tcs-dither-limit>

By default a pattern will run only once and if it needs to be repeated, the loop count can be increased.

Operation

The initial action is to "Load Pattern File" which will present a dialog box for selecting the input file. The default extension is *.txt but the dialog box allows selection of other types even though they are dimmed. The "Execute" button will be enabled after the input has been processed and validated.

Pressing the "Execute" button starts the process and there will be no further interaction with the user unless the user wishes to abort the process. The offset and filter move commands are asynchronous and are issued concurrently. Both commands have to be completed before the exposure command is initiated. The process checks for the TCS in position flag and the AOS settled flag to determine that the offset command is completed. The filter move command completion is based on the responses from the OMS cards. The exposure is initiated via the following LOIS command: 

single start {test=false} {sub=0} {oscan=32} {trigger=soft} {etime=2.0} {nexp=1} {title=TYC 2531-01739-1} {comment1=first dither (0,30) - U}

eTime, title, and comment1 are from the input line. All other parameters are either set by default or are read from LOIS cache. The default settings are:

{test=false} {sub=0} {oscan=32} {trigger=soft} {nexp=1}

setamp, sub, rbin, cbin, oscan, trigger, etime, nexp, and frame are taken from LOIS cache. To make sure that the exposure command is correct, it is important to take a test image so that the cache values are updated to the desired ones. After the exposure is complete and readout has started, the action will proceed to the next row and the appropriate row in the table is highlighted. There will be a message in place of the iteration number when the pattern is complete.

The process can only be aborted by pressing the abort button within the view. Using other abort buttons or stop series buttons will have unforeseen results. The abort stops the loop but it may not stop the last exposure. Depending on where LOIS is in the exposure process, LOIS may decide to finish the exposure but the file will not be written to disk.

Notes

Dither function may be used without any dithering. For instance, it can be used for taking exposures at different filters on the same object while guiding. If ALL the offset values in the pattern file are zero, the code will not send any offset command to the TCS. In this special case, the guide state will not change. By default guiding will turn off when an offset command is received by the TCS and there is no offset guiding is available at this time.

Another special case is when exposure time is set to 0. In this case the command will not be sent to LOIS. This can be used for resetting the system back to an initial state by issuing 0 offsets and moving the filter wheels without any exposure.

The filter moves are synchronous and the secondary filter wheel will always be homed.

On rare occasions, a filter move fails and the system gets into an unknown state. The code has no way to recover or even acknowledge this failure. It is imperative to monitor the progress and use the Abort button if necessary.

After a pattern file has run, the execute button will not be re-enabled. If for some reason the user needs to run the same pattern file, it will have to be loaded again.

Slew/Dither Function

Introduction

This function is a generic implementation of a slew or dither pattern. The format of the input file will determine the command issued to the TCS. 

Image Removed

The action, whether it is a slew or dither, is composed of three independent actions; TCS command, filter move, and an exposure. The input is a pattern file:

#title=true ra=true dec=true exposureTime=true numExposures=true filter=true muRA=true muDec=true epoch=true dRA=true dDec=true rotatorPA=true rotatorFrame=true xi=true eta=true comment=true
#
"Vega - Alpha Lyrae" 18:36:56.336 +38:47:01.28  10.0  3  V 10 5 2000 2 1 0.0 Target 30 60 "Comment 1"
"Vega - Alpha Lyrae" 18:36:56.3   +38:47:1.3    20.0  3  R 10 5 2000 2 1 0.0 Fixed  10 20 "Comment 2"

Each input line may be composed of 

• object title - string composed of any valid ASCII character surrounded by double quotation (")
• Right Ascension (hh:mm:ss.sss)
• Declination (+dd:mm:ss.ss)
• exposure time - float/double (seconds)
• number of exposures - integer
• filter name - string that has to match the display filter name (no spaces allowed)
• Proper Motion in RA - float/double (mas/yr)
• Proper Motion in DEC - float/double (mas/yr)
• epoch - float/double
• differential track rate in RA - float/double (arc-seconds/hour)
• differential track rate in DEC - float/double (arc-seconds/hour)
• rotator Position Angle - float/double (degrees)
• rotator Frame - literal string (Fixed or Target)
• offset 1 (xi) - float/double (arc-seconds)
• offset 2 (eta) - float/double (arc-seconds)
• comment - string composed of any valid ASCII character surrounded by double quotation (") - optional

The input is not fixed width and there is some validation when loaded. The first 2 lines are meta data and have to be present in the exact form stated above. The boolean value (true or false) for each parameter tells the loading function what to expect and what to validate. All the input files have to follow the format indicated by the meta data.

The validation checks for correct number of parameters, correct numerical format and correct filter names. Obviously not all combination of parameters are legal. For instance if both RA/DEC and Xi/Eta are present, the slew command will take precedence and the offset command will not be issued.

The offset command is an absolute TCS offset command in TPLANE mode. Both parameters are in arc-seconds with a maximum allowed value that is set in the configuration file:

<tcs-dither-limit>900.0</tcs-dither-limit>

By default a pattern will run only once and if it needs to be repeated, the loop count can be increased.

Operation

The initial action is to "Load Pattern File" which will present a dialog box for selecting the input file. The default extension is *.txt but the dialog box allows selection of other types even though they are dimmed. The "Execute" button will be enabled after the input has been processed and validated.

Pressing the "Execute" button starts the process and there will be no further interaction with the user unless the user wishes to abort the process. The TCS (slew or offset) and filter move commands are asynchronous and are issued concurrently. Both commands have to be completed before the exposure command is initiated. The process checks for the TCS in position flag, the AOS settled flag and the DOME in position flag to determine that the TCS move command is completed. The filter move command completion is based on the responses from the OMS cards. The exposure is initiated via the following LOIS command: 

single start {test=false} {sub=0} {oscan=32} {trigger=soft} {etime=2.0} {nexp=1} {title=TYC 2531-01739-1} {comment1=first dither (0,30) - U}

eTime, nexp, title, and comment1 are read from the input line. All other parameters are either set by default or are read from LOIS cache. The default settings are:

{test=false} {sub=0} {oscan=32} {trigger=soft} {nexp=1} {title=current science target name}

setamp, sub, rbin, cbin, oscan, trigger, etime, nexp, and frame are taken from LOIS cache. If title is not provided in the input line, the current science target name will be used. And if there is no science target has been issued prior to executing the macro, UNKNOWN is used for title. To make sure that the exposure command is correct, it is important to take a test image so that the cache values are updated to the desired ones. After the exposure is complete and readout has started, the action will proceed to the next row and the appropriate row in the table is highlighted. There will be a message in place of the iteration number when the pattern is complete.

The process can only be aborted by pressing the abort button within the view. Using other abort buttons or stop series buttons will have unforeseen results. The abort stops the loop but it may not stop the last exposure. Depending on where LOIS is in the exposure process, LOIS may decide to finish the exposure but the file will not be written to disk.

Notes for special cases

The function may be used without any slewing or dithering. For instance, it can be used for taking exposures at different filters on the same object while guiding. In this special case, the guide state will not change. By default guiding will turn off when an offset command is received by the TCS and there is no guided offsets are available at this time.

Another special case is when exposure time is set to 0. In this case the command will not be sent to LOIS. This can be used for resetting the system back to an initial state by issuing 0 offsets and moving the filter wheels without any exposure.

The filter moves are synchronous and the secondary filter wheel will always be homed.

On rare occasions, a filter move fails and the system gets into an unknown state. The code has no way to recover or even acknowledge this failure. It is imperative to monitor the progress and use the Abort button if necessary.

...

• subframe - comma delimited list of integers - default=0 (full frame)
• Proper Motion in RA - float/double (mas/yr) - this is the angular measurement used by most catalogs: μα×cos(δ)
• Proper Motion in DEC - float/double (mas/yr) - μδ
• differential track rate in RA - float/double (arc-seconds/hour)
• differential track rate in DEC - float/double (arc-seconds/hour)
• rotator Position Angle - float/double (degrees)
• rotator Frame - literal string (Fixed or Target)
• offset 1 (xi) - float/double (arc-seconds)
• offset 2 (eta) - float/double (arc-seconds)
• comment - string composed of any valid ASCII character surrounded by double quotation (")
• commandOption - literal string (Slew or Dither) 

The input is not fixed width and there is some validation when loaded. The first 2 lines are meta data and have to be present in the exact form stated above. The boolean value (true or false) for each parameter tells the loading function what to expect and what to validate. All the input lines have to follow the format indicated by the meta data, in other words each line of the input file should have the same number of parameters.

The validation checks for correct number of parameters, correct numerical format and correct filter names. Obviously not all combination of parameters are legal. For instance if both RA/DEC and Xi/Eta are present, the slew command will take precedence and the offset command will not be issued unless the command option is set which will override this logic. 

The offset command is an absolute TCS offset command in TPLANE mode. Both parameters are in arc-seconds with a maximum allowed value that is set in the configuration file:

<tcs-dither-limit>900.0</tcs-dither-limit>

By default a pattern will run only once and if it needs to be repeated, the loop count can be increased.

Operation

The initial action is to "Load Pattern File" which will present a dialog box for selecting the input file. The default extension is *.txt but the dialog box allows selection of other types even though they are dimmed. The "Execute" button will be enabled after the input has been processed and validated. The validation can cause either an error or a warning. The input file will not be loaded if the code detects an error such as wrong syntax for an input line. A warning on the other hand will generate a pop-up message informing the user that an issue may exist but it will still load the file after the dialog box has been dismissed. Example of a warning is a pattern file with filter=true and having the same filter position for every line.

Pressing the "Execute" button starts the process and there will be no further interaction with the user unless the user wishes to abort the process. The TCS (slew or offset) and filter move commands are asynchronous and are issued concurrently. Both commands have to be completed before the exposure command is initiated. The process checks for the TCS in position flag, the AOS settled flag and the DOME in position flag to determine that the TCS move command is completed. The filter move command completion is based on the responses from the OMS cards. On rare occasions, the filter move operation overshoots the desired filter and settles in the next filter detent. Unlike the LMI Camera Control view, the code in this function does not check that we are at the desired filter. It only checks for completion of the move command.

The exposure is initiated via the following LOIS command: 

single start {test=false} {sub=0} {oscan=32} {trigger=soft} {etime=2.0} {nexp=1} {title=TYC 2531-01739-1} {comment1=first dither (0,30) - U}

eTime, nexp, title, and comment1 are read from the input line. All other parameters are either set by default or are read from LOIS cache. The default settings are:

{test=false} {sub=0} {oscan=32} {trigger=soft} {nexp=1} {title=current science target name}

setamp, rbin, cbin, and frame are taken from LOIS cache. The value of the Image Title parameter in the LMI Camera Control is not used in this function. So if title is not provided in the input line, the current science target name from TCS will be used. And if there is no science target has been issued prior to executing the macro, UNKNOWN is used for title.

After the exposure is complete and readout has started, the action will proceed to the next row and the appropriate row in the table is highlighted. There will be a message in place of the iteration number when the pattern is complete.

The process can only be aborted by pressing the abort button within the view. Using other abort buttons or stop series buttons will have unforeseen results. The abort stops the loop but it may not stop the last exposure. Depending on where LOIS is in the exposure process, LOIS may decide to finish the exposure but the file will not be written to disk.

Some times it becomes necessary to abort a pattern file manually or it can be automatically aborted. In such cases it will be more efficient to reload the original pattern file but start from the aborted row instead of editing the file and starting from the beginning of the modified list. This is accomplished by putting the relevant row number in the text box right below the loop count. If loop count is greater than 1, the next loop begins at row 1.

Notes

Guiding may turn off when an offset command is received by the TCS. Guided offsets are supported but there are limitations that the user needs to be aware of. Please consult with the operator if you plan to use guided offsets.

Another special case is when exposure time is set to 0. In this case the command will not be sent to LOIS. This can be used for resetting the system back to an initial state by issuing 0 offsets and moving the filter wheels without any exposure.

The filter moves are synchronous and the secondary filter wheel will always be homed.

After a pattern file has run, the execute button will not be re-enabled. If for some reason the user needs to run the same pattern file, it will have to be loaded again.

 The code does not check whether the filter is at the desired location so if a filter move fails in a way that it goes to the wrong filter but the detent is good, the pattern will continue with the exposure. If the detent is bad, there will be an automatic abort and a dialog box will pop up explaining what happened.

Target rejection by TCS is NOT caught and the pattern will continue with the execution of the commands assuming that TCS is at the right coordinates after TCS gets in position

There is no way to pause in the middle of a series so a pause command will take effect at the end of the series. One should also remember that we cannot resume at an arbitrary row. The code will resume at the point that it had paused.

Special Cases

Color Sequence

The function may be used without any slewing or dithering. For instance, it can be used for taking exposures at different filters on the same object while guiding. In this special case, the guide state will not change. Below is a sample pattern file for such a case:

#title=false ra=false dec=false exposureTime=true numExposures=true filter=true muRA=false muDec=false epoch=false dRA=false dDec=false rotatorPA=false rotatorFrame=false xi=false eta=false comment=true commandOption=false
#
   10.0  3  V  "3 exposures of 10sec at V"
   20.0  2  R  "2 exposures of 20sec at R"
   30.0  1  B  "1 exposure of 30sec at B"

Dithering

A common use of this function is to perform a dither pattern. Please remember that the TCS offset command is an absolute offset command in TPLANE mode and that the TCS will not automatically clear the offsets upon receiving a new science target. So you should consider using an offset of 0,0 as the last row with exposure time of 0 seconds to effectively clear the offsets in the TCS. Below is a sample pattern file for such a case. The title is set to false so the last science target name will be used and with numExposures set to false, the default value of 1 is used.

#title=false ra=false dec=false exposureTime=true numExposures=false filter=true muRA=false muDec=false epoch=false dRA=false dDec=false rotatorPA=false rotatorFrame=false xi=true eta=true comment=true commandOption=false
#
10.0 U      0.0  30.0 "first dither (0,30) - U"
10.0 B     30.0   0.0 "second dither (30,0) - B"
10.0 V      0.0 -30.0 "third dither (0,-30) - V"
10.0 R    -30.0   0.0 "fourth dither (-30,0) - R"
10.0 OPEN   0.0   0.0 "origin"

Slewing

Probably the most common use of this function is to perform a series of slews automatically. Most of the meta data parameters are relevant to this case where a science target XML packet has to be generated and sent to the TCS. The example below shows the a simple slew pattern including the title, RA/DEC, exposure time, number of exposures and the filter. Since all the exposure are with the V filter, this pattern file can be simplified by setting filter to false and therefore eliminating the column. The user has to make sure though that the filter is correctly set in the test image prior to the start of the pattern.

#title=true ra=true dec=true exposureTime=true numExposures=true filter=true muRA=false muDec=false epoch=false dRA=false dDec=false rotatorPA=false rotatorFrame=false xi=false eta=false comment=false commandOption=false
#
"Field5 " 00:15:00.00 +45:30:00.0   2 1 V
"Field6 " 00:26:00.00 +46:30:00.0  15 2 V
"Field7 " 00:37:00.00 +47:30:00.0   5 3 V

Slewing & Dithering

This is the latest enhancement to the function allowing the user to issue slews and dithers using the same input file. This is accomplished by the commandOption parameter. An example pattern file is shown below. When the command option is Slew, there should be valid values for ξ and η even though these values will be ignored. The reverse is also true so when the command option is Dither, RA and DEC have to be present and valid even though they will be ignored.

#title=true ra=true dec=true exposureTime=true numExposures=true filter=true muRA=false muDec=false epoch=false dRA=false dDec=false rotatorPA=false rotatorFrame=false xi=true eta=true comment=true commandOption=true
#
"object 1" 00:15:00.00 +45:30:00.0  10.0  1 R  0  0 "Object 1, slew, no dither"         Slew
"object 1" 00:15:00.00 +46:30:00.0  10.0  1 R 30 30 "Object 1, dither 30,30"            Dither
"object 1" 00:15:00.00 +46:30:00.0  10.0  1 R 60 60 "Object 1, dither 60,60"            Dither
"object 1" 00:15:00.00 +46:30:00.0   0.0  1 R  0  0 "Object 1, dither 0,0 - clear"      Dither
"object 2" 00:37:00.00 +47:30:00.0   7.5  2 V  0  0 "Object 2, slew no dither"          Slew
"object 2" 00:37:00.00 +47:30:00.0   7.5  2 V 30 30 "Object 2, dither 30,30"            Dither
"object 2" 00:37:00.00 +47:30:00.0   7.5  2 V 60 60 "Object 2, dither 60,60"            Dither
"object 2" 00:37:00.00 +47:30:00.0   0.0  2 V  0  0 "Object 2, dither 0,0 - clear"      Dither