grx-tensor 0.1.0 → 0.2.0

data/lib/grx/optim.rb

@@ -3,7 +3,7 @@
 module GRX
   module Optim
     # ================================================================
-    # SGD — Stochastic Gradient Descent (con momentum opcional)
+    # SGD — Stochastic Gradient Descent (with optional momentum)
     # ================================================================
     class SGD
       def initialize(params, lr: 0.01, momentum: 0.0, weight_decay: 0.0)
@@ -11,7 +11,7 @@ module GRX
         @lr           = lr
         @momentum     = momentum
         @weight_decay = weight_decay
-        # Buffer de velocidad para momentum
+        # Velocity buffer for momentum
         @velocity = params.map { |p| Tensor.zeros_like(p) }
       end
 
@@ -21,7 +21,7 @@ module GRX
 
           grad = param.grad
 
-          # L2 regularización (weight decay)
+          # L2 regularization (weight decay)
           if @weight_decay > 0
             grad = grad + param.scale(@weight_decay)
           end
@@ -35,7 +35,7 @@ module GRX
           if CAPI::LOADED
             CAPI.grx_sgd_step(param.storage.ptr, grad.storage.ptr, @lr, param.numel)
           else
-            # Fallback Ruby
+            # Ruby fallback
             param_data = param.to_a
             grad_data  = grad.to_a
             param_data.each_with_index { |v, j| param_data[j] = v - @lr * grad_data[j] }
@@ -51,7 +51,7 @@ module GRX
 
     # ================================================================
     # Adam — Adaptive Moment Estimation (Kingma & Ba, 2015)
-    # El optimizador estándar para redes neuronales profundas.
+    # The standard optimizer for deep neural networks.
     # ================================================================
     class Adam
       def initialize(params, lr: 0.001, beta1: 0.9, beta2: 0.999,
@@ -62,16 +62,16 @@ module GRX
         @beta2        = beta2
         @epsilon      = epsilon
         @weight_decay = weight_decay
-        @t            = 0  # paso actual
+        @t            = 0  # current step
 
-        # Momentos de primer y segundo orden (inicializados en cero)
+        # First and second order moment vectors (zero-initialized)
         @m = params.map { |p| Tensor.zeros_like(p) }
         @v = params.map { |p| Tensor.zeros_like(p) }
       end
 
       def step
         @t += 1
-        beta1t = @beta1 ** @t  # beta1^t para corrección de bias
+        beta1t = @beta1 ** @t  # beta1^t for bias correction
         beta2t = @beta2 ** @t
 
         @params.each_with_index do |param, i|
@@ -94,7 +94,7 @@ module GRX
               param.numel
             )
           else
-            # Fallback Ruby puro
+            # Pure Ruby fallback
             p_data = param.to_a
             m_data = @m[i].to_a
             v_data = @v[i].to_a

data/lib/grx/serialization.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module GRX
+  # ===================================================================
+  # Serialization — Native binary .grx format
+  #
+  # Binary layout:
+  # - 8 bytes:  Magic header "GRX1\0\0\0\0"
+  # - 4 bytes:  Number of parameter tensors (unsigned 32-bit big-endian)
+  # For each tensor:
+  #   - 2 bytes: Rank (number of dimensions)
+  #   - 4 bytes * rank: Dimensions of the shape (uint32 big-endian)
+  #   - 8 bytes: Total numel (uint64 big-endian)
+  #   - numel * 8 bytes: Direct binary packed IEEE 754 doubles
+  # ===================================================================
+  module Serialization
+    MAGIC = "GRX1\x00\x00\x00\x00".b
+
+    def self.save(model, path)
+      params = model.parameters
+      File.open(path, "wb") do |f|
+        f.write(MAGIC)
+        f.write([params.size].pack("N"))
+        params.each do |p|
+          shape = p.shape
+          f.write([shape.size].pack("n"))
+          f.write(shape.pack("N*"))
+          f.write([p.numel].pack("Q>"))
+          # Direct binary copy from native C buffer
+          bytes = if p.storage.ptr
+            p.storage.ptr[0, p.numel * 8]
+          else
+            p.to_a.pack("d*")
+          end
+          f.write(bytes)
+        end
+      end
+      path
+    end
+
+    def self.load(model, path)
+      params = model.parameters
+      File.open(path, "rb") do |f|
+        magic = f.read(8)
+        raise StorageError, "Invalid format: not a valid .grx binary file" unless magic == MAGIC
+        count = f.read(4).unpack1("N")
+        raise StorageError, "Parameter count mismatch: model has #{params.size}, file has #{count}" unless count == params.size
+
+        params.each_with_index do |p, idx|
+          rank = f.read(2).unpack1("n")
+          shape = f.read(rank * 4).unpack("N*")
+          numel = f.read(8).unpack1("Q>")
+          raise ShapeError, "Shape mismatch for parameter #{idx}: expected #{p.shape}, got #{shape}" unless shape == p.shape
+
+          bytes = f.read(numel * 8)
+          if p.storage.ptr
+            p.storage.ptr[0, bytes.bytesize] = bytes
+          else
+            p.storage.instance_variable_set(:@data, bytes.unpack("d*"))
+          end
+        end
+      end
+      model
+    end
+  end
+end

