ai4r 1.13 → 2.0

data/lib/ai4r/search/a_star.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Generic A* search algorithm.
+
+require 'set'
+
+module Ai4r
+  module Search
+    # Generic A* search implementation operating on arbitrary graph
+    # representations.
+    #
+    # Initialize with start node, a goal predicate, a neighbor function and a
+    # heuristic.
+    #
+    # The neighbor function must return a hash mapping neighbor nodes to edge
+    # costs. The heuristic receives a node and returns the estimated remaining
+    # cost to reach the goal.
+    class AStar
+      # @param start [Object] initial node
+      # @param goal_test [Proc] predicate returning true when node is goal
+      # @param neighbor_fn [Proc] -> node { neighbor => cost, ... }
+      # @param heuristic_fn [Proc] -> node => estimated remaining cost
+      def initialize(start, goal_test, neighbor_fn, heuristic_fn)
+        @start = start
+        @goal_test = goal_test
+        @neighbor_fn = neighbor_fn
+        @heuristic_fn = heuristic_fn
+      end
+
+      # Execute the search and return the path as an array of nodes or nil
+      # if the goal cannot be reached.
+      def search
+        open_set = [@start]
+        came_from = {}
+        g = { @start => 0 }
+        f = { @start => @heuristic_fn.call(@start) }
+        closed = Set.new
+
+        until open_set.empty?
+          current = open_set.min_by { |n| f[n] }
+          return reconstruct_path(came_from, current) if @goal_test.call(current)
+
+          open_set.delete(current)
+          closed << current
+          @neighbor_fn.call(current).each do |neighbor, cost|
+            next if closed.include?(neighbor)
+
+            tentative_g = g[current] + cost
+            next unless g[neighbor].nil? || tentative_g < g[neighbor]
+
+            came_from[neighbor] = current
+            g[neighbor] = tentative_g
+            f[neighbor] = tentative_g + @heuristic_fn.call(neighbor)
+            open_set << neighbor unless open_set.include?(neighbor)
+          end
+        end
+        nil
+      end
+
+      private
+
+      def reconstruct_path(came_from, node)
+        path = [node]
+        while came_from.key?(node)
+          node = came_from[node]
+          path.unshift(node)
+        end
+        path
+      end
+    end
+  end
+end

