hopfield 1.0 → 1.1

data/README.md

@@ -1,30 +1,34 @@
 # Hopfield Network in Ruby
 
+A pure, albeit slow Ruby implementation of a Hopfield Network.
+
 ## What is it?
 [Hopfield Networks](http://en.wikipedia.org/wiki/Hopfield_network) model the way humans recall memories, or more specific, how neurons recall the pattern. This means you first train the network with a set of known patterns and then pass an unknown or perturbed version of the pattern. The neurons will restore the missing information to create an exact match. 
 
 The patterns can be passed using multi dimensional array of either 0 and 1 or -1 and 1. An artifical neural network will learn the patterns. Now let's move on to an example.
 
+```ruby
+gem 'hopfield'
+```
+
 ## How do I use it?
 ```ruby
 training = Hopfield::Training.new([pattern1, pattern2])
 network = Hopfield::Network.new(training, perturbed_pattern)
+
+# Propagate until match
+network.propagate until network.associated?
+
 network.pattern # the matched pattern
 network.runs # how many propagations it took
 ```
 
-## Example with images
-See examples/image.rb for a memory association of Charlie Sheen, with a cat hiding him.
-```
-$ cd examples
-$ ruby image.rb
-Image 1 is now in an array of [20x20]
-Image 2 is now in an array of [20x20]
-Hopfield neurons are trained!
-Neurons propagated: 1776
-Errors: [0]
-```
-The script also creates black and white pattern images for you.
+## TODO
+- Make this a C extension to boost performance
+- Turn the random picking of neurons into pseudo randomness to prevent the same neuron to be propagated over and over again
+- Implement the Storkey learning rule to provide an alternative for the already implemented Hebbian learning rule.
+- Release the examples
+
 
-## Credits
+## Thanks to
 I was introduced to Hopfield networks through the book [Clever Algorithms](www.cleveralgorithms.com), and I've borrowed bits of the implementation shown in the book. Also used the `.associated?` syntax found here: [Brain](https://github.com/brainopia/brain).

data/lib/hopfield.rb

@@ -1,3 +1,5 @@
+require 'matrix'
+
 require_relative 'hopfield/neuron'
 require_relative 'hopfield/training'
 require_relative 'hopfield/network'

data/lib/hopfield/network.rb

@@ -1,24 +1,27 @@
 module Hopfield
   class Network
-    attr_accessor :neurons, :patterns, :state, :pattern_width, :vector, :last_error, :runs
+    attr_accessor :neurons, :patterns, :weights, :state, :pattern_dimensions, :last_error, :runs
     
     def initialize(training, perturbed_pattern)
       unless training.class.to_s == 'Hopfield::Training'
         raise TypeError, 'Training has to be an instance of Hopfield::Training'
       end
       
-      unless training.patterns.first.size == perturbed_pattern.size
+      unless training.patterns.first.size == perturbed_pattern.flatten.size
         raise SyntaxError, 'Given pattern does not match size of the training patterns'
       end
       
       # Turn 0 into -1
-      perturbed_pattern.map {|value| (value == 0 ? -1 : value) }
+      perturbed_pattern = perturbed_pattern.flatten.map { |value| (value == 0 ? -1 : value) }
       
       self.neurons =  training.neurons
       self.patterns = training.patterns
-      self.pattern_width = training.pattern_width
-      self.vector =   perturbed_pattern.flatten
-      self.neurons.each_with_index { |neuron,i| neuron.output = self.vector[i] }
+      self.weights =  training.weights
+      self.pattern_dimensions = training.pattern_dimensions
+      
+      self.neurons.count.times do |i|
+        self.neurons[i].state = perturbed_pattern[i]
+      end
       
       self.last_error = [1]
       self.runs =       0
@@ -32,26 +35,35 @@ module Hopfield
       return self.state
     end
     
+    def get_weight(i , j)
+      ij = [i, j].sort
+      return self.weights[ij.first][ij.last]
+    end
+    
     def propagate
       # Select random neuron
-      i = rand(self.neurons.size)
-      activation = 0
+      i = rand(self.neurons.count)
+      
+      activation = 0.0
+      
       self.neurons.each_with_index do |other, j|
-        activation += other.weights[i]*other.output if i!=j
+        next if i == j
+        activation += get_weight(i, j)*other.state
       end
+      
       output = transfer(activation)
-      change = output != self.neurons[i].output
-      self.neurons[i].output = output
+      change = output != self.neurons[i].state
+      self.neurons[i].state = output
       
       # Compile state of outputs
-      state = Array.new(self.neurons.size){|i| self.neurons[i].output}
-      
+      state = Array.new(self.neurons.count){ |i| self.neurons[i].state }
+
       # Calculate the current error
       self.last_error = calculate_error(state)
-      
+
       # Convert state to binary and back to a multi dimensional array
       state = to_binary(state)
-      state = state.each_slice(self.pattern_width).to_a
+      state = state.each_slice(self.pattern_dimensions[:width]).to_a
       self.state = state
       
       self.runs += 1
@@ -85,7 +97,7 @@ module Hopfield
     end
     
     def to_binary(vector)
-      return Array.new(vector.size){|i| ((vector[i]==-1) ? 0 : 1)}
+      return Array.new(vector.size){|i| ((vector[i] == -1) ? 0 : 1)}
     end
     
   end

data/lib/hopfield/neuron.rb

@@ -1,18 +1,5 @@
 module Hopfield
   class Neuron
-    attr_accessor :weights, :output
-    
-    def initialize(pattern_size)
-      minmax = Array.new(pattern_size) { [-0.5, 0.5] }
-      
-      self.weights =  random_vector(minmax)
-    end
-    
-    def random_vector(minmax)
-      return Array.new(minmax.size) do |i|
-        minmax[i][0] + ((minmax[i][1] - minmax[i][0]) * rand())
-      end
-    end
-    
+    attr_accessor :state
   end
 end

data/lib/hopfield/training.rb

@@ -1,46 +1,68 @@
 module Hopfield
+  
+  # Two learning rules have been implemented, storkey and hebbian
+  # See: http://en.wikipedia.org/wiki/Hopfield_network#Learning_Rules
+  HEBBIAN_RULE = 1
+  STORKEY_RULE = 2
+  
   class Training
-    attr_accessor :patterns, :neurons, :pattern_width
+    attr_accessor :patterns, :neurons, :weights, :pattern_dimensions,  :rule
     
-    def initialize(patterns)
+    def initialize(patterns, rule=Hopfield::HEBBIAN_RULE)
       # Check if patterns are the same size
       unless patterns.map(&:size).uniq.count == 1
-        raise SyntaxError, 'Inconsistent pattern size'
+        raise ArgumentError, 'Inconsistent pattern size'
       end
       
-      # Turn 0 into -1
-      patterns.map { |pattern| pattern.map {|value| (value == 0 ? -1 : value) }}
-      
-      # Set the patterns for this training
-      self.patterns = patterns
-      
       # Calculate the amount of required neurons
       # This number is based on the number of inputs of a pattern
-      connections =  patterns.first.map(&:size).inject{|sum,x| sum + x }
-      self.pattern_width = patterns.first.first.size
+      net_size =  patterns.first.map(&:size).inject{|sum,x| sum + x }
+      
+      self.pattern_dimensions = Hash.new
+      self.pattern_dimensions[:width] =  patterns.first.first.size
+      self.pattern_dimensions[:height] = patterns.first.size
+      
+      # Flatten patterns to 1D array
+      self.patterns = patterns.map { |pattern| pattern.flatten }
+      
+      # Turn 0 into -1
+      self.patterns = self.patterns.map { |pattern| pattern.map { |value| (value == 0 ? -1 : value) }}
       
       # Create neurons
-      self.neurons = Array.new(connections) { Neuron.new connections }
+      self.neurons = Array.new(self.patterns.first.length) { Neuron.new }
+      
+      self.weights = Array.new
       
       # Train the neurons
-      train(connections)
+      train(rule)
     end
     
-    def train(connections)
-      self.neurons.each_with_index do |neuron, i|  
-        for j in ((i+1)...connections) do
-          wij = 0.0
-          self.patterns.each do |pattern|
-            vector = pattern.flatten
-            #puts "Pattern: " + pattern.size.to_s
-            #puts "Pattern Y: " + pattern.first.size.to_s
-            #puts "Vector: " + vector.size.to_s
-            wij += vector[i]*vector[j]
+    def set_weight(neuron_index, other_neuron_index, weight)
+      # Connections are symmetric, so ij is the same as ji, so store it only once
+      ij = [neuron_index, other_neuron_index].sort
+      self.weights[ij.first] = [] if self.weights[ij.first].nil?
+      self.weights[ij.first][ij.last] = weight
+    end
+    
+    def train(rule)
+      # Neurons are fully connected; every neuron has a weight value for every other neuron
+      case rule
+        when Hopfield::HEBBIAN_RULE
+          self.neurons.count.times do |i|
+            for j in ((i+1)...self.neurons.count) do
+              next if i == j
+              weight = 0.0
+              self.patterns.each do |pattern|
+                weight += pattern[i] * pattern[j]
+              end
+              set_weight(i, j, weight / self.patterns.count)
+            end
           end
-          self.neurons[i].weights[j] = wij
-          self.neurons[j].weights[i] = wij
+        when Hopfield::STORKEY_RULE
+          
+        else
+          abort 'Unknown learning rule specified, either use Hopfield::STORKEY_RULE or Hopfield::HEBBIAN_RULE'
         end
-      end
     end
     
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hopfield
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-17 00:00:00.000000000 Z
+date: 2013-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -57,7 +57,7 @@ files:
 - lib/hopfield.rb
 - LICENSE
 - README.md
-homepage: http://github.com/bartolsthoorn/ruby-hopfield
+homepage: http://github.com/bartolsthoorn/hopfield-ruby
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -77,9 +77,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Ruby implementation of a Hopfield Network
 test_files: []
-has_rdoc: