ai4r 1.13 → 2.0

data/lib/ai4r/neural_network/hopfield.rb

@@ -1,149 +1,266 @@
+# frozen_string_literal: true
+
 # Author::    Sergio Fierens
 # License::   MPL 1.1
 # Project::   ai4r
-# Url::       http://ai4r.org/
+# Url::       https://github.com/SergioFierens/ai4r
 #
-# You can redistribute it and/or modify it under the terms of 
-# the Mozilla Public License version 1.1  as published by the 
+# You can redistribute it and/or modify it under the terms of
+# the Mozilla Public License version 1.1  as published by the
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
 
-require File.dirname(__FILE__) + '/../data/parameterizable' 
+require_relative '../data/parameterizable'
 
- module Ai4r
-   
+module Ai4r
   module NeuralNetwork
-    
     # = Hopfield Net =
-    # 
+    #
     # A Hopfield Network is a recurrent Artificial Neural Network.
-    # Hopfield nets are able to memorize a set of patterns, and then evaluate 
+    # Hopfield nets are able to memorize a set of patterns, and then evaluate
     # an input, returning the most similar stored pattern (although
     # convergence to one of the stored patterns is not guaranteed).
-    # Hopfield nets are great to deal with input noise. If a system accepts a 
-    # discrete set of inputs, but inputs are subject to noise, you can use a 
+    # Hopfield nets are great to deal with input noise. If a system accepts a
+    # discrete set of inputs, but inputs are subject to noise, you can use a
     # Hopfield net to eliminate noise and identified the given input.
     #
     # = How to Use =
-    # 
+    #
     #   data_set = Ai4r::Data::DataSet.new :data_items => array_of_patterns
     #   net = Ai4r::NeuralNetworks::Hopfield.new.train data_set
     #   net.eval input
     #     => one of the stored patterns in array_of_patterns
     class Hopfield
-      
       include Ai4r::Data::Parameterizable
-      
+
       attr_reader :weights, :nodes
-      
-      parameters_info :eval_iterations => "The network will run for a maximum "+
-        "of 'eval_iterations' iterations while evaluating an input. 500 by " +
-        "default.",
-        :active_node_value => "Default: 1",
-        :inactive_node_value => "Default: -1",
-        :threshold => "Default: 0"
-            
-      def initialize
+
+      parameters_info eval_iterations: 'The network will run for a maximum ' \
+                                       "of 'eval_iterations' iterations while evaluating an input. 500 by " \
+                                       'default.',
+                      active_node_value: 'Default: 1',
+                      inactive_node_value: 'Default: -1',
+                      threshold: 'Default: 0',
+                      weight_scaling: 'Scale factor applied when computing weights. ' \
+                                      'Default 1.0 / patterns_count',
+                      stop_when_stable: 'Stop evaluation when consecutive energy ' \
+                                        'values do not change. False by default',
+                      update_strategy: 'Update mode: :async_random (default), ' \
+                                       ':async_sequential, :synchronous'
+
+      # @param params [Object]
+      # @return [Object]
+      def initialize(params = {})
         @eval_iterations = 500
         @active_node_value = 1
         @inactive_node_value = -1
         @threshold = 0
+        @weight_scaling = nil
+        @stop_when_stable = false
+        @update_strategy = :async_random
+        # Deterministic random generator to guarantee reproducible behaviour
+        @rng = Random.new(3)
+        set_parameters(params) if params && !params.empty?
       end
 
       # Prepares the network to memorize the given data set.
       # Future calls to eval (should) return one of the memorized data items.
-      # A Hopfield network converges to a local minimum, but converge to one 
+      # A Hopfield network converges to a local minimum, but converge to one
       # of the "memorized" patterns is not guaranteed.
+      # @param data_set [Object]
+      # @return [Object]
       def train(data_set)
         @data_set = data_set
+        validate_training_data
         initialize_nodes(@data_set)
         initialize_weights(@data_set)
-        return self
+        self
       end
 
       # You can use run instead of eval to propagate values step by step.
-      # With this you can verify the progress of the network output with 
+      # With this you can verify the progress of the network output with
       # each step.
-      # 
+      #
       # E.g.:
       #   pattern = input
       #   100.times do
       #      pattern = net.run(pattern)
       #      puts pattern.inspect
       #   end
+      # @param input [Object]
+      # @return [Object]
       def run(input)
         set_input(input)
         propagate
