BAIT: insgen command

NAME

insgen - list generator and process spawner for automatic telescope operation

SYNOPSIS

insgen [ DD/MM/YYYY ] [ sim ] [ help ] [ list ] [ makelist ] [ nopush ] [ listonly ] [ fail= ] [ noupdate ] [sim=]

DESCRIPTION

insgen is the "master program" for automatic telescope operation. It not only generates lists of objects to observe based upon all the request files currently active, but also spawns processes at the appropriate times to observe targets.

When invoked, insgen notes the current time and reads a UNIX socket ($HOME_DIR/INSERV where HOME_DIR is an environment variable) for command strings containing instructions. Commands may be sent sent by the tin command.

Activity is started by the newreqs command informing insgen of the desired targets. As each request file is read insgen makes some tests and prints one of two types of message to stdout depending on the severity of the error.

Request files that have format errors such as an invalid RA, or declinations outside of the telescope limits, or DAYEND already passed, generate a message like:


20:00:00 insgen rejects xxx.rqs `RA is bad'

Request files that are otherwise valid, but cannot be scheduled tonight generate a message like:


20:00:00 insgen skips RA11_08.rqs 'window 2 does not overlap'
20:00:00 insgen skips RA12_01.rqs 'target not visible on 02/11/1997'
20:00:00 insgen skips sn34.rqs `moon=8.6'

Situations that can cause these messages are: DAYSTART has not arrived yet or the object is too close to the Moon as set by the MOONPHASE and MOONDIST.

Once insgen has a list of targets for the current night. It then sorts the list using the following criteria.

rank (0 is better than 10)
days past due (3 is better than 2)
interval (1 is better than 2)
transit time (closer to midnight is better)

The rank depends on the PRIORITY of the observation (an integer between 0 and 100 with lower number as more important). Actually negative priorities are allowed (all the way to -100), but these should be reserved for system functions and they will not be passed on by the accepter. If the rank exceeds 100 on a given night, the message


`insgen skips xxx.rqs `rank=111'

will be printed out and the request will not be considered on that night. If an INTERVAL is specified and it is early i.e. less than INTERVAL days since the last observation (DAYLAST), then rank is decreased by the following formula.

rank = priority + 100 * (days_early/interval)

insgen then attempts to schedule each object at its "best" observation time (usually at transit). If this cannot be done, it tries to find a time at which the observation can be inserted and then `pushes' the other observations to earlier or later times that will remain consistent with their observing windows. If this cannot be done, needless to say, the object is not scheduled.

Having created a list, insgen then waits (if needed) until the system time reaches the time at which it has scheduled the first item. (If the telescope is overbooked and it is consistent with the observing window, the wait is skipped and the observation begins immediately.) Then the program prints the length of time it is waiting to stdout, as well as the name of the next target. and spawns telco with the path/name of the request file as an argument. This process then moves the telescope, switches filters, makes an exposure, etc. When the observation is complete insgen then re-makes the list (it only takes a few seconds) and starts the whole procedure over again.

If telco returns a non-zero exit code six time in a row, (or the request has been marked - see below) insgen assumes that the weather is poor and invokes weatherpause for one hour. At the end of the sleep period, it then puts the six previous failed targets back into the queue, re-evaluates an acceptable list of targets, and starts observing. Subsequent calls to weatherpause will increase the time by a factor of 1.4.

insgen will shut down 1 hour after dawn; where dawn is defined as that time the sun is ten degrees below the horizon. It will then execute morning.csh and exit. Any error causing premature termination will cause a message to be printed on stderr and a non-zero exit code to be returned. These events should only occur due to program errors or system resource problems; hopefully they will not be caused by format peculiar values in the request files.

If a request file contains a value of NUMPERNI that is greater than one, insgen chops the available observing window into NUMPERNI chunks and reproduces the request file modifying the observing window to fit each chunk. It is therefore possible that some of the observations will not be scheduled if the telescope is too busy.

After telco completes a request file it modifies it depending on the exit code. If the exit code is zero (i.e. everything was o.k) it records the date and time of the observation as DAYLAST and UTLAST respectively. In addition it increments the value of the keyword NUM-DONE. If the exit code is non-zero it only increments the value of NUM-FAIL and doesn't touch the other keywords.

If an observations fails and the request file is marked with `SENDMAIL = T' then insgen will add a line stating that the request failed to the file sendmail.log. This file is ultimately sorted by mailaddr and sent out by morning.csh.

The length of time each request file takes to execute is estimated from the exposure time and guiding acquisition (if needed). Timings for extra overhead are found in ait.config with the SIM_ symbols.

The list option causes insgen to write the file `insgen.list' which cand be viewed by the `show list' command. A typical which file contains lines similar to the following:

