Skip to content

Epoch

The Epoch class is the fundamental time representation in Brahe. It encapsulates a specific instant in time, defined by both a time representation and a time scale. The Epoch class provides methods for converting between different time representations and time scales, as well as for performing arithmetic operations on time instances.

There are even more capabilities and features of the Epoch class beyond what is covered in this guide. For a complete reference of all available methods and properties, please refer to the Epoch API Reference.

Initialization

There are all sorts of ways you can initialize an Epoch instance. The most common methods are described below.

Date Time

The most common way to create an Epoch is from date and time components. You can specify just a date (which defaults to midnight), or provide the full date and time including fractional seconds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import brahe as bh

bh.initialize_eop()

# Create epoch from date only (midnight)
epc1 = bh.Epoch(2024, 1, 1)
print(f"Date only: {epc1}")

# Create epoch from full datetime components
epc2 = bh.Epoch(2024, 6, 15, 14, 30, 45.5, 0.0)
print(f"Full datetime: {epc2}")

# Create epoch with different time system
epc3 = bh.Epoch(2024, 12, 25, 18, 0, 0.0, 0.0, time_system=bh.TimeSystem.GPS)
print(f"GPS time system: {epc3}")

# In Python you can also use the direct datetime constant
epc4 = bh.Epoch(2024, 12, 25, 18, 0, 0.0, 0.0, time_system=bh.TAI)
print(f"GPS time system: {epc4}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create epoch from date only (midnight)
    let epc1 = bh::Epoch::from_date(2024, 1, 1, bh::TimeSystem::UTC);
    println!("Date only: {}", epc1);

    // Create epoch from full datetime components
    let epc2 = bh::Epoch::from_datetime(2024, 6, 15, 14, 30, 45.5, 0.0, bh::TimeSystem::UTC);
    println!("Full datetime: {}", epc2);

    // Create epoch with different time system
    let epc3 = bh::Epoch::from_datetime(2024, 12, 25, 18, 0, 0.0, 0.0, bh::TimeSystem::GPS);
    println!("GPS time system: {}", epc3);
}
Output 
1
2
3
4
Date only: 2024-01-01 00:00:00.000 UTC
Full datetime: 2024-06-15 14:30:45.500 UTC
GPS time system: 2024-12-25 18:00:00.000 GPS
GPS time system: 2024-12-25 18:00:00.000 TAI

1
2
3
Date only: 2024-01-01 00:00:00.000 UTC
Full datetime: 2024-06-15 14:30:45.500 UTC
GPS time system: 2024-12-25 18:00:00.000 GPS

MJD

Modified Julian Date (MJD) is a commonly used time representation in astronomy and astrodynamics. MJD is defined as JD - 2400000.5, which makes it more convenient for modern dates.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import brahe as bh

bh.initialize_eop()

# Create epoch from MJD
mjd = 61041.5
epc2 = bh.Epoch.from_mjd(mjd, bh.UTC)
print(f"MJD {mjd}: {epc2}")

# Verify round-trip conversion
mjd_out = epc2.mjd()
print(f"Round-trip MJD: {mjd_out:.6f}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create epoch from MJD
    let mjd = 61041.5; // 2024-01-01 12:00:00 UTC
    let epc2 = bh::Epoch::from_mjd(mjd, bh::TimeSystem::UTC);
    println!("MJD {}: {}", mjd, epc2);

    // Verify round-trip conversion
    let mjd_out = epc2.mjd();
    println!("Round-trip MJD: {:.6}", mjd_out);
}
Output 
1
2
MJD 61041.5: 2026-01-01 12:00:00.000 UTC
Round-trip MJD: 61041.500000

1
2
MJD 61041.5: 2026-01-01 12:00:00.000 UTC
Round-trip MJD: 61041.500000

JD

Julian Date (JD) is a continuous count of days since the beginning of the Julian Period. It's widely used in astronomy for precise time calculations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import brahe as bh

bh.initialize_eop()

