EpochArray#

class EpochArray(times: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], sys: Literal['TDB', 'ET', 'UTC', 'TT', 'TDT', 'TAI', 'SCLK', 'GPS'] = 'TDB', rep: Literal['NUM', 'AWU', 'CAL', 'DOY', 'ISOC', 'ISOD', 'JDTDB', 'JED', 'JDTDT', 'JDUTC'] = 'AWU', prec: int = 16, disp_len: int = 25, sc_id: int = None)#

Bases: object

Time interface within Scarabaeus.

Performs conversions between time systems and representations.

Parameters:
timesstr or float or array_like

The time or times contained within the EpochArray. Valid input types are:

  • str - single epoch input. Numerical strings are cast as floats and assumed to be in seconds past J2000 (TDB). Non-numerical strings are parsed according to their format/representation (ISO, calendar, DOY, JD).

  • float- single epoch input. Assumed to be in seconds past J2000 (TDB).

  • list or ndarray - Multi-epoch input. Element types follow the same conventions as their single epoch counterparts, see above bullets.

sysTimeSystem, optional

The uniform time system in which EpochArray is defined. Defaults to 'TDB'. Supported systems are:

  • 'TDB' or 'ET' - Barycentric Dynamical Time (TDB), also known as Ephemeris Time (ET).

  • 'UTC' - Coordinated Universal Time (UTC). A leapsecond kernel (LSK) must be loaded.

  • 'TT' or 'TDT' - Terrestrial Time (TT), formerly referred to as Terrestrial Dynamical Time (TDT). Both refer to the same time system.

  • 'TAI' - International Atomic Time (TAI).

  • 'SCLK' - Spacecraft Clock Time. An SCLK kernel must be loaded and a spacecraft SPICE ID must be provided.

  • 'GPS' - Global Position System (GPS) Time.

rep{‘NUM’, ‘AWU’, ‘CAL’, ‘DOY’, ‘ISOC’, ‘ISOD’, ‘JDTDB’, ‘JED’, ‘JDTDT’, ‘JDUTC’}, optional

The representation in which the EpochArray displays and returns times. The type of the returned time value or values depends on the selected representation, noted as “r_type” in the following bullets along with an example, “ex_ret”, of the return. Defaults to 'AWU'. Supported representations, their resepective return types, and example returns are:

  • 'NUM' - numerical representation in the EpochArray’s time system. Only valid for the uniform time systems TDB, TAI, TT, GPS, JDTDB, JDTDT, and their synonym systems if they have one, e.g. TDB and ET. r_type = float, ex_ret = 833544069.1849113.

  • 'AWU' - numerical representation with associated units, r_type = ArrayWUnits with units of seconds, ex_ret = 833544069.1849113 sec.

  • 'CAL' - Calendar date. An LSK must be loaded for this representation, r_type = str, ex_ret = '2026 JUN 12:00:00.000'.

  • 'DOY' - Day of year. An LSK must be loaded for this representation, r_type = str, ex_ret = '2026-152 // 12:00:00.000'.

  • 'ISOC' - International Organization for Standardization (ISO) 8601, calendar, r_type = str, ex_ret = '2026-06-01T12:00:00.000'.

  • 'ISOD' - International Organization for Standardization (ISO) 8601, day of year, r_type = str, ex_ret = '2026-152T12:00:00.000'.

  • 'JDTDB' or 'JED' - Julian Date relative to TDB (JDTDB), also known as Julian Ephemeris Date (JED).

  • 'JDTDT' - Julian Date relative to TDT (JDTDT).

  • 'JDUTC' - Julian Date relative to UTC (JDUTC), r_type = str, ex_ret = 'JD 2461193.0'.

precint, optional

Digits of precision in fractional seconds or days. Defaults to 16.

disp_lenint, optional

Number of digits/characters to display. Defaults to 25.

sc_idint, optional

SPICE ID of an associated onboard clock, required for SCLK definitions.

Attributes:
disp_len

Maximum number of characters in formatted time strings; longer strings are truncated to this length.

et

Raw ephemeris time — TDB seconds past J2000.

ndim

The number of dimensions of the EpochArray.

prec

Digits of precision in fractional seconds (or days for Julian Date representations) used when formatting string representations.

representation

The time representation in which the EpochArray’s times are formatted.

sc_id

SPICE ID of the associated onboard spacecraft clock, required for SCLK-system epochs.

shape

The shape of the EpochArray

size

The size of the EpochArray.

system

The time system in which the EpochArray is defined.

times

The numerical values of each epoch contained within the EpochArray, defined in the EpochArray’s time system and formatted based on its representation.

Methods

duration([units])

Find the length of time spanned by the EpochArray.

