ignis-numerics 0.0.1

data/lib/nvruby/solver/svd.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require_relative "cusolver_bindings"
+
+module Ignis
+  module Solver
+    # Singular Value Decomposition (SVD) operations using cuSOLVER
+    # Computes A = U * Σ * V^T decomposition
+    module SVD
+      # Job types for SVD computation
+      JOB_ALL = "A".ord      # Compute all m columns of U / all n rows of V^T
+      JOB_SLIM = "S".ord     # Compute min(m,n) columns of U / rows of V^T
+      JOB_OVERWRITE = "O".ord # Overwrite A with U or V^T
+      JOB_NONE = "N".ord     # Do not compute U or V^T
+
+      class << self
+        # Compute SVD of a matrix
+        # @param matrix [NvArray] Input matrix (m x n)
+        # @param full_matrices [Boolean] If true, compute full U (m x m) and Vt (n x n)
+        # @param compute_uv [Boolean] If true, compute U and Vt matrices
+        # @return [Hash] Contains :u, :s (singular values), :vt
+        # @raise [CuSolverError] If computation fails
+        def gesvd(matrix, full_matrices: false, compute_uv: true)
+          CuSolverBindings.ensure_loaded!
+
+          validate_matrix!(matrix)
+          m, n = matrix.shape
+          lda = m
+          min_mn = [m, n].min
+
+          # Determine job type
+          if compute_uv
+            jobu = full_matrices ? JOB_ALL : JOB_SLIM
+            jobvt = full_matrices ? JOB_ALL : JOB_SLIM
+          else
+            jobu = JOB_NONE
+            jobvt = JOB_NONE
+          end
+
+          # Allocate output arrays
+          s = allocate_singular_values(min_mn, matrix.dtype)
+          u = allocate_u_matrix(m, min_mn, full_matrices, compute_uv, matrix.dtype)
+          vt = allocate_vt_matrix(n, min_mn, full_matrices, compute_uv, matrix.dtype)
+
+          # Dimensions
+          ldu = compute_uv ? (full_matrices ? m : m) : 1
+          ldvt = compute_uv ? (full_matrices ? n : min_mn) : 1
+
+          # Get workspace size
+          lwork_ptr = FFI::MemoryPointer.new(:int)
+          get_gesvd_buffer_size(m, n, lwork_ptr, matrix.dtype)
+          lwork = lwork_ptr.read_int
+
+          # Allocate workspace
+          workspace = CUDA::Memory.new(lwork * dtype_size(matrix.dtype))
+          rwork = CUDA::Memory.new(min_mn * dtype_size(real_dtype(matrix.dtype)))
+          info = CUDA::Memory.new(4)
+
+          # Copy matrix to avoid overwriting original
+          work_matrix = matrix.dup
+
+          # Perform SVD
+          perform_gesvd(
+            jobu, jobvt, m, n,
+            work_matrix.device_ptr, lda,
+            s, u, ldu, vt, ldvt,
+            workspace, lwork, rwork, info,
+            matrix.dtype
+          )
+
+          # Check info
+          info_value = read_device_int(info)
+          if info_value < 0
+            raise CuSolverError.new("SVD: parameter #{-info_value} had an illegal value",
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_INVALID_VALUE)
+          elsif info_value > 0
+            raise CuSolverError.new("SVD: #{info_value} superdiagonals did not converge",
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_EXECUTION_FAILED)
+          end
+
+          CUDA::RuntimeAPI.cudaDeviceSynchronize
+
+          # Create result arrays
+          result = {
+            s: create_singular_values_array(s, min_mn, matrix.dtype)
+          }
+
+          if compute_uv
+            result[:u] = create_u_array(u, m, min_mn, full_matrices, matrix.dtype)
+            result[:vt] = create_vt_array(vt, n, min_mn, full_matrices, matrix.dtype)
+          end
+
+          result
+        ensure
+          workspace&.free! if defined?(workspace) && workspace
+          rwork&.free! if defined?(rwork) && rwork
+          info&.free! if defined?(info) && info
+        end
+
+        # Compute only singular values (faster than full SVD)
+        # @param matrix [NvArray] Input matrix (m x n)
+        # @return [NvArray] Singular values in descending order
+        def singular_values(matrix)
+          result = gesvd(matrix, compute_uv: false)
+          result[:s]
+        end
+
+        # Compute matrix rank using SVD
+        # @param matrix [NvArray] Input matrix
+        # @param tol [Float, nil] Tolerance (defaults to max(m,n) * eps * largest_singular_value)
+        # @return [Integer] Numerical rank
+        def rank(matrix, tol: nil)
+          s = singular_values(matrix)
+          s_host = s.to_a
+
+          return 0 if s_host.empty?
+
+          max_sv = s_host.first
+          tol ||= [matrix.shape[0], matrix.shape[1]].max * Float::EPSILON * max_sv
+
+          s_host.count { |sv| sv > tol }
+        end
+
+        # Compute condition number using SVD
+        # @param matrix [NvArray] Input matrix
+        # @return [Float] Condition number (ratio of largest to smallest singular value)
+        def cond(matrix)
+          s = singular_values(matrix)
+          s_host = s.to_a
+
+          return Float::INFINITY if s_host.empty? || s_host.last.zero?
+
+          s_host.first / s_host.last
+        end
+
+        private
+
+        def validate_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 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(dtype)
+          case dtype
+          when :complex64 then :float32
+          when :complex128 then :float64
+          else dtype
+          end
+        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 allocate_singular_values(count, dtype)
+          size = count * dtype_size(real_dtype(dtype))
+          CUDA::Memory.new(size)
+        end
+
+        def allocate_u_matrix(m, min_mn, full_matrices, compute_uv, dtype)
+          return nil unless compute_uv
+
+          cols = full_matrices ? m : min_mn
+          size = m * cols * dtype_size(dtype)
+          CUDA::Memory.new(size)
+        end
+
+        def allocate_vt_matrix(n, min_mn, full_matrices, compute_uv, dtype)
+          return nil unless compute_uv
+
+          rows = full_matrices ? n : min_mn
+          size = rows * n * dtype_size(dtype)
+          CUDA::Memory.new(size)
+        end
+
+        def create_singular_values_array(ptr, count, dtype)
+          real = real_dtype(dtype)
+          NvArray.from_device_ptr(ptr, shape: [count], dtype: real, take_ownership: true)
+        end
+
+        def create_u_array(ptr, m, min_mn, full_matrices, dtype)
+          cols = full_matrices ? m : min_mn
+          NvArray.from_device_ptr(ptr, shape: [m, cols], dtype: dtype, take_ownership: true)
+        end
+
+        def create_vt_array(ptr, n, min_mn, full_matrices, dtype)
+          rows = full_matrices ? n : min_mn
+          NvArray.from_device_ptr(ptr, shape: [rows, n], dtype: dtype, take_ownership: true)
+        end
+
+        def get_gesvd_buffer_size(m, n, lwork_ptr, dtype)
+          handle = CuSolverBindings.get_handle
+
+          status = case dtype
+                   when :float32
+                     CuSolverBindings.cusolverDnSgesvd_bufferSize(handle, m, n, lwork_ptr)
+                   when :float64
+                     CuSolverBindings.cusolverDnDgesvd_bufferSize(handle, m, n, lwork_ptr)
+                   when :complex64
+                     CuSolverBindings.cusolverDnCgesvd_bufferSize(handle, m, n, lwork_ptr)
+                   when :complex128
+                     CuSolverBindings.cusolverDnZgesvd_bufferSize(handle, m, n, lwork_ptr)
+                   else
+                     CuSolverBindings.cusolverDnSgesvd_bufferSize(handle, m, n, lwork_ptr)
+                   end
+
+          CuSolverBindings.check_status!(status, "cusolverDnXgesvd_bufferSize")
+        end
+
+        def perform_gesvd(jobu, jobvt, m, n, a, lda, s, u, ldu, vt, ldvt, work, lwork, rwork, info, dtype)
+          handle = CuSolverBindings.get_handle
+          u_ptr = u || FFI::Pointer::NULL
+          vt_ptr = vt || FFI::Pointer::NULL
+
+          status = case dtype
+                   when :float32
+                     CuSolverBindings.cusolverDnSgesvd(
+                       handle, jobu, jobvt, m, n, a, lda,
+                       s, u_ptr, ldu, vt_ptr, ldvt,
+                       work, lwork, rwork, info
+                     )
+                   when :float64
+                     CuSolverBindings.cusolverDnDgesvd(
+                       handle, jobu, jobvt, m, n, a, lda,
+                       s, u_ptr, ldu, vt_ptr, ldvt,
+                       work, lwork, rwork, info
+                     )
+                   when :complex64
+                     CuSolverBindings.cusolverDnCgesvd(
+                       handle, jobu, jobvt, m, n, a, lda,
+                       s, u_ptr, ldu, vt_ptr, ldvt,
+                       work, lwork, rwork, info
+                     )
+                   when :complex128
+                     CuSolverBindings.cusolverDnZgesvd(
+                       handle, jobu, jobvt, m, n, a, lda,
+                       s, u_ptr, ldu, vt_ptr, ldvt,
+                       work, lwork, rwork, info
+                     )
+                   else
+                     CuSolverBindings.cusolverDnSgesvd(
+                       handle, jobu, jobvt, m, n, a, lda,
+                       s, u_ptr, ldu, vt_ptr, ldvt,
+                       work, lwork, rwork, info
+                     )
+                   end
+
+          CuSolverBindings.check_status!(status, "cusolverDnXgesvd")
+        end
+      end
+    end
+  end
+end

