1 /* Copyright 2002-2024 CS GROUP
2 * Licensed to CS GROUP (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
21 import org.hipparchus.CalculusFieldElement;
22 import org.orekit.utils.Constants;
23
24 /** Offset between {@link UTCScale UTC} and {@link TAIScale TAI} time scales.
25 * <p>The {@link UTCScale UTC} and {@link TAIScale TAI} time scales are two
26 * scales offset with respect to each other. The {@link TAIScale TAI} scale is
27 * continuous whereas the {@link UTCScale UTC} includes some discontinuity when
28 * leap seconds are introduced by the <a href="http://www.iers.org/">International
29 * Earth Rotation Service</a> (IERS).</p>
30 * <p>This class represents the offset between the two scales that is
31 * valid between two leap seconds occurrences. It handles both the linear offsets
32 * used from 1961-01-01 to 1971-12-31 and the constant integer offsets used since
33 * 1972-01-01.</p>
34 * @author Luc Maisonobe
35 * @see UTCScale
36 * @see UTCTAIHistoryFilesLoader
37 */
38 public class UTCTAIOffset implements TimeStamped, Serializable {
39
40 /** Serializable UID. */
41 private static final long serialVersionUID = 4742190573136348054L;
42
43 /** Leap date. */
44 private final AbsoluteDate leapDate;
45
46 /** Leap date in Modified Julian Day. */
47 private final int leapDateMJD;
48
49 /** Offset start of validity date. */
50 private final AbsoluteDate validityStart;
51
52 /** Reference date for the slope multiplication as Modified Julian Day. */
53 private final int mjdRef;
54
55 /** Reference date for the slope multiplication. */
56 private final AbsoluteDate reference;
57
58 /** Value of the leap at offset validity start (in seconds). */
59 private final double leap;
60
61 /** Offset at validity start in seconds (TAI minus UTC). */
62 private final double offset;
63
64 /** Offset slope in seconds per UTC second (TAI minus UTC / dUTC). */
65 private final double slopeUTC;
66
67 /** Offset slope in seconds per TAI second (TAI minus UTC / dTAI). */
68 private final double slopeTAI;
69
70 /** Simple constructor for a linear model.
71 * @param leapDate leap date
72 * @param leapDateMJD leap date in Modified Julian Day
73 * @param leap value of the leap at offset validity start (in seconds)
74 * @param offset offset in seconds (TAI minus UTC)
75 * @param mjdRef reference date for the slope multiplication as Modified Julian Day
76 * @param slope offset slope in seconds per UTC second (TAI minus UTC / dUTC)
77 * @param reference date for slope computations.
78 */
79 UTCTAIOffset(final AbsoluteDate leapDate, final int leapDateMJD,
80 final double leap, final double offset,
81 final int mjdRef, final double slope, final AbsoluteDate reference) {
82 this.leapDate = leapDate;
83 this.leapDateMJD = leapDateMJD;
84 this.validityStart = leapDate.shiftedBy(leap);
85 this.mjdRef = mjdRef;
86 this.reference = reference;
87 this.leap = leap;
88 this.offset = offset;
89 this.slopeUTC = slope;
90 this.slopeTAI = slope / (1 + slope);
91 }
92
93 /** Get the date of the start of the leap.
94 * @return date of the start of the leap
95 * @see #getValidityStart()
96 */
97 public AbsoluteDate getDate() {
98 return leapDate;
99 }
100
101 /** Get the date of the start of the leap as Modified Julian Day.
102 * @return date of the start of the leap as Modified Julian Day
103 */
104 public int getMJD() {
105 return leapDateMJD;
106 }
107
108 /** Get the start time of validity for this offset.
109 * <p>The start of the validity of the offset is {@link #getLeap()}
110 * seconds after the start of the leap itself.</p>
111 * @return start of validity date
112 * @see #getDate()
113 */
114 public AbsoluteDate getValidityStart() {
115 return validityStart;
116 }
117
118 /** Get the value of the leap at offset validity start (in seconds).
119 * @return value of the leap at offset validity start (in seconds)
120 */
121 public double getLeap() {
122 return leap;
123 }
124
125 /** Get the TAI - UTC offset in seconds.
126 * @param date date at which the offset is requested
127 * @return TAI - UTC offset in seconds.
128 */
129 public double getOffset(final AbsoluteDate date) {
130 if (slopeTAI == 0) {
131 // we use an if statement here so the offset computation returns
132 // a finite value when date is AbsoluteDate.FUTURE_INFINITY
133 // without this if statement, the multiplication between an
134 // infinite duration and a zero slope would induce a NaN offset
135 return offset;
136 } else {
137 return offset + date.durationFrom(reference) * slopeTAI;
138 }
139 }
140
141 /** Get the TAI - UTC offset in seconds.
142 * @param date date at which the offset is requested
143 * @param <T> type of the filed elements
144 * @return TAI - UTC offset in seconds.
145 * @since 9.0
146 */
147 public <T extends CalculusFieldElement<T>> T getOffset(final FieldAbsoluteDate<T> date) {
148 if (slopeTAI == 0) {
149 // we use an if statement here so the offset computation returns
150 // a finite value when date is FieldAbsoluteDate.getFutureInfinity(field)
151 // without this if statement, the multiplication between an
152 // infinite duration and a zero slope would induce a NaN offset
153 return date.getField().getZero().newInstance(offset);
154 } else {
155 return date.durationFrom(reference).multiply(slopeTAI).add(offset);
156 }
157 }
158
159 /** Get the TAI - UTC offset in seconds.
160 * @param date date components (in UTC) at which the offset is requested
161 * @param time time components (in UTC) at which the offset is requested
162 * @return TAI - UTC offset in seconds.
163 */
164 public double getOffset(final DateComponents date, final TimeComponents time) {
165 final int days = date.getMJD() - mjdRef;
166 final double fraction = time.getSecondsInUTCDay();
167 return offset + days * (slopeUTC * Constants.JULIAN_DAY) + fraction * slopeUTC;
168 }
169
170 }