time_conversion
#
Conversions and computation on date and time.
This module provide a variety of functions to convert time and date from Julian Dates and calendar dates. Conversion between different time scales are also possible. Different helpers 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, the 1st of January 2000.
References#
Chapter 2 of: Kaplan, G. United States Naval Observatory Circular No. 179, The IAU Resolutions on Astronomical Reference Systems, Time Scales, and Earth Rotation Models.
This document can be accessed at the following link: https://www.usno.navy.mil/USNO/astronomicalapplications/publications/Circular_179.pdf/view
Functions#

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


Convert Julian days to a calendar date. 

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

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


Convert a Julian day to a Modified Julian day. 
Convert a Modified Julian day to a Julian day. 


Determine the number of full days that have passed in the year of a given calendar date. 

Create the calendar date from the year and the number of days in the year. 
Determine the number of seconds that have elapsed in the given Julian day. 


Assess wether a year is a leap year or not. 

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

Convert time from the TCB scale to the TDB scale. 

Convert time from the TBD scale to the TCB scale. 

Convert time from the TCG scale to the TT scale. 

Convert time from the TT scale to the TCG scale. 

Convert time from the TAI scale to the TT scale. 

Convert time from the TT scale to the TAI scale. 

Approximately convert time from the TT scale to the TDB scale. 
 calendar_date_to_julian_day(calendar_date: datetime.datetime) float #
Convert a calendar date to Julian days.
 Parameters:
calendar_date (datetime.datetime) – Datetime, using the default Python library. Both the date and the time (hour, minutes, and seconds), can be specified. Milliseconds are ignored.
 Returns:
Date in Julian days since January 1st 4713 BC.
 Return type:
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, epoch_since_julian_day_zero: float = 2451545.0) float #
Convert a calendar date to Julian days since a given epoch.
 Parameters:
calendar_date (datetime.datetime) – Datetime, using the default Python 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:
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:
Calendar date using the Datetime Python library, containing the date and time corresponding to the Julian date input.
 Return type:
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:
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:
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:
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:
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:
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
 calendar_date_to_day_of_year(calendar_date: datetime.datetime) float #
Determine the number of full days that have passed in the year of a given calendar date.
 Parameters:
calendar_date (datetime.datetime) – Datetime, using the default Python library. Both the date and the time (hour, minutes, and seconds), can be specified. Milliseconds are ignored.
 Returns:
Number of full days that have passed in the year at the given calendar date.
 Return type:
Examples
In this example, the number of days that have passed in 2020 when the date is the 2nd of May is computed.
# Define the 2nd of May 2020 date = datetime.datetime(2020, 5, 2) # Compute the number of full days that have passed in 2020 when at the given date days_passed = time_conversion.calendar_date_to_day_of_year(date) # Print the converted output print(J2000) # prints 122.0
 year_and_days_in_year_to_calendar_date(year: int, days_in_year: int) datetime.datetime #
Create the calendar date from the year and the number of days in the year.
Can be seen as the inverse function of
calendar_date_to_day_of_year()
. Parameters:
 Returns:
Corresponding calendar date.
 Return type:
Examples
In this example, the calendar date corresponding to when 122 days have passed in 2020 is computed.
# Compute the calendar date when 122 days have passed in 2020 date = time_conversion.year_and_days_in_year_to_calendar_date(2020, 122) # Print the converted output print(J2000) # prints datetime.datetime(2020, 5, 2, 0, 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:
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:
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 nonleap 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:
 Returns:
Number of days in the month of the given year.
 Return type:
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:
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()
.
 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.
 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()
.
 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.
 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()
.