enforce_precision([precision])

Return a high-precision string representation of this epoch.

from_dict(data)

Reconstruct an EpochArray from a dict produced by to_dict().

interval(start, end[, dt, n_epochs, sys, ...])

Create epochs across an interval with given time step and time system.

to([sys, rep])

Convert to the given time system and/or representation.

to_dict()

Serialize to a JSON-friendly dict.

IntervalBound

TimeRepresentation

TimeSystem

Raises:
MissingLSKError

Raised if a time or times are defined in a non-TDB system and there is no recognized leapsecond kernel (LSK) furnished in the kernel pool. See the SPICE LSK time system reading for more.

SCLKError

Raised if:

  • a time or times are given in an SCLK representation when there is no recognized spacecraft clock time kernel (SCLK) furnished in the kernel pool. See the SPICE SCLK time system reading for more.

  • an epoch is requested with a time representation other than 'NUM' or 'AWU' as there is no conversion between spacecraft clock ticks and any of the other representations.

SCIDError

Raised if:

  • a time or times are given in SCLK but a spacecraft ID was not given.

  • a time or times are given in SCLK but the given spacecraft ID could not be located in the kernel pool.

See the SPICE SCLK conversions reading for more.

BadTimeError

Raised if:

  • a time is given in an unrecognized format.

  • a time is given in a recognized format but the time itself is

    unrecognizable, e.g, '2026 FEB 50'.

References

[1]

NASA/NAIF. (2021, December 23). SPICE Time Subsystem. Navigation and Ancillary Information Facility. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/time.html

[2]

NASA/NAIF. (2021, September 4). SCLK Required Reading. Navigation and Ancillary Information Facility. https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/sclk.html#SCLK%20kernels

classmethod from_dict(data: dict) → EpochArray#

Reconstruct an EpochArray from a dict produced by to_dict().

static interval(start: Self | float | str, end: Self | float | str, dt: ArrayWUnits = None, n_epochs: int = None, sys: Literal['TDB', 'ET', 'UTC', 'TT', 'TDT', 'TAI', 'SCLK', 'GPS'] = None, rep: Literal['NUM', 'AWU', 'CAL', 'DOY', 'ISOC', 'ISOD', 'JDTDB', 'JED', 'JDTDT', 'JDUTC'] = 'AWU', sc_id: int = None)#

Create epochs across an interval with given time step and time system.

Supports two different forms of interval definition:

  • step definition - create evenly stepped epochs along the half open interval [start, end), defined by the step size dt.

  • count definition - create evenly spaced epochs along the closed interval [start, end], defined by the total number of epochs n_epochs.

Cannot define both a dt and an n_epochs as they are mutually exclusive and define different interval construction processes.

Parameters:
startIntervalBound

The starting epoch, defined as one of the following types:

  • EpochArray - Defined in its system and representation.

  • float - Assumed to be given in TDB unless another system is provided.

  • str - Numerical strings are cast as floats and assumed to be in seconds past J2000 (TDB). Non-numerical strings are parsed according to their format/representation (ISO, calendar, DOY, JD).

endIntervalBound

The ending epoch, defined as one of the following types:

  • EpochArray - Defined in its system and representation.

  • float - Assumed to be given in TDB unless another system is provided.

  • str - Numerical strings are cast as floats and assumed to be in seconds past J2000 (TDB). Non-numerical strings are parsed according to their format/representation (ISO, calendar, DOY, JD).

dtArrayWUnits, optional

The amount of time to space each epoch by along the duration of the interval. Mutually exclusive with num_epochs. Defaults to None.

n_epochsint, optional

The number of total epochs to place evenly within the interval. Mutually exclusive with dt. Defaults to None.

sysTimeSystem, optional

The time system in which the epochs are defined. If start is of type EpochArray, its time system will be used unless a different system is provided. If start is not an EpochArray but end is, its time system will be used unless a different system is provided. If neither start nor end are EpochArray and the system is not defined, an error will be raised.

See EpochArray for all valid time systems.

repTimeRepresentation, optional

The time representation in which the epochs are defined. If start is of type EpochArray, its representation will be used unless a different one is provided. If start is not an EpochArray but end is, its representation will be used unless a different one is provided. If neither start nor end are EpochArray, the representation is assumed to be 'NUM'.

See EpochArray for all valid time representations.

Returns:
time_intervalEpochArray

The interval of epochs.

Examples

Create interval using str and float type interval bounds:

import scarabaeus as scb
hr = scb.Units.get_units('hr')
epochs = scb.EpochArray.interval(start = '2026 JUN 01 00:00:00.000',
                                 end   = 574538961669.1835, # 1 day later in TDB
                                 dt    = scb.ArrayWUnits(1, hr))

