ignis 0.0.1

data/lib/nvruby/errors.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Ignis
+  # Base error class for all Ignis errors
+  class Error < StandardError; end
+
+  # Raised when a CUDA operation fails
+  class CudaError < Error
+    # @return [Integer] CUDA error code
+    attr_reader :cuda_code
+
+    # @param message [String] Error message
+    # @param cuda_code [Integer, nil] CUDA error code
+    def initialize(message, cuda_code: nil)
+      @cuda_code = cuda_code
+      super(cuda_code ? "#{message} (CUDA error #{cuda_code})" : message)
+    end
+  end
+
+  # Raised when CUDA runtime encounters an error
+  class CudaRuntimeError < CudaError; end
+
+  # Raised when cuBLAS operation fails
+  class CuBLASError < CudaError
+    STATUSES = {
+      0  => :success,
+      1  => :not_initialized,
+      3  => :alloc_failed,
+      7  => :invalid_value,
+      8  => :arch_mismatch,
+      11 => :mapping_error,
+      13 => :execution_failed,
+      14 => :internal_error,
+      15 => :not_supported,
+      16 => :license_error
+    }.freeze
+
+    # @param status [Integer] cuBLAS status code
+    def initialize(status)
+      status_name = STATUSES[status] || :unknown
+      super("cuBLAS operation failed: #{status_name}", cuda_code: status)
+    end
+  end
+
+  # Raised when cuFFT operation fails
+  class CuFFTError < CudaError
+    STATUSES = {
+      0  => :success,
+      1  => :invalid_plan,
+      2  => :alloc_failed,
+      3  => :invalid_type,
+      4  => :invalid_value,
+      5  => :internal_error,
+      6  => :exec_failed,
+      7  => :setup_failed,
+      8  => :invalid_size,
+      9  => :unaligned_data,
+      10 => :incomplete_parameter_list,
+      11 => :invalid_device,
+      12 => :parse_error,
+      13 => :no_workspace,
+      14 => :not_implemented,
+      15 => :license_error,
+      16 => :not_supported
+    }.freeze
+
+    # @param status [Integer] cuFFT status code
+    def initialize(status)
+      status_name = STATUSES[status] || :unknown
+      super("cuFFT operation failed: #{status_name}", cuda_code: status)
+    end
+  end
+
+  # Raised when cuRAND operation fails
+  class CuRANDError < CudaError
+    STATUSES = {
+      0   => :success,
+      100 => :version_mismatch,
+      101 => :not_initialized,
+      102 => :allocation_failed,
+      103 => :type_error,
+      104 => :out_of_range,
+      105 => :length_not_multiple,
+      106 => :double_precision_required,
+      201 => :launch_failure,
+      202 => :preexisting_failure,
+      203 => :initialization_failed,
+      204 => :arch_mismatch,
+      999 => :internal_error
+    }.freeze
+
+    # @param status [Integer] cuRAND status code
+    def initialize(status)
+      status_name = STATUSES[status] || :unknown
+      super("cuRAND operation failed: #{status_name}", cuda_code: status)
+    end
+  end
+
+  # Raised when cuSPARSE operation fails
+  class CuSPARSEError < CudaError
+    STATUSES = {
+      0  => :success,
+      1  => :not_initialized,
+      2  => :alloc_failed,
+      3  => :invalid_value,
+      4  => :arch_mismatch,
+      5  => :mapping_error,
+      6  => :execution_failed,
+      7  => :internal_error,
+      8  => :matrix_type_not_supported,
+      9  => :zero_pivot,
+      10 => :not_supported,
+      11 => :insufficient_resources
+    }.freeze
+
+    # @param status [Integer] cuSPARSE status code
+    def initialize(status)
+      status_name = STATUSES[status] || :unknown
+      super("cuSPARSE operation failed: #{status_name}", cuda_code: status)
+    end
+  end
+
+  # Raised when cuSOLVER operation fails
+  class CuSolverError < CudaError
+    STATUSES = {
+      0  => :success,
+      1  => :not_initialized,
+      2  => :alloc_failed,
+      3  => :invalid_value,
+      4  => :arch_mismatch,
+      5  => :mapping_error,
+      6  => :execution_failed,
+      7  => :internal_error,
+      8  => :matrix_type_not_supported,
+      9  => :not_supported,
+      10 => :zero_pivot,
+      11 => :invalid_license,
+      12 => :irs_params_not_initialized,
+      13 => :irs_params_invalid,
+      14 => :irs_params_invalid_prec,
+      15 => :irs_params_invalid_refine,
+      16 => :irs_params_invalid_maxiter,
+      20 => :irs_internal_error,
+      21 => :irs_not_supported,
+      22 => :irs_out_of_range,
+      23 => :irs_nrhs_not_supported_for_refine_gmres,
+      25 => :irs_infos_not_initialized
+    }.freeze
+
+    # @return [String, nil] Context where error occurred
+    attr_reader :context
+
+    # @param message [String] Error message
+    # @param cusolver_code [Integer, nil] cuSOLVER status code
+    # @param context [String, nil] Context for error
+    def initialize(message, cusolver_code: nil, context: nil)
+      @context = context
+      status_name = cusolver_code ? (STATUSES[cusolver_code] || :unknown) : nil
+
+      full_message = message
+      full_message = "#{context}: #{full_message}" if context
+      full_message = "#{full_message} (#{status_name})" if status_name
+
+      super(full_message, cuda_code: cusolver_code)
+    end
+  end
+
+  # Raised when memory allocation fails
+  class MemoryError < Error; end
+
+  # Raised when device memory allocation fails
+  class DeviceMemoryError < MemoryError; end
+
+  # Raised when host memory allocation fails
+  class HostMemoryError < MemoryError; end
+
+  # Raised when an invalid operation is attempted
+  class InvalidOperationError < Error; end
+
+  # Raised when required CUDA library is not found
+  class LibraryNotFoundError < Error
+    # @return [String] Library name that was not found
+    attr_reader :library_name
+
+    # @param library_name [String] Name of the missing library
+    def initialize(library_name)
+      @library_name = library_name
+      super("Required CUDA library not found: #{library_name}")
+    end
+  end
+
+  # Raised when no CUDA-capable device is available
+  class NoDeviceError < Error
+    def initialize
+      super("No CUDA-capable device is available")
+    end
+  end
+
+  # Raised when array dimensions are incompatible
+  class DimensionError < Error; end
+
+  # Raised when data type is not supported
+  class UnsupportedDTypeError < Error
+    # @return [Symbol] The unsupported dtype
+    attr_reader :dtype
+
+    # @param dtype [Symbol] The unsupported data type
+    # @param operation [String, nil] The operation that doesn't support this dtype
+    def initialize(dtype, operation: nil)
+      @dtype = dtype
+      message = "Unsupported data type: #{dtype}"
+      message += " for operation #{operation}" if operation
+      super(message)
+    end
+  end
+
+  # Raised when autotuning fails
+  class AutotuneError < Error; end
+
+  # Raised when plan creation fails
+  class PlanError < Error; end
+
+  # Raised when NVRTC compilation fails
+  class NVRTCError < CudaError
+    STATUSES = {
+      0  => :success,
+      1  => :out_of_memory,
+      2  => :program_creation_failure,
+      3  => :invalid_input,
+      4  => :invalid_program,
+      5  => :invalid_option,
+      6  => :compilation_error,
+      7  => :builtin_operation_failure,
+      8  => :no_name_expressions_after_compilation,
+      9  => :no_lowered_names_before_compilation,
+      10 => :name_expression_not_valid,
+      11 => :internal_error
+    }.freeze
+
+    # @return [String, nil] Compilation log with error details
+    attr_reader :compilation_log
+
+    # @return [String, nil] Context where error occurred
+    attr_reader :context
+
+    # @param status [Integer] NVRTC result code
+    # @param compilation_log [String, nil] Compilation error log
+    # @param context [String, nil] Context for error
+    def initialize(status, compilation_log: nil, context: nil)
+      @compilation_log = compilation_log
+      @context = context
+      status_name = STATUSES[status] || :unknown
+
+      message = "NVRTC error: #{status_name}"
+      message = "#{context}: #{message}" if context
+      message = "#{message}\nCompilation log:\n#{compilation_log}" if compilation_log && !compilation_log.empty?
+
+      super(message, cuda_code: status)
+    end
+  end
+
+  # Raised when CUDA Driver API operation fails
+  class CudaDriverError < CudaError
+    STATUSES = {
+      0   => :success,
+      1   => :invalid_value,
+      2   => :out_of_memory,
+      3   => :not_initialized,
+      4   => :deinitialized,
+      100 => :no_device,
+      101 => :invalid_device,
+      200 => :invalid_image,
+      201 => :invalid_context,
+      209 => :no_binary_for_gpu,
+      218 => :invalid_ptx,
+      300 => :invalid_source,
+      301 => :file_not_found,
+      400 => :invalid_handle,
+      500 => :not_found,
+      600 => :not_ready,
+      700 => :illegal_address,
+      701 => :launch_out_of_resources,
+      702 => :launch_timeout,
+      719 => :launch_failed,
+      999 => :unknown
+    }.freeze
+
+    # @return [String, nil] Context where error occurred
+    attr_reader :context
+
+    # @param status [Integer] CUDA Driver result code
+    # @param context [String, nil] Context for error
+    def initialize(status, context: nil)
+      @context = context
+      status_name = STATUSES[status] || :unknown
+
+      message = "CUDA Driver error: #{status_name}"
+      message = "#{context}: #{message}" if context
+
+      super(message, cuda_code: status)
+    end
+  end
+end

