time_conversion#

Conversions and computation on date and time.

This module provide a variety of functions to convert times and dates from Julian Dates, calendar dates and epochs. Conversion between different time scales (UTC, TDB, TT, etc.) are also possible. Conversions between time scales make extensive use of the SOFA library. Different helper functions are also included to ease the most common operation on dates and times.

Notes#

  • Unless specified otherwise, the time used in Tudatpy is in seconds since J2000, noon on the 1st of January 2000 (e.g., this epoch defines \(t=0\))

  • Tudat uses two different classes for date and time. One is the regular datetime from the Python datetime library. The other is a Tudat-native Datetime class, which allows finer resolution for time definitions, and allows for easier convesion to time representations (seconds since epoch, Julian day, modified Julian day). You can convert between the two using the datetime_to_tudat() and datetime_to_python() functions.

References#

Functions#

datetime_to_tudat(datetime)

Function to convert a Python datetime.datetime object to a Tudat DateTime object.

datetime_to_python(datetime)

Function to convert a Tudat DateTime object to a Python datetime.datetime object.

calendar_date_to_julian_day(calendar_date)

Convert a calendar date to Julian days.

calendar_date_to_julian_day_since_epoch(...)

Convert a calendar date to Julian days since a given epoch.

julian_day_to_calendar_date(julian_day)

Convert Julian days to a calendar date.

julian_day_to_seconds_since_epoch(julian_day)

Convert Julian days to seconds since a given epoch.

seconds_since_epoch_to_julian_day(...[, ...])

Convert Jseconds since a given epoch to a Julian day.

seconds_since_epoch_to_julian_years_since_epoch(...)

Convert the number of seconds since a given (unspecified) epoch to Julian years since the same epoch.

seconds_since_epoch_to_julian_centuries_since_epoch(...)

Convert the number of seconds since a given (unspecified) epoch to Julian centuries since the same epoch.

julian_day_to_modified_julian_day(julian_day)

Convert a Julian day to a Modified Julian day.

modified_julian_day_to_julian_day(...)

Convert a Modified Julian day to a Julian day.

calculate_seconds_in_current_julian_day(...)

Determine the number of seconds that have elapsed in the given Julian day.

is_leap_year(year)

Assess wether a year is a leap year or not.

get_days_in_month(month, year)

Get the number of days in the month of a given year.

TCB_to_TDB(TCB_time)

Convert time from the TCB scale to the TDB scale.

TDB_to_TCB(TDB_time)

Convert time from the TBD scale to the TCB scale.

TCG_to_TT(TCG_time)

Convert time from the TCG scale to the TT scale.

TT_to_TCG(TT_time)

Convert time from the TT scale to the TCG scale.

TAI_to_TT(TAI_time)

Convert time from the TAI scale to the TT scale.

TT_to_TAI(TT_time)

Convert time from the TT scale to the TAI scale.

TT_to_TDB_approximate(TT_time)

Approximately convert time from the TT scale to the TDB scale.

epoch_from_date_time_components(year, month, ...)

Computes the epoch as seconds since J2000 from the entries of the current date and time.

epoch_from_date_time_iso_string(iso_datetime)

Computes the epoch as seconds since J2000 from an ISO datetime string.

epoch_from_date_time_iso_string(iso_datetime)

Computes the epoch as seconds since J2000 from an ISO datetime string.

date_time_from_epoch(epoch)

Creates a Tudat-native DateTime object from the seconds since J2000.

date_time_from_iso_string(iso_datetime)

Creates a Tudat-native DateTime object from an ISO datetime string.
datetime_to_tudat(datetime: datetime.datetime) → tudat::basic_astrodynamics::DateTime#

Function to convert a Python datetime.datetime object to a Tudat DateTime object. The Tudat-native alternative has the advantage of providing sub-femtosecond resolution, as opposed to the microsecond resolution of the Python version

Parameters

datetime (datetime.datetime) – Datetime object, using the Python datetime library. Both the date and the time (hour, minutes, and seconds), can be specified, up to millisecond resolution.

Returns

DateTime object defined in Tudat

Return type

DateTime

datetime_to_python(datetime: tudat::basic_astrodynamics::DateTime) → datetime.datetime#

Function to convert a Tudat DateTime object to a Python datetime.datetime object. This is the inverse of the datetime_to_tudat() function

Parameters

datetime (DateTime) – Tudat-native Datetime object. Both the date and the time (hour, minutes, and seconds), can be specified, up to sub-femtosecond resolution.

Returns

Datetime object, using the Python datetime library

Return type

datetime.datetime

calendar_date_to_julian_day(calendar_date: datetime.datetime) → float#

