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

calceph_time_jd_to_cal

int calceph_time_jd_to_cal(t_calcephbin *eph, int timescale, double jd0, double jdfrac, int *yy, int *month, int *day, int *hh, int *min, double *sec)

Parameters:

eph -- ephemeris descriptor
timescale -- timescale of the input date and result ( see Timescale constant for the available timescales)
jd0 -- Integer part of Julian Date
jdfrac -- Fractional part of Julian Date
yy -- Year
month -- Month [1–12]
day -- Day [1–31]
hh -- Hour [0–23]
min -- Minute [0–59]
sec -- seconds [0.0–61.0[

Returns:

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:

t_calcephbin *peph;
double jd0 = 2451545.0; /* J2000.0 */
double jdfrac = 0.5;    /* 12h */
int yy, mm, dd, hh, min;
double sec;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* convert JD to Calendar (UTC) */
    if (calceph_time_jd_to_cal(peph, CALCEPH_UTC, jd0, jdfrac,
                               &yy, &mm, &dd, &hh, &min, &sec) != 0)
    {
        printf("Date: %d-%d-%d %d:%d:%f\n", yy, mm, dd, hh, min, sec);
    }

    /* close the file */
    calceph_close(peph);
}

calceph_time_cal_to_jd

int calceph_time_cal_to_jd(t_calcephbin *eph, int timescale, int yy, int month, int day, int hh, int min, double sec, double *jd0, double *jdfrac)

Parameters:

eph -- ephemeris descriptor
timescale -- timescale of the input date and result ( see Timescale constant for the available timescales)
yy -- Year
month -- Month [1–12]
day -- Day [1–31]
hh -- Hour [0–23]
min -- Minute [0–59]
sec -- Seconds [0.0–61.0[
jd0 -- Integer part of Julian Date
jdfrac -- Fractional part of Julian Date

Returns:

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:

t_calcephbin *peph;
double jd0, jdfrac;
int yy = 2000, mm = 1, dd = 1;
int hh = 12, min = 0;
double sec = 0.0;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* convert Calendar (UTC) to JD */
    if (calceph_time_cal_to_jd(peph, CALCEPH_UTC, yy, mm, dd, hh, min, sec,
                               &jd0, &jdfrac) != 0)
    {
        printf("Julian Date: %f + %f\n", jd0, jdfrac);
    }

    /* close the file */
    calceph_close(peph);
}

calceph_time_str_to_jd

int calceph_time_str_to_jd(t_calcephbin *eph, int timescale, const char *str, double *jd0, double *jdfrac)

Parameters:

eph -- ephemeris descriptor
timescale -- timescale of the input date and result ( see Timescale constant for the available timescales)
str -- Input time string to be parsed
jd0 -- Integer part of Julian Date
jdfrac -- Fractional part of Julian Date

Returns:

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:

t_calcephbin *peph;
double jd0, jdfrac;
const char *str = "2000-01-01T12:00:00";

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Parse string as UTC and convert to the julian day UTC */
    if (calceph_time_str_to_jd(peph, CALCEPH_UTC, str, &jd0, &jdfrac) != 0)
    {
        printf("Julian Date from string: %f + %f\n", jd0, jdfrac);
    }

    /* close the file */
    calceph_close(peph);
}

calceph_time_set_relationship_tt_tdb

int calceph_time_set_relationship_tt_tdb(t_calcephbin *eph, int model)

Parameters:

eph -- ephemeris descriptor
model --

Relationship model

0: use of calceph_compute_unit()

1: use the model based on TLS file

Returns:

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 calceph_time_jd_tdb_to_jd_tt() and calceph_time_jd_tt_to_jd_tdb().

The supported values for the model argument are:

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

t_calcephbin *peph;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Force using the default model based on TLS file for TT-TDB */
    if (calceph_time_set_relationship_tt_tdb(peph, 1) != 0)
    {
        printf("Relationship set to model 1.\n");
    }

    calceph_close(peph);
}

calceph_time_jd_tdb_to_jd_tt

int calceph_time_jd_tdb_to_jd_tt(t_calcephbin *eph, double jd0_tdb, double jdfrac_tdb, double *jd0_tt, double *jdfrac_tt)

Parameters:

eph -- ephemeris descriptor
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)
jd0_tt -- Integer part of Julian Date (TT)
jdfrac_tt -- Fractional part of Julian Date (TT)

Returns:

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

The following example converts a TDB date to TT:

