qten.utils.devices

Module reference for qten.utils.devices.

devices

Logical device helpers used by QTen objects.

QTen exposes a small device vocabulary through Device: "cpu" for host execution and "gpu" for accelerated execution. The concrete backend is resolved by PyTorch when a device is used, currently mapping "gpu" to CUDA through Device.torch_device().

Repository usage

Use Device to store device intent in QTen data structures and implement DeviceBounded when an object can move or copy itself between logical devices.

Examples:

device = Device.new("gpu:0")
torch_device = device.torch_device()

obj_on_cpu = obj.cpu()
obj_on_gpu = obj.gpu(0)

Device dataclass

Device(
    name: Literal["cpu", "gpu"], index: Optional[int] = None
)

Lightweight immutable device descriptor used by QTen.

The public device model is intentionally small: - "cpu" represents host execution. - "gpu" represents accelerated execution.

For GPU devices, index optionally stores a CUDA device index. This index is only meaningful on CUDA-capable systems.

Parameters:

Name	Type	Description	Default
name	Literal['cpu', 'gpu']	The logical device family.	required
index	Optional[int]	Optional CUDA device index. This should only be set when name is "gpu".	`None`

Attributes:

Name	Type	Description
name	Literal['cpu', 'gpu']	Logical device family.
index	Optional[int]	Optional CUDA device index for GPU execution.

name instance-attribute

name: Literal['cpu', 'gpu']

Logical device family. QTen uses "cpu" for host execution and "gpu" for CUDA-backed execution.

index class-attribute instance-attribute

index: Optional[int] = None

Optional CUDA device index for GPU execution. This is meaningful only when name == "gpu".

__repr__ class-attribute instance-attribute

__repr__ = __str__

new staticmethod

new(name: str) -> Device

Parse a user-facing device string into a Device.

Supported inputs

• "cpu"
• "gpu"
• "gpu:<index>", where <index> is a non-negative integer

Parameters:

Name	Type	Description	Default
name	str	Device string to parse.	required

Returns:

Type	Description
Device	Parsed immutable device descriptor.

Raises:

Type	Description
ValueError	If the input does not match one of the supported formats.

Examples:

Device.new("cpu")
Device.new("gpu:0")

Source code in src/qten/utils/devices.py

@staticmethod
def new(name: str) -> "Device":
    """
    Parse a user-facing device string into a [`Device`][qten.utils.devices.Device].

    Supported inputs
    ----------------
    - `"cpu"`
    - `"gpu"`
    - `"gpu:<index>"`, where ``<index>`` is a non-negative integer

    Parameters
    ----------
    name : str
        Device string to parse.

    Returns
    -------
    Device
        Parsed immutable device descriptor.

    Raises
    ------
    ValueError
        If the input does not match one of the supported formats.

    Examples
    --------
    ```python
    Device.new("cpu")
    Device.new("gpu:0")
    ```
    """
    if name == "cpu":
        return Device(name="cpu")
    if name.startswith("gpu"):
        parts = name.split(":")
        if len(parts) == 1:
            return Device(name="gpu")
        elif len(parts) == 2 and parts[1].isdigit():
            return Device(name="gpu", index=int(parts[1]))
    raise ValueError(f"Invalid device name: {name}")

torch_device

torch_device() -> torch.device

Resolve this logical device into the concrete PyTorch backend device.

Resolution is runtime-dependent: - "cpu" always maps to torch.device("cpu"). - "gpu" prefers CUDA when available.

When CUDA is selected, an explicit index is used if present. Otherwise, the current CUDA device reported by PyTorch is used.

Returns:

Type	Description
device	Concrete PyTorch device corresponding to this logical device.

Raises:

Type	Description
ValueError	If self.name is not a supported logical device value.
RuntimeError	If a GPU device is requested but neither CUDA nor MPS is available in the current environment.

Source code in src/qten/utils/devices.py