Convert a calendar date to Julian days.

Parameters

calendar_date (datetime.datetime) – Datetime object, using the Python datetime library. Both the date and the time (hour, minutes, and seconds), can be specified, up to millisecond resolution.

Returns

Julian day number (days since noon January 1st 4713 BC.)

Return type

float

Examples

In this example, the calendar date of the 21st of May 2022 at 13:52 and 41 seconds is converted to Julian days.

# Define the calendar date using datetime
calendar_date = datetime.datetime(2022, 5, 21, 13, 52, 41)
# Convert the calendar date to Julian days since January 1st 4713 BC
julian_date = time_conversion.calendar_date_to_julian_day(calendar_date)
# Print the converted output
print(julian_date)  # prints 2459721.0782523146
calendar_date_to_julian_day_since_epoch(calendar_date: datetime.datetime) → float#

Convert a calendar date to Julian days since a given epoch.

Parameters

  • calendar_date (datetime.datetime) – Datetime object, using the Python datetime library. Both the date and the time (hour, minutes, and seconds), can be specified. Milliseconds are ignored.

  • epoch_since_julian_day_zero (float, default = constants.JULIAN_DAY_ON_J2000) – Epoch since when the Julian days have to be counted. By default, set to constants.JULIAN_DAY_ON_J2000 (2451545.0) corresponding to the 1st of January 2000.

Returns

Date in Julian days since the given epoch.

Return type

float

Examples

In this example, the calendar date of the 21st of May 2022 at 13:52 and 41 seconds is converted to Julian days since J2000 (the 1st of January 2000).

# Define the calendar date using datetime
calendar_date = datetime.datetime(2022, 5, 21, 13, 52, 41)
# Convert the calendar date to Julian days since J2000
julian_date = time_conversion.calendar_date_to_julian_day_since_epoch(calendar_date)
# Print the converted output
print(julian_date)  # prints 8176.07825231459
julian_day_to_calendar_date(julian_day: float) → datetime.datetime#

Convert Julian days to a calendar date.

Inverse function of calendar_date_to_julian_day().

Parameters

julian_day (float) – Date in Julian days since January 1st 4713 BC.

Returns

Datetime object, using the Python datetime library, containing the date and time corresponding to the Julian date input.

Return type

datetime.datetime

Examples

In this example, the Julian date 2459721.0783 (in days since January 1st 4713 BC), is converted to a calendar date.

# Define the Julian date in days since January 1st 4713 BC
julian_date = 2459721.0783
# Convert the Julian date to a calendar date
calendar_date = time_conversion.julian_day_to_calendar_date(julian_date)
# Print the converted output
print(calendar_date)  # prints datetime.datetime(2022, 5, 21, 13, 52, 45)
julian_day_to_seconds_since_epoch(julian_day: float, epoch_since_julian_day_zero: float = 2451545.0) → float#

Convert Julian days to seconds since a given epoch.

Parameters

  • julian_day (float) – Date in Julian days since January 1st 4713 BC.

  • epoch_since_julian_day_zero (float, default = constants.JULIAN_DAY_ON_J2000) – Epoch since when the Julian days have to be counted. By default, set to constants.JULIAN_DAY_ON_J2000 (2451545.0), corresponding to the 1st of January 2000.

Returns

Seconds since the Julian date and the given epoch.

Return type

float

Examples

In this example, the Julian date 2459721.0783 (in days since January 1st 4713 BC), is converted to seconds since J2000 (January 1st 2000).

# Define the Julian date in days since January 1st 4713 BC
julian_date = 2459721.0783
# Convert the Julian date to the number of seconds since J2000
seconds_since_J2000 = time_conversion.julian_day_to_seconds_since_epoch(julian_date)
# Print the converted output
print(seconds_since_J2000)  # prints 706413165.1200145
seconds_since_epoch_to_julian_day(seconds_since_epoch: float, epoch_since_julian_day_zero: float = 2451545.0) → float#

Convert Jseconds since a given epoch to a Julian day.

Inverse function of julian_day_to_seconds_since_epoch().

Parameters

  • julian_day (float) – Date in Julian days since January 1st 4713 BC.

  • epoch_since_julian_day_zero (float, default = constants.JULIAN_DAY_ON_J2000) – Epoch since when the Julian days have to be counted. By default, set to constants.JULIAN_DAY_ON_J2000 (2451545.0), corresponding to the 1st of January 2000.

Returns

Seconds since the Julian date and the given epoch.

Return type

float

Examples

In this example, the Julian date 2459721.0783 (in days since January 1st 4713 BC), is converted to seconds since J2000 (January 1st 2000).

