Skip to main content

Troubleshooting

CUDA Library Load Failures

If a CUDA run fails while loading cuTENSOR, cuSOLVER, or cuBLAS, first check that the CUDA runtime libraries are on the dynamic-linker path:

CUDA_PATH=/usr/local/cuda-12.4
LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH

Choose a matched driver, runtime, NVRTC, and vendor-library stack from the CUDA and NVIDIA library compatibility matrix. The matrix distinguishes tenferro’s minimum, loader ABI candidates, and the versions exercised by CI.

For non-standard installs, set the exact library paths:

TENFERRO_CUTENSOR_PATH=/opt/cuda/lib64/libcutensor.so.2
TENFERRO_CUSOLVER_PATH=/opt/cuda/lib64/libcusolver.so.12
TENFERRO_CUBLAS_PATH=/opt/cuda/lib64/libcublas.so.12
TENFERRO_CUFFT_PATH=/opt/cuda/lib64/libcufft.so.11

Unsupported PTX Version

CUDA_ERROR_UNSUPPORTED_PTX_VERSION usually means the loaded NVRTC is newer than the host driver API. Check both versions with nvidia-smi and the NVRTC library selected by LD_LIBRARY_PATH. On a driver reporting CUDA 12.4, load NVRTC 12.4; on a driver reporting CUDA 12.8 or newer, load NVRTC 12.8 to retain the full CUDA feature set.

Expected GPU Tensor

An error like expected GPU tensor ... use upload_tensor() means a CUDA backend operation received CPU data. Upload first:

use tenferro_gpu::cuda::{cuda_devices, gpu_available, upload_tensor, CudaEngine};
use tenferro_tensor::Tensor;

if !gpu_available() {
    return Ok(());
}
let devices = cuda_devices()?;
let device = devices.first().ok_or("no CUDA device is visible")?;
let engine = CudaEngine::open(device.id())?;
let x = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?;
let gpu_x = upload_tensor(engine.runtime(), &x)?;
assert_eq!(gpu_x.shape(), &[2]);

Host Access to GPU Tensors

Host access methods read CPU memory. If a tensor lives on CUDA memory, download it before inspecting values:

use tenferro_gpu::cuda::{cuda_devices, download_tensor, gpu_available, upload_tensor, CudaEngine};
use tenferro_tensor::Tensor;

if !gpu_available() {
    return Ok(());
}
let devices = cuda_devices()?;
let device = devices.first().ok_or("no CUDA device is visible")?;
let engine = CudaEngine::open(device.id())?;
let x = Tensor::from_vec_col_major(vec![1], vec![3.0_f64])?;
let gpu_x = upload_tensor(engine.runtime(), &x)?;
let cpu_x = download_tensor(engine.runtime(), &gpu_x)?;
assert_eq!(cpu_x.as_slice::<f64>()?, &[3.0]);

Compacting a view does not change that transfer rule. Host views compact to host tensors; CUDA views compact on CUDA when the backend supports that path. Neither path silently moves tensor data between CPU and GPU.

Dtype Mismatch

Typed accessors must match the tensor dtype. If as_slice::<f64>() fails, check whether the tensor was created from f32, complex values, or another supported scalar type.

view is not slice-contiguous

A view cannot be exposed as a borrowed slice unless its layout is contiguous. Materialize a compact owner with the session’s to_contiguous_read before requesting the slice:

use tenferro_cpu::CpuEngine;
use tenferro_tensor::{TensorStructural, TypedTensor};

let source = TypedTensor::<f64>::from_vec_col_major(
    vec![2, 3],
    vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
let transposed = source.as_view().transpose_view([1, 0])?;
let error = transposed.as_slice().unwrap_err();
assert!(error
    .to_string()
    .contains("view is not slice-contiguous"));

let mut engine = CpuEngine::serial();
let read = transposed.into_tensor_read()?;
let compact = engine.to_contiguous_read(read)?;
assert_eq!(compact.as_slice::<f64>()?, &[1.0, 3.0, 5.0, 2.0, 4.0, 6.0]);

mutable tensor layout may overlap physical elements

Mutable views must not alias one physical element from multiple logical positions. Materialize or construct a contiguous owner before requesting mutable access:

use tenferro_tensor::{TypedTensor, TypedTensorViewMut};

let mut data = [1.0_f64, 2.0];
let error = TypedTensorViewMut::from_slice(vec![2], vec![0], 0, &mut data).unwrap_err();
assert!(error
    .to_string()
    .contains("mutable tensor layout may overlap physical elements"));

let mut owner = TypedTensor::<f64>::from_vec_col_major(vec![2], vec![1.0, 2.0])?;
{
    let mut view = owner.as_view_mut();
    *view.get_mut(&[0]).ok_or("index in contiguous owner")? = 3.0;
}
assert_eq!(owner.as_slice()?, &[3.0, 2.0]);

Column-Major and Row-Major Confusion

Tensor::from_vec_col_major expects tenferro’s physical column-major order. When porting PyTorch, NumPy, or JAX examples that use row-major flat data, explicitly reorder the buffer at the import boundary. Export with into_vec_col_major::<T>(); consumers that require another order should convert outside tenferro. See Memory Order.

CPU Backend Selection

There is nothing to select. The CPU stack links exactly one faer build, so every CpuEngine in the process uses faer and no system BLAS/LAPACK library is required. A dependency list that still carries native, blas, blas-openblas, blas-accelerate, blas-mkl, or provider-inject fails with “feature does not exist” after the vendor providers were dropped: remove the feature and the default-features = false that went with it.

External CPU providers may replace only a provider bundle slot, such as dot_general; they do not replace the CPU linalg path. See Parallelism and Caching for thread-count and cache-retention controls.