data/lib/ai4r/search/bfs.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Basic breadth-first search implementation.
+
+module Ai4r
+  module Search
+    # Explore nodes in breadth-first order until a goal is found.
+    class BFS
+      # Create a new BFS searcher.
+      #
+      # goal_test::  lambda returning true for a goal node
+      # neighbor_fn:: lambda returning adjacent nodes for a given node
+      # start::       optional starting node
+      def initialize(goal_test, neighbor_fn, start = nil)
+        @goal_test = goal_test
+        @neighbor_fn = neighbor_fn
+        @start = start
+      end
+
+      # Find a path from the start node to a goal.
+      #
+      # start:: initial node if not provided on initialization
+      #
+      # Returns an array of nodes representing the path, or nil if no goal was found.
+      def search(start = nil)
+        start ||= @start
+        raise ArgumentError, 'start node required' unless start
+
+        queue = [[start, [start]]]
+        visited = { start => true }
+        until queue.empty?
+          node, path = queue.shift
+          return path if @goal_test.call(node)
+
+          @neighbor_fn.call(node).each do |n|
+            next if visited[n]
+
+            visited[n] = true
+            queue << [n, path + [n]]
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/ai4r/search/dfs.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Basic depth-first search implementation.
+
+module Ai4r
+  module Search
+    # Explore nodes in depth-first order until a goal is found.
+    class DFS
+      # Create a new DFS searcher.
+      #
+      # goal_test::  lambda returning true for a goal node
+      # neighbor_fn:: lambda returning adjacent nodes for a given node
+      # start::       optional starting node
+      def initialize(goal_test, neighbor_fn, start = nil)
+        @goal_test = goal_test
+        @neighbor_fn = neighbor_fn
+        @start = start
+      end
+
+      # Find a path from the start node to a goal.
+      #
+      # start:: initial node if not provided on initialization
+      #
+      # Returns an array of nodes representing the path, or nil if no goal was found.
+      def search(start = nil)
+        start ||= @start
+        raise ArgumentError, 'start node required' unless start
+
+        stack = [[start, [start]]]
+        visited = { start => true }
+        until stack.empty?
+          node, path = stack.pop
+          return path if @goal_test.call(node)
+
+          @neighbor_fn.call(node).each do |n|
+            next if visited[n]
+
+            visited[n] = true
+            stack << [n, path + [n]]
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/ai4r/search/mcts.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Author::    OpenAI Assistant
+# License::   MPL 1.1
+# Project::   ai4r
+#
+# Minimal Monte Carlo Tree Search implementation.
+
+require_relative '../data/parameterizable'
+
+module Ai4r
+  module Search
+    # Basic UCT-style Monte Carlo Tree Search.
+    #
+    # This generic implementation expects four callbacks:
+    # - +actions_fn.call(state)+ returns available actions for a state.
+    # - +transition_fn.call(state, action)+ computes the next state.
+    # - +terminal_fn.call(state)+ returns true if the state has no children.
+    # - +reward_fn.call(state)+ yields a numeric payoff for terminal states.
+    #
+    # Example:
+    #   env = {
+    #     actions_fn: ->(s) { s == :root ? %i[a b] : [] },
+    #     transition_fn: ->(s, a) { a == :a ? :win : :lose },
+    #     terminal_fn: ->(s) { %i[win lose].include?(s) },
+    #     reward_fn: ->(s) { s == :win ? 1.0 : 0.0 }
+    #   }
+    #   mcts = Ai4r::Search::MCTS.new(**env)
+    #   best = mcts.search(:root, 50)
+    #   # => :a
+    class MCTS
+      include Ai4r::Data::Parameterizable
+
+      Node = Struct.new(:state, :parent, :action, :children, :visits, :value) do
+        def initialize(state, parent = nil, action = nil)
+          super(state, parent, action, [], 0, 0.0)
+        end
+      end
+
+      parameters_info exploration: 'UCT exploration constant'
+
+      # Create a new search object.
+      #
+      # actions_fn::     returns available actions for a state
+      # transition_fn::  computes the next state given a state and action
+      # terminal_fn::    predicate to detect terminal states
+      # reward_fn::      numeric payoff for terminal states
+      def initialize(actions_fn:, transition_fn:, terminal_fn:, reward_fn:,
+                     exploration: Math.sqrt(2))
+        @actions_fn = actions_fn
+        @transition_fn = transition_fn
+        @terminal_fn = terminal_fn
+        @reward_fn = reward_fn
+        @exploration = exploration
+      end
+
+      # Run MCTS starting from +root_state+ for a number of +iterations+.
+      # Returns the action considered best from the root.
+      def search(root_state, iterations)
+        root = Node.new(root_state)
+        iterations.times do
+          node = tree_policy(root)
+          reward = default_policy(node.state)
+          backup(node, reward)
+        end
+        best_child(root, 0)&.action
+      end
+
+      private
+
+      def tree_policy(node)
+        until @terminal_fn.call(node.state)
+          actions = @actions_fn.call(node.state)
+          return expand(node, actions) if node.children.length < actions.length
+
+          node = best_child(node, @exploration)
+
+        end
+        node
+      end
+
+      def expand(node, actions)
+        tried = node.children.map(&:action)
+        untried = actions - tried
+        action = untried.sample
+        state = @transition_fn.call(node.state, action)
+        child = Node.new(state, node, action)
+        node.children << child
+        child
+      end
+
+      def best_child(node, c)
+        node.children.max_by do |child|
+          exploitation = child.value / (child.visits.nonzero? || 1)
+          exploration = c * Math.sqrt(Math.log(node.visits + 1) / (child.visits.nonzero? || 1))
+          exploitation + exploration
+        end
+      end
+
+      def default_policy(state)
+        current = state
+        until @terminal_fn.call(current)
+          action = @actions_fn.call(current).sample
+          current = @transition_fn.call(current, action)
+        end
+        @reward_fn.call(current)
+      end
+
+      def backup(node, reward)
+        while node
+          node.visits += 1
+          node.value += reward
+          node = node.parent
+        end
+      end
+    end
+  end
+end

data/lib/ai4r/search.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'search/a_star'
+require_relative 'search/bfs'
+require_relative 'search/dfs'
+require_relative 'search/mcts'
+
+module Ai4r
+  # Namespace for search algorithms like A*.
+  module Search
+  end
+end