data/lib/nvruby/solver.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Ignis Solver Module
+# Provides GPU-accelerated linear algebra solvers using cuSOLVER
+
+require_relative "solver/cusolver_bindings"
+require_relative "solver/lu"
+require_relative "solver/svd"
+require_relative "solver/eigen"
+require_relative "solver/sparse_solver"
+
+module Ignis
+  module Solver
+    class << self
+      # Solve linear system Ax = b
+      # @param a [NvArray] Coefficient matrix (n x n)
+      # @param b [NvArray] Right-hand side (n x nrhs)
+      # @return [NvArray] Solution x
+      def solve(a, b)
+        LU.solve(a, b)
+      end
+
+      # LU decomposition with partial pivoting
+      # @param matrix [NvArray] Input matrix (m x n)
+      # @return [Hash] { lu:, pivot:, info: }
+      def lu(matrix)
+        LU.getrf(matrix)
+      end
+
+      # Singular Value Decomposition
+      # @param matrix [NvArray] Input matrix (m x n)
+      # @param full_matrices [Boolean] Compute full U, V matrices
+      # @return [Hash] { u:, s:, vt: }
+      def svd(matrix, full_matrices: false)
+        SVD.gesvd(matrix, full_matrices: full_matrices)
+      end
+
+      # Compute singular values only
+      # @param matrix [NvArray] Input matrix
+      # @return [NvArray] Singular values
+      def svdvals(matrix)
+        SVD.singular_values(matrix)
+      end
+
+      # Eigenvalue decomposition of symmetric/Hermitian matrix
+      # @param matrix [NvArray] Symmetric/Hermitian matrix
+      # @param eigenvectors [Boolean] Compute eigenvectors
+      # @return [Hash] { eigenvalues:, eigenvectors: }
+      def eigh(matrix, eigenvectors: true)
+        Eigen.eigh(matrix, eigenvectors: eigenvectors)
+      end
+
+      # Eigenvalues of symmetric/Hermitian matrix
+      # @param matrix [NvArray] Symmetric/Hermitian matrix
+      # @return [NvArray] Eigenvalues
+      def eigvalsh(matrix)
+        Eigen.eigvalsh(matrix)
+      end
+
+      # Eigenvalue decomposition of general matrix
+      # @param matrix [NvArray] General square matrix
+      # @return [Hash] { eigenvalues:, eigenvectors: }
+      def eig(matrix)
+        Eigen.eig(matrix)
+      end
+
+      # Matrix rank via SVD
+      # @param matrix [NvArray] Input matrix
+      # @param tol [Float, nil] Tolerance
+      # @return [Integer] Numerical rank
+      def matrix_rank(matrix, tol: nil)
+        SVD.rank(matrix, tol: tol)
+      end
+
+      # Condition number via SVD
+      # @param matrix [NvArray] Input matrix
+      # @return [Float] Condition number
+      def cond(matrix)
+        SVD.cond(matrix)
+      end
+
+      # Create an LU solver for repeated solves
+      # @param matrix [NvArray] Coefficient matrix
+      # @return [LUSolver]
+      def lu_solver(matrix)
+        LUSolver.new(matrix)
+      end
+
+      # Solve sparse linear system Ax = b using cuDSS
+      # @param sparse_matrix [Sparse::SparseMatrix] Sparse coefficient matrix in CSR format
+      # @param b [NvArray] Right-hand side vector/matrix
+      # @param matrix_type [Symbol] Type of matrix (:general, :symmetric, :spd)
+      # @return [NvArray] Solution x
+      def sparse_solve(sparse_matrix, b, matrix_type: :general)
+        SparseSolver.solve(sparse_matrix, b, matrix_type: matrix_type)
+      end
+
+      # Create a sparse solver for repeated solves with same sparsity pattern
+      # @param sparse_matrix [Sparse::SparseMatrix] Sparse coefficient matrix
+      # @param matrix_type [Symbol] Type of matrix (:general, :symmetric, :spd)
+      # @return [SparseSolver]
+      def sparse_solver(sparse_matrix, matrix_type: :general)
+        SparseSolver.new(sparse_matrix, matrix_type: matrix_type)
+      end
+
+      # Check if cuSOLVER is available
+      # @return [Boolean]
+      def available?
+        CuSolverBindings.ensure_loaded!
+        true
+      rescue StandardError
+        false
+      end
+
+      # Finalize cuSOLVER (release resources)
+      # @return [void]
+      def finalize!
+        CuSolverBindings.finalize!
+      end
+    end
+  end
+end

