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 form — toc_reduce's keyword-only offsets= spelling (issues #177, #187), whose segmented kernel stays beside the type 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 batch kernels 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 kernel here: the segmented form of :func:toc_reduce (reached through its offsets= keyword since issue

187), kept beside its entry point 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.

Batch vectorized: array in, array out, elementwise.

Scalar returns are numpy.uint64 (issue #187): every mortie word -- morton or toc -- comes back as the same numpy scalar type, so a word means one type on every entry point. Mind that uint64 arithmetic is not Python's: under NEP 50 a word mixed with a Python int stays uint64, so it wraps at 264 instead of promoting to a big integer (an arithmetic wrap raises a RuntimeWarning first, so -W error::RuntimeWarning turns it into a failure; a bit shift off the top of the word truncates silently, with no warning to catch), and mixing with a Python float gives float64. int(w) is the escape: it gives back the unbounded Python integer these operations used to run on.

NEP 50 is why numpy>=2 is a hard floor for this package -- below it a word's arithmetic promotes to float64, which is inexact above 2**53 while mortie words run near 2**62.

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
`uint64 or ndarray`	Timestamp word(s), `uint64` either way (scalar in -> `numpy.uint64` 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.

    **Batch vectorized**: array in, array out, elementwise.

    **Scalar returns are** ``numpy.uint64`` (issue #187): every mortie word
    -- morton or toc -- comes back as the same numpy scalar type, so a word
    means one type on every entry point.  Mind that ``uint64`` arithmetic is
    not Python's: under NEP 50 a word mixed with a Python ``int`` stays
    ``uint64``, so it **wraps at 2**64** instead of promoting to a big
    integer (an *arithmetic* wrap raises a ``RuntimeWarning`` first, so ``-W
    error::RuntimeWarning`` turns it into a failure; a bit shift off the top
    of the word truncates silently, with no warning to catch), and mixing
    with a Python ``float`` gives ``float64``.  ``int(w)`` is the escape: it
    gives back the unbounded Python integer these operations used to run on.

    NEP 50 is why ``numpy>=2`` is a hard floor for this package -- below it a
    word's arithmetic promotes to ``float64``, which is inexact above
    ``2**53`` while mortie words run near ``2**62``.

    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
    -------
    numpy.uint64 or ndarray
        Timestamp word(s), ``uint64`` either way (scalar in ->
        ``numpy.uint64`` 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 np.uint64(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.

Batch vectorized: array in, array out, elementwise.

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
`uint64 or ndarray`	Range word(s), `uint64` either way (scalar in -> `numpy.uint64` out). See :func:`time2toc` on `uint64` arithmetic.

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.

    **Batch vectorized**: array in, array out, elementwise.

    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
    -------
    numpy.uint64 or ndarray
        Range word(s), ``uint64`` either way (scalar in ->
        ``numpy.uint64`` out).  See :func:`time2toc` on ``uint64``
        arithmetic.

    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 np.uint64(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).

Batch vectorized: array in, arrays out, elementwise.

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).

    **Batch vectorized**: array in, arrays out, elementwise.

    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.

Batch vectorized: array in, array out, elementwise.

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
`uint64 or ndarray`	Merged word(s), `uint64` either way (scalar in -> `numpy.uint64` out). See :func:`time2toc` on `uint64` arithmetic.

Raises:

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

See Also

toc_reduce : merge a whole array to one word — or one word per group, via its offsets form.

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.

    **Batch vectorized**: array in, array out, elementwise.

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

    Returns
    -------
    numpy.uint64 or ndarray
        Merged word(s), ``uint64`` either way (scalar in ->
        ``numpy.uint64`` out).  See :func:`time2toc` on ``uint64``
        arithmetic.

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

    See Also
    --------
    toc_reduce : merge a whole array to one word — or one word per group,
        via its ``offsets`` form.
    """
    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 np.uint64(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). toc_reduce : single-envelope folds, whole-array or segmented (offsets=).

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).
    toc_reduce : single-envelope folds, whole-array or segmented
        (``offsets=``).

    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, *, offsets=None)`

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.

Batch vectorized (issue #187): pass offsets and the same call reduces a whole ragged column of groups, one word per group, in one crossing. The whole-array form returns numpy.uint64, the type every mortie word scalar carries -- see :func:time2toc on uint64 arithmetic.

Parameters:

Name	Type	Description	Default
`words`	`array - like`	Toc words (`uint64`), at least one. With `offsets`, the flat concatenation of every group in the column.	required
`offsets`	`array - like or None`	`int64` arrow list offsets selecting the segmented form: group `i` spans `words[offsets[i]:offsets[i + 1]]`, and the offsets must exactly cover `words`. `None` (default) is the whole-array form.	`None`

Returns:

Type	Description
`uint64 or ndarray`	The merged word; with `offsets`, a `uint64` array holding one merged word per group.

Raises:

Type	Description
`ValueError`	If `words` is empty (the merge has no identity element), or is negative or non-integer-typed. With `offsets`, an empty group is refused for the same reason, naming the group.

See Also

toc_merge : the elementwise pairwise form. _tocs_reduce : the segmented kernel the offsets form delegates to.

Source code in mortie/_toc.py

def toc_reduce(words, *, offsets=None):
    """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.

    **Batch vectorized** (issue #187): pass ``offsets`` and the same call
    reduces a whole ragged column of groups, one word per group, in one
    crossing.  The whole-array form returns ``numpy.uint64``, the type every
    mortie word scalar carries -- see :func:`time2toc` on ``uint64``
    arithmetic.

    Parameters
    ----------
    words : array-like
        Toc words (``uint64``), at least one.  With ``offsets``, the flat
        concatenation of every group in the column.
    offsets : array-like or None, optional
        ``int64`` arrow list offsets selecting the segmented form: group ``i``
        spans ``words[offsets[i]:offsets[i + 1]]``, and the offsets must
        exactly cover ``words``.  ``None`` (default) is the whole-array form.

    Returns
    -------
    numpy.uint64 or numpy.ndarray
        The merged word; with ``offsets``, a ``uint64`` array holding one
        merged word per group.

    Raises
    ------
    ValueError
        If ``words`` is empty (the merge has no identity element), or is
        negative or non-integer-typed.  With ``offsets``, an empty *group* is
        refused for the same reason, naming the group.

    See Also
    --------
    toc_merge : the elementwise pairwise form.
    _tocs_reduce : the segmented kernel the ``offsets`` form delegates to.
    """
    if offsets is not None:
        try:
            return _tocs_reduce(words, offsets)
        except ValueError as exc:
            # The kernel's empty-group refusal predates the plural name's
            # retirement (issue #187); re-raise naming the surviving entry
            # point.  Same type, same text otherwise, so handlers keep
            # working.
            raise ValueError(
                str(exc).replace("tocs_reduce", "toc_reduce")
            ) from None
    w = _as_u64(words, "words")
    return np.uint64(_rustie.rust_toc_reduce(np.ascontiguousarray(w.ravel())))

`toc_is_range(words)`

Test which variant each toc word is.

Batch vectorized: array in, array out, elementwise.

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.

    **Batch vectorized**: array in, array out, elementwise.

    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.

Batch vectorized: array in, array out, elementwise (one shared window).

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.

    **Batch vectorized**: array in, array out, elementwise (one shared
    window).

    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.

Batch vectorized: array in, array out, elementwise (one shared window).

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.

    **Batch vectorized**: array in, array out, elementwise (one shared
    window).

    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.

Batch vectorized: array in, array out, elementwise.

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.

    **Batch vectorized**: array in, array out, elementwise.

    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).

Batch vectorized: array in, array out, elementwise.

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).

    **Batch vectorized**: array in, array out, elementwise.

    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.

Batch vectorized: array in, array out, elementwise.

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.

    **Batch vectorized**: array in, array out, elementwise.

    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.

Batch vectorized: array in, array out, elementwise.

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.

    **Batch vectorized**: array in, array out, elementwise.

    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

mortie toc kernel

187), kept beside its entry point because it is a fold over the word type

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

Q_START_NS = 1 << 31 module-attribute

Q_END_NS = 1 << 32 module-attribute

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

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

time2toc(t_ns)

span2toc(start_ns, end_ns)

toc2time(words)

toc_merge(a, b)

toc_normalize(words)

toc_and(a, b)

toc_reduce(words, *, offsets=None)

toc_is_range(words)

toc_overlaps(words, q_start_ns, q_end_ns)

toc_contains(words, q_start_ns, q_end_ns)

from_datetime64(when)

to_datetime64(t_ns)

from_gps_ns(gps_ns)

to_gps_ns(t_ns)

`Q_START_NS = 1 << 31` `module-attribute`

`Q_END_NS = 1 << 32` `module-attribute`

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

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

`time2toc(t_ns)`

`span2toc(start_ns, end_ns)`

`toc2time(words)`

`toc_merge(a, b)`

`toc_normalize(words)`

`toc_and(a, b)`

`toc_reduce(words, *, offsets=None)`

`toc_is_range(words)`

`toc_overlaps(words, q_start_ns, q_end_ns)`

`toc_contains(words, q_start_ns, q_end_ns)`

`from_datetime64(when)`

`to_datetime64(t_ns)`

`from_gps_ns(gps_ns)`

`to_gps_ns(t_ns)`