Time Conversions

Functions for converting between different time systems and formats.

Time System Offset Functions

time_system_offset_for_mjd builtin

time_system_offset_for_mjd(mjd: float, time_system_src: TimeSystem, time_system_dst: TimeSystem) -> float

Calculate the offset between two time systems for a given Modified Julian Date.

Parameters:

Name	Type	Description	Default
mjd	float	Modified Julian date	required
time_system_src	TimeSystem	Source time system	required
time_system_dst	TimeSystem	Destination time system	required

Returns:

Name	Type	Description
float	float	Offset between time systems in seconds

Example

import brahe as bh

# Get offset from UTC to TAI at J2000 epoch
mjd_j2000 = 51544.0
offset = bh.time_system_offset_for_mjd(mjd_j2000, bh.TimeSystem.UTC, bh.TimeSystem.TAI)
print(f"UTC to TAI offset: {offset} seconds")
# Output: UTC to TAI offset: 32.0 seconds

time_system_offset_for_jd builtin

time_system_offset_for_jd(jd: float, time_system_src: TimeSystem, time_system_dst: TimeSystem) -> float

Calculate the offset between two time systems for a given Julian Date.

Parameters:

Name	Type	Description	Default
jd	float	Julian date	required
time_system_src	TimeSystem	Source time system	required
time_system_dst	TimeSystem	Destination time system	required

Returns:

Name	Type	Description
float	float	Offset between time systems in seconds

Example

import brahe as bh

# Get offset from GPS to UTC at a specific Julian Date
jd = 2460000.0
offset = bh.time_system_offset_for_jd(jd, bh.TimeSystem.GPS, bh.TimeSystem.UTC)
print(f"GPS to UTC offset: {offset} seconds")
# Output: GPS to UTC offset: -18.0 seconds

time_system_offset_for_datetime builtin

time_system_offset_for_datetime(year: int, month: int, day: int, hour: int, minute: int, second: float, nanosecond: float, time_system_src: TimeSystem, time_system_dst: TimeSystem) -> float

Calculate the offset between two time systems for a given Gregorian calendar date.

Parameters:

Name	Type	Description	Default
year	int	Year	required
month	int	Month (1-12)	required
day	int	Day of month (1-31)	required
hour	int	Hour (0-23)	required
minute	int	Minute (0-59)	required
second	float	Second with fractional part	required
nanosecond	float	Nanosecond component	required
time_system_src	TimeSystem	Source time system	required
time_system_dst	TimeSystem	Destination time system	required

Returns:

Name	Type	Description
float	float	Offset between time systems in seconds

Example

import brahe as bh

# Get offset from TT to TAI on January 1, 2024
offset = bh.time_system_offset_for_datetime(
    2024, 1, 1, 0, 0, 0.0, 0.0,
    bh.TimeSystem.TT, bh.TimeSystem.TAI
)
print(f"TT to TAI offset: {offset} seconds")
# Output: TT to TAI offset: -32.184 seconds

DateTime Conversion Functions

datetime_to_jd builtin

datetime_to_jd(year: int, month: int, day: int, hour: int, minute: int, second: float, nanosecond: float) -> float

Convert a Gregorian calendar date to the equivalent Julian Date.

Note: Due to the ambiguity of the nature of leap second insertion, this method should not be used if a specific behavior for leap second insertion is expected. This method treats leap seconds as if they don't exist.

Parameters:

Name	Type	Description	Default
year	int	Year	required
month	int	Month (1-12)	required
day	int	Day of month (1-31)	required
hour	int	Hour (0-23)	required
minute	int	Minute (0-59)	required
second	float	Second with fractional part	required
nanosecond	float	Nanosecond component	required

Returns:

Type	Description
float	Julian date of epoch

Example

import brahe as bh

# Convert January 1, 2024 noon to Julian Date
jd = bh.datetime_to_jd(2024, 1, 1, 12, 0, 0.0, 0.0)
print(f"JD: {jd:.6f}")
# Output: JD: 2460311.000000

datetime_to_mjd builtin

datetime_to_mjd(year: int, month: int, day: int, hour: int, minute: int, second: float, nanosecond: float) -> float

Convert a Gregorian calendar date to the equivalent Modified Julian Date.

Note: Due to the ambiguity of the nature of leap second insertion, this method should not be used if a specific behavior for leap second insertion is expected. This method treats leap seconds as if they don't exist.

Parameters:

Name	Type	Description	Default
year	int	Year	required
month	int	Month (1-12)	required
day	int	Day of month (1-31)	required
hour	int	Hour (0-23)	required
minute	int	Minute (0-59)	required
second	float	Second with fractional part	required
nanosecond	float	Nanosecond component	required

Returns:

Type	Description
float	Modified Julian date of epoch

Example

import brahe as bh

# Convert January 1, 2024 noon to Modified Julian Date
mjd = bh.datetime_to_mjd(2024, 1, 1, 12, 0, 0.0, 0.0)
print(f"MJD: {mjd:.6f}")
# Output: MJD: 60310.500000

jd_to_datetime builtin

jd_to_datetime(jd: float) -> Tuple

Convert a Julian Date to the equivalent Gregorian calendar date.

Note: Due to the ambiguity of the nature of leap second insertion, this method should not be used if a specific behavior for leap second insertion is expected. This method treats leap seconds as if they don't exist.

Parameters:

Name	Type	Description	Default
jd	float	Julian date	required

Returns:

Name	Type	Description
tuple	Tuple	A tuple containing (year, month, day, hour, minute, second, nanosecond)

Example

import brahe as bh

# Convert Julian Date to Gregorian calendar
jd = 2460311.0
year, month, day, hour, minute, second, nanosecond = bh.jd_to_datetime(jd)
print(f"{year}-{month:02d}-{day:02d} {hour:02d}:{minute:02d}:{second:06.3f}")
# Output: 2024-01-01 12:00:00.000

mjd_to_datetime builtin

mjd_to_datetime(mjd: float) -> Tuple

Convert a Modified Julian Date to the equivalent Gregorian calendar date.

Note: Due to the ambiguity of the nature of leap second insertion, this method should not be used if a specific behavior for leap second insertion is expected. This method treats leap seconds as if they don't exist.

Parameters:

Name	Type	Description	Default
mjd	float	Modified Julian date	required

Returns:

Name	Type	Description
tuple	Tuple	A tuple containing (year, month, day, hour, minute, second, nanosecond)

Example

import brahe as bh

# Convert Modified Julian Date to Gregorian calendar
mjd = 60310.5
year, month, day, hour, minute, second, nanosecond = bh.mjd_to_datetime(mjd)
print(f"{year}-{month:02d}-{day:02d} {hour:02d}:{minute:02d}:{second:06.3f}")
# Output: 2024-01-01 12:00:00.000