mortie toc kernel

The word grammar is normative in the specification (§11, frozen for the 1.x series — bit layout, epoch and timescale, encode/decode laws, sort order, merge law, conformance vectors); this page documents the API surface over it.

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 the MOC kernel has to its ops over one cover), plus one ragged operator — tocs_reduce, the segmented sibling of toc_reduce (issue #177), kept here because it folds the word type itself rather than operating over covers. toc_normalize and toc_and are the set-algebra entries the issue #177 call-site audit ruled in: the canonical cover form and the one set operation over it. The many-cover plurals still land in mortie.batch. The names stay flat on the package (mortie.time2toc, ...).

These are the kernel layer: words in, words out, no wrapping cost, and nothing here is deprecated. The object layer over them is mortie.Toc, where every public method is a single delegation to a function on this page.

!!! warning "mortie.toc is no longer a module (issue #198)"

The implementation moved to `mortie/_toc.py` so that `mortie.toc` could
become the `Toc` constructor — the same move issue #196 made for
`mortie.moc`. `import mortie.toc` and `from mortie.toc import …`
**break**; the flat package names (`mortie.time2toc`,
`mortie.toc_merge`, …, and now `mortie.Q_START_NS`, `mortie.Q_END_NS`,
`mortie.TOC_MAX_NS`, `mortie.GPS_EPOCH_NS`) are unchanged and are the
supported spelling. `mortie.toc.toc_merge`-style attribute access still
resolves for one minor version, with a `DeprecationWarning`.

Worked example: examples/toc_temporal_coverage.ipynb walks the type end-to-end on synthetic data — encoding, the conservative merge, sorting without a comparator, the window predicates at a quantum boundary, and the UTC/GPS round-trip (run it on Binder).

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. :func:tocs_reduce is the one ragged operator here: the segmented sibling of :func:toc_reduce, kept beside its scalar because it is a fold over the word type itself rather than an op over covers (issue #177). :func:toc_normalize and :func:toc_and are the set-algebra entries the

177 call-site audit ruled in (issues #177 / #198): the canonical cover

form the Toc object builds on, and the one set operation over it. The many-cover plurals still land in :mod:mortie.batch.

Renamed from mortie/toc.py to mortie/_toc.py for issue #198, which frees the mortie.toc name for the :class:~mortie.toc_object.Toc constructor -- the same move issue #196 made for mortie.moc. Nothing here changed and nothing here is deprecated: these free functions are the kernel layer -- words in, words out, no wrapping cost -- and the array-first consumers keep calling them on plain ndarrays. :class:~mortie.toc_object.Toc is the object layer over them, and every one of its public methods is a single delegation to :func:toc_and.

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. tocs_reduce : the segmented form, one word per group.

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.
    tocs_reduce : the segmented form, one word per group.
    """
    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_normalize(words)

Canonicalize a toc word set: sorted maximal merges.

The canonical cover form (issues #177 <https://github.com/espg/mortie/issues/177> / #198 <https://github.com/espg/mortie/issues/198>): the unique sorted word set with the same decoded coverage as the input. Range words coalesce iff their decoded half-open [start, end) envelopes overlap or abut exactly -- a surviving decoded gap is never bridged, however small, because outward rounding only shrinks apparent gaps, so a gap that survives encoding is a floor on the true gap. A timestamp subsumed by a range's decoded span adds no coverage and is absorbed; a timestamp no range subsumes survives bit-identical as an exact degenerate member, and equal timestamps deduplicate. Timestamps never merge with each other or extend a range: re-encoding an instant into a range would round outward and change coverage, which normalize never does.

The canonical-form laws -- uniqueness, sortedness, duplicate-freeness -- are guarantees over encoder-produced words, the scope :func:toc_merge carries. An arbitrary bit pattern can decode to an empty envelope (a "range" whose decoded end falls below its decoded start), which subsumes nothing and does not collapse even against a copy of itself, so junk words can come back duplicated. Coverage is still preserved exactly (an empty envelope covers nothing) and the output is still deterministic and a fixpoint -- junk in is junk out.

Conservative directions (envelope algebra):

• Coverage-identical, not conservatively identical: the output's decoded coverage equals the input's exactly. Merged bounds are min/max of on-grid values (starts on the 2^31 ns grid, ends on 2^32), so no rounding arm exists anywhere in the operation.
• The input envelopes themselves over-cover the real data they were encoded from (the encoders round outward) and never under-cover; normalize preserves that direction unchanged.
• Lossy toward coverage (word identity, not coverage): which subsumed instants existed -- and how many times -- is dropped. Exact instants live in the sibling word arrays a cover is built from; a cover can be rebuilt from the arrays, never the arrays from a cover.

Parameters:

Name	Type	Description	Default
words	array - like	Toc words (uint64), any order, duplicates allowed.	required

Returns:

Type	Description
ndarray	The canonical cover, sorted uint64 words (a set, not a per-element map -- always an array, possibly shorter than the input; empty in, empty out).

Raises:

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

See Also

toc_merge : the single-envelope semilattice join (one word out). tocs_reduce : segmented single-envelope folds.

Examples:

Timestamps inside a covering range absorb; a free instant survives exactly, and the gap before it is preserved:

>>> import mortie, numpy as np
>>> r = mortie.span2toc(mortie.from_datetime64("2020-03-01"),
...                     mortie.from_datetime64("2020-03-05"))
>>> t = mortie.time2toc(mortie.from_datetime64(
...     ["2020-03-02", "2020-03-03", "2020-07-04"]))
>>> got = mortie.toc_normalize(np.append(t, np.uint64(r)))
>>> got.tolist() == sorted([r, int(t[2])])
True

Source code in mortie/_toc.py

def toc_normalize(words):
    """Canonicalize a toc word set: sorted maximal merges.

    The canonical cover form (issues `#177
    <https://github.com/espg/mortie/issues/177>`_ / `#198
    <https://github.com/espg/mortie/issues/198>`_): the unique sorted word
    set with the same decoded coverage as the input.  Range words coalesce
    **iff** their decoded half-open ``[start, end)`` envelopes overlap or
    abut exactly -- a surviving decoded gap is never bridged, however small,
    because outward rounding only shrinks apparent gaps, so a gap that
    survives encoding is a floor on the true gap.  A timestamp subsumed by
    a range's decoded span adds no coverage and is absorbed; a timestamp no
    range subsumes survives bit-identical as an exact degenerate member,
    and equal timestamps deduplicate.  Timestamps never merge with each
    other or extend a range: re-encoding an instant into a range would
    round outward and change coverage, which normalize never does.

    The canonical-form laws -- uniqueness, sortedness, duplicate-freeness
    -- are guarantees over **encoder-produced** words, the scope
    :func:`toc_merge` carries.  An arbitrary bit pattern can decode to an
    empty envelope (a "range" whose decoded end falls below its decoded
    start), which subsumes nothing and does not collapse even against a
    copy of itself, so junk words can come back duplicated.  Coverage is
    still preserved exactly (an empty envelope covers nothing) and the
    output is still deterministic and a fixpoint -- junk in is junk out.

    Conservative directions (envelope algebra):

    - **Coverage-identical, not conservatively identical**: the output's
      decoded coverage equals the input's exactly.  Merged bounds are
      min/max of on-grid values (starts on the 2^31 ns grid, ends on 2^32),
      so no rounding arm exists anywhere in the operation.
    - The input envelopes themselves **over-cover** the real data they were
      encoded from (the encoders round outward) and never under-cover;
      normalize preserves that direction unchanged.
    - **Lossy toward coverage** (word identity, not coverage): which
      subsumed instants existed -- and how many times -- is dropped.  Exact
      instants live in the sibling word arrays a cover is built from; a
      cover can be rebuilt from the arrays, never the arrays from a cover.

    Parameters
    ----------
    words : array-like
        Toc words (``uint64``), any order, duplicates allowed.

    Returns
    -------
    numpy.ndarray
        The canonical cover, sorted ``uint64`` words (a set, not a
        per-element map -- always an array, possibly shorter than the
        input; empty in, empty out).

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

    See Also
    --------
    toc_merge : the single-envelope semilattice join (one word out).
    tocs_reduce : segmented single-envelope folds.

    Examples
    --------
    Timestamps inside a covering range absorb; a free instant survives
    exactly, and the gap before it is preserved:

    >>> import mortie, numpy as np
    >>> r = mortie.span2toc(mortie.from_datetime64("2020-03-01"),
    ...                     mortie.from_datetime64("2020-03-05"))
    >>> t = mortie.time2toc(mortie.from_datetime64(
    ...     ["2020-03-02", "2020-03-03", "2020-07-04"]))
    >>> got = mortie.toc_normalize(np.append(t, np.uint64(r)))
    >>> got.tolist() == sorted([r, int(t[2])])
    True
    """
    w = _as_u64(words, "words")
    return np.asarray(_rustie.rust_toc_normalize(
        np.ascontiguousarray(w.ravel())))

toc_and(a, b)

Intersect two toc word sets: the canonical cover of the common coverage.

The one set operation the #177 <https://github.com/espg/mortie/issues/177> call-site audit ruled in beyond :func:toc_normalize (issue #198 <https://github.com/espg/mortie/issues/198>). Both operands are canonicalized internally, so raw unsorted word sets are accepted; the intersection then runs as a sorted-interval sweep, each surviving piece [max(starts), min(ends)). A timestamp survives iff it is genuinely covered on both sides -- inside the other cover's decoded ranges, or present as the identical instant in both -- and it survives bit-identical. Union needs no operator (concatenate, then :func:toc_normalize); the difference/xor directions deliberately do not ship -- conservative covers under-cover on subtraction, and no audited call site exists. Junk words carry :func:toc_normalize's scope: garbage in, garbage out, deterministically.

Conservative directions (envelope algebra):

• Exact by grid closure, no rounding: the max of two starts stays on the 2^31 ns start grid and the min of two ends on the 2^32 ns end grid, so every intersection bound is exactly representable.
• Never under-covers the true intersection: A ⊇ X and B ⊇ Y imply A ∩ B ⊇ X ∩ Y -- conservatism is preserved by construction.
• May over-cover near piece edges by up to one quantum per side, inherited from the operands' outward-rounded envelopes; the operation itself adds none.

Parameters:

Name	Type	Description	Default
a	array - like	Toc words (uint64), any order, duplicates allowed.	required
b	array - like	Toc words (uint64), the other operand.	required

Returns:

Type	Description
ndarray	The canonical cover of the intersection, sorted uint64 words (a set, not a per-element map -- always an array, empty when the covers share nothing).

Raises:

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

See Also

toc_normalize : the canonical cover form (and, with concatenation, the union). toc_overlaps : the boolean window predicate when only intersection emptiness is asked.

Examples:

Two observing campaigns share exactly their overlap week:

>>> import mortie
>>> a = mortie.span2toc(mortie.from_datetime64("2020-03-01"),
...                     mortie.from_datetime64("2020-03-15"))
>>> b = mortie.span2toc(mortie.from_datetime64("2020-03-10"),
...                     mortie.from_datetime64("2020-04-01"))
>>> both = mortie.toc_and([a], [b])
>>> s, e = mortie.toc2time(int(both[0]))
>>> s == mortie.toc2time(b)[0] and e == mortie.toc2time(a)[1]
True

Source code in mortie/_toc.py

def toc_and(a, b):
    """Intersect two toc word sets: the canonical cover of the common coverage.

    The one set operation the `#177
    <https://github.com/espg/mortie/issues/177>`_ call-site audit ruled in
    beyond :func:`toc_normalize` (issue `#198
    <https://github.com/espg/mortie/issues/198>`_).  Both operands are
    canonicalized internally, so raw unsorted word sets are accepted; the
    intersection then runs as a sorted-interval sweep, each surviving piece
    ``[max(starts), min(ends))``.  A timestamp survives iff it is genuinely
    covered on both sides -- inside the other cover's decoded ranges, or
    present as the identical instant in both -- and it survives
    bit-identical.  Union needs no operator (concatenate, then
    :func:`toc_normalize`); the difference/xor directions deliberately do
    not ship -- conservative covers under-cover on subtraction, and no
    audited call site exists.  Junk words carry :func:`toc_normalize`'s
    scope: garbage in, garbage out, deterministically.

    Conservative directions (envelope algebra):

    - **Exact by grid closure, no rounding**: the max of two starts stays on
      the 2^31 ns start grid and the min of two ends on the 2^32 ns end
      grid, so every intersection bound is exactly representable.
    - **Never under-covers the true intersection**: ``A ⊇ X`` and ``B ⊇ Y``
      imply ``A ∩ B ⊇ X ∩ Y`` -- conservatism is preserved by construction.
    - **May over-cover** near piece edges by up to one quantum per side,
      inherited from the operands' outward-rounded envelopes; the operation
      itself adds none.

    Parameters
    ----------
    a : array-like
        Toc words (``uint64``), any order, duplicates allowed.
    b : array-like
        Toc words (``uint64``), the other operand.

    Returns
    -------
    numpy.ndarray
        The canonical cover of the intersection, sorted ``uint64`` words
        (a set, not a per-element map -- always an array, empty when the
        covers share nothing).

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

    See Also
    --------
    toc_normalize : the canonical cover form (and, with concatenation,
        the union).
    toc_overlaps : the boolean window predicate when only intersection
        emptiness is asked.

    Examples
    --------
    Two observing campaigns share exactly their overlap week:

    >>> import mortie
    >>> a = mortie.span2toc(mortie.from_datetime64("2020-03-01"),
    ...                     mortie.from_datetime64("2020-03-15"))
    >>> b = mortie.span2toc(mortie.from_datetime64("2020-03-10"),
    ...                     mortie.from_datetime64("2020-04-01"))
    >>> both = mortie.toc_and([a], [b])
    >>> s, e = mortie.toc2time(int(both[0]))
    >>> s == mortie.toc2time(b)[0] and e == mortie.toc2time(a)[1]
    True
    """
    wa = _as_u64(a, "a")
    wb = _as_u64(b, "b")
    return np.asarray(_rustie.rust_toc_and(
        np.ascontiguousarray(wa.ravel()), np.ascontiguousarray(wb.ravel())))

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 over encoder-produced words, so every fold tree produces the identical uint64. Arbitrary bit patterns are garbage in, garbage out (see :func:toc_merge): each fold tree still answers deterministically, but the trees need not agree with one another.

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. tocs_reduce : the segmented form, one word per group.

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 over
    encoder-produced words, so every fold tree produces the identical
    ``uint64``.  Arbitrary bit patterns are garbage in, garbage out (see
    :func:`toc_merge`): each fold tree still answers deterministically, but
    the trees need not agree with one another.

    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.
    tocs_reduce : the segmented form, one word per group.
    """
    w = _as_u64(words, "words")
    return int(_rustie.rust_toc_reduce(np.ascontiguousarray(w.ravel())))

tocs_reduce(words, offsets)

Merge each group of toc words down to one word, in one call.

The segmented sibling of :func:toc_reduce (issue #177), named in the batch family's plural convention (mocs_and, mocs_to_orders): the whole ragged group set crosses the Python/Rust boundary once, the GIL is released for the batch, and Rust parallelizes across groups. Result i is bit-identical to toc_reduce(words[offsets[i]:offsets[i + 1]]) — same join, same instant preservation (a group of bitwise-equal timestamps comes back as that timestamp, not as its range envelope), same fold-tree independence. That identity is a guarantee over encoder-produced words, the scope :func:toc_merge carries: an out-of-domain "timestamp" can merge to a word with the timestamp flag set, and past that point the two functions' fold trees may disagree — each deterministic, neither wrong, since junk in is junk out.

Input is ragged in the arrow list layout the batch family uses; the output is dense — one uint64 per group — because the reduction is many→one per group, so there are no output offsets to carry. The consumer this exists for is a per-cell fold: zagg's GEDI shot pooling and its ATL03 overview envelopes-of-envelopes both run the scalar reduce once per cell (zagg#410 <https://github.com/englacial/zagg/issues/410>_), which is the Python loop this call replaces.

Parameters:

Name	Type	Description	Default
words	array - like	Flat toc words (uint64), all groups concatenated.	required
offsets	array - like	int64 arrow list offsets: group i spans [offsets[i], offsets[i + 1]), so there are len(offsets) - 1 groups. The offsets must exactly cover words -- offsets[0] == 0 and offsets[-1] == len(words) -- so a sliced arrow array must be re-based before it gets here; anything else is an error naming the endpoint that failed. An empty group is an error, not an empty slot: the merge has no identity element, so many→one over no words has no answer, exactly as :func:toc_reduce refuses an empty array.	required

Returns:

Type	Description
ndarray	uint64 array of len(offsets) - 1 merged words, one per group.

Raises:

Type

Description

ValueError

Fail-fast, naming the offending group (e.g. group 4217: tocs_reduce of an empty segment ...): an empty group, or a layout failure -- non-monotone / out-of-bounds offsets, or offsets that do not exactly cover words (the message names which endpoint failed). Also if words is negative or non-integer-typed. The index named is the lowest-index offender within its pass: layout is checked for the whole batch first, so a layout failure at a high index is reported ahead of an empty group at a low one -- deliberate, since the group indices an empty-group error is reported by are read out of offsets.

See Also

toc_reduce : the whole-array (one group) form. toc_merge : the elementwise pairwise join both reduce with.

Examples:

Two cells' shot times fold to one word each:

>>> import mortie, numpy as np
>>> w = mortie.time2toc(np.array([10, 20, 30, 40], dtype=np.uint64) * 10**9)
>>> got = mortie.tocs_reduce(w, [0, 3, 4])
>>> int(got[0]) == mortie.toc_reduce(w[:3]) and int(got[1]) == int(w[3])
True

Source code in mortie/_toc.py

def tocs_reduce(words, offsets):
    """Merge each group of toc words down to one word, in one call.

    The **segmented** sibling of :func:`toc_reduce` (issue #177), named in the
    batch family's plural convention (``mocs_and``, ``mocs_to_orders``): the
    whole ragged group set crosses the Python/Rust boundary once, the GIL is
    released for the batch, and Rust parallelizes across groups.  Result ``i``
    is bit-identical to ``toc_reduce(words[offsets[i]:offsets[i + 1]])`` — same
    join, same instant preservation (a group of bitwise-equal timestamps comes
    back as that timestamp, not as its range envelope), same fold-tree
    independence.  That identity is a guarantee over **encoder-produced**
    words, the scope :func:`toc_merge` carries: an out-of-domain "timestamp"
    can merge to a word with the timestamp flag set, and past that point the
    two functions' fold trees may disagree — each deterministic, neither
    wrong, since junk in is junk out.

    Input is ragged in the arrow list layout the batch family uses; the
    **output is dense** — one ``uint64`` per group — because the reduction is
    many→one per group, so there are no output offsets to carry.  The consumer
    this exists for is a per-cell fold: zagg's GEDI shot pooling and its ATL03
    overview envelopes-of-envelopes both run the scalar reduce once per cell
    (`zagg#410 <https://github.com/englacial/zagg/issues/410>`_), which is the
    Python loop this call replaces.

    Parameters
    ----------
    words : array-like
        Flat toc words (``uint64``), all groups concatenated.
    offsets : array-like
        ``int64`` arrow list offsets: group ``i`` spans
        ``[offsets[i], offsets[i + 1])``, so there are ``len(offsets) - 1``
        groups.  The offsets must **exactly cover** ``words`` --
        ``offsets[0] == 0`` and ``offsets[-1] == len(words)`` -- so a sliced
        arrow array must be re-based before it gets here; anything else is an
        error naming the endpoint that failed.  An **empty group is an
        error**, not an empty slot: the merge has no identity element, so
        many→one over no words has no answer, exactly as :func:`toc_reduce`
        refuses an empty array.

    Returns
    -------
    numpy.ndarray
        ``uint64`` array of ``len(offsets) - 1`` merged words, one per group.

    Raises
    ------
    ValueError
        Fail-fast, naming the offending group (e.g. ``group 4217:
        tocs_reduce of an empty segment ...``): an empty group, or a *layout*
        failure -- non-monotone / out-of-bounds offsets, or offsets that do not
        exactly cover ``words`` (the message names which endpoint failed).
        Also if ``words`` is negative or non-integer-typed.  The index named
        is the lowest-index offender **within its pass**: layout is checked for
        the whole batch first, so a layout failure at a high index is reported
        ahead of an empty group at a low one -- deliberate, since the group
        indices an empty-group error is reported *by* are read out of
        ``offsets``.

    See Also
    --------
    toc_reduce : the whole-array (one group) form.
    toc_merge : the elementwise pairwise join both reduce with.

    Examples
    --------
    Two cells' shot times fold to one word each:

    >>> import mortie, numpy as np
    >>> w = mortie.time2toc(np.array([10, 20, 30, 40], dtype=np.uint64) * 10**9)
    >>> got = mortie.tocs_reduce(w, [0, 3, 4])
    >>> int(got[0]) == mortie.toc_reduce(w[:3]) and int(got[1]) == int(w[3])
    True
    """
    w = _as_u64(words, "words")
    return np.asarray(_rustie.rust_tocs_reduce(
        np.ascontiguousarray(w.ravel()), _as_offsets(offsets)))

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