data/lib/nvruby/half.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Ignis
+  # Pure-Ruby IEEE-754 half-precision (binary16) and bfloat16 <-> float32 conversion.
+  #
+  # Ruby and FFI have no native 16-bit float type, so NvArray stores fp16/bf16 as
+  # raw uint16 bit patterns. These helpers convert to/from Ruby Floats with correct
+  # round-to-nearest-even rounding and proper subnormal / overflow / inf / NaN handling.
+  #
+  # This is the single source of truth for half conversion across BOTH NvArray
+  # classes (Ignis::NvArray and Ignis::Shared::NvArray) and the safetensors codec,
+  # so the math cannot drift between them.
+  module Half
+    module_function
+
+    # Encode a Float as IEEE-754 binary16 (fp16) bit pattern.
+    # @param value [Numeric]
+    # @return [Integer] 16-bit unsigned (0..0xFFFF)
+    def f32_to_f16(value)
+      bits = [value.to_f].pack("e").unpack1("V") # float32 little-endian bit pattern
+      sign = (bits >> 16) & 0x8000
+      exp  = (bits >> 23) & 0xFF
+      mant = bits & 0x7FFFFF
+
+      # Inf / NaN
+      return sign | (mant.zero? ? 0x7C00 : 0x7E00) if exp == 0xFF
+
+      e = exp - 127 + 15
+
+      if e >= 0x1F
+        # Overflow -> signed Inf
+        sign | 0x7C00
+      elsif e <= 0
+        # Subnormal or zero
+        return sign if e < -10 # too small to represent even as a subnormal
+
+        m = mant | 0x800000 # restore the implicit leading 1
+        shift = 14 - e # 14..24
+        half = m >> shift
+        rem = m & ((1 << shift) - 1)
+        halfway = 1 << (shift - 1)
+        half += 1 if rem > halfway || (rem == halfway && (half & 1) == 1) # round half to even
+        sign | half
+      else
+        # Normal
+        half = sign | (e << 10) | (mant >> 13)
+        rem = mant & 0x1FFF
+        # round half to even; a carry correctly propagates mantissa -> exponent (incl. -> Inf)
+        half += 1 if rem > 0x1000 || (rem == 0x1000 && (half & 1) == 1)
+        half & 0xFFFF
+      end
+    end
+
+    # Decode an IEEE-754 binary16 (fp16) bit pattern to a Ruby Float.
+    # @param bits [Integer] 16-bit unsigned
+    # @return [Float]
+    def f16_to_f32(bits)
+      sign = (bits >> 15) & 0x1
+      exp  = (bits >> 10) & 0x1F
+      mant = bits & 0x3FF
+
+      if exp.zero?
+        return sign.zero? ? 0.0 : -0.0 if mant.zero?
+
+        val = (mant / 1024.0) * (2.0**-14)
+      elsif exp == 0x1F
+        return Float::NAN unless mant.zero?
+
+        return sign.zero? ? Float::INFINITY : -Float::INFINITY
+      else
+        val = (1.0 + mant / 1024.0) * (2.0**(exp - 15))
+      end
+
+      sign.zero? ? val : -val
+    end
+
+    # Encode a Float as bfloat16 (the upper 16 bits of float32), round-to-nearest-even.
+    # @param value [Numeric]
+    # @return [Integer] 16-bit unsigned (0..0xFFFF)
+    def f32_to_bf16(value)
+      bits = [value.to_f].pack("e").unpack1("V")
+      # NaN: keep sign+exponent, force a non-zero mantissa (quiet NaN)
+      return ((bits >> 16) | 0x0040) & 0xFFFF if (bits & 0x7FFFFFFF) > 0x7F800000
+
+      lsb = (bits >> 16) & 1
+      bits += 0x7FFF + lsb # round half to even
+      (bits >> 16) & 0xFFFF
+    end
+
+    # Decode a bfloat16 bit pattern to a Ruby Float.
+    # @param bits [Integer] 16-bit unsigned
+    # @return [Float]
+    def bf16_to_f32(bits)
+      [(bits & 0xFFFF) << 16].pack("V").unpack1("e")
+    end
+  end
+end