-        return @nodes
+        @nodes
       end
 
       # Propagates the input until the network returns one of the memorized
       # patterns, or a maximum of "eval_iterations" times.
-      def eval(input)
+      #
+      # If +trace: true+ is passed the method returns a hash with the
+      # :states and :energies recorded at every iteration (including the
+      # initial state). This can be used to visualize convergence.
+      # @param input [Object]
+      # @param trace [Object]
+      # @return [Object]
+      def eval(input, trace: false)
         set_input(input)
+        prev_energy = energy
+        if trace
+          states = [@nodes.clone]
+          energies = [prev_energy]
+        end
         @eval_iterations.times do
-          propagate  
-          break if @data_set.data_items.include?(@nodes)
+          propagate
+          new_energy = energy
+          if trace
+            states << @nodes.clone
+            energies << new_energy
+          end
+          if @data_set.data_items.include?(@nodes)
+            return(if trace
+                     { states: states,
+                       energies: energies }
+                   else
+                     @nodes
+                   end)
+          end
+          break if @stop_when_stable && new_energy == prev_energy
+
+          prev_energy = new_energy
         end
-        return @nodes
+        trace ? { states: states, energies: energies } : @nodes
       end
-      
-      protected 
+
+      # Calculate network energy using current node states and weights.
+      # Energy = -0.5 * Σ w_ij * s_i * s_j
+      # @return [Object]
+      def energy
+        sum = 0.0
+        @nodes.each_with_index do |s_i, i|
+          i.times do |j|
+            sum += read_weight(i, j) * s_i * @nodes[j]
+          end
+        end
+        -sum
+      end
+
+      protected
+
       # Set all nodes state to the given input.
       # inputs parameter must have the same dimension as nodes
+      # @param inputs [Object]
+      # @return [Object]
       def set_input(inputs)
         raise ArgumentError unless inputs.length == @nodes.length
-        inputs.each_with_index { |input, i| @nodes[i] = input}
+
+        inputs.each_with_index { |input, i| @nodes[i] = input }
       end
-      
-      # Select a single node randomly and propagate its state to all other nodes
+
+      # Propagate network state according to configured update strategy.
+      # @return [Object]
       def propagate
+        case @update_strategy
+        when :async_sequential
+          propagate_async_sequential
+        when :synchronous
+          propagate_synchronous
+        else
+          propagate_async_random
+        end
+      end
+
+      # Select a single node randomly and propagate its state to all other nodes
+      # @return [Object]
+      def propagate_async_random
         sum = 0
-        i = (rand * @nodes.length).floor
-        @nodes.each_with_index {|node, j| sum += read_weight(i,j)*node }
-        @nodes[i] = (sum > @threshold) ? @active_node_value : @inactive_node_value
+        i = (@rng.rand * @nodes.length).floor
+        @nodes.each_with_index { |node, j| sum += read_weight(i, j) * node }
+        @nodes[i] = sum > @threshold ? @active_node_value : @inactive_node_value
+      end
+
+      # Iterate through nodes sequentially, updating each immediately
+      # @return [Object]
+      def propagate_async_sequential
+        @nodes.each_index do |i|
+          sum = 0
+          @nodes.each_with_index { |node, j| sum += read_weight(i, j) * node }
+          @nodes[i] = sum > @threshold ? @active_node_value : @inactive_node_value
+        end
+      end
+
+      # Update all nodes simultaneously using previous state
+      # @return [Object]
+      def propagate_synchronous
+        new_nodes = Array.new(@nodes.length)
+        @nodes.each_index do |i|
+          sum = 0
+          @nodes.each_with_index { |node, j| sum += read_weight(i, j) * node }
+          new_nodes[i] = sum > @threshold ? @active_node_value : @inactive_node_value
+        end
+        @nodes = new_nodes
       end
-      
+
       # Initialize all nodes with "inactive" state.
+      # @param data_set [Object]
+      # @return [Object]
       def initialize_nodes(data_set)
-        @nodes = Array.new(data_set.data_items.first.length, 
-          @inactive_node_value)
+        @nodes = Array.new(data_set.data_items.first.length,
+                           @inactive_node_value)
+      end
+
+      # Ensure training data only contains active or inactive values.
+      # @return [Object]
+      def validate_training_data
+        allowed = [@active_node_value, @inactive_node_value]
+        @data_set.data_items.each_with_index do |item, row|
+          item.each_with_index do |v, col|
+            raise ArgumentError, "Invalid value #{v} in item #{row}, position #{col}" unless allowed.include?(v)
+          end
+        end
       end