03:01:00      293 Nov3adrq     20 done     LBL        D00187X 
03:05:57      515 sn5          15 error    SN         NGC7541
03:14:38      197 Nov3adqs     38.selected LBL        D23637A
09:48:30      350 RA04_07      61 nospace  SN         NGC1518
09:49:23      870 RA04_02      61 nospace  SN         NGC1517
20:18:52      350 RA15_01      11 skipped  SN         NGC5812
20:19:02      870 RA15_02      11 skipped  SN         NGC5813

where the first field is the Universal time of the start of the request file, the second is the expected observation time (in seconds) of the entire request file, the third the the request id, the fourth field is the rank. The fifth field has the messages done - if observed successfully; error - if exit code was 1; selected - if an observation is planned; nospace - if there is no room in the schedule; skipped - if the request is not considered due to moon or rank. NOTE: the first field of the nospace and


skipped

fields is the Universal time of transit.

SOCKET COMMANDS

There are several different commands that can be transmitted to insgen via the INSERV socket. The command which fires up the program and makes it enter new request files is the following.

newreqs xxx.rqs yyy.rqs .... Where the multiple arguments list the request file names (with extension but no path) which are to be found in the directory $HOME_DIR/targets. After insgen reads them it returns the line to the socket.

done newreqs accepted=xx skipped=yy rejected=zz

Stating how many requests fell into the three possible categories. Note: if a request file has a reqid (filename stripped of path and extension) that matches one already accepted by insgen the previous entries are removed from memory before the new one is added.

shutdown command causes insgen to to exit the loop and perform the procedure morning.csh.

interrupt command causes insgen to stop normal observations until it receives the resume command. Other commands can be executed while the interrupt in in progress. Interrupts terminate at the shutdown time.

help command lists the possible commands.

remove command removes the listed reqid(s) (i.e filenames stripped of their extensions) from the list of targets.

mark command sets the status flag on the specified reqid(s) to STAT_ERROR. This command is useful to notify insgen of requests that may have failed after background processing.

unmark command sets the status flag on the specified reqid(s) to STAT_SELECTED.

manual command causes the specified request files to be executed next, ignoring all scheduling constraints and checks.

conditions [seeing=] [extinct=] [use_conditions=] command updates the internal real time values of the seeing and extinction. Requests can ask that they only be executed under conditions of good seeing and high transparency. See the CONDITIONS section for more details.

CONDITIONS

insgen keeps track of the current seeing and extinction as floating point variables. They are set by the Socket commands usually by the procedure dostandards. At startup the values are set to 50 arc-seconds and 100 magnitudes. If the request file values exceed these values, then the observation is skipped on this cycle. The condition testing can be turned on and off by the use_conditions flag. If this flag is 0, then condition testing is ignored. It is important to make sure that the standard star, bias, openup and closedowns requests are scheduled with a value of extinction of 100, so that they will be executed regardless.

DEBUGGING

The sim flag turns on a fictitious clock takes the place of the system clock, so that an entire night's performance can be shown in a few minutes. Instead of invoking telco or other scripts it calls a telescope simulator which attempts to model the actual telescope time between objects. For each stanza in the request file prints out targets, the simulator prints out a message for each target like:

01:33:27 telcosim -4.603 5.874 1.18 0.00   171    164 34

Where the first field is the Universal time, the third and fourth are the ha and dec at the time of observation in decimal degrees. The fifth and sixth are the secz of observation and secz-transit_secz. The eighth field is the dome azimuth. The ninth is the observation (telescope + image) time and the tenth field is the telescope move time in seconds.

The makelist causes insgen to write the file `insgen.makelist' which contains lines like:

sn39 84.64 selected 12:23:21 1610 -123 0 NGC4162

Where the first field is the rqs file name (minus extension and path), the second field is the rank. The third is the status and can be either selected or nospace. The fourth is the Universal time of the jd_best, the fifth is the observation time. The sixth field lists the difference between time the observation has been scheduled band the best time. The seventh file is the amount (if any) that the target been pushed.

The noupdate option disable the updating of DAYLAST, UTLAST and NUM-OBS of the request file. Use this option when testing insgen.

OPTIONS

DD/MM/YYYY: causes the given date to be used as the basis for scheduling, rather than the system date (also turns on sim).

sim: allows use in a simulated mode.

list: prints the current list to the file `insgen.list'.

listonly: Reads the first socket command, prints the list of targets (to insgen.list) and exits; it doesn't actually run telco or the simulator.

makelist: prints a cumulative list of the rankings and differences between the `best' time and the actual scheduled times. This file is `insgen.makelist' and can grow to be quite large.

fail=: allows the simulated telco process to fail depending on the floating point number entered. A value of 1.0 will cause all observations to return non-zero exit codes. It also turns on the sim flag.

nopush: turns off the pushing feature of the list generation process.