data/lib/ai4r/som/distance_metrics.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ai4r
+  module Som
+    # Helper module with distance metrics for node coordinates
+    module DistanceMetrics
+      # @param dx [Object]
+      # @param dy [Object]
+      # @return [Object]
+      def self.chebyshev(dx, dy)
+        [dx.abs, dy.abs].max
+      end
+
+      # @param dx [Object]
+      # @param dy [Object]
+      # @return [Object]
+      def self.euclidean(dx, dy)
+        Math.sqrt((dx**2) + (dy**2))
+      end
+
+      # @param dx [Object]
+      # @param dy [Object]
+      # @return [Object]
+      def self.manhattan(dx, dy)
+        dx.abs + dy.abs
+      end
+    end
+  end
+end

data/lib/ai4r/som/layer.rb

@@ -1,18 +1,18 @@
+# frozen_string_literal: true
+
 # Author::    Thomas Kern
 # 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
 # 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 Som
-
     # responsible for the implementation of the algorithm's decays
     # currently has methods for the decay of the radius, influence and learning rate.
     # Has only one phase, which ends after the number of epochs is passed by the Som-class.
@@ -24,16 +24,22 @@ module Ai4r
     # * epochs => number of epochs the algorithm runs, has to be an integer. By default it is set to 100
     # * learning_rate => sets the initial learning rate
     class Layer
-
       include Ai4r::Data::Parameterizable
 
-      parameters_info :nodes => "number of nodes, has to be equal to the som",
-                      :epochs => "number of epochs the algorithm has to run",
-                      :radius => "sets the initial neighborhoud radius"
+      parameters_info nodes: 'number of nodes, has to be equal to the som',
+                      epochs: 'number of epochs the algorithm has to run',
+                      radius: 'sets the initial neighborhoud radius',
+                      distance_metric: 'metric used to compute node distance'
+
+      # @param nodes [Object]
+      # @param radius [Object]
+      # @param epochs [Object]
+      # @param learning_rate [Object]
+      # @param options [Object]
+      # @return [Object]
+      def initialize(nodes, radius, epochs = 100, learning_rate = 0.7, options = {})
+        raise('Too few nodes') if nodes < 3
 
-      def initialize(nodes, radius, epochs = 100, learning_rate = 0.7)
-        raise("Too few nodes") if nodes < 3
-        
         @nodes = nodes
         @epochs = epochs
         @radius = radius
@@ -41,28 +47,33 @@ module Ai4r
         @time_for_epoch = @epochs + 1.0 if @time_for_epoch < @epochs
 
         @initial_learning_rate = learning_rate
+        @distance_metric = options[:distance_metric] || :chebyshev
       end
 
       # calculates the influnce decay for a certain distance and the current radius
       # of the epoch
+      # @param distance [Object]
+      # @param radius [Object]
+      # @return [Object]
       def influence_decay(distance, radius)
-        Math.exp(- (distance.to_f**2 / 2.0 / radius.to_f**2))
+        Math.exp(- ((distance.to_f**2) / 2.0 / (radius.to_f**2)))
       end
 
       # calculates the radius decay for the current epoch. Uses @time_for_epoch
       # which has to be higher than the number  of epochs, otherwise the decay will be - Infinity
+      # @param epoch [Object]
+      # @return [Object]
       def radius_decay(epoch)
-        (@radius * ( 1 - epoch/ @time_for_epoch)).round
+        (@radius * (1 - (epoch / @time_for_epoch))).round
       end
 
       # calculates the learning rate decay. uses @time_for_epoch again and same rule applies:
       # @time_for_epoch has to be higher than the number  of epochs, otherwise the decay will be - Infinity
+      # @param epoch [Object]
+      # @return [Object]
       def learning_rate_decay(epoch)
-        @initial_learning_rate * ( 1 - epoch / @time_for_epoch)
+        @initial_learning_rate * (1 - (epoch / @time_for_epoch))
       end
-
     end
-
   end
-
 end

data/lib/ai4r/som/node.rb

@@ -1,19 +1,20 @@
+# frozen_string_literal: true
+
 # Author::    Thomas Kern
 # 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
 # Mozilla Foundation at http://www.mozilla.org/MPL/MPL-1.1.txt
 
-require File.dirname(__FILE__) + '/../data/parameterizable'
-require File.dirname(__FILE__) + '/layer'
+require_relative '../data/parameterizable'
+require_relative 'layer'
+require_relative 'distance_metrics'
 
 module Ai4r
-
   module Som
-
     # this class is used for the individual node and will be (nodes * nodes)-time instantiated
     #
     # = attributes
