ignis-numerics 0.0.1

data/lib/nvruby/solver/lu.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require_relative "cusolver_bindings"
+
+module Ignis
+  module Solver
+    # LU Decomposition operations using cuSOLVER
+    # Computes P*A = L*U factorization for solving linear systems
+    module LU
+      class << self
+        # Compute LU factorization of a matrix
+        # @param matrix [NvArray] Input matrix (m x n)
+        # @param overwrite [Boolean] If true, overwrite input matrix with result
+        # @return [Hash] Contains :lu (factored matrix), :pivot (pivot indices), :info (status)
+        # @raise [CuSolverError] If factorization fails
+        def getrf(matrix, overwrite: false)
+          CuSolverBindings.ensure_loaded!
+
+          validate_matrix!(matrix)
+          m, n = matrix.shape
+          lda = m
+
+          # Copy matrix if not overwriting
+          work_matrix = overwrite ? matrix : matrix.dup
+
+          # Get workspace size
+          lwork_ptr = FFI::MemoryPointer.new(:int)
+          get_buffer_size(matrix.dtype, m, n, work_matrix.device_ffi_ptr, lda, lwork_ptr)
+          lwork = lwork_ptr.read_int
+
+          # Allocate workspace and pivot array
+          workspace = CUDA::Memory.new(lwork * dtype_size(matrix.dtype))
+          pivot = CUDA::Memory.new(([m, n].min) * 4) # int32 pivot indices
+          info = CUDA::Memory.new(4) # int32 info
+
+          # Perform LU factorization (FFI cuSOLVER needs FFI pointers, not Fiddle)
+          perform_getrf(matrix.dtype, m, n, work_matrix.device_ffi_ptr, lda,
+                        workspace.ffi_ptr, pivot.ffi_ptr, info.ffi_ptr)
+
+          # Read info to check for errors
+          info_value = read_device_int(info)
+          if info_value < 0
+            raise CuSolverError.new("LU factorization: parameter #{-info_value} had an illegal value", 
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_INVALID_VALUE)
+          elsif info_value > 0
+            Ignis.logger.warn("LU factorization: U(#{info_value},#{info_value}) is exactly zero. " \
+                               "The factorization has been completed, but U is singular.")
+          end
+
+          # Synchronize to ensure completion
+          CUDA::RuntimeAPI.cudaDeviceSynchronize
+
+          {
+            lu: work_matrix,
+            pivot: pivot,
+            pivot_size: [m, n].min,
+            info: info_value
+          }
+        ensure
+          workspace&.free! if defined?(workspace) && workspace
+          info&.free! if defined?(info) && info && info_value
+        end
+
+        # Solve linear system Ax = b using LU factorization
+        # @param a [NvArray] Coefficient matrix (n x n) - can be pre-factored LU
+        # @param b [NvArray] Right-hand side matrix/vector (n x nrhs)
+        # @param pivot [FFI::Pointer, nil] Pivot indices from getrf (nil to compute fresh)
+        # @param trans [Symbol] :none, :transpose, or :conjugate
+        # @return [NvArray] Solution x
+        # @raise [CuSolverError] If solve fails
+        def getrs(a, b, pivot: nil, trans: :none)
+          CuSolverBindings.ensure_loaded!
+
+          validate_matrix!(a)
+          validate_matrix!(b)
+
+          n = a.shape[0]
+          raise ArgumentError, "Matrix A must be square" unless a.shape[0] == a.shape[1]
+          raise ArgumentError, "Matrix dimensions mismatch" unless b.shape[0] == n
+
+          nrhs = b.shape.length > 1 ? b.shape[1] : 1
+          lda = n
+          ldb = n
+
+          # If no pivot provided, compute LU factorization first
+          if pivot.nil?
+            result = getrf(a)
+            lu_matrix = result[:lu]
+            pivot = result[:pivot]
+          else
+            lu_matrix = a
+          end
+
+          # Copy b to output
+          x = b.dup
+
+          # Allocate info
+          info = CUDA::Memory.new(4)
+
+          # Map transpose option
+          trans_op = case trans
+                     when :none then CuSolverBindings::CUBLAS_OP_N
+                     when :transpose then CuSolverBindings::CUBLAS_OP_T
+                     when :conjugate then CuSolverBindings::CUBLAS_OP_C
+                     else CuSolverBindings::CUBLAS_OP_N
+                     end
+
+          # Perform solve (FFI cuSOLVER needs FFI pointers, not Fiddle)
+          pivot_ptr = pivot.respond_to?(:ffi_ptr) ? pivot.ffi_ptr : pivot
+          perform_getrs(a.dtype, trans_op, n, nrhs, lu_matrix.device_ffi_ptr, lda,
+                        pivot_ptr, x.device_ffi_ptr, ldb, info.ffi_ptr)
+
+          # Check info
+          info_value = read_device_int(info)
+          if info_value < 0
+            raise CuSolverError.new("LU solve: parameter #{-info_value} had an illegal value",
+                                    cusolver_code: CuSolverBindings::CUSOLVER_STATUS_INVALID_VALUE)
+          end
+
+          CUDA::RuntimeAPI.cudaDeviceSynchronize
+
+          x
+        ensure
+          info&.free! if defined?(info) && info
+        end
+
+        # Solve linear system Ax = b (convenience method)
+        # @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)
+          getrs(a, b)
+        end
+
+        private
+
+        # Validate that input is a valid matrix
+        # @param matrix [NvArray]
+        # @raise [ArgumentError] If matrix is invalid
+        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
+
+        # Get element size for dtype
+        # @param dtype [Symbol]
+        # @return [Integer]
+        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
+
+        # Read an int32 from a CUDA::Memory (info/pivot) via the Fiddle-safe
+        # CUDA::Memory#copy_to_host path (avoids mixing FFI and Fiddle pointers).
+        # @param mem [CUDA::Memory]
+        # @return [Integer]
+        def read_device_int(mem)
+          buf = mem.copy_to_host(count: 4)
+          buf[0, 4].unpack1("l")
+        end
+
+        # Get buffer size for LU factorization — dispatched by dtype (was hardcoded
+        # to Sgetrf, so float64/complex matrices sized their workspace for float32).
+        def get_buffer_size(dtype, m, n, a_ptr, lda, lwork_ptr)
+          h = CuSolverBindings.get_handle
+          status = case dtype
+                   when :float32 then CuSolverBindings.cusolverDnSgetrf_bufferSize(h, m, n, a_ptr, lda, lwork_ptr)
+                   when :float64 then CuSolverBindings.cusolverDnDgetrf_bufferSize(h, m, n, a_ptr, lda, lwork_ptr)
+                   when :complex64 then CuSolverBindings.cusolverDnCgetrf_bufferSize(h, m, n, a_ptr, lda, lwork_ptr)
+                   when :complex128 then CuSolverBindings.cusolverDnZgetrf_bufferSize(h, m, n, a_ptr, lda, lwork_ptr)
+                   else raise UnsupportedDTypeError.new(dtype, operation: "LU factorization")
+                   end
+          CuSolverBindings.check_status!(status, "cusolverDn#{dtype}getrf_bufferSize")
+        end
+
+        # Perform LU factorization — dispatched by dtype.
+        def perform_getrf(dtype, m, n, a_ptr, lda, workspace, pivot, info)
+          h = CuSolverBindings.get_handle
+          status = case dtype
+                   when :float32 then CuSolverBindings.cusolverDnSgetrf(h, m, n, a_ptr, lda, workspace, pivot, info)
+                   when :float64 then CuSolverBindings.cusolverDnDgetrf(h, m, n, a_ptr, lda, workspace, pivot, info)
+                   when :complex64 then CuSolverBindings.cusolverDnCgetrf(h, m, n, a_ptr, lda, workspace, pivot, info)
+                   when :complex128 then CuSolverBindings.cusolverDnZgetrf(h, m, n, a_ptr, lda, workspace, pivot, info)
+                   else raise UnsupportedDTypeError.new(dtype, operation: "LU factorization")
+                   end
+          CuSolverBindings.check_status!(status, "cusolverDn#{dtype}getrf")
+        end
+
+        # Perform LU solve — dispatched by dtype.
+        def perform_getrs(dtype, trans, n, nrhs, a_ptr, lda, pivot, b_ptr, ldb, info)
+          h = CuSolverBindings.get_handle
+          status = case dtype
+                   when :float32 then CuSolverBindings.cusolverDnSgetrs(h, trans, n, nrhs, a_ptr, lda, pivot, b_ptr, ldb, info)
+                   when :float64 then CuSolverBindings.cusolverDnDgetrs(h, trans, n, nrhs, a_ptr, lda, pivot, b_ptr, ldb, info)
+                   when :complex64 then CuSolverBindings.cusolverDnCgetrs(h, trans, n, nrhs, a_ptr, lda, pivot, b_ptr, ldb, info)
+                   when :complex128 then CuSolverBindings.cusolverDnZgetrs(h, trans, n, nrhs, a_ptr, lda, pivot, b_ptr, ldb, info)
+                   else raise UnsupportedDTypeError.new(dtype, operation: "LU solve")
+                   end
+          CuSolverBindings.check_status!(status, "cusolverDn#{dtype}getrs")
+        end
+      end
+    end
+
+    # LU Solver plan for repeated solves with the same matrix
+    # Caches the LU factorization for efficiency
+    class LUSolver
+      # @return [NvArray] Original matrix
+      attr_reader :matrix
+
+      # @return [NvArray] LU factored matrix
+      attr_reader :lu
+
+      # @return [FFI::Pointer] Pivot indices
+      attr_reader :pivot
+
+      # @return [Integer] Matrix dimension
+      attr_reader :n
+
+      # Create an LU solver for the given matrix
+      # @param matrix [NvArray] Coefficient matrix (n x n)
+      def initialize(matrix)
+        @matrix = matrix
+        validate!
+        @n = matrix.shape[0]
+        factorize!
+      end
+
+      # Solve Ax = b using the cached factorization
+      # @param b [NvArray] Right-hand side (n x nrhs)
+      # @param trans [Symbol] :none, :transpose, or :conjugate
+      # @return [NvArray] Solution x
+      def solve(b, trans: :none)
+        LU.getrs(@lu, b, pivot: @pivot, trans: trans)
+      end
+
+      # Release resources
+      # @return [void]
+      def destroy!
+        @pivot&.free!
+        @pivot = nil
+        @factorized = false
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "Matrix must be square" unless @matrix.shape[0] == @matrix.shape[1]
+        raise ArgumentError, "Matrix must be 2D" unless @matrix.shape.length == 2
+      end
+
+      def factorize!
+        result = LU.getrf(@matrix.dup)
+        @lu = result[:lu]
+        @pivot = result[:pivot]
+        @factorized = true
+      end
+    end
+  end
+end

