upxo.meshing.gbconformant.d3v2p1.backend module

Execution backend for d3v2p1: core detection, worker count, tier choice and a worker pool that falls back to serial execution.

Tiers: - ‘numpy’: serial, pure numpy, in this process. Always available. - ‘parallel’: worker processes. Used when more than one worker is allowed

and processes start; if they cannot start or a worker dies, the work is redone serially and the reason is recorded.

• ‘numba’: compiled kernels with numba threads, for stages that have kernels (numba_kernels=True in plan()). ‘auto’ prefers it when numba compiles; a stage without kernels, or a machine without numba, falls back to ‘parallel’ (and from there to ‘numpy’) and records why.

Choice order: explicit function arguments, then the environment variables UPXO_BACKEND (‘auto’, ‘numpy’, ‘parallel’, ‘numba’) and UPXO_N_WORKERS (a positive integer), then automatic selection. The automatic worker count is the number of physical cores this process may use, so hyper-threads are not oversubscribed. Results of every d3v2p1 stage do not depend on the tier or the worker count unless that stage’s documentation says otherwise.

upxo.meshing.gbconformant.d3v2p1.backend.logical_cores()

Logical CPUs in the machine (at least 1).

upxo.meshing.gbconformant.d3v2p1.backend.usable_cores()

Logical CPUs this process may run on (affinity / container limits).

upxo.meshing.gbconformant.d3v2p1.backend.physical_cores()

Physical cores, or None when they cannot be determined.

Uses psutil when installed, else /proc/cpuinfo on Linux.

upxo.meshing.gbconformant.d3v2p1.backend.auto_workers()

Default worker count: physical cores, limited to the usable CPUs. Falls back to the usable logical CPUs when physical cores are unknown.

upxo.meshing.gbconformant.d3v2p1.backend.cores()

JSON-compatible summary of the detected CPUs.

upxo.meshing.gbconformant.d3v2p1.backend.numba_available()

True when numba imports and compiles a small function (checked once).

upxo.meshing.gbconformant.d3v2p1.backend.check_workers(n_workers)

upxo.meshing.gbconformant.d3v2p1.backend.resolve_workers(n_workers=None)

Worker count: None or 0 -> UPXO_N_WORKERS or auto_workers(); a positive integer -> at most the usable CPUs.

class upxo.meshing.gbconformant.d3v2p1.backend.Plan(requested, used, workers, fallback=None)

Bases: object

Chosen tier and worker count for one stage call, plus what happened.

used: ‘numpy’, ‘parallel’ or ‘numba’. fallback: None, or the reason a requested tier was not used (missing kernels, pool start or worker failure).

property parallel

property numba

degrade(reason)

Switch to the serial numpy tier for the rest of the call.

report()

upxo.meshing.gbconformant.d3v2p1.backend.plan(backend='auto', n_workers=None, items=None, min_items_per_worker=1, numba_kernels=False, max_auto_workers=None)

Choose the tier and worker count for a stage call.

backend: ‘auto’ (default), ‘numpy’, ‘parallel’ or ‘numba’; ‘auto’ and the default n_workers=None defer to UPXO_BACKEND / UPXO_N_WORKERS. items: amount of independent work; with min_items_per_worker it caps the worker count, so small inputs run serially (or on one numba thread). numba_kernels: the stage has numba kernels; ‘auto’ and ‘numba’ then use them when numba is available. max_auto_workers: cap on the automatic worker count for stages that slow down with many workers; an explicit n_workers or UPXO_N_WORKERS overrides it.

class upxo.meshing.gbconformant.d3v2p1.backend.WorkerPool(plan, initializer=None, initargs=())

Bases: object

Process pool for one stage call that falls back to serial execution.

map(function, tasks, serial=None) returns [function(t) for t in tasks] in task order. In the parallel tier it runs in worker processes (started on first use, kept for the call). If the pool cannot start or a worker fails, the plan is switched to ‘numpy’, the reason recorded, and the tasks are run by serial() (default: function in this process). serial must be given when function relies on worker-only state (an initializer). Use as a context manager.

close()

map(function, tasks, serial=None)

class upxo.meshing.gbconformant.d3v2p1.backend.numba_threads(n)

Bases: object

Context manager: run numba parallel kernels on n threads, restoring the previous setting afterwards (n is capped at numba’s thread pool).

upxo.meshing.gbconformant.d3v2p1.backend.single_thread_numba()

In a worker process: numba kernels run on one thread (the processes already use the cores).