brain 0.0.2

data/History.txt

@@ -0,0 +1,10 @@
+== 0.0.2 2008-07-10
+* Implementation of Hopfield net:
+  * Specs
+  * Code
+  * RDoc
+
+== 0.0.1 2008-06-26
+
+* 1 major enhancement:
+  * Initial release

data/README.txt

@@ -0,0 +1,53 @@
+= brain
+
+* http://brain.rubyforge.org
+* http://github.com/brainopia/brain
+
+== DESCRIPTION:
+
+Implements several types of Neural Networks such as multilayer perceptron (data classification), Kohonen net (data clusterization), Hopfield net (data association).
+
+== FEATURES:
+
+Currently supports:
+* Hopfield net
+
+== SYNOPSIS:
+
+Basic examples:
+  
+* Hopfield net
+    
+    sample = Brain::Hopfield[[-1, -1, -1, -1], [1, 1, 1, 1]].associate [1, 1, -1, 1]
+    sample.run until sample.associated?
+    sample.current # => [1, 1, 1, 1]
+  
+
+== INSTALL:
+
+  sudo gem install brain
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Ravil Bayramgalin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/brain.rb

@@ -0,0 +1,18 @@
+=begin rdoc
+  Defines Brain module.
+=end
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'mathn'
+
+=begin rdoc
+  Contains neural network classes: Brain::Hopfield, Brain::Kohonen and Brain::Perceptron.
+  
+  Classes are autoloaded with the first invoking.
+=end
+
+module Brain
+  autoload 'Hopfield', 'brain/hopfield'
+end

data/lib/brain/hopfield.rb

@@ -0,0 +1,75 @@
+=begin rdoc
+  Defines Brain::Hopfield class.
+=end
+
+=begin rdoc
+  Represents a Hopfield net.
+    
+    net = Brain::Hopfield[[-1, -1, -1, -1], [1, 1, 1, 1]]
+    sample = net.associate [1, 1, -1, 1]
+    sample.run until sample.associated?
+    sample.current # => [1, 1, 1, 1]
+    sample.iterations # => 2
+    
+  In this example, it can take up to 4 iterations to associate the sample (actual value depends on a random order of updating neurons).
+=end
+class Brain::Hopfield
+  require 'brain/hopfield/sample'
+  
+  # Shortcut for creation of a new Hopfield object.
+  def self.[](*learning_samples)
+    new learning_samples
+  end
+  
+  # Learning samples must be not empty and have same dimension.
+  def initialize(learning_samples)
+    @learning_samples = learning_samples
+    learning_samples_must_be_not_empty!
+    
+    @dimension = @learning_samples.first.size
+    learning_samples_must_have_same_dimension!
+    
+    calculate_weight_matrix
+  end
+  
+  # Returns a Brain::Hopfield::Sample object which can be used for an association of given sample.
+  def associate(sample)
+    Sample.new self, sample
+  end
+  
+  # Learning samples attribute.
+  def learning_samples
+    @learning_samples
+  end
+
+  # Weights attribute.
+  def weights
+    @weights
+  end
+  
+  # Dimension attribute.
+  def dimension
+    @dimension
+  end
+  
+  protected
+  
+  def learning_samples_must_be_not_empty!
+    raise ArgumentError if learning_samples.empty?
+  end
+  
+  def learning_samples_must_have_same_dimension!
+    raise ArgumentError unless learning_samples.all? {|sample| sample.size == dimension }
+  end
+  
+  def calculate_weight_matrix
+    @weights = Matrix.zero(dimension)
+    
+    learning_samples.each do |sample|
+      vector = Matrix.row_vector sample
+      @weights += vector.transpose * vector
+    end
+    
+    @weights = Matrix[*@weights.to_a.each_with_index {|row, i| row[i] = 0 }]
+  end
+end

data/lib/brain/hopfield/sample.rb

