1   /* Copyright 2002-2019 CS Systèmes d'Information
2    * Licensed to CS Systèmes d'Information (CS) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * CS licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *   http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.orekit.time;
18  
19  import java.io.Serializable;
20  import java.util.List;
21  
22  import org.hipparchus.RealFieldElement;
23  import org.orekit.errors.OrekitException;
24  import org.orekit.errors.OrekitInternalError;
25  import org.orekit.utils.Constants;
26  
27  /** Coordinated Universal Time.
28   * <p>UTC is related to TAI using step adjustments from time to time
29   * according to IERS (International Earth Rotation Service) rules. Before 1972,
30   * these adjustments were piecewise linear offsets. Since 1972, these adjustments
31   * are piecewise constant offsets, which require introduction of leap seconds.</p>
32   * <p>Leap seconds are always inserted as additional seconds at the last minute
33   * of the day, pushing the next day forward. Such minutes are therefore more
34   * than 60 seconds long. In theory, there may be seconds removal instead of seconds
35   * insertion, but up to now (2010) it has never been used. As an example, when a
36   * one second leap was introduced at the end of 2005, the UTC time sequence was
37   * 2005-12-31T23:59:59 UTC, followed by 2005-12-31T23:59:60 UTC, followed by
38   * 2006-01-01T00:00:00 UTC.</p>
39   * <p>This is intended to be accessed thanks to the {@link TimeScalesFactory} class,
40   * so there is no public constructor.</p>
41   * @author Luc Maisonobe
42   * @see AbsoluteDate
43   */
44  public class UTCScale implements TimeScale {
45  
46      /** Serializable UID. */
47      private static final long serialVersionUID = 20150402L;
48  
49      /** UTC-TAI offsets. */
50      private UTCTAIOffset[] offsets;
51  
52      /** Package private constructor for the factory.
53       * Used to create the prototype instance of this class that is used to
54       * clone all subsequent instances of {@link UTCScale}. Initializes the offset
55       * table that is shared among all instances.
56       * @param offsetModels UTC-TAI offsets
57       */
58      UTCScale(final List<OffsetModel> offsetModels) {
59  
60          if (offsetModels.get(0).getStart().getYear() > 1968) {
61              // the pre-1972 linear offsets are missing, add them manually
62              // excerpt from UTC-TAI.history file:
63              //  1961  Jan.  1 - 1961  Aug.  1     1.422 818 0s + (MJD - 37 300) x 0.001 296s
64              //        Aug.  1 - 1962  Jan.  1     1.372 818 0s +        ""
65              //  1962  Jan.  1 - 1963  Nov.  1     1.845 858 0s + (MJD - 37 665) x 0.001 123 2s
66              //  1963  Nov.  1 - 1964  Jan.  1     1.945 858 0s +        ""
67              //  1964  Jan.  1 -       April 1     3.240 130 0s + (MJD - 38 761) x 0.001 296s
68              //        April 1 -       Sept. 1     3.340 130 0s +        ""
69              //        Sept. 1 - 1965  Jan.  1     3.440 130 0s +        ""
70              //  1965  Jan.  1 -       March 1     3.540 130 0s +        ""
71              //        March 1 -       Jul.  1     3.640 130 0s +        ""
72              //        Jul.  1 -       Sept. 1     3.740 130 0s +        ""
73              //        Sept. 1 - 1966  Jan.  1     3.840 130 0s +        ""
74              //  1966  Jan.  1 - 1968  Feb.  1     4.313 170 0s + (MJD - 39 126) x 0.002 592s
75              //  1968  Feb.  1 - 1972  Jan.  1     4.213 170 0s +        ""
76              offsetModels.add( 0, new OffsetModel(new DateComponents(1961,  1, 1), 37300, 1.4228180, 0.0012960));
77              offsetModels.add( 1, new OffsetModel(new DateComponents(1961,  8, 1), 37300, 1.3728180, 0.0012960));
78              offsetModels.add( 2, new OffsetModel(new DateComponents(1962,  1, 1), 37665, 1.8458580, 0.0011232));
79              offsetModels.add( 3, new OffsetModel(new DateComponents(1963, 11, 1), 37665, 1.9458580, 0.0011232));
80              offsetModels.add( 4, new OffsetModel(new DateComponents(1964,  1, 1), 38761, 3.2401300, 0.0012960));
81              offsetModels.add( 5, new OffsetModel(new DateComponents(1964,  4, 1), 38761, 3.3401300, 0.0012960));
82              offsetModels.add( 6, new OffsetModel(new DateComponents(1964,  9, 1), 38761, 3.4401300, 0.0012960));
83              offsetModels.add( 7, new OffsetModel(new DateComponents(1965,  1, 1), 38761, 3.5401300, 0.0012960));
84              offsetModels.add( 8, new OffsetModel(new DateComponents(1965,  3, 1), 38761, 3.6401300, 0.0012960));
85              offsetModels.add( 9, new OffsetModel(new DateComponents(1965,  7, 1), 38761, 3.7401300, 0.0012960));
86              offsetModels.add(10, new OffsetModel(new DateComponents(1965,  9, 1), 38761, 3.8401300, 0.0012960));
87              offsetModels.add(11, new OffsetModel(new DateComponents(1966,  1, 1), 39126, 4.3131700, 0.0025920));
88              offsetModels.add(12, new OffsetModel(new DateComponents(1968,  2, 1), 39126, 4.2131700, 0.0025920));
89          }
90  
91          // create cache
92          offsets = new UTCTAIOffset[offsetModels.size()];
93  
94          UTCTAIOffset previous = null;
95  
96          // link the offsets together
97          final TimeScale tai = TimeScalesFactory.getTAI();
98          for (int i = 0; i < offsetModels.size(); ++i) {
99  
100             final OffsetModel    o      = offsetModels.get(i);
101             final DateComponents date   = o.getStart();
102             final int            mjdRef = o.getMJDRef();
103             final double         offset = o.getOffset();
104             final double         slope  = o.getSlope();
105 
106             // start of the leap
107             final double previousOffset    = (previous == null) ? 0.0 : previous.getOffset(date, TimeComponents.H00);
108             final AbsoluteDateDate">AbsoluteDate leapStart   = new AbsoluteDate(date, tai).shiftedBy(previousOffset);
109 
110             // end of the leap
111             final double startOffset       = offset + slope * (date.getMJD() - mjdRef);
112             final AbsoluteDateDate">AbsoluteDate leapEnd     = new AbsoluteDate(date, tai).shiftedBy(startOffset);
113 
114             // leap computed at leap start and in UTC scale
115             final double normalizedSlope   = slope / Constants.JULIAN_DAY;
116             final double leap              = leapEnd.durationFrom(leapStart) / (1 + normalizedSlope);
117 
118             previous = new UTCTAIOffset(leapStart, date.getMJD(), leap, offset, mjdRef, normalizedSlope);
119             offsets[i] = previous;
120 
121         }
122 
123     }
124 
125     /** {@inheritDoc} */
126     @Override
127     public double offsetFromTAI(final AbsoluteDate date) {
128         final int offsetIndex = findOffsetIndex(date);
129         if (offsetIndex < 0) {
130             // the date is before the first known leap
131             return 0;
132         } else {
133             return -offsets[offsetIndex].getOffset(date);
134         }
135     }
136 
137     /** {@inheritDoc} */
138     @Override
139     public <T extends RealFieldElement<T>> T offsetFromTAI(final FieldAbsoluteDate<T> date) {
140         final int offsetIndex = findOffsetIndex(date.toAbsoluteDate());
141         if (offsetIndex < 0) {
142             // the date is before the first known leap
143             return date.getField().getZero();
144         } else {
145             return offsets[offsetIndex].getOffset(date).negate();
146         }
147     }
148 
149     /** {@inheritDoc} */
150     @Override
151     public double offsetToTAI(final DateComponents date,
152                               final TimeComponents time) {
153 
154         // take offset from local time into account, but ignoring seconds,
155         // so when we parse an hour like 23:59:60.5 during leap seconds introduction,
156         // we do not jump to next day
157         final int minuteInDay = time.getHour() * 60 + time.getMinute() - time.getMinutesFromUTC();
158         final int correction  = minuteInDay < 0 ? (minuteInDay - 1439) / 1440 : minuteInDay / 1440;
159 
160         // find close neighbors, assuming date in TAI, i.e a date earlier than real UTC date
161         final int mjd = date.getMJD() + correction;
162         final UTCTAIOffset offset = findOffset(mjd);
163         if (offset == null) {
164             // the date is before the first known leap
165             return 0;
166         } else {
167             return offset.getOffset(date, time);
168         }
169 
170     }
171 
172     /** {@inheritDoc} */
173     public String getName() {
174         return "UTC";
175     }
176 
177     /** {@inheritDoc} */
178     public String toString() {
179         return getName();
180     }
181 
182     /** Get the date of the first known leap second.
183      * @return date of the first known leap second
184      */
185     public AbsoluteDate getFirstKnownLeapSecond() {
186         return offsets[0].getDate();
187     }
188 
189     /** Get the date of the last known leap second.
190      * @return date of the last known leap second
191      */
192     public AbsoluteDate getLastKnownLeapSecond() {
193         return offsets[offsets.length - 1].getDate();
194     }
195 
196     /** {@inheritDoc} */
197     @Override
198     public boolean insideLeap(final AbsoluteDate date) {
199         final int offsetIndex = findOffsetIndex(date);
200         if (offsetIndex < 0) {
201             // the date is before the first known leap
202             return false;
203         } else {
204             return date.compareTo(offsets[offsetIndex].getValidityStart()) < 0;
205         }
206     }
207 
208     /** {@inheritDoc} */
209     @Override
210     public <T extends RealFieldElement<T>> boolean insideLeap(final FieldAbsoluteDate<T> date) {
211         return insideLeap(date.toAbsoluteDate());
212     }
213 
214     /** {@inheritDoc} */
215     @Override
216     public int minuteDuration(final AbsoluteDate date) {
217         final int offsetIndex = findOffsetIndex(date);
218         if (offsetIndex < 0) {
219             // the date is before the first known leap
220             return 60;
221         } else {
222             if (date.compareTo(offsets[offsetIndex].getValidityStart()) < 0) {
223                 // the date is during the leap itself
224                 return 61;
225             } else {
226                 // the date is after a leap, but it may be just before the next one
227                 if (offsetIndex + 1 < offsets.length &&
228                     offsets[offsetIndex + 1].getDate().durationFrom(date) <= 60.0) {
229                     // the next leap will start in one minute, it will extend the current minute
230                     return 61;
231                 } else {
232                     // no leap is expected within the next minute
233                     return 60;
234                 }
235             }
236         }
237     }
238 
239     /** {@inheritDoc} */
240     @Override
241     public <T extends RealFieldElement<T>> int minuteDuration(final FieldAbsoluteDate<T> date) {
242         return minuteDuration(date.toAbsoluteDate());
243     }
244 
245     /** {@inheritDoc} */
246     @Override
247     public double getLeap(final AbsoluteDate date) {
248         final int offsetIndex = findOffsetIndex(date);
249         if (offsetIndex < 0) {
250             // the date is before the first known leap
251             return 0;
252         } else {
253             return offsets[offsetIndex].getLeap();
254         }
255     }
256 
257     /** {@inheritDoc} */
258     @Override
259     public <T extends RealFieldElement<T>> T getLeap(final FieldAbsoluteDate<T> date) {
260         return date.getField().getZero().add(getLeap(date.toAbsoluteDate()));
261     }
262 
263     /** Find the index of the offset valid at some date.
264      * @param date date at which offset is requested
265      * @return index of the offset valid at this date, or -1 if date is before first offset.
266      */
267     private int findOffsetIndex(final AbsoluteDate date) {
268         int inf = 0;
269         int sup = offsets.length;
270         while (sup - inf > 1) {
271             final int middle = (inf + sup) >>> 1;
272             if (date.compareTo(offsets[middle].getDate()) < 0) {
273                 sup = middle;
274             } else {
275                 inf = middle;
276             }
277         }
278         if (sup == offsets.length) {
279             // the date is after the last known leap second
280             return offsets.length - 1;
281         } else if (date.compareTo(offsets[inf].getDate()) < 0) {
282             // the date is before the first known leap
283             return -1;
284         } else {
285             return inf;
286         }
287     }
288 
289     /** Find the offset valid at some date.
290      * @param mjd Modified Julian Day of the date at which offset is requested
291      * @return offset valid at this date, or null if date is before first offset.
292      */
293     private UTCTAIOffset findOffset(final int mjd) {
294         int inf = 0;
295         int sup = offsets.length;
296         while (sup - inf > 1) {
297             final int middle = (inf + sup) >>> 1;
298             if (mjd < offsets[middle].getMJD()) {
299                 sup = middle;
300             } else {
301                 inf = middle;
302             }
303         }
304         if (sup == offsets.length) {
305             // the date is after the last known leap second
306             return offsets[offsets.length - 1];
307         } else if (mjd < offsets[inf].getMJD()) {
308             // the date is before the first known leap
309             return null;
310         } else {
311             return offsets[inf];
312         }
313     }
314 
315     /** Replace the instance with a data transfer object for serialization.
316      * @return data transfer object that will be serialized
317      */
318     private Object writeReplace() {
319         return new DataTransferObject();
320     }
321 
322     /** Internal class used only for serialization. */
323     private static class DataTransferObject implements Serializable {
324 
325         /** Serializable UID. */
326         private static final long serialVersionUID = 20131209L;
327 
328         /** Replace the deserialized data transfer object with a {@link UTCScale}.
329          * @return replacement {@link UTCScale}
330          */
331         private Object readResolve() {
332             try {
333                 return TimeScalesFactory.getUTC();
334             } catch (OrekitException oe) {
335                 throw new OrekitInternalError(oe);
336             }
337         }
338 
339     }
340 
341 }