convolver 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0f2badf8733818f128a1c6f1456ae37e114f549
-  data.tar.gz: 81889f084e50d4789ec202082422dd9b24304210
+  metadata.gz: 99ab37662a25bbb5d060946aff94c533e336db14
+  data.tar.gz: 5ef276e831151248a543a6f33adbb3524c82a37f
 SHA512:
-  metadata.gz: 557d6b5738041165a5a22f4ede39d4d0cc7333aa6bfd2937cf3334e16e8daa7c12672ed6377be31003974b90b4a8a942f93fdf812d886202894d46088a2c30a5
-  data.tar.gz: d598375b28278a5ac14619280068cfaeab82fe2d1c4aac9aeae817bb4b4958c913c1fb6674af1b9f4af901f7844621863e2ffd9d4991dc7ca31e7c8e32818c48
+  metadata.gz: c97668640eb1ac262397b20915e2739ec3617d0c13c6e06a70a5e7306f8bcb85553ae7022160dea7e63c2d9a7325e2e45d641f7949de6c694b5a3eff9f73f54b
+  data.tar.gz: a3f26841861e48034835af3ed730c1a0cae33d565287c4197f772bf7a1ee6de59cfe0c91abfb75fd5d9789fe54a83f34769fb0700ff22e96302571f0b5715099

data/README.md