@@ -0,0 +1,107 @@
+=begin rdoc
+  Defines Brain::Hopfield::Sample class.
+=end
+
+=begin rdoc
+  Uses a given Hopfield object for a successive accosiation with a given sample.
+
+  When there is too much noise in the initial sample, it can associate it with an inverse version of a learning sample. Example:
+ 
+    net = Brain::Hopfield[[1, 1, 1, 1]]
+    sample = net.associate [1, -1, -1, -1]
+    sample.run until sample.associated?
+    sample.current # => [-1, -1, -1, -1]
+ 
+  Initial sample [1, -1, -1, -1] containes too much noise to be comparable with [1, 1, 1, 1]. So sample is associated with the inverse version of [1, 1, 1, 1] which equals [-1, -1, -1, -1].
+=end
+class Brain::Hopfield::Sample
+    
+  # A sample must have same dimension as a Hopfield object.
+  def initialize(net, sample)
+    @net, @initial, @indexes = net, sample, []
+    @current, @iterations, @associated = initial, 0, false
+    
+    sample_must_have_same_dimension_as_net!
+    @associated = true if known_sample?
+  end
+  
+  # Returns true if the current sample is accosiated.
+  def associated?
+    @associated
+  end
+  
+  # Used to update a state of the current sample in a random order. A number of updated positions is controlled with a given parameter.  
+  def run(number = 1)
+    number.times do
+      break if associated?
+      update_next_neuron
+      @associated = true if minimal_energy? or known_sample?
+    end
+    current
+  end
+  
+  # Measure of closerness to learning samples. The least energy state corresponds to an association with a learning sample.
+  def energy
+    (Matrix.row_vector(current) * net.weights).row(0).inner_product current
+  end
+  
+  # A corresponding Hopfield object.
+  def net
+    @net
+  end
+  
+  # Initial state of sample.
+  def initial
+    @initial
+  end
+  
+  # Current state of sample.
+  def current
+    @current
+  end
+  
+  # Number of itererations.
+  def iterations
+    @iterations
+  end
+  
+  protected
+    
+  def sample_must_have_same_dimension_as_net!
+    raise ArgumentError unless current.size == net.dimension
+  end
+  
+  def known_sample?
+    net.learning_samples.any? {|sample| sample == current }
+  end
+  
+  def minimal_energy?
+    @energy_changed = true unless @previous_energy == energy
+    if @indexes.empty?
+      @energy_changed ? (@energy_changed = false) : true
+    end
+  end
+  
+  def activation_argument(neuron_index)
+    net.weights.row(neuron_index).inner_product current
+  end
+  
+  def activation_function(neuron_index)
+    activation = activation_argument neuron_index
+    return  1 if activation > 0
+    return -1 if activation < 0
+    current[neuron_index]
+  end
+  
+  def next_neuron
+    @indexes = Array.new(net.dimension) {|i| i } if @indexes.empty?
+    @indexes.delete_at rand(@indexes.size)
+  end
+  
+  def update_next_neuron
+    @previous_energy = energy
+    neuron_index = next_neuron
+    current[neuron_index] = activation_function neuron_index
+    @iterations += 1
+  end
+end

data/lib/brain/version.rb

@@ -0,0 +1,9 @@
+module Brain
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 2
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/spec/brain/hopfield/sample_spec.rb