# Create epoch from JD
jd = 2460310.5
epc = bh.Epoch.from_jd(jd, bh.UTC)
print(f"JD {jd}: {epc}")

# Verify round-trip conversion
jd_out = epc.jd()
print(f"Round-trip JD: {jd_out:.10f}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create epoch from JD
    let jd = 2460310.5;
    let epc = bh::Epoch::from_jd(jd, bh::TimeSystem::UTC);
    println!("JD {}: {}", jd, epc);

    // Verify round-trip conversion
    let jd_out = epc.jd();
    println!("Round-trip JD: {:.10}", jd_out);
}
Output 
1
2
JD 2460310.5: 2024-01-01 00:00:00.000 UTC
Round-trip JD: 2460310.5000000000

1
2
JD 2460310.5: 2024-01-01 00:00:00.000 UTC
Round-trip JD: 2460310.5000000000

String

Epoch instances can be created from ISO 8601 formatted strings or simple date-time strings. The time system can be specified in the string.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import brahe as bh

bh.initialize_eop()

# The string can be an ISO 8601 format
epc1 = bh.Epoch.from_string("2025-01-02T04:56:54.123Z")
print(f"ISO 8601: {epc1}")

# It can be a simple space-separated format with a time system
epc2 = bh.Epoch.from_string("2024-06-15 14:30:45.500 GPS")
print(f"Simple format: {epc2}")

# It can be a datetime without a time system (defaults to UTC)
epc3 = bh.Epoch.from_string("2023-12-31 23:59:59")
print(f"Datetime without time system: {epc3}")

# Or it can just be a date
epc4 = bh.Epoch.from_string("2022-07-04")
print(f"Date only: {epc4}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // The string can be an ISO 8601 format
    let epc1 = bh::Epoch::from_string("2025-01-02T04:56:54.123Z").unwrap();
    println!("ISO 8601: {}", epc1);

    // It can be a simple space-separated format with a time system
    let epc2 = bh::Epoch::from_string("2024-06-15 14:30:45.500 GPS").unwrap();
    println!("Simple format: {}", epc2);

    // It can be a datetime without a time system (defaults to UTC)
    let epc3 = bh::Epoch::from_string("2023-12-31 23:59:59").unwrap();
    println!("Datetime without time system: {}", epc3);

    // Or it can just be a date
    let epc4 = bh::Epoch::from_string("2022-07-04").unwrap();
    println!("Date only: {}", epc4);
}
Output 
1
2
3
4
ISO 8601: 2025-01-02 04:56:54.123 UTC
Simple format: 2024-06-15 14:30:45.500 GPS
Datetime without time system: 2023-12-31 23:59:59.000 UTC
Date only: 2022-07-04 00:00:00.000 UTC

1
2
3
4
ISO 8601: 2025-01-02 04:56:54.123 UTC
Simple format: 2024-06-15 14:30:45.500 GPS
Datetime without time system: 2023-12-31 23:59:59.000 UTC
Date only: 2022-07-04 00:00:00.000 UTC

GPS Week and Seconds

For GPS applications, you can create epochs from GPS week number and seconds into the week, or from GPS seconds since the GPS epoch (January 6, 1980).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import brahe as bh

bh.initialize_eop()

# Create epoch from GPS week and seconds
# Week 2390, day 2 (October 28, 2025)
week = 2390
seconds = 2 * 86400.0
epc1 = bh.Epoch.from_gps_date(week, seconds)
print(f"GPS Week {week}, Seconds {seconds}: {epc1}")

# Verify round-trip conversion
week_out, sec_out = epc1.gps_date()
print(f"Round-trip: Week {week_out}, Seconds {sec_out:.1f}")