@@ -2,18 +2,14 @@
 
 [![Build Status](https://travis-ci.org/neilslater/convolver.png?branch=master)](http://travis-ci.org/neilslater/convolver)
 
-Adds a convolve operation to NArray floats. It is around 250 times faster than equivalents
-in pure Ruby.
-
-The gem makes convolution via FFTW3 library available. This is faster for convolutions with
-larger kernels and signals. The relationship is complex, but as a rule of thumb, the kernel
-needs to be around 1000 entries or larger before it is worth switching to FFTW3-based convolves.
+Calculates discrete convolution between two multi-dimensional arrays.
+See http://en.wikipedia.org/wiki/Convolution
 
 ## Planned features
 
-The *convolver* gem will eventually contain a basic kit for creating, training and running convolutional
-neural networks. As a side effect of this plan, it will also contain efficient code for
-calculating signal convolutions for other types of analysis.
+The *convolver* gem will eventually contain a basic kit for creating, training and running
+convolutional neural networks. As a side effect of this plan, it currently contains code for
+calculating floating-point convolutions for other types of analysis.
 
 ## Installation
 
@@ -53,12 +49,10 @@ kernel in the same dimension.
  * Convolver expects input a and kernel b to have the same rank, and for the kernel to be same size
 or smaller in all dimensions as the input.
 
-FFTW3 convolution:
-
-    a = NArray[0.3,0.4,0.5]
-    b = NArray[1.3, -0.5]
-    c = Convolver.convolve_fftw3( a, b )
-    => NArray.float(2): [ 0.19, 0.27 ]
+ * Convolver.convolve will try to choose the faster of two approaches it has coded. In general,
+small convolutions are processed directly by multiplying out all combinations and summing them,
+and large convolutions are processed using FFTW3 to convert to frequency space where convolution
+is simpler and faster to calculate, then convert back.
 
 ## Contributing
 

data/convolver.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "yard", ">= 0.8.7.2"
   spec.add_development_dependency "bundler", ">= 1.3"
   spec.add_development_dependency "rspec", ">= 2.13.0"
+  spec.add_development_dependency "mocha", ">= 0.14.0"
   spec.add_development_dependency "rake", ">= 1.9.1"
   spec.add_development_dependency "rake-compiler", ">= 0.8.3"
 

data/ext/convolver/convolver.c

@@ -63,7 +63,7 @@ static VALUE narray_fit_backwards( VALUE self, VALUE a, VALUE b ) {
 }
 
 
-/* @overload convolve( signal, kernel )
+/* @overload convolve_basic( signal, kernel )
  * Calculates convolution of an array of floats representing a signal, with a second array representing
  * a kernel. The two parameters must have the same rank. The output has same rank, its size in each dimension d is given by
  *  signal.shape[d] - kernel.shape[d] + 1
@@ -167,7 +167,7 @@ static VALUE narray_nn_run_single_layer( VALUE self, VALUE inputs, VALUE weights
 
 void Init_convolver() {
   Convolver = rb_define_module( "Convolver" );
-  rb_define_singleton_method( Convolver, "convolve", narray_convolve, 2 );
+  rb_define_singleton_method( Convolver, "convolve_basic", narray_convolve, 2 );
   rb_define_singleton_method( Convolver, "nn_run_layer", narray_nn_run_single_layer, 3 );
   rb_define_singleton_method( Convolver, "fit_kernel_backwards", narray_fit_backwards, 2 );
 }

data/lib/convolver.rb

@@ -4,6 +4,35 @@ require "convolver/version"
 require 'fftw3'
 
 module Convolver
+  # Chooses and calls likely fastest method from #convolve_basic and #convolve_fftw3.
+  # The two parameters must have the same rank. The output has same rank, its size in each
+  # dimension d is given by
+  #  signal.shape[d] - kernel.shape[d] + 1
+  # If you always perform convolutions of the same size, you may be better off benchmarking your
+  # own code using either #convolve_basic or #convolve_fftw3, and have your code use the fastest.
+  # @param [NArray] signal must be same size or larger than kernel in each dimension
+  # @param [NArray] kernel must be same size or smaller than signal in each dimension
+  # @return [NArray] result of convolving signal with kernel
+  def self.convolve signal, kernel
+    # For small signals or kernels, just go straight to basic
+    if signal.size < 1000 || kernel.size < 100
+      return convolve_basic( signal, kernel )
+    end
+
+    # If predicted time is less than a millisecond, just do a basic convolve
+    basic_time_predicted = predict_convolve_basic_time( signal, kernel )
+    if basic_time_predicted < 0.1
+      return convolve_basic( signal, kernel )
+    end
+
+    # Factor of two to allow for large uncertainty in predictions for FFTW3
+    if predict_convolve_fft_time( signal, kernel ) < 2 * basic_time_predicted
+      return convolve_fftw3( signal, kernel )
+    end
+
+    convolve_basic( signal, kernel )
+  end
+
   # Uses FFTW3 library to calculate convolution of an array of floats representing a signal,
   # with a second array representing a kernel. The two parameters must have the same rank.
   # The output has same rank, its size in each dimension d is given by

data/lib/convolver/version.rb

@@ -1,3 +1,3 @@
 module Convolver
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/spec/{convolver_spec.rb → convolve_basic_spec.rb}

@@ -1,19 +1,19 @@
 require 'helpers'
 
 describe Convolver do
-  describe "#convolve" do
+  describe "#convolve_basic" do
 
     it "should work like the example in the README" do
       a = NArray[ 0.3, 0.4, 0.5 ]
       b = NArray[ 1.3, -0.5 ]
-      c = Convolver.convolve( a, b )
+      c = Convolver.convolve_basic( a, b )
       c.should be_narray_like NArray[ 0.19, 0.27 ]
     end
 
     it "should calculate a 2D convolution" do
       a = NArray[ [ 0.3, 0.4, 0.5 ], [ 0.6, 0.8, 0.2 ], [ 0.9, 1.0, 0.1 ] ]
       b = NArray[ [ 1.2, -0.5 ], [ 0.5, -1.3 ] ]
-      c = Convolver.convolve( a, b )
+      c = Convolver.convolve_basic( a, b )
       c.should be_narray_like NArray[ [ -0.58, 0.37 ], [ -0.53, 1.23 ] ]
     end
 
@@ -22,7 +22,7 @@ describe Convolver do
         [ 0.9, 1.0, 0.1, 0.9, 1.0 ], [ 0.5, 0.9, 0.3, 0.2, 0.8 ], [ 0.7, 0.1, 0.3, 0.0, 0.1 ],
         [ 0.4, 0.5, 0.6, 0.7, 0.8 ], [ 0.5, 0.4, 0.3, 0.2, 0.1 ] ]
       b = NArray[ [ 1.2, -0.5, 0.2 ], [ 1.8, 0.5, -1.3 ] ]
-      c = Convolver.convolve( a, b )
+      c = Convolver.convolve_basic( a, b )
       c.should be_narray_like NArray[ [ 1.48, 0.79, 1.03 ], [ 2.35, 1.7, -0.79 ], [ 1.56, 2.84, -0.53 ],
         [ 1.13, 1.3, 0.83 ], [ 1.04, 0.26, 0.77 ], [ 1.06, 1.05, 1.04 ] ]
     end
@@ -43,7 +43,7 @@ describe Convolver do
       ]
 
       # Should be 3x2x1
-      c = Convolver.convolve( a, b )
+      c = Convolver.convolve_basic( a, b )
       c.should be_narray_like NArray[ [ [ 5.51, 3.04, 4.3 ], [ 3.04, 6.31, 3.87 ] ] ]
     end
 
@@ -74,33 +74,11 @@ describe Convolver do
         [ [ 0.8, 0.2 ], [ 0.5, 0.0 ], [ 1.4, 1.3 ] ] ] ]
 
       # Should be 2x2x3x2
-      c = Convolver.convolve( a, b )
+      c = Convolver.convolve_basic( a, b )
       c.should be_narray_like NArray[
         [ [ [ 8.5, 8.2 ], [ 11.34, 9.68 ] ], [ [ 7.68, 6.56 ], [ 11.24, 7.16 ] ], [ [ 9.14, 6.54 ], [ 12.44, 9.2 ] ] ],
         [ [ [ 8.5, 8.2 ], [ 11.34, 9.68 ] ], [ [ 7.68, 6.56 ], [ 11.24, 7.16 ] ], [ [ 9.14, 6.54 ], [ 12.44, 9.2 ] ] ]
       ]
     end
   end
-
-  describe "#nn_run_layer" do
-    it "should calculate basic layer rules" do
-      inputs = NArray[ 1.0 ]
-      weights = NArray[ [ 1.0 ] ]
-      thresholds = NArray[ 0.0 ]
-      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
-      outputs.should be_narray_like NArray[ 1.0 ]
-
-      inputs = NArray[ 0.5, -0.5 ]
-      weights = NArray[ [ 1.0, 2.0 ], [ 2.0, 1.0 ] ]
-      thresholds = NArray[ 0.0, 0.0 ]
-      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
-      outputs.should be_narray_like NArray[ 0.0, 0.5 ]
-
-      inputs = NArray[ 0.3, -0.4, 0.8, -0.7 ]
-      weights = NArray[ [ 1.0, 0.25, 0.5, -0.5 ], [ -1.0, -0.25, -0.5, 0.5 ] ]
-      thresholds = NArray[ 0.0, 0.0 ]
-      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
-      outputs.should be_narray_like NArray[ 0.95, 0.0 ]
-    end
-  end
 end

data/spec/convolve_fftw3_spec.rb

@@ -114,7 +114,7 @@ describe Convolver do
           (1..signal_length).each do |kernel_length|
             signal = NArray.sfloat(signal_length).random()
             kernel = NArray.sfloat(kernel_length).random()
-            expect_result = Convolver.convolve( signal, kernel )
+            expect_result = Convolver.convolve_basic( signal, kernel )
             got_result = Convolver.convolve_fftw3( signal, kernel )
             got_result.should be_narray_like expect_result
           end
@@ -128,7 +128,7 @@ describe Convolver do
               (1..signal_y).each do |kernel_y|
                 signal = NArray.sfloat(signal_x,signal_y).random()
                 kernel = NArray.sfloat(kernel_x,kernel_y).random()
-                expect_result = Convolver.convolve( signal, kernel )
+                expect_result = Convolver.convolve_basic( signal, kernel )
                 got_result = Convolver.convolve_fftw3( signal, kernel )
                 got_result.should be_narray_like expect_result
               end
@@ -146,7 +146,7 @@ describe Convolver do
                   (1..signal_z).each do |kernel_z|
                     signal = NArray.sfloat(signal_x,signal_y,signal_z).random()
                     kernel = NArray.sfloat(kernel_x,kernel_y,kernel_z).random()
-                    expect_result = Convolver.convolve( signal, kernel )
+                    expect_result = Convolver.convolve_basic( signal, kernel )
                     got_result = Convolver.convolve_fftw3( signal, kernel )
                     got_result.should be_narray_like expect_result
                   end

data/spec/convolve_spec.rb

@@ -0,0 +1,31 @@
+require 'helpers'
+
+describe Convolver do
+  describe "#convolve" do
+
+    it "should work like the example in the README" do
+      a = NArray[ 0.3, 0.4, 0.5 ]
+      b = NArray[ 1.3, -0.5 ]
+      c = Convolver.convolve( a, b )
+      c.should be_narray_like NArray[ 0.19, 0.27 ]
+    end
+
+    it "should choose #convolve_basic for small inputs" do
+      a = NArray.sfloat(50,50).random()
+      b = NArray.sfloat(10,10).random()
+      Convolver.expects( :convolve_basic ).once
+      Convolver.expects( :convolve_fftw3 ).never
+      c = Convolver.convolve( a, b )
+    end
+
+    it "should choose #convolve_fftw3 for large inputs" do
+      a = NArray.sfloat(500,500).random()
+      b = NArray.sfloat(100,100).random()
+      Convolver.expects( :convolve_basic ).never
+      Convolver.expects( :convolve_fftw3 ).once
+      c = Convolver.convolve( a, b )
+    end
+
+  end
+
+end

data/spec/helpers.rb

@@ -1,5 +1,6 @@
 # convolver/spec/helpers.rb
 require 'convolver'
+require 'mocha/api'
 
 # Matcher compares NArrays numerically
 RSpec::Matchers.define :be_narray_like do |expected_narray|

data/spec/nn_run_layer_spec.rb

@@ -0,0 +1,25 @@
+require 'helpers'
+
+describe Convolver do
+  describe "#nn_run_layer" do
+    it "should calculate basic layer rules" do
+      inputs = NArray[ 1.0 ]
+      weights = NArray[ [ 1.0 ] ]
+      thresholds = NArray[ 0.0 ]
+      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
+      outputs.should be_narray_like NArray[ 1.0 ]
+
+      inputs = NArray[ 0.5, -0.5 ]
+      weights = NArray[ [ 1.0, 2.0 ], [ 2.0, 1.0 ] ]
+      thresholds = NArray[ 0.0, 0.0 ]
+      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
+      outputs.should be_narray_like NArray[ 0.0, 0.5 ]
+
+      inputs = NArray[ 0.3, -0.4, 0.8, -0.7 ]
+      weights = NArray[ [ 1.0, 0.25, 0.5, -0.5 ], [ -1.0, -0.25, -0.5, 0.5 ] ]
+      thresholds = NArray[ 0.0, 0.0 ]
+      outputs = Convolver.nn_run_layer( inputs, weights, thresholds );
+      outputs.should be_narray_like NArray[ 0.95, 0.0 ]
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: convolver
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Neil Slater
@@ -80,6 +80,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: 2.13.0
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.14.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,8 +136,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- benchmarks/convolve_benchmark.rb
-- benchmarks/nn_layer_benchmark.rb
 - convolver.gemspec
 - ext/convolver/cnn_components.c
 - ext/convolver/cnn_components.h
@@ -135,9 +147,11 @@ files:
 - ext/convolver/narray_shared.h
 - lib/convolver.rb
 - lib/convolver/version.rb
+- spec/convolve_basic_spec.rb
 - spec/convolve_fftw3_spec.rb
-- spec/convolver_spec.rb
+- spec/convolve_spec.rb
 - spec/helpers.rb
+- spec/nn_run_layer_spec.rb
 homepage: http://github.com/neilslater/convolver
 licenses:
 - MIT
@@ -163,7 +177,9 @@ signing_key:
 specification_version: 4
 summary: Convolution for NArray
 test_files:
+- spec/convolve_basic_spec.rb
 - spec/convolve_fftw3_spec.rb
-- spec/convolver_spec.rb
+- spec/convolve_spec.rb
 - spec/helpers.rb
+- spec/nn_run_layer_spec.rb
 has_rdoc: