Time conversion functions

The following group of functions allow to convert dates between different timescales (UTC, TAI, TT, TDB, TCB) and formats (Julian date, calendar date). Some of these functions accept time strings as input, which are parsed internally.

When an error occurs, these functions execute error handlers according to the behavior defined by the function f90calceph_seterrorhandler().

Timescale notes

Conversions involving the Coordinated Universal Time (UTC) rely on the history of leap seconds. Consequently, these functions require an ephemeris file containing the time constants (usually DELTET or DELTA_AT) to be opened and provided to the function . These time constants are provided in the leap second spice kernel file (*.tls).

Conversions the Barycentric Dynamical Time (TDB) and the Terrestrial Time (TT) are performed using the model chosen with the f90calceph_time_set_relationship_tt_tdb() function.

Input string formats

For functions accepting time strings as input, the library supports various formats, including ISO 8601, explicit Julian dates, and custom calendar strings.

If the time scale is specified within the string (e.g., "1996-01-01 UTC"), it is automatically detected. If the time scale is not present in the string, it is considered as UTC time scale.

The following strings show some examples of supported strings

"2006-01-15T12:01:10.00 UTC"
"2006-01-15T12:01:10.00 TDB"
"1995 December 31  15:59:59.5  (UTC)"
"1988 June 13, 12:29:48 TDB"
"1988 June 13, 12:29:48 TT"
"JD 2453751.0008101849816740 (TAI)"
"JD 2453751.0011826851405203 (TT)"
"JD 2453751.0013471459969878 (TCB)"
"2451515.2981 (JD)"

Functions

f90calceph_time_jd_to_cal

function f90calceph_time_jd_to_cal(eph, timescale, jd0, jdfrac, yy, month, day, hh, min, sec)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• timescale [INTEGER, intent(in)] :: timescale of the input date and result ( see Timescale constant for the available timescales)

• jd0 [REAL(8), intent(in)] :: Integer part of Julian Date

• jdfrac [REAL(8), intent(in)] :: Fractional part of Julian Date

• yy [INTEGER, intent(out)] :: Year

• month [INTEGER, intent(out)] :: Month [1-12]

• day [INTEGER, intent(out)] :: Day [1-31]

• hh [INTEGER, intent(out)] :: Hour [0-23]

• min [INTEGER, intent(out)] :: Minute [0-59]

• sec [REAL(8), intent(out)] :: Seconds [0-60)

Return:

