1 /* Contributed in the public domain.
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.util.Collection;
20 import java.util.function.BiFunction;
21
22 import org.orekit.frames.EOPEntry;
23 import org.orekit.frames.Frames;
24 import org.orekit.utils.IERSConventions;
25
26 /**
27 * A collection of {@link TimeScale}s. This interface defines methods for obtaining
28 * instances of many common time scales.
29 *
30 * @author Luc Maisonobe
31 * @author Evan Ward
32 * @see TimeScalesFactory
33 * @see TimeScale
34 * @see LazyLoadedTimeScales
35 * @see #of(Collection, BiFunction)
36 * @since 10.1
37 */
38 public interface TimeScales {
39
40 /**
41 * Get the International Atomic Time scale.
42 *
43 * @return International Atomic Time scale
44 */
45 TAIScale getTAI();
46
47 /**
48 * Get the Universal Time Coordinate scale.
49 *
50 * @return Universal Time Coordinate scale
51 */
52 UTCScale getUTC();
53
54 /**
55 * Get the Universal Time 1 scale.
56 *
57 * @param conventions IERS conventions for which EOP parameters will provide dUT1
58 * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
59 * @return Universal Time 1 scale
60 * @see #getUTC()
61 * @see Frames#getEOPHistory(IERSConventions, boolean)
62 */
63 UT1Scale getUT1(IERSConventions conventions, boolean simpleEOP);
64
65 /**
66 * Get the Terrestrial Time scale.
67 *
68 * @return Terrestrial Time scale
69 */
70 TTScale getTT();
71
72 /**
73 * Get the Galileo System Time scale.
74 *
75 * @return Galileo System Time scale
76 */
77 GalileoScale getGST();
78
79 /**
80 * Get the GLObal NAvigation Satellite System time scale.
81 *
82 * @return GLObal NAvigation Satellite System time scale
83 */
84 GLONASSScale getGLONASS();
85
86 /**
87 * Get the Quasi-Zenith Satellite System time scale.
88 *
89 * @return Quasi-Zenith Satellite System time scale
90 */
91 QZSSScale getQZSS();
92
93 /**
94 * Get the Global Positioning System scale.
95 *
96 * @return Global Positioning System scale
97 */
98 GPSScale getGPS();
99
100 /**
101 * Get the Geocentric Coordinate Time scale.
102 *
103 * @return Geocentric Coordinate Time scale
104 */
105 TCGScale getTCG();
106
107 /**
108 * Get the Barycentric Dynamic Time scale.
109 *
110 * @return Barycentric Dynamic Time scale
111 */
112 TDBScale getTDB();
113
114 /**
115 * Get the Barycentric Coordinate Time scale.
116 *
117 * @return Barycentric Coordinate Time scale
118 */
119 TCBScale getTCB();
120
121 /**
122 * Get the Greenwich Mean Sidereal Time scale.
123 *
124 * @param conventions IERS conventions for which EOP parameters will provide dUT1
125 * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
126 * @return Greenwich Mean Sidereal Time scale
127 * @since 7.0
128 */
129 GMSTScale getGMST(IERSConventions conventions, boolean simpleEOP);
130
131 /**
132 * Get the Indian Regional Navigation Satellite System time scale.
133 *
134 * @return Indian Regional Navigation Satellite System time scale
135 */
136 IRNSSScale getIRNSS();
137
138 /**
139 * Get the BeiDou Navigation Satellite System time scale.
140 *
141 * @return BeiDou Navigation Satellite System time scale
142 */
143 BDTScale getBDT();
144
145 /**
146 * Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.
147 * <p>Both <code>java.util.Date</code> and {@link DateComponents} classes
148 * follow the astronomical conventions and consider a year 0 between years -1 and +1,
149 * hence this reference date lies in year -4712 and not in year -4713 as can be seen
150 * in other documents or programs that obey a different convention (for example the
151 * <code>convcal</code> utility).</p>
152 *
153 * @return Julian epoch.
154 */
155 AbsoluteDate getJulianEpoch();
156
157 /**
158 * Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.
159 *
160 * @return Modified Julian Epoch
161 */
162 AbsoluteDate getModifiedJulianEpoch();
163
164 /**
165 * Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.
166 *
167 * @return Fifties Epoch
168 */
169 AbsoluteDate getFiftiesEpoch();
170
171 /**
172 * Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01T00:00:00
173 * International Atomic Time (<em>not</em> UTC).
174 *
175 * @return CCSDS Epoch
176 */
177 AbsoluteDate getCcsdsEpoch();
178
179 /**
180 * Reference epoch for Galileo System Time: 1999-08-22T00:00:00 GST.
181 *
182 * @return Galileo Epoch
183 */
184 AbsoluteDate getGalileoEpoch();
185
186 /**
187 * Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
188 *
189 * @return GPS Epoch
190 */
191 AbsoluteDate getGpsEpoch();
192
193 /**
194 * Reference epoch for QZSS weeks: 1980-01-06T00:00:00 QZSS time.
195 *
196 * @return QZSS Epoch
197 */
198 AbsoluteDate getQzssEpoch();
199
200 /**
201 * Reference epoch for IRNSS weeks: 1999-08-22T00:00:00 IRNSS time.
202 *
203 * @return IRNSS Epoch
204 */
205 AbsoluteDate getIrnssEpoch();
206
207 /**
208 * Reference epoch for BeiDou weeks: 2006-01-01T00:00:00 UTC.
209 *
210 * @return Beidou Epoch
211 */
212 AbsoluteDate getBeidouEpoch();
213
214 /**
215 * Reference epoch for GLONASS four-year interval number: 1996-01-01T00:00:00 GLONASS
216 * time.
217 * <p>By convention, TGLONASS = UTC + 3 hours.</p>
218 *
219 * @return GLONASS Epoch
220 */
221 AbsoluteDate getGlonassEpoch();
222
223 /**
224 * J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (<em>not</em> UTC).
225 *
226 * @return J2000 Epoch
227 * @see AbsoluteDate#createJulianEpoch(double)
228 * @see AbsoluteDate#createBesselianEpoch(double)
229 */
230 AbsoluteDate getJ2000Epoch();
231
232 /**
233 * Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate.
234 * <p>
235 * Between 1968-02-01 and 1972-01-01, UTC-TAI = 4.213 170 0s + (MJD - 39 126) x 0.002
236 * 592s. As on 1970-01-01 MJD = 40587, UTC-TAI = 8.000082s
237 * </p>
238 *
239 * @return Java Epoch
240 */
241 AbsoluteDate getJavaEpoch();
242
243 /**
244 * Dummy date at infinity in the past direction.
245 *
246 * @return the earliest date.
247 */
248 AbsoluteDate getPastInfinity();
249
250 /**
251 * Dummy date at infinity in the future direction.
252 *
253 * @return the latest date.
254 */
255 AbsoluteDate getFutureInfinity();
256
257 /**
258 * Build an instance corresponding to a Julian Epoch (JE).
259 * <p>According to Lieske paper: <a
260 * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&defaultprint=YES&filetype=.pdf.">
261 * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>,
262 * Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is
263 * related to Julian Ephemeris Date as:</p>
264 * <pre>
265 * JE = 2000.0 + (JED - 2451545.0) / 365.25
266 * </pre>
267 * <p>
268 * This method reverts the formula above and computes an {@code AbsoluteDate} from the
269 * Julian Epoch.
270 * </p>
271 *
272 * @param julianEpoch Julian epoch, like 2000.0 for defining the classical reference
273 * J2000.0
274 * @return a new instant
275 * @see #getJ2000Epoch()
276 * @see #createBesselianEpoch(double)
277 */
278 AbsoluteDate createJulianEpoch(double julianEpoch);
279
280 /**
281 * Build an instance corresponding to a Besselian Epoch (BE).
282 * <p>According to Lieske paper: <a
283 * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&defaultprint=YES&filetype=.pdf.">
284 * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>,
285 * Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch
286 * is related to Julian Ephemeris Date as:</p>
287 * <pre>
288 * BE = 1900.0 + (JED - 2415020.31352) / 365.242198781
289 * </pre>
290 * <p>
291 * This method reverts the formula above and computes an {@code AbsoluteDate} from the
292 * Besselian Epoch.
293 * </p>
294 *
295 * @param besselianEpoch Besselian epoch, like 1950 for defining the classical
296 * reference B1950.0
297 * @return a new instant
298 * @see #createJulianEpoch(double)
299 */
300 AbsoluteDate createBesselianEpoch(double besselianEpoch);
301
302 /* Helpers for creating new instances. */
303
304 /**
305 * Create a set of time scales where all the data is loaded from the given functions.
306 *
307 * @param utcMinusTai offsets used to compute UTC. If the pre-1972 linear offsets are
308 * missing they will be added.
309 * @param eopSupplier function to retrieve the EOP data. Since the EOP have to be
310 * reloaded every time a different {@link IERSConventions} is
311 * requested this function may be called multiple times. The
312 * requested conventions and the created time scales are passed as
313 * arguments. Attempting to call {@link #getUT1(IERSConventions,
314 * boolean)} or {@link #getGMST(IERSConventions, boolean)} on the
315 * time scales argument may result in unbounded recursion. To
316 * ignore EOP corrections this function should return an empty
317 * collection.
318 * @return a set of time scales based on the given data.
319 * @see UTCTAIOffsetsLoader.Parser
320 * @see org.orekit.frames.EopHistoryLoader.Parser
321 */
322 static TimeScales of(
323 final Collection<? extends OffsetModel> utcMinusTai,
324 final BiFunction<
325 ? super IERSConventions,
326 ? super TimeScales,
327 ? extends Collection<? extends EOPEntry>> eopSupplier) {
328 return new PreloadedTimeScales(utcMinusTai, eopSupplier);
329 }
330
331 }