# Times and dates

A proper definition of epochs, time intervals, time scales, dates, *etc.* is essential for setting up a proper numerical simulation, and for data analysis. In Tudat, the time defined inside the numerical propagation is always defined using J2000 epoch (01-01-2000, 12:00:00) as reference epoch, in TBD scale. This choice and definition is ‘inherited’ from SPICE, which is typically used in Tudat to determine the state and orientation of solar system bodies. When defining or providing a `time`

to any function in Tudat, this is simply a `float`

(or `double`

in C++), which denotes the seconds since J2000 epoch (an alternative for a `float`

is described below). Note that the difference between TDB (dynamical barycentric time) and TT (terrestrial time) is purely periodic and on the order of millisecond. For many applications, the two can be see as equivalent.

However, seconds since J2000 in TBD is not a very intuitive quantity to provide for a user. Therefore, functionality is provided to convert between different time scale and representations:

Conversion between calendar dates and times and seconds since J2000

Conversion of time between different time scales (UTC, UT1, TAI, TDB, TT)

The use of a

`Time`

class, which uses a two-step representation of time, which ensures sub-picoseconds resolution over long time scales.

## Calendar dates and times

Tudat comes with its own class to represent an epoch as a calendar date and time, which is driven by the need for extremely accurate representations of time that occur in some astrodynamics applications, in particular with regards to tracking data (10 picoseconds of light-time error corresponds to 3 mm of range error).
The specifics are described in the `DateTime`

documentation. In summary, this class allows the definition of epochs with approximately femtosecond resolution. For compatibility, a conversion between the `datetime`

class from Python’s `datetime`

library is provided in Tudat, with the note that this class can represent time to microsecond resolution. The `DateTime`

class in Tudat contains member functions that allow it to be converted to seconds since J2000, Julian day, modified Julian day, or an ISO string representing time. An overview is given on the API documentation.

Below is an example of defining the current date and time through the Python `datetime`

class, or through Tudat’s `DateTime`

class.

from datetime import datetime from tudatpy.kernel.astro import time_conversion # Create Python datetime object python_datetime = datetime.fromisoformat('2023-06-20T00:05:23.281765') # Convert to Tudat DateTime object tudat_datetime = time_conversion.datetime_to_tudat( python_datetime ) # Extract single-valued epoch in different scales from Tudat object seconds_since_j2000 = tudat_datetime.epoch( ) julian_day = tudat_datetime.julian_day( ) modified_julian_day = tudat_datetime.modified_julian_day( )

note that the inverse operations, creating a `DateTime`

object from an epoch (`date_time_from_epoch()`

),
an iso string (`date_time_from_iso_string()`

), or directly from the year, month, day and time
(`DateTime`

constructor) are also available

In the above, the `epoch`

is a floating point value, that can be used as input to (for instance) a numerical propagation.
Note that this epoch may need to be converted to a different time scale (see below)

## Julian days

In astrodynamics, the use of a Julian day (full days since 12:00 on 01-01-4713BC of the Julian calendar) or modified Julian day (full days since 00:00 of 17-11-1858 of the Gregorian calendar)
continues to be prevalent. Although these time representations are not used directly inside Tudat, we do offer a number of useful conversion functions
to support (modified) Julian days as input or output. Both quantities can be extracted directly as attributes from the `DateTime`

class.
The function `seconds_since_epoch_to_julian_day()`

can be used to convert the ‘typical Tudat time of seconds since J2000 epoch to a Julian day,
and `julian_day_to_seconds_since_epoch()`

the inverse operation.
a Julian day

## Conversion between time scales

Users will often define epochs in UTC scale, whereas the Tudat propagation requires time in TDB scale. The different time scales are described very well in USNO circular 179. The Tudat methods for converting between time scales rely heavily in the SOFA software, for which the documentation on SOFA Time Scale and Calendar Tools provides additional useful information.

Tudat supports the automatic conversion between the following time scales:

Universal Time UT1, based on Earth rotation

Coordinated Universal Time UTC, the primary time standard used globally

International Atomic Time TAI, which differs from UTC through leap seconds (UTC incorporates leap seconds, TAI does not)

Terrestrial Time TT, equivalent to TAI with an offset of 32.184 seconds

Barycentric Dynamical Time TDB, the time scale in which solar system ephemerides are often disseminated, related to TT through a four-dimensional relativistic conversion linear scaling

Geocentric coordinate time TCG, a coordinate time for ‘geocentric’ applications, related to TT by a linear scaling

Barycentric coordinate time TCB, a coordinate time for ‘barycentric’ applications, related to TBD by a linear scaling

Conversion between each of these time scales can be done using the `TimeScaleConverter`

, which can convert an epoch from and to any one of the above time scales. Below is an example of how to convert an epoch from one time scale to another:

from tudatpy.kernel.astro import time_conversion # Create time scale converter object time_scale_converter = time_conversion.default_time_scale_converter( ) # Set the epoch in UTC scale (for instance from the above example using DateTime epoch_utc = tudat_datetime.epoch( ) epoch_tdb = time_scale_converter.convert_time( input_scale = time_conversion.utc_scale, output_scale = time_conversion.tdb_scale, input_value = epoch_utc )

The conversion between UTC and UT1 (the latter of which is used directly to compute Earth rotation) is based on the detailed Earth rotation model as defined in the IERS 2010 Conventions. The `default_time_scale_converter`

is initialized using default settings for small variations to Earth rotation (see the notes here on high-accuracy Earth rotation model). The conversion between geocentric scales (TT/TCG) and barycentric scales (TDB/TCB) is performed using the model implemented in SOFA for TT-TDB, which is a series expansion with about 800n terms, based on a numerical solution to the governing equation of the transformation. This conversion is accurate to the level of several nanoseconds. For higher accuracy in this conversion, numerical computation of these time scales, consistent with a given solar system ephemeris, should be used. Data for such conversions is shipped with recent INPOP ephemerides (for instance).

Formally, the conversion from TT to TDB (and therefore also UTC to TDB) depends on the geocentric position at which the time in TT/UTC is registered. This effect is very small, with the largest effect a daily periodic variation on the order of several microseconds.

## High-resolution Time representation

In addition to the `DateTime`

class described above, Tudat has a `Time`

class that allows time representation to be provided to about femtoseconds (`long double`

resolution for seconds in the current hour; which for most C++ compilers translates into a resolution of \(10^{-19}/3600\)) resolution. Unlike the `DateTime`

class, the `Time`

class supports arithmetic operations, so that it can be used to reprent an epoch (with the 0 value defined as J2000) or a time interval. Tudat can be compiled such that it uses this `Time`

class rather than a `float`

as an independnet variable of propagation, reference time for an observation, etc. However, this requires a recompilation of Tudat, and the present conda packages are not compiled with this option on (to enable this functionality in your own build, modify the definition of the `TIME_TYPE`

macro in tudatpy).