Package org.orekit.time

Class FieldAbsoluteDate<T extends CalculusFieldElement<T>>

java.lang.Object
org.orekit.time.FieldAbsoluteDate<T>
Type Parameters:
T - type of the field elements
All Implemented Interfaces:
Comparable<FieldAbsoluteDate<T>>, FieldTimeShiftable<FieldAbsoluteDate<T>,T>, FieldTimeStamped<T>, TimeShiftable<FieldAbsoluteDate<T>>
public class FieldAbsoluteDate<T extends CalculusFieldElement<T>> extends Object implements FieldTimeStamped<T>, FieldTimeShiftable<FieldAbsoluteDate<T>,T>, Comparable<FieldAbsoluteDate<T>>
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 scales (say TAI and UTC for example) are simply different perspective related to a single object. Only one FieldAbsoluteDate<T> 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();
   FieldAbsoluteDate<T> date = new FieldAbsoluteDate<>(utcComponents, TimeScalesFactory.getUTC());
   writeNextDate(date.getComponents(TimeScalesFactory.getTAI()));

Two complementary views are available:

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: getJulianEpoch(Field), getModifiedJulianEpoch(Field), getFiftiesEpoch(Field), getCCSDSEpoch(Field), getGalileoEpoch(Field), getGPSEpoch(Field), getJ2000Epoch(Field), getJavaEpoch(Field). There are also two factory methods createJulianEpoch(CalculusFieldElement) and createBesselianEpoch(CalculusFieldElement) that can be used to compute other reference epochs like J1900.0 or B1950.0. In addition to these reference epochs, two other constants are defined for convenience: getPastInfinity(Field) and getFutureInfinity(Field), 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 FieldAbsoluteDate<T> class are guaranteed to be immutable.

