insgen command

NAME

insgen - scheduler for automatic telescopes

SYNOPSIS

insgen [debug[=]..] [avoid=] [nomoon] [nogenerate] [nopublish] [nosort] [iso=] [database=] [import] [reqid=]...

DESCRIPTION

insgen generates the telescope schedule. When invoked, insgen reads the current system time (unless iso is specified) and, depending on the command line options, reads requests from the database. It then estimates how long each request will take to observe and the optimum time to observe it.

insgen then uses a least cost insertion algorithm to make the decisions to generate a schedule of observations and publish the results in the Database.

You may want to also read about the insgen DETAILS or look at the Messier marathon.

PRELIMINARIES

When invoked, insgen does the following:

Reads system clock unless overridden by the iso command line option
Reads the telescope server to determine telescope location and limits (tel_status)
Reads the telescope server to determine CCD readout speeds (ccd_status)
Sets all Request.ReasonBad to NULL (unless nopublish)
Clears the Schedule table (unless nopublish)
Calculate moon position phase for local midnight

READING THE REQUESTS

insgen reads the entries in the Request table of the database joining with others (Target and Picture) as needed. Contrary to earlier versions, insgen requires all parameters such as Request.Interval, Request.Twilight etc to be specified in the database rather than relying on internal default values.

Requests may be entered by:

entered en masse by using the import option
specifying their RequestIDs directly with the reqid= option (which may be repeated)

THE IMPORT OPTION

The import accepts active Requests where active means either:

Request.Count > Request.NumberDone
Request.Count == NULL

Requests where Request.Count = 0 are expired and are no longer considered.

It then goes through the Log table and skips Requests that have either:

failed in the past 1.5 hours (Log.Success==0)
succeeded in the past Request.Interval hours (Log.Success==1)

The first time can be changed by the avoid command line option.

The second part involving the Interval is a bit complex see the discussion below on short interval observations.

THE REQID OPTION

Requests can also be specified by reading them individually by specifying their RequestIDs using the reqid= option. They are read in the order as they appear on the command line but they will be sorted before scheduling unless the nosort option is specified.

The success and failure checks mentioned above do not apply when using the reqid= command line option.

REJECTED REQUESTS

As each request is read insgen makes some tests on the correctness of the request. If errors are detected, an entry is made to the Request table in the database with the Request.ReasonBad column set to non NULL value. This is different than skipping them as Rejected requests can never be scheduled. Here are the reasons that a request may be rejected:

no request found - specified RequestID not found
no Xxxx - parameter Xxxx is NULL in the database
north limit - declination too big
south limit - declination too small
altitude limit - always below airmass or telescope alt limit
no UTStart, SunStart or Coordinate - can't find window
no obstime - can't determine observing time
UTStart not HMS - non sexagesimal format
no RA found - scheduled by Transit but RA missing
no Dec found - scheduled by Transit but Dec missing
both UTStart and SunStart - pick one or the other

BLOCK TIME

insgen needs to know the time it will take to execute the request (BlockTime). If Request.ObsTime is not NULL, it uses that figure (in seconds). Otherwise it generates an estimate by taking the sum of the following:

exposure time of all Pictures for all Targets
CCD readout time taking into account binning factor
guess at telescope move time from the number of Targets
guess at guider acquisition time
overhead (fudge)

The CCD readout time is taken from the server using the ccd server and the ccd_status command. The constants in the program to calculate the above have been adjusted to get reasonable agreement with reality.

The BlockTime in seconds is published in Schedule.BlockTime.

OBSERVATION WINDOWS

There are three ways an observation may be scheduled:

Transit
UTStart - a particular Universal time (or range deliminted by commas)
SunStart - a particular sun altitude (or range deliminted by commas)

insgen defines time windows to figure out when to schedule observations. A window consists of a start time and length. For all cases there are two important windows:

BEST - the ideal time to start the observation and length BlockTime
VISIBLE - the earliest time it is possible to start the observation till the latest time to start

For the Transit case insgen determines following four windows.

BEST : the window for which the midpoint of the observation is the time of group transits and lasts as long as the observation.
UP: the window during which all of the targets in the request are above Request.Airmass and are with the telescope limits.
NIGHT: the window when the sun is below the specified Request.Twilight value.
VISIBLE: is the intersection of the UP and NIGHT windows.

Note: the BEST window may or may not be within the VISIBLE window.

The UTStart case occurs if Request.UTStart is not NULL,

BEST begins at the specified Universal time and lasts the the BlockTime
UP and VISIBLE is the same as BEST

The SunStart case occurs if Request.SunStart is not NULL,

BEST begins when the sun sets to the requested altitude and lasts the BlockTime
UP and VISIBLE is the same as BEST

If the length of the VISIBLE window is less than the BlockTime, the observation is skipped.

SHORT INTERVAL OBSERVATIONS

If the Request.Interval is shorter than the the VISBILE window, the window is chopped into smaller VISIBLE windows each with its own BEST spot.

insgen will use only the sub window that who's end time is soonest after the present time. When insgen is run at a later time, the later windows will be scheduled. The interaction with telco will hopefull cause the target to be observed every Request.Interval seconds.

HANDLING THE MOON

insgen considers the moon in the scheduling of requests when scheduled by Transit. For simplicity, the coordinates and phase of the moon are calculated only at midnight.

