Enum CubeDevice 

#[non_exhaustive]
pub enum CubeDevice {
    Cuda(CudaDevice),
    Hip(AmdDevice),
    Metal(MetalDevice),
    Wgpu(WgpuDevice),
    Cpu(CpuDevice),
}

The device a cube tensor lives on.

One type across every runtime: which runtime a tensor runs on is what its device says, not what its type is. A device of any runtime.

A value names both the runtime and the device on it. A value can name a runtime the build does not link — the enum is the same in every build — and it is reaching for a client that then fails.

use cubecl::Device;

let client = Device::default().client();
println!("running on {}", client.name());

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Cuda(CudaDevice)

A device of the CUDA runtime.

Hip(AmdDevice)

A device of the HIP runtime.

Metal(MetalDevice)

A device of the native Metal runtime.

Wgpu(WgpuDevice)

A device of the wgpu runtime, on its default compiler.

Cpu(CpuDevice)

The device of the CPU runtime.

Implementations

impl Device

Naming one device rather than taking Device::default.

Each asks the runtime whether the machine really has what was named, so a device that would only fail at the client call is an error here instead. They are in every build: a runtime this one left out is DeviceUnavailable::NotLinked, not a function that went missing.

use cubecl::Device;

// The second GPU if there is one, otherwise whatever this machine has.
let device = Device::cuda(1).or_else(|_| Device::cpu())?;
let client = device.client();

pub fn cpu() -> Result<Device, DeviceUnavailable>

The CPU device.

pub fn cuda(index: usize) -> Result<Device, DeviceUnavailable>

The CUDA device at index, counting the GPUs CUDA reports.

pub fn rocm(index: usize) -> Result<Device, DeviceUnavailable>

The ROCm device at index, counting the GPUs HIP reports.

pub fn metal(kind: MetalDevice) -> Result<Device, DeviceUnavailable>

The native Metal device kind names.

The Metal runtime proper. Reaching Metal through wgpu’s MSL backend is Device::wgpu instead, and hands back a wgpu device.