data/lib/nvruby/solver/sparse_solver.rb

@@ -0,0 +1,429 @@
+# frozen_string_literal: true
+
+require_relative "cudss_bindings"
+
+module Ignis
+  module Solver
+    # High-level sparse linear solver using cuDSS
+    # Solves sparse systems of the form Ax = b using direct methods
+    #
+    # cuDSS phases:
+    # 1. Analysis: Reordering and symbolic factorization
+    # 2. Factorization: Numerical factorization (LU, Cholesky, LDL)
+    # 3. Solve: Forward/backward substitution
+    #
+    # @example Solve a sparse linear system
+    #   solver = Ignis::Solver::SparseSolver.new(sparse_matrix)
+    #   solver.analyze!
+    #   solver.factor!
+    #   x = solver.solve(b)
+    #   solver.destroy!
+    #
+    # @example Quick solve (combines all phases)
+    #   x = Ignis::Solver::SparseSolver.solve(sparse_matrix, b)
+    class SparseSolver
+      # Matrix types for cuDSS
+      MATRIX_TYPE_GENERAL = 0
+      MATRIX_TYPE_SYMMETRIC = 1
+      MATRIX_TYPE_HERMITIAN = 2
+      MATRIX_TYPE_SPD = 3  # Symmetric Positive Definite
+      MATRIX_TYPE_HPD = 4  # Hermitian Positive Definite
+
+      # Index base
+      INDEX_BASE_ZERO = 0
+      INDEX_BASE_ONE = 1
+
+      # CUDA library data types (from library_types.h)
+      # cuDSS uses these for both value and index types
+      CUDA_R_32F = 0    # float
+      CUDA_R_64F = 1    # double
+      CUDA_R_16F = 2    # half
+      CUDA_C_32F = 4    # cuComplex
+      CUDA_C_64F = 5    # cuDoubleComplex
+      CUDA_R_32I = 10   # int32
+      CUDA_R_64I = 24   # int64
+
+      # @return [Sparse::SparseMatrix] The sparse coefficient matrix
+      attr_reader :matrix
+
+      # @return [Symbol] Matrix type (:general, :symmetric, :spd)
+      attr_reader :matrix_type
+
+      # @return [Boolean] Whether analysis has been performed
+      attr_reader :analyzed
+
+      # @return [Boolean] Whether factorization has been performed
+      attr_reader :factored
+
+      # Convenience method to solve a sparse system in one call
+      # @param sparse_matrix [Sparse::SparseMatrix] Sparse coefficient matrix A
+      # @param b [NvArray] Right-hand side vector/matrix b
+      # @param matrix_type [Symbol] Type of matrix (:general, :symmetric, :spd)
+      # @return [NvArray] Solution vector/matrix x
+      def self.solve(sparse_matrix, b, matrix_type: :general)
+        solver = new(sparse_matrix, matrix_type: matrix_type)
+        begin
+          solver.analyze!
+          solver.factor!
+          solver.solve(b)
+        ensure
+          solver.destroy!
+        end
+      end
+
+      # Initialize sparse solver
+      # @param sparse_matrix [Sparse::SparseMatrix] Sparse coefficient matrix A in CSR format
+      # @param matrix_type [Symbol] Type of matrix (:general, :symmetric, :spd, :hermitian, :hpd)
+      def initialize(sparse_matrix, matrix_type: :general)
+        validate_matrix!(sparse_matrix)
+        @matrix = sparse_matrix
+        @matrix_type = matrix_type
+        @analyzed = false
+        @factored = false
+        @handle = nil
+        @config = nil
+        @data = nil
+        @matrix_wrapper = nil
+        @placeholder_x = nil
+        @placeholder_b = nil
+        @stream = nil
+
+        initialize_cudss!
+      end
+
+      # Perform analysis phase (reordering + symbolic factorization)
+      # @return [self]
+      def analyze!
+        raise StateError, "cuDSS not initialized" unless @handle
+
+        phase = CuDSSBindings::CUDSS_PHASE_ANALYSIS
+        status = CuDSSBindings.cudssExecute(
+          @handle, phase, @config, @data, @matrix_wrapper, @placeholder_x, @placeholder_b
+        )
+        CuDSSBindings.check_status!(status, "cuDSS analysis")
+
+        @analyzed = true
+        self
+      end
+
+      # Perform numerical factorization
+      # @return [self]
+      def factor!
+        raise StateError, "Must call analyze! before factor!" unless @analyzed
+
+        phase = CuDSSBindings::CUDSS_PHASE_FACTORIZATION
+        status = CuDSSBindings.cudssExecute(
+          @handle, phase, @config, @data, @matrix_wrapper, @placeholder_x, @placeholder_b
+        )
+        CuDSSBindings.check_status!(status, "cuDSS factorization")
+
+        @factored = true
+        self
+      end
+
+      # Solve the system Ax = b
+      # @param b [NvArray] Right-hand side vector/matrix
+      # @return [NvArray] Solution vector/matrix x
+      def solve(b)
+        raise StateError, "Must call factor! before solve!" unless @factored
+
+        validate_rhs!(b)
+
+        # Ensure b is on device
+        b_dev = b.on_device? ? b : b.to_device
+
+        # Create output matrix
+        x = NvArray.zeros(b.shape, dtype: b.dtype, device: @matrix.device_index)
+        x = x.to_device
+
+        # Create cuDSS matrix wrappers for b and x
+        b_wrapper = create_dense_matrix_wrapper(b_dev)
+        x_wrapper = create_dense_matrix_wrapper(x)
+
+        # Execute solve phase
+        phase = CuDSSBindings::CUDSS_PHASE_SOLVE
+        status = CuDSSBindings.cudssExecute(
+          @handle, phase, @config, @data, @matrix_wrapper, x_wrapper, b_wrapper
+        )
+        CuDSSBindings.check_status!(status, "cuDSS solve")
+
+        # Cleanup temporary wrappers
+        CuDSSBindings.cudssMatrixDestroy(b_wrapper)
+        CuDSSBindings.cudssMatrixDestroy(x_wrapper)
+
+        x
+      end
+
+      # Refactor with updated numerical values (same sparsity pattern)
+      # Useful when solving multiple systems with same structure but different values
+      # @return [self]
+      def refactor!
+        raise StateError, "Must call factor! before refactor!" unless @factored
+
+        phase = CuDSSBindings::CUDSS_PHASE_REFACTORIZATION
+        status = CuDSSBindings.cudssExecute(
+          @handle, phase, @config, @data, @matrix_wrapper, nil, nil
+        )
+        CuDSSBindings.check_status!(status, "cuDSS refactorization")
+
+        self
+      end
+
+      # Release all cuDSS resources
+      # @return [void]
+      def destroy!
+        if @placeholder_x
+          CuDSSBindings.cudssMatrixDestroy(@placeholder_x)
+          @placeholder_x = nil
+        end
+
+        if @placeholder_b
+          CuDSSBindings.cudssMatrixDestroy(@placeholder_b)
+          @placeholder_b = nil
+        end
+
+        if @matrix_wrapper
+          CuDSSBindings.cudssMatrixDestroy(@matrix_wrapper)
+          @matrix_wrapper = nil
+        end
+
+        if @data && @handle
+          CuDSSBindings.cudssDataDestroy(@handle, @data)
+          @data = nil
+        end
+
+        if @config
+          CuDSSBindings.cudssConfigDestroy(@config)
+          @config = nil
+        end
+
+        if @handle
+          CuDSSBindings.cudssDestroy(@handle)
+          @handle = nil
+        end
+
+        @analyzed = false
+        @factored = false
+      end
+
+      private
+
+      # Validate input sparse matrix
+      def validate_matrix!(matrix)
+        unless matrix.is_a?(Sparse::SparseMatrix)
+          raise ArgumentError, "Expected SparseMatrix, got #{matrix.class}"
+        end
+
+        unless matrix.format == :csr
+          raise ArgumentError, "cuDSS requires CSR format, got #{matrix.format}"
+        end
+
+        unless %i[float32 float64 complex64 complex128].include?(matrix.dtype)
+          raise UnsupportedDTypeError.new(matrix.dtype, operation: "sparse solve")
+        end
+      end
+
+      # Validate right-hand side
+      def validate_rhs!(b)
+        unless b.is_a?(NvArray)
+          raise ArgumentError, "Expected NvArray, got #{b.class}"
+        end
+
+        n = @matrix.shape[0]
+        if b.ndim == 1
+          unless b.shape[0] == n
+            raise DimensionError, "RHS size (#{b.shape[0]}) doesn't match matrix rows (#{n})"
+          end
+        elsif b.ndim == 2
+          unless b.shape[0] == n
+            raise DimensionError, "RHS rows (#{b.shape[0]}) don't match matrix rows (#{n})"
+          end
+        else
+          raise DimensionError, "RHS must be 1D or 2D, got #{b.ndim}D"
+        end
+      end
+
+      # Initialize cuDSS handle and create matrix wrapper
+      def initialize_cudss!
+        CuDSSBindings.ensure_loaded!
+
+        # Create handle
+        handle_ptr = FFI::MemoryPointer.new(:pointer)
+        status = CuDSSBindings.cudssCreate(handle_ptr)
+        CuDSSBindings.check_status!(status, "cuDSS create")
+        @handle = handle_ptr.read_pointer
+
+        # Set CUDA stream (required before analyze)
+        setup_cuda_stream!
+
+        # Create config and data objects
+        @config = create_config_object
+        @data = create_data_object
+
+        # Create sparse matrix wrapper
+        @matrix_wrapper = create_csr_matrix_wrapper
+
+        # Create placeholder solution/rhs wrappers (required for analyze/factor phases)
+        create_placeholder_vectors!
+      end
+
+      # Set up CUDA stream for cuDSS operations
+      # @return [void]
+      def setup_cuda_stream!
+        @stream_obj = CUDA::Stream.new
+        @stream = @stream_obj.handle
+
+        status = CuDSSBindings.cudssSetStream(@handle, @stream)
+        CuDSSBindings.check_status!(status, "cuDSS set stream")
+      end
+
+      # Create placeholder solution/rhs vectors for analyze/factor phases
+      # cuDSS requires valid matrix wrappers even if values aren't used during these phases
+      # @return [void]
+      def create_placeholder_vectors!
+        n = @matrix.shape[0]
+        value_type = cudss_data_type(@matrix.dtype)
+        layout = 0  # CUDSS_LAYOUT_COL_MAJOR (0 = column major, 1 = row major not supported)
+
+        # Allocate device memory for placeholder vectors
+        elem_size = @matrix.dtype == :float64 ? 8 : 4
+        @placeholder_x_mem = CUDA::Memory.new(n * elem_size)
+        @placeholder_b_mem = CUDA::Memory.new(n * elem_size)
+
+        # Create dense matrix wrappers for x (solution) and b (rhs)
+        x_ptr = FFI::MemoryPointer.new(:pointer)
+        status = CuDSSBindings.cudssMatrixCreateDn(
+          x_ptr, n, 1, n, @placeholder_x_mem.device_ptr, value_type, layout
+        )
+        CuDSSBindings.check_status!(status, "cuDSS create placeholder x")
+        @placeholder_x = x_ptr.read_pointer
+
+        b_ptr = FFI::MemoryPointer.new(:pointer)
+        status = CuDSSBindings.cudssMatrixCreateDn(
+          b_ptr, n, 1, n, @placeholder_b_mem.device_ptr, value_type, layout
+        )
+        CuDSSBindings.check_status!(status, "cuDSS create placeholder b")
+        @placeholder_b = b_ptr.read_pointer
+      end
+
+      # Create cuDSS config object
+      # @return [FFI::Pointer]
+      def create_config_object
+        config_ptr = FFI::MemoryPointer.new(:pointer)
+
+        status = CuDSSBindings.cudssConfigCreate(config_ptr)
+        CuDSSBindings.check_status!(status, "cuDSS config create")
+
+        config_ptr.read_pointer
+      end
+
+      # Create cuDSS data object
+      # @return [FFI::Pointer]
+      def create_data_object
+        data_ptr = FFI::MemoryPointer.new(:pointer)
+
+        status = CuDSSBindings.cudssDataCreate(@handle, data_ptr)
+        CuDSSBindings.check_status!(status, "cuDSS data create")
+
+        data_ptr.read_pointer
+      end
+
+      # Create CSR matrix wrapper for cuDSS
+      # @return [FFI::Pointer]
+      def create_csr_matrix_wrapper
+        matrix_ptr = FFI::MemoryPointer.new(:pointer)
+
+        n_rows = @matrix.shape[0]
+        n_cols = @matrix.shape[1]
+        nnz = @matrix.nnz
+
+        # Ensure CUDA context is initialized (cuDSS requires active context)
+        Ignis.synchronize
+
+        # Ensure matrix is on device - cuDSS requires device pointers
+        @matrix.to_device unless @matrix.on_device?
+
+        # Verify we have valid device pointers
+        raise StateError, "Matrix not on device" unless @matrix.on_device?
+        raise StateError, "row_ptr is nil" if @matrix.row_ptr.nil?
+        raise StateError, "col_indices is nil" if @matrix.col_indices.nil?
+        raise StateError, "values is nil" if @matrix.values.nil?
+
+        # Get cuDSS data type
+        value_type = cudss_data_type(@matrix.dtype)
+        index_type = CUDA_R_32I  # int32 indices
+
+        # Matrix structure type
+        structure = case @matrix_type
+                    when :general then MATRIX_TYPE_GENERAL
+                    when :symmetric then MATRIX_TYPE_SYMMETRIC
+                    when :hermitian then MATRIX_TYPE_HERMITIAN
+                    when :spd then MATRIX_TYPE_SPD
+                    when :hpd then MATRIX_TYPE_HPD
+                    else MATRIX_TYPE_GENERAL
+                    end
+
+        # mview: CUDSS_MVIEW_FULL = 0
+        mview_full = 0
+
+        status = CuDSSBindings.cudssMatrixCreateCsr(
+          matrix_ptr,
+          n_rows, n_cols, nnz,
+          @matrix.row_ptr.device_ptr,
+          FFI::Pointer::NULL,  # row_end - NULL for standard CSR
+          @matrix.col_indices.device_ptr,
+          @matrix.values.device_ptr,
+          index_type,
+          value_type,
+          structure,
+          mview_full,       # mview - full matrix view
+          INDEX_BASE_ZERO   # indexBase - zero-based indexing
+        )
+        CuDSSBindings.check_status!(status, "cuDSS CSR matrix create")
+
+        matrix_ptr.read_pointer
+      end
+
+      # Create dense matrix wrapper for cuDSS
+      # @return [FFI::Pointer]
+      def create_dense_matrix_wrapper(array)
+        matrix_ptr = FFI::MemoryPointer.new(:pointer)
+
+        n_rows = array.ndim == 1 ? array.shape[0] : array.shape[0]
+        n_cols = array.ndim == 1 ? 1 : array.shape[1]
+        ld = n_rows  # Leading dimension (column-major)
+
+        value_type = cudss_data_type(array.dtype)
+        layout = 0  # CUDSS_LAYOUT_COL_MAJOR (0 = column major, 1 = row major not supported)
+
+        status = CuDSSBindings.cudssMatrixCreateDn(
+          matrix_ptr,
+          n_rows, n_cols, ld,
+          array.device_ptr,
+          value_type,
+          layout
+        )
+        CuDSSBindings.check_status!(status, "cuDSS dense matrix create")
+
+        matrix_ptr.read_pointer
+      end
+
+      # Convert Ignis dtype to CUDA library data type
+      # @param dtype [Symbol]
+      # @return [Integer]
+      def cudss_data_type(dtype)
+        case dtype
+        when :float32 then CUDA_R_32F
+        when :float64 then CUDA_R_64F
+        when :complex64 then CUDA_C_32F
+        when :complex128 then CUDA_C_64F
+        else
+          raise UnsupportedDTypeError.new(dtype, operation: "cuDSS")
+        end
+      end
+    end
+
+    # State error for solver operations
+    class StateError < StandardError; end
+  end
+end