Device configuration (sbd.device_config)

Selects the backend a solver call runs on. Pass a DeviceConfig as the device_config argument of sbd.sbd_solver.solve_sci_batch() or solve_sci().

class DeviceConfig(device='cpu', use_precalculated_dets=True, max_memory_gb=-1, use_gpu=None)

Bases: object

Helper class to configure CPU vs GPU execution for SBD calculations.

Usage:

from sbd.device_config import DeviceConfig
from sbd.sbd_solver import solve_sci_batch

device = DeviceConfig.auto()               # best backend that is built
device = DeviceConfig.cpu()                # or force one
device = DeviceConfig.gpu(max_memory_gb=16)

results = solve_sci_batch(..., device_config=device)

Initialize device configuration.

Parameters:

• device (str) – Backend device key — ‘cpu’, ‘gpu’ (NVHPC Thrust, NVIDIA-only), ‘gpu-omp’ (OpenMP target offload, NVIDIA or AMD), or any alias known to sbd._device_aliases. Default ‘cpu’.

• use_precalculated_dets (bool) – Use precalculated determinants (GPU only)

• max_memory_gb (int) – Maximum GPU memory in GB (-1 = auto)

• use_gpu (bool | None) – Deprecated boolean. If supplied without device, True maps to ‘gpu’ (Thrust) and False to ‘cpu’ for backward compatibility with pre-OMP-offload code.

classmethod auto(max_memory_gb=-1)

Auto-detect the best available backend and use it.

Chooses among the backends that were actually built, not merely the hardware present, so an AMD host or a CPU-only build is never handed a backend it lacks. The preference order is Thrust (‘gpu’) where it exists, then OpenMP offload (‘gpu-omp’), then CPU, the same order sbd.get_backend('auto') uses.

Parameters:

max_memory_gb (int) – Maximum GPU memory in GB (-1 = auto)

Returns:

DeviceConfig for the best backend that is both built and runnable

Return type:

DeviceConfig

classmethod cpu()

Force CPU execution.

Return type:

DeviceConfig

classmethod gpu(use_precalculated_dets=True, max_memory_gb=-1)

Force NVHPC Thrust GPU execution. NVIDIA only.

Requires SBD compiled with THRUST (the _core_gpu_thrust extension, i.e. SBD_BUILD_BACKEND=gpu, or the default auto).

There is no AMD equivalent: upstream SBD wires the Thrust path to nvc++ -cuda, so no rocThrust configuration exists to build. On an AMD host use gpu_omp() instead.

Parameters:

• use_precalculated_dets (bool)

• max_memory_gb (int)

Return type:

DeviceConfig

classmethod gpu_omp(max_memory_gb=-1)

Force OpenMP target-offload GPU execution. Works on NVIDIA and AMD.

Requires SBD compiled with the OMP-offload backend (the _core_gpu_omp_offload extension), which the default SBD_BUILD_BACKEND=auto builds whenever a GPU compiler is present; narrow it to gpu_omp_offload to build only this one.

One module and one device string serve both vendors – the same source and macros, compiled by nvc++ -mp=gpu with NVHPC’s libnvomp, or by amdclang++ --offload-arch=gfx* with LLVM’s libomp/libomptarget. sbd.get_backend('gpu-omp').__sbd_offload_target__ reports which, e.g. 'amdgcn-amd-amdhsa:gfx90a'.

It installs alongside the CPU backend (and Thrust, on NVIDIA) – backends are imported lazily, one per process, which is what keeps them apart. The one combination to avoid in a single process is this backend together with the CPU one: they share an OpenMP runtime (libnvomp on NVIDIA, libomp on AMD), and loading _core_cpu first leaves it initialised host-only, after which offload regions run on the host. sbd.has_backend_conflict() reports that combination.

Parameters:

max_memory_gb (int)

Return type:

DeviceConfig