Scarabaeus Time System (EpochArray)#


Last revised 2026 MAY 8

Objectives#

All time information in Scarabaeus (SCB) is managed by the EpochArray class. This tutorial will cover the basics of utilizing EpochArray, demonstrating common errors that may arise, performing operations with it, and converting between the many different time systems and their representations.

See Also#

Imports and Set Up#

First we’ll import the necessary libraries, define units, and load in supplementary data, which for this tutorial are a leapsecond kernel (LSK) and a spacecraft clock kernel (SCLK). Note that we do not furnish either yet so we can illustrate what happens if you don’t have them loaded.

[1]:
import scarabaeus as scb
import supplementary as supp

import numpy as np

# define units
sec, hr, day = scb.Units.get_units(['sec', 'hr', 'day'])

# load tutorial data
data = supp.load_data()

# NOTE: it's generally good practice to load kernels here (we'll
#       need a leapsecond kernel (LSK) for this tutorial), but to
#       illustrate EpochArray error handling, the LSK furnish will
#       be omitted until later in the tutorial
SCB supplementary data out of date.
---------------------------------------------------------------------------
StdinNotImplementedError                  Traceback (most recent call last)
Cell In[1], line 10
      6 # define units
      7 sec, hr, day = scb.Units.get_units(['sec', 'hr', 'day'])
      8
      9 # load tutorial data
---> 10 data = supp.load_data()
     11
     12 # NOTE: it's generally good practice to load kernels here (we'll
     13 #       need a leapsecond kernel (LSK) for this tutorial), but to

File ~/scb_public/scarabaeus/docs/online_documentation/sphinx_files/_collections/tutorials/supplementary/supp_data.py:433, in load_data()
    431 waiting = True
    432 while waiting:
--> 433     response = input("\nDownload and generate missing files? (y/n): ")
    434     match response.strip().lower():
    435         case "y":

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/ipykernel/kernelbase.py:1514, in Kernel.raw_input(self, prompt)
   1512 if not self._allow_stdin:
   1513     msg = "raw_input was called, but this frontend does not support input requests."
-> 1514     raise StdinNotImplementedError(msg)
   1515 return self._input_request(
   1516     str(prompt),
   1517     self._get_shell_context_var(self._shell_parent_ident),
   1518     self.get_parent("shell"),
   1519     password=False,
   1520 )

StdinNotImplementedError: raw_input was called, but this frontend does not support input requests.

Creating EpochArrays#

EpochArray utilizes the SPICE time subsystem to perform conversions and provide representations. For a thorough explanation of SPICE’s time subsystem, see SPICE Time Subsystem Required Reading.

All of these different time systems and representations can sometimes be cumbersome to track while working on a script. EpochArray is intended to alleviate some of this overhead and make working with times as simple as possible. The following section will cover the most common ways to construct an EpochArray, but for an exhaustive list, see the EpochArray documentation.

EpochArray Error Handling#

EpochArray implements a robust set of error handling to make clear why something may be failing. This section will provide examples that raise a few of these errors to illustrate common pitfalls when working with time in SCB

  • NOTE: If an EpochArray error is raised as the result of another error deeper within SPICE, the SPICE error will also be noted at the end, e.g. -- SPICE(UNPARSEDTIME).


MissingLSKError#

All times in EpochArray are internally defined in Barycentric Dynamical Time (TDB), also known as Ephemeris Time (ET). This maintains consistency when performing time operations, but it also requires that a leapsecond kernel (LSK) be loaded if attempting to use to any non-uniform time representations like ISOC or CAL.

[2]:
# make sure the kernel pool is clean
scb.SpiceManager.clear_kernels()

# uniform systems work without an LSK as long as the format is also uniform
eparr_tdb = scb.EpochArray(0.0)  # default system is TDB, default rep is NUM
print(f'** Uniform time systems/representations work without an LSK **\n{eparr_tdb}\n')

# throws error if missing leapseconds when providing non-uniform definition
try:
    scb.EpochArray('2026 JUN 01')
except Exception as e:
    print('** Providing a non-uniform time without a loaded leapsecond '
          f'kernel will raise an error **\n'
          f'{type(e).__name__}: {e}\n')

# or attempting to set a non-uniform representation even if the definiton is uniform
try:
    scb.EpochArray(0.0, rep = 'ISOC')
except Exception as e:
    print('** Requesting a non-uniform time representation without a loaded '
          f'leapsecond kernel will raise an error **\n'
          f'{type(e).__name__}: {e}\n')
** Uniform time systems/representations work without an LSK **
0.0 sec (TDB)