# Create from GPS seconds since GPS epoch
gps_seconds = week * 7 * 86400.0 + seconds
epc2 = bh.Epoch.from_gps_seconds(gps_seconds)
print(f"GPS Seconds {gps_seconds}: {epc2}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create epoch from GPS week and seconds
    // Week 2390, day 2 (October 28, 2025)
    let week = 2390;
    let seconds = 2.0 * 86400.0; // 3 days + 12 hours
    let epc1 = bh::Epoch::from_gps_date(week, seconds);
    println!("GPS Week {}, Seconds {}: {}", week, seconds, epc1);

    // Verify round-trip conversion
    let (week_out, sec_out) = epc1.gps_date();
    println!("Round-trip: Week {}, Seconds {:.1}", week_out, sec_out);

    // Create from GPS seconds since GPS epoch
    let gps_seconds = week as f64 * 7.0 * 86400.0 + seconds;
    let epc2 = bh::Epoch::from_gps_seconds(gps_seconds);
    println!("GPS Seconds {}: {}", gps_seconds, epc2);
}
Output 
1
2
3
GPS Week 2390, Seconds 172800.0: 2025-10-28 00:00:00.000 GPS
Round-trip: Week 2390, Seconds 172800.0
GPS Seconds 1445644800.0: 2025-10-28 00:00:00.000 GPS

1
2
3
GPS Week 2390, Seconds 172800: 2025-10-28 00:00:00.000 GPS
Round-trip: Week 2390, Seconds 172800.0
GPS Seconds 1445644800: 2025-10-28 00:00:00.000 GPS

Time System

Every Epoch carries a TimeSystem, set at construction. It records the time scale the epoch is expressed in. For what each scale means and when to use it, see Time Systems and Representations.

In Python the time system is optional and defaults to UTC when omitted; it can be given either as an enumeration member (bh.TimeSystem.GPS) or as the equivalent module-level constant (bh.GPS). Rust requires it explicitly at construction, using bh::TimeSystem::GPS.

An Epoch stores an absolute instant, and the time system only determines the scale it reports in. to_time_system returns a new Epoch at the same instant expressed in a different scale — it changes how the epoch prints, not when it is. The original is left untouched, and the two compare equal because they denote the same instant.

To read a single value out in another scale without creating a new Epoch, use the *_as_time_system family: to_datetime_as_time_system, to_string_as_time_system, jd_as_time_system, mjd_as_time_system, day_of_year_as_time_system, and seconds_past_j2000_as_time_system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
import brahe as bh

bh.initialize_eop()

# The time system is set at construction. It defaults to UTC.
epc_utc = bh.Epoch(2024, 6, 15, 12, 0, 0.0, 0.0)
print(f"Default:  {epc_utc}")

# Specify a time system with the TimeSystem enumeration...
epc_gps = bh.Epoch(2024, 6, 15, 12, 0, 0.0, 0.0, time_system=bh.TimeSystem.GPS)
print(f"GPS:      {epc_gps}")

# ...or with the equivalent module-level constant.
epc_tai = bh.Epoch(2024, 6, 15, 12, 0, 0.0, 0.0, time_system=bh.TAI)
print(f"TAI:      {epc_tai}")

# Read back the time system an Epoch was created in.
print(f"Read back: {epc_gps.time_system}")

# The same calendar values in different time systems are different instants.
print(f"UTC and GPS equal? {epc_utc == epc_gps}")

# to_time_system returns a new Epoch at the SAME instant, displayed in a new
# time system. It changes how the epoch prints, not when it is.
epc_as_gps = epc_utc.to_time_system(bh.TimeSystem.GPS)
print(f"As GPS:   {epc_as_gps}")
print(f"Same instant? {epc_utc == epc_as_gps}")

# The original is untouched.
print(f"Original: {epc_utc}")