-      
+
       # Create a partial weigth matrix:
-      #   [ 
-      #     [w(1,0)], 
+      #   [
+      #     [w(1,0)],
       #     [w(2,0)], [w(2,1)],
       #     [w(3,0)], [w(3,1)], [w(3,2)],
-      #     ... 
+      #     ...
       #     [w(n-1,0)], [w(n-1,1)], [w(n-1,2)], ... , [w(n-1,n-2)]
       #   ]
       # where n is the number of nodes.
-      # 
+      #
       # We are saving memory here, as:
-      # 
+      #
       # * w[i][i] = 0 (no node connects with itself)
       # * w[i][j] = w[j][i] (weigths are symmetric)
-      # 
+      #
       # Use read_weight(i,j) to find out weight between node i and j
+      # @param data_set [Object]
+      # @return [Object]
       def initialize_weights(data_set)
-        @weights = Array.new(@nodes.length-1) {|l| Array.new(l+1)}
+        patterns_count = data_set.data_items.length
+        scaling = @weight_scaling || (1.0 / patterns_count)
+        @weights = Array.new(@nodes.length - 1) { |l| Array.new(l + 1) }
         @nodes.each_index do |i|
           i.times do |j|
-            @weights[i-1][j] = data_set.data_items.inject(0) { |sum, item| sum+= item[i]*item[j] }
+            sum = data_set.data_items.inject(0) { |s, item| s + (item[i] * item[j]) }
+            @weights[i - 1][j] = sum * scaling
           end
         end
       end
-      
-      # read_weight(i,j) reads the weigth matrix and returns weight between 
+
+      # read_weight(i,j) reads the weigth matrix and returns weight between
       # node i and j
+      # @param index_a [Object]
+      # @param index_b [Object]
+      # @return [Object]
       def read_weight(index_a, index_b)
         return 0 if index_a == index_b
+
         index_a, index_b = index_b, index_a if index_b > index_a
-        return @weights[index_a-1][index_b]
+        @weights[index_a - 1][index_b]
       end
-      
     end
-    
   end
-  
 end