# Define the Julian date in days since January 1st 4713 BC
julian_date = 2459721.0783
# Convert the Julian date to the number of seconds since J2000
seconds_since_J2000 = time_conversion.julian_day_to_seconds_since_epoch(julian_date)
# Print the converted output
print(seconds_since_J2000)  # prints 706413165.1200145
seconds_since_epoch_to_julian_years_since_epoch(seconds_since_epoch: float) → float#

Convert the number of seconds since a given (unspecified) epoch to Julian years since the same epoch.

Parameters

seconds_since_epoch (float) – Seconds elapsed since a given (unspecified) epoch.

Returns

Julian years since the specified epoch.

Since this is a float, not a integer, meaning that the fraction of the year is also included.

Return type

float

Examples

In this example, 706413165.12 seconds since a given epoch are converted to Julian years since the same epoch.

# Define the number of seconds elapsed
seconds_since_epoch = 706413165.12
# Convert the number of seconds to Julian years
julian_years = time_conversion.seconds_since_epoch_to_julian_years_since_epoch(seconds_since_epoch)
# Print the converted output
print(julian_years)  # prints 22.38488240930869
seconds_since_epoch_to_julian_centuries_since_epoch(seconds_since_epoch: float) → float#

Convert the number of seconds since a given (unspecified) epoch to Julian centuries since the same epoch.

Parameters

seconds_since_epoch (float) – Seconds elapsed since a given (unspecified) epoch.

Returns

Julian centuries since the specified epoch.

Since this is a float, not a integer, meaning that the fraction of the century is also included.

Return type

float

Examples

In this example, 706413165.12 seconds since a given epoch are converted to Julian centuries since the same epoch.

# Define the number of seconds elapsed
seconds_since_epoch = 706413165.12
# Convert the number of seconds to Julian centuries
julian_centuries = time_conversion.seconds_since_epoch_to_julian_centuries_since_epoch(seconds_since_epoch)
# Print the converted output
print(julian_centuries)  # prints 0.2238488240930869
julian_day_to_modified_julian_day(julian_day: float) → float#

Convert a Julian day to a Modified Julian day.

Parameters

julian_day (float) – Date in Julian days (number of days since January 1st 4713 BC).

Returns

Date in modified Julian days (number of days since November 17th 1858).

Return type

float

Examples

In this example, the Julian date 2451545.0 (J2000) is converted to a modified Julian date.

# Convert from Julian Days to Modified Julian Days
MJD = time_conversion.julian_day_to_modified_julian_day(constants.JULIAN_DAY_ON_J2000)
# Print the converted output
print(MJD)  # prints 51544.5
modified_julian_day_to_julian_day(modified_julian_day: float) → float#

Convert a Modified Julian day to a Julian day.

Inverse function of julian_day_to_modified_julian_day().

Parameters

modified_julian_day (float) – Date in modified Julian days (number of days since November 17th 1858).

Returns

Date in Julian days (number of days since January 1st 4713 BC).

Return type

float

Examples

In this example, the Modified Julian date 51544.5 ( corresponding to J2000) is converted to a modified Julian date.

# Define J2000 in Modified Julian Days
J2000_MJD = 51544.5
# Convert from Modified Julian Days to Julian Days
J2000 = time_conversion.modified_julian_day_to_julian_day(J2000_MJD)
# Print the converted output
print(J2000)  # prints 2451545.0
calculate_seconds_in_current_julian_day(julian_day: float) → float#

Determine the number of seconds that have elapsed in the given Julian day.

Parameters

julian_day (float) – Date in Julian days (number of days since January 1st 4713 BC).

Returns

Number of seconds that have passed in the given Julian day.

Return type

float

Examples

In this example, the number of seconds that have elapsed at the Julian day 2451545.2 is computed.

# Compute the number of seconds that have passed in the given Julian day
seconds_passed = time_conversion.calculate_seconds_in_current_julian_day(constants.JULIAN_DAY_ON_J2000)
# Print the converted output
print(seconds_passed)  # prints 43200.0
is_leap_year(year: int) → bool#

Assess wether a year is a leap year or not.

Parameters

year (int) – Calendar year.

Returns

A value of True means that the year is a leap year.

Return type

bool

Examples

In this example, the first list should contains only True, and the second False, since the first list uses leap years and the second does not.

# Check known leap years
leap_years = [time_conversion.is_leap_year(year) for year in [2020, 2016, 2000, 2400]]
# Print the converted output
print(leap_years)  # prints [True, True, True, True]
# Check known non-leap years
non_leap_years = [time_conversion.is_leap_year(year) for year in [2021, 2022, 2100, 2001]]
# Print the converted output
print(non_leap_years)  # prints [False, False, False, False]
get_days_in_month(month: int, year: int) → int#