# To read a single value out in another system without making a new Epoch,
# use the *_as_time_system projections.
print(f"epc_utc as TAI: {epc_utc.to_string_as_time_system(bh.TimeSystem.TAI)}")
print(f"MJD as UTC: {epc_utc.mjd_as_time_system(bh.TimeSystem.UTC):.9f}")
print(f"MJD as TT:  {epc_utc.mjd_as_time_system(bh.TimeSystem.TT):.9f}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // The time system is always explicit in Rust.
    let epc_utc = bh::Epoch::from_datetime(2024, 6, 15, 12, 0, 0.0, 0.0, bh::TimeSystem::UTC);
    println!("Default:  {}", epc_utc);

    let epc_gps = bh::Epoch::from_datetime(2024, 6, 15, 12, 0, 0.0, 0.0, bh::TimeSystem::GPS);
    println!("GPS:      {}", epc_gps);

    let epc_tai = bh::Epoch::from_datetime(2024, 6, 15, 12, 0, 0.0, 0.0, bh::TimeSystem::TAI);
    println!("TAI:      {}", epc_tai);

    // Read back the time system an Epoch was created in. This is a field.
    println!("Read back: {}", epc_gps.time_system);

    // The same calendar values in different time systems are different instants.
    println!("UTC and GPS equal? {}", epc_utc == epc_gps);

    // to_time_system returns a new Epoch at the SAME instant, displayed in a
    // new time system. It changes how the epoch prints, not when it is.
    let epc_as_gps = epc_utc.to_time_system(bh::TimeSystem::GPS);
    println!("As GPS:   {}", epc_as_gps);
    println!("Same instant? {}", epc_utc == epc_as_gps);

    // The original is untouched.
    println!("Original: {}", epc_utc);

    // To read a single value out in another system without making a new Epoch,
    // use the *_as_time_system projections.
    println!("epc_utc as TAI: {}", epc_utc.to_string_as_time_system(bh::TimeSystem::TAI));
    println!("MJD as UTC: {:.9}", epc_utc.mjd_as_time_system(bh::TimeSystem::UTC));
    println!("MJD as TT:  {:.9}", epc_utc.mjd_as_time_system(bh::TimeSystem::TT));
}
Output 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Default:  2024-06-15 12:00:00.000 UTC
GPS:      2024-06-15 12:00:00.000 GPS
TAI:      2024-06-15 12:00:00.000 TAI
Read back: GPS
UTC and GPS equal? False
As GPS:   2024-06-15 12:00:18.000 GPS
Same instant? True
Original: 2024-06-15 12:00:00.000 UTC
epc_utc as TAI: 2024-06-15 12:00:37.000 TAI
MJD as UTC: 60476.500000000
MJD as TT:  60476.500800741

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Default:  2024-06-15 12:00:00.000 UTC
GPS:      2024-06-15 12:00:00.000 GPS
TAI:      2024-06-15 12:00:00.000 TAI
Read back: GPS
UTC and GPS equal? false
As GPS:   2024-06-15 12:00:18.000 GPS
Same instant? true
Original: 2024-06-15 12:00:00.000 UTC
epc_utc as TAI: 2024-06-15 12:00:37.000 TAI
MJD as UTC: 60476.500000000
MJD as TT:  60476.500800741

Operations

Once you have an epoch class instance you can add and subtract time as you would expect.

Info

When performing arithmetic the other operand is always interpreted as a time duration in seconds.

Addition

You can add a time duration (in seconds) to an Epoch to get a new Epoch at a later time.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import brahe as bh

bh.initialize_eop()

# Create an epoch
epc = bh.Epoch(2025, 1, 1, 12, 0, 0.0, 0.0)
print(f"Original epoch: {epc}")

# You can add time in seconds to an Epoch and get a new Epoch back

# Add 1 hour (3600 seconds)
epc_plus_hour = epc + 3600.0
print(f"Plus 1 hour: {epc_plus_hour}")

# Add 1 day (86400 seconds)
epc_plus_day = epc + 86400.0
print(f"Plus 1 day: {epc_plus_day}")

# You can also do in-place addition

# Add 1 second in-place
epc += 1.0
print(f"In-place plus 1 second: {epc}")

