org.orekit.time
Class AbsoluteDate

java.lang.Object
  org.orekit.time.AbsoluteDate

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<AbsoluteDate>, TimeStamped

public class AbsoluteDate
extends java.lang.Object
implements TimeStamped, java.lang.Comparable<AbsoluteDate>, java.io.Serializable

This class represents a specific instant in time.

Instances of this class are considered to be absolute in the sense that each one represent the occurrence of some event and can be compared to other instances or located in any time scale. In other words the different locations of an event with respect to two different time scale (say TAI and UTC for example) are simply different perspective related to a single object. Only one AbsoluteDate instance is needed, both representations being available from this single instance by specifying the time scales as parameter when calling the ad-hoc methods.

Since an instance is not bound to a specific time-scale, all methods related to the location of the date within some time scale require to provide the time scale as an argument. It is therefore possible to define a date in one time scale and to use it in another one. An example of such use is to read a date from a file in UTC and write it in another file in TAI. This can be done as follows:

   DateTimeComponents utcComponents = readNextDate();
   AbsoluteDate date = new AbsoluteDate(utcComponents, TimeScalesFactory.getUTC());
   writeNextDate(date.getComponents(TimeScalesFactory.getTAI()));
 

Two complementary views are available:

• location view (mainly for input/output or conversions)

  locations represent the coordinate of one event with respect to a time scale. The related methods are AbsoluteDate(DateComponents, TimeComponents, TimeScale), AbsoluteDate(int, int, int, int, int, double, TimeScale), AbsoluteDate(int, int, int, TimeScale), AbsoluteDate(Date, TimeScale), createGPSDate(int, double), toString()toDate(TimeScale), toString(timeScale), toString(), and timeScalesOffset(org.orekit.time.TimeScale, org.orekit.time.TimeScale).

• offset view (mainly for physical computation)

  offsets represent either the flow of time between two events (two instances of the class) or durations. They are counted in seconds, are continuous and could be measured using only a virtually perfect stopwatch. The related methods are AbsoluteDate(AbsoluteDate, double), durationFrom(AbsoluteDate), compareTo(AbsoluteDate), equals(Object) and hashCode().

A few reference epochs which are commonly used in space systems have been defined. These epochs can be used as the basis for offset computation. The supported epochs are: JULIAN_EPOCH, MODIFIED_JULIAN_EPOCH, FIFTIES_EPOCH, GPS_EPOCH, J2000_EPOCH, JAVA_EPOCH. In addition to these reference epochs, two other constants are defined for convenience: PAST_INFINITY and FUTURE_INFINITY, which can be used either as dummy dates when a date is not yet initialized, or for initialization of loops searching for a min or max date.

Instances of the AbsoluteDate class are guaranteed to be immutable.

Version:

$Revision:1665 $ $Date:2008-06-11 12:12:59 +0200 (mer., 11 juin 2008) $

Author:

Luc Maisonobe

See Also:

TimeScale, TimeStamped, ChronologicalComparator, Serialized Form

Field Summary

static AbsoluteDate	FIFTIES_EPOCH Reference epoch for 1950 dates: 1950-01-01T00:00:00.
static AbsoluteDate	FUTURE_INFINITY Dummy date at infinity in the future direction.
static AbsoluteDate	GPS_EPOCH Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
static AbsoluteDate	J2000_EPOCH J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (not UTC).
static AbsoluteDate	JAVA_EPOCH Java Reference epoch: 1970-01-01T00:00:00 TT.
static AbsoluteDate	JULIAN_EPOCH Reference epoch for julian dates: -4712-01-01T12:00:00.
static AbsoluteDate	MODIFIED_JULIAN_EPOCH Reference epoch for modified julian dates: 1858-11-17T00:00:00.
static AbsoluteDate	PAST_INFINITY Dummy date at infinity in the past direction.

Constructor Summary

AbsoluteDate()
Create an instance with a default value (J2000_EPOCH).

AbsoluteDate(AbsoluteDate since, double elapsedDuration)
Build an instance from an elapsed duration since to another instant.

