Voir la source de User Manual 3.4.1 Time

__NOTOC__ 
== Introduction ==
=== Scope ===
Despite its current use, time requires careful attention in the description of physical phenomena. Indeed the rate at which time passes has to be accurate in order to guarantee the best physical description of a phenomenon. To that purpose several time scales have been set up and with the introduction of atomic clocks, more accurate time scales have been defined.

=== Javadoc ===
The object related with dates and time scales are available in the package <code>org.orekit.time</code> of OREKIT.
{| class="wikitable"
|-
! scope="col"| Library
! scope="col"| Javadoc
|-
|Orekit
|[{{JavaDoc3.4.1}}/org/orekit/time/package-summary.html Package org.orekit.time]
|-
|Orekit addons
|[{{JavaDoc3.4.1}}/org/orekit/utils/package-summary.html Package org.orekit.utils]
|}


=== Links ===
''Orekit Time architecture description'', [http://procyon.cst.cnes.fr/mvnsites/1_0_1/orekit/architecture/time.html Orekit site].

=== Useful Documents ===
None as of now.

=== Package Overview ===
[[File:timeOrekit.JPG]]

This package overview is from the OREKIT website, under apache license.

== Features Description ==
=== OREKIT Dates ===
In Orekit, the class <code>AbsoluteDate</code> represents a specific instant in time. There are different ways to create a date :

* for instance, one way is to give the date with a calendar form (year, month and day as 3 integers or as a <code>DateComponents</code> object) and a time scale : <code>AbsoluteDate(int, int, int, TimeScale)</code> or <code>AbsoluteDate(DateComponents, TimeScale)</code>
* to be more precise the informations of the hour, the minute and the second can be added : <code>AbsoluteDate(int, int, int, int, int, double, TimeScale)</code> or <code>AbsoluteDate(DateComponents, TimeComponents, TimeScale)</code>
NB : a DateComponents object represents a date broken up as year, month and day ; a TimeComponents object represents a day broken up as hour, minute and second.
* another way is to give a predefined date and an elapsed duration from this date : <code>AbsoluteDate(AbsoluteDate, double)</code>

{{warning|For advanced users only : a constructor <code>AbsoluteDate(long, double)</code> is available. It uses as parameters an "epoch" and an "offset", which are in fact the attributes of AbsoluteDate. These attributes have no meaning outside of AbsoluteDate, and are not meant to be exposed or manipulated directly by regular users. This constructor was added for the purpose of creating AbsoluteDate instances very quickly from a static storage (apart from serialization) and without loss of precision. Getters for "epoch" and "offset" are also available for this purpose.'''Use at your own risk!'''}}

As for the time scale, OREKIT counts 10 different time scales among which the TAI scale (International Atomic Time), the TT scale (Terrestrial Time), the UT1 scale (Universal Time), the UTC scale (Coordinated Universal Time)... The creation of a time scale is done through the <code>TimeScalesFactory</code> as follows : <code>TimeScale scale = TimeScalesFactory.getTT();</code>

Some reference epochs are directly available, for instance :

* J2000 epoch (2000-01-01T12:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.J2000_EPOCH;</code>
* julian epoch (-4712-01-01T12:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.JULIAN_EPOCH;</code>
* fifties epoch (CNES julian dates origin, 1950-01-01T00:00:00) in TT scale : <code>AbsoluteDate date = AbsoluteDate.FIFTIES_EPOCH_TT;</code>
* fifties epoch (CNES julian dates origin) in UTC scale : <code>AbsoluteDate date = AbsoluteDate.FIFTIES_EPOCH_UTC;</code>
* Java Reference epoch (1970-01-01T00:00:00) in UTC scale : <code>AbsoluteDate date = AbsoluteDate.JAVA_EPOCH;</code>
* ...

=== Time Interval ===
This implementation for This implementation for time intervals, <code>AbsoluteDateInterval</code>, uses the Orekit <code>AbsoluteDate</code> class as the endpoint value type.

Infinite endpoints ( <code>AbsoluteDate.PAST_INFINITY</code> and <code>AbsoluteDate.FUTURE_INFINITY</code> ) are supported, but as open endpoints only. Empty intervals are also forbidden.

This implementation extends the class <code>ComparableInterval</code>, inheriting the following operations: 

* check if two intervals are equal:
<code> boolean equal = interval.equals(Object) </code>

* check if two intervals overlap:
<code> boolean overlaps = interval.overlaps(ComparableInterval<T>) </code>

* check if the interval includes another interval:
<code> boolean includes = interval.includes(ComparableInterval<T>) </code>

* check if the interval is connected to another interval (its lower point coincides with the upper point of the input interval, and one point is closed and the other open):
<code> boolean connected = interval.isConnectedTo(ComparableInterval<T>) </code>

* compare the lower end point with the lower end point of another interval:
<code> int compare = interval.compareLowerEndTo(ComparableInterval<T>) </code>

* compare the upper end point with the upper end point of another interval:
<code> int compare = interval.compareUpperEndTo(ComparableInterval<T>) </code>

In addition to inherited capabilities, the class can also:

* compute the duration of the interval in seconds (as computed in a regular timescale - the duration has a physical meaning):
<code> double duration = interval.getDuration() </code>

* compute the duration between intervals in seconds (that is : the duration between the end of the earlier interval and the beginning of the later one):
<code> double duration = interval.durationFrom(AbsoluteDateInterval nextInterval) </code>

* merge the interval with another interval if possible (the intervals must overlap or be connected to be merged):
<code> AbsoluteDateInterval mergedInterval = interval.mergeTo(AbsoluteDateInterval) </code>

* get the intersection between two intervals when overlapping:
<code> AbsoluteDateInterval intersection = interval.getIntersectionWith(AbsoluteDateInterval) </code>

* compare the duration of an interval with the duration of another interval:
<code> int compare = interval.compareDurationTo(AbsoluteDateInterval) </code>

==== List of time intervals ====

The class <code>AbsoluteDateIntervalsList</code> represents a list of time intervals (whose elements are <code>AbsoluteDateInterval</code> instances).
As <code>AbsoluteDateInterval</code> objects implement the <code>Comparable</code> interface via the class <code>ComparableInterval</code>, the time intervals in the list are automatically ordered by their lower/upper dates. 

<syntaxhighlight lang="java">
        final AbsoluteDateIntervalsList list = new AbsoluteDateIntervalsList();
        IntervalEndpointType open = IntervalEndpointType.OPEN;
        IntervalEndpointType closed = IntervalEndpointType.CLOSED;
        // set up the time intervals to add:
        final AbsoluteDateInterval i1 = new AbsoluteDateInterval(open, date1, date2, closed);
        final AbsoluteDateInterval i2 = new AbsoluteDateInterval(closed, date1, date3, open);      
        list.add(i1);
        list.add(i2);
</syntaxhighlight>

In addition to the methods inherited from the <code>TreeSet</code> class, <code>AbsoluteDateIntervalsList</code> can also:

* tell which time intervals in the list contain a predetermined date:<br><code>  AbsoluteDateIntervalsList  intervals = list.getIntervalsContainingDate(date) </code>

* compute the shortest interval containing all the intervals belonging to the list:<br><code>  AbsoluteDateInterval inclusiveInterval = list.getInclusiveInterval(); </code>

* compute the list of complementary intervals of the given intervals list:<br><code>  AbsoluteDateIntervalsList complementaryList = list.getComplementaryIntervals(); </code>

Please see the Javadoc for more information.

=== Local time and solar time ===
Local time is represented by the angle between the projections of the Earth-Sun vector and the Earth-Spacecraft vector in the equatorial plane. Local time is expressed in hours and its value is 12h when this angle is 0 rad. Beware, in PATRIUS, local time is always expressed as an angle in the range [-PI; PI[ and always represents the angle between the projections of the Earth-Sun vector and the Earth-Spacecraft vector in the equatorial plane. If one wants to retrieve local time (in hours) from the local time angle provided by PATRIUS, the following formula should be used:

<center>Local time = 12h + local time angle* 12 / Pi.</center>

Local time increases for prograde orbits and decreases for retrograde orbits.

Similarly, solar time is represented by the angle between the Earth-Sun projection in the orbital plane and the Earth-Spacecraft vector. Solar time is expressed in hours and its value is 12h when this angle is 0 rad. Beware, in PATRIUS, solar time is always expressed as an angle in the range [-PI; PI[ and always represents the angle between the Earth-Sun projection in the orbital plane and the Earth-Spacecraft vector. If one wants to retrieve solar time (in hours) from the solar time angle provided by PATRIUS, the following formula should be used:

<center>Solar time = 12h + solar time angle* 12 / Pi.</center>

Solar time always increases with time. It is mesured around the orbit momentum.

The class <code>LocalTimeAngle</code> provides methods to compute:
* True local time angle using <code>computeTrueLocalTimeAngle()</code>. Local time is always computed in TIRF frame. True local time is represented by the angle between projection of satellite position and Sun position over the equatorial plane in provided frame. Returned time is expressed in seconds in the range [-PI; PI[.
* Mean local time angle using <code>computeMeanLocalTimeAngle()</code>. Local time angle is always computed in TIRF frame. Mean local time is the difference between true local time and equation of time (EOT):

<center><math>Mean local time = True local time + EOT</math></center>

* Equation of time using <code>computeEquationOfTime()</code>:

Equation of time is true local time of GMST ([0; 0; 1] vector in TIRF frame) minus seconds in the date:


<center><math>EOT =-(Local time GMST - sec)</math></center>

Equation of time is periodic over one year in the range [-16min; +14min]:

[[File:EquationOfTime.png|center]]

== Getting Started ==
==== AbsoluteDateInterval ====

Here is given a code example on how to use the <code>AbsoluteDateInterval</code>:

<syntaxhighlight lang="java">
        final AbsoluteDate t1 = new AbsoluteDate("1969-11-03", TimeScalesFactory.getTT());
        final AbsoluteDate t2 = new AbsoluteDate("1969-11-04", TimeScalesFactory.getTT());
        final AbsoluteDate t3 = new AbsoluteDate("1969-11-06", TimeScalesFactory.getTT());
        final AbsoluteDate t4 = new AbsoluteDate("1969-11-07", TimeScalesFactory.getTT());
        final IntervalEndpointType open = IntervalEndpointType.OPEN;
        final double dayInSeconds = Constants.JULIAN_DAY;
        // Two separated intervals, two days of separation :
        // ..] t1 ; t2 [....] t3 ; t4 [..
        final AbsoluteDateInterval ad1A = new AbsoluteDateInterval(open, t1, t2, open);
        final AbsoluteDateInterval ad1B = new AbsoluteDateInterval(open, t3, t4, open);
        final double dur11 = ad1B.durationFrom(ad1A);
        final double dur12 = ad1A.durationFrom(ad1B);
        // ad1B begins 2 days after ad1A ends : duration from is + 2 days
        Assert.assertEquals(2.* dayInSeconds, dur11, 0.);
        // ad1A ends 2 days before ad1B begins : duration from is- 2 days
        Assert.assertEquals(-2.* dayInSeconds, dur12, 0.);
</syntaxhighlight>


== Contents ==
=== Interfaces ===
{| class="wikitable"
|-
! scope="col"| Interface
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''TimeScale'''
|Interface for time scales.
|[{{JavaDoc3.4.1}}/org/orekit/time/TimeScale.html ...]
|-
|'''TimeStamped'''
|This interface represents objects that have a AbsoluteDate  date attached to them.
|[{{JavaDoc3.4.1}}/org/orekit/time/TimeStamped.html ...]
|}


=== Classes ===
{| class="wikitable"
|-
! scope="col"| Class
! scope="col"| Summary
! scope="col"| Javadoc
|-
|'''AbsoluteDate'''
|This class represents a specific instant in time.
|[{{JavaDoc3.4.1}}/org/orekit/time/AbsoluteDate.html ...]
|-
|'''AbsoluteDateInterval'''
|This class implements an interval based on the AbsoluteDate class.
|[{{JavaDoc3.4.1}}/org/orekit/utils/AbsoluteDateInterval.html ...]
|-
|'''AbsoluteDateIntervalsList'''
|This class represents a list of AbsoluteDateInterval objects.
|[{{JavaDoc3.4.1}}/org/orekit/utils/AbsoluteDateIntervalsList.html ...]
|-
|'''ChronologicalComparator'''
|Comparator for TimeStamped instance.
|[{{JavaDoc3.4.1}}/org/orekit/time/ChronologicalComparator.html ...]
|-
|'''ComparableInterval'''
|Class describing an interval of Comparable data.
|[{{JavaDoc3.4.1}}/org/orekit/utils/ComparableInterval.html ...]
|-
|'''DateComponents'''
|Class representing a date broken up as year, month and day components.
|[{{JavaDoc3.4.1}}/org/orekit/time/DateComponents.html ...]
|-
|'''DateTimeComponents'''
|Holder for date and time components.
|[{{JavaDoc3.4.1}}/org/orekit/time/DateTimeComponents.html ...]
|-
|'''GalileoScale'''
|Galileo system time scale.
|[{{JavaDoc3.4.1}}/org/orekit/time/GalileoScale.html ...]
|-
|'''GenericInterval'''
|Generic class to describe an interval.
|[{{JavaDoc3.4.1}}/org/orekit/utils/GenericInterval.html ...]
|-
|'''GMSTScale'''
|Greenwich Mean Sidereal Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/GMSTScale.html ...]
|-
|'''GPSScale'''
|GPS time scale.
|[{{JavaDoc3.4.1}}/org/orekit/time/GPSScale.html ...]
|-
|'''TAIScale'''
|International Atomic Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/TAIScale.html ...]
|-
|'''TCBScale'''
|Barycentric Coordinate Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/TCBScale.html ...]
|-
|'''TCGScale'''
|Geocentric Coordinate Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/TCGScale.html ...]
|-
|'''TDBScale'''
|Barycentric Dynamic Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/TDBScale.html ...]
|-
|'''TimeComponents'''
|Class representing a time within the day broken up as hour, minute and second components.
|[{{JavaDoc3.4.1}}/org/orekit/time/TimeComponents.html ...]
|-
|'''TimeScalesFactory'''
|Factory for predefined time scales.
|[{{JavaDoc3.4.1}}/org/orekit/time/TimeScalesFactory.html ...]
|-
|'''TTScale'''
|Terrestrial Time as defined by IAU(1991) recommendation IV.
|[{{JavaDoc3.4.1}}/org/orekit/time/TTScale.html ...]
|-
|'''UT1Scale'''
|Universal Time 1.
|[{{JavaDoc3.4.1}}/org/orekit/time/UT1Scale.html ...]
|-
|'''UTCScale'''
|Coordinated Universal Time.
|[{{JavaDoc3.4.1}}/org/orekit/time/UTCScale.html ...]
|}

== Tutorials ==
=== Tutorial 1 ===
[Tutoriels_Flight_Dynamics.Dates Tutoriel sur les dates]

[[Category:User_Manual_3.4.1_Flight_Dynamics]]