osmose.engine.thread_policy

Single-run Numba thread policy.

A single 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). This module resolves a sensible thread count for a SINGLE run and applies it.

Scope: single-run entry points ONLY (UI run thread, benchmark, headless single-run scripts). NOT calibration — its nested ProcessPoolExecutor workers call the engine directly and want the unrestricted default; keep this out of the shared engine core so they are unaffected.

Functions

apply_single_run_threads([requested])	Set Numba's thread count for a single run; log it; return the count.
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.