** Providing a non-uniform time without a loaded leapsecond kernel will raise an error **
SpiceNOLEAPSECONDS:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(NOLEAPSECONDS) --

The variable that points to the leapseconds (DELTET/DELTA_AT) could not be located in the kernel pool.  It is likely that the leapseconds kernel has not been loaded.

str2et_c --> STR2ET --> TTRANS

================================================================================

** Requesting a non-uniform time representation without a loaded leapsecond kernel will raise an error **
MissingLSKError: Cannot set requested time representation ISOC. The necessary leapsecond kernel (LSK) could not be located in the kernel pool. -- SPICE(MISSINGTIMEINFO)

Note that the previously failed definitions function correctly when an LSK is loaded. Generally the LSK should be included in the metakernel, but we’ll load it directly here for clarity:

[3]:
# load light second kernel
scb.SpiceManager.load_kernel(data.lsk.path)

# redo previous definitions to show that they work now
print(scb.EpochArray('2026 JUN 01'))
print(scb.EpochArray(0.0, rep = 'ISOC'))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 2
      1 # load light second kernel
----> 2 scb.SpiceManager.load_kernel(data.lsk.path)
      3
      4 # redo previous definitions to show that they work now
      5 print(scb.EpochArray('2026 JUN 01'))

NameError: name 'data' is not defined

BadTimeError#

Passing epochs that formatted incorrectly or that don’t exist will raise a BadTimeError:

[4]:
# throws error if given an unrecognized format
try:
    scb.EpochArray('I AM NOT A TIME')
except Exception as e:
    print('** Providing an unrecognized time representation '
          'will raise an error **\n'
          f'{type(e).__name__}: {e}\n')

# throws error if the time doesn't make sense
try:
    scb.EpochArray('2026 FEB 50')
except Exception as e:
    print('** Providing a valid time represntation but invalid time '
          'itself will raise an error **\n'
          f'{type(e).__name__}: {e}\n')
** Providing an unrecognized time representation will raise an error **
SpiceUNPARSEDTIME:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(UNPARSEDTIME) --

The input string contains an unrecognizable substring beginning at the character marked by <I>: "<I> AM NOT A TIME TDB"

str2et_c --> STR2ET

================================================================================

** Providing a valid time represntation but invalid time itself will raise an error **
SpiceBADTIMESTRING:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(BADTIMESTRING) --

The day of the month specified for the month of February was 5.00E+01.  For February the day must be at least 1.0D0 and less than 2.9E+01.

str2et_c --> STR2ET

================================================================================


SCLKErorr#

The last error we’ll cover occurs when defining spacecraft clock (SCLK) epochs without a set of clock coefficients loaded in the kernel pool via a .tscn file. In order to match the epoch to the spacecraft’s clock, we’ll also need to provide a spacecraft ID:

[5]:
# make sure the kernel pool is clean (and reload LSK again since we cleared it)
scb.SpiceManager.clear_kernels()
scb.SpiceManager.load_kernel(data.lsk.path)

# throws error if missing SCLK kernel and SC ID
try:
    scb.EpochArray(100000, sys = 'SCLK', sc_id = -64)  # OSIRIS-REx ID
except Exception as e:
    print('** Attempting to define an epoch in SCLK without an SCLK '
          'kernel loaded will raise an error **\n'
          f'{type(e).__name__}: {e}\n')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[5], line 3
      1 # make sure the kernel pool is clean (and reload LSK again since we cleared it)
      2 scb.SpiceManager.clear_kernels()
----> 3 scb.SpiceManager.load_kernel(data.lsk.path)
      4
      5 # throws error if missing SCLK kernel and SC ID
      6 try:

NameError: name 'data' is not defined

Just like for the LSK, loading an SCLK kernel will allow the previously failed definitions to pass:

[6]:
# load spacecraft clock kernel
scb.SpiceManager.load_kernel(data.OREx_sclk.path)

# redo previously failed definitions and see that they work
print(scb.EpochArray(100000, sys = 'SCLK', sc_id = -64))
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[6], line 2
      1 # load spacecraft clock kernel
----> 2 scb.SpiceManager.load_kernel(data.OREx_sclk.path)
      3
      4 # redo previously failed definitions and see that they work
      5 print(scb.EpochArray(100000, sys = 'SCLK', sc_id = -64))

NameError: name 'data' is not defined

Array Functionality#

EpochArray fully supports scalar and array-like definitions:

[7]:
# use the same epoch for simplicity
time_str   = '2026 JUN 01 00:00:00.000'