f90calceph_time_jd_to_cal [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Julian Date, expressed as two double-precision numbers, into a Gregorian calendar date (year, month, day) and time (hour, minute, second).

Depending on the value of the timescale argument, the function behaves as follows:

• CALCEPH_UTC: The function handles leap seconds. It requires that the ephemeris file associated to eph contains leap second history (constants DELTET or DELTA_AT).

• Other timescales (e.g., CALCEPH_TT, CALCEPH_TDB): The time is treated as continuous. The seconds field is always in the range [0, 60[.

If the timescale is CALCEPH_UTC and the ephemeris file does not contain the required leap second constants, the function returns an error.

The following example converts a JD to a calendar date in TDB:

integer*8 peph
integer res, yy, mo, dd, hh,mi
double precision ss

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the julian day 2457754.499994212962963 UTC (leap second) to the calendar date UTC
  res = f90calceph_time_jd_to_cal(peph, 2460679.0D0, 0.45902180578559637D0, yy, mo, dd, hh,mi, ss)
  write(*,*) yy, mo, dd, hh,mi, ss ! print 2016 12 31 23 59 60.49999421295723

  call f90calceph_close(peph)
endif

f90calceph_time_cal_to_jd

function f90calceph_time_cal_to_jd(eph, timescale, yy, month, day, hh, min, sec, jd0, jdfrac)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• timescale [INTEGER, intent(in)] :: timescale of the input date and result ( see Timescale constant for the available timescales)

• yy [INTEGER, intent(in)] :: Year

• month [INTEGER, intent(in)] :: Month [1-12]

• day [INTEGER, intent(in)] :: Day [1-31]

• hh [INTEGER, intent(in)] :: Hour [0-23]

• min [INTEGER, intent(in)] :: Minute [0-59]

• sec [REAL(8), intent(in)] :: Seconds [0.0-60.0)

• jd0 [REAL(8), intent(out)] :: Integer part of Julian Date

• jdfrac [REAL(8), intent(out)] :: Fractional part of Julian Date

Return:

f90calceph_time_cal_to_jd [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Gregorian calendar date (year, month, day) and time (hour, minute, second) into a Julian Date, expressed as two double-precision floating-point numbers.

The resulting Julian Date is the sum of the two returned values jd0 and jdfrac. This split representation preserves numerical precision.

Depending on the value of the timescale argument, the function performs the conversion as follows:

• CALCEPH_UTC: The function accounts for leap seconds. It calculates the Julian Date by checking the leap second history stored in the ephemeris file (eph).

  • If the input date corresponds to a leap second (e.g., 23:59:60), the function correctly computes the JD for that instant.

  • The function requires the ephemeris file to contain standard time constants (DELTET or DELTA_AT).

• Other timescales (e.g., CALCEPH_TT, CALCEPH_TDB): The time is treated as continuous (without leap seconds). The minutes are assumed to always contain 60 seconds.

If timescale is CALCEPH_UTC and the necessary leap second data is missing from the ephemeris file, the function returns an error.

The following example converts a calendar date to a Julian Date:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  ! convert 2025-01-03T22:59:50.300 UTC to the julian day UTC
  res = f90calceph_time_cal_to_jd(peph, CALCEPH_UTC, 2025, 1, 3, 22, 59, 50.3D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45822106481481484

  call f90calceph_close(peph)
endif

f90calceph_time_str_to_jd

function f90calceph_time_str_to_jd(eph, timescale, const char *str, jd0, jdfrac)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• timescale [INTEGER, intent(in)] :: timescale of the input date and result ( see Timescale constant for the available timescales)

• str [CHARACTER(len=*), intent(in)] :: Input time string to be parsed

• jd0 [REAL(8), intent(out)] :: Integer part of Julian Date

• jdfrac [REAL(8), intent(out)] :: Fractional part of Julian Date

Return:

f90calceph_time_str_to_jd [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function parses a time string and converts it into a Julian Date, returned as two double-precision numbers (jd0 and jdfrac).

This function supports various input string formats, including ISO 8601, explicit Julian Dates (prefixed with "JD"), and standard calendar formats.

The interpretation of the date depends on the timescale argument:

• Specific Timescale (e.g., CALCEPH_UTC, CALCEPH_TT): The function interprets the date components parsed from the string as being in this specific timescale, regardless of any timescale suffix present in the string itself.

• CALCEPH_TIMESCALE_FROM_STR: The function attempts to detect the timescale from the string (e.g., "2000-01-01 TDB").

  • If a timescale is found in the string, it is used for the conversion.

  • If no timescale is found, the function defaults to UTC.

If the resulting conversion requires UTC (either explicitly requested or detected), the ephemeris handle associated to eph must contain leap second data.

The following example parses a string and converts it to a Julian Date:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the calendar date TAI to the julian day TAI
  res = f90calceph_time_str_to_jd(peph, CALCEPH_TAI, "2025-01-03T22:59:50.300", jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45822106481481484

  call f90calceph_close(peph)
endif

f90calceph_time_set_relationship_tt_tdb

function f90calceph_time_set_relationship_tt_tdb(eph, model)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• model [INTEGER, intent(in)] ::

  Relationship model

  0: use of f90calceph_compute_unit()

  1: use the model based on TLS file

Return:

f90calceph_time_set_relationship_tt_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function sets the mathematical model or data source used to convert dates between the Terrestrial Time (TT) and Barycentric Dynamical Time (TDB) scales.

The selected model affects the behavior of the conversion functions f90calceph_time_jd_tdb_to_jd_tt() and f90calceph_time_jd_tt_to_jd_tdb().

The supported values for the model argument are:

• 0: The conversion uses f90calceph_compute_unit() to retrieve the time difference. The difference TT-TDB should be available in the ephemeris file.

• 1: The conversion uses a default model based on the loaded TLS file.

If an invalid model is specified, the function returns an error.

The following example sets the relationship model to use the binary ephemeris data:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  res = f90calceph_time_jd_tt_to_jd_tdb(peph, 2460679.0D0, 0.4590218056322423D0, jd0, jdfrac)

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tdb_to_jd_tt

function f90calceph_time_jd_tdb_to_jd_tt(eph, jd0_tdb, jdfrac_tdb, jd0_tt, jdfrac_tt)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• jd0_tdb [REAL(8), intent(in)] :: Integer part of Julian Date (TDB)

• jdfrac_tdb [REAL(8), intent(in)] :: Fractional part of Julian Date (TDB)

• jd0_tt [REAL(8), intent(out)] :: Integer part of Julian Date (TT)

• jdfrac_tt [REAL(8), intent(out)] :: Fractional part of Julian Date (TT)

Return:

f90calceph_time_jd_tdb_to_jd_tt [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Julian Date from the Barycentric Dynamical Time (TDB) scale to the Terrestrial Time (TT) scale.

The conversion relies on the model previously set by the function f90calceph_time_set_relationship_tt_tdb().

The input Julian Date is provided as two double-precision numbers (jd0_tdb and jdfrac_tdb) to maintain precision. The result is returned in the output variables jd0_tt and jdfrac_tt.

Depending on the selected model:

• Model 0: Retrieves the offset with f90calceph_compute_unit().

• Model 1: Uses the internal default model from the TLS file.

The following example converts a TDB date to TT:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the julian day 2460679.45902180578559637 TDB to the julian day TT
  res = f90calceph_time_jd_tdb_to_jd_tt(peph, 2460679.0D0, 0.45902180578559637D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.4590218056322423

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tt_to_jd_tdb

function f90calceph_time_jd_tt_to_jd_tdb(eph, jd0_tt, jdfrac_tt, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• jd0_tt [REAL(8), intent(in)] :: Integer part of Julian Date (TT)

• jdfrac_tt [REAL(8), intent(in)] :: Fractional part of Julian Date (TT)

• jd0_tdb [REAL(8), intent(out)] :: Integer part of Julian Date (TDB)

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of Julian Date (TDB)

Return:

f90calceph_time_jd_tt_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Julian Date from the Terrestrial Time (TT) scale to the Barycentric Dynamical Time (TDB) scale.

This is the inverse operation of f90calceph_time_jd_tdb_to_jd_tt(). It uses the model configured with the function f90calceph_time_set_relationship_tt_tdb().

The input Julian Date is provided as two double-precision numbers (jd0_tt and jdfrac_tt). The converted date is stored in jd0_tdb and jdfrac_tdb.

If the ephemeris handle is NULL or if the model configuration is invalid, the function returns an error.

The following example converts a TT date to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the julian day 2460679.4590218056322423 TDB to the julian day TT
  res = f90calceph_time_jd_tt_to_jd_tdb(peph, 2460679.0D0, 0.4590218056322423D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45902180578559637

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tdb_to_jd_tcb

function f90calceph_time_jd_tdb_to_jd_tcb(eph, jd0_tdb, jdfrac_tdb, jd0_tcb, jdfrac_tcb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• jd0_tdb [REAL(8), intent(in)] :: Integer part of Julian Date (TDB)

• jdfrac_tdb [REAL(8), intent(in)] :: Fractional part of Julian Date (TDB)

• jd0_tcb [REAL(8), intent(out)] :: Integer part of Julian Date (TCB)

• jdfrac_tcb [REAL(8), intent(out)] :: Fractional part of Julian Date (TCB)

Return:

f90calceph_time_jd_tdb_to_jd_tcb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Julian Date from the Barycentric Dynamical Timescale (TDB) to the Barycentric Coordinate Timescale (TCB).

The conversion relies on the relation between TCB and TDB defined by the IAU 2006 Resolution B3 : "Re-definition of Barycentric Dynamical Time, TDB".

The input Julian Date is provided as two double-precision numbers (jd0_tdb and jdfrac_tdb) to maintain precision. The result is returned in the output variables jd0_tcb and jdfrac_tcb.

The following example converts a TDB date to TCB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  ! convert the julian day 2450083.1267361110076308 TDB to the julian day TCB
  res = f90calceph_time_jd_tdb_to_jd_tcb(peph, 2450083.0D0, 0.1267361110076308D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2450083.0 0.1268436964601278

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tcb_to_jd_tdb

function f90calceph_time_jd_tcb_to_jd_tdb(eph, jd0_tcb, jdfrac_tcb, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• jd0_tcb [REAL(8), intent(in)] :: Integer part of Julian Date (TCB)

• jdfrac_tcb [REAL(8), intent(in)] :: Fractional part of Julian Date (TCB)

• jd0_tdb [REAL(8), intent(out)] :: Integer part of Julian Date (TDB)

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of Julian Date (TDB)

Return:

f90calceph_time_jd_tcb_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Julian Date from the Barycentric Coordinate Timescale (TCB) to the Barycentric Dynamical Timescale (TDB) .

This is the inverse operation of f90calceph_time_jd_tdb_to_jd_tcb().

The conversion relies on the relation between TCB and TDB defined by the IAU 2006 Resolution B3 : "Re-definition of Barycentric Dynamical Time, TDB".

The input Julian Date is provided as two double-precision numbers (jd0_tcb and jdfrac_tcb). The converted date is stored in jd0_tdb and jdfrac_tdb.

If the ephemeris handle is NULL, the function returns an error.

The following example converts a TCB date to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  ! convert the julian day 2450083.1268436964601278 TCB to the julian day TDB
  res = f90calceph_time_jd_tcb_to_jd_tdb(peph, 450083.0D0, 0.1268436964601278D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 222450083.0  0.1267361110076308

  call f90calceph_close(peph)
endif

f90calceph_time_cal_utc_to_jd_tdb

function f90calceph_time_cal_utc_to_jd_tdb(eph, yy, month, day, hh, min, sec, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• yy [INTEGER, intent(in)] :: Year

• month [INTEGER, intent(in)] :: Month

• day [INTEGER, intent(in)] :: Day

• hh [INTEGER, intent(in)] :: Hour

• min [INTEGER, intent(in)] :: Minute

• sec [REAL(8), intent(in)] :: Second

• jd0_tdb [REAL(8), intent(out)] :: Integer part of the resulting TDB Julian Date

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of the resulting TDB Julian Date

Return:

f90calceph_time_cal_utc_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a Coordinated Universal Time (UTC) calendar date (year, month, day, hour, minute, second) into a Barycentric Dynamical Time (TDB) Julian Date.

The result is returned as two double-precision floating-point numbers (jd0_tdb and jdfrac_tdb) to preserve precision.

This function performs the following transformation chain internally:

1. Converts the UTC calendar date to a UTC Julian Date.

2. Computes the difference between UTC and TT (Terrestrial Time) using leap second data.

3. Converts TT to TDB using f90calceph_time_jd_tt_to_jd_tdb().

This function requires that the ephemeris file associated to eph contains both leap second constants (for UTC → TT) and the necessary data for the TT → TDB transformation that can be initialized with f90calceph_time_set_relationship_tt_tdb().

The following example converts a UTC calendar date to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert 2025-01-03T22:59:50.300 UTC to the julian day TDB
  res = f90calceph_time_cal_utc_to_jd_tdb(peph, 2025, 1, 3, 22, 59, 50.3D0, jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45902180578559637

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tdb_to_cal_utc

function f90calceph_time_jd_tdb_to_cal_utc(eph, jd0_tdb, jdfrac_tdb, yy, month, day, hh, min, sec)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• jd0_tdb [REAL(8), intent(in)] :: Integer part of the TDB Julian Date

• jdfrac_tdb [REAL(8), intent(in)] :: Fractional part of the TDB Julian Date

• yy [INTEGER, intent(out)] :: Year

• month [INTEGER, intent(out)] :: Month

• day [INTEGER, intent(out)] :: Day

• hh [INTEGER, intent(out)] :: Hour

• min [INTEGER, intent(out)] :: Minute

• sec [REAL(8), intent(out)] :: Second

Return:

f90calceph_time_jd_tdb_to_cal_utc [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a TDB Julian Date into a UTC calendar date (year, month, day, hour, minute, second).

This is the inverse operation of f90calceph_time_cal_utc_to_jd_tdb().

The transformation chain performed is:

1. Converts TDB to TT using f90calceph_time_jd_tdb_to_jd_tt().

2. Computes the difference between TT and UTC (using leap seconds).

3. Converts the resulting UTC Julian Date into calendar components.

The function requires that the ephemeris file associated to eph contains the necessary time constants.

The following example converts a TDB Julian Date to a UTC calendar date:

integer*8 peph
integer res, yy, mo, dd, hh,mi
double precision ss

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the julian day 2460679.45902180578559637 TDB to the calendar date UTC
  res = f90calceph_time_jd_tdb_to_cal_utc(peph, 2460679.0D0, 0.45902180578559637D0, yy, mo, dd, hh,mi, ss)
  write(*,*) yy, mo, dd, hh,mi, ss ! print 2025 1 3 22 59 50.30000662574196

  call f90calceph_close(peph)
endif

f90calceph_time_str_utc_to_jd_tdb

function f90calceph_time_str_utc_to_jd_tdb(eph, const char *str, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• str [CHARACTER(len=*), intent(in)] :: UTC time string to parse

• jd0_tdb [REAL(8), intent(out)] :: Integer part of the resulting TDB Julian Date

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of the resulting TDB Julian Date

Return:

f90calceph_time_str_utc_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function parses a time string representing a UTC date and converts it directly to a TDB Julian Date.

The function forces the interpretation of the input string as UTC, ignoring any potential timescale suffix present in the string. It then performs the full conversion chain (UTC → TAI → TT → TDB).

The following example converts a UTC string to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the calendar date UTC to the julian day TDB
  res = f90calceph_time_str_utc_to_jd_tdb(peph, "2025-01-03T22:59:50.300", jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45902180578559637

  call f90calceph_close(peph)
endif

f90calceph_time_str_any_to_jd_tdb

function f90calceph_time_str_any_to_jd_tdb(eph, const char *str, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• str [CHARACTER(len=*), intent(in)] :: Time string to parse

• jd0_tdb [REAL(8), intent(out)] :: Integer part of the resulting TDB Julian Date

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of the resulting TDB Julian Date

Return:

f90calceph_time_str_any_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function parses a time string, identifies its native time scale, and converts the date directly to the TDB scale.

The function first parses the string to extract the date and the time scale (e.g., "2000-01-01 TAI"). Based on the detected time scale, it performs the necessary conversions to reach TDB.

The supported input timescales and their internal conversion paths are:

• CALCEPH_TDB: No conversion needed.

• CALCEPH_TT: Performs the transformation TT → TDB.

• CALCEPH_TAI: Performs the transformation chain TAI → TT → TDB.

• CALCEPH_UTC: Performs the transformation chain UTC → TAI → TT → TDB.

If the input string does not specify a time scale, the function defaults to CALCEPH_UTC before converting to TDB.

This function requires that the ephemeris file associated to eph contains the necessary data for the requested conversions (leap seconds for UTC/TAI, and relationship model for TT/TDB that can be initialized with f90calceph_time_set_relationship_tt_tdb()).

The following example converts a TAI string to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac

res = f90calceph_open(peph, "example_lsk.tls")
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  ! convert the calendar date UTC to the julian day TDB
  res = f90calceph_time_str_any_to_jd_tdb(peph, "2025-01-03T22:59:50.300 UTC", jd0, jdfrac)
  write(*,*) jd0, jdfrac ! print 2460679.0 0.45902180578559637

  call f90calceph_close(peph)
endif

f90calceph_time_str_spacecraft_clock_to_jd_tdb

function f90calceph_time_str_spacecraft_clock_to_jd_tdb(eph, itarget, str, jd0_tdb, jdfrac_tdb)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• itarget [INTEGER, intent(in)] :: NAIF ID of the spacecraft

• str [CHARACTER(len=*), intent(in)] :: Spacecraft clock string (e.g., "1/1234:56")

• jd0_tdb [REAL(8), intent(out)] :: Integer part of the resulting TDB Julian Date

• jdfrac_tdb [REAL(8), intent(out)] :: Fractional part of the resulting TDB Julian Date

Return:

f90calceph_time_str_spacecraft_clock_to_jd_tdb [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function converts a spacecraft clock string (SCLK) to the Barycentric Dynamical Time (TDB) scale.

The input spacecraft clock string is provided in the parameter str. The converted date is stored in jd0_tdb and jdfrac_tdb.

It is strictly required to load a Spacecraft Clock kernel (usually .tsc) to define the clock partitions and coefficients.

Since this function performs an internal conversion between Terrestrial Time (TT) and Barycentric Dynamical Time (TDB), additional kernels are required depending on the configuration set by f90calceph_time_set_relationship_tt_tdb():

• If the relationship mode is 0 (default), an Ephemeris kernel (usually .bsp) containing the ntime tranformation TT-TDB must be loaded.

• If the relationship mode is 1, a Leap Seconds kernel (usually .tls) must be loaded.

If the required kernels are missing or if the string format is invalid, then the function returns an error.

The following example converts a spacecraft clock string to TDB:

integer*8 peph
integer res
double precision jd0, jdfrac
character*80 filear(2)

filear(1) = "example_lsk.tls"
filear(2) = "example_sclk.tsc"
res = f90calceph_open_array(peph, 2, filear, 80)
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  res = f90calceph_time_str_spacecraft_clock_to_jd_tdb(peph, 28, "1/0707109102:11026", jd0, jdfrac)
  write(*,*) jd0, jdfrac

  call f90calceph_close(peph)
endif

f90calceph_time_jd_tdb_to_str_spacecraft_clock

function f90calceph_time_jd_tdb_to_str_spacecraft_clock(eph, itarget, jd0_tdb, jdfrac_tdb, str)

Parameters:

• eph [INTEGER(8), intent(in)] :: ephemeris descriptor

• itarget [INTEGER, intent(in)] :: NAIF ID of the spacecraft

• jd0_tdb [REAL(8), intent(in)] :: Integer part of Julian Date (TDB)

• jdfrac_tdb [REAL(8), intent(in)] :: : Fractional part of Julian Date (TDB)

• str [CHARACTER(len=CALCEPH_MAX_CONSTANTVALUE), intent(out)] :: Output spacecraft clock time string

Return:

f90calceph_time_jd_tdb_to_str_spacecraft_clock [INTEGER] :: 0 if an error occurs, otherwise non-zero value.

This function computes the spacecraft clock string corresponding to a given Barycentric Dynamical Time (TDB).

This is the inverse operation of f90calceph_time_str_spacecraft_clock_to_jd_tdb(). The input Julian Date is provided as two double-precision numbers (jd0_tdb and jdfrac_tdb).

The resulting spacecraft clock string is stored in the character array str. Trailing blanks are added to the character array str.

It is strictly required to load a Spacecraft Clock kernel (usually .tsc) to define the clock partitions and coefficients.

Since this function performs an internal conversion between Barycentric Dynamical Time (TDB) and Terrestrial Time (TT), additional kernels are required depending on the configuration set by f90calceph_time_set_relationship_tt_tdb():

• If the relationship mode is 0 (default), an Ephemeris kernel (usually .bsp) containing the ntime tranformation TT-TDB must be loaded.

• If the relationship mode is 1, a Leap Seconds kernel (usually .tls) must be loaded.

If the time falls outside the range covered by the SCLK coefficients, then the function returns an error.

The following example converts a TDB date to a spacecraft clock string:

integer*8 peph
integer res
character(len=CALCEPH_MAX_CONSTANTVALUE) strdate
character*80 filear(2)

filear(1) = "example_lsk.tls"
filear(2) = "example_sclk.tsc"
res = f90calceph_open_array(peph, 2, filear, 80)
if (res.eq.1) then

  res = f90calceph_time_set_relationship_tt_tdb(peph, 1)
  res = f90calceph_time_jd_tdb_to_str_spacecraft_clock(peph, 28, 2459728D0, 0.63395731542095745681D0, strdate)
  write(*,*) strdate

  call f90calceph_close(peph)
endif