Author:
Luc Maisonobe
See Also:

  • Constructor Details

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, AbsoluteDate date)
      Build an instance from an AbsoluteDate.
      Parameters:
      field - used by default
      date - AbsoluteDate to instantiate as a FieldAbsoluteDate

    • FieldAbsoluteDate

      @DefaultDataContext public FieldAbsoluteDate(Field<T> field)
      Create an instance with a default value (getJ2000Epoch(Field)).

      This method uses the default data context.

      Parameters:
      field - field used by default
      See Also:

    • FieldAbsoluteDate

      public FieldAbsoluteDate(FieldAbsoluteDate<T> since, T elapsedDuration)
      Build an instance from an elapsed duration since 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(FieldAbsoluteDate) 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:

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, 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).

      As CCSDS ASCII calendar segmented time code is a trimmed down version of ISO-8601, it is also supported by this constructor.

      Parameters:
      field - field utilized by default
      location - location in the time scale, must be in a supported format
      timeScale - time scale
      Throws:
      IllegalArgumentException - if location string is not in a supported format

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, DateTimeComponents location, TimeScale timeScale)
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      location - location in the time scale
      timeScale - time scale

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, DateComponents date, TimeComponents time, TimeScale timeScale)
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      date - date location in the time scale
      time - time location in the time scale
      timeScale - time scale

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, int month, int day, int hour, int minute, double second, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      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:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, int month, int day, int hour, int minute, TimeOffset second, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      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:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      Since:
      13.0

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, Month month, int day, int hour, int minute, double second, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      year - year number (may be 0 or negative for BC years)
      month - month enumerate
      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:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, Month month, int day, int hour, int minute, TimeOffset second, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized by default
      year - year number (may be 0 or negative for BC years)
      month - month enumerate
      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:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)
      Since:
      13.0

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, DateComponents date, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.

      The hour is set to 00:00:00.000.

      Parameters:
      field - field utilized by default
      date - date location in the time scale
      timeScale - time scale
      Throws:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, int month, int day, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.

      The hour is set to 00:00:00.000.

      Parameters:
      field - field utilized by default
      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:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, int year, Month month, int day, TimeScale timeScale) throws IllegalArgumentException
      Build an instance from a location in a time scale.

      The hour is set to 00:00:00.000.

      Parameters:
      field - field utilized by default
      year - year number (may be 0 or negative for BC years)
      month - month enumerate
      day - day number from 1 to 31
      timeScale - time scale
      Throws:
      IllegalArgumentException - if inconsistent arguments are given (parameters out of range)

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, Date location, TimeScale timeScale)
      Build an instance from a location in a time scale.
      Parameters:
      field - field utilized as default
      location - location in the time scale
      timeScale - time scale

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, Instant instant, TimeScale timeScale)
      Build an instance from an instant in a time scale.
      Parameters:
      field - field utilized as default
      instant - instant in the time scale
      timeScale - time scale
      Since:
      12.0

    • FieldAbsoluteDate

      @DefaultDataContext public FieldAbsoluteDate(Field<T> field, Instant instant)
      Build an instance from an instant in utc time scale.
      Parameters:
      field - field utilized as default
      instant - instant in the utc timescale
      Since:
      12.1

    • FieldAbsoluteDate

      public FieldAbsoluteDate(Field<T> field, Instant instant, UTCScale utcScale)
      Build an instance from an instant in the time scale.
      Parameters:
      field - field utilized as default
      instant - instant in the time scale
      utcScale - utc time scale
      Since:
      12.1

    • FieldAbsoluteDate

      public FieldAbsoluteDate(FieldAbsoluteDate<T> since, double elapsedDuration)
      Build an instance from an elapsed duration since another instant.

      It is important to note that the elapsed duration is not the difference between two readings on a time scale.

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

    • FieldAbsoluteDate

      public FieldAbsoluteDate(FieldAbsoluteDate<T> since, TimeOffset elapsedDuration)
      Build an instance from an elapsed duration since another instant.

      It is important to note that the elapsed duration is not the difference between two readings on a time scale.

      Parameters:
      since - start instant of the measured duration
      elapsedDuration - physically elapsed duration from the since instant, as measured in a regular time scale
      Since:
      13.0

    • FieldAbsoluteDate

      public FieldAbsoluteDate(FieldAbsoluteDate<T> since, long elapsedDuration, TimeUnit timeUnit)
      Build an instance from an elapsed duration since another instant.

      It is important to note that the elapsed duration is not the difference between two readings on a time scale.

      Parameters:
      since - start instant of the measured duration
      elapsedDuration - physically elapsed duration from the since instant, as measured in a regular time scale
      timeUnit - TimeUnit of the elapsed duration
      Since:
      12.1

    • FieldAbsoluteDate

      public FieldAbsoluteDate(AbsoluteDate since, T elapsedDuration)
      Build an instance from an elapsed duration since another instant.

      It is important to note that the elapsed duration is not the difference between two readings on a time scale.

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

    • FieldAbsoluteDate

      public FieldAbsoluteDate(AbsoluteDate since, long elapsedDuration, TimeUnit timeUnit, Field<T> field)
      Build an instance from an elapsed duration since another instant.

      It is important to note that the elapsed duration is not the difference between two readings on a time scale.

      Parameters:
      since - start instant of the measured duration
      elapsedDuration - physically elapsed duration from the since instant, as measured in a regular time scale
      timeUnit - TimeUnit of the elapsed duration
      field - field utilized by default
      Since:
      12.1

    • FieldAbsoluteDate

      public FieldAbsoluteDate(FieldAbsoluteDate<T> 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(FieldAbsoluteDate, 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:

  • Method Details

    • toFUD1Field

      public FieldAbsoluteDate<FieldUnivariateDerivative1<T>> toFUD1Field()
      Creates Field date with offset as univariate derivative of first order, with a unit linear coefficient in time.
      Returns:
      univariate derivative 1 date
      Since:
      13.1

    • toFUD2Field

      public FieldAbsoluteDate<FieldUnivariateDerivative2<T>> toFUD2Field()
      Creates Field date with offset as univariate derivative of second order, with a unit linear coefficient in time.
      Returns:
      univariate derivative 2 date
      Since:
      12.2

    • parseCCSDSUnsegmentedTimeCode

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSUnsegmentedTimeCode(Field<T> field, byte preambleField1, byte preambleField2, byte[] timeField, FieldAbsoluteDate<T> agencyDefinedEpoch)
      Build an instance from a CCSDS Unsegmented Time Code (CUC).

      CCSDS Unsegmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      If the date to be parsed is formatted using version 3 of the standard (CCSDS 301.0-B-3 published in 2002) or if the extension of the preamble field introduced in version 4 of the standard is not used, then the preambleField2 parameter can be set to 0.

      This method uses the default data context if the CCSDS epoch is used.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      preambleField1 - first byte of the field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      preambleField2 - second byte of the field specifying the format (added in revision 4 of the CCSDS standard in 2010), often not transmitted in data interfaces, as it is constant for a given data interface (value ignored if presence not signaled in preambleField1)
      timeField - byte array containing the time code
      agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case)
      Returns:
      an instance corresponding to the specified date
      See Also:

    • parseCCSDSUnsegmentedTimeCode

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSUnsegmentedTimeCode(byte preambleField1, byte preambleField2, byte[] timeField, FieldAbsoluteDate<T> agencyDefinedEpoch, FieldAbsoluteDate<T> ccsdsEpoch)
      Build an instance from a CCSDS Unsegmented Time Code (CUC).

      CCSDS Unsegmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      If the date to be parsed is formatted using version 3 of the standard (CCSDS 301.0-B-3 published in 2002) or if the extension of the preamble field introduced in version 4 of the standard is not used, then the preambleField2 parameter can be set to 0.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      preambleField1 - first byte of the field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      preambleField2 - second byte of the field specifying the format (added in revision 4 of the CCSDS standard in 2010), often not transmitted in data interfaces, as it is constant for a given data interface (value ignored if presence not signaled in preambleField1)
      timeField - byte array containing the time code
      agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case, but then ccsdsEpoch must be non-null)
      ccsdsEpoch - reference epoch, ignored if the preamble field specifies the agency epoch is used (and hence may be null in this case, but then agencyDefinedEpoch must be non-null).
      Returns:
      an instance corresponding to the specified date
      Since:
      10.1

    • parseCCSDSDaySegmentedTimeCode

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSDaySegmentedTimeCode(Field<T> field, byte preambleField, byte[] timeField, DateComponents agencyDefinedEpoch)
      Build an instance from a CCSDS Day Segmented Time Code (CDS).

      CCSDS Day Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      timeField - byte array containing the time code
      agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case)
      Returns:
      an instance corresponding to the specified date
      See Also:

    • parseCCSDSDaySegmentedTimeCode

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSDaySegmentedTimeCode(Field<T> field, byte preambleField, byte[] timeField, DateComponents agencyDefinedEpoch, TimeScale utc)
      Build an instance from a CCSDS Day Segmented Time Code (CDS).

      CCSDS Day Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      timeField - byte array containing the time code
      agencyDefinedEpoch - reference epoch, ignored if the preamble field specifies the CCSDS reference epoch is used (and hence may be null in this case)
      utc - time scale used to compute date and time components.
      Returns:
      an instance corresponding to the specified date
      Since:
      10.1

    • parseCCSDSCalendarSegmentedTimeCode

      @DefaultDataContext public FieldAbsoluteDate<T> parseCCSDSCalendarSegmentedTimeCode(byte preambleField, byte[] timeField)
      Build an instance from a CCSDS Calendar Segmented Time Code (CCS).

      CCSDS Calendar Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      This method uses the default data context.

      Parameters:
      preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      timeField - byte array containing the time code
      Returns:
      an instance corresponding to the specified date
      See Also:

    • parseCCSDSCalendarSegmentedTimeCode

      public FieldAbsoluteDate<T> parseCCSDSCalendarSegmentedTimeCode(byte preambleField, byte[] timeField, TimeScale utc)
      Build an instance from a CCSDS Calendar Segmented Time Code (CCS).

      CCSDS Calendar Segmented Time Code is defined in the blue book: CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010

      Parameters:
      preambleField - field specifying the format, often not transmitted in data interfaces, as it is constant for a given data interface
      timeField - byte array containing the time code
      utc - time scale used to compute date and time components.
      Returns:
      an instance corresponding to the specified date
      Since:
      10.1

    • createJDDate

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJDDate(int jd, T secondsSinceNoon, TimeScale timeScale)
      Build an instance corresponding to a Julian Day date.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      jd - Julian day
      secondsSinceNoon - seconds in the Julian day (BEWARE, Julian days start at noon, so 0.0 is noon)
      timeScale - time scale in which the seconds in day are defined
      Returns:
      a new instant

    • createJDDate

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJDDate(int jd, T secondsSinceNoon, TimeScale timeScale, TimeScale pivotTimeScale)
      Build an instance corresponding to a Julian Day date.

      This function should be preferred to createJDDate(int, CalculusFieldElement, TimeScale) when the target time scale has a non-constant offset with respect to TAI.

      The idea is to introduce a pivot time scale that is close to the target time scale but has a constant bias with TAI.

      For example, to get a date from an MJD in TDB time scale, it's advised to use the TT time scale as a pivot scale. TT is very close to TDB and has constant offset to TAI.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      jd - Julian day
      secondsSinceNoon - seconds in the Julian day (BEWARE, Julian days start at noon, so 0.0 is noon)
      timeScale - time scale in which the seconds in day are defined
      pivotTimeScale - pivot timescale used as intermediate timescale
      Returns:
      a new instant

    • createMJDDate

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createMJDDate(int mjd, T secondsInDay, TimeScale timeScale)
      Build an instance corresponding to a Modified Julian Day date.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      mjd - modified Julian day
      secondsInDay - seconds in the day
      timeScale - time scale in which the seconds in day are defined
      Returns:
      a new instant

    • createMedian

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createMedian(FieldAbsoluteDate<T> date1, FieldAbsoluteDate<T> date2)
      Create an instance as the median data between two existing instances.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      date1 - first instance
      date2 - second instance
      Returns:
      median date between first and second instance
      Since:
      13.0

    • createGPSDate

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createGPSDate(int weekNumber, T milliInWeek)
      Build an instance corresponding to a GPS date.

      This method uses the default data context.

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

      Type Parameters:
      T - the type of the field elements
      Parameters:
      weekNumber - week number since GPS epoch
      milliInWeek - number of milliseconds since week start
      Returns:
      a new instant
      See Also:

    • createGPSDate

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createGPSDate(int weekNumber, T milliInWeek, TimeScale gps)
      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.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      weekNumber - week number since GPS epoch
      milliInWeek - number of milliseconds since week start
      gps - GPS time scale.
      Returns:
      a new instant
      Since:
      10.1

    • createJulianEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJulianEpoch(T julianEpoch)
      Build an instance corresponding to a Julian Epoch (JE).

      According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is related to Julian Ephemeris Date as: 

      JE = 2000.0 + (JED - 2451545.0) / 365.25

      This method reverts the formula above and computes an FieldAbsoluteDate<T> from the Julian Epoch.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      julianEpoch - Julian epoch, like 2000.0 for defining the classical reference J2000.0
      Returns:
      a new instant
      See Also:

    • createJulianEpoch

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJulianEpoch(T julianEpoch, TimeScales timeScales)
      Build an instance corresponding to a Julian Epoch (JE).

      According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is related to Julian Ephemeris Date as: 

      JE = 2000.0 + (JED - 2451545.0) / 365.25

      This method reverts the formula above and computes an FieldAbsoluteDate<T> from the Julian Epoch.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      julianEpoch - Julian epoch, like 2000.0 for defining the classical reference J2000.0
      timeScales - used in the computation.
      Returns:
      a new instant
      Since:
      10.1
      See Also:

    • createBesselianEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createBesselianEpoch(T besselianEpoch)
      Build an instance corresponding to a Besselian Epoch (BE).

      According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch is related to Julian Ephemeris Date as:

       BE = 1900.0 + (JED - 2415020.31352) / 365.242198781

      This method reverts the formula above and computes an FieldAbsoluteDate<T> from the Besselian Epoch.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      besselianEpoch - Besselian epoch, like 1950 for defining the classical reference B1950.0
      Returns:
      a new instant
      See Also:

    • createBesselianEpoch

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createBesselianEpoch(T besselianEpoch, TimeScales timeScales)
      Build an instance corresponding to a Besselian Epoch (BE).

      According to Lieske paper: Precession Matrix Based on IAU (1976) System of Astronomical Constants, Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch is related to Julian Ephemeris Date as:

       BE = 1900.0 + (JED - 2415020.31352) / 365.242198781

      This method reverts the formula above and computes an FieldAbsoluteDate<T> from the Besselian Epoch.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      besselianEpoch - Besselian epoch, like 1950 for defining the classical reference B1950.0
      timeScales - used in the computation.
      Returns:
      a new instant
      Since:
      10.1
      See Also:

    • getJulianEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJulianEpoch(Field<T> field)
      Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.

      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).

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for julian dates as a FieldAbsoluteDate
      See Also:

    • getModifiedJulianEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getModifiedJulianEpoch(Field<T> field)
      Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for modified julian dates as a FieldAbsoluteDate
      See Also:

    • getFiftiesEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getFiftiesEpoch(Field<T> field)
      Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for 1950 dates as a FieldAbsoluteDate
      See Also:

    • getCCSDSEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getCCSDSEpoch(Field<T> field)
      Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4).

      This method uses the default data context.

      1958-01-01T00:00:00 International Atomic Time (not UTC).
      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for CCSDS Time Code Format as a FieldAbsoluteDate
      See Also:

    • getGalileoEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getGalileoEpoch(Field<T> field)
      Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for Galileo System Time as a FieldAbsoluteDate
      See Also:

    • getGPSEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getGPSEpoch(Field<T> field)
      Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the reference epoch for GPS weeks as a FieldAbsoluteDate
      See Also:

    • getJ2000Epoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJ2000Epoch(Field<T> field)
      J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (not UTC).

      This method uses the default data context.

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the J2000.0 reference epoch as a FieldAbsoluteDate
      See Also:

    • getJavaEpoch

      @DefaultDataContext public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJavaEpoch(Field<T> field)
      Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate.

      This method uses the default data context.

      Between 1968-02-01 and 1972-01-01, UTC-TAI = 4.213 170 0s + (MJD - 39 126) x 0.002 592s. As on 1970-01-01 MJD = 40587, UTC-TAI = 8.000082s

      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      the Java reference epoch as a FieldAbsoluteDate
      See Also:

    • getPastInfinity

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getPastInfinity(Field<T> field)
      Dummy date at infinity in the past direction.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      a dummy date at infinity in the past direction as a FieldAbsoluteDate
      See Also:

    • getFutureInfinity

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getFutureInfinity(Field<T> field)
      Dummy date at infinity in the future direction.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      a dummy date at infinity in the future direction as a FieldAbsoluteDate
      See Also:

    • getArbitraryEpoch

      public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getArbitraryEpoch(Field<T> field)
      Get an arbitrary date. Useful when a non-null date is needed but its values does not matter.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field for the components
      Returns:
      an arbitrary date.

    • shiftedBy

      public FieldAbsoluteDate<T> shiftedBy(T dt)
      Get a time-shifted date.

      Calling this method is equivalent to call new FieldAbsoluteDate&lt;&gt;(this, dt).

      Specified by:
      shiftedBy in interface FieldTimeShiftable<FieldAbsoluteDate<T extends CalculusFieldElement<T>>,T extends CalculusFieldElement<T>>
      Parameters:
      dt - time shift in seconds
      Returns:
      a new date, shifted with respect to instance (which is immutable)
      See Also:

    • durationFrom

      public T durationFrom(FieldAbsoluteDate<T> 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(FieldAbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

      This method is the reverse of the FieldAbsoluteDate(FieldAbsoluteDate, 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:

    • durationFrom

      public T durationFrom(FieldAbsoluteDate<T> instant, TimeUnit timeUnit)
      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(FieldAbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

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

      Parameters:
      instant - instant to subtract from the instance
      timeUnit - TimeUnit precision for the offset
      Returns:
      offset in seconds between the two instants (positive if the instance is posterior to the argument)
      See Also:

    • durationFrom

      public T 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(FieldAbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

      This method is the reverse of the FieldAbsoluteDate(FieldAbsoluteDate, 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:

    • durationFrom

      public T durationFrom(AbsoluteDate instant, TimeUnit timeUnit)
      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(FieldAbsoluteDate, TimeScale) with a second argument set to one of the regular scales cited above.

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

      Parameters:
      instant - instant to subtract from the instance
      timeUnit - TimeUnit precision for the offset
      Returns:
      offset in the given timeunit between the two instants (positive if the instance is posterior to the argument), rounded to the nearest integer TimeUnit
      Since:
      12.1
      See Also:

    • offsetFrom

      public T offsetFrom(FieldAbsoluteDate<T> 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(FieldAbsoluteDate) method is 2 seconds.

      This method is the reverse of the FieldAbsoluteDate(FieldAbsoluteDate, 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:

    • timeScalesOffset

      public T 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 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

    • toInstant

      @DefaultDataContext public Instant toInstant()
      Convert the instance to a Java Instant. Nanosecond precision is preserved during this conversion
      Returns:
      a Instant instance representing the location of the instant in the utc time scale
      Since:
      12.1

    • toInstant

      public Instant toInstant(TimeScales timeScales)
      Convert the instance to a Java Instant. Nanosecond precision is preserved during this conversion
      Parameters:
      timeScales - the timescales to use
      Returns:
      a Instant instance representing the location of the instant in the utc time scale
      Since:
      12.1

    • getComponents

      public DateTimeComponents getComponents(TimeScale timeScale)
      Split the instance into date/time components.
      Parameters:
      timeScale - time scale to use
      Returns:
      date/time components

    • getComponents

      @DefaultDataContext public DateTimeComponents getComponents(int minutesFromUTC)
      Split the instance into date/time components for a local time.

      This method uses the default data context.

      Parameters:
      minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC)
      Returns:
      date/time components
      See Also:

    • getComponents

      public DateTimeComponents getComponents(int minutesFromUTC, TimeScale utc)
      Split the instance into date/time components for a local time.
      Parameters:
      minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC)
      utc - time scale used to compute date and time components.
      Returns:
      date/time components
      Since:
      10.1

    • getDate

      public FieldAbsoluteDate<T> getDate()
      Get the date.
      Specified by:
      getDate in interface FieldTimeStamped<T extends CalculusFieldElement<T>>
      Returns:
      date attached to the object

    • getField

      public Field<T> getField()
      Get the field.
      Returns:
      field instance.

    • getComponents

      @DefaultDataContext public DateTimeComponents getComponents(TimeZone timeZone)
      Split the instance into date/time components for a time zone.

      This method uses the default data context.

      Parameters:
      timeZone - time zone
      Returns:
      date/time components
      See Also:

    • getComponents

      public DateTimeComponents getComponents(TimeZone timeZone, TimeScale utc)
      Split the instance into date/time components for a time zone.
      Parameters:
      timeZone - time zone
      utc - time scale used to compute date and time components.
      Returns:
      date/time components
      Since:
      10.1

    • compareTo

      public int compareTo(FieldAbsoluteDate<T> other)
      Compare the instance with another date.
      Specified by:
      compareTo in interface Comparable<T extends CalculusFieldElement<T>>
      Parameters:
      other - 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.

    • equals

      public boolean equals(Object other)
      Check if the instance represents the same time as another instance.
      Overrides:
      equals in class Object
      Parameters:
      other - other date
      Returns:
      true if the instance and the other date refer to the same instant with same Field and addendum

    • isEqualTo

      public boolean isEqualTo(FieldTimeStamped<T> other)
      Check if the instance represents the same time as another.
      Parameters:
      other - the instant to compare this date to
      Returns:
      true if the instance and the argument refer to the same instant
      Since:
      10.1
      See Also:

    • isCloseTo

      public boolean isCloseTo(FieldTimeStamped<T> other, double tolerance)
      Check if the instance time is close to another.
      Parameters:
      other - the instant to compare this date to
      tolerance - the separation, in seconds, under which the two instants will be considered close to each other
      Returns:
      true if the duration between the instance and the argument is strictly below the tolerance
      Since:
      10.1
      See Also:

    • isBefore

      public boolean isBefore(FieldTimeStamped<T> other)
      Check if the instance represents a time that is strictly before another.
      Parameters:
      other - the instant to compare this date to
      Returns:
      true if the instance is strictly before the argument when ordering chronologically
      Since:
      10.1
      See Also:

    • isAfter

      public boolean isAfter(FieldTimeStamped<T> other)
      Check if the instance represents a time that is strictly after another.
      Parameters:
      other - the instant to compare this date to
      Returns:
      true if the instance is strictly after the argument when ordering chronologically
      Since:
      10.1
      See Also:

    • isBeforeOrEqualTo

      public boolean isBeforeOrEqualTo(FieldTimeStamped<T> other)
      Check if the instance represents a time that is before or equal to another.
      Parameters:
      other - the instant to compare this date to
      Returns:
      true if the instance is before (or equal to) the argument when ordering chronologically
      Since:
      10.1
      See Also:

    • isAfterOrEqualTo

      public boolean isAfterOrEqualTo(FieldTimeStamped<T> other)
      Check if the instance represents a time that is after or equal to another.
      Parameters:
      other - the instant to compare this date to
      Returns:
      true if the instance is after (or equal to) the argument when ordering chronologically
      Since:
      10.1
      See Also:

    • isBetween

      public boolean isBetween(FieldTimeStamped<T> boundary, FieldTimeStamped<T> otherBoundary)
      Check if the instance represents a time that is strictly between two others representing the boundaries of a time span. The two boundaries can be provided in any order: in other words, whether boundary represents a time that is before or after otherBoundary will not change the result of this method.
      Parameters:
      boundary - one end of the time span
      otherBoundary - the other end of the time span
      Returns:
      true if the instance is strictly between the two arguments when ordering chronologically
      Since:
      10.1
      See Also:

    • isBetweenOrEqualTo

      public boolean isBetweenOrEqualTo(FieldTimeStamped<T> boundary, FieldTimeStamped<T> otherBoundary)
      Check if the instance represents a time that is between two others representing the boundaries of a time span, or equal to one of them. The two boundaries can be provided in any order: in other words, whether boundary represents a time that is before or after otherBoundary will not change the result of this method.
      Parameters:
      boundary - one end of the time span
      otherBoundary - the other end of the time span
      Returns:
      true if the instance is between the two arguments (or equal to at least one of them) when ordering chronologically
      Since:
      10.1
      See Also:

    • hashCode

      public int hashCode()
      Get a hashcode for this date.
      Overrides:
      hashCode in class Object
      Returns:
      hashcode

    • toString

      @DefaultDataContext public String toString()
      Get a String representation of the instant location with up to 16 digits of precision for the seconds value.

      Since this method is used in exception messages and error handling every effort is made to return some representation of the instant. If UTC is available from the default data context then it is used to format the string in UTC. If not then TAI is used. Finally if the prior attempts fail this method falls back to converting this class's internal representation to a string.

      This method uses the default data context.

      Overrides:
      toString in class Object
      Returns:
      a string representation of the instance, in ISO-8601 format if UTC is available from the default data context.
      See Also:

    • toString

      public String toString(TimeScale timeScale)
      Get a String representation of the instant location in ISO-8601 format without the UTC offset and with up to 16 digits of precision for the seconds value.
      Parameters:
      timeScale - time scale to use
      Returns:
      a string representation of the instance.
      See Also:

    • toString

      @DefaultDataContext public String toString(int minutesFromUTC)
      Get a String representation of the instant location for a local time.

      This method uses the default data context.

      Parameters:
      minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC).
      Returns:
      string representation of the instance, in ISO-8601 format with milliseconds accuracy
      See Also:

    • toString

      public String toString(int minutesFromUTC, TimeScale utc)
      Get a String representation of the instant location for a local time.
      Parameters:
      minutesFromUTC - offset in minutes from UTC (positive Eastwards UTC, negative Westward UTC).
      utc - time scale used to compute date and time components.
      Returns:
      string representation of the instance, in ISO-8601 format with milliseconds accuracy
      Since:
      10.1

    • toString

      @DefaultDataContext public String toString(TimeZone timeZone)
      Get a String representation of the instant location for a time zone.

      This method uses the default data context.

      Parameters:
      timeZone - time zone
      Returns:
      string representation of the instance, in ISO-8601 format with milliseconds accuracy
      See Also:

    • toString

      public String toString(TimeZone timeZone, TimeScale utc)
      Get a String representation of the instant location for a time zone.
      Parameters:
      timeZone - time zone
      utc - time scale used to compute date and time components.
      Returns:
      string representation of the instance, in ISO-8601 format with milliseconds accuracy
      Since:
      10.1

    • toStringWithoutUtcOffset

      public String toStringWithoutUtcOffset(TimeScale timeScale, int fractionDigits)
      Return a string representation of this date-time, rounded to the given precision.

      The format used is ISO8601 without the UTC offset.

      Parameters:
      timeScale - to use to compute components.
      fractionDigits - the number of digits to include after the decimal point in the string representation of the seconds. The date and time is first rounded as necessary. fractionDigits must be greater than or equal to 0.
      Returns:
      string representation of this date, time, and UTC offset
      Since:
      12.2
      See Also:

    • shiftedBy

      public FieldAbsoluteDate<T> shiftedBy(double dt)
      Get a time-shifted date.

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

      Specified by:
      shiftedBy in interface TimeShiftable<T extends CalculusFieldElement<T>>
      Parameters:
      dt - time shift in seconds
      Returns:
      a new date, shifted with respect to instance (which is immutable)
      See Also:

    • shiftedBy

      public FieldAbsoluteDate<T> shiftedBy(TimeOffset dt)
      Get a time-shifted date.

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

      Specified by:
      shiftedBy in interface TimeShiftable<T extends CalculusFieldElement<T>>
      Parameters:
      dt - time shift
      Returns:
      a new date, shifted with respect to instance (which is immutable)
      Since:
      13.0
      See Also:

    • shiftedBy

      public FieldAbsoluteDate<T> shiftedBy(long dt, TimeUnit timeUnit)
      Get a time-shifted date.

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

      Parameters:
      dt - time shift in time units
      timeUnit - TimeUnit for dt
      Returns:
      a new date, shifted with respect to instance (which is immutable)
      Since:
      12.1
      See Also:

    • toAbsoluteDate

      public AbsoluteDate toAbsoluteDate()
      Transform the FieldAbsoluteDate in an AbsoluteDate.
      Returns:
      AbsoluteDate of the FieldObject

    • hasZeroField

      public boolean hasZeroField()
      Check if the Field is semantically equal to zero.

      Using FieldElement.isZero()

      Returns:
      true the Field is semantically equal to zero
      Since:
      12.0

    • getMJD

      @DefaultDataContext public T getMJD()
      Return the given date as a Modified Julian Date expressed in UTC.
      Returns:
      double representation of the given date as Modified Julian Date.
      Since:
      12.2

    • getMJD

      public T getMJD(TimeScale ts)
      Return the given date as a Modified Julian Date expressed in given timescale.
      Parameters:
      ts - time scale
      Returns:
      double representation of the given date as Modified Julian Date.
      Since:
      12.2

    • getJD

      @DefaultDataContext public T getJD()
      Return the given date as a Julian Date expressed in UTC.
      Returns:
      double representation of the given date as Julian Date.
      Since:
      12.2

    • getJD

      public T getJD(TimeScale ts)
      Return the given date as a Julian Date expressed in given timescale.
      Parameters:
      ts - time scale
      Returns:
      double representation of the given date as Julian Date.
      Since:
      12.2

    • getDayOfYear

      public T getDayOfYear(TimeScale utc)
      Get day of year, preserving continuity as much as possible.

      This is a continuous extension of the integer value returned by getComponents(utc).getDate().getDayOfYear(). In order to have it remain as close as possible to its integer counterpart, day 1.0 is considered to occur on January 1st at noon.

      Continuity is preserved from day to day within a year, but of course there is a discontinuity at year change, where it switches from 365.49999… (or 366.49999… on leap years) to 0.5

      Parameters:
      utc - time scale to compute date components
      Returns:
      day of year, with day 1.0 occurring on January first at noon
      Since:
      13.0