ULTRACAM times

The times generated by the pipeline comes from the routine ultracam/src/read_header.cc. In principle this should be a simple process but has become complicated owing to various bugs in early versions of the GPS timestamp code.

The aim is to generate a UT date and time corresponding to the middle of the exposure. The GPS time stamp gives the number of seconds from the start of the week (defined as midnight on the saturday/sunday transition) and the number of nanoseconds in addition to this (i.e this lies in the range 0 to 999999999. It also gives a date. So the standard is to add whatever seconds are left after removal of integer*86400 + nanoseconds/1e9 to the date.

This is by no means all there is to do, because to correct to the middle of the exposure then depends upon the readout mode. However before getting to this point there are several special cases:

May 2002 run This run had no date information, and so the known start of week date (12 May 2002) is used to offset from. There was moreover an error where some times jumped back by 10 seconds. This is corrected by seeing if a time is less than an earlier one. I don't think this ever causes problems, but could do if it is the first frame of all that is wrong. Luckily it is usually a fairly short lived problem.
The first night of the May 2002 run had a short vertical clock time that caused the nasty "peppering" effect on the CCD. The parameter VCLOCK_FRAME is set specially for this night. The vclock_frame was not stored in the XML in this run so known numbers are used for all nights of this run (these are needed for the correaction to the mid-point of the exposures).

September 2002 run From the second night of this run we had date information. Unfortunately the year was not always right and so special code fixes this to 2002. On top of this day numbers were only correct to within 1 day, changing incorrectly near midnight They are therefore used to identify the week in question, and then the number of seconds is used as in the May 2002 case.

No GPS mode With no GPS one can still get relative times from the computer. These are indicated by the number of satellites = -1. The date is then set to an arbitrary 1 Jan 2000 (i.e. before ULTRACAM started) and the number of seconds etc is added to it. The number of seconds however is now from the start of loading the software and therefore does not mean anything in absolute terms.

Midnight bug Data taken near UT midnight can suffer from the following problem: the number of seconds indicates that the date has changed, but the date itself has yet to update. This perhaps reflects some sort of offset in the polling time for the date versus the time. I now correct for these by comparing the say of the week implied by the number of seconds with the day of the week implied by the GPS date. If these differ, 1 day is added to the GPS date. A warning is issued.

Correcting the times for the readout mode

Once the GPS time has been processed as above, it needs to be corrected to the mid-exposure time. This is a function of the readout mode. In some cases one must have read the time of the frame before to make this correction, or even several frames before. (drift mode) If this is not possible (e.g. first frame or frames) the time will be flagged as being not OK (NOK). NB. If nsat=-1, the time may still be flagged as "OK" which it is as far as the exposure correction, but not otherwise.

Here are the possibilities:

FULLFRAME_CLEAR
FULLFRAME_OVERSCAN In these modes we simply add half the exposure time to the GPS time from above. No previous frames needed, the time are always OK.

FULLFRAME_NOCLEAR
WINDOWS These are the most common options. In this case an estimate is made from the frame transfer vertical clock to correct the first frame, otherwise the previous frame is used to get the most accurate time. If there is no previous frame and it is not the first frame, then the same correction used for the first frame is applied, but the time is marked NOK, although it may be quite good in reality.

DRIFT This is the most copmplex because we have to store several previous frame times as the time attached to a set of data actually applies to data that will be read out in several frames time. The routine therefore keeps a list of times, and only once this is filled can times be set properly. Thus the first few time in drift mode are rubbish.
The main difficulty here is the synchronisation of timestamp with data. I think I have got it right but it has yet to be proven that I have, so watch out for offsets of 1 or 2 exposure times.

For full details, you will need to look at the code itself, but the above information may give you an indication of where there may be problems.

Tom Marsh, Warwick

May 2002 run	This run had no date information, and so the known start of week date (12 May 2002) is used to offset from. There was moreover an error where some times jumped back by 10 seconds. This is corrected by seeing if a time is less than an earlier one. I don't think this ever causes problems, but could do if it is the first frame of all that is wrong. Luckily it is usually a fairly short lived problem. The first night of the May 2002 run had a short vertical clock time that caused the nasty "peppering" effect on the CCD. The parameter VCLOCK_FRAME is set specially for this night. The vclock_frame was not stored in the XML in this run so known numbers are used for all nights of this run (these are needed for the correaction to the mid-point of the exposures).
September 2002 run	From the second night of this run we had date information. Unfortunately the year was not always right and so special code fixes this to 2002. On top of this day numbers were only correct to within 1 day, changing incorrectly near midnight They are therefore used to identify the week in question, and then the number of seconds is used as in the May 2002 case.
No GPS mode	With no GPS one can still get relative times from the computer. These are indicated by the number of satellites = -1. The date is then set to an arbitrary 1 Jan 2000 (i.e. before ULTRACAM started) and the number of seconds etc is added to it. The number of seconds however is now from the start of loading the software and therefore does not mean anything in absolute terms.
Midnight bug	Data taken near UT midnight can suffer from the following problem: the number of seconds indicates that the date has changed, but the date itself has yet to update. This perhaps reflects some sort of offset in the polling time for the date versus the time. I now correct for these by comparing the say of the week implied by the number of seconds with the day of the week implied by the GPS date. If these differ, 1 day is added to the GPS date. A warning is issued.

FULLFRAME_CLEAR FULLFRAME_OVERSCAN	In these modes we simply add half the exposure time to the GPS time from above. No previous frames needed, the time are always OK.
FULLFRAME_NOCLEAR WINDOWS	These are the most common options. In this case an estimate is made from the frame transfer vertical clock to correct the first frame, otherwise the previous frame is used to get the most accurate time. If there is no previous frame and it is not the first frame, then the same correction used for the first frame is applied, but the time is marked NOK, although it may be quite good in reality.
DRIFT	This is the most copmplex because we have to store several previous frame times as the time attached to a set of data actually applies to data that will be read out in several frames time. The routine therefore keeps a list of times, and only once this is filled can times be set properly. Thus the first few time in drift mode are rubbish. The main difficulty here is the synchronisation of timestamp with data. I think I have got it right but it has yet to be proven that I have, so watch out for offsets of 1 or 2 exposure times.