ignis-numerics 0.0.1

data/lib/nvruby/solver/cusolver_bindings.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Ignis
+  module Solver
+    # cuSOLVER Dense (Dn) library FFI bindings
+    # Provides LU decomposition, SVD, and eigenvalue solvers
+    module CuSolverBindings
+      extend FFI::Library
+
+      # cuSOLVER status codes
+      CUSOLVER_STATUS_SUCCESS = 0
+      CUSOLVER_STATUS_NOT_INITIALIZED = 1
+      CUSOLVER_STATUS_ALLOC_FAILED = 2
+      CUSOLVER_STATUS_INVALID_VALUE = 3
+      CUSOLVER_STATUS_ARCH_MISMATCH = 4
+      CUSOLVER_STATUS_MAPPING_ERROR = 5
+      CUSOLVER_STATUS_EXECUTION_FAILED = 6
+      CUSOLVER_STATUS_INTERNAL_ERROR = 7
+      CUSOLVER_STATUS_MATRIX_TYPE_NOT_SUPPORTED = 8
+      CUSOLVER_STATUS_NOT_SUPPORTED = 9
+      CUSOLVER_STATUS_ZERO_PIVOT = 10
+      CUSOLVER_STATUS_INVALID_LICENSE = 11
+      CUSOLVER_STATUS_IRS_PARAMS_NOT_INITIALIZED = 12
+      CUSOLVER_STATUS_IRS_PARAMS_INVALID = 13
+      CUSOLVER_STATUS_IRS_PARAMS_INVALID_PREC = 14
+      CUSOLVER_STATUS_IRS_PARAMS_INVALID_REFINE = 15
+      CUSOLVER_STATUS_IRS_PARAMS_INVALID_MAXITER = 16
+      CUSOLVER_STATUS_IRS_INTERNAL_ERROR = 20
+      CUSOLVER_STATUS_IRS_NOT_SUPPORTED = 21
+      CUSOLVER_STATUS_IRS_OUT_OF_RANGE = 22
+      CUSOLVER_STATUS_IRS_NRHS_NOT_SUPPORTED_FOR_REFINE_GMRES = 23
+      CUSOLVER_STATUS_IRS_INFOS_NOT_INITIALIZED = 25
+
+      # cuSOLVER EigMode (for eigenvalue/eigenvector computation)
+      CUSOLVER_EIG_MODE_NOVECTOR = 0  # Compute eigenvalues only
+      CUSOLVER_EIG_MODE_VECTOR = 1    # Compute eigenvalues and eigenvectors
+
+      # cuSOLVER EigType (for generalized eigenvalue problem)
+      CUSOLVER_EIG_TYPE_1 = 1  # A*x = lambda*B*x
+      CUSOLVER_EIG_TYPE_2 = 2  # A*B*x = lambda*x
+      CUSOLVER_EIG_TYPE_3 = 3  # B*A*x = lambda*x
+
+      # cuSOLVER EigRange (eigenvalue range selection)
+      CUSOLVER_EIG_RANGE_ALL = 0  # All eigenvalues
+      CUSOLVER_EIG_RANGE_V = 1    # Eigenvalues in half-open interval (vl, vu]
+      CUSOLVER_EIG_RANGE_I = 2    # il-th through iu-th eigenvalues
+
+      # cuBLAS fill mode (used by cuSOLVER)
+      CUBLAS_FILL_MODE_LOWER = 0
+      CUBLAS_FILL_MODE_UPPER = 1
+      CUBLAS_FILL_MODE_FULL = 2
+
+      # cuBLAS operation types
+      CUBLAS_OP_N = 0  # No transpose
+      CUBLAS_OP_T = 1  # Transpose
+      CUBLAS_OP_C = 2  # Conjugate transpose
+
+      # Status code descriptions
+      STATUS_DESCRIPTIONS = {
+        CUSOLVER_STATUS_SUCCESS => "Success",
+        CUSOLVER_STATUS_NOT_INITIALIZED => "Library not initialized",
+        CUSOLVER_STATUS_ALLOC_FAILED => "Resource allocation failed",
+        CUSOLVER_STATUS_INVALID_VALUE => "Invalid parameter value",
+        CUSOLVER_STATUS_ARCH_MISMATCH => "Architecture mismatch",
+        CUSOLVER_STATUS_MAPPING_ERROR => "Mapping error",
+        CUSOLVER_STATUS_EXECUTION_FAILED => "Execution failed",
+        CUSOLVER_STATUS_INTERNAL_ERROR => "Internal error",
+        CUSOLVER_STATUS_MATRIX_TYPE_NOT_SUPPORTED => "Matrix type not supported",
+        CUSOLVER_STATUS_NOT_SUPPORTED => "Operation not supported",
+        CUSOLVER_STATUS_ZERO_PIVOT => "Zero pivot encountered",
+        CUSOLVER_STATUS_INVALID_LICENSE => "Invalid license"
+      }.freeze
+
+      @loaded = false
+      @handle = nil
+      @mutex = Mutex.new
+
+      class << self
+        # @return [FFI::Pointer, nil] cuSOLVER handle
+        attr_accessor :handle
+
+        # Check if cuSOLVER is loaded
+        # @return [Boolean]
+        def loaded?
+          @loaded
+        end
+
+        # Ensure cuSOLVER is loaded and initialized
+        # @return [void]
+        # @raise [CuSolverError] If initialization fails
+        def ensure_loaded!
+          @mutex.synchronize do
+            return if @loaded
+
+            CUDA::LibraryLoader.load_library(:cusolver)
+
+            cuda_bin = Ignis.configuration.cuda_bin_path
+            dll_path = if cuda_bin
+                         Dir.glob(File.join(cuda_bin, "cusolver64_*.dll")).max
+                       else
+                         "cusolver64_12"
+                       end
+
+            raise LibraryNotFoundError, "cusolver" unless dll_path
+
+            ffi_lib dll_path
+            attach_cusolver_functions!
+            initialize_cusolver!
+
+            @loaded = true
+            Ignis.logger.info("cuSOLVER initialized successfully")
+          end
+        end
+
+        # Get or create cuSOLVER handle
+        # @return [FFI::Pointer]
+        def get_handle
+          ensure_loaded!
+          @handle
+        end
+
+        # Set the CUDA stream for cuSOLVER operations
+        # @param stream [FFI::Pointer] CUDA stream
+        # @return [void]
+        def set_stream(stream)
+          ensure_loaded!
+          status = cusolverDnSetStream(@handle, stream)
+          check_status!(status, "cusolverDnSetStream")
+        end
+
+        # Finalize cuSOLVER and release resources
+        # @return [void]
+        def finalize!
+          @mutex.synchronize do
+            return unless @handle
+
+            cusolverDnDestroy(@handle)
+            @handle = nil
+            @loaded = false
+            Ignis.logger.info("cuSOLVER finalized")
+          end
+        end
+
+        # Check cuSOLVER status and raise error if not success
+        # @param status [Integer] cuSOLVER status code
+        # @param context [String] Context for error message
+        # @return [void]
+        # @raise [CuSolverError] If status indicates an error
+        def check_status!(status, context = "cuSOLVER operation")
+          return if status == CUSOLVER_STATUS_SUCCESS
+
+          description = STATUS_DESCRIPTIONS[status] || "Unknown error"
+          raise CuSolverError.new("#{context} failed: #{description}", cusolver_code: status)
+        end
+
+        private
+
+        # Attach all cuSOLVER FFI functions
+        # @return [void]
+        def attach_cusolver_functions!
+          # Handle management
+          attach_function :cusolverDnCreate, [:pointer], :int
+          attach_function :cusolverDnDestroy, [:pointer], :int
+          attach_function :cusolverDnSetStream, [:pointer, :pointer], :int
+          attach_function :cusolverDnGetStream, [:pointer, :pointer], :int
+
+          # LU factorization - buffer size queries
+          attach_function :cusolverDnSgetrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDgetrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCgetrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZgetrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+
+          # LU factorization
+          attach_function :cusolverDnSgetrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnDgetrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnCgetrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnZgetrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :pointer
+          ], :int
+
+          # LU solve (getrs)
+          attach_function :cusolverDnSgetrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDgetrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCgetrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZgetrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+
+          # SVD buffer size queries
+          attach_function :cusolverDnSgesvd_bufferSize, [
+            :pointer, :int, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDgesvd_bufferSize, [
+            :pointer, :int, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCgesvd_bufferSize, [
+            :pointer, :int, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZgesvd_bufferSize, [
+            :pointer, :int, :int, :pointer
+          ], :int
+
+          # SVD computation
+          attach_function :cusolverDnSgesvd, [
+            :pointer, :char, :char, :int, :int, :pointer, :int,
+            :pointer, :pointer, :int, :pointer, :int,
+            :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnDgesvd, [
+            :pointer, :char, :char, :int, :int, :pointer, :int,
+            :pointer, :pointer, :int, :pointer, :int,
+            :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnCgesvd, [
+            :pointer, :char, :char, :int, :int, :pointer, :int,
+            :pointer, :pointer, :int, :pointer, :int,
+            :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnZgesvd, [
+            :pointer, :char, :char, :int, :int, :pointer, :int,
+            :pointer, :pointer, :int, :pointer, :int,
+            :pointer, :int, :pointer, :pointer
+          ], :int
+
+          # Symmetric eigenvalue solver buffer size (syevd)
+          attach_function :cusolverDnSsyevd_bufferSize, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnDsyevd_bufferSize, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnCheevd_bufferSize, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer
+          ], :int
+          attach_function :cusolverDnZheevd_bufferSize, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer
+          ], :int
+
+          # Symmetric eigenvalue solver (syevd/heevd)
+          attach_function :cusolverDnSsyevd, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDsyevd, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCheevd, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZheevd, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+
+          # Cholesky factorization buffer size
+          attach_function :cusolverDnSpotrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDpotrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCpotrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZpotrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+
+          # Cholesky factorization
+          attach_function :cusolverDnSpotrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDpotrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCpotrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZpotrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+
+          # Cholesky solve
+          attach_function :cusolverDnSpotrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDpotrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCpotrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZpotrs, [
+            :pointer, :int, :int, :int, :pointer, :int, :pointer, :int, :pointer
+          ], :int
+
+          # QR factorization buffer size
+          attach_function :cusolverDnSgeqrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDgeqrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCgeqrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZgeqrf_bufferSize, [
+            :pointer, :int, :int, :pointer, :int, :pointer
+          ], :int
+
+          # QR factorization
+          attach_function :cusolverDnSgeqrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnDgeqrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnCgeqrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+          attach_function :cusolverDnZgeqrf, [
+            :pointer, :int, :int, :pointer, :int, :pointer, :pointer, :int, :pointer
+          ], :int
+        end
+
+        # Initialize cuSOLVER handle
+        # @return [void]
+        def initialize_cusolver!
+          handle_ptr = FFI::MemoryPointer.new(:pointer)
+          status = cusolverDnCreate(handle_ptr)
+          check_status!(status, "cusolverDnCreate")
+
+          @handle = handle_ptr.read_pointer
+        end
+      end
+    end
+  end
+end

data/lib/nvruby/solver/eigen.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "cusolver_bindings"
+
+module Ignis
+  module Solver
+    # Eigenvalue and Eigenvector computation using cuSOLVER
+    # Supports symmetric/Hermitian matrices (syevd/heevd) and general matrices (geev)
+    module Eigen
+      class << self
+        # Compute eigenvalues and eigenvectors of a symmetric/Hermitian matrix
+        # Uses divide-and-conquer algorithm (syevd/heevd)
+        # @param matrix [NvArray] Symmetric (real) or Hermitian (complex) matrix (n x n)
+        # @param eigenvectors [Boolean] If true, compute eigenvectors
+        # @param uplo [Symbol] :lower or :upper indicating which triangle contains the matrix
+        # @return [Hash] Contains :eigenvalues and optionally :eigenvectors
+        # @raise [CuSolverError] If computation fails
+        def eigh(matrix, eigenvectors: true, uplo: :lower)
+          CuSolverBindings.ensure_loaded!
+
+          validate_symmetric_matrix!(matrix)
+          n = matrix.shape[0]
+          lda = n
+
+          # Job mode
+          jobz = eigenvectors ? CuSolverBindings::CUSOLVER_EIG_MODE_VECTOR : CuSolverBindings::CUSOLVER_EIG_MODE_NOVECTOR
+          fill_mode = uplo == :lower ? CuSolverBindings::CUBLAS_FILL_MODE_LOWER : CuSolverBindings::CUBLAS_FILL_MODE_UPPER
+
+          # Allocate eigenvalues array (always real)
+          real_dtype = real_dtype_for(matrix.dtype)
+          eigenvalues = CUDA::Memory.new(n * dtype_size(real_dtype))
+
+          # Copy matrix to work array (will contain eigenvectors on output if requested)
+          work_matrix = matrix.dup
+
+          # Get workspace size
+          lwork_ptr = FFI::MemoryPointer.new(:int)
+          get_syevd_buffer_size(jobz, fill_mode, n, work_matrix.device_ptr, lda, eigenvalues, lwork_ptr, matrix.dtype)
+          lwork = lwork_ptr.read_int
+
+          # Allocate workspace and info
+          workspace = CUDA::Memory.new(lwork * dtype_size(matrix.dtype))
+          info = CUDA::Memory.new(4)
+
+          # Perform eigenvalue computation
+          perform_syevd(jobz, fill_mode, n, work_matrix.device_ptr, lda, eigenvalues, workspace, lwork, info, matrix.dtype)
+
+          # Check info
+          info_value = read_device_int(info)
+          if info_value < 0
+            raise CuSolverError.new("Eigenvalue computation: parameter #{-info_value} had an illegal value",
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_INVALID_VALUE)
+          elsif info_value > 0
+            raise CuSolverError.new("Eigenvalue computation: #{info_value} off-diagonal elements did not converge to zero",
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_EXECUTION_FAILED)
+          end
+
+          CUDA::RuntimeAPI.cudaDeviceSynchronize
+
+          result = {
+            eigenvalues: NvArray.from_device_ptr(eigenvalues, shape: [n], dtype: real_dtype, take_ownership: true)
+          }
+
+          if eigenvectors
+            result[:eigenvectors] = work_matrix
+          end
+
+          result
+        ensure
+          workspace&.free! if defined?(workspace) && workspace
+          info&.free! if defined?(info) && info
+        end
+
+        # Compute eigenvalues only of a symmetric/Hermitian matrix (faster)
+        # @param matrix [NvArray] Symmetric/Hermitian matrix
+        # @return [NvArray] Eigenvalues in ascending order
+        def eigvalsh(matrix)
+          result = eigh(matrix, eigenvectors: false)
+          result[:eigenvalues]
+        end
+
+        # Compute eigenvalues and eigenvectors of a general (non-symmetric) matrix
+        # Note: This is more expensive than eigh for symmetric matrices
+        # @param matrix [NvArray] General square matrix (n x n)
+        # @return [Hash] Contains :eigenvalues (may be complex), :eigenvectors_right
+        def eig(matrix)
+          CuSolverBindings.ensure_loaded!
+
+          validate_square_matrix!(matrix)
+          n = matrix.shape[0]
+
+          # For general matrices, eigenvalues may be complex
+          # Even for real input, we may get complex eigenvalues
+          # For now, we'll use Schur decomposition approximation
+
+          # Copy matrix
+          work_matrix = matrix.dup
+
+          # For real matrices, eigenvalues are returned as real/imaginary pairs
+          # For complex matrices, eigenvalues are complex directly
+
+          if complex_dtype?(matrix.dtype)
+            compute_complex_eig(work_matrix, n)
+          else
+            compute_real_eig(work_matrix, n)
+          end
+        end
+
+        # Check if a matrix is approximately symmetric
+        # @param matrix [NvArray] Matrix to check
+        # @param tol [Float] Tolerance for symmetry check
+        # @return [Boolean]
+        def symmetric?(matrix, tol: 1e-10)
+          return false unless matrix.shape[0] == matrix.shape[1]
+
+          # For a proper check, we'd compare A with A^T
+          # This is a simplified placeholder - full implementation would
+          # compute max(abs(A - A^T))
+          true # Placeholder - assumes caller knows matrix is symmetric
+        end
+
+        private
+
+        def validate_symmetric_matrix!(matrix)
+          raise ArgumentError, "Expected NvArray" unless matrix.is_a?(NvArray)
+          raise ArgumentError, "Matrix must be 2D" unless matrix.shape.length == 2
+          raise ArgumentError, "Matrix must be square" unless matrix.shape[0] == matrix.shape[1]
+          raise ArgumentError, "Matrix must be on device" unless matrix.on_device?
+        end
+
+        def validate_square_matrix!(matrix)
+          raise ArgumentError, "Expected NvArray" unless matrix.is_a?(NvArray)
+          raise ArgumentError, "Matrix must be 2D" unless matrix.shape.length == 2
+          raise ArgumentError, "Matrix must be square" unless matrix.shape[0] == matrix.shape[1]
+          raise ArgumentError, "Matrix must be on device" unless matrix.on_device?
+        end
+
+        def dtype_size(dtype)
+          case dtype
+          when :float32 then 4
+          when :float64 then 8
+          when :complex64 then 8
+          when :complex128 then 16
+          else 4
+          end
+        end
+
+        def real_dtype_for(dtype)
+          case dtype
+          when :complex64 then :float32
+          when :complex128 then :float64
+          else dtype
+          end
+        end
+
+        def complex_dtype?(dtype)
+          %i[complex64 complex128].include?(dtype)
+        end
+
+        def read_device_int(ptr)
+          host_ptr = FFI::MemoryPointer.new(:int)
+          CUDA::RuntimeAPI.cudaMemcpy(host_ptr, ptr, 4, CUDA::RuntimeAPI::MEMCPY_DEVICE_TO_HOST)
+          host_ptr.read_int
+        end
+
+        def get_syevd_buffer_size(jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr, dtype)
+          handle = CuSolverBindings.get_handle
+
+          status = case dtype
+                   when :float32
+                     CuSolverBindings.cusolverDnSsyevd_bufferSize(handle, jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr)
+                   when :float64
+                     CuSolverBindings.cusolverDnDsyevd_bufferSize(handle, jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr)
+                   when :complex64
+                     CuSolverBindings.cusolverDnCheevd_bufferSize(handle, jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr)
+                   when :complex128
+                     CuSolverBindings.cusolverDnZheevd_bufferSize(handle, jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr)
+                   else
+                     CuSolverBindings.cusolverDnSsyevd_bufferSize(handle, jobz, uplo, n, a_ptr, lda, w_ptr, lwork_ptr)
+                   end
+
+          CuSolverBindings.check_status!(status, "cusolverDnXsyevd_bufferSize")
+        end
+
+        def perform_syevd(jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info, dtype)
+          handle = CuSolverBindings.get_handle
+
+          status = case dtype
+                   when :float32
+                     CuSolverBindings.cusolverDnSsyevd(handle, jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info)
+                   when :float64
+                     CuSolverBindings.cusolverDnDsyevd(handle, jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info)
+                   when :complex64
+                     CuSolverBindings.cusolverDnCheevd(handle, jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info)
+                   when :complex128
+                     CuSolverBindings.cusolverDnZheevd(handle, jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info)
+                   else
+                     CuSolverBindings.cusolverDnSsyevd(handle, jobz, uplo, n, a_ptr, lda, w_ptr, work, lwork, info)
+                   end
+
+          CuSolverBindings.check_status!(status, "cusolverDnXsyevd")
+        end
+
+        # General (non-symmetric) real eigensolver.
+        #
+        # NOT IMPLEMENTED: cuSOLVER's general eigensolver (geev) is not bound. The
+        # previous code silently ran the SYMMETRIC solver (syevd) on the raw matrix
+        # and only logged a warning, returning the eigenpairs of (A+Aᵀ)/2 — wrong
+        # (and possibly real-only) results for any non-symmetric A. Fail loudly
+        # instead; use #eigh for genuinely symmetric/Hermitian matrices.
+        def compute_real_eig(_matrix, _n)
+          raise NotImplementedError,
+                "General (non-symmetric) eigenvalue solver is not implemented (geev not bound). " \
+                "Use eigh/eigvalsh for symmetric/Hermitian matrices."
+        end
+
+        # General complex eigensolver — not implemented (see compute_real_eig).
+        def compute_complex_eig(_matrix, _n)
+          raise NotImplementedError,
+                "General complex eigenvalue solver is not implemented (geev not bound). " \
+                "Use eigh for Hermitian matrices."
+        end
+      end
+    end
+  end
+end