Get the number of days in the month of a given year.

Parameters

  • month (int) – Calendar month.

  • year (int) – Calendar year.

Returns

Number of days in the month of the given year.

Return type

int

Examples

In this example, the number of days in February for both 2021 and 2020 are computed.

# Check the number of days in February 2021
days_feb_2021 = time_conversion.get_days_in_month(2, 2021)
# Print the converted output
print(days_feb_2021)  # prints 28
# Check the number of days in February 2022
days_feb_2020 = time_conversion.get_days_in_month(2, 2020)
# Print the converted output
print(days_feb_2020)  # prints 29
TCB_to_TDB(TCB_time: float) → float#

Convert time from the TCB scale to the TDB scale.

The TCB scale is the Barycentric Coordinate Time, and the TDB scale is the Barycentric Dynamical Time.

Parameters

TCB_time (float) – Time in seconds since J2000, in the TCB time scale.

Returns

Time in seconds since J2000, in the TDB time scale.

Return type

float

Examples

In this example, the calendar date of the 17th of February 2022, at 15:41 and 2 seconds is first converted to Julian seconds since J2000. Then, this date and time is converted from the TCB scale to the TDB scale.

# Define the date and time
date = datetime.datetime(2022, 2, 17, 15, 41, 2)
# Convert it in Julian days since J2000
date_J2000 = time_conversion.calendar_date_to_julian_day(date)
# Convert it in Julian seconds since J2000
date_J2000_sec = time_conversion.julian_day_to_seconds_since_epoch(date_J2000)
# Check the date from the TCB scale to the TDB scale
date_TDB_scale = time_conversion.TCB_to_TDB(date_J2000_sec)
# Print the converted output
print(date_TDB_scale)  # prints 698384439.9176273
TDB_to_TCB(TDB_time: float) → float#

Convert time from the TBD scale to the TCB scale.

The TDB scale is the Barycentric Dynamical Time, and the TCB scale is the Barycentric Coordinate Time.

Inverse function of TCB_to_TDB().

Parameters

TDB_time (float) – Time in seconds since J2000, in the TDB time scale.

Returns

Time in seconds since J2000, in the TCB time scale.

Return type

float

TCG_to_TT(TCG_time: float) → float#

Convert time from the TCG scale to the TT scale.

The TCG scale is the Geocentric Coordinate Time, and the TT scale is the Terrestrial Time.

Parameters

TCG_time (float) – Time in seconds since J2000, in the TCG time scale.

Returns

Time in seconds since J2000, in the TT time scale.

Return type

float

TT_to_TCG(TT_time: float) → float#

Convert time from the TT scale to the TCG scale.

The TT scale is the Terrestrial Time, and the TCG scale is the Geocentric Coordinate Time.

Inverse function of TCG_to_TT().

Parameters

TT_time (float) – Time in seconds since J2000, in the TT time scale.

Returns

Time in seconds since J2000, in the TCG time scale.

Return type

float

TAI_to_TT(TAI_time: float) → float#

Convert time from the TAI scale to the TT scale.

The TAI scale is the International Atomic Time, and the TT scale is the Terrestrial Time.

Parameters

TAI_time (float) – Time in seconds since J2000, in the TAI time scale.

Returns

Time in seconds since J2000, in the TT time scale.

Return type

float

TT_to_TAI(TT_time: float) → float#

Convert time from the TT scale to the TAI scale.

The TT scale is the Terrestrial Time, and the TAI scale is the International Atomic Time.

Inverse function of TAI_to_TT().

Parameters

TT_time (float) – Time in seconds since J2000, in the TT time scale.

Returns

Time in seconds since J2000, in the TAI time scale.

Return type

float

TT_to_TDB_approximate(TT_time: float) → float#

Approximately convert time from the TT scale to the TDB scale.

The TT scale is the Terrestrial Time, and the TDB scale is the Barycentric Dynamical Time.

Parameters

TT_time (float) – Time in seconds since J2000, in the TT time scale.

Returns

Time in seconds since J2000, in the TDB time scale.

Return type

float

epoch_from_date_time_components(year: int, month: int, day: int, hour: int, minute: int, seconds: float) → float#

Computes the epoch as seconds since J2000 from the entries of the current date and time.

Computes the epoch as seconds since J2000. This function is added for convenience, and creates a DateTime object, and subsequently calls its epoch function

