2. EpochArray#

class EpochArray(times: str | int | float | ArrayWUnits | list[str] | list[float] | list[int] | ndarray, time_frame: Literal['TDB', 'UTC', 'JD', 'CAL'] = 'TDB')#

Bases: object

Scarabaeus’ system for storing, manipulating, and converting between various representations of time.

Holds an epoch or an array of epochs and the time frame [1] the given epoch(s) is defined in. From NASA [2]:

“An epoch is an arbitrary fixed instant of time or date used as a chronological reference datum for calendars, celestial reference systems, star catalogs, and orbital motions.”

EpochArray objects are always defined as matrices. A single epoch can be thought of as a 1x1 matrix, and a vector of time steps can be thought of as a 1xn matrix.

Parameters:

  • times (TimeType (see Notes section)) – The value quantifying the moment or moments in time.

  • time_frame (str) –

    The time frame associated with the given times. Passed as a code denoting the frame. See Notes, Input Tables for more. Valid codes:

    • 'TDB'

    • 'UTC'

    • 'JD'

    • 'CAL'

See also

scarabaeus.ArrayWUnits

Scarabaeus’ representation of values with associated units.

Notes

TimeType:

Due to the many possible formats associated with differing time frames, when ingesting time values, EpochArray employs the type hint TimeType, an alias to any one of the following acceptable object types:

  • string

  • float

  • ArrayWUnits

  • list[str]

  • list[float]

  • list[int]

  • np.ndarray

Each of these input types correspond to a certain time frame. When a given time does not match the expected input type for the given time frame, an error is raised. See Input Tables below for more information.

Input Tables:

EpochArray supports four different time systems, denoted by the time_frame property. They are TDB, UTC, JDUTC, and CAL. See SPICE [1] for more on these systems. The below table provides infomration on:

  • Time System - the name of the time frame

  • Frame Code - the string passed to the time_frame argument that assigns the associated time frame

  • Expected Type(s) - valid types passed to the times argument that describes the time values

  • Input Format Example - an example of the time frame’s format

Time System

Frame Code

Expected Type(s)

Input Format Example
Barycentric Dynamical
Time

TDB
int, float, ArrayWUnits,
list[int], list[float],
np.ndarray

1096804869.182343
Coordinated Universal
Time

UTC

str, list[str], np.ndarray

'2050-01-00T00:00:00.000000'
Julian Data UTC

JD

str, list[str], np.ndarray

'JD 2469807.500000'

Calendar Date

CAL

str, list[str], np.ndarray

'2050 JAN 01 00:00:00.0000000000'

Math Operations:

EpochArray supports two explicit math operations:

  1. EpochArray ± time value = EpochArray

  2. EpochArray - EpochArray = time value

Adding or subtracting a time value (1. above) is only defined for an EpochArray object plus or minus a time value, defined as an ArrayWUnits object with Dimensions of Time. The resulting sum or difference is then returned as an EpochArray object. Matrix addition/subtraction rules apply.

Subtracting two EpochArray objects (2. above) follows matrix addition/subtraction rules. The resulting difference is returned as a time value, defined as an ArrayWUnits object with Units of seconds.

See Examples for more.

References

Examples

Define an epoch (1x1 EpochArray):

# initial setup
import scarabaeus as scb

# define epoch and its time frame
epoch = scb.EpochArray('2050-01-00T00:00:00.000000', 'UTC')

Define a set of times (1xn EpochArray):

import numpy as np

# generate random times
rng = np.random.default_rng()
times = rng.uniform(0,100,10)

# define the times in a time frame
epochs = scb.EpochArray(times, 'TDB')

Valid mathematical operations performed on EpochArray:

# generate units
sec = scb.Units.get_units('sec')

# create two EpochArray objects
ea_one = scb.EpochArray(1096804869.182343, 'TDB')
ea_two = scb.EpochArray(1096804879.182343, 'TDB')

# create an time value (ArrayWUnits)
time_val = scb.ArrayWUnits(1000, sec)

## from Notes section: valid math operations for EpochArray
# EpochArray ± time value = EpochArray
ea_one_offset1000 = ea_one + time_val

>>> print(ea_one_offset1000)
1096805869.182343 sec (TDB)

# EpochArray - EpochArray = time value
time_delta = ea_two - ea_one

>>> print(time_delta)
10.0 sec

Attributes

shape

The shape of the EpochArray

size

The size of the EpochArray.

time_frame

The time frame associated with the EpochArray.

times

The numerical values of each epoch contained within the EpochArray.

Methods

convert_to(to_time_frame)

DESC

def_new_time_frame(new_time_frame)

Defines a new time frame.

enforce_precision([precision])

DESC
classmethod def_new_time_frame(new_time_frame: str)#

Defines a new time frame.

Parameters:

new_time_frame (str) – The name of the new time frame to be added.

convert_to(to_time_frame: Literal['TDB', 'UTC', 'JD', 'CAL'])#

DESC

Parameters:

to_time_frame (str) – Desc

Returns:

converted – DESC

Return type:

EpochArray

Raises:

ValueError – Explain

Notes

Examples

stuff here
enforce_precision(precision: int = 13)#

DESC

Parameters:

precision (int, optional) – DESC

Notes

References

TimeType: TypeAlias = str | int | float | scarabaeus.units.ArrayWUnits.ArrayWUnits | list[str] | list[float] | list[int] | numpy.ndarray#
property shape: tuple[int, int]#

The shape of the EpochArray

property size: int#

The size of the EpochArray.

property time_frame: str#

The time frame associated with the EpochArray.

property times: ArrayWUnits | ndarray[ArrayWUnits]#

The numerical values of each epoch contained within the EpochArray.