Skip to main content

rusttorch_core/
device.rs

1//! Runtime device discovery and strict device selection.
2
3use std::sync::OnceLock;
4
5use tch::{Cuda, Device, Kind, Tensor};
6
7use crate::{Result, RustTorchError};
8
9/// A device request that is resolved against the linked LibTorch build.
10///
11/// New backend requests may be added in future releases.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13#[non_exhaustive]
14pub enum DeviceSpec {
15    /// Selects CUDA device 0, then MPS, then CPU, in that order of availability.
16    Auto,
17    /// Selects the CPU backend.
18    Cpu,
19    /// Selects the CUDA device at the given zero-based index.
20    Cuda(usize),
21    /// Selects Apple's Metal Performance Shaders backend.
22    Mps,
23}
24
25/// Backends that can actually be used by the current process.
26///
27/// Obtain this value from [`available_devices`]; future releases may report
28/// additional capabilities.
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30#[non_exhaustive]
31pub struct DeviceCapabilities {
32    /// Whether the CPU backend is available. This is always `true`.
33    pub cpu: bool,
34    /// Whether at least one CUDA device is usable.
35    pub cuda: bool,
36    /// Number of usable CUDA devices exposed by LibTorch.
37    pub cuda_device_count: usize,
38    /// Whether cuDNN is available with the CUDA backend.
39    pub cudnn: bool,
40    /// Whether an MPS tensor operation succeeds in this process.
41    pub mps: bool,
42}
43
44/// Probes the linked LibTorch backends without consulting Python at runtime.
45pub fn available_devices() -> DeviceCapabilities {
46    let cuda = Cuda::is_available();
47    let cuda_device_count = if cuda {
48        Cuda::device_count().max(0) as usize
49    } else {
50        0
51    };
52    DeviceCapabilities {
53        cpu: true,
54        cuda,
55        cuda_device_count,
56        cudnn: cuda && Cuda::cudnn_is_available(),
57        mps: mps_is_available(),
58    }
59}
60
61/// Resolves an explicit or automatic device request.
62pub fn resolve_device(spec: DeviceSpec) -> Result<Device> {
63    let capabilities = available_devices();
64    match spec {
65        DeviceSpec::Auto if capabilities.cuda => Ok(Device::Cuda(0)),
66        DeviceSpec::Auto if capabilities.mps => Ok(Device::Mps),
67        DeviceSpec::Auto | DeviceSpec::Cpu => Ok(Device::Cpu),
68        DeviceSpec::Cuda(index) if index < capabilities.cuda_device_count => {
69            Ok(Device::Cuda(index))
70        }
71        DeviceSpec::Cuda(index) => Err(RustTorchError::BackendUnavailable {
72            backend: "CUDA",
73            reason: format!(
74                "device {index} was requested, but the linked LibTorch build exposes {} usable CUDA device(s)",
75                capabilities.cuda_device_count
76            ),
77        }),
78        DeviceSpec::Mps if capabilities.mps => Ok(Device::Mps),
79        DeviceSpec::Mps => Err(RustTorchError::BackendUnavailable {
80            backend: "MPS",
81            reason:
82                "the linked LibTorch build or current machine does not provide a usable MPS device"
83                    .to_owned(),
84        }),
85    }
86}
87
88fn mps_is_available() -> bool {
89    static AVAILABLE: OnceLock<bool> = OnceLock::new();
90    *AVAILABLE.get_or_init(|| {
91        Tensor::f_zeros([1], (Kind::Float, Device::Mps))
92            .and_then(|tensor| tensor.f_add_scalar(1.0))
93            .is_ok()
94    })
95}
96
97/// Verifies that `tensor` is stored on `expected` for the named operation.
98///
99/// `context` identifies the operation or tensor in any resulting error. Returns
100/// [`RustTorchError::DeviceMismatch`] when the tensor's actual device differs
101/// from `expected`.
102pub fn ensure_device(context: impl Into<String>, tensor: &Tensor, expected: Device) -> Result<()> {
103    let actual = tensor.device();
104    if actual == expected {
105        Ok(())
106    } else {
107        Err(RustTorchError::DeviceMismatch {
108            context: context.into(),
109            expected,
110            actual,
111        })
112    }
113}