data/lib/ai4r/neural_network/transformer.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# Minimal Transformer implementation
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+# Url::       https://github.com/SergioFierens/ai4r
+
+require_relative '../data/parameterizable'
+require_relative 'activation_functions'
+
+module Ai4r
+  module NeuralNetwork
+    # A tiny Transformer with embeddings, positional encoding,
+    # multi-head attention and a feed-forward layer. Depending on the
+    # architecture configuration it can operate as an encoder, decoder or
+    # encoder-decoder model. Weights are initialized randomly and the model is
+    # not trainable.
+    class Transformer
+      include Ai4r::Data::Parameterizable
+
+      parameters_info embed_dim: 'Embedding dimension.',
+                      num_heads: 'Number of attention heads.',
+                      ff_dim: 'Feed-forward hidden size.',
+                      vocab_size: 'Vocabulary size.',
+                      max_len: 'Maximum sequence length.',
+                      architecture: 'Architecture (:encoder, :decoder or :seq2seq).',
+                      seed: 'Deterministic random seed for initialization.'
+
+      # Initialize the Transformer with given hyperparameters.
+      def initialize(vocab_size:, max_len:, embed_dim: 8, num_heads: 2, ff_dim: 32,
+                     architecture: :encoder, seed: nil)
+        @seed = seed
+        @rng = seed ? Random.new(seed) : Random.new
+        @vocab_size = vocab_size
+        @max_len = max_len
+        @embed_dim = embed_dim
+        @num_heads = num_heads
+        @ff_dim = ff_dim
+        @architecture = architecture
+        if embed_dim % num_heads != 0
+          raise ArgumentError,
+                'embed_dim must be divisible by num_heads'
+        end
+        raise ArgumentError, 'invalid architecture' unless %i[encoder decoder seq2seq].include?(@architecture)
+
+        init_weights
+        build_positional_encoding
+      end
+
+      # Evaluate a sequence of integer token ids. Returns an array of
+      # length seq_len with embed_dim sized vectors.
+      def eval(*args)
+        case @architecture
+        when :encoder
+          tokens = args.first
+          raise ArgumentError, 'sequence too long' if tokens.length > @max_len
+
+          encode(tokens)
+        when :decoder
+          tokens = args.first
+          raise ArgumentError, 'sequence too long' if tokens.length > @max_len
+
+          decode(tokens)
+        when :seq2seq
+          src, tgt = args
+          raise ArgumentError, 'sequence too long' if src.length > @max_len || tgt.length > @max_len
+
+          memory = encode(src)
+          decode(tgt, memory)
+        else
+          raise ArgumentError, 'invalid architecture'
+        end
+      end
+
+      private
+
+      def encode(tokens)
+        x = tokens.map.with_index { |t, i| add(@token_embeddings[t], @positional[i]) }
+        x = multi_head_attention(x)
+        feed_forward(x)
+      end
+
+      def decode(tokens, memory = nil)
+        x = tokens.map.with_index { |t, i| add(@token_embeddings[t], @positional[i]) }
+        mask = causal_mask(x.length)
+        x = multi_head_attention(x, x, x, mask)
+        x = multi_head_attention(x, memory, memory) if memory
+        feed_forward(x)
+      end
+
+      def causal_mask(len)
+        Array.new(len) { |i| Array.new(len) { |j| j <= i } }
+      end
+
+      def head_dim
+        @embed_dim / @num_heads
+      end
+
+      def init_weights
+        @token_embeddings = Array.new(@vocab_size) { Array.new(@embed_dim) { @rng.rand * 2 - 1 } }
+        hd = head_dim
+        @heads = Array.new(@num_heads) do
+          {
+            q: Array.new(@embed_dim) { Array.new(hd) { @rng.rand * 2 - 1 } },
+            k: Array.new(@embed_dim) { Array.new(hd) { @rng.rand * 2 - 1 } },
+            v: Array.new(@embed_dim) { Array.new(hd) { @rng.rand * 2 - 1 } }
+          }
+        end
+        @wo = Array.new(@num_heads * hd) { Array.new(@embed_dim) { @rng.rand * 2 - 1 } }
+        @w1 = Array.new(@embed_dim) { Array.new(@ff_dim) { @rng.rand * 2 - 1 } }
+        @b1 = Array.new(@ff_dim, 0.0)
+        @w2 = Array.new(@ff_dim) { Array.new(@embed_dim) { @rng.rand * 2 - 1 } }
+        @b2 = Array.new(@embed_dim, 0.0)
+      end
+
+      def build_positional_encoding
+        @positional = Array.new(@max_len) do |pos|
+          Array.new(@embed_dim) do |i|
+            angle = pos / (10_000.0**((2 * (i / 2)) / @embed_dim.to_f))
+            i.even? ? Math.sin(angle) : Math.cos(angle)
+          end
+        end
+      end
+
+      def add(a, b)
+        a.each_index.map { |i| a[i] + b[i] }
+      end
+
+      def dot(a, b)
+        sum = 0.0
+        a.each_index { |i| sum += a[i] * b[i] }
+        sum
+      end
+
+      def matmul(mat, weights)
+        mat.map do |row|
+          weights.transpose.map { |w| dot(row, w) }
+        end
+      end
+
+      def softmax(vec)
+        m = vec.max
+        exps = vec.map { |v| Math.exp(v - m) }
+        sum = exps.inject(:+)
+        exps.map { |e| e / sum }
+      end
+
+      def multi_head_attention(q_in, k_in = nil, v_in = nil, mask = nil)
+        k_in ||= q_in
+        v_in ||= k_in
+        hd = head_dim
+        heads_out = @heads.map do |h|
+          q = matmul(q_in, h[:q])
+          k = matmul(k_in, h[:k])
+          v = matmul(v_in, h[:v])
+          scores = matmul(q, k.transpose)
+          scale = Math.sqrt(hd.to_f)
+          scores.each_index do |i|
+            scores[i].each_index do |j|
+              scores[i][j] /= scale
+              scores[i][j] = -1e9 if mask && !mask[i][j]
+            end
+          end
+          scores.map! { |row| softmax(row) }
+          matmul(scores, v)
+        end
+        concat = Array.new(q_in.length) { [] }
+        heads_out.each do |head|
+          head.each_index do |i|
+            concat[i].concat(head[i])
+          end
+        end
+        matmul(concat, @wo)
+      end
+
+      def relu(x)
+        x.positive? ? x : 0
+      end
+
+      def affine(mat, weights, bias)
+        mat.map do |row|
+          weights.transpose.map.with_index { |w, j| dot(row, w) + bias[j] }
+        end
+      end
+
+      def feed_forward(x)
+        h = affine(x, @w1, @b1)
+        h.map! { |row| row.map { |v| relu(v) } }
+        affine(h, @w2, @b2)
+      end
+    end
+  end
+end