def torch_device(self) -> torch.device:
    """
    Resolve this logical device into the concrete PyTorch backend device.

    Resolution is runtime-dependent:
    - `"cpu"` always maps to ``torch.device("cpu")``.
    - `"gpu"` prefers CUDA when available.

    When CUDA is selected, an explicit ``index`` is used if present.
    Otherwise, the current CUDA device reported by PyTorch is used.

    Returns
    -------
    torch.device
        Concrete PyTorch device corresponding to this logical device.

    Raises
    ------
    ValueError
        If ``self.name`` is not a supported logical device value.
    RuntimeError
        If a GPU device is requested but neither CUDA nor MPS is available
        in the current environment.
    """
    if self.name == "cpu":
        return torch.device("cpu")
    if not self.name == "gpu":
        raise ValueError(f"Invalid device name: {self.name}")
    if torch.cuda.is_available():
        index = (
            self.index if self.index is not None else torch.cuda.current_device()
        )
        return torch.device("cuda", index)
    raise RuntimeError("The current system does not have GPU devices!")

__str__

__str__() -> str

Format the device using QTen's logical device syntax.

Returns:

Type	Description
str	"cpu", "gpu", or "gpu:<index>".

Raises:

Type	Description
ValueError	If self.name is not a supported logical device value.

Source code in src/qten/utils/devices.py

def __str__(self) -> str:
    """
    Format the device using QTen's logical device syntax.

    Returns
    -------
    str
        "cpu", `"gpu"`, or `"gpu:<index>"`.

    Raises
    ------
    ValueError
        If ``self.name`` is not a supported logical device value.
    """
    match self.name:
        case "cpu":
            return "cpu"
        case "gpu":
            if self.index is not None:
                return f"gpu:{self.index}"
            return "gpu"
        case _:
            raise ValueError(f"Invalid device name: {self.name}")

DeviceBounded

Bases: ABC

Mixin for objects that can be copied or moved between logical devices.

Concrete subclasses implement to_device and expose their current device. Convenience helpers cpu and gpu are defined in terms of that abstract interface.

device abstractmethod property

device: Device

Return the current device this object resides on.

Returns:

Type	Description
Device	The current device of this object.

cpu

cpu() -> Self

Return a copy of this object residing on the CPU device.

Returns:

Type	Description
Self	A copy of this object on the logical CPU device.

Source code in src/qten/utils/devices.py

def cpu(self) -> Self:
    """
    Return a copy of this object residing on the CPU device.

    Returns
    -------
    Self
        A copy of this object on the logical CPU device.
    """
    return self.to_device(Device("cpu"))

gpu

gpu(index: Optional[int] = None) -> Self

Return a copy of this object residing on a GPU device.

Parameters:

Name	Type	Description	Default
index	Optional[int]	Optional CUDA device index. This should only be set when the target GPU backend supports multiple devices (e.g. CUDA). If not provided, the current device will be used.	`None`

Returns:

Type	Description
Self	A copy of this object on the specified GPU device.

Source code in src/qten/utils/devices.py

def gpu(self, index: Optional[int] = None) -> Self:
    """
    Return a copy of this object residing on a GPU device.

    Parameters
    ----------
    index : Optional[int], default=`None`
        Optional CUDA device index. This should only be set when the target
        GPU backend supports multiple devices (e.g. CUDA). If not provided,
        the current device will be used.

    Returns
    -------
    Self
        A copy of this object on the specified GPU device.
    """
    device = Device("gpu", index)
    return self.to_device(device)

to_device abstractmethod

to_device(device: Device) -> Self

Return a copy of this object residing on the specified device.

Parameters:

Name	Type	Description	Default
device	Device	The target device to move this object to.	required

Returns:

Type	Description
Self	A copy of this object on the specified device.

Source code in src/qten/utils/devices.py

@abstractmethod
def to_device(self, device: Device) -> Self:
    """
    Return a copy of this object residing on the specified device.

    Parameters
    ----------
    device : Device
        The target device to move this object to.

    Returns
    -------
    Self
        A copy of this object on the specified device.
    """
    pass