Skip to content

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 
1
2
3
4
5
6
7
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 
1
2
3
4
5
6
7
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 
1
2
3
4
5
6
7
8
9
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 
1
2
3
4
5
6
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 
1
2
3
4
5
6
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 
1
2
3
4
5
6
7
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 
1
2
3
4
5
6
7
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