# Add 1 milisecond in-place
epc += 0.001
print(f"In-place plus 1 millisecond: {epc}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create an epoch
    let epc = bh::Epoch::from_datetime(2025, 1, 1, 12, 0, 0.0, 0.0, bh::TimeSystem::UTC);
    println!("Original epoch: {}", epc);

    // You can add time in seconds to an Epoch and get a new Epoch back

    // Add 1 hour (3600 seconds)
    let epc_plus_hour = epc + 3600.0;
    println!("Plus 1 hour: {}", epc_plus_hour);

    // Add 1 day (86400 seconds)
    let epc_plus_day = epc + 86400.0;
    println!("Plus 1 day: {}", epc_plus_day);

    // You can also do in-place addition

    // Add 1 second in-place
    let mut epc = epc;
    epc += 1.0;
    println!("In-place plus 1 second: {}", epc);

    // Add 1 millisecond in-place
    epc += 0.001;
    println!("In-place plus 1 millisecond: {}", epc);
}
Output 
1
2
3
4
5
Original epoch: 2025-01-01 12:00:00.000 UTC
Plus 1 hour: 2025-01-01 13:00:00.000 UTC
Plus 1 day: 2025-01-02 12:00:00.000 UTC
In-place plus 1 second: 2025-01-01 12:00:01.000 UTC
In-place plus 1 millisecond: 2025-01-01 12:00:01.001 UTC

1
2
3
4
5
Original epoch: 2025-01-01 12:00:00.000 UTC
Plus 1 hour: 2025-01-01 13:00:00.000 UTC
Plus 1 day: 2025-01-02 12:00:00.000 UTC
In-place plus 1 second: 2025-01-01 12:00:01.000 UTC
In-place plus 1 millisecond: 2025-01-01 12:00:01.001 UTC

Subtraction

Subtracting two Epoch instances returns the time difference between them in seconds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
import brahe as bh

bh.initialize_eop()

# You can subtract two Epoch instances to get the time difference in seconds
epc1 = bh.Epoch(2024, 1, 1, 12, 0, 0.0, 0.0)
epc2 = bh.Epoch(2024, 1, 2, 12, 1, 1.0, 0.0)

dt = epc2 - epc1
print(f"Time difference: {dt:.1f} seconds")

# You can also subtract a float (in seconds) from an Epoch to get a new Epoch
epc = bh.Epoch(2024, 6, 15, 10, 30, 0.0, 0.0)

# Subtract 1 hour (3600 seconds)
epc_minus_hour = epc - 3600.0
print(f"Minus 1 hour: {epc_minus_hour}")

# You can also update an Epoch in-place by subtracting seconds
epc = bh.Epoch(2024, 1, 1, 0, 0, 0.0, 0.0)
epc -= 61.0  # Subtract 61 seconds
print(f"In-place minus 61 seconds: {epc}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create two epochs
    let epc1 = bh::Epoch::from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh::TimeSystem::UTC);
    let epc2 = bh::Epoch::from_datetime(2024, 1, 2, 13, 1, 1.0, 0.0, bh::TimeSystem::UTC);

    // Compute time difference in seconds
    let dt = epc2 - epc1;
    println!("Time difference: {:.1} seconds", dt);

    // You can also subtract a float (in seconds) from an Epoch to get a new Epoch
    let epc = bh::Epoch::from_datetime(2024, 6, 15, 10, 30, 0.0, 0.0, bh::TimeSystem::UTC);
    let epc_minus_hour = epc - 3600.0;
    println!("Minus 1 hour: {}", epc_minus_hour);

    // You can also update an Epoch in-place by subtracting seconds
    let mut epc = bh::Epoch::from_datetime(2024, 1, 1, 0, 0, 0.0, 0.0, bh::TimeSystem::UTC);
    epc -= 61.0; // Subtract 61 seconds
    println!("In-place minus 61 seconds: {}", epc);
}
Output 
1
2
3
Time difference: 86461.0 seconds
Minus 1 hour: 2024-06-15 09:30:00.000 UTC
In-place minus 61 seconds: 2023-12-31 23:58:59.000 UTC

1
2
3
Time difference: 90061.0 seconds
Minus 1 hour: 2024-06-15 09:30:00.000 UTC
In-place minus 61 seconds: 2023-12-31 23:58:59.000 UTC

Other Operations