@@ -0,0 +1,87 @@
+require File.dirname(__FILE__) + '/../../spec_helper'
+
+describe Brain::Hopfield::Sample do
+  it "should be initialized with a Hopfield net and a sample" do    
+    lambda { Hopfield::Sample.new Hopfield[ [1, 1, 1] ], [-1, 1, -1] }.
+        should_not raise_error(ArgumentError)
+  end
+
+  it "should raise error if the sample has a different arity then the net" do
+    lambda { Hopfield::Sample.new Hopfield[ [1, 1, 1] ], [-1, 1, -1, 1] }.
+        should raise_error(ArgumentError)    
+  end
+  
+  it "should check if the sample belongs to learning samples" do
+    sample = Hopfield::Sample.new(Hopfield[ [1, 1, 1] ], [1, 1, 1])
+    sample.associated?.should == true
+  end
+
+  describe '(after initialization)' do
+    before(:each) do
+      @learned_sample = [1, -1, 1, -1, 1, -1, 1, -1, 1, -1]
+      @tested_sample = [-1, -1, -1, -1, -1, -1, 1, 1, 1, -1]
+      
+      @net = Hopfield[ @learned_sample ]
+      @sample = Hopfield::Sample.new @net, @tested_sample
+    end
+    
+    it "should start an iterations count with 0" do
+      @sample.iterations.should == 0
+    end
+    
+    it "should return a status of training" do
+      @sample.associated?.should == false
+    end
+    
+    it "should return a current associated sample" do
+      @sample.current.should == @tested_sample
+    end
+    
+    it "should return an initial sample" do
+      @sample.initial.should == @tested_sample
+    end
+    
+    it "should be ran a given number of times" do
+      @sample.run(50).should == @learned_sample
+    end
+    
+    it "should increment iterations after an every run" do
+      @sample.stub!(:associated?).and_return(false)
+      3.times { @sample.run(3) }
+      @sample.iterations.should == 9
+    end
+    
+    it "should stop incrementing iterations after it's associated" do
+      @sample.stub!(:associated?).and_return(false)
+      @sample.run(4)
+      @sample.stub!(:associated?).and_return(true)
+      @sample.run(4)
+      @sample.iterations.should == 4
+    end
+    
+    it "should be ran by default one time" do
+      @sample.run
+      @sample.iterations.should == 1
+    end
+    
+    it "should return an using net" do
+      @sample.net.should == @net
+    end
+    
+    it "shouldn't increase energy" do
+      previous_energy = @sample.energy
+      until @sample.associated?
+        @sample.run
+        previous_energy.should_not > @sample.energy
+        previous_energy = @sample.energy
+      end
+    end
+    
+    it "should return an inverse version of the learning sample if there is too much noise in the initial sample" do
+      net = Brain::Hopfield[[1, 1, 1, 1]]
+      sample = net.associate [1, -1, -1, -1]
+      sample.run until sample.associated?
+      sample.current.should == [-1, -1, -1, -1]
+    end    
+  end
+end

data/spec/brain/hopfield_spec.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe Brain::Hopfield do
+  it "should be created with learning samples" do
+    lambda { Hopfield.new }.should raise_error(ArgumentError)
+    lambda { Hopfield.new [] }.should raise_error(ArgumentError)
+    lambda { Hopfield.new [[1, 1], [1, 1]] }.should_not raise_error 
+  end
+  
+  it "learning samples should have a same arity" do
+    lambda { Hopfield.new [[-1, -1], [1]] }.should raise_error(ArgumentError)
+    lambda { Hopfield.new [[-1, -1], [1, 1]] }.should_not raise_error
+  end
+  
+  it "should have a shortcut [] for creation" do
+    Hopfield[[1, 1], [1, 1]].should be_instance_of(Hopfield)
+  end
+  
+  describe '(after initialization)' do
+    before(:each) do
+      @net = Hopfield[ [-1, 1, -1], [1, -1, 1] ]
+    end
+
+    it "should return a weight matrix" do
+      @net.weights.should == Matrix[ [ 0, -2,  2],
+                                     [-2,  0, -2],
+                                     [ 2, -2,  0] ]
+    end
+    
+    it "should return an array of learning samples" do
+      @net.learning_samples.should == [ [-1, 1, -1], [1, -1, 1] ]
+    end
+    
+    it "should return an arity" do
+      @net.dimension.should == 3
+    end
+    
+    it "should create an object for an association with a given sample" do
+      associated_sample = @net.associate([1, 1, 1])
+      associated_sample.should be_instance_of(Hopfield::Sample)
+    end    
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--colour

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  gem 'rspec'
+  require 'spec'
+end
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require 'brain'
+include Brain

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: brain
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Ravil Bayramgalin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-07-12 00:00:00 +04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.0
+    version: 
+description: Implementation of fundamental types of neural networks which includes multilayer perceptron, Kohonen net and Hopfield net.
+email: 
+- ravwar@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.txt
+files: 
+- History.txt
+- README.txt
+- lib/brain.rb
+- lib/brain/hopfield.rb
+- lib/brain/hopfield/sample.rb
+- lib/brain/version.rb
+- spec/brain/hopfield/sample_spec.rb
+- spec/brain/hopfield_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://brain.rubyforge.org
+post_install_message: |-
+  
+  For more information on brain, see http://brain.rubyforge.org
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: brain
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Implementation of fundamental types of neural networks which includes multilayer perceptron, Kohonen net and Hopfield net.
+test_files: 
+- spec/brain/hopfield/sample_spec.rb
+- spec/brain/hopfield_spec.rb