oasislmf.pytools.common.id_index
================================

.. py:module:: oasislmf.pytools.common.id_index

.. autoapi-nested-parse::

   Unified integer key → index lookup.

   Auto-selects strategy at build time:
       mode 0: flat   (density >= 25%, shifted by min_id)
       mode 1: sorted uniform   (avg_err / n < 0.02, use interpolation)
       mode 2: sorted non-uniform (use binary search)

   Keys must be sorted on input. Return array has same dtype as input keys.

   Header (first HEADER elements, same dtype as keys):
       arr[0] = mode (0=flat, 1=sorted_uniform, 2=sorted_nonuniform)
       arr[1] = n_keys
       arr[2] = min_id
       arr[3] = max_id

   Data (arr[HEADER:]):
       Flat:   arr[HEADER + (key - min_id)] = index  (NOT_FOUND = empty)
       Sorted: arr[HEADER + i] = keys[i], position i = index

   Batch output:
       out[i] = index into keys passed to build(), or NOT_FOUND (0xFFFFFFFF).



Attributes
----------

.. autoapisummary::

   oasislmf.pytools.common.id_index.HEADER
   oasislmf.pytools.common.id_index.HEADER_N_KEYS
   oasislmf.pytools.common.id_index.NOT_FOUND
   oasislmf.pytools.common.id_index.MODE_FLAT
   oasislmf.pytools.common.id_index.MODE_SORTED_UNIFORM
   oasislmf.pytools.common.id_index.MODE_SORTED_NONUNIFORM
   oasislmf.pytools.common.id_index.MODE_EMPTY
   oasislmf.pytools.common.id_index.FLAT_DENSITY_THRESHOLD
   oasislmf.pytools.common.id_index.SORTED_UNIFORM_REL_ERR


Functions
---------

.. autoapisummary::

   oasislmf.pytools.common.id_index.build
   oasislmf.pytools.common.id_index.get_idx
   oasislmf.pytools.common.id_index.get_idx_batch
   oasislmf.pytools.common.id_index.get_idx_sorted_batch
   oasislmf.pytools.common.id_index.match


Module Contents
---------------

.. py:data:: HEADER
   :value: 4


.. py:data:: HEADER_N_KEYS
   :value: 1


.. py:data:: NOT_FOUND

.. py:data:: MODE_FLAT
   :value: 0


.. py:data:: MODE_SORTED_UNIFORM
   :value: 1


.. py:data:: MODE_SORTED_NONUNIFORM
   :value: 2


.. py:data:: MODE_EMPTY
   :value: 3


.. py:data:: FLAT_DENSITY_THRESHOLD
   :value: 0.25


.. py:data:: SORTED_UNIFORM_REL_ERR
   :value: 0.02


.. py:function:: build(keys)

   Build a self-describing lookup structure.

   Args:
       keys: sorted array of unique keys (uint32, int32, uint64, or int64).

   Returns:
       arr: array of same dtype as keys, with header + data.


.. py:function:: get_idx(arr, key)

   Single lookup. Returns uint32 index or NOT_FOUND.

   Note: explicit np.uint32() casts ensure the NOT_FOUND sentinel (0xFFFFFFFF)
   is returned correctly even when the underlying array has a signed dtype
   (e.g. int32 flat arrays store NOT_FOUND as -1, which must be cast to uint32).


.. py:function:: get_idx_batch(arr, keys, out)

   Batch lookup, keys may be unsorted.

   Args:
       arr: structure from build().
       keys: array of lookup keys (same dtype as build input).
       out: uint32 array of length len(keys).


.. py:function:: get_idx_sorted_batch(arr, sorted_keys, out)

   Batch lookup for sorted keys.

   Precondition: sorted_keys must be unique. In the FLAT branch, duplicates equal to
   arr[3] (the structure's max_id) are silently dropped past the first occurrence
   because the truncation uses `_interp_find_pos`, which returns only one position.
   Callers in this codebase pass deduplicated event/key arrays, so this is fine in
   practice — but if you add a new caller, dedupe first.

   Args:
       arr: structure from build().
       sorted_keys: sorted array (same dtype as build input).
       out: uint32 array of length len(sorted_keys).


.. py:function:: match(target, query, out)

   For each key in query, find its index in target.

   Args:
       target: structure from build() (the keys to search in).
       query:  structure from build() (the keys to look up).
       out:    uint32 array of length n_query_keys.
               out[i] = index of query's i-th key in target, or NOT_FOUND.

   Auto-selects strategy:
       query sorted           -> delegates to get_idx_sorted_batch
       both flat              -> iterate overlap range, O(1) per key
       query flat, target sorted -> iterate target overlap, flat check in query