The Epoch class also supports comparison operations (e.g., equality, less than, greater than) to compare different time instances. It also supports methods for getting string representations using language-specific formatting options.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import brahe as bh

bh.initialize_eop()

# Create an epoch
epc_1 = bh.Epoch(2024, 1, 1, 12, 0, 0.0, 0.0)
epc_2 = bh.Epoch(2024, 1, 1, 12, 0, 0.0, 1.0)
epc_3 = bh.Epoch(2024, 1, 1, 12, 0, 0.0, 0.0)

# You can compare two Epoch instances for equality
print(f"epc_1 == epc_2: {epc_1 == epc_2}")
print(f"epc_1 == epc_3: {epc_1 == epc_3}")

# You can also use inequality and comparison operators
print(f"epc_1 != epc_2: {epc_1 != epc_2}")
print(f"epc_1 < epc_2: {epc_1 < epc_2}")
print(f"epc_2 < epc_1: {epc_2 < epc_1}")
print(f"epc_2 > epc_1: {epc_2 > epc_1}")
print(f"epc_1 <= epc_3: {epc_1 <= epc_3}")
print(f"epc_2 >= epc_1: {epc_2 >= epc_1}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create an epoch
    let epc_1 = bh::Epoch::from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh::TimeSystem::UTC);
    let epc_2 = bh::Epoch::from_datetime(2024, 1, 1, 12, 0, 0.0, 1.0, bh::TimeSystem::UTC);
    let epc_3 = bh::Epoch::from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh::TimeSystem::UTC);

    // You can compare two Epoch instances for equality
    println!("epc_1 == epc_2: {}", epc_1 == epc_2);
    println!("epc_1 == epc_3: {}", epc_1 == epc_3);

    // You can also use inequality and comparison operators
    println!("epc_1 != epc_2: {}", epc_1 != epc_2);
    println!("epc_1 < epc_2: {}", epc_1 < epc_2);
    println!("epc_2 < epc_1: {}", epc_2 < epc_1);
    println!("epc_2 > epc_1: {}", epc_2 > epc_1);
    println!("epc_1 <= epc_3: {}", epc_1 <= epc_3);
    println!("epc_2 >= epc_1: {}", epc_2 >= epc_1);
}
Output 
1
2
3
4
5
6
7
8
epc_1 == epc_2: False
epc_1 == epc_3: True
epc_1 != epc_2: True
epc_1 < epc_2: True
epc_2 < epc_1: False
epc_2 > epc_1: True
epc_1 <= epc_3: True
epc_2 >= epc_1: True

1
2
3
4
5
6
7
8
epc_1 == epc_2: false
epc_1 == epc_3: true
epc_1 != epc_2: true
epc_1 < epc_2: true
epc_2 < epc_1: false
epc_2 > epc_1: true
epc_1 <= epc_3: true
epc_2 >= epc_1: true

Output and Formatting

Finally, you can take any Epoch instance and then output it in different representations.

Date Time

You can extract the date and time components from an Epoch, optionally converting to a different time system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import brahe as bh

bh.initialize_eop()

# Create an epoch
epc = bh.Epoch(2024, 6, 15, 14, 30, 45.5, 0.0)
print(f"Epoch: {epc}")

# Output the equivalent Julian Date
jd = epc.jd()
print(f"Julian Date: {jd:.6f}")

# Get the Julian Date in a different time system (e.g., TT)
jd_tt = epc.jd_as_time_system(time_system=bh.TT)
print(f"Julian Date (TT): {jd_tt:.6f}")

# Output the equivalent Modified Julian Date
mjd = epc.mjd()
print(f"Modified Julian Date: {mjd:.6f}")

# Get the Modified Julian Date in a different time system (e.g., GPS)
mjd_gps = epc.mjd_as_time_system(time_system=bh.GPS)
print(f"Modified Julian Date (GPS): {mjd_gps:.6f}")

# Get the GPS Week and Seconds of Week
gps_week, gps_sow = epc.gps_date()
print(f"GPS Week: {gps_week}, Seconds of Week: {gps_sow:.3f}")

