oasislmf.pytools.common.id_index

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

HEADER
HEADER_N_KEYS
NOT_FOUND
MODE_FLAT
MODE_SORTED_UNIFORM
MODE_SORTED_NONUNIFORM
MODE_EMPTY
FLAT_DENSITY_THRESHOLD
SORTED_UNIFORM_REL_ERR

Functions

build(keys)	Build a self-describing lookup structure.
get_idx(arr, key)	Single lookup. Returns uint32 index or NOT_FOUND.
get_idx_batch(arr, keys, out)	Batch lookup, keys may be unsorted.
get_idx_sorted_batch(arr, sorted_keys, out)	Batch lookup for sorted keys.
match(target, query, out)	For each key in query, find its index in target.

Module Contents

oasislmf.pytools.common.id_index.HEADER = 4

oasislmf.pytools.common.id_index.HEADER_N_KEYS = 1

oasislmf.pytools.common.id_index.NOT_FOUND

oasislmf.pytools.common.id_index.MODE_FLAT = 0

oasislmf.pytools.common.id_index.MODE_SORTED_UNIFORM = 1

oasislmf.pytools.common.id_index.MODE_SORTED_NONUNIFORM = 2

oasislmf.pytools.common.id_index.MODE_EMPTY = 3

oasislmf.pytools.common.id_index.FLAT_DENSITY_THRESHOLD = 0.25

oasislmf.pytools.common.id_index.SORTED_UNIFORM_REL_ERR = 0.02

oasislmf.pytools.common.id_index.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.

oasislmf.pytools.common.id_index.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).

oasislmf.pytools.common.id_index.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).

oasislmf.pytools.common.id_index.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).

oasislmf.pytools.common.id_index.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