# define and print different definition shapes
eparr_sclr = scb.EpochArray(time_str)                         # scalar
eparr_vec  = scb.EpochArray([time_str, time_str, time_str])   # vector (1D array)
eparr_mat  = scb.EpochArray(np.array([[time_str, time_str],   # matrix (nD array)
                                        [time_str, time_str]]))

for eparr in [eparr_sclr, eparr_vec, eparr_mat]:
    print(eparr)
---------------------------------------------------------------------------
SpiceNOLEAPSECONDS                        Traceback (most recent call last)
Cell In[7], line 5
      1 # use the same epoch for simplicity
      2 time_str   = '2026 JUN 01 00:00:00.000'
      3
      4 # define and print different definition shapes
----> 5 eparr_sclr = scb.EpochArray(time_str)                         # scalar
      6 eparr_vec  = scb.EpochArray([time_str, time_str, time_str])   # vector (1D array)
      7 eparr_mat  = scb.EpochArray(np.array([[time_str, time_str],   # matrix (nD array)
      8                                         [time_str, time_str]]))

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:160, in EpochArray.__init__(self, times, sys, rep, prec, disp_len, sc_id)
    158 self._validate_and_set_system(sys)
    159 self._validate_and_set_rep(rep)
--> 160 self._validate_and_set_to_et(times)
    162 # precision and display
    163 self._prec = prec

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:324, in EpochArray._validate_and_set_to_et(self, times)
    321 match self._system:
    322     case "TDB" | "ET":
    323         # append TDB so spice knows its TDB
--> 324         et_vals.append(spice.str2et(f"{t} TDB"))
    325     case "UTC":
    326         # str2et already assumes UTC
    327         et_vals.append(spice.str2et(t))

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:161, in spice_error_check.<locals>.with_errcheck(*args, **kwargs)
    157             res = f(*args, **kwargs)
    158             check_for_spice_error(f)
    159             return res
    160         except BaseException:
--> 161             raise

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:141, in check_for_spice_error(f)
    137         explain = getmsg("EXPLAIN", 100).strip()
    138         long = getmsg("LONG", 1841).strip()
    139         traceback = qcktrc(200)
    140         reset()
--> 141         raise dynamically_instantiate_spiceyerror(
    142             short=short, explain=explain, long=long, traceback=traceback
    143         )

SpiceNOLEAPSECONDS:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(NOLEAPSECONDS) --

The variable that points to the leapseconds (DELTET/DELTA_AT) could not be located in the kernel pool.  It is likely that the leapseconds kernel has not been loaded.

str2et_c --> STR2ET --> TTRANS

================================================================================

Additionally, instead of manually creating every entry in a vector of times, use EpochArray.interval(). This function supports two different interval construction methods, one that defines the interval using a given time step dt, and the other where it defines the interval using a given number of total epochs n_epochs. Both are shown below:

[8]:
# two day interval with points every 12 hours
epochs = scb.EpochArray.interval(start = '2026 JUN 01', end = '2026 JUN 03',
                                   dt = scb.ArrayWUnits(12, hr),
                                   sys = 'TDB', rep = 'CAL')
dur = epochs.duration(units = day)  # can also get the duration sequential times
print(f'** Step-defined epoch interval with duration {dur}:\n{epochs}')

# two day interval with 3 total epochs
epochs = scb.EpochArray.interval(start = '2026 JUN 01', end = '2026 JUN 03',
                                   n_epochs = 3, sys = 'UTC', rep = 'CAL')
dur = epochs.duration(units = day)
print(f'\n** Count-defined epoch interval with duration {dur}:\n{epochs}')
---------------------------------------------------------------------------
SpiceNOLEAPSECONDS                        Traceback (most recent call last)
Cell In[8], line 2
      1 # two day interval with points every 12 hours
----> 2 epochs = scb.EpochArray.interval(start = '2026 JUN 01', end = '2026 JUN 03',
      3                                    dt = scb.ArrayWUnits(12, hr),
      4                                    sys = 'TDB', rep = 'CAL')
      5 dur = epochs.duration(units = day)  # can also get the duration sequential times

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:1310, in EpochArray.interval(start, end, dt, n_epochs, sys, rep, sc_id)
   1308 ## convert start and end if neccessary and get in TDB floats
   1309 if not isinstance(start, EpochArray):
-> 1310     start = EpochArray(start, sys = sys)
   1312 if not isinstance(end, EpochArray):
   1313     end = EpochArray(end, sys = sys)

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:160, in EpochArray.__init__(self, times, sys, rep, prec, disp_len, sc_id)
    158 self._validate_and_set_system(sys)
    159 self._validate_and_set_rep(rep)
