Time Conventions

← Previous topic: Directory Naming Conventions | Next topic: Common Variable Names →

Argus measurement capabilities require good control of time and space. While spatial control and image geometry solution occupies a lot of research focus, understanding time standards is also very important. Argus must be accurate to small fractions of a second in order to be synchronous with other instruments and must be organized in a way that works for decades over multiple time zones.

Common time standards might be local time, matlab's datenum, and epoch time.

The time standard adopted by the CIL has been epoch time, the number of seconds past 12:00 am, January 1, 1970, in the GMT time zone. For example epoch time 1424646004 corresponds to 23:00:04, 22 Feb, 2015 GMT. This was adopted from the Unix community and is a broadly accepted standard. There are several reasons for this choice.

• Stations are operated across multiple time zones or may be controlled by a computer in a different time zone than the station,
• the choice of time standard should not change for daylight savings time. GMT is always GMT
• epoch time values currently have 10 digits, so can be conveniently used as an integer in CIL file naming conventions and is, in fact, a key to many time search functions in CIL routines. Datenum expresses fractional days and could not be as easily incorporated in file naming algorithms.

There are actually two uses for time in Argus work. The first is when producing data products at the remote station, where the collection program is responsible for knowing how to create epoch times. The other is in Matlab processing "back home". For a very long time, Matlab was completely ignorant of time zones, knowing only the "current time" of the system it was running on. The "now" function returns a datenum IN LOCAL TIME. If you execute the following code in Matlab, using CIL functions:

epoch2GMTString(matlab2Epoch(now))

you will get a string that says it is GMT but is the current local time. For many years, the CIL had a MEX function called "epochtime" that was intended to provide the true Unix epoch time using the Unix system calls designed to provide that. The fun of maintaining MEX code across OS and Matlab versions forced us into a approximation where "epochtime" was calculated from "now" by adding a timezone offset managed by a local configuration file. That, of course, meant you needed to manage the timezone offset and "epochtime" would be wrong.

There is a better way, today. The java API in Matlab allows access to an object called "java.util.Date". One of the member functions of Date is "getTime", which returns the java epoch time. Java epoch time is the time in milliseconds since 00:00 Jan. 1, 1970 GMT. I.e., 1000 times Unix epoch time. The latest version of the CIL epochtime.m function is now:

function time = epochtime()
poo = javaObject('java.util.Date');
time = floor(poo.getTime/1000);

Very simple. And right.

That said, epoch time is often inconvenient for matlab analysis and display. Thus routines are supplied to convert to and from datenum. These are epoch2Matlab and matlab2Epoch. Note that true Unix epoch time is an integer, and matlab2Epoch follows that standard by flooring the epoch time it returns.

← Previous topic: Directory Naming Conventions | Next topic: Common Variable Names →