data/lib/grx/storage.rb

@@ -4,45 +4,37 @@ require "fiddle"
 
 module GRX
   # ===================================================================
-  # Storage — Buffer de memoria nativa
+  # Storage — Native memory buffer
   #
-  # Cuando CAPI está cargado:
-  #   @ptr  → Fiddle::Pointer a un bloque de doubles alineado a 32 bytes
-  #           reservado con grx_alloc() (malloc alineado en C).
-  #           Los datos viven en el heap de C, NO en el GC de Ruby.
+  # When CAPI is loaded:
+  #   @ptr  → Fiddle::Pointer to 32-byte aligned doubles block
+  #           allocated via grx_alloc() (C posix_memalign / _aligned_malloc).
+  #           Data lives in C heap, NOT managed by Ruby GC.
   #
-  # Cuando CAPI NO está cargado (fallback):
-  #   @data → Array de Ruby normal (lento pero siempre correcto).
-  #
-  # La separación entre los dos modos es transparente para Tensor.
+  # When CAPI is NOT loaded (fallback):
+  #   @data → Standard Ruby Array (slow but correct).
   # ===================================================================
   class Storage
     attr_reader :size
-
-    # ptr expuesto para que CAPI pueda leerlo directamente
     attr_reader :ptr
 
     def initialize(array_plano)
       @size = array_plano.size
 
       if CAPI::LOADED
-        # --- MODO RÁPIDO: memoria C alineada ---
-        # grx_alloc devuelve un double* alineado a 32 bytes
+        # Fast mode: aligned C memory
         @ptr = CAPI.grx_alloc(@size)
-        raise StorageError, "grx_alloc falló (OOM)" if @ptr.null?
+        raise StorageError, "grx_alloc failed (OOM)" if @ptr.null?
 
-        # Empaquetamos el Array de Ruby en el buffer C como doubles (little-endian)
-        # Array#pack("d*") → String binaria de IEEE 754 doubles
+        # Pack Ruby Array into C buffer as IEEE 754 doubles
         bytes = array_plano.pack("d*")
         @ptr[0, bytes.bytesize] = bytes
 
-        # Registramos un finalizer para liberar la memoria C cuando el objeto
-        # Ruby sea recolectado por el GC. Usamos ObjectSpace para evitar
-        # que el closure capture self (lo que impediría la recolección).
+        # Finalizer releases C memory upon Ruby GC collection
         ptr_to_free = @ptr
         ObjectSpace.define_finalizer(self, self.class.make_finalizer(ptr_to_free))
       else
-        # --- MODO FALLBACK: Array de Ruby ---
+        # Fallback mode: Ruby Array
         @data = array_plano.map(&:to_f)
         @ptr  = nil
       end
@@ -53,12 +45,11 @@ module GRX
     end
 
     # ------------------------------------------------------------------
-    # Lectura / escritura — usadas solo en modo fallback y por get()
-    # Las operaciones masivas (add, mul, etc.) van directo por @ptr en C.
+    # Read / Write — used in fallback mode and by item/get()
+    # High-performance tensor ops operate directly on @ptr in C.
     # ------------------------------------------------------------------
     def read(indice)
       if CAPI::LOADED
-        # Leemos 8 bytes desde el offset correcto y los desempaquetamos como double
         @ptr[indice * 8, 8].unpack1("d")
       else
         @data[indice]
@@ -73,7 +64,7 @@ module GRX
       end
     end
 
-    # Vuelca todo el buffer a un Array de Ruby (para to_a, inspect, tests)
+    # Dumps entire buffer to a Ruby Array
     def to_ruby_array
       if CAPI::LOADED
         @ptr[0, @size * 8].unpack("d#{@size}")