curryer.spicetime ================= .. py:module:: curryer.spicetime .. autoapi-nested-parse:: SPICE-based time conversions. Module Listings --------------- leapsecond Methods to handle finding, loading and updating leapsecond kernels. The included leapsecond kernel will be loaded on import of this package if there is not another one loaded. convert Methods and classes to convert between time formats. Offers two APIs: `adapt` for converting from one format to another, and `SpiceTime` for tracking the time format in a numpy ndarray and converting to other time formats. Time Formats ------------ et : float64, seconds Ephemeris time, seconds since J2000 in ET. Also called Barycentric Dynamical Time (TDB) in SPICE documentation. All times are converted to and from ET. ugps : int64, microseconds GPS microseconds since 1980-01-06T00:00:00.0 UTC. gps : float64, seconds GPS seconds since 1980-01-06T00:00:00.0 UTC. tai : float64, seconds International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC. NOTE: Within the SPICE system "TAI" often represents the J2000 epoch, we deviate from that to support the standard 1958 epoch. utc : str, ISO Coordinated Universal Time (UTC), including leapseconds. The default input and output format is ISO. The output format can be specified with a Python-style datetime format string and the keyword `date_format` (e.g.,`date_format='%Y-%d-%m'`). Some format keys are not supported. .. rubric:: Examples >>> from curryer import spicetime >>> print(spicetime.adapt(0, 'ugps', 'utc')) '1980-01-06 00:00:00.000000' >>> ugps = spicetime.SpiceTime([0, 1], 'ugps') >>> print(repr(ugps)) SpiceTime([0, 1], ttype='ugps') >>> print(ugps.to_utc('%S.%f')) ['00.000000' '00.000001'] @author: Brandon Stone Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/curryer/spicetime/constants/index /autoapi/curryer/spicetime/convert/index /autoapi/curryer/spicetime/leapsecond/index /autoapi/curryer/spicetime/native/index /autoapi/curryer/spicetime/utils/index Classes ------- .. autoapisummary:: curryer.spicetime.SpiceTime Functions --------- .. autoapisummary:: curryer.spicetime.adapt Package Contents ---------------- .. py:class:: SpiceTime(shape, dtype=float, buffer=None, offset=0, strides=None, order=None) Bases: :py:obj:`numpy.ndarray` SPICE Date and Time Conversions. Time Formats ------------ et : float64, seconds Ephemeris time, seconds since J2000 in ET. Also called Barycentric Dynamical Time (TDB) in SPICE documentation. All times are converted to and from ET. ugps : int64, microseconds GPS microseconds since 1980-01-06T00:00:00.0 UTC. gps : float64, seconds GPS seconds since 1980-01-06T00:00:00.0 UTC. tai : float64, seconds International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC. NOTE: Within the SPICE system "TAI" often represents the J2000 epoch, we deviate from that to support the standard 1958 epoch. utc : str, ISO Coordinated Universal Time (UTC), including leapseconds. The default input and output format is ISO. The output format can be specified with a Python-style datetime format string and the keyword `date_format` (e.g.,`date_format='%Y-%d-%m'`). Some format keys are not supported. .. attribute:: ttype Date time format (e.g., "ugps"). Read-only, unless None. :type: str :param in_arr: Scalar or array of times. :type in_arr: float :param ttype: Supported format string specifying the input time format. :type ttype: str .. rubric:: Examples >>> st = SpiceTime('2016-05-09 14:49:17.371099', 'utc') >>> print(repr(st)) SpiceTime('2016-05-09 14:49:17.371099', dtype='>> print('Ephemeris Time: {}'.format(st.to_et())) Ephemeris Time: 516077425.55644935 >>> print('uGPS: {}'.format(st.to_ugps())) uGPS: 1146840574371099 >>> gps = st.to_gps() >>> print(gps.ttype) gps >>> st = SpiceTime([0, 1], 'gps') >>> print(st, st.ttype) [ 0. 1.] gps >>> print(st.to_utc('%S.%f')) ['00.000000' '01.000000'] .. rubric:: Notes - Requires a leapsecond kernel to be loaded (automated by library). .. py:method:: __array_finalize__(obj) Numpy's replacement for "__init__", supports construction, casting, and templates. .. rubric:: Notes Three possible ways to create this subclass: 1) Explicit construction: arr = SpiceTime(np.arange(3), fmt='et') type(`obj`) is ndarray; `self` is built in `SpiceTime.__new__` 2) View casting: arr = np.arange(3).view(SpiceTime) type(`obj`) can be `SpiceTime` or another 3) New-from-template: arr = np.SpiceTime(arange(3))[1:] type(`obj`) is `SpiceTime` The optional method `__array_prepare__` is similar, but before the values are calculated. .. rubric:: References - https://docs.scipy.org/doc/numpy/user/basics.subclassing.html .. py:method:: __array_prepare__(out_arr, context=None) Numpy's way of supporting subclassing from ufuncs (e.g., `np.min(et_arr)`). Allows viewing (ONLY) the output data structure and context (func & args) before the calculation. .. py:method:: __array_wrap__(out_arr, context=None) Numpy's way of supporting subclassing from ufuncs (e.g., `np.min(et_arr)`). Allows tweaking the output (`out_arr`), before final casting as `SpiceTime`. .. py:method:: __repr__() String representation of the array with the time format `ttype`. .. py:property:: ttype Time format. .. py:method:: adapt(to, **kwargs) Convert from the current time format to another. .. py:method:: to_et() Convert times to Ephemeris Time (SPICE; float64). .. py:method:: to_ugps() Convert times to GPS microseconds (int64). .. py:method:: to_gps() Convert times to GPS seconds (float64). .. py:method:: to_tai() Convert times to International Atomic Time seconds (1958; float64). .. py:method:: to_utc(date_format=None) Convert times to UTC strings (ISO format). .. py:function:: adapt(dt_val, from_=None, to=None, **kwargs) Convert between different date time formats. Time Formats ------------ et : float64, seconds Ephemeris time, seconds since J2000 in ET. Also called Barycentric Dynamical Time (TDB) in SPICE documentation. Most times are converted to and from ET. ugps : int64, microseconds GPS microseconds since 1980-01-06T00:00:00.0 UTC. Supports native (no SPICE) conversion to/from `dt64` and `epoch` et al. gps : float64, seconds GPS seconds since 1980-01-06T00:00:00.0 UTC. tai : float64, seconds International Atomic Time, seconds since 1958-01-01T00:00:00.0 UTC. NOTE: Within the SPICE system "TAI" often represents the J2000 epoch, we deviate from that to support the standard 1958 epoch. utc : str, ISO Coordinated Universal Time (UTC), including leapseconds. The default input and output format is ISO. The output format can be specified with a Python-style datetime format string and the keyword `date_format` (e.g.,`date_format='%Y-%d-%m'`). Some format keys are not supported. iso : str, ISO Alias for utc. dt64 : np.datetime64, ns Numpy datetime64 type with nanosecond precision. Does *not* support leapseconds. Default is to round those times up to the nearest second. Set `ceil_leapseconds=False` to raise errors instead. epoch : float64, days Fractional days since an epoch without leapseconds. The epoch name is defined with `from_epoch` or `to_epoch`, depending on the direction. See `sds_spice.spicetime.constants.EpochGpsDays`. Typically results in a loss of microsecond precision. Leapseconds are accounted for when determining the day, but the fraction for days with leapseconds assumes 8.64e4 seconds per day (no leapsecond). Times within leapseconds are rounded up. sorce : float64, days Fractional days since 2003-01-24. See `epoch` for details. tcte : float64, days Fractional days since 2013-11-18. See `epoch` for details. tsis : float64, days Fractional days since 2017-12-14. See `epoch` for details. tsis1 : float64, days Alias for `tsis`. See `tsis` for details. tsis2 : float64, days Fractional days since 2017-12-14 (placeholder; launch TBD). See `epoch` for details. ctim : float64, days Fractional days since 2022-07-02. See `epoch` for details. gpsd : float64, days Fractional days since 1980-01-06. See `epoch` for details. mjd : float64, days Fractional days since the Modified Julian epoch (1858-11-17). See `epoch` for details. jd : float64, days Fractional days since the Julian epoch. See `epoch` for details. Least precision of all time formats. :param dt_val: One or more time values to convert from one time format to another. :type dt_val: scalar or list or tuple or numpy.ndarray of str or int or float :param from_: Time format (ttype) of the input data `dt_val`. Default='ugps'. Note: Either one or both of `from_` or `to` must be specified. :type from_: str, optional :param to: Time format (ttype) to convert the input data `dt_val`, to. Default='ugps'. Note: Either one or both of `from_` or `to` must be specified. :type to: str, optional :param \*\*kwargs: Passes extra keywords that are not None to the conversion functions that support them (e.g., "date_format" when `to="utc"`). :returns: The converted time(s). Each time value has the data type of output time format specified by `to` (e.g., str for "utc"). When converting multiple times, the output container matches the input `dt_val`. :rtype: scalar or list or tuple or numpy.ndarray of str or int or float