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:
objectTime 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).listorndarray- 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 =ArrayWUnitswith 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_lenMaximum number of characters in formatted time strings; longer strings are truncated to this length.
etRaw ephemeris time — TDB seconds past J2000.
ndimThe number of dimensions of the EpochArray.
precDigits of precision in fractional seconds (or days for Julian Date representations) used when formatting string representations.
representationThe time representation in which the EpochArray’s times are formatted.
sc_idSPICE ID of the associated onboard spacecraft clock, required for SCLK-system epochs.
shapeThe shape of the EpochArray
sizeThe size of the EpochArray.
systemThe time system in which the EpochArray is defined.
timesThe numerical values of each epoch contained within the EpochArray, defined in the EpochArray’s time
systemand formatted based on itsrepresentation.
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
dtand ann_epochsas 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 toNone.- n_epochsint, optional
The number of total epochs to place evenly within the interval. Mutually exclusive with
dt. Defaults toNone.- sysTimeSystem, optional
The time system in which the epochs are defined. If
startis of typeEpochArray, its time system will be used unless a different system is provided. Ifstartis not anEpochArraybutendis, its time system will be used unless a different system is provided. If neitherstartnorendareEpochArrayand the system is not defined, an error will be raised.See
EpochArrayfor all valid time systems.- repTimeRepresentation, optional
The time representation in which the epochs are defined. If
startis of typeEpochArray, its representation will be used unless a different one is provided. Ifstartis not anEpochArraybutendis, its representation will be used unless a different one is provided. If neitherstartnorendareEpochArray, the representation is assumed to be'NUM'.See
EpochArrayfor all valid time representations.
- Returns:
- time_intervalEpochArray
The interval of epochs.
Examples
Create interval using
strandfloattype 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
EpochArraytype 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:
- units
Unitsof time or str, optional The time units to return the duration in. Defaults to seconds.
- units
- Returns:
- dur
ArrayWUnits The duration of time spanned by the EpochArray in the requested units, which are seconds by default.
- dur
- 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 as21:00:00 UTCconverted with.to('TDB')renders as21:01:09.18xin 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
sysnorrepis 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().
- TimeRepresentation: TypeAlias#
alias of
Literal[‘NUM’, ‘AWU’, ‘CAL’, ‘DOY’, ‘ISOC’, ‘ISOD’, ‘JDTDB’, ‘JED’, ‘JDTDT’, ‘JDUTC’]
- 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
systemandrepresentation. Unliketimes, 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.
0for the scalar epoch that indexing an array returns (and thatStateArray.epochholds), 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.
Nonewhen no clock is associated.
- property times: ndarray[float] | ndarray[str] | ArrayWUnits#
The numerical values of each epoch contained within the EpochArray, defined in the EpochArray’s time
systemand formatted based on itsrepresentation.