t_calcephbin *peph;
double jd0_tdb = 2451545.0;
double jdfrac_tdb = 0.5;
double jd0_tt, jdfrac_tt;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Convert TDB to TT */
    if (calceph_time_jd_tdb_to_jd_tt(peph, jd0_tdb, jdfrac_tdb,
                                     &jd0_tt, &jdfrac_tt) != 0)
    {
        printf("TT Date: %f + %f\n", jd0_tt, jdfrac_tt);
    }

    calceph_close(peph);
}

calceph_time_jd_tt_to_jd_tdb

int calceph_time_jd_tt_to_jd_tdb(t_calcephbin *eph, double jd0_tt, double jdfrac_tt, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
jd0_tt -- Integer part of Julian Date (TT)
jdfrac_tt -- Fractional part of Julian Date (TT)
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

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

t_calcephbin *peph;
double jd0_tt = 2451545.0;
double jdfrac_tt = 0.5;
double jd0_tdb, jdfrac_tdb;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Convert TT to TDB */
    if (calceph_time_jd_tt_to_jd_tdb(peph, jd0_tt, jdfrac_tt,
                                     &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Date: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_jd_tdb_to_jd_tcb

int calceph_time_jd_tdb_to_jd_tcb(t_calcephbin *eph, double jd0_tdb, double jdfrac_tdb, double *jd0_tcb, double *jdfrac_tcb)

Parameters:

eph -- ephemeris descriptor
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)
jd0_tcb -- Integer part of Julian Date (TCB)
jdfrac_tcb -- Fractional part of Julian Date (TCB)

Returns:

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:

t_calcephbin *peph;
double jd0_tdb = 2451545.0;
double jdfrac_tdb = 0.5;
double jd0_tcb, jdfrac_tcb;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Convert TDB to TCB */
    if (calceph_time_jd_tdb_to_jd_tcb(peph, jd0_tdb, jdfrac_tdb,
                                     &jd0_tcb, &jdfrac_tcb) != 0)
    {
        printf("TCB Date: %f + %f\n", jd0_tcb, jdfrac_tcb);
    }

    calceph_close(peph);
}

calceph_time_jd_tcb_to_jd_tdb

int calceph_time_jd_tcb_to_jd_tdb(t_calcephbin *eph, double jd0_tcb, double jdfrac_tcb, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
jd0_tcb -- Integer part of Julian Date (TCB)
jdfrac_tcb -- Fractional part of Julian Date (TCB)
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

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 calceph_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:

t_calcephbin *peph;
double jd0_tcb = 2451545.0;
double jdfrac_tcb = 0.5;
double jd0_tdb, jdfrac_tdb;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Convert TCB to TDB */
    if (calceph_time_jd_tcb_to_jd_tdb(peph, jd0_tcb, jdfrac_tcb,
                                     &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Date: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_cal_utc_to_jd_tdb

int calceph_time_cal_utc_to_jd_tdb(t_calcephbin *eph, int yy, int month, int day, int hh, int min, double sec, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
yy -- Year
month -- Month
day -- Day
hh -- Hour
min -- Minute
sec -- Second
jd0_tdb -- Integer part of the resulting TDB Julian Date
jdfrac_tdb -- Fractional part of the resulting TDB Julian Date

Returns:

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:

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 calceph_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 calceph_time_set_relationship_tt_tdb().

The following example converts a UTC calendar date to TDB:

t_calcephbin *peph;
double jd0_tdb, jdfrac_tdb;
int yy = 2010, mm = 6, dd = 1;
int hh = 0, min = 0;
double sec = 0.0;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Direct conversion: UTC Calendar -> TDB JD */
    if (calceph_time_cal_utc_to_jd_tdb(peph, yy, mm, dd, hh, min, sec,
                                       &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Julian Date: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_jd_tdb_to_cal_utc

int calceph_time_jd_tdb_to_cal_utc(t_calcephbin *eph, double jd0_tdb, double jdfrac_tdb, int *yy, int *month, int *day, int *hh, int *min, double *sec)

Parameters:

eph -- ephemeris descriptor
jd0_tdb -- Integer part of the TDB Julian Date
jdfrac_tdb -- Fractional part of the TDB Julian Date
yy -- Year
month -- Month
day -- Day
hh -- Hour
min -- Minute
sec -- Second

Returns:

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

The transformation chain performed is:

Converts TDB to TT using calceph_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 associated to eph contains the necessary time constants.

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

t_calcephbin *peph;
double jd0_tdb = 2455348.5;
double jdfrac_tdb = 0.0;
int yy, mm, dd, hh, min;
double sec;

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Direct conversion: TDB JD -> UTC Calendar */
    if (calceph_time_jd_tdb_to_cal_utc(peph, jd0_tdb, jdfrac_tdb,
                                       &yy, &mm, &dd, &hh, &min, &sec) != 0)
    {
        printf("UTC Date: %d-%d-%d %d:%d:%f\n", yy, mm, dd, hh, min, sec);
    }

    calceph_close(peph);
}

calceph_time_str_utc_to_jd_tdb

int calceph_time_str_utc_to_jd_tdb(t_calcephbin *eph, const char *str, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
str -- UTC time string to parse
jd0_tdb -- Integer part of the resulting TDB Julian Date
jdfrac_tdb -- Fractional part of the resulting TDB Julian Date

Returns:

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:

t_calcephbin *peph;
double jd0_tdb, jdfrac_tdb;
const char *utc_str = "2010-06-01T00:00:00";

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Parse UTC string and convert directly to TDB */
    if (calceph_time_str_utc_to_jd_tdb(peph, utc_str, &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Julian Date: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_str_any_to_jd_tdb

int calceph_time_str_any_to_jd_tdb(t_calcephbin *eph, const char *str, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
str -- Time string to parse
jd0_tdb -- Integer part of the resulting TDB Julian Date
jdfrac_tdb -- Fractional part of the resulting TDB Julian Date

Returns:

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

The following example converts a TAI string to TDB:

t_calcephbin *peph;
double jd0_tdb, jdfrac_tdb;
/* String with explicit timescale */
const char *str = "2010-06-01T00:00:00 TAI";

/* open the ephemeris file */
peph = calceph_open("example_lsk.tls");
if (peph != NULL)
{
    /* Parse string (detecting TAI) and convert to TDB */
    if (calceph_time_str_any_to_jd_tdb(peph, str, &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Julian Date from TAI string: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_str_spacecraft_clock_to_jd_tdb

int calceph_time_str_spacecraft_clock_to_jd_tdb(t_calcephbin *eph, int target, const char *str, double *jd0_tdb, double *jdfrac_tdb)

Parameters:

eph -- ephemeris descriptor
target -- NAIF ID of the spacecraft
str -- Spacecraft clock string (e.g., "1/1234:56")
jd0_tdb -- Integer part of Julian Date (TDB)
jdfrac_tdb -- Fractional part of Julian Date (TDB)

Returns:

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 calceph_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:

t_calcephbin *peph;
double jd0_tdb, jdfrac_tdb;
int target = 28;
const char *str = "1/0707109102:11026";
const char *filenames[] = {"example_sclk.tsc", "example_lsk.tls"};

/* open the ephemeris files */
peph = calceph_open_array(2, filenames);
calceph_time_set_relationship_tt_tdb(peph, 1);

if (peph != NULL)
{
    /* Convert SCLK string to TDB */
    if (calceph_time_str_spacecraft_clock_to_jd_tdb(peph, target, str,
                                                    &jd0_tdb, &jdfrac_tdb) != 0)
    {
        printf("TDB Date: %f + %f\n", jd0_tdb, jdfrac_tdb);
    }

    calceph_close(peph);
}

calceph_time_jd_tdb_to_str_spacecraft_clock

int calceph_time_jd_tdb_to_str_spacecraft_clock(t_calcephbin *eph, int target, double jd0_tdb, double jdfrac_tdb, t_calcephcharvalue str)

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)
str -- Output string buffer

Returns:

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

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 calceph_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:

t_calcephbin *peph;
double jd0_tdb = 2459728.0;
double jdfrac_tdb = 0.63395731542095745681;
int target = 28;
t_calcephcharvalue str;
const char *filenames[] = {"example_sclk.tsc", "example_lsk.tls"};

/* open the ephemeris files */
peph = calceph_open_array(2, filenames);

calceph_time_set_relationship_tt_tdb(peph, 1);

if (peph != NULL)
{
    /* Convert TDB to SCLK string */
    if (calceph_time_jd_tdb_to_str_spacecraft_clock(peph, target,
                                                    jd0_tdb, jdfrac_tdb, str) != 0)
    {
        printf("SCLK string: %s\n", str);
    }

    calceph_close(peph);
}