solprop.backends#

Execution backends behind one seam.

The NumPy reference and native backends (docs/dev/backends.md). This package exports the seam itself — the Backend protocol and the record types it returns — and solprop.backends.registry, which selects a backend by name and says why one is not usable, and the thread budget every backend’s pools are held within.

class solprop.backends.ThreadBudget(threads, source, oversubscribe=False, requested=None)#

Bases: object

The threads a process may run at once, and the limit that set it.

Attributes:
threadsint

The budget, at least one.

sourcestr

The tightest limit: "affinity", "physical cores", "top-tier cores", "cgroup quota" or "SOLPROP_THREADS".

oversubscribebool

Whether SOLPROP_OVERSUBSCRIBE lets an explicit count exceed the CPUs and the quota (see explicit()).

requestedint or None

SOLPROP_THREADS, which nothing exceeds, or None when it is unset.

explicit(count)#

Clamp a count someone asked for to what this budget allows.

Normally the budget itself. With SOLPROP_OVERSUBSCRIBE=1 only SOLPROP_THREADS holds, so a test can run more threads than the machine has CPUs on purpose (a thread-count invariance test on a small runner).

Parameters:
countint

The positive count asked for.

Returns:
int

The count allowed.

Examples

>>> from solprop.backends import ThreadBudget
>>> ThreadBudget(4, "affinity").explicit(8)
4
>>> ThreadBudget(4, "affinity", oversubscribe=True).explicit(8)
8
oversubscribe: bool = False#
requested: int | None = None#
source: str#
threads: int#
solprop.backends.thread_budget()#

Return how many threads this process may run at once (ADR-052).

The smallest of the CPUs it may run on (allowed_cpus: taskset, a batch scheduler’s allocation), the physical cores that hold them (physical_cores) and, on a chip with cores of several kinds, those of the fastest kind (top_tier_cores), both unless SOLPROP_THREADS is set, its control groups’ CPU quota (cgroup_cpus) and SOLPROP_THREADS. Every pool solprop sizes is held within it, and so is any count asked for explicitly unless SOLPROP_OVERSUBSCRIBE=1 (ThreadBudget.explicit()); the pools take turns, so each may use the whole budget.

Returns:
ThreadBudget

The budget and the limit that set it; on a tie, the earlier in that order.

Raises:
ValueError

If SOLPROP_THREADS is not a positive thread count, or SOLPROP_OVERSUBSCRIBE is neither 0 nor 1.

Examples

>>> from solprop.backends import thread_budget
>>> thread_budget().threads >= 1
True

Modules

adams_core

The Adams march's controller as functions of its policy and its state (SEP 39).

engines

The engine protocols: what a march asks of the state it advances (SEP 52 §5.2).

events

The records an execution session hands its service loop (SEP 47 section 5.3).

exponential

The phi functions and exponential Adams weights, in NumPy (SEP 16 sections 4.2-4.3).

export

Destination-based export of a session's field (SEP 47 section 5.4).

ledger

The Adams march's bookkeeping, shared by both backends (SEP 13 section 5, SEP 39).

low_storage

The low-storage interaction-picture RK4 march: replay-only, accepted in place.

memory

Byte counts and sizes the backends share for their memory ledgers.

node_chunk

How many nodes a response pass holds at once: the backend's node-chunk plan.

numpy_ref

The NumPy reference backend: the oracle.

populations

Map backend channel reductions onto the mixture's ordered species axis.

protocol

The seam: what a backend is, and what comes back from one.

records

The run records: what one run's march, session and monitor read (SEP 52 §5.1).

registry

Selecting one of the two backends by name, and saying why one is not usable.

rk_core

The Runge-Kutta march's controller as functions of its policy and state (SEP 45).

session

The execution-session contract between solprop and a backend (SEP 47 section 5).

sessions

The run layer's one door to a backend's sessions (SEP 47 phases 2 to 5).

spatial

Collect spatial host statistics through bounded transverse reconstruction chunks.

tdse_source

Assemble the TDSE response's macroscopic source at one evaluation (SEP 49).