mortie.toc

The toc word — temporal order coverage (issue #175): one uint64 packing either an exact nanosecond timestamp or a conservative time range, sortable as a plain unsigned integer and closed under a semilattice merge. Times are ns since 1850-01-01 on a continuous, leap-free, GPS-aligned scale; the datetime64 / GPS converters are the only place leap seconds exist. Not an IVOA T-MOC. These flat-array elementwise ops are the type's scalar surface (the same relationship mortie.moc has to its ops over one cover); the ragged many-cover plurals land in mortie.batch when the interval-set algebra (issue #177) activates. The names stay flat on the package (mortie.time2toc, ...).

toc word -- temporal order coverage (issue #175).

One uint64, a tagged union of an exact nanosecond timestamp and a quantized, conservative time range, templated on what the morton word does for space: self-describing, sortable as a plain unsigned integer, and closed under a semilattice merge. All internal times are u64 nanoseconds since 1850-01-01T00:00:00 on a continuous, leap-free, GPS-aligned timescale; leap seconds exist only at the UTC boundary (:func:from_datetime64 / :func:to_datetime64).

Layout (bit 0 = LSB)::

[start: 32 bits, 2^31 ns units][flag: 1 bit][low: 31 bits]

• timestamp (flag = 1): the word is t_ns with the flag bit spliced in at position 31 -- monotone in t_ns.
• range (flag = 0): low is the end code, 31 bits at 2^32 ns; the encoded envelope is half-open [start * 2^31, end * 2^32), rounded outward with a strictly-greater end ceiling so it always properly contains the real interval.

Unsigned word order is order by conservative encoded start; within a tied start quantum, ranges sort before timestamps, then timestamps by exact ns and ranges shorter-first. The layout, epoch, merge results, and sort order are normative (words persist on disk) and pinned by golden fixtures; see the decision ledger on issue #175 <https://github.com/espg/mortie/issues/175> and the design record on zagg#410 <https://github.com/englacial/zagg/issues/410>.

Naming note: "toc" pleasantly echoes tick/tock and T-MOC, but this is not an IVOA T-MOC and does not conform to the IVOA MOC 2.0 recommendation (different epoch, timescale, and cell model -- see the T-MOC research on zagg#410 for why the hierarchical cell was rejected).

These flat-array elementwise ops are the type's scalar surface, mirroring the relationship :mod:mortie.moc has to its ops over one cover; the ragged many-cover plurals land in :mod:mortie.batch when the interval-set algebra (issue #177) activates.

Q_START_NS = 1 << 31 module-attribute

Start quantum: 2^31 ns (~2.15 s); a range's start code floors to this.

Q_END_NS = 1 << 32 module-attribute

End quantum: 2^32 ns (~4.29 s); a range's end code ceils to this.

TOC_MAX_NS = (1 << 63) - (1 << 32) module-attribute

Exclusive ceiling on internal times: 2^63 - 2^32 ns past the epoch (~4 s short of year 2142); the end code must fit its 31-bit field.

GPS_EPOCH_NS = 47486 * 86400 * 10 ** 9 module-attribute

Internal ns of the GPS epoch 1980-01-06T00:00:00: 47,486 proleptic-Gregorian days of 86,400 s past 1850-01-01 (the leap-free scale ticks exactly with GPS, so the constant is a plain day count -- validated against datetime.date arithmetic in the test suite).

time2toc(t_ns)

Encode exact instants (internal ns) as timestamp words.

The word is t_ns with a 1 flag bit spliced in at position 31, so unsigned word order over timestamps is exactly the ns order.

Parameters:

Name	Type	Description	Default
t_ns	int or array - like	Instant(s) in nanoseconds since 1850-01-01T00:00:00 on the continuous GPS-aligned scale, each in [0, TOC_MAX_NS).	required

Returns:

Type	Description
int or ndarray	Timestamp word(s), uint64 for array input (scalar in -> int out).

Raises:

Type	Description
ValueError	If any instant is negative, non-integer-typed, or at or beyond TOC_MAX_NS.

See Also

span2toc : encode a real interval as a range word. toc2time : decode words back to conservative bounds.

Source code in mortie/toc.py

def time2toc(t_ns):
    """Encode exact instants (internal ns) as timestamp words.

    The word is ``t_ns`` with a 1 flag bit spliced in at position 31, so
    unsigned word order over timestamps is exactly the ns order.

    Parameters
    ----------
    t_ns : int or array-like
        Instant(s) in nanoseconds since 1850-01-01T00:00:00 on the
        continuous GPS-aligned scale, each in ``[0, TOC_MAX_NS)``.

    Returns
    -------
    int or ndarray
        Timestamp word(s), ``uint64`` for array input (scalar in ->
        ``int`` out).

    Raises
    ------
    ValueError
        If any instant is negative, non-integer-typed, or at or beyond
        ``TOC_MAX_NS``.

    See Also
    --------
    span2toc : encode a real interval as a range word.
    toc2time : decode words back to conservative bounds.
    """
    is_scalar = np.isscalar(t_ns)
    t = _as_u64(t_ns, "t_ns")
    words = _rustie.rust_time2toc(np.ascontiguousarray(t.ravel()))
    words = words.reshape(t.shape)
    if is_scalar:
        return int(words[0])
    return words

span2toc(start_ns, end_ns)

Encode real closed intervals [start, end] as range words.

Outward rounding with a strictly-greater end ceiling: the start code floors to the 2^31 ns grid and the end code is (end >> 32) + 1 -- uniformly, including when end sits exactly on the 2^32 ns grid -- so the encoded envelope always properly contains the interval. start_ns and end_ns broadcast against each other.

Parameters:

Name	Type	Description	Default
start_ns	int or array - like	Interval start(s) in internal ns.	required
end_ns	int or array - like	Interval end(s) in internal ns (inclusive real endpoint), each >= start_ns and < TOC_MAX_NS.	required

Returns:

Type	Description
int or ndarray	Range word(s), uint64 for array input (scalar in -> int out).

Raises:

Type	Description
ValueError	If any start is after its end, or any end is at or beyond TOC_MAX_NS (the 31-bit end code would overflow -- ~4 s short of the year-2142 span ceiling; rejected rather than wrapped).

See Also

time2toc : encode an exact instant. toc2time : decode words back to conservative bounds.

Source code in mortie/toc.py

def span2toc(start_ns, end_ns):
    """Encode real closed intervals ``[start, end]`` as range words.

    Outward rounding with a strictly-greater end ceiling: the start code
    floors to the 2^31 ns grid and the end code is ``(end >> 32) + 1`` --
    uniformly, including when ``end`` sits exactly on the 2^32 ns grid --
    so the encoded envelope always properly contains the interval.
    ``start_ns`` and ``end_ns`` broadcast against each other.

    Parameters
    ----------
    start_ns : int or array-like
        Interval start(s) in internal ns.
    end_ns : int or array-like
        Interval end(s) in internal ns (inclusive real endpoint), each
        ``>= start_ns`` and ``< TOC_MAX_NS``.

    Returns
    -------
    int or ndarray
        Range word(s), ``uint64`` for array input (scalar in -> ``int``
        out).

    Raises
    ------
    ValueError
        If any start is after its end, or any end is at or beyond
        ``TOC_MAX_NS`` (the 31-bit end code would overflow -- ~4 s short
        of the year-2142 span ceiling; rejected rather than wrapped).

    See Also
    --------
    time2toc : encode an exact instant.
    toc2time : decode words back to conservative bounds.
    """
    is_scalar = np.isscalar(start_ns) and np.isscalar(end_ns)
    starts, ends = np.broadcast_arrays(_as_u64(start_ns, "start_ns"),
                                       _as_u64(end_ns, "end_ns"))
    words = _rustie.rust_span2toc(np.ascontiguousarray(starts.ravel()),
                                  np.ascontiguousarray(ends.ravel()))
    words = words.reshape(starts.shape)
    if is_scalar:
        return int(words[0])
    return words

toc2time(words)

Decode toc words to conservative (start_ns, end_ns) bounds.

A timestamp yields its exact instant twice, (t, t). A range yields its half-open envelope bounds: end_ns is exclusive, strictly greater than every instant the range covers (the encoder's strictly-greater ceiling guarantees this even for interval ends that sat exactly on the 2^32 ns grid).

Parameters:

Name	Type	Description	Default
words	int or array - like	Toc word(s) (uint64).	required

Returns:

Name	Type	Description
start_ns	int or ndarray	Conservative start(s) in internal ns, uint64 for array input (scalar in -> int out).
end_ns	int or ndarray	Exact instant (timestamps) or exclusive envelope end (ranges), same convention as start_ns.

Raises:

Type	Description
ValueError	If words is negative or non-integer-typed.

See Also

toc_is_range : which variant each word is.

Source code in mortie/toc.py

def toc2time(words):
    """Decode toc words to conservative ``(start_ns, end_ns)`` bounds.

    A timestamp yields its exact instant twice, ``(t, t)``.  A range
    yields its half-open envelope bounds: ``end_ns`` is **exclusive**,
    strictly greater than every instant the range covers (the encoder's
    strictly-greater ceiling guarantees this even for interval ends that
    sat exactly on the 2^32 ns grid).

    Parameters
    ----------
    words : int or array-like
        Toc word(s) (``uint64``).

    Returns
    -------
    start_ns : int or ndarray
        Conservative start(s) in internal ns, ``uint64`` for array input
        (scalar in -> ``int`` out).
    end_ns : int or ndarray
        Exact instant (timestamps) or exclusive envelope end (ranges),
        same convention as ``start_ns``.

    Raises
    ------
    ValueError
        If ``words`` is negative or non-integer-typed.

    See Also
    --------
    toc_is_range : which variant each word is.
    """
    is_scalar = np.isscalar(words)
    w = _as_u64(words, "words")
    starts, ends = _rustie.rust_toc2time(np.ascontiguousarray(w.ravel()))
    starts, ends = starts.reshape(w.shape), ends.reshape(w.shape)
    if is_scalar:
        return int(starts[0]), int(ends[0])
    return starts, ends

toc_merge(a, b)

Merge two toc words elementwise (the semilattice join).

Bitwise-equal inputs return that word unchanged -- merging two equal timestamps must not produce their range envelope. Any other pair merges conservative envelopes (min of start codes, max of end codes) into a range word. Exactly associative, commutative, and idempotent, so any fold tree over the same words produces the identical uint64. a and b broadcast against each other.

Parameters:

Name	Type	Description	Default
a	int or array - like	Toc word(s) (uint64).	required
b	int or array - like	Toc word(s) (uint64).	required

Returns:

Type	Description
int or ndarray	Merged word(s), uint64 for array input (scalar in -> int out).

Raises:

Type	Description
ValueError	If either input is negative or non-integer-typed.

See Also

toc_reduce : merge a whole array to one word.

Source code in mortie/toc.py

def toc_merge(a, b):
    """Merge two toc words elementwise (the semilattice join).

    Bitwise-equal inputs return that word unchanged -- merging two equal
    timestamps must not produce their range envelope.  Any other pair
    merges conservative envelopes (min of start codes, max of end codes)
    into a range word.  Exactly associative, commutative, and idempotent,
    so any fold tree over the same words produces the identical ``uint64``.
    ``a`` and ``b`` broadcast against each other.

    Parameters
    ----------
    a : int or array-like
        Toc word(s) (``uint64``).
    b : int or array-like
        Toc word(s) (``uint64``).

    Returns
    -------
    int or ndarray
        Merged word(s), ``uint64`` for array input (scalar in -> ``int``
        out).

    Raises
    ------
    ValueError
        If either input is negative or non-integer-typed.

    See Also
    --------
    toc_reduce : merge a whole array to one word.
    """
    is_scalar = np.isscalar(a) and np.isscalar(b)
    wa, wb = np.broadcast_arrays(_as_u64(a, "a"), _as_u64(b, "b"))
    merged = _rustie.rust_toc_merge(np.ascontiguousarray(wa.ravel()),
                                    np.ascontiguousarray(wb.ravel()))
    merged = merged.reshape(wa.shape)
    if is_scalar:
        return int(merged[0])
    return merged

toc_reduce(words)

Merge an array of toc words down to one word.

The fold tree is unspecified (parallel under the hood) -- safe because the merge is exactly associative, commutative, and idempotent, so every fold tree produces the identical uint64.

Parameters:

Name	Type	Description	Default
words	array - like	Toc words (uint64), at least one.	required

Returns:

Type	Description
int	The merged word.

Raises:

Type	Description
ValueError	If words is empty (the merge has no identity element), or is negative or non-integer-typed.

See Also

toc_merge : the elementwise pairwise form.

Source code in mortie/toc.py

def toc_reduce(words):
    """Merge an array of toc words down to one word.

    The fold tree is unspecified (parallel under the hood) -- safe because
    the merge is exactly associative, commutative, and idempotent, so
    every fold tree produces the identical ``uint64``.

    Parameters
    ----------
    words : array-like
        Toc words (``uint64``), at least one.

    Returns
    -------
    int
        The merged word.

    Raises
    ------
    ValueError
        If ``words`` is empty (the merge has no identity element), or is
        negative or non-integer-typed.

    See Also
    --------
    toc_merge : the elementwise pairwise form.
    """
    w = _as_u64(words, "words")
    return int(_rustie.rust_toc_reduce(np.ascontiguousarray(w.ravel())))

toc_is_range(words)

Test which variant each toc word is.

Parameters:

Name	Type	Description	Default
words	int or array - like	Toc word(s) (uint64).	required

Returns:

Type	Description
bool or ndarray	True where the word is a range (flag bit 31 = 0), False for a timestamp; bool ndarray for array input (scalar in -> bool out).

Raises:

Type	Description
ValueError	If words is negative or non-integer-typed.

Source code in mortie/toc.py

def toc_is_range(words):
    """Test which variant each toc word is.

    Parameters
    ----------
    words : int or array-like
        Toc word(s) (``uint64``).

    Returns
    -------
    bool or ndarray
        True where the word is a range (flag bit 31 = 0), False for a
        timestamp; ``bool`` ndarray for array input (scalar in ->
        ``bool`` out).

    Raises
    ------
    ValueError
        If ``words`` is negative or non-integer-typed.
    """
    is_scalar = np.isscalar(words)
    w = _as_u64(words, "words")
    flags = _rustie.rust_toc_is_range(np.ascontiguousarray(w.ravel()))
    flags = flags.reshape(w.shape)
    if is_scalar:
        return bool(flags[0])
    return flags

toc_overlaps(words, q_start_ns, q_end_ns)

Test which words intersect a half-open query window.

The test runs on each word's conservative encoded bounds (a timestamp is its exact instant; a range is its outward-rounded envelope), against the half-open window [q_start_ns, q_end_ns). Consequently it may over-report near window edges by up to one quantum (a range whose envelope grazes the window without its real interval doing so), and it never under-reports: every word whose real time content intersects the window tests True. An empty window (q_start_ns == q_end_ns) matches nothing.

Parameters:

Name	Type	Description	Default
words	int or array - like	Toc word(s) (uint64).	required
q_start_ns	int	Window start in internal ns (inclusive).	required
q_end_ns	int	Window end in internal ns (exclusive), >= q_start_ns.	required

Returns:

Type	Description
bool or ndarray	True where the word's conservative bounds intersect the window; bool ndarray for array input (scalar in -> bool out).

Raises:

Type	Description
ValueError	If the window is inverted, or words is negative or non-integer-typed.

See Also

toc_contains : containment in the window instead of intersection.

Source code in mortie/toc.py

def toc_overlaps(words, q_start_ns, q_end_ns):
    """Test which words intersect a half-open query window.

    The test runs on each word's **conservative encoded bounds** (a
    timestamp is its exact instant; a range is its outward-rounded
    envelope), against the half-open window ``[q_start_ns, q_end_ns)``.
    Consequently it may **over-report** near window edges by up to one
    quantum (a range whose envelope grazes the window without its real
    interval doing so), and it **never under-reports**: every word whose
    real time content intersects the window tests True.  An empty window
    (``q_start_ns == q_end_ns``) matches nothing.

    Parameters
    ----------
    words : int or array-like
        Toc word(s) (``uint64``).
    q_start_ns : int
        Window start in internal ns (inclusive).
    q_end_ns : int
        Window end in internal ns (exclusive), ``>= q_start_ns``.

    Returns
    -------
    bool or ndarray
        True where the word's conservative bounds intersect the window;
        ``bool`` ndarray for array input (scalar in -> ``bool`` out).

    Raises
    ------
    ValueError
        If the window is inverted, or ``words`` is negative or
        non-integer-typed.

    See Also
    --------
    toc_contains : containment in the window instead of intersection.
    """
    return _window(words, q_start_ns, q_end_ns, 0)

toc_contains(words, q_start_ns, q_end_ns)

Test which words are contained in a half-open query window.

The test runs on each word's conservative encoded bounds against the half-open window [q_start_ns, q_end_ns). Consequently it never over-reports (the real interval is inside the envelope, so envelope-in-window implies interval-in-window), and it may under-report near window edges by up to one quantum -- a range whose real interval fits the window but whose outward-rounded envelope spills past an edge tests False. An empty window (q_start_ns == q_end_ns) contains nothing.

Parameters:

Name	Type	Description	Default
words	int or array - like	Toc word(s) (uint64).	required
q_start_ns	int	Window start in internal ns (inclusive).	required
q_end_ns	int	Window end in internal ns (exclusive), >= q_start_ns.	required

Returns:

Type	Description
bool or ndarray	True where the word's conservative bounds fit inside the window; bool ndarray for array input (scalar in -> bool out).

Raises:

Type	Description
ValueError	If the window is inverted, or words is negative or non-integer-typed.

See Also

toc_overlaps : intersection with the window instead of containment.

Source code in mortie/toc.py

def toc_contains(words, q_start_ns, q_end_ns):
    """Test which words are contained in a half-open query window.

    The test runs on each word's **conservative encoded bounds** against
    the half-open window ``[q_start_ns, q_end_ns)``.  Consequently it
    **never over-reports** (the real interval is inside the envelope, so
    envelope-in-window implies interval-in-window), and it may
    **under-report** near window edges by up to one quantum -- a range
    whose real interval fits the window but whose outward-rounded
    envelope spills past an edge tests False.  An empty window
    (``q_start_ns == q_end_ns``) contains nothing.

    Parameters
    ----------
    words : int or array-like
        Toc word(s) (``uint64``).
    q_start_ns : int
        Window start in internal ns (inclusive).
    q_end_ns : int
        Window end in internal ns (exclusive), ``>= q_start_ns``.

    Returns
    -------
    bool or ndarray
        True where the word's conservative bounds fit inside the window;
        ``bool`` ndarray for array input (scalar in -> ``bool`` out).

    Raises
    ------
    ValueError
        If the window is inverted, or ``words`` is negative or
        non-integer-typed.

    See Also
    --------
    toc_overlaps : intersection with the window instead of containment.
    """
    return _window(words, q_start_ns, q_end_ns, 1)

from_datetime64(when)

Convert UTC datetime64 times to internal ns.

The internal scale is continuous and GPS-aligned: from 1972 the offset to naive UTC day-count time is GPS - UTC = TAI - UTC - 19 from the static in-module leap-second table (zero at the GPS epoch 1980-01-06, +18 s since 2017-01-01). Before 1972 the proleptic convention is zero offset (naive day-count seconds, no leap adjustment): it pins the epoch identity (1850-01-01T00:00:00 -> 0 ns exactly), whereas freezing the 1972 offset of -9 s would push the epoch itself to a negative, unrepresentable internal time. Pre-1972 "UTC" was not SI-second aligned anyway, and such data carries hours-level precision. Cost: the mapping steps back 9 s across the 1972-01-01 boundary, so the last 9 SI seconds of 1971 are not invertible (they alias early 1972); conversion is exact and invertible from 1972 on.

Parameters:

Name	Type	Description	Default
when	datetime64, str, or array-like	UTC instant(s); anything np.asarray(when, 'datetime64[ns]') accepts.	required

Returns:

Type	Description
int or ndarray	Internal ns (uint64) since 1850-01-01T00:00:00 on the continuous GPS-aligned scale; scalar in -> int out.

Raises:

Type	Description
ValueError	If any instant is before the 1850 epoch or at or beyond TOC_MAX_NS (the toc span ceiling, ~year 2142).

See Also

to_datetime64 : the inverse conversion. from_gps_ns : the leap-free GPS entry point.

Source code in mortie/toc.py

def from_datetime64(when):
    """Convert UTC ``datetime64`` times to internal ns.

    The internal scale is continuous and GPS-aligned: from 1972 the offset
    to naive UTC day-count time is ``GPS - UTC = TAI - UTC - 19`` from the
    static in-module leap-second table (zero at the GPS epoch 1980-01-06,
    +18 s since 2017-01-01).  **Before 1972** the proleptic convention is
    **zero offset** (naive day-count seconds, no leap adjustment): it pins
    the epoch identity (1850-01-01T00:00:00 -> 0 ns exactly), whereas
    freezing the 1972 offset of -9 s would push the epoch itself to a
    negative, unrepresentable internal time.  Pre-1972 "UTC" was not
    SI-second aligned anyway, and such data carries hours-level precision.
    Cost: the mapping steps back 9 s across the 1972-01-01 boundary, so
    the last 9 SI seconds of 1971 are not invertible (they alias early
    1972); conversion is exact and invertible from 1972 on.

    Parameters
    ----------
    when : datetime64, str, or array-like
        UTC instant(s); anything ``np.asarray(when, 'datetime64[ns]')``
        accepts.

    Returns
    -------
    int or ndarray
        Internal ns (``uint64``) since 1850-01-01T00:00:00 on the
        continuous GPS-aligned scale; scalar in -> ``int`` out.

    Raises
    ------
    ValueError
        If any instant is before the 1850 epoch or at or beyond
        ``TOC_MAX_NS`` (the toc span ceiling, ~year 2142).

    See Also
    --------
    to_datetime64 : the inverse conversion.
    from_gps_ns : the leap-free GPS entry point.
    """
    # A 0-d ndarray classifies as array (matching np.isscalar in the word
    # ops); np.isscalar itself is unusable here -- it is False for a
    # np.datetime64 scalar.
    is_scalar = np.ndim(when) == 0 and not isinstance(when, np.ndarray)
    naive = np.atleast_1d(
        np.asarray(when, dtype="datetime64[ns]")).astype(np.int64)
    # Ceiling guard on the *internal* result, evaluated before the offset
    # addition so the int64 arithmetic below cannot overflow: the offset in
    # force anywhere near the ceiling is the table's last entry, so every
    # naive value at or past this limit maps to internal >= TOC_MAX_NS.
    limit = TOC_MAX_NS - _EPOCH_1850_1970_NS - int(_OFFSETS_NS[-1])
    if naive.size and int(naive.max()) >= limit:
        raise ValueError(
            "datetime64 input is at or beyond the toc span ceiling "
            "(~year 2142)")
    idx = np.searchsorted(_UTC_STEPS_1970_NS, naive, side="right")
    internal = naive + _EPOCH_1850_1970_NS + _OFFSETS_NS[idx]
    if internal.size and int(internal.min()) < 0:
        raise ValueError("datetime64 input is before the 1850-01-01 epoch")
    internal = internal.astype(np.uint64)
    if is_scalar:
        return int(internal[0])
    return internal

to_datetime64(t_ns)

Convert internal ns to UTC datetime64[ns] times.

The inverse of :func:from_datetime64 (same leap table, same pre-1972 zero-offset convention). Internal instants that fall inside an inserted leap second render into the following UTC second -- datetime64 cannot express 23:59:60 -- so, e.g., the middle of the 2016-12-31 leap second renders as 2017-01-01T00:00:00.5. Roundtrip to_datetime64(from_datetime64(t)) is exact for every datetime64 from 1972 on (no datetime64 names a leap-second instant).

Parameters:

Name	Type	Description	Default
t_ns	int or array - like	Internal ns (uint64), each below 2**63.	required

Returns:

Type	Description
datetime64 or ndarray	UTC instant(s) as datetime64[ns]; scalar in -> np.datetime64 out.

Raises:

Type	Description
ValueError	If any value is negative, non-integer-typed, or at or beyond 2**63 (past every representable envelope bound).

See Also

from_datetime64 : the inverse conversion. to_gps_ns : the leap-free GPS exit point.

Source code in mortie/toc.py

def to_datetime64(t_ns):
    """Convert internal ns to UTC ``datetime64[ns]`` times.

    The inverse of :func:`from_datetime64` (same leap table, same pre-1972
    zero-offset convention).  Internal instants that fall *inside* an
    inserted leap second render into the following UTC second --
    ``datetime64`` cannot express 23:59:60 -- so, e.g., the middle of the
    2016-12-31 leap second renders as 2017-01-01T00:00:00.5.  Roundtrip
    ``to_datetime64(from_datetime64(t))`` is exact for every ``datetime64``
    from 1972 on (no ``datetime64`` names a leap-second instant).

    Parameters
    ----------
    t_ns : int or array-like
        Internal ns (``uint64``), each below ``2**63``.

    Returns
    -------
    datetime64 or ndarray
        UTC instant(s) as ``datetime64[ns]``; scalar in -> ``np.datetime64``
        out.

    Raises
    ------
    ValueError
        If any value is negative, non-integer-typed, or at or beyond
        ``2**63`` (past every representable envelope bound).

    See Also
    --------
    from_datetime64 : the inverse conversion.
    to_gps_ns : the leap-free GPS exit point.
    """
    is_scalar = np.isscalar(t_ns)
    t = _as_u64(t_ns, "t_ns")
    if t.size and int(t.max()) >= 1 << 63:
        raise ValueError("t_ns must lie below 2**63")
    idx = np.searchsorted(_INTERNAL_STEPS_NS, t, side="right")
    naive = t.astype(np.int64) - _OFFSETS_NS[idx] - _EPOCH_1850_1970_NS
    out = naive.astype("datetime64[ns]")
    if is_scalar:
        return out[0]
    return out

from_gps_ns(gps_ns)

Convert GPS time (ns since 1980-01-06T00:00:00) to internal ns.

A pure constant offset: both scales are continuous and leap-free and tick together, so the conversion is gps_ns + GPS_EPOCH_NS. The ICESat-2 ingest path (delta_time + atlas_sdp_gps_epoch -> GPS ns) composes with this directly.

Parameters:

Name	Type	Description	Default
gps_ns	int or array - like	GPS time(s) in ns since the GPS epoch, each below TOC_MAX_NS - GPS_EPOCH_NS.	required

Returns:

Type	Description
int or ndarray	Internal ns (uint64); scalar in -> int out.

Raises:

Type	Description
ValueError	If any value is negative, non-integer-typed, or maps at or beyond TOC_MAX_NS.

See Also

to_gps_ns : the inverse conversion.

Source code in mortie/toc.py

def from_gps_ns(gps_ns):
    """Convert GPS time (ns since 1980-01-06T00:00:00) to internal ns.

    A pure constant offset: both scales are continuous and leap-free and
    tick together, so the conversion is ``gps_ns + GPS_EPOCH_NS``.  The
    ICESat-2 ingest path (``delta_time`` + ``atlas_sdp_gps_epoch`` -> GPS
    ns) composes with this directly.

    Parameters
    ----------
    gps_ns : int or array-like
        GPS time(s) in ns since the GPS epoch, each below
        ``TOC_MAX_NS - GPS_EPOCH_NS``.

    Returns
    -------
    int or ndarray
        Internal ns (``uint64``); scalar in -> ``int`` out.

    Raises
    ------
    ValueError
        If any value is negative, non-integer-typed, or maps at or beyond
        ``TOC_MAX_NS``.

    See Also
    --------
    to_gps_ns : the inverse conversion.
    """
    is_scalar = np.isscalar(gps_ns)
    g = _as_u64(gps_ns, "gps_ns")
    if g.size and int(g.max()) >= TOC_MAX_NS - GPS_EPOCH_NS:
        raise ValueError(
            "gps_ns input maps at or beyond the toc span ceiling "
            "(~year 2142)")
    internal = g + np.uint64(GPS_EPOCH_NS)
    if is_scalar:
        return int(internal[0])
    return internal

to_gps_ns(t_ns)

Convert internal ns to GPS time (ns since 1980-01-06T00:00:00).

The exact inverse of :func:from_gps_ns. Internal times before the GPS epoch have no non-negative GPS representation and are rejected.

Parameters:

Name	Type	Description	Default
t_ns	int or array - like	Internal ns (uint64), each at or after GPS_EPOCH_NS.	required

Returns:

Type	Description
int or ndarray	GPS ns (uint64); scalar in -> int out.

Raises:

Type	Description
ValueError	If any value is negative, non-integer-typed, or before the GPS epoch.

See Also

from_gps_ns : the inverse conversion.

Source code in mortie/toc.py

def to_gps_ns(t_ns):
    """Convert internal ns to GPS time (ns since 1980-01-06T00:00:00).

    The exact inverse of :func:`from_gps_ns`.  Internal times before the
    GPS epoch have no non-negative GPS representation and are rejected.

    Parameters
    ----------
    t_ns : int or array-like
        Internal ns (``uint64``), each at or after ``GPS_EPOCH_NS``.

    Returns
    -------
    int or ndarray
        GPS ns (``uint64``); scalar in -> ``int`` out.

    Raises
    ------
    ValueError
        If any value is negative, non-integer-typed, or before the GPS
        epoch.

    See Also
    --------
    from_gps_ns : the inverse conversion.
    """
    is_scalar = np.isscalar(t_ns)
    t = _as_u64(t_ns, "t_ns")
    if t.size and int(t.min()) < GPS_EPOCH_NS:
        raise ValueError(
            "t_ns is before the GPS epoch 1980-01-06 (internal ns "
            f"{GPS_EPOCH_NS}); no non-negative GPS time exists")
    gps = t - np.uint64(GPS_EPOCH_NS)
    if is_scalar:
        return int(gps[0])
    return gps