pub fn wgpu(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The device kind names, on whichever graphics API this machine offers.

The portable one: which API it comes up on — and so which shader compiler it is fed — is the runtime’s to settle, best first, from the enabled features and what the machine has. Naming the API instead is vulkan and its siblings.

pub fn vulkan(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The Vulkan device kind names — and so SPIR-V, where the build and the adapter allow it.

Naming a graphics API is a promise the machine has to keep: this fails where the device is not reachable on Vulkan, rather than quietly coming up on something else. The same device on two APIs is two devices, each with an id and a client of its own.

use cubecl::{Device, device::WgpuDeviceKind};

let client = Device::vulkan(WgpuDeviceKind::default())?.client();

pub fn dx12(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The DirectX 12 device kind names. See vulkan for what naming an API promises.

pub fn gl(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The OpenGL device kind names. See vulkan for what naming an API promises.

pub fn webgpu(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The WebGPU device kind names — the browser’s own. See vulkan for what naming an API promises.

pub fn metal_msl(kind: WgpuDeviceKind) -> Result<Device, DeviceUnavailable>

The device kind names on Metal’s own API, reached through wgpu — and so MSL, where the build allows it.

Not the native Metal runtime, which is Device::metal and a different device altogether.

pub fn on(self, backend: WgpuBackend) -> Result<Device, DeviceUnavailable>

This device on backend, where the machine has it there.

For the caller holding a device already and wanting it on a particular API. Only the API named is asked: where the device came up by default says nothing about whether this one has it.

pub fn client(&self) -> Client

The compute client of this device, initialized on first use.

Panics

Where this build does not link the device’s runtime.

pub fn can_read_tensor(&self, shape: &Shape, strides: &Strides) -> bool

Whether a tensor with shape and strides can be read as it lies, or has to be made contiguous first. A property of the runtime, which is why it is asked of the device rather than of the client.

Panics

Where this build does not link the device’s runtime.

pub fn enumerate(device_id: DeviceId) -> Vec<DeviceId>

The ids of every device sharing device_id’s runtime and device type — and for a wgpu device, its graphics API, the same adapter on another being another device.

Takes and returns ids in Device’s own encoding, so a caller holding one id can ask what else is on that device’s runtime without unpacking the runtime itself. Whatever device_id spends the high byte on comes back on every id, untouched.

pub fn enumerate_all() -> Vec<Device>

Every device of every runtime this build links.

What a caller listing “the devices” wants, now that one type covers them all — a runtime with no hardware present contributes nothing.

pub fn runtime(&self) -> RuntimeId

The runtime this device belongs to.

pub fn utilization(&self) -> Result<DeviceUtilization, UtilizationUnavailable>

How busy this device is, by the counter its card’s driver or its platform keeps: NVML for an NVIDIA card, gpu_busy_percent for an AMD one and the idle residency of an Intel one on Linux, the GPU engine counters Task Manager reads on Windows, the accelerator’s statistics in the I/O Registry on macOS, and the processor times for the CPU.

The card decides which counter answers, not the runtime, so an NVIDIA card reads the same through CUDA as through wgpu. Asking creates the device’s client, and a card’s counter is opened the first time it is asked and kept for the life of the process.

The Intel, Windows and CPU counters measure the time between two readings. A reading covers the time since the card was last asked, by any caller, and the first is UtilizationUnavailable::NoPreviousReading.

use cubecl::Device;

match Device::default().utilization() {
    Ok(utilization) => println!("{}% busy", utilization.busy_percent),
    Err(reason) => println!("no reading: {reason}"),
}

pub fn from_id(device_id: DeviceId) -> Device

The device a DeviceId in this type’s encoding names.

Panics

Where device_id names no runtime at all. An id only travels between builds of the same application, so this is a build mismatch rather than input to validate.

pub fn to_id(&self) -> DeviceId

This device’s id, with its runtime stamped in the tag bits so ids from two runtimes cannot collide.

Trait Implementations

impl Clone for Device

fn clone(&self) -> Device

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Device

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Device

Available on any_runtime only.

The default device of the most capable runtime with hardware to run on.

Walks the runtimes this build links, most capable first, and takes the first that reports a device — so a binary that links both CUDA and wgpu lands on wgpu when it turns out there is no NVIDIA card, rather than naming a device it cannot reach.

The last runtime in that order is taken without asking. There is nothing left to fall back to, so its answer cannot change the outcome, and a build that links one runtime — the usual one — probes nothing at all. Where a probe does run, its result is kept for the life of the process: a device appearing or disappearing later goes unnoticed.

fn default() -> Device

Returns the “default value” for a type.

impl Device for Device

Available on any_runtime only.

What lets this stand in wherever a runtime’s own device type did: burn’s backends take a device through this trait, and are handed this one.

Only where a runtime is linked, since the trait asks for a default.

fn from_id(device_id: DeviceId) -> Device

Create a device from its id.

fn to_id(&self) -> DeviceId

Retrieve the device id from the device.

impl DeviceOps for Device

fn defaults(&self) -> DeviceSettings

Returns the default settings for this device.

fn id(&self) -> DeviceId

Returns the device id.

impl Eq for Device

impl From<AmdDevice> for Device

fn from(device: AmdDevice) -> Device

Converts to this type from the input type.

impl From<CpuDevice> for Device

fn from(device: CpuDevice) -> Device

Converts to this type from the input type.

impl From<CudaDevice> for Device

fn from(device: CudaDevice) -> Device

Converts to this type from the input type.

impl From<MetalDevice> for Device

fn from(device: MetalDevice) -> Device

Converts to this type from the input type.

impl From<WgpuDevice> for Device

fn from(device: WgpuDevice) -> Device

Converts to this type from the input type.

impl Hash for Device

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Device

fn eq(&self, other: &Device) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Device