`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:

values (str 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.
system (TimeSystem, 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).
- '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 'NUM'. 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 (JDTB), also known as Julian Ephemeris Date (JED).
- 'JDTDT' - Julian Date relative to TDT (JDTDT).
- 'JDUTC' - DESC, r_type = str, ex_ret = 'JD '.
prec (int, optional) – Digits of precision in fractional seconds or days. Defaults to 16.
disp_len (int, optional) – Number of digits/characters to display. Defaults to 25.
sc_id (int, optional) – SPICE ID of an associated onboard clock, required for SCLK definitions.

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.
.. _SPICE LSK time system reading` – :py:class:`https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/time.html#The%20Leapseconds%20Kernel%20LSK:
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.
.. _SPICE SCLK time system reading` – :py:class:`https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/time.html#Spacecraft%20Clock%20SCLK:
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.
.. _SPICE SCLK conversions reading` – :py:class:`https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/sclk.html#Converting%20between%20SCLK%20strings%20and%20ET%20or%20UTC:
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

Attributes:

disp_len: DESC
prec: DESC
representation: The time representation in which the EpochArray’s times are formatted.
sc_id: DESC
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, rep])	Create epochs across an interval with given time step and time system.
`to`([sys, rep])	Convert to the given time system and representation.
`to_dict`()	Serialize to a JSON-friendly dict.

IntervalBound
TimeRepresentation
TimeSystem

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')#

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:

start (IntervalBound) –
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).
end (IntervalBound) –
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).
dt (ArrayWUnits, 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_epochs (int, optional) – The number of total epochs to place evenly within the interval. Mutually exclusive with dt. Defaults to None.
sys (TimeSystem, 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.
rep (TimeRepresentation, 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_interval – The interval of epochs.

Return type:

EpochArray

Examples

Create interval using str and float type interval bounds:

Create interval using EpochArray type interval bounds:

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 (Units of time or str, optional) – The time units to return the duration in. Defaults to seconds.

Returns:

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

Return type:

ArrayWUnits

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 time 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.

Parameters:: precision (int, 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 representation.

Parameters:

sys (TimeSystem, optional) – {sys_desc}
rep (TimeRepresentation, optional) – DESC

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#: DESC

property prec: int#: DESC

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#: DESC

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.

EpochArray#

`EpochArray`#