`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 conversion to time representations (seconds since epoch, Julian day, modified Julian day). You can convert between the two using the from_python_datetime() and to_python_datetime() methods.
A number of conversion functions take the current Julian day or modified Julian day (as a float) as input or output. This represents the number of days (86400 seconds) since noon January 1st 4713 BC, or midnight November 17th 1858 AD, respectively.
A number of conversion functions take the seconds/days/… “since epoch” as input or output.

References¶

Kaplan [13, Chapter 2]
IAU [27]
Petit and Luzum [17, Sections 5.5.3 and Chapter 10]

Functions¶

`date_time_components_to_epoch`(year, month, ...)	Computes the epoch as seconds since J2000 from the entries of the current date and time.
`iso_string_to_epoch`(iso_datetime)	Computes the epoch as seconds since J2000 from an ISO datetime string.
`julian_day_to_seconds_since_epoch`(julian_day)	Convert Julian days to seconds since a given 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.
`seconds_since_epoch_to_julian_day`(...[, ...])	Convert seconds since a given reference 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.
`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, using the following first-order approximation:
`TT_to_TDB`(TT_time, earth_fixed_position, 1]])	Convert time from the TT scale to the TDB scale.
`TDB_to_TT`(TDB_time, earth_fixed_position, 1]])	Convert time from the TDB scale to the TT scale.
`default_time_scale_converter`()	Function to create a time-scale converter object with default settings.

date_time_components_to_epoch(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 is equivalent to DateTime(...).to_epoch().

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

iso_string_to_epoch(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 is equivalent to DateTime.from_iso_string(...).to_epoch().

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

julian_day_to_seconds_since_epoch(julian_day: float, days_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.
days_since_julian_day_zero (float, default = constants.JULIAN_DAY_ON_J2000) – Reference epoch (in days since January 1st 4713 BC) since when the number of seconds 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

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

seconds_since_epoch_to_julian_day(seconds_since_epoch: float, days_since_julian_day_zero: float = 2451545.0) → float¶

Convert seconds since a given reference epoch to a Julian day.

Inverse function of julian_day_to_seconds_since_epoch().

Parameters:

seconds_since_epoch (float) – Seconds since days_since_julian_day_zero which are to be converted to date in Julian days.
days_since_julian_day_zero (float, default = constants.JULIAN_DAY_ON_J2000) – Reference epoch (in days since January 1st 4713 BC) since when the number of seconds 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 January 1st 4713 BC, as computed from the input parameters

Return type:

float

Examples

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

# Define the amount of seconds since January 1st 2000
seconds_since_J2000 = 706413165.1200145
# Convert the amount of seconds since J2000 to the Julian date
julian_date = time_conversion.seconds_since_epoch_to_julian_day(seconds_since_J2000)
# Print the converted output
print(julian_date)  # prints 2459721.0783

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.

Convert the number of seconds since a given (unspecified) epoch to Julian years since the same epoch. This is equivalent to converting a time interval in seconds to Julian years

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.

Convert the number of seconds since a given (unspecified) epoch to Julian years since the same epoch. This is equivalent to converting a time interval in seconds to Julian centuries

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

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.python_datetime_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, using the following first-order approximation:

\[t_{\text{TDB}} = t_{\text{TT}} + 0.001657 * \sin( 628.3076 T_{\text{TT}} + 6.2401 );\]

with \(t\) the epoch in seconds since J2000, \(T\) the epoch in centuries since J2000.

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

TT_to_TDB(TT_time: tudat::Time, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]]) → tudat::Time¶

Convert time from the TT scale to the TDB scale.

Convert time from the TT scale to the TDB scale, using the iauDtdb function in Sofa, which has an accuracy of 3 nanoseconds or better in the time span 1950-2050 To call the Sofa function, we assume UTC=UT1 for the UT1 input. For this function, UT1 is only used in this sofa function to compute the local solar time, which in turn is used to compute the time-modulation of the topocentric term (dependent on the ground station position). Since these terms have an amplitude at the microsecond level, the error induced by this assumption is negligible given the inherent quality of the Sofa model.

Parameters:

TT_time (float) – Time in seconds since J2000, in the TT time scale.
earth_fixed_position (numpy.ndarray, default=numpy.array([0, 0, 0])) – Earth-fixed position (e.g. in ITRF) that is used for detailed conversion between TDB and TT (induces a signature at the microsecond level)

Returns:

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

Return type:

float

TDB_to_TT(TDB_time: tudat::Time, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]]) → tudat::Time¶