The observation will be skipped if either of the following are true:

the current phase of the moon is greater than the Request.MoonPhase
any of the targets in the request are closer than the number of degrees specified by Request.MoonDistance

If Request.UTStart or Request.SunStart are used to schedule the request, or if insgen is run with the nomoon option, the request will be scheduled regardless of the moon.

SCHEDULING

Once insgen has read the requests for the current night and calculated the observing windows it sorts the list using the following criteria:

Request.Priority (bigger is better)
if priority is same then transit time (farther from midnight is better)

Sorting can be disabled by using the nosort command line option.

insgen attempts to generate a schedule where each object is observed as close to its ideal time as possible. The list is then generated by taking each request and trying each of the following steps :

at its BEST window if available and it is within VISIBLE

the time closest to the BEST window yet within the VISIBLE window

pushes the other already scheduled observations to earlier or later times that will remain consistent with their VISIBLE windows and inserts request within its VISIBLE window so the Cost is a minimum

Cost is defined as the sum of the squares of the time displacement of the requests pushed.

If the request cannot be scheduled with any of the three methods, it is skipped.

SKIPPING

There are several reasons a request may not be scheduled on a given night and will be skipped. When this occurs Schedule.StartTime will be NULL and that Schedule.Reason will have one of the following values:

nospace - too many observations in front of it
window too short - the target is not up long enough to observe
not up tonight - never up during nighttime
too close to the moon - moon distance less than Request.Moondist
done recently - if the request has been done in the Request.Interval (import only)
failed x.x hours ago" - recently failed (import only)

PROGRAM OUTPUT

Used without debugging options, arguments the output is something like this:

2009-12-27T23:47:37Z insgen
reqid=00138 REJECTED altitude limit
reqid=00140 REJECTED altitude limit
...
reqid=00179 SKIPPED too close to moon 10
reqid=00164 SKIPPED not up tonight
reqid=00207 SKIPPED not up tonight
reqid=00206 SKIPPED not up tonight
...
reqid=00191 START=2009-12-28T02:03:10Z   340 M57
reqid=00190 START=2009-12-28T02:08:50Z   340 M56
reqid=00205 START=2009-12-28T02:14:30Z   340 M71
reqid=00161 START=2009-12-28T02:20:10Z   340 M27

The first is the ISO time that the schedule was created. This is followed by three blocks: The first block are the rejected requests. The second block, the skipped and the final are the scheduled requests. The reasons for rejection and skipping are stated after the request ID. The last block is for the scheduled requests listing the start time, block time and name respectively.

PUBLISHING RESULTS

Having generated a list, insgen clear then writes the following information in the Schedule table.

Schedule.UpStart- the DateTime of the beginning of UP window
Schedule.UpEnd- the DateTime of the end of UP window
Schedule.BestStart- the DateTime of the beginning of BEST window
Schedule.BestEnd- the DateTime of the end of BEST window
Schedule.NightStart- the DateTime of the beginning of NIGHT window
Schedule.NightEnd- the DateTime of the end of NIGHT window
Schedule.StartTime- best starting time (NULL if not scheduled)
Schedule.BlockTime- calculated length of observation in seconds
Schedule.Reason- the reason for omitting observation from the schedule (NULL if scheduled)

LIMITATIONS AND BUGS

The least cost algorithm is an approximation not an ideal method to solving the minimization problem.

insgen is a bit erratic about scheduling objects that have two observing windows during the night.

No optimization of declination nor dome moves is made. Only hour angle positioning is treated.

When used with short intervals, only one observation will appear scheduled during the night.

PROGRAM OPTIONS

avoid= sets the time delay (in seconds) after a requests fails that it is not read using the import option. The default value is 5400 seconds. A value of 0 disables this feature. It has no effect when the reqid option is used.

debug= setting the value to the OR'ed combination of the following leads yields even more output. Repeating the statement may lead to even more debug output

#define DEBUG_REQUEST   0x01
#define DEBUG_GROUP     0x02
#define DEBUG_QUERY     0x04
#define DEBUG_COORD     0x08
#define DEBUG_LIST      0x10
#define DEBUG_CLOCK     0x20
#define DEBUG_SERVER    0x40

You can preface the value with "0x" for hexadecimal.

debug - uses a debug value that varies depending on what I was attempting to inspect when it was last compiled.

import - queries the Request table in the database for active requests. See above for definition.

iso= sets the clock to the ISO8601 time rather than the current time. ISO time is of the format YYYY-MM-DDTHH:MM:SSZ. For example: 2009-12-27T23:47:37Z.

nomoon- does not do the moon avoidance algorithm.

nogenerate - doesn't generate the list, just reads the requests.

nopublish - reads the requests, generates the list but doesn't update the database Window, Schedule and Skipped tables.

nosort - doesn't sort the input requests as discussed above. Instead the order specified on the command line using reqid='s or import is used.

reqid= queries the Request table as above but only for the requests submitted by specified RequestID. Multiple instances of this option can be put on the command line.

EXAMPLES

The usual way insgen is invoked (say by insgenlog):

insgen import

For testing you might like to see the calls to the database and information about the group windows but not actually re-run them.

insgen nopublish debug=0x06 import

For testing some of the details of three requests.

insgen nopublish debug reqid=370 reqid=395 reqid=4444 nosort

Program index