data/lib/nvruby/sparse/cusparse_bindings.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Ignis
+  module Sparse
+    # cuSPARSE library FFI bindings
+    module CuSPARSEBindings
+      extend FFI::Library
+
+      # Sparse matrix formats
+      CUSPARSE_INDEX_BASE_ZERO = 0
+      CUSPARSE_INDEX_BASE_ONE = 1
+
+      # Matrix types
+      CUSPARSE_MATRIX_TYPE_GENERAL = 0
+      CUSPARSE_MATRIX_TYPE_SYMMETRIC = 1
+      CUSPARSE_MATRIX_TYPE_HERMITIAN = 2
+      CUSPARSE_MATRIX_TYPE_TRIANGULAR = 3
+
+      # Fill modes
+      CUSPARSE_FILL_MODE_LOWER = 0
+      CUSPARSE_FILL_MODE_UPPER = 1
+
+      # Diagonal types
+      CUSPARSE_DIAG_TYPE_NON_UNIT = 0
+      CUSPARSE_DIAG_TYPE_UNIT = 1
+
+      # Index types
+      CUSPARSE_INDEX_16U = 1
+      CUSPARSE_INDEX_32I = 2
+      CUSPARSE_INDEX_64I = 3
+
+      # Sparse matrix-vector operation types
+      CUSPARSE_OPERATION_NON_TRANSPOSE = 0
+      CUSPARSE_OPERATION_TRANSPOSE = 1
+      CUSPARSE_OPERATION_CONJUGATE_TRANSPOSE = 2
+
+      # SpMV algorithms
+      CUSPARSE_SPMV_ALG_DEFAULT = 0
+      CUSPARSE_SPMV_CSR_ALG1 = 1
+      CUSPARSE_SPMV_CSR_ALG2 = 2
+      CUSPARSE_SPMV_COO_ALG1 = 3
+      CUSPARSE_SPMV_COO_ALG2 = 4
+
+      # SpMM algorithms
+      CUSPARSE_SPMM_ALG_DEFAULT = 0
+      CUSPARSE_SPMM_CSR_ALG1 = 1
+      CUSPARSE_SPMM_CSR_ALG2 = 2
+      CUSPARSE_SPMM_CSR_ALG3 = 3
+      CUSPARSE_SPMM_COO_ALG1 = 4
+      CUSPARSE_SPMM_COO_ALG2 = 5
+      CUSPARSE_SPMM_COO_ALG3 = 6
+      CUSPARSE_SPMM_COO_ALG4 = 7
+      CUSPARSE_SPMM_BLOCKED_ELL_ALG1 = 8
+
+      @loaded = false
+      @handle = nil
+
+      class << self
+        # @return [FFI::Pointer, nil] cuSPARSE handle
+        attr_accessor :handle
+
+        # Ensure cuSPARSE is loaded
+        # @return [void]
+        def ensure_loaded!
+          return if @loaded
+
+          CUDA::LibraryLoader.load_library(:cusparse)
+
+          cuda_bin = Ignis.configuration.cuda_bin_path
+          if cuda_bin
+            ffi_lib Dir.glob(File.join(cuda_bin, "cusparse64_*.dll")).max
+          else
+            ffi_lib "cusparse64_12"
+          end
+
+          attach_cusparse_functions!
+          initialize_cusparse!
+
+          @loaded = true
+        end
+
+        # Get or create cuSPARSE handle
+        # @return [FFI::Pointer]
+        def get_handle
+          ensure_loaded!
+          @handle
+        end
+
+        # Finalize cuSPARSE
+        # @return [void]
+        def finalize!
+          return unless @handle
+
+          cusparseDestroy(@handle)
+          @handle = nil
+          @loaded = false
+        end
+
+        private
+
+        # rubocop:disable Metrics/MethodLength
+        def attach_cusparse_functions!
+          # Handle management
+          attach_function :cusparseCreate, [:pointer], :int
+          attach_function :cusparseDestroy, [:pointer], :int
+          attach_function :cusparseSetStream, [:pointer, :pointer], :int
+          attach_function :cusparseGetStream, [:pointer, :pointer], :int
+
+          # Matrix descriptor (legacy API)
+          attach_function :cusparseCreateMatDescr, [:pointer], :int
+          attach_function :cusparseDestroyMatDescr, [:pointer], :int
+          attach_function :cusparseSetMatType, [:pointer, :int], :int
+          attach_function :cusparseGetMatType, [:pointer], :int
+          attach_function :cusparseSetMatFillMode, [:pointer, :int], :int
+          attach_function :cusparseGetMatFillMode, [:pointer], :int
+          attach_function :cusparseSetMatDiagType, [:pointer, :int], :int
+          attach_function :cusparseGetMatDiagType, [:pointer], :int
+          attach_function :cusparseSetMatIndexBase, [:pointer, :int], :int
+          attach_function :cusparseGetMatIndexBase, [:pointer], :int
+
+          # Generic API - Sparse Matrix Descriptors
+          attach_function :cusparseCreateCsr, [
+            :pointer,      # spMatDescr
+            :int64,        # rows
+            :int64,        # cols
+            :int64,        # nnz
+            :pointer,      # csrRowOffsets
+            :pointer,      # csrColInd
+            :pointer,      # csrValues
+            :int,          # csrRowOffsetsType
+            :int,          # csrColIndType
+            :int,          # idxBase
+            :int           # valueType
+          ], :int
+
+          attach_function :cusparseCreateCoo, [
+            :pointer,      # spMatDescr
+            :int64,        # rows
+            :int64,        # cols
+            :int64,        # nnz
+            :pointer,      # cooRowInd
+            :pointer,      # cooColInd
+            :pointer,      # cooValues
+            :int,          # cooIdxType
+            :int,          # idxBase
+            :int           # valueType
+          ], :int
+
+          attach_function :cusparseDestroySpMat, [:pointer], :int
+
+          # Dense Vector/Matrix Descriptors
+          attach_function :cusparseCreateDnVec, [:pointer, :int64, :pointer, :int], :int
+          attach_function :cusparseDestroyDnVec, [:pointer], :int
+          attach_function :cusparseCreateDnMat, [
+            :pointer, :int64, :int64, :int64, :pointer, :int, :int
+          ], :int
+          attach_function :cusparseDestroyDnMat, [:pointer], :int
+
+          # SpMV - Sparse Matrix-Vector Multiplication
+          attach_function :cusparseSpMV, [
+            :pointer,      # handle
+            :int,          # opA
+            :pointer,      # alpha
+            :pointer,      # matA
+            :pointer,      # vecX
+            :pointer,      # beta
+            :pointer,      # vecY
+            :int,          # computeType
+            :int,          # alg
+            :pointer       # externalBuffer
+          ], :int
+
+          attach_function :cusparseSpMV_bufferSize, [
+            :pointer, :int, :pointer, :pointer, :pointer, :pointer, :pointer, :int, :int, :pointer
+          ], :int
+
+          # SpMM - Sparse Matrix-Matrix Multiplication
+          attach_function :cusparseSpMM, [
+            :pointer,      # handle
+            :int,          # opA
+            :int,          # opB
+            :pointer,      # alpha
+            :pointer,      # matA
+            :pointer,      # matB
+            :pointer,      # beta
+            :pointer,      # matC
+            :int,          # computeType
+            :int,          # alg
+            :pointer       # externalBuffer
+          ], :int
+
+          attach_function :cusparseSpMM_bufferSize, [
+            :pointer, :int, :int, :pointer, :pointer, :pointer, :pointer, :pointer, :int, :int, :pointer
+          ], :int
+
+          # CSR format conversion
+          attach_function :cusparseXcoo2csr, [
+            :pointer, :pointer, :int, :int, :pointer, :int
+          ], :int
+          attach_function :cusparseXcsr2coo, [
+            :pointer, :pointer, :int, :int, :pointer, :int
+          ], :int
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # Initialize cuSPARSE handle
+        def initialize_cusparse!
+          handle_ptr = FFI::MemoryPointer.new(:pointer)
+          status = cusparseCreate(handle_ptr)
+
+          raise CuSPARSEError, status unless status.zero?
+
+          @handle = handle_ptr.read_pointer
+          Ignis.logger.info("cuSPARSE initialized successfully")
+        end
+      end
+
+      # Check cuSPARSE status and raise error if not success
+      # @param status [Integer] cuSPARSE status code
+      # @param context [String] Context for error message
+      # @return [void]
+      def self.check_status!(status, context = "cuSPARSE operation")
+        return if status.zero?
+
+        raise CuSPARSEError, status
+      end
+    end
+  end
+end