# The Epoch as GPS seconds since the GPS epoch
gps_seconds = epc.gps_seconds()
print(f"GPS Seconds since epoch: {gps_seconds:.3f}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create an epoch
    let epc = bh::Epoch::from_datetime(2024, 6, 15, 14, 30, 45.5, 0.0, bh::TimeSystem::UTC);
    println!("Epoch: {}", epc);

    // Output the equivalent Julian Date
    let jd = epc.jd();
    println!("Julian Date: {:.6}", jd);

    // Get the Julian Date in a different time system (e.g., TT)
    let jd_tt = epc.jd_as_time_system(bh::TimeSystem::TT);
    println!("Julian Date (TT): {:.6}", jd_tt);

    // Output the equivalent Modified Julian Date
    let mjd = epc.mjd();
    println!("Modified Julian Date: {:.6}", mjd);

    // Get the Modified Julian Date in a different time system (e.g., GPS)
    let mjd_gps = epc.mjd_as_time_system(bh::TimeSystem::GPS);
    println!("Modified Julian Date (GPS): {:.6}", mjd_gps);

    // Get the GPS Week and Seconds of Week
    let (gps_week, gps_sow) = epc.gps_date();
    println!("GPS Week: {}, Seconds of Week: {:.3}", gps_week, gps_sow);

    // The Epoch as GPS seconds since the GPS epoch
    let gps_seconds = epc.gps_seconds();
    println!("GPS Seconds since epoch: {:.3}", gps_seconds);
}
Output 
1
2
3
4
5
6
7
Epoch: 2024-06-15 14:30:45.500 UTC
Julian Date: 2460477.104693
Julian Date (TT): 2460477.105494
Modified Julian Date: 60476.604693
Modified Julian Date (GPS): 60476.604902
GPS Week: 2318, Seconds of Week: 570663.500
GPS Seconds since epoch: 1402497063.500

1
2
3
4
5
6
7
Epoch: 2024-06-15 14:30:45.500 UTC
Julian Date: 2460477.104693
Julian Date (TT): 2460477.105494
Modified Julian Date: 60476.604693
Modified Julian Date (GPS): 60476.604902
GPS Week: 2318, Seconds of Week: 570663.500
GPS Seconds since epoch: 1402497063.500

String Representation

Epochs can be converted to human-readable strings in various formats and time systems.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import brahe as bh

bh.initialize_eop()

# Create an epoch
epc = bh.Epoch(2024, 6, 15, 14, 30, 45.123456789, 0.0)

# Default string representation
print(f"Default: {epc}")

# Explicit string conversion
print(f"String: {str(epc)}")

# Debug representation
print(f"Debug: {repr(epc)}")

# Get string in a different time system
print(f"TT: {epc.to_string_as_time_system(bh.TimeSystem.TT)}")

# Get as ISO 8601 formatted string
print(f"ISO 8601: {epc.isostring()}")

# Get as ISO 8601 with different number of decimal places
print(f"ISO 8601 (0 decimal places): {epc.isostring_with_decimals(0)}")
print(f"ISO 8601 (3 decimal places): {epc.isostring_with_decimals(3)}")
print(f"ISO 8601 (6 decimal places): {epc.isostring_with_decimals(6)}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    // Create an epoch
    let epc = bh::Epoch::from_datetime(2024, 6, 15, 14, 30, 45.123456789, 0.0, bh::TimeSystem::UTC);

    // Default string representation
    println!("Default: {}", epc);

    // Explicit string conversion (same as default in Rust)
    println!("String: {}", epc.to_string());

    // Debug representation
    println!("Debug: {:?}", epc);

    // Get string in a different time system
    println!("TT: {}", epc.to_string_as_time_system(bh::TimeSystem::TT));

    println!("ISO 8601: {}", epc.isostring());

    println!("ISO 8601 (0 decimal places): {}", epc.isostring_with_decimals(0));
    println!("ISO 8601 (3 decimal places): {}", epc.isostring_with_decimals(3));
    println!("ISO 8601 (6 decimal places): {}", epc.isostring_with_decimals(6));
}
Output 
1
2
3
4
5
6
7
8
Default: 2024-06-15 14:30:45.123 UTC
String: 2024-06-15 14:30:45.123 UTC
Debug: Epoch<2460477, 9082, 123456788.98545027, 0, UTC>
TT: 2024-06-15 14:31:54.307 TT
ISO 8601: 2024-06-15T14:30:45Z
ISO 8601 (0 decimal places): 2024-06-15T14:30:45Z
ISO 8601 (3 decimal places): 2024-06-15T14:30:45.123Z
ISO 8601 (6 decimal places): 2024-06-15T14:30:45.123456Z