data/lib/nvruby/jit/compiled_kernel.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Ignis
+  module JIT
+    # Represents compiled CUDA code (CUBIN binary)
+    # Device-agnostic representation that can be loaded onto any compatible GPU
+    # Thread-safe immutable object suitable for caching
+    class CompiledKernel
+      # @return [String] The compiled CUBIN binary data
+      attr_reader :cubin_data
+
+      # @return [Integer] Size of the CUBIN data in bytes
+      attr_reader :cubin_size
+
+      # @return [Integer] Target compute capability (e.g., 89 for sm_89)
+      attr_reader :compute_capability
+
+      # @return [String] The original source code (for debugging)
+      attr_reader :source_code
+
+      # @return [String] Kernel function name
+      attr_reader :kernel_name
+
+      # @return [Array<String>] Compilation options used
+      attr_reader :compile_options
+
+      # @return [Time] Compilation timestamp
+      attr_reader :compiled_at
+
+      # Create a new CompiledKernel
+      # @param cubin_data [String] The compiled CUBIN binary
+      # @param compute_capability [Integer] Target compute capability
+      # @param kernel_name [String] Kernel function name
+      # @param source_code [String, nil] Original source code
+      # @param compile_options [Array<String>] Options used for compilation
+      def initialize(cubin_data:, compute_capability:, kernel_name:, source_code: nil, compile_options: [])
+        @cubin_data = cubin_data.freeze
+        @cubin_size = cubin_data.bytesize
+        @compute_capability = compute_capability
+        @kernel_name = kernel_name.freeze
+        @source_code = source_code&.freeze
+        @compile_options = compile_options.map(&:freeze).freeze
+        @compiled_at = Time.now.freeze
+        freeze
+      end
+
+      # Load this compiled kernel onto a specific device
+      # @param device_id [Integer] Device index to load onto
+      # @return [KernelModule] The loaded module with function handle
+      # @raise [CudaDriverError] If loading fails
+      def load(device_id: 0)
+        Ignis.set_device(device_id)
+        KernelModule.new(self, device_id: device_id)
+      end
+
+      # Get a string representation
+      # @return [String]
+      def to_s
+        "#<Ignis::JIT::CompiledKernel #{@kernel_name} sm_#{@compute_capability} #{@cubin_size} bytes>"
+      end
+
+      # Get detailed inspection
+      # @return [String]
+      def inspect
+        "#<Ignis::JIT::CompiledKernel:0x#{object_id.to_s(16)} " \
+          "kernel=#{@kernel_name.inspect} " \
+          "sm=#{@compute_capability} " \
+          "size=#{@cubin_size} " \
+          "compiled_at=#{@compiled_at.strftime('%Y-%m-%d %H:%M:%S')}>"
+      end
+
+      # Check if compatible with a given compute capability
+      # @param target_cc [Integer] Target compute capability
+      # @return [Boolean] True if this kernel can run on target
+      def compatible_with?(target_cc)
+        target_cc >= @compute_capability
+      end
+    end
+  end
+end

