where:
VLBI Software Documentation
Field System
setcl: FS Time Model Control
W. E. Himwich
NVI, Inc./GSFC
User Guide
NASA/Goddard Space Flight Center Version 9.3
Space Geodesy Program September 1, 1997
The setcl program is used to model the error in the FS computer clock relative to UT. This is
necessary for two reasons: (1) the FS computer does not know the UT time when it boots, it only
has the approximate time maintained by a CMOS clock, and (2) once set at boot, the computer
clock runs at a precise but inaccurate rate typically gaining or losing a few seconds per day
depending on the PC.
To correct for these problems, the setcl program is designed to measure differences between
the computer time and the formatter (Mark III, Mark IV, VLBA, or S2 recorder) time. It uses
these differences to calculate a clock model consisting of an offset and a rate. This model is then
used to estimate the formatter time from the computer time. The FS uses this estimated time,
rather than the computer time, for all its functions.
In the examples used in this document, the syntax for running setcl is given within an
sy=run setl & SNAP command. Once the FS is running, setcl may also be run from a
shell prompt by typing run setcl The output only appears in the log. All files discussed in this
document are located in the /usr2/control directory if the full pathname is not stated.
2.0 Normal Operation
The setcl program can only be used when the FS is running. Normally it should only be run in
the initi SNAP procedure using the command:
sy=run setcl &
This will determine the offset between the FS computer and the formatter, if no offset has been
determined since the last boot. If an offset has already been determined, information about
current time will be reported, but the offset will not be changed. The program operates in this
way, so that by default, it will develop as long a time history of the clock offset as possible, even
when the FS is repeatedly stopped and restarted. See the Log Output section for a description of
the reported information.
Normally the model rate would be the a priori value from the control file time.ctl. If the rate
in this file is not accurate it can be updated, see the Set-up section. Typically the rate is stable to
within a few hundredths of a second per day. If a well determined a priori value is in use, the
clock offset should not need to be updated after it has been measured.
In order to avoid integer arithmetic overflow problems, it is recommended that the computer
clock be kept within a few minutes of the correct time and that the PC should be re-booted at
least once a month.
3.0 Checking the Clock Accuracy
The accuracy of the clock model can be checked by manually entering the command:
sy=run setcl &
or by typing Control-Shift-S or selecting Setcl from the operator's menu, if the window
menus are set-up in the default way. Assuming the clock offset has already been determined, for
example, by a similar command in the initi SNAP procedure, this command will report the
difference between the current clock model and the formatter. This command does not disturb the
existing clock model in any way. It merely provides a check on the accuracy of the current
model.
See the Log Output section for details about the output. The last parameter on the time record is
the most immediately useful. It gives the difference between the current FS modeled time and the
formatter time in hundredths of a second. If things are working correctly, the absolute value of
this number would be less than 10.
There are two situations in which it is appropriate to update the model. The first of these is when
the rate being used is inaccurate. Normally, the rate is read from the time.ctl control file. If
the rate has never been determined for a particular computer or it was determined over a short
time period, it may need to be updated. To update the rate, enter the command:
sy=run setcl rate &
This command will update the rate based on the amount of drift between the current Clock
Model and the formatter time. Note that this will not update the rate if the new estimate would be
less precise that the one currently in use. The precision is stated in terms of how many hours
(span) the rate was measured over. The rate will not be updated unless the new estimate comes
from a measurement span longer than was used to determine the current one. For example, if the
rate in the time.ctl file has a span specified as 24 hours, it will be not be possible to update
the rate if the current span is less than 24 hours. If a new rate measurement is desired
immediately, the span in the time.ctl file may be manually reduced to a small value, say
0.0001, and the FS restarted. It will then be possible to update the rate with whatever the current
span is.
The other situation in which the model must be updated is if the formatter time is changed. This
might occur if the formatter was reset before running a test experiment. In this case the offset
needs to be updated, but not the rate. After changing the formatter time, the FS clock offset can
be updated by using the command:
sy=run setcl offset &
This will update only the clock offset. The rate is assumed to not have changed.
5.0 Saving the Clock Rate Information
Once the rate has been determined, it can saved in a control file. When the FS is restarted, this
file is read in. Thus once the rate has been determined, only a measurement of the offset is
necessary each time the computer is booted. To save the current rate information, use the
command:
sy=run setcl save &
With this command the most recently measured rate and its span are written to the file time.new, overwriting any previous contents of this file. If this file is then renamed to time.ctl it will be used as input the next time the FS is started. Note that the offset information isn't and doesn't need to be saved. The offset information depends on when the system was booted and is retained by the FS until the next boot or
sy=run setcl offset & command.
6.0 Setting the Computer Clock
If the computer time, as opposed to the FS time, is in error by a large amount of time, possibly
several hours, the setcl program can be used to reset the computer clock. Use the command:
sy=run setcl cpu &
In this case the system time is reset to the nearest whole second and the time offset between the computer and the formatter is automatically remeasured (an implicit
sy=run setcl offset & occurs).
7.0 Log Output
There are two types of log output records from the setcl program. The time record displays the
current time information determined from the formatter and the computer clock. The model
record contains information about the clock model. The time record has the form:
#setcl#time/centisecs,window,year,doy,hour,minute,second,new_rate,new_span,error
where:
centisecs elapsed time since the last boot (centiseconds of computer time), this is the average of computer times before and after formatter time was sampled.
window difference in computer times measured before and after sampling the formatter time (centiseconds)
year year reported by formatter, for Mark III formatters the century and decade are obtained from the equip.ctl file
doy day of year reported by the formatter
hour hour of day reported by the formatter
minute minute of hour reported by formatter
second second of minute reported by formatter, with centisecond precision
new_rate the rate that would result if it were calculated now (seconds/day), positive if the computer clock runs slow
new_span the time interval over which new_rate was calculated (hours)
error residual difference between formatter time and modeled FS time (centiseconds), the
residual should be added to the FS model to get the formatter time
The other log output record is the model record, which records information about the current
model:
#setcl#model/age,secs,offset,epoch,rate,span,type
where:
age old or new, old indicates that this is the existing model, new indicates that this is an updated model
secs time of the CMOS clock at the last re-boot in seconds since January 1, 1970, 0 hours UT
offset difference between the formatter and computer time (centiseconds) at epoch, add the value to the computer time to get the formatter time
epoch time of the offset measurement in centiseconds since the last boot
rate clock rate difference between the computer and the formatter (seconds/day), positive if the computer runs slow
span the time interval over which rate was measured (hours)
type model being used: none, offset, or rate
A time and model/old record are output for every measurement. A model/new record is
also output if the model is updated.
8.0 Set-up
To install setcl follow these steps:
(1) Put the command:
sy=run setcl &
in the initi procedure of the station procedure library. Generally speaking this command
should go near the beginning of the procedure. For systems with a VLBA DAR, the procedure
vlbainit or the command form=addr should proceed this command to make sure that the
formatter's address is set. With this command in the initi procedure, setcl will be run
automatically every time the FS is started. The first time the FS is run after a re-boot, this will
measure the formatter-computer offset. If there are any commands in initi that relay on time
references involving exclamation marks, such as wx@!,5m, it would be desirable to put them
after the command that runs setcl with perhaps a 5 second delay (!+5S) after the running of
setcl.
(2) Measure the drift rate of the computer clock. The longer the time span the rate is measured
over, up to a few days, the better. The minimum useful span is about one hour, which will
determine the rate to about one second per day. A span of at least one day is recommended.
Measuring the rate is very easy. After starting the FS, execute the command:
sy=run setcl rate &
at least one hour after the last time the offset was updated. Note that the rate will not be updated
until at least as long a span as was used for the current rate has passed. You can monitor the time
by issuing the command
sy=run setcl &
or entering Control-Shift-S if the default window menus are installed. The next to last
parameter on the time log entry from setcl gives the number of hours since the last offset
measurement. The second to last parameter gives an estimate of the rate that would be calculated
at the present time. The rate and clock information can be monitored this way as often as desired.
In fact, once you determine a rate, it is useful to make several checks, so that you can be sure that
the rate you measured is reasonable. You might have gotten an erroneous measurement due, for
example, to a communications error.
Once you are satisfied with the rate value, you can save it by issuing the command:
sy=run setcl save &
This will write the rate and span information into the file time.new. You can rename (mv) the
file to time.ctl so that the next time the FS starts it will use this value for its a priori rate.
If you did happen to get an outlier when you measured the rate, or if you want to determine a
more precise rate, you can run setcl with the rate parameter again. You can continue to do
this repeatedly, even after restarting the FS, with no loss of precision as long as you don't reset
the formatter or computer time, reboot the computer, or update the offset.
9.0 Algorithms
The way time is handled within the FS is controlled by what is available from the operating
system. The primary pieces of information are: the system time measured in seconds since
January 1, 1970, 0 hours UT, and the centiseconds since the system was booted.
The time difference between the formatter and the computer is kept in two parts: (1) the computer time of the last boot, and (2) the modeled offset and drift rate of the computer clock relative to the formatter. The former is back calculated using the current system time and the centiseconds since the last boot. This is only done on the first FS start after a reboot or if the cpu option of setcl is used to reset the computer time. The modeled offset and rate are applied to the centiseconds since the last boot. The FS time is calculated as:
where:
The offset is calculated using the raw computer time and the formatter time for one epoch:
The rate is calculated by using the offsets calculated from two different epochs:
The "zero" epoch is the epoch of the first measured offset.
When the formatter time is read, the computer time is sampled immediately before and after the
communication that retrieves, or in some cases latches, the time to be retrieved. The before and
after computer times define a "window" within which the retrieved time was sampled. Because
of overhead in the serial card driver, this window is always at least about two or three
centiseconds wide. This is true even when using 9600 BAUD and the required communication
has been reduced to a bare minimum of two characters (one sent to initiate latching and one
received to acknowledge the latching). The driver overhead appears to be the limiting uncertainty
in the measurement. For simplicity the computer time that corresponds to the retrieved time is
assumed to be the average of the before and after samples.
Because of the limited size of "long" integers, the clock model will fail if any of following
quantities exceeds about 248 days (231-1 hundredths of seconds actually): (1) the difference
between the computer and formatter times, (2) the elapsed time since the last boot, or (3) either
the offset or the rate contribution to the clock correction. Normally this shouldn't be a problem.
10.0 Command Parameter Summary
Up to one command line parameter may be specified for each invocation of setcl. The
behavior when no parameters are provided is described below as (NULL). The command line
parameters recognized by setcl are:
cpu set the computer clock and remeasure the offset
offset update the clock offset
rate update the rate if new rate is more precise than the current
save write the current rate and span information to time.new
(NULL) measure the current offset if none has been measured, otherwise just report on the
current time and model
The time.ctl file control resides in the /usr2/control directory. The description of this
file is also found in the Control Files manual.
Records starting with asterisks (*) are comments. This file contains one data record with three
fields:
rate span model
where:
rate the computer a priori clock drift rate (seconds/day), positive values indicate that the computer runs more slowly than the formatter
span period over which the rate was determined (hours)
model model to use for correcting the computer clock: none, offset, or rate
The default control file, /usr2/fs/st.default/control/time.ctl, has zero rate, a
span of 1 hour, and a model parameter of rate. The default file is listed here as an example:
* rate (seconds/day) span (hours) model (none/offset/rate)
0.000 1.000 rate