osmose.engine.thread_policy

Numba thread policy for single runs and for engine worker pools.

A Python-engine run’s mortality kernel is a Numba prange cell-loop (@njit(parallel=True)). Its output is bit-identical at every thread count, but it does NOT scale past ~physical cores: on a hyperthreaded box, using all logical cores is ~1.5-2x SLOWER than the physical-core optimum (per-timestep fork/join + hyperthread contention + memory bandwidth).

Two policies:

  • Single run (apply_single_run_threads): UI run thread, benchmark, headless single-run scripts use the physical-core budget.

  • Worker pools (apply_worker_threads, called in each worker’s initializer): each of W engine worker processes uses max(1, physical cores // W) threads. Measured 2026-11-14 on a 14-physical-core box (docs/perf/2026-11-14-worker-thread-sweep.md): 8 workers at Numba’s unrestricted default (28 threads each) gave 124 evals/h, while 14 workers at 1 thread gave 492 evals/h (3.96x, interleaved repeats). Unrestricted workers oversubscribe the cores. This reverses the 2026-07-15 decision to leave calibration workers unrestricted, which rested on a thread-backend measurement. OSMOSE_WORKER_THREADS overrides the rule: a positive integer forces that count, unrestricted restores Numba’s default.

The calls are thread-local runtime settings (numba.set_num_threads), never inherited environment variables, so a single-run cap cannot leak into a worker pool.

Apply the worker rule IN the worker, never in a parent that forks. On Numba’s GNU OpenMP threading layer, any Numba thread call (get_num_threads / set_num_threads, or a parallel kernel) starts the layer in the calling process, and a child forked afterwards is terminated (“fork() called from a process already using GNU OpenMP, this is unsafe”) as soon as it runs a parallel kernel. Fork-started pools must therefore take apply_worker_threads as their initializer, as forkserver and spawn pools do.

Functions

apply_single_run_threads([requested])

Set Numba's thread count for a single run; log it; return the count.

apply_worker_threads(n_workers)

Apply the worker rule in THIS process (a pool initializer); return the count applied.

logical_budget()

Logical CPUs the process may actually use (cgroup/taskset-aware).

physical_budget()

Distinct physical cores within the affinity set, via /sys topology.

resolve_engine_threads(requested)

Resolve a single-run Numba thread count.

worker_thread_count(n_workers)

Numba threads for each of n_workers engine worker processes.