Convert time from the TDB scale to the TT scale.

Convert time from the TT scale to the TDB scale, using the iauDtdb function in Sofa, which has an accuracy of 3 nanoseconds or better in the time span 1950-2050 To call the Sofa function, we assume UTC=UT1 and TT=TDB to compute UT1 from the input TDB. For this function, UT1 is only used in this sofa function to compute the local solar time, which in turn is used to compute the time-modulation of the topocentric term (dependent on the ground station position). Since these terms have an amplitude at the microsecond level, the error induced by this assumption is negligible given the inherent quality of the Sofa model.

Parameters:

TDB_time (float) – Time in seconds since J2000, in the TDB time scale.
earth_fixed_position (numpy.ndarray, default=numpy.array([0, 0, 0])) – Earth-fixed position (e.g. in ITRF) that is used for detailed conversion between TDB and TT (induces a signature at the microsecond level)

Returns:

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

Return type:

float

default_time_scale_converter() → tudatpy.kernel.astro.time_conversion.TimeScaleConverter¶

Function to create a time-scale converter object with default settings. In particular, it uses default settings for conversion between UT1 and UTC:

Corrections for semi-diurnal variations due to libration for a non-rigid Earth as per Table 5.1b of IERS Conventions 2010
Corrections diurnal and semidiurnal variations due to ocean tides as per Tables 8.2a and 8.2b of the IERS Conventions 2010
For epoch 01-01-1962 and later: linear interpolation (correcting for discontinuities during days with leap seconds) of daily corrections for UTC-UT1 from the eopc04_14_IAU2000.62-now.txt file in the tudat-resources directory
For epochs before 01-01-1962, where UTC-UT1 is not available from these files, we use the values if for :math:Delta T = UT1-TT` from here (back to year 1620). In this period, we set the approxomation UTC=UT1

See TimeScaleConverter for specific functionality and options for time-scale conversions.

Returns:: Object to convert between different terrestrial time scales.
Return type:: TimeScaleConverter

Enumerations¶

TimeScales

Enumeration of available time scales between which the TimeScaleConverter can automaticaly convert.

class TimeScales¶

Enumeration of available time scales between which the TimeScaleConverter can automaticaly convert.

Members:

tai_scale :

tt_scale :

tdb_scale :

utc_scale :

ut1_scale :

property name¶

Classes¶

`DateTime`	Class to store a calendar date and time of day, with high resolution.
`TimeScaleConverter`	Class to convert between different time scales (TAI, TT, TDB, UTC, UT1)

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

__init__(self: tudatpy.kernel.astro.time_conversion.DateTime, year: int, month: int, day: int, hour: int = 12, minute: int = 0, seconds: float = 0.0) → None¶

add_days(self: tudatpy.kernel.astro.time_conversion.DateTime, days_to_add: tudat::Time) → tudatpy.kernel.astro.time_conversion.DateTime¶

Function to create a new Tudat DateTime object by adding a number of days (86400 seconds) to an existing Tudat DateTime object

Note

This method does not modify the original DateTime object, but returns a new one with the added days.

Parameters:: days_to_add (float) – Number of days to add
Returns:: Tudat-native Datetime object created by adding the given number of days to the original DateTime
Return type:: DateTime

Examples

In this example, 1 day is added to a DateTime object to construct a new DateTime.

from tudatpy.astro.time_conversion import DateTime

dt = DateTime(2025, 1, 1, 0, 0, 0.0)
dt_days_added = dt.add_days(1.0)
print(f"Original dt: {dt}")
print(f"dt with days added: {dt_days_added}")
# prints:
# Original dt: 2025-01-01 00:00:00.000000000000000
# dt with days added: 2025-01-02 00:00:00.000000000000000

add_seconds(self: tudatpy.kernel.astro.time_conversion.DateTime, seconds_to_add: tudat::Time) → tudatpy.kernel.astro.time_conversion.DateTime¶

Function to create a new Tudat DateTime object by adding a number of seconds to an existing Tudat DateTime object.

Note

This method does not modify the original DateTime object, but returns a new one with the added seconds.

Parameters:: seconds_to_add (float) – Number of seconds to add
Returns:: Tudat-native Datetime object created by adding the given number of seconds to the original DateTime
Return type:: DateTime

Examples

In this example, 86400 seconds are added to a DateTime object to construct a new DateTime.

from tudatpy.astro.time_conversion import DateTime

dt = DateTime(2025, 1, 1, 0, 0, 0.0)
dt_seconds_added = dt.add_seconds(86400.0)
print(f"Original dt: {dt}")
print(f"dt with seconds added: {dt_seconds_added}")
# prints:
# Original dt: 2025-01-01 00:00:00.000000000000000
# dt with seconds added: 2025-01-02 00:00:00.000000000000000

epoch_time_object(self: tudatpy.kernel.astro.time_conversion.DateTime) → tudat::Time¶

static 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

Examples

In this example, the datetime is constructed from an epoch in seconds since J2000.

from tudatpy.astro.time_conversion import DateTime

epoch_et = 788961600.0

dt = DateTime.from_epoch(epoch_et)
print(dt) # prints 2025-01-01 00:00:00.000000000000000

static from_epoch_time_object(epoch: tudat::Time) → tudatpy.kernel.astro.time_conversion.DateTime¶

static from_iso_string(iso_time: str) → 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

Examples

In this example, the datetime is constructed from the iso string.

from tudatpy.astro.time_conversion import DateTime

dt = DateTime.from_iso_string("2025-01-01T00:00:00.000")
print(dt) # prints 2025-01-01 00:00:00.000000000000000

static from_julian_day(julian_day: float) → tudatpy.kernel.astro.time_conversion.DateTime¶

Creates a Tudat-native DateTime object from a Julian day.

Parameters:: julian_day (float) – Date in Julian days since January 1st 4713 BC.
Returns:: Tudat DateTime object.
Return type:: DateTime

Examples

In this example, the DateTime is constructed from a Julian day since January 1st 4713 BC.

from tudatpy.astro.time_conversion import DateTime

julian_day = 2451545.0

dt = DateTime.from_julian_day(julian_day)
print(dt) # prints 2000-01-01 12:00:00.000000000000000

static from_modified_julian_day(modified_julian_day: float) → tudatpy.kernel.astro.time_conversion.DateTime¶

Creates a Tudat-native DateTime object from a modified Julian day.

Parameters:: modified_julian_day (float) – Date in modified Julian days (number of days since November 17th 1858).
Returns:: Tudat DateTime object.
Return type:: DateTime

Examples

In this example, the DateTime is constructed from a modified Julian day since November 17th 1858.

from tudatpy.astro.time_conversion import DateTime

modified_julian_day = 51544.5

dt = DateTime.from_modified_julian_day(modified_julian_day)
print(dt) # prints 2000-01-01 12:00:00.000000000000000

static from_python_datetime(datetime: datetime.datetime) → tudatpy.kernel.astro.time_conversion.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.

Warning

This function uses the C++ std::chrono library, which is limited in the time range it can represent. If the range is exceeded, the conversion will overflow and NOT throw an exception.

The exact range is platform-dependent. On Windows, dates between 1970-01-01 and 3000-12-31 are allowed, on MacOS dates after 1900-01-01 are allowed and on Linux dates between 1678-01-01 and 2261-12-31 are allowed.

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

Examples

In this example, the Tudat DateTime object is constructed from python native datetime object.

from datetime import datetime
from tudatpy.astro.time_conversion import DateTime

python_datetime = datetime(2025, 1, 1, 0, 0, 0)

dt = DateTime.from_python_datetime(python_datetime)
print(dt) # prints 2025-01-01 00:00:00.000000000000000

static from_year_and_day_of_year(year: int, day_of_year: int) → tudatpy.kernel.astro.time_conversion.DateTime¶

Create the Tudat DateTime from the year and the number of days in the year.

Parameters:

year (int) – Calendar year.
day_of_year (int) – Number of days that have passed in the year.

Returns:

Corresponding calendar date as a DateTime object. Note: the hours, minutes and seconds in the object are set to 0 when calling this function.

Return type:

DateTime

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
currentDate = time_conversion.DateTime.from_year_and_day_of_year(2020, 122)
# Print the converted output
print(currentDate)  # prints (2020, 5, 2, 0, 0)

to_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

to_days_since_reference_julian_day(self: tudatpy.kernel.astro.time_conversion.DateTime, reference_julian_day: float = 2451545.0) → float¶

Convert a DateTime to Julian days since a given reference Julian date.

Parameters:: reference_julian_day (float, default = constants.JULIAN_DAY_ON_J2000) – Reference epoch (in days) 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 reference 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).

from tudatpy.astro.time_conversion import DateTime

# Define the calendar date using datetime
dt = DateTime(2022, 5, 21, 13, 52, 41)
# Convert the calendar date to Julian days since J2000
julian_date = dt.to_days_since_reference_julian_day()
# Print the converted output
print(julian_date)  # prints 8176.07825231459

to_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

to_epoch_time_object(self: tudatpy.kernel.astro.time_conversion.DateTime) → tudat::Time¶

to_iso_string(self: tudatpy.kernel.astro.time_conversion.DateTime, add_T: bool = False, number_of_digits_seconds: int = 15) → 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)
time (Boolean denoting whether to use a 'T' or a blank space to separate the date from the)
number_of_digits_seconds (int, default = 15)
truncated) (Number of digits to use after the decimal separator (trailing zeros will be)

Returns:

ISO-compatible string representing the date and time

Return type:

str

to_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

to_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

to_python_datetime(self: tudatpy.kernel.astro.time_conversion.DateTime) → datetime.datetime¶

Method to convert retrieve a Python datetime.datetime object from the Tudat DateTime object. This is the inverse of the from_python_datetime() method.

Note

The conversion uses the C++ std::chrono library, which is limited the time range it can represent. If the range is exceeded, the conversion will fail and throw an exception.

Returns:: Datetime object, using the Python datetime library
Return type:: datetime.datetime

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

class TimeScaleConverter¶

Class to convert between different time scales (TAI, TT, TDB, UTC, UT1)

Class to convert between different time scales (TAI, TT, TDB, UTC, UT1), as per algorithms described in (for instance) IERS 2010 Conventions and USNO circular no. 179. The algorithms used for the conversion are (where there is any choice in models):

Conversion between TDB and TT uses the SOFA function iauDtdb function (equivalently to TT_to_TDB() and TDB_to_TT())
Conversion between UTC and UT1 applies (semi-)diurnal and daily measured variations depending on settings during object creation (typically as per default_time_scale_converter())
Leap seconds as per the latest SOFA package

convert_time(self: tudatpy.kernel.astro.time_conversion.TimeScaleConverter, input_scale: tudatpy.kernel.astro.time_conversion.TimeScales, output_scale: tudatpy.kernel.astro.time_conversion.TimeScales, input_value: float, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → float¶

convert_time_object(self: tudatpy.kernel.astro.time_conversion.TimeScaleConverter, input_scale: tudatpy.kernel.astro.time_conversion.TimeScales, output_scale: tudatpy.kernel.astro.time_conversion.TimeScales, input_value: tudat::Time, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → tudat::Time¶

get_time_difference(self: tudatpy.kernel.astro.time_conversion.TimeScaleConverter, input_scale: tudatpy.kernel.astro.time_conversion.TimeScales, output_scale: tudatpy.kernel.astro.time_conversion.TimeScales, input_value: float, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → float¶

get_time_object_difference(self: tudatpy.kernel.astro.time_conversion.TimeScaleConverter, input_scale: tudatpy.kernel.astro.time_conversion.TimeScales, output_scale: tudatpy.kernel.astro.time_conversion.TimeScales, input_value: tudat::Time, earth_fixed_position: numpy.ndarray[numpy.float64[3, 1]] = array([0., 0., 0.])) → tudat::Time¶

time_conversion¶

Notes¶

References¶

Functions¶

Enumerations¶

Classes¶

`time_conversion`¶