--> 160 self._validate_and_set_to_et(times)
    162 # precision and display
    163 self._prec = prec

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:324, in EpochArray._validate_and_set_to_et(self, times)
    321 match self._system:
    322     case "TDB" | "ET":
    323         # append TDB so spice knows its TDB
--> 324         et_vals.append(spice.str2et(f"{t} TDB"))
    325     case "UTC":
    326         # str2et already assumes UTC
    327         et_vals.append(spice.str2et(t))

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:161, in spice_error_check.<locals>.with_errcheck(*args, **kwargs)
    157             res = f(*args, **kwargs)
    158             check_for_spice_error(f)
    159             return res
    160         except BaseException:
--> 161             raise

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:141, in check_for_spice_error(f)
    137         explain = getmsg("EXPLAIN", 100).strip()
    138         long = getmsg("LONG", 1841).strip()
    139         traceback = qcktrc(200)
    140         reset()
--> 141         raise dynamically_instantiate_spiceyerror(
    142             short=short, explain=explain, long=long, traceback=traceback
    143         )

SpiceNOLEAPSECONDS:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(NOLEAPSECONDS) --

The variable that points to the leapseconds (DELTET/DELTA_AT) could not be located in the kernel pool.  It is likely that the leapseconds kernel has not been loaded.

str2et_c --> STR2ET --> TTRANS

================================================================================

Notice that the step defined interval is a half open interval [start, end) while the count defined interval is a closed interval [start, end].

EpochArray Operations#

Can only add time to an Epocharray. Can only subtract time or another EpochArray from an EpochArray:

[9]:
a = scb.EpochArray('2026 JUN 01', rep = 'JDTDB')
b = scb.EpochArray('2026 JUN 08', rep = 'JDTDB')

# add time to an epoch
a_plus_1_day = a + scb.ArrayWUnits(1, day)
print(f'a = {a}')
print(f'a + 1 day = {a_plus_1_day}\n')

# subtract time from an epoch
a_minus_1_day = a - scb.ArrayWUnits(1, day)
print(f'a = {a}')
print(f'a - 1 day = {a_minus_1_day}\n')

# subtract an epoch from an epoch to get a time
b_minus_a = b - a
print(f'a = {a}, b = {b}')
print(f'b - a = {b_minus_a.convert_to(day)}')
---------------------------------------------------------------------------
SpiceMISSINGTIMEINFO                      Traceback (most recent call last)
File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:589, in EpochArray._validate_and_set_rep(self, rep)
    588 try:
--> 589     spice.et2utc(0.0, "C", 30)  # dummy et to check for LSK
    590 except Exception as e:

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:161, in spice_error_check.<locals>.with_errcheck(*args, **kwargs)
    159             return res
    160         except BaseException:
--> 161             raise

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:141, in check_for_spice_error(f)
    139         traceback = qcktrc(200)
    140         reset()
