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 usesmax(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_THREADSoverrides the rule: a positive integer forces that count,unrestrictedrestores 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
|
Set Numba's thread count for a single run; log it; return the count. |
|
Apply the worker rule in THIS process (a pool initializer); return the count applied. |
|
Logical CPUs the process may actually use (cgroup/taskset-aware). |
|
Distinct physical cores within the affinity set, via /sys topology. |
|
Resolve a single-run Numba thread count. |
|
Numba threads for each of |