data/lib/nvruby/jit/compiler.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Ignis
+  module JIT
+    # JIT Compiler with multi-level caching
+    # Provides runtime compilation of CUDA C++ source to executable kernels
+    # Based on nvmath-python caching strategy:
+    # - Thread-local cache for fast path (no locking)
+    # - Shared cache with Mutex for cross-thread reuse
+    # - Cache key: source code hash + compute capability
+    class Compiler
+      # Default compilation options
+      DEFAULT_OPTIONS = [
+        "--fmad=true",
+        "--std=c++17",
+        "-default-device"
+      ].freeze
+
+      # Thread-local storage key for kernel pointer cache
+      THREAD_LOCAL_CACHE_KEY = :nvruby_jit_kernel_cache
+
+      # Shared caches (guarded by mutex)
+      @compiled_code_cache = {} # cc -> source_hash -> CompiledKernel
+      @kernel_module_cache = {} # device_id -> source_hash -> KernelModule
+      @cache_mutex = Mutex.new
+
+      class << self
+        # Compile CUDA source code and return an executable Kernel
+        # @param source [String] CUDA C++ source code
+        # @param kernel_name [String] Name of the kernel function
+        # @param device_id [Integer] Target device (for compute capability)
+        # @param options [Array<String>] Additional compilation options
+        # @return [Kernel] Executable kernel
+        # @raise [NVRTCError] If compilation fails
+        def compile(source, kernel_name, device_id: 0, options: [])
+          source_hash = compute_source_hash(source, kernel_name)
+          cc = get_device_cc(device_id)
+
+          kernel_ptr = get_cached_kernel(device_id, source_hash)
+          return kernel_ptr if kernel_ptr
+
+          @cache_mutex.synchronize do
+            kernel_ptr = get_kernel_module_cached(source, source_hash, kernel_name, device_id, cc, options)
+            cache_kernel_pointer(device_id, source_hash, kernel_ptr)
+            kernel_ptr
+          end
+        end
+
+        # Compile to CompiledKernel without loading (for caching/serialization)
+        # @param source [String] CUDA C++ source code
+        # @param kernel_name [String] Name of the kernel function
+        # @param compute_capability [Integer] Target compute capability (e.g., 89)
+        # @param options [Array<String>] Additional compilation options
+        # @return [CompiledKernel] Compiled kernel (not yet loaded)
+        # @raise [NVRTCError] If compilation fails
+        def compile_only(source, kernel_name, compute_capability:, options: [])
+          compile_to_cubin(source, kernel_name, compute_capability, options)
+        end
+
+        # Clear all caches
+        # @return [void]
+        def clear_cache!
+          @cache_mutex.synchronize do
+            @compiled_code_cache.clear
+            @kernel_module_cache.clear
+          end
+          clear_thread_local_cache!
+          Ignis.logger.info("JIT compiler caches cleared")
+        end
+
+        # Clear thread-local cache only
+        # @return [void]
+        def clear_thread_local_cache!
+          Thread.current[THREAD_LOCAL_CACHE_KEY] = nil
+        end
+
+        # Get cache statistics
+        # @return [Hash] Statistics about cache usage
+        def cache_stats
+          @cache_mutex.synchronize do
+            compiled_count = @compiled_code_cache.values.sum { |h| h.size }
+            module_count = @kernel_module_cache.values.sum { |h| h.size }
+
+            {
+              compiled_kernels: compiled_count,
+              loaded_modules: module_count,
+              compute_capabilities: @compiled_code_cache.keys,
+              devices_with_modules: @kernel_module_cache.keys
+            }
+          end
+        end
+
+        # Get version information
+        # @return [Hash] NVRTC and driver version info
+        def version_info
+          {
+            nvrtc: NVRTCBindings.version,
+            cuda_driver: Ignis.cuda_version
+          }
+        end
+
+        private
+
+        # Compute a hash key for source code
+        # @param source [String]
+        # @param kernel_name [String]
+        # @return [String]
+        def compute_source_hash(source, kernel_name)
+          Digest::SHA256.hexdigest("#{kernel_name}:#{source}")
+        end
+
+        # Get device compute capability
+        # @param device_id [Integer]
+        # @return [Integer] Compute capability as integer (e.g., 89)
+        def get_device_cc(device_id)
+          thread_cache = Thread.current[:nvruby_device_cc_cache] ||= {}
+          return thread_cache[device_id] if thread_cache.key?(device_id)
+
+          major, minor = DriverAPIBindings.get_device_compute_capability(device_id)
+          cc = major * 10 + minor
+          thread_cache[device_id] = cc
+          cc
+        end
+
+        # Get cached kernel from thread-local cache
+        # @param device_id [Integer]
+        # @param source_hash [String]
+        # @return [Kernel, nil]
+        def get_cached_kernel(device_id, source_hash)
+          cache = Thread.current[THREAD_LOCAL_CACHE_KEY]
+          return nil unless cache
+
+          device_cache = cache[device_id]
+          return nil unless device_cache
+
+          device_cache[source_hash]
+        end
+
+        # Cache kernel in thread-local cache
+        # @param device_id [Integer]
+        # @param source_hash [String]
+        # @param kernel [Kernel]
+        # @return [void]
+        def cache_kernel_pointer(device_id, source_hash, kernel)
+          cache = Thread.current[THREAD_LOCAL_CACHE_KEY] ||= {}
+          device_cache = cache[device_id] ||= {}
+          device_cache[source_hash] = kernel
+        end
+
+        # Get or create kernel module from shared cache
+        # @param source [String]
+        # @param source_hash [String]
+        # @param kernel_name [String]
+        # @param device_id [Integer]
+        # @param cc [Integer]
+        # @param options [Array<String>]
+        # @return [Kernel]
+        def get_kernel_module_cached(source, source_hash, kernel_name, device_id, cc, options)
+          device_cache = @kernel_module_cache[device_id] ||= {}
+          kernel_module = device_cache[source_hash]
+
+          if kernel_module.nil? || kernel_module.destroyed?
+            compiled = get_compiled_code_cached(source, source_hash, kernel_name, cc, options)
+            kernel_module = compiled.load(device_id: device_id)
+            device_cache[source_hash] = kernel_module
+            Ignis.logger.debug("Loaded kernel module: #{kernel_name} on device #{device_id}")
+          end
+
+          kernel_module.to_kernel
+        end
+
+        # Get or create compiled code from shared cache
+        # @param source [String]
+        # @param source_hash [String]
+        # @param kernel_name [String]
+        # @param cc [Integer]
+        # @param options [Array<String>]
+        # @return [CompiledKernel]
+        def get_compiled_code_cached(source, source_hash, kernel_name, cc, options)
+          cc_cache = @compiled_code_cache[cc] ||= {}
+          compiled = cc_cache[source_hash]
+
+          if compiled.nil?
+            compiled = compile_to_cubin(source, kernel_name, cc, options)
+            cc_cache[source_hash] = compiled
+            Ignis.logger.info("Compiled kernel: #{kernel_name} for sm_#{cc}")
+          else
+            Ignis.logger.debug("Using cached compiled kernel: #{kernel_name} for sm_#{cc}")
+          end
+
+          compiled
+        end
+
+        # Compile source code to CUBIN
+        # @param source [String]
+        # @param kernel_name [String]
+        # @param cc [Integer]
+        # @param options [Array<String>]
+        # @return [CompiledKernel]
+        def compile_to_cubin(source, kernel_name, cc, options)
+          major = cc / 10
+          minor = cc % 10
+          arch_option = "--gpu-architecture=sm_#{major}#{minor}"
+
+          all_options = DEFAULT_OPTIONS + [arch_option] + options
+
+          Ignis.logger.debug("Compiling kernel #{kernel_name} with options: #{all_options}")
+
+          program = NVRTCBindings.create_program(source, name: "#{kernel_name}.cu")
+
+          begin
+            NVRTCBindings.compile_program(program, options: all_options)
+            cubin_data = NVRTCBindings.get_cubin(program)
+
+            CompiledKernel.new(
+              cubin_data: cubin_data,
+              compute_capability: cc,
+              kernel_name: kernel_name,
+              source_code: source,
+              compile_options: all_options
+            )
+          ensure
+            NVRTCBindings.destroy_program(program)
+          end
+        end
+      end
+    end
+  end
+end