--> 141         raise dynamically_instantiate_spiceyerror(
    142             short=short, explain=explain, long=long, traceback=traceback

SpiceMISSINGTIMEINFO:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(MISSINGTIMEINFO) --

The following variables, needed to convert between the input uniform time scales, were not found in the kernel pool: DELTET/DELTA_T_A, DELTET/K, DELTET/EB, DELTET/M. Your program may have failed to load a leapseconds kernel. Other possible causes of this problem include loading an invalid leapseconds kernel---one that lacks an initial \begindata marker or final newline character, or is otherwise corrupted---or deleting previously loaded kernel pool variables via calls to routines that clear the kernel pool.

et2utc_c --> ET2UTC --> UNITIM

================================================================================

During handling of the above exception, another exception occurred:

MissingLSKError                           Traceback (most recent call last)
Cell In[9], line 1
----> 1 a = scb.EpochArray('2026 JUN 01', rep = 'JDTDB')
      2 b = scb.EpochArray('2026 JUN 08', rep = 'JDTDB')
      3
      4 # add time to an epoch

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:159, in EpochArray.__init__(self, times, sys, rep, prec, disp_len, sc_id)
    157 # times, system, and representation info
    158 self._validate_and_set_system(sys)
--> 159 self._validate_and_set_rep(rep)
    160 self._validate_and_set_to_et(times)
    162 # precision and display

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:598, in EpochArray._validate_and_set_rep(self, rep)
    591 if "SPICE(MISSINGTIMEINFO)" in str(e):
    592     # no loaded LSK
    593     err_str = (
    594         f"Cannot set requested time representation {rep}. "
    595         "The necessary leapsecond kernel (LSK) could not "
    596         "be located in the kernel pool. -- SPICE(MISSINGTIMEINFO)"
    597     )
--> 598     raise type("MissingLSKError", (Exception,), {})(err_str)
    599 else:
    600     raise e

MissingLSKError: Cannot set requested time representation JDTDB. The necessary leapsecond kernel (LSK) could not be located in the kernel pool. -- SPICE(MISSINGTIMEINFO)

Converting Between EpochArrays#

Can perform conersions between systems and representaitons using .to():

[10]:
eparr_tdb_cal = scb.EpochArray('2000 JAN 01 12:00:00.000')

# convert to new system
eparr_gps_cal = eparr_tdb_cal.to(sys = 'GPS')
print(f'{eparr_tdb_cal} = {eparr_gps_cal}')

# change representation
eparr_gps_num = eparr_gps_cal.to(rep = 'NUM')
print(f'{eparr_gps_cal} = {eparr_gps_num}')

# can do both at the same time as well
epa_tai_jdutc = eparr_tdb_cal.to(sys = 'TAI', rep = 'JDUTC')
print(f'{eparr_tdb_cal} = {epa_tai_jdutc}')
---------------------------------------------------------------------------
SpiceNOLEAPSECONDS                        Traceback (most recent call last)
Cell In[10], line 1
----> 1 eparr_tdb_cal = scb.EpochArray('2000 JAN 01 12:00:00.000')
      2
      3 # convert to new system
      4 eparr_gps_cal = eparr_tdb_cal.to(sys = 'GPS')

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:160, in EpochArray.__init__(self, times, sys, rep, prec, disp_len, sc_id)
    158 self._validate_and_set_system(sys)
    159 self._validate_and_set_rep(rep)
--> 160 self._validate_and_set_to_et(times)
    162 # precision and display
    163 self._prec = prec

File ~/scb_public/scarabaeus/src/scarabaeus/timeAndFrame/EpochArray.py:324, in EpochArray._validate_and_set_to_et(self, times)
    321 match self._system:
    322     case "TDB" | "ET":
    323         # append TDB so spice knows its TDB
--> 324         et_vals.append(spice.str2et(f"{t} TDB"))
    325     case "UTC":
    326         # str2et already assumes UTC
    327         et_vals.append(spice.str2et(t))

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:161, in spice_error_check.<locals>.with_errcheck(*args, **kwargs)
    157             res = f(*args, **kwargs)
    158             check_for_spice_error(f)
    159             return res
    160         except BaseException:
--> 161             raise

File ~/scb_public/scarabaeus/.venv/lib/python3.11/site-packages/spiceypy/spiceypy.py:141, in check_for_spice_error(f)
    137         explain = getmsg("EXPLAIN", 100).strip()
    138         long = getmsg("LONG", 1841).strip()
    139         traceback = qcktrc(200)
    140         reset()
--> 141         raise dynamically_instantiate_spiceyerror(
    142             short=short, explain=explain, long=long, traceback=traceback
    143         )

SpiceNOLEAPSECONDS:
================================================================================

Toolkit version: CSPICE_N0067

SPICE(NOLEAPSECONDS) --

The variable that points to the leapseconds (DELTET/DELTA_AT) could not be located in the kernel pool.  It is likely that the leapseconds kernel has not been loaded.

str2et_c --> STR2ET --> TTRANS

================================================================================

Finally, as an easy reference, we’ll create a table of all the possible time systems and representations. We’ll pass the June 1st, 2026 EpochArray we’ve been using to a supplementary plotting function that will loop through each time system and display all of its representations along a row of the table.

[11]:
eparr_w_sc_id = scb.EpochArray(31622464.183948725, sys = 'TDB', sc_id = -64)
supp.plotting.plot_epocharray_table(eparr_w_sc_id, data.OREx_sclk.path)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[11], line 2
      1 eparr_w_sc_id = scb.EpochArray(31622464.183948725, sys = 'TDB', sc_id = -64)
----> 2 supp.plotting.plot_epocharray_table(eparr_w_sc_id, data.OREx_sclk.path)

NameError: name 'data' is not defined

We can see that we’ve checked the synonym systems like TDB and ET, as well as the sibling representations like NUM and AWU, so there will be a few identical rows and columns, but this is a good visual for all of the different combinations possible within EpochArray. Notice that plotting function has omitted representations that are are undefined for different systems, for example a JTDB representation of a TAI epoch.