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.

Parameters:

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

Returns:

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

Return type:

arr

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.

Parameters:

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

Parameters:

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

Parameters:

• 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