Create interval using EpochArray type interval bounds:

import scarabaeus as scb
hr = scb.Units.get_units('hr')

t0 = scb.EpochArray('2026 JUN 01 00:00:00.000')
tf = scb.EpochArray('2026 JUN 02 00:00:00.000')

epochs = scb.EpochArray.interval(start = t0, end = tf, dt = scb.ArrayWUnits(1, hr))
duration(units: Units | str = 'sec')#

Find the length of time spanned by the EpochArray.

Singular (scalar) epochs and non-chronological arrays are undefined.

Parameters:
unitsUnits of time or str, optional

The time units to return the duration in. Defaults to seconds.

Returns:
durArrayWUnits

The duration of time spanned by the EpochArray in the requested units, which are seconds by default.

Raises:
InvalidDurError

Raise if:

  • the EpochArray contains a single epoch (scalar).

  • the EpochArray does not contain chronological epochs, i.e. it doesn’t contain strictly increasing times in TDB.

enforce_precision(precision: int = 13)#

Return a high-precision string representation of this epoch.

Formats the internal ET (TDB seconds past J2000) value as a fixed-length decimal string with precision digits after the decimal point, padding or truncating as needed. Useful when interfacing with SPICE routines that require precise numeric strings. Only defined for scalar EpochArray instances.

Parameters:
precisionint, optional
to(sys: Literal['TDB', 'ET', 'UTC', 'TT', 'TDT', 'TAI', 'SCLK', 'GPS'] = None, rep: Literal['NUM', 'AWU', 'CAL', 'DOY', 'ISOC', 'ISOD', 'JDTDB', 'JED', 'JDTDT', 'JDUTC'] = None) → Self#

Convert to the given time system and/or representation.

Returns a new EpochArray pointing at the same physical instant(s); the instant itself is never changed. Internally epochs are always stored as TDB (ET) seconds past J2000, so converting the system does not modify the stored value — it changes the system the epoch is expressed in when displayed or returned via times. For example, an epoch built as 21:00:00 UTC converted with .to('TDB') renders as 21:01:09.18x in the TDB calendar (the same instant, expressed in a different system).

Parameters:
sysTimeSystem, optional

The time system to express the epochs in. See the class docstring for all valid systems. If omitted, the current system is kept.

repTimeRepresentation, optional

The representation to display/return the epochs in. See the class docstring for all valid representations. If omitted, the current representation is kept.

Returns:
EpochArray

A new EpochArray for the same instant(s) in the requested system and representation.

Raises:
ValueError

If neither sys nor rep is provided.

to_dict() → dict#

Serialize to a JSON-friendly dict.

Stores the underlying ET (TDB seconds past J2000) values, the original array shape, and the display system so the EpochArray can be exactly reconstructed by from_dict().

IntervalBound: TypeAlias#

alias of Self | float | str

TimeRepresentation: TypeAlias#

alias of Literal[‘NUM’, ‘AWU’, ‘CAL’, ‘DOY’, ‘ISOC’, ‘ISOD’, ‘JDTDB’, ‘JED’, ‘JDTDT’, ‘JDUTC’]

TimeSystem: TypeAlias#

alias of Literal[‘TDB’, ‘ET’, ‘UTC’, ‘TT’, ‘TDT’, ‘TAI’, ‘SCLK’, ‘GPS’]

property disp_len: int#

Maximum number of characters in formatted time strings; longer strings are truncated to this length.

property et: ndarray#

Raw ephemeris time — TDB seconds past J2000.

The internal numeric value(s) of the epochs, independent of the EpochArray’s display system and representation. Unlike times, the return type does not change with the representation, so this is the safe accessor when raw floats are needed (e.g. to hand epochs to an integrator or SPICE call).

property ndim: int#

The number of dimensions of the EpochArray.

0 for the scalar epoch that indexing an array returns (and that StateArray.epoch holds), which is the case that cannot be indexed further.

property prec: int#

Digits of precision in fractional seconds (or days for Julian Date representations) used when formatting string representations.

property representation: str#

The time representation in which the EpochArray’s times are formatted.

The representation determines the format in which the EpochArray is displayed as well as the type of object returned by its times.

property sc_id: int#

SPICE ID of the associated onboard spacecraft clock, required for SCLK-system epochs. None when no clock is associated.

property shape: tuple[int, int]#

The shape of the EpochArray

property size: int#

The size of the EpochArray.

property system: str#

The time system in which the EpochArray is defined.

property times: ndarray[float] | ndarray[str] | ArrayWUnits#

The numerical values of each epoch contained within the EpochArray, defined in the EpochArray’s time system and formatted based on its representation.