Parameters

  • year (int) – Calendar year

  • month (int) – Calendar month (value must be 1-12)

  • day (int) – Calendar day in current month, value must be larger than 0, and smaller or equal to the number of days in the month

  • hour (int) – Full hours into the current day (value must be 0-23)

  • minute (int) – Full minutes into the current hour (value must be 0-59)

  • seconds (float) – Number of seconds into the current minute. Note that this value is stored as long double in Tudat, which may be 64-bit or 80-bit (16 or 19 digits) depending on the compiler used.

Returns

Time in seconds since J2000.

Return type

float

epoch_from_date_time_iso_string(iso_datetime: str) → float#

Computes the epoch as seconds since J2000 from an ISO datetime string.

Computes the epoch as seconds since J2000. This function is added for convenience, and creates a DateTime object, and subsequently calls its epoch function

Parameters

iso_datetime (str) – Date and time as ISO compatible string (“YYYY-MM-DDTHH:MM:SS.SSSSS..”, where the T may be replaced with a space)

Returns

Time in seconds since J2000.

Return type

float

epoch_from_date_time_iso_string(iso_datetime: str) → float#

Computes the epoch as seconds since J2000 from an ISO datetime string.

Computes the epoch as seconds since J2000. This function is added for convenience, and creates a DateTime object, and subsequently calls its epoch function

Parameters

iso_datetime (str) – Date and time as ISO compatible string (“YYYY-MM-DDTHH:MM:SS.SSSSS..”, where the T may be replaced with a space)

Returns

Time in seconds since J2000.

Return type

float

date_time_from_epoch(epoch: float) → tudatpy.kernel.astro.time_conversion.DateTime#

Creates a Tudat-native DateTime object from the seconds since J2000.

Parameters

epoch (float) – Seconds since J2000

Returns

Tudat DateTime object.

Return type

DateTime

date_time_from_iso_string(iso_datetime: float) → tudatpy.kernel.astro.time_conversion.DateTime#

Creates a Tudat-native DateTime object from an ISO datetime string.

Parameters

iso_datetime (str) – Date and time as ISO compatible string (“YYYY-MM-DDTHH:MM:SS.SSSSS..”, where the T may be replaced with a space)

Returns

Tudat DateTime object.

Return type

DateTime

Classes#

DateTime

Class to store a calendar date and time of day, with high resolution.
class DateTime#

Class to store a calendar date and time of day, with high resolution.

Class to store a calendar date and time of day, with high resolution compared to Python datetime.datetime. This class stores the seconds as a long double variable in the C++ implementation, corresponding to about 16 or 19 digits of precision (depending on the compiler used). In either case, this will be sufficient for sub-femtosecond resolution. In addition, this class allows easy conversion to typical time representations in astrodynamics (seconds since J2000, Julian day, and modified Julian day).

day_of_year(self: tudatpy.kernel.astro.time_conversion.DateTime) → int#

Function to get the day number in the current year

Returns

Day number in the current year

Return type

int

epoch(self: tudatpy.kernel.astro.time_conversion.DateTime) → float#

Function to get the epoch in seconds since J2000 for the current date and time

Returns

Current epoch in seconds since J2000

Return type

float

iso_string(self: tudatpy.kernel.astro.time_conversion.DateTime, add_T: bool = False) → str#

Function to get the ISO-compatible string.

Function to get the current date and time as an ISO-compatible string (“YYYY-MM-DDTHH:MM:SS.SSSSS..”) where the seconds may be provided with any number of digits. The ‘T’ entry separating the date from the time may be omitted by setting the add_T parameter to false

Parameters

add_T (Bool) – Boolean denoting whether to use a ‘T’ or a blank space to separate the date from the time

Returns

ISO-compatible string representing the date and time

Return type

str

julian_day(self: tudatpy.kernel.astro.time_conversion.DateTime) → float#

Function to get the epoch as Julian day for the current date and time

Returns

Current Julian day

Return type

float

modified_julian_day(self: tudatpy.kernel.astro.time_conversion.DateTime) → float#

Function to get the epoch as modified Julian day for the current date and time

Returns

Current modified Julian day

Return type

float

property day#

Calendar day in current month, value must be larger than 0, and smaller or equal to the number of days in the month

Type

int

property hour#

Full hours into the current day (value must be 0-23)

Type

int

property minute#

Full minutes into the current hour (value must be 0-59)

Type

int

property month#

Calendar month (value must be 1-12)

Type

int

property seconds#

Number of seconds into the current minute. Note that this value is stored as long double in Tudat, which may be 64-bit or 80-bit (16 or 19 digits) depending on the compiler used.

Type

float

property year#

Calendar year

Type

int