Epoch¶
The epoch module provides the Epoch class for representing instants in time.
The Epoch class uses an internal representation of integer Julian Day number, seconds within the day, and a Kahan summation compensator for maintaining precision during arithmetic operations.
The Kahan compensator tracks floating-point rounding errors that accumulate during repeated additions (e.g., time stepping in numerical integration), preventing error growth from O(N) to O(1) machine epsilon.
The Epoch class is registered as a JAX pytree, making it compatible with
jax.jit, jax.vmap, and jax.lax.scan. All arithmetic, comparison,
and time-computation methods use JAX operations and are fully traceable.
Float components use the configurable dtype (default float32, see
:func:astrojax.config.set_dtype). The split representation
(int32 days + float seconds) provides ~8ms precision at float32 and
sub-nanosecond precision at float64.
Epoch
¶
Represents a single instant in time with high-precision arithmetic.
The internal representation uses three private components
_jd (jnp.int32), _seconds (configurable float dtype),
_kahan_c (configurable float dtype).
Use jd() and mjd() to access the absolute time as Julian Date
or Modified Julian Date.
The Kahan compensator accumulates floating-point rounding errors during arithmetic operations, preventing error growth when many small time steps are added (e.g., during numerical integration).
This class is registered as a JAX pytree and is compatible with
jax.jit, jax.vmap, and jax.lax.scan.
Precision note
The split (int32 + float) representation gives ~8ms precision at
float32 and sub-nanosecond precision at float64. The jd()
and mjd() accessors return a single float, which may be lossy
for sub-day precision at float32. For high-precision time
differences, use epoch subtraction (epc1 - epc2) which
preserves the full split-representation precision.
Constructors
Epoch(2018, 1, 1) Epoch(2018, 1, 1, 12, 0, 0.0) Epoch("2018-01-01T12:00:00Z") Epoch(other_epoch)
__add__(delta)
¶
__iadd__(delta)
¶
Add seconds to this epoch using Kahan compensated summation.
Returns a new Epoch instance (Python rebinds the name on +=).
This functional style is required for JAX traceability — JAX pytree
leaves are immutable during tracing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
delta
|
float
|
Seconds to add. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Epoch |
Epoch
|
New Epoch with delta seconds added. |
__init__(*args)
¶
__isub__(delta)
¶
__sub__(other)
¶
Subtract seconds or compute difference between Epochs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
Epoch | float
|
If Epoch, returns the time difference in seconds. If numeric, returns a new Epoch with seconds subtracted. |
required |
Returns:
| Type | Description |
|---|---|
Epoch | Array
|
float or Epoch: Time difference in seconds, or new Epoch. |
caldate()
¶
Return the calendar date components.
This method extracts concrete Python values from JAX arrays and
is not traceable under jax.jit. It should only be called
outside of JIT-compiled functions.
Returns:
| Name | Type | Description |
|---|---|---|
tuple |
tuple[Array, Array, Array, int, int, float]
|
(year, month, day, hour, minute, second) where second includes fractional part. |
gmst(use_degrees=False)
¶
Compute Greenwich Mean Sidereal Time using the IAU 1982 model.
Uses the Vallado GMST82 polynomial approximation. This implementation assumes UTC approximates UT1, which introduces at most ~1 second of error for most applications.
Computes T_UT1 directly from the split (int32 + float32) internal representation to avoid the precision loss of a single-float JD.
All operations use jnp and are fully traceable under jax.jit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
use_degrees
|
bool
|
If True, return in degrees. Default: False (radians). |
False
|
Returns:
| Type | Description |
|---|---|
Array
|
jax.Array: Greenwich Mean Sidereal Time. Units: rad (or deg if use_degrees=True) |
References:
1. D. Vallado, *Fundamentals of Astrodynamics and Applications
(4th Ed.)*, 2010.
jd()
¶
Return the Julian Date as a single float.
Note
At float32, a single value near typical JD values (~2.45M) has
~0.25 day precision. At float64, precision is sub-millisecond.
For time-of-day sensitive computations at float32, use the
Epoch object directly or caldate().
Returns:
| Type | Description |
|---|---|
Array
|
jax.Array: Julian Date. |
mjd()
¶
Return the Modified Julian Date as a single float.
Note
MJD values (~51544) are smaller than JD, giving better precision
than jd(). At float32 this is ~0.004 day (~6 min); at
float64 it is sub-microsecond.
Returns:
| Type | Description |
|---|---|
Array
|
jax.Array: Modified Julian Date. |