1
2
3
4
5
6
7
8
Default: 2024-06-15 14:30:45.123 UTC
String: 2024-06-15 14:30:45.123 UTC
Debug: Epoch<2460477, 9082, 123456788.98545027, 0, UTC>
TT: 2024-06-15 14:31:54.307 TT
ISO 8601: 2024-06-15T14:30:45Z
ISO 8601 (0 decimal places): 2024-06-15T14:30:45Z
ISO 8601 (3 decimal places): 2024-06-15T14:30:45.123Z
ISO 8601 (6 decimal places): 2024-06-15T14:30:45.123456Z

Seconds Past J2000 in a Specific Time System

seconds_past_j2000_as_time_system returns the number of seconds elapsed since the J2000 epoch (2000-01-01 12:00:00 TT), expressed in a chosen time system. Requesting TimeSystem.TDB gives SPICE ephemeris time (ET), the time argument used by SPK/PCK kernel queries (spk_position, sun_position_spice, ...); see SPICE Kernels. spice_et() is a convenience alias for seconds_past_j2000_as_time_system(TimeSystem.TDB).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import brahe as bh

bh.initialize_eop()

epc = bh.Epoch.from_datetime(2025, 3, 15, 6, 30, 21.0, 0.0, bh.TimeSystem.UTC)

# SPICE ephemeris time (ET) is TDB seconds past J2000. spk_position/velocity/state
# and the *_spice functions convert epochs this way internally.
et = epc.seconds_past_j2000_as_time_system(bh.TimeSystem.TDB)
print(f"Epoch: {epc}")
print(f"SPICE ET (TDB seconds past J2000): {et:.6f}")

# Other time systems are available the same way.
tt = epc.seconds_past_j2000_as_time_system(bh.TimeSystem.TT)
print(f"TT seconds past J2000: {tt:.6f}")
print(f"TDB - TT (s): {et - tt:.9f}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
use brahe as bh;

fn main() {
    bh::initialize_eop().unwrap();

    let epc = bh::Epoch::from_datetime(2025, 3, 15, 6, 30, 21.0, 0.0, bh::TimeSystem::UTC);

    // SPICE ephemeris time (ET) is TDB seconds past J2000. spk_position/velocity/state
    // and the *_spice functions convert epochs this way internally.
    let et = epc.seconds_past_j2000_as_time_system(bh::TimeSystem::TDB);
    println!("Epoch: {}", epc);
    println!("SPICE ET (TDB seconds past J2000): {:.6}", et);

    // Other time systems are available the same way.
    let tt = epc.seconds_past_j2000_as_time_system(bh::TimeSystem::TT);
    println!("TT seconds past J2000: {:.6}", tt);
    println!("TDB - TT (s): {:.9}", et - tt);
}
Output 
1
2
3
4
Epoch: 2025-03-15 06:30:21.000 UTC
SPICE ET (TDB seconds past J2000): 795292290.185543
TT seconds past J2000: 795292290.184000
TDB - TT (s): 0.001543045

1
2
3
4
Epoch: 2025-03-15 06:30:21.000 UTC
SPICE ET (TDB seconds past J2000): 795292290.185543
TT seconds past J2000: 795292290.184000
TDB - TT (s): 0.001543045

See Also