solprop.backends.registry#

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

docs/dev/backends.md section 1: there are exactly two backends (ADR-077), native and numpy_ref. Selection is by name; availability is detected with importlib.util.find_spec() and never cached. A name that is neither, a retired backend’s included, is a BackendError naming the two; native without its package is an ImportError saying what to install.

The native backend is a second distribution, solprop-native, built from native/ in this repository and a required dependency; probing availability does not import it. Automatic selection is that backend, with no fallback (SEP 43). It refuses when the package is absent or this processor is below the installed build’s CPU baseline, using the package’s own check (solprop_native._cpu), loaded by path and read from the same code that refuses the import. Import, compatibility and construction errors remain visible, and they never trigger different arithmetic.

Module Attributes

`BACKEND_NAMES`	The two backends (ADR-077): the numerical reference and the native backend.
`AUTO`	What `"auto"` selects, with no fallback (SEP 43).
`REQUIRE_DEVICE_SETTING`	Where a run must execute: `cuda`, `hip` or `any`; unset for no requirement.

Functions

`available`()	Return the names of the backends that can run here and now.
`resolve_name`([name])	Resolve automatic selection to an installed backend's name.
`select`(name, problem, request, *[, grid, ...])	Construct the named backend for a validated problem and its run's request.
`select_batch`(owners)	Select batch arithmetic without substituting a different backend.
`statistics_refusal`(name, names)	Return why a backend cannot form some of the statistics named, or `None`.

solprop.backends.registry.AUTO: Final = 'native'#: What "auto" selects, with no fallback (SEP 43).

solprop.backends.registry.BACKEND_NAMES: Final = ('numpy_ref', 'native')#: The two backends (ADR-077): the numerical reference and the native backend.

solprop.backends.registry.REQUIRE_DEVICE_SETTING: Final = 'SOLPROP_REQUIRE_DEVICE'#: Where a run must execute: cuda, hip or any; unset for no requirement.

solprop.backends.registry.available()[source]#

Return the names of the backends that can run here and now.

Detection is by importlib.util.find_spec(), so nothing is imported and nothing is cached: a native package installed while the process runs becomes available without a restart, and initializing a native runtime is never a side effect of asking.

Returns:

tuple of str: The usable names, in the order of BACKEND_NAMES.

Examples

>>> from solprop.backends.registry import available
>>> "numpy_ref" in available()
True

solprop.backends.registry.resolve_name(name='auto')[source]#

Resolve automatic selection to an installed backend’s name.

Parameters:

namestr, optional: "auto" is "native", and has no fallback: it refuses if solprop_native can’t be found or this processor doesn’t meet the installed build’s CPU baseline. "native" and "numpy_ref" pass through unchanged.

Returns:

str: Concrete selection to store in simulation settings. This uncached probe does not import a backend or initialize a native runtime. select() constructs the backend; failures there never cause a fallback.

Raises:

BackendError: If name is neither backend (a retired backend’s name included), or "auto" has nothing to select; the message says what to do.

Examples

>>> resolve_name("numpy_ref")
'numpy_ref'

solprop.backends.registry.select(name, problem, request, *, grid=None, modes=None, profiles=None, tdse_binding=None, options=None)[source]#

Construct the named backend for a validated problem and its run’s request.

The backend receives the request where it is built (SEP 47 section 5.2): it checks the pair (solprop.translate.problem.validate_run()) and refuses an unsupported combination by name before it allocates, and it lowers the method, the error control, the itinerary, the planes and the statistics once. A session is then started on it with that request, adapted to one run (for_run()).

Parameters:

namestr: "native", "numpy_ref", or "auto" for the native backend, with no fallback (resolve_name()).
problemsolprop.translate.problem.PropagationProblem: The problem to step.
requestsolprop.translate.run_request.RunRequest: The run’s policies. The backend validates it with the problem again.
gridsolprop.grid.TimeGrid, optional: The grid the state lives on. Statistics need it and the kernel contract does not carry it, so it is passed alongside rather than inside the problem.
modescollections.abc.Sequence, optional: The propagated modes, in state order, for the statistics that need them.
profilescollections.abc.Mapping, optional: The z-profiles keyed by statistic name, for the profile statistics.
tdse_bindingsolprop.translate.tdse.TDSEBinding or None, optional: Driver-owned host response binding for a TDSE problem on NumPy.
optionssolprop.backends.session.ExecutionOptions or None, optional: The run’s execution options, among them an explicit node budget, from which the backend plans its node chunk (SEP 47 section 6.5); None for the automatic choice.

Returns:

Backend: The constructed backend.

Raises:

BackendError: If name is neither backend, or the backend does not run what the problem asks for; the message says what to use instead.
ImportError: If name is "native" and its package is missing; the message says what to install.

Examples

>>> from solprop.backends.registry import BACKEND_NAMES
>>> BACKEND_NAMES
('numpy_ref', 'native')

solprop.backends.registry.select_batch(owners)[source]#

Select batch arithmetic without substituting a different backend.

This is the reference group’s lockstep runner. The native backend runs its groups through its own prepared group instead (solprop.backends.sessions.start_group(); SEP 47 section 6.7), and is refused here by name.

Parameters:

ownerssequence of solprop.backends.protocol.Backend: Compatible, loaded member owners.

Returns:

BatchBackend: Common fixed march using the selected backend’s arithmetic.

Raises:

BackendError: If the members are not of one backend, or their backend has no lockstep runner (its groups start through start_group).

solprop.backends.registry.statistics_refusal(name, names)[source]#

Return why a backend cannot form some of the statistics named, or None.

Asking about the native backend imports the installed package, as selecting it would, to read the far-field statistics its class declares it forms.

Parameters:

namestr: The resolved backend name.
namescollections.abc.Sequence of str: The statistics asked for.

Returns:

str or None: The refusal, naming the backend that forms them, or None when the backend forms every one (or is not installed, which selecting it reports).

Examples

>>> from solprop.backends.registry import statistics_refusal
>>> statistics_refusal("numpy_ref", ["energy", "beam_spectrum"]) is None
True