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 calceph_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 CalcephBin.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

CalcephBin.time_jd_to_cal

CalcephBin.time_jd_to_cal(timescale, jd0, jdfrac) → yy, month, day, hh, min, sec

Parameters:

timescale (int) -- timescale of the input date and result ( see Timescale constant for the available timescales)
jd0 (int) -- Integer part of Julian Date
jdfrac (int) -- Fractional part of Julian Date

Returns:

Year, Month [1–12], Day [1–31], Hour [0–23], Minute [0–59], seconds [0.0–61.0[

Return type:

int, int, int, int, int, float

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:

UTC: The function handles leap seconds. It requires that the ephemeris file self contains leap second history (constants DELTET or DELTA_AT).
Other timescales (e.g., TT, TDB): The time is treated as continuous. The seconds field is always in the range [0, 60[.

If the timescale is 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:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the julian day 2457754.499994212962963 UTC (leap second) to the calendar date UTC
[yy, mo, dd, hh,mi, ss] = peph.time_jd_to_cal(Constants.UTC, 2457754, 0.499994212962963);
printf("%d-%d-%d %d:%d:%.6f\n", yy, mo, dd, hh,mi, ss) # print 2016-12-31 23:59:60.499994
peph.close()

CalcephBin.time_cal_to_jd

CalcephBin.time_cal_to_jd(timescale, yy, month, day, hh, min, sec) → jd0, jdfrac

Parameters:

timescale (int) -- timescale of the input date and result ( see Timescale constant for the available timescales)
yy (int) -- Year
month (int) -- Month [1–12]
day (int) -- Day [1–31]
hh (int) -- Hour [0–23]
min (int) -- Minute [0–59]
sec (float) -- Seconds [0.0–61.0[

Returns:

Integer part of Julian Date, Fractional part of Julian Date

Return type:

float, float

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:

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., TT, TDB): The time is treated as continuous (without leap seconds). The minutes are assumed to always contain 60 seconds.

If timescale is 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:

peph = CalcephBin.open("example_lsk.tls")
# convert 2025-01-03T22:59:50.300 UTC to the julian day UTC
[jd0, jdfrac] = peph.time_cal_to_jd(Constants.UTC, 2025, 1, 3, 22, 59, 50.3);
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4582210648148148
peph.close()

CalcephBin.time_str_to_jd

CalcephBin.time_str_to_jd(timescale, str) → jd0, jdfrac

Parameters:

timescale -- timescale of the input date and result ( see Timescale constant for the available timescales)
str -- Input time string to be parsed

Returns:

Integer part of Julian Date, Fractional part of Julian Date

Return type:

float, float

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., UTC, 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.
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 self must contain leap second data.

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

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the calendar date TAI to the julian day TAI
[jd0, jdfrac] = peph.time_str_to_jd(Constants.TAI, "2025-01-03T22:59:50.300");
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4582210648148148
peph.close()

CalcephBin.time_set_relationship_tt_tdb

CalcephBin.time_set_relationship_tt_tdb(model)

Parameters:

model --

Relationship model
0: use of CalcephBin.compute_unit()
1: use the model based on TLS file

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 CalcephBin.time_jd_tdb_to_jd_tt() and CalcephBin.time_jd_tt_to_jd_tdb().

The supported values for the model argument are:

0: The conversion uses CalcephBin.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:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
[jd0, jdfrac] = peph.time_jd_tt_to_jd_tdb(2460679.0, 0.4590218056322423);
peph.close()

CalcephBin.time_jd_tdb_to_jd_tt

CalcephBin.time_jd_tdb_to_jd_tt(jd0_tdb, jdfrac_tdb) → jd0_tt, jdfrac_tt

Parameters:

jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

Integer part of Julian Date (TT), Fractional part of Julian Date (TT)

Return type:

float, float

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 CalcephBin.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 CalcephBin.compute_unit().
Model 1: Uses the internal default model from the TLS file.

The following example converts a TDB date to TT:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the julian day 2460679.45902180578559637 TDB to the julian day TT
[jd0, jdfrac] = peph.time_jd_tdb_to_jd_tt(2460679.0, 0.45902180578559637);
printf("%f %.16f\n", jd0, jdfrac) # print  2460679.000000 0.4590218056322423
peph.close()

CalcephBin.time_jd_tt_to_jd_tdb

CalcephBin.time_jd_tt_to_jd_tdb(jd0_tt, jdfrac_tt) → jd0_tdb, jdfrac_tdb

Parameters:

jd0_tt -- Integer part of Julian Date (TT)
jdfrac_tt -- Fractional part of Julian Date (TT)

Returns:

Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)

Return type:

float, float

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 CalcephBin.time_jd_tdb_to_jd_tt(). It uses the model configured with the function CalcephBin.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:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the julian day 2460679.4590218056322423 TDB to the julian day TT
[jd0, jdfrac] = peph.time_jd_tt_to_jd_tdb(2460679.0, 0.4590218056322423);
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4590218057855964
peph.close()

CalcephBin.time_jd_tdb_to_jd_tcb

CalcephBin.time_jd_tdb_to_jd_tcb(jd0_tdb, jdfrac_tdb) → jd0_tcb, jdfrac_tcb

Parameters:

jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

Integer part of Julian Date (TCB), Fractional part of Julian Date (TCB)

Return type:

float, float

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:

peph = CalcephBin.open("example_lsk.tls")
# convert the julian day 2450083.1267361110076308 TDB to the julian day TCB
[jd0, jdfrac] = peph.time_jd_tdb_to_jd_tcb(2450083.0, 0.1267361110076308);
printf("%f %.16f\n", jd0, jdfrac) # print  2450083.000000 0.1268436964601278
peph.close()

CalcephBin.time_jd_tcb_to_jd_tdb

CalcephBin.time_jd_tcb_to_jd_tdb(jd0_tcb, jdfrac_tcb) → jd0_tdb, jdfrac_tdb

Parameters:

jd0_tcb -- Integer part of Julian Date (TCB)
jdfrac_tcb -- Fractional part of Julian Date (TCB)

Returns:

Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)

Return type:

float, float

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

This is the inverse operation of CalcephBin.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:

peph = CalcephBin.open("example_lsk.tls")
# convert the julian day 2450083.126843696460127 TCB to the julian day TDB
[jd0, jdfrac] = peph.time_jd_tcb_to_jd_tdb(2450083.0, 0.1268436964601278);
printf("%f %.16f\n", jd0, jdfrac) # print 22450083.000000  0.1267361110076308
peph.close()

CalcephBin.time_cal_utc_to_jd_tdb

CalcephBin.time_cal_utc_to_jd_tdb(yy, month, day, hh, min, sec) → jd0_tdb, jdfrac_tdb

param yy:

Year

param month:

Month

param day:

Day

param hh:

Hour

param min:

Minute

param sec:

Second

return:

Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)

rtype:

float, float

Returns:: 0 on success, 1 on error

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:

Converts the UTC calendar date to a UTC Julian Date.
Computes the difference between UTC and TT (Terrestrial Time) using leap second data.
Converts TT to TDB using CalcephBin.time_jd_tt_to_jd_tdb().

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

The following example converts a UTC calendar date to TDB:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert 2025-01-03T22:59:50.300 UTC to the julian day TDB
[jd0, jdfrac] = peph.time_cal_utc_to_jd_tdb(2025, 1, 3, 22, 59, 50.3);
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4590218057855964
peph.close()

CalcephBin.time_jd_tdb_to_cal_utc

CalcephBin.time_jd_tdb_to_cal_utc(jd0_tdb, jdfrac_tdb) → yy, month, day, hh, min, sec

Parameters:

jd0_tdb -- Integer part of the TDB Julian Date
jdfrac_tdb -- Fractional part of the TDB Julian Date

Returns:

Year, Month [1–12], Day [1–31], Hour [0–23], Minute [0–59], seconds [0.0–61.0[

Return type:

int, int, int, int, int, float

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

This is the inverse operation of CalcephBin.time_cal_utc_to_jd_tdb().

The transformation chain performed is:

Converts TDB to TT using CalcephBin.time_jd_tdb_to_jd_tt().
Computes the difference between TT and UTC (using leap seconds).
Converts the resulting UTC Julian Date into calendar components.

The function requires that the ephemeris file self contains the necessary time constants.

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

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the julian day 2460679.45902180578559637 TDB to the calendar date UTC
[yy, mo, dd, hh,mi, ss] = peph.time_jd_tdb_to_cal_utc(2460679.0, 0.45902180578559637);
printf("%d-%d-%d %d:%d:%.6f\n", yy, mo, dd, hh,mi, ss) # print  2025-1-3 22:59:50.300007
peph.close()

CalcephBin.time_str_utc_to_jd_tdb

CalcephBin.time_str_utc_to_jd_tdb(str) → jd0_tdb, jdfrac_tdb

Parameters:: str -- UTC time string to parse
Returns:: Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)
Return type:: float, float

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:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the calendar date UTC to the julian day TDB
[jd0, jdfrac] = peph.time_str_utc_to_jd_tdb("2025-01-03T22:59:50.300");
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4590218057855964
peph.close()

CalcephBin.time_str_any_to_jd_tdb

CalcephBin.time_str_any_to_jd_tdb(str) → jd0_tdb, jdfrac_tdb

Parameters:: str -- Time string to parse
Returns:: Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)
Return type:: float, float

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:

TDB: No conversion needed.
TT: Performs the transformation TT → TDB.
TAI: Performs the transformation chain TAI → TT → TDB.
UTC: Performs the transformation chain UTC → TAI → TT → TDB.

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

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

The following example converts a TAI string to TDB:

peph = CalcephBin.open("example_lsk.tls")
peph.time_set_relationship_tt_tdb(1);
# convert the calendar date UTC to the julian day TDB
[jd0, jdfrac] = peph.time_str_any_to_jd_tdb("2025-01-03T22:59:50.300 UTC");
printf("%f %.16f\n", jd0, jdfrac) # print 2460679.000000 0.4590218057855964
peph.close()

CalcephBin.time_str_spacecraft_clock_to_jd_tdb

CalcephBin.time_str_spacecraft_clock_to_jd_tdb(target, strdate) → jd0_tdb, jdfrac_tdb

Parameters:

target -- NAIF ID of the spacecraft
strdate -- Spacecraft clock string (e.g., "1/1234:56")

Returns:

Integer part of Julian Date (TDB), Fractional part of Julian Date (TDB)

Return type:

float, float

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 CalcephBin.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:

peph = CalcephBin.open(cellstr({'example_lsk.tls', 'example_sclk.tsc'}))
peph.time_set_relationship_tt_tdb(1);
[jd0, jdfrac] = peph.time_str_spacecraft_clock_to_jd_tdb(28, "1/0707109102:11026");
printf("%f %.16f\n", jd0, jdfrac) # print 2459728.000000 0.6339573152363300
peph.close();

CalcephBin.time_jd_tdb_to_str_spacecraft_clock

CalcephBin.time_jd_tdb_to_str_spacecraft_clock(eph, target, jd0_tdb, jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
target -- NAIF ID of the spacecraft
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

Output spacecraft clock time string

Return type:

str

Returns:

returns 0 or an exception if an error occurs, otherwise a non-zero value.

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

This is the inverse operation of CalcephBin.time_str_spacecraft_clock_to_jd_tdb(). The input Julian Date is provided as two double-precision numbers (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 Barycentric Dynamical Time (TDB) and Terrestrial Time (TT), additional kernels are required depending on the configuration set by CalcephBin.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:

peph = CalcephBin.open(cellstr({'example_lsk.tls', 'example_sclk.tsc'}))
peph.time_set_relationship_tt_tdb(1);
strdate = peph.time_jd_tdb_to_str_spacecraft_clock(28, 2459728, 0.63395731542095745681);
printf("%s\n", strdate) # print "1/0707109102:11026"
peph.close()