data/lib/ai4r/neural_network/weight_initializations.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Author::    Sergio Fierens
+# License::   MPL 1.1
+# Project::   ai4r
+# Url::       https://github.com/SergioFierens/ai4r
+#
+# You can redistribute it and/or modify it under the terms of
+# the Mozilla Public License version 1.1  as published by the
+# Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
+
+module Ai4r
+  module NeuralNetwork
+    # Collection of common weight initialization strategies.
+    module WeightInitializations
+      # Uniform distribution in [-1, 1)
+      def uniform
+        ->(_n, _i, _j) { (rand * 2) - 1 }
+      end
+
+      # Xavier/Glorot initialization based on layer dimensions
+      def xavier(structure)
+        lambda do |layer, _i, _j|
+          limit = Math.sqrt(6.0 / (structure[layer] + structure[layer + 1]))
+          (rand * 2 * limit) - limit
+        end
+      end
+
+      # He initialization suitable for ReLU activations
+      def he(structure)
+        lambda do |layer, _i, _j|
+          limit = Math.sqrt(6.0 / structure[layer])
+          (rand * 2 * limit) - limit
+        end
+      end
+
+      module_function :uniform, :xavier, :he
+    end
+  end
+end

data/lib/ai4r/reinforcement/policy_iteration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Classical policy iteration for finite MDPs.
+
+require_relative '../data/parameterizable'
+
+module Ai4r
+  module Reinforcement
+    # Compute an optimal policy for a known MDP.
+    class PolicyIteration
+      include Ai4r::Data::Parameterizable
+
+      parameters_info discount: 'Discount factor'
+
+      def initialize
+        @discount = 0.9
+      end
+
+      # Perform policy iteration.
+      # states:: Array of states
+      # actions:: Array of actions
+      # transition:: Hash[state][action] => {next_state => prob}
+      # reward:: Hash[state][action] => reward
+      def policy_iteration(states, actions, transition, reward)
+        policy = {}
+        states.each { |s| policy[s] = actions.first }
+        values = Hash.new(0.0)
+
+        loop do
+          # Policy evaluation
+          delta = Float::INFINITY
+          while delta > 1e-6
+            delta = 0.0
+            states.each do |s|
+              v = values[s]
+              a = policy[s]
+              new_v = reward[s][a] +
+                      @discount * transition[s][a].sum { |s2, p| p * values[s2] }
+              values[s] = new_v
+              diff = (v - new_v).abs
+              delta = diff if diff > delta
+            end
+          end
+
+          # Policy improvement
+          stable = true
+          states.each do |s|
+            old = policy[s]
+            best = actions.max_by do |a|
+              reward[s][a] +
+                @discount * transition[s][a].sum { |s2, p| p * values[s2] }
+            end
+            policy[s] = best
+            stable = false if best != old
+          end
+          break if stable
+        end
+        policy
+      end
+    end
+  end
+end

data/lib/ai4r/reinforcement/q_learning.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Basic tabular Q-learning implementation.
+
+require_relative '../data/parameterizable'
+
+module Ai4r
+  module Reinforcement
+    # Simple Q-learning agent storing Q-values in a Hash.
+    class QLearning
+      include Ai4r::Data::Parameterizable
+
+      parameters_info learning_rate: 'Update step size',
+                      discount: 'Discount factor',
+                      exploration: 'Exploration rate'
+
+      def initialize
+        @learning_rate = 0.1
+        @discount = 0.9
+        @exploration = 0.1
+        @q = Hash.new { |h, k| h[k] = Hash.new(0.0) }
+      end
+
+      # Update Q(s,a) from an observed transition.
+      def update(state, action, reward, next_state)
+        best_next = @q[next_state].values.max || 0.0
+        @q[state][action] += @learning_rate * (
+          reward + @discount * best_next - @q[state][action]
+        )
+      end
+
+      # Choose an action using an ε-greedy strategy.
+      def choose_action(state)
+        return nil if @q[state].empty?
+
+        if rand < @exploration
+          @q[state].keys.sample
+        else
+          @q[state].max_by { |_, v| v }.first
+        end
+      end
+
+      # Direct access to learned Q-values.
+      attr_reader :q
+    end
+  end
+end