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_PATHChoose 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.11Unsupported 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.