AbsoluteDate(AbsoluteDate reference, double apparentOffset, TimeScale timeScale)
Build an instance from an apparent clock offset with respect to another instant in the perspective of a specific time scale.

AbsoluteDate(DateComponents date, TimeComponents time, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(DateComponents date, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(DateTimeComponents location, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(java.util.Date location, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(int year, int month, int day, int hour, int minute, double second, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(int year, int month, int day, TimeScale timeScale)
Build an instance from a location in a time scale.

AbsoluteDate(java.lang.String location, TimeScale timeScale)
Build an instance from a location (parsed from a string) in a time scale.

Method Summary

int	compareTo(AbsoluteDate date) Compare the instance with another date.
static AbsoluteDate	createGPSDate(int weekNumber, double milliInWeek) Build an instance corresponding to a GPS date.
double	durationFrom(AbsoluteDate instant) Compute the physically elapsed duration between two instants.
boolean	equals(java.lang.Object date) Check if the instance represent the same time as another instance.
DateTimeComponents	getComponents(TimeScale timeScale) Split the instance into date/time components.
AbsoluteDate	getDate() Get the date.
int	hashCode() Get a hashcode for this date.
double	offsetFrom(AbsoluteDate instant, TimeScale timeScale) Compute the apparent clock offset between two instant in the perspective of a specific time scale.
AbsoluteDate	shiftedBy(double dt) Get a time-shifted date.
double	timeScalesOffset(TimeScale scale1, TimeScale scale2) Compute the offset between two time scales at the current instant.
java.util.Date	toDate(TimeScale timeScale) Convert the instance to a Java Date.
java.lang.String	toString() Get a String representation of the instant location in UTC time scale.
java.lang.String	toString(TimeScale timeScale) Get a String representation of the instant location.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

JULIAN_EPOCH

public static final AbsoluteDate JULIAN_EPOCH

Reference epoch for julian dates: -4712-01-01T12:00:00.

Both java.util.Date and DateComponents classes follow the astronomical conventions and consider a year 0 between years -1 and +1, hence this reference date lies in year -4712 and not in year -4713 as can be seen in other documents or programs that obey a different convention (for example the convcal utility).

MODIFIED_JULIAN_EPOCH

public static final AbsoluteDate MODIFIED_JULIAN_EPOCH

Reference epoch for modified julian dates: 1858-11-17T00:00:00.

FIFTIES_EPOCH

public static final AbsoluteDate FIFTIES_EPOCH

Reference epoch for 1950 dates: 1950-01-01T00:00:00.

GPS_EPOCH

public static final AbsoluteDate GPS_EPOCH

Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.

J2000_EPOCH

public static final AbsoluteDate J2000_EPOCH

J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (not UTC).

JAVA_EPOCH

public static final AbsoluteDate JAVA_EPOCH

Java Reference epoch: 1970-01-01T00:00:00 TT.

PAST_INFINITY

public static final AbsoluteDate PAST_INFINITY

Dummy date at infinity in the past direction.

FUTURE_INFINITY

public static final AbsoluteDate FUTURE_INFINITY

Dummy date at infinity in the future direction.

Constructor Detail

AbsoluteDate

public AbsoluteDate()

Create an instance with a default value (J2000_EPOCH).

AbsoluteDate

public AbsoluteDate(java.lang.String location,
                    TimeScale timeScale)

Build an instance from a location (parsed from a string) in a time scale.

The supported formats for location are mainly the ones defined in ISO-8601 standard, the exact subset is explained in DateTimeComponents.parseDateTime(String), DateComponents.parseDate(String) and TimeComponents.parseTime(String).

Parameters:

location - location in the time scale, must be in a supported format

timeScale - time scale

Throws:

java.lang.IllegalArgumentException - if location string is not in a supported format

AbsoluteDate

public AbsoluteDate(DateTimeComponents location,
                    TimeScale timeScale)

Build an instance from a location in a time scale.

Parameters:

location - location in the time scale

timeScale - time scale

AbsoluteDate

public AbsoluteDate(DateComponents date,
                    TimeComponents time,
                    TimeScale timeScale)

Build an instance from a location in a time scale.

Parameters:

date - date location in the time scale

time - time location in the time scale

timeScale - time scale

AbsoluteDate

public AbsoluteDate(int year,
                    int month,
                    int day,
                    int hour,
                    int minute,
                    double second,
                    TimeScale timeScale)
             throws java.lang.IllegalArgumentException

Build an instance from a location in a time scale.

Parameters:

year - year number (may be 0 or negative for BC years)

month - month number from 1 to 12

day - day number from 1 to 31

hour - hour number from 0 to 23

minute - minute number from 0 to 59

second - second number from 0.0 to 60.0 (excluded)

timeScale - time scale

Throws:

java.lang.IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

AbsoluteDate

public AbsoluteDate(DateComponents date,
                    TimeScale timeScale)
             throws java.lang.IllegalArgumentException

Build an instance from a location in a time scale.

The hour is set to 00:00:00.000.

Parameters:

date - date location in the time scale

timeScale - time scale

Throws:

java.lang.IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

AbsoluteDate

public AbsoluteDate(int year,
                    int month,
                    int day,
                    TimeScale timeScale)
             throws java.lang.IllegalArgumentException

Build an instance from a location in a time scale.

The hour is set to 00:00:00.000.

Parameters:

year - year number (may be 0 or negative for BC years)

month - month number from 1 to 12

day - day number from 1 to 31

timeScale - time scale

Throws:

java.lang.IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

AbsoluteDate

public AbsoluteDate(java.util.Date location,
                    TimeScale timeScale)

Build an instance from a location in a time scale.

Parameters:

location - location in the time scale

timeScale - time scale

AbsoluteDate

public AbsoluteDate(AbsoluteDate since,
                    double elapsedDuration)

Build an instance from an elapsed duration since to another instant.

It is important to note that the elapsed duration is not the difference between two readings on a time scale. As an example, the duration between the two instants leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the UTC time scale is not 1 second, but a stop watch would have measured an elapsed duration of 2 seconds between these two instances because a leap second was introduced at the end of 2005 in this time scale.

This constructor is the reverse of the durationFrom(AbsoluteDate) method.

Parameters:

since - start instant of the measured duration

elapsedDuration - physically elapsed duration from the since instant, as measured in a regular time scale

See Also:

durationFrom(AbsoluteDate)

AbsoluteDate

public AbsoluteDate(AbsoluteDate reference,
                    double apparentOffset,
                    TimeScale timeScale)

Build an instance from an apparent clock offset with respect to another instant in the perspective of a specific time scale.

It is important to note that the apparent clock offset is the difference between two readings on a time scale and not an elapsed duration. As an example, the apparent clock offset between the two instants leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the UTC time scale is 1 second, but the elapsed duration is 2 seconds because a leap second has been introduced at the end of 2005 in this time scale.

This constructor is the reverse of the offsetFrom(AbsoluteDate, TimeScale) method.

Parameters:

reference - reference instant

apparentOffset - apparent clock offset from the reference instant (difference between two readings in the specified time scale)

timeScale - time scale with respect to which the offset is defined

See Also:

offsetFrom(AbsoluteDate, TimeScale)

Method Detail

createGPSDate

public static AbsoluteDate createGPSDate(int weekNumber,
                                         double milliInWeek)

Build an instance corresponding to a GPS date.

GPS dates are provided as a week number starting at GPS epoch and as a number of milliseconds since week start.

Parameters:

weekNumber - week number since GPS epoch

milliInWeek - number of milliseconds since week start

Returns:

a new instant

shiftedBy

public AbsoluteDate shiftedBy(double dt)

Get a time-shifted date.

Calling this method is equivalent to call new AbsoluteDate(this, dt).

Parameters:

dt - time shift in seconds

Returns:

a new date, shifted with respect to instance (which is immutable)

See Also:

PVCoordinates.shiftedBy(double), Attitude.shiftedBy(double), Orbit.shiftedBy(double), SpacecraftState.shiftedBy(double)

durationFrom

public double durationFrom(AbsoluteDate instant)

Compute the physically elapsed duration between two instants.

The returned duration is the number of seconds physically elapsed between the two instants, measured in a regular time scale with respect to surface of the Earth (i.e either the TAI scale, the TT scale or the GPS scale). It is the only method that gives a duration with a physical meaning.

This method gives the same result (with less computation) as calling offsetFrom(AbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

This method is the reverse of the AbsoluteDate(AbsoluteDate, double) constructor.

Parameters:

instant - instant to subtract from the instance

Returns:

offset in seconds between the two instants (positive if the instance is posterior to the argument)

See Also:

offsetFrom(AbsoluteDate, TimeScale), AbsoluteDate(AbsoluteDate, double)

offsetFrom

public double offsetFrom(AbsoluteDate instant,
                         TimeScale timeScale)

Compute the apparent clock offset between two instant in the perspective of a specific time scale.

The offset is the number of seconds counted in the given time scale between the locations of the two instants, with all time scale irregularities removed (i.e. considering all days are exactly 86400 seconds long). This method will give a result that may not have a physical meaning if the time scale is irregular. For example since a leap second was introduced at the end of 2005, the apparent offset between 2005-12-31T23:59:59 and 2006-01-01T00:00:00 is 1 second, but the physical duration of the corresponding time interval as returned by the durationFrom(AbsoluteDate) method is 2 seconds.

This method is the reverse of the AbsoluteDate(AbsoluteDate, double, TimeScale) constructor.

Parameters:

instant - instant to subtract from the instance

timeScale - time scale with respect to which the offset should be computed

Returns:

apparent clock offset in seconds between the two instants (positive if the instance is posterior to the argument)

See Also:

durationFrom(AbsoluteDate), AbsoluteDate(AbsoluteDate, double, TimeScale)

timeScalesOffset

public double timeScalesOffset(TimeScale scale1,
                               TimeScale scale2)

Compute the offset between two time scales at the current instant.

The offset is defined as l₁-l₂ where l₁ is the location of the instant in the scale1 time scale and l₂ is the location of the instant in the scale2 time scale.

Parameters:

scale1 - first time scale

scale2 - second time scale

Returns:

offset in seconds between the two time scales at the current instant

toDate

public java.util.Date toDate(TimeScale timeScale)

Convert the instance to a Java Date.

Conversion to the Date class induces a loss of precision because the Date class does not provide sub-millisecond information. Java Dates are considered to be locations in some times scales.

Parameters:

timeScale - time scale to use

Returns:

a Date instance representing the location of the instant in the time scale

getComponents

public DateTimeComponents getComponents(TimeScale timeScale)

Split the instance into date/time components.

Parameters:

timeScale - time scale to use

Returns:

date/time components

compareTo

public int compareTo(AbsoluteDate date)

Compare the instance with another date.

Specified by:

compareTo in interface java.lang.Comparable<AbsoluteDate>

Parameters:

date - other date to compare the instance to

Returns:

a negative integer, zero, or a positive integer as this date is before, simultaneous, or after the specified date.

getDate

public AbsoluteDate getDate()

Get the date.

Specified by:

getDate in interface TimeStamped

Returns:

date attached to the object

equals

public boolean equals(java.lang.Object date)

Check if the instance represent the same time as another instance.

Overrides:

equals in class java.lang.Object

Parameters:

date - other date

Returns:

true if the instance and the other date refer to the same instant

hashCode

public int hashCode()

Get a hashcode for this date.

Overrides:

hashCode in class java.lang.Object

Returns:

hashcode

toString

public java.lang.String toString()

Get a String representation of the instant location in UTC time scale.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the instance, in ISO-8601 format with milliseconds accuracy

toString

public java.lang.String toString(TimeScale timeScale)

Get a String representation of the instant location.

Parameters:

timeScale - time scale to use

Returns:

a string representation of the instance, in ISO-8601 format with milliseconds accuracy