@@ -24,37 +25,67 @@ module Ai4r
     # * weights => values of the current weights are stored in an array of dimension 'dimensions'.
     # Weights are of type float
     # * instantiated_weight => the values of the first instantiation of weights. these values are
-    # never changed 
+    # never changed
 
+    # Represents a node in the self-organizing map grid.
     class Node
-
       include Ai4r::Data::Parameterizable
 
-      parameters_info :weights => "holds the current weight",
-                      :instantiated_weight => "holds the very first weight",
-                      :x => "holds the row ID of the unit in the map",
-                      :y => "holds the column ID of the unit in the map",
-                      :id => "id of the node"      
+      parameters_info weights: 'holds the current weight',
+                      instantiated_weight: 'holds the very first weight',
+                      x: 'holds the row ID of the unit in the map',
+                      y: 'holds the column ID of the unit in the map',
+                      id: 'id of the node',
+                      distance_metric: 'metric used to compute node distance'
 
       # creates an instance of Node and instantiates the weights
-      # the parameters is a uniq and sequential ID as well as the number of total nodes
-      # dimensions signals the dimension of the input vector
-      def self.create(id, total, dimensions)
+      #
+      # +id+:: unique identifier for this node
+      # +rows+:: number of rows of the SOM grid
+      # +columns+:: number of columns of the SOM grid
+      # +dimensions+:: dimension of the input vector
+      # @param id [Object]
+      # @param rows [Object]
+      # @param columns [Object]
+      # @param dimensions [Object]
+      # @param options [Object]
+      # @option options [Range] :range (0..1) range used to initialize weights
+      # @option options [Integer] :random_seed Seed for Ruby's RNG. The
+      #   deprecated :seed key is supported for backward compatibility.
+      # @return [Object]
+      def self.create(id, _rows, columns, dimensions, options = {})
         n = Node.new
         n.id = id
-        n.instantiate_weight dimensions
-        n.x = id % total
-        n.y = (id / total.to_f).to_i
+        n.distance_metric = options[:distance_metric] || :chebyshev
+        n.instantiate_weight dimensions, options
+        n.x = id % columns
+        n.y = (id / columns.to_f).to_i
         n
       end
 
       # instantiates the weights to the dimension (of the input vector)
       # for backup reasons, the instantiated weight is stored into @instantiated_weight  as well
-      def instantiate_weight(dimensions)
+      # @param dimensions [Object]
+      # @param options [Object]
+      # @option options [Range] :range (0..1) range used to initialize weights
+      # @option options [Integer] :random_seed Seed for Ruby's RNG. The
+      #   deprecated :seed key is supported for backward compatibility.
+      # @return [Object]
+      def instantiate_weight(dimensions, options = {})
+        opts = { range: 0..1, random_seed: nil, seed: nil, rng: nil }.merge(options)
+        rng = opts[:rng]
+        unless rng
+          seed = opts[:random_seed] || opts[:seed]
+          rng = seed.nil? ? Random.new : Random.new(seed)
+        end
+        range = opts[:range] || (0..1)
+        min = range.first.to_f
+        max = range.last.to_f
+        span = max - min
         @weights = Array.new dimensions
         @instantiated_weight = Array.new dimensions
-        @weights.each_with_index do |weight, index|
-          @weights[index] = rand
+        @weights.each_index do |index|
+          @weights[index] = min + (rng.rand * span)
           @instantiated_weight[index] = @weights[index]
         end
       end
@@ -62,10 +93,12 @@ module Ai4r
       # returns the square distance between the current weights and the input
       # the input is a vector/array of the same size as weights
       # at the end, the square root is extracted from the sum of differences
+      # @param input [Object]
+      # @return [Object]
       def distance_to_input(input)
         dist = 0
         input.each_with_index do |i, index|
-          dist += (i - @weights[index]) ** 2
+          dist += (i - @weights[index])**2
         end
 
         Math.sqrt(dist)
@@ -79,18 +112,14 @@ module Ai4r
       # 2 1 1 1 2
       # 2 2 2 2 2
       # 0 being the current node
+      # @param node [Object]
+      # @return [Object]
       def distance_to_node(node)
-        max((self.x - node.x).abs, (self.y - node.y).abs)
+        dx = x - node.x
+        dy = y - node.y
+        metric = @distance_metric || :chebyshev
+        DistanceMetrics.send(metric, dx, dy)
       end
-
-      private
-
-      def max(a, b)
-        a > b ? a : b
-      end
-
     end
-
   end
-
 end