multiarray 0.4.1 → 0.5.0

data/COPYING

@@ -1,5 +1,5 @@
   This is the license for the computer vision library Hornetseye.
- Copyright (C) 2006, 2007, 2008, 2009 Jan Wedekind, Sheffield, United Kingdom.
+ Copyright (C) 2006 - 2010 Jan Wedekind, Sheffield, United Kingdom.
 
 
 		    GNU GENERAL PUBLIC LICENSE

data/README.md

@@ -0,0 +1,3 @@
+MultiArray
+==========
+This Ruby-extension defines the class {Hornetseye::MultiArray} and other native datatypes. {Hornetseye::MultiArray} provides multi-dimensional Ruby arrays with elements of same type. The extension is designed to be mostly compatible with Masahiro Tanaka's NArray. However it allows the definition of custom element types and operations on them. This work was also inspired by Ronald Garcia's boost::multi_array and by Todd Veldhuizen's Blitz++.

data/Rakefile

@@ -6,11 +6,11 @@ require 'rake/packagetask'
 require 'rbconfig'
 
 PKG_NAME = 'multiarray'
-PKG_VERSION = '0.4.1'
+PKG_VERSION = '0.5.0'
 RB_FILES = FileList[ 'lib/**/*.rb' ]
 TC_FILES = FileList[ 'test/tc_*.rb' ]
 TS_FILES = FileList[ 'test/ts_*.rb' ]
-PKG_FILES = [ 'Rakefile', 'README', 'COPYING', 'TODO', '.document' ] +
+PKG_FILES = [ 'Rakefile', 'README.md', 'COPYING', 'TODO', '.document' ] +
             RB_FILES + TS_FILES + TC_FILES
 SUMMARY = %q{Multi-dimensional and uniform Ruby arrays}
 DESCRIPTION = %q{This Ruby-extension defines Hornetseye::MultiArray and other native datatypes. Hornetseye::MultiArray provides multi-dimensional Ruby arrays with elements of same type. The extension is designed to be mostly compatible with Masahiro Tanaka's NArray. However it allows the definition of custom element types and operations on them. This work was also inspired by Ronald Garcia's boost::multi_array and by Todd Veldhuizen's Blitz++.}
@@ -30,8 +30,8 @@ desc 'Install Ruby extension'
 task :install do
   verbose true do
     for f in RB_FILES do
-      FileUtils.mkdir_p "#{$SITELIBDIR}/#{File.dirname( f[ 4 .. -1 ] )}"
-      FileUtils.cp_r f, "#{$SITELIBDIR}/#{f[ 4 .. -1 ]}"
+      FileUtils.mkdir_p "#{$SITELIBDIR}/#{File.dirname f.gsub( /^lib\//, '' )}"
+      FileUtils.cp_r f, "#{$SITELIBDIR}/#{f.gsub /^lib\//, ''}"
     end
   end
 end
@@ -40,7 +40,7 @@ desc 'Uninstall Ruby extension'
 task :uninstall do
   verbose true do
     for f in RB_FILES do
-      FileUtils.rm_f "#{$SITELIBDIR}/#{f[ 4 .. -1 ]}"
+      FileUtils.rm_f "#{$SITELIBDIR}/#{f.gsub /^lib\//, ''}"
     end
   end
 end
@@ -84,7 +84,8 @@ begin
     s.has_rdoc = 'yard'
     s.extra_rdoc_files = []
     s.rdoc_options = %w{--no-private}
-    s.add_dependency %q<malloc>, [ '~> 0.2' ]
+    s.add_dependency %q<malloc>, [ '~> 1.0' ]
+    s.add_development_dependency %q{rake}
   end
   GEM_SOURCE = "#{PKG_NAME}-#{PKG_VERSION}.gem"
   desc "Build the gem file #{GEM_SOURCE}"

data/TODO

@@ -1,7 +1,82 @@
-ranges (rolling, lazy rolling, lazy ranges)
+# test for multiarray-indgen
+# accept ranges for element access
+# compile Convolve#demand
+# inject without initial is [ 1 .. -1 ].inject with [ 0 ] as initial value
+# Composite numbers?
+# pointer-increments for better efficiency
+# How does contiguous work here? typecasts?
+# separate secondary operations like equality
+# preload cache
+# Sequence( UBYTE, 3 )[ ... ]
+
+# histogram (implement using injection)
+# inject: min, max, equal, n-d clips for warp
+# block(var1,var2,...) with smart subst?
+# lazy( 5 ) { |i| 0 } # but lazy { 0 }
+# lazy( 3, 2 ) { |i,j| i }
+# lazy( 3, 2 ) { |i,j| j.to_object }
+
+# RSpec
+
+# downsampling after correlation?
+# README.rdoc, YARD documentation with pictures, demo video
+
+# f(g(i)) # g(i), f(g(i)) all can be vectors and all can be lazy
+# lut(g(i))
+# f(warp(i))
+#class Node
+#  def map( lut, options = {} )
+#    
+#  end
+#end
+
+
+# cache <-> demand/get? what about store?
+# Composite numbers?
+# change Convolve#demand to generate GCC code
+# inspect method (type method to get MultiArray( ... ) or Sequence( ... ))
+# put JIT-calls into 'force'-method, don't call JIT for OBJECT
+# -> multiarray gem
+# pointer-increments for better efficiency
+# use pid, allow creation of library for pre-loading cache
+
+# histogram
+# binary operations, equality: ( a == b ).inject( true ) { |e,b| e && b }
+# inject: min, max, equal, n-d clips for warp
+# block(var1,var2,...) with smart subst?
+# lazy( 5 ) { |i| 0 }
+# lazy( 3, 2 ) { |i,j| i }
+# lazy( 3, 2 ) { |i,j| j }
+
+# downsampling after correlation?
+# ruby -Ilib -rrubygems -rmultiarray -rtest test/tc_sequence.rb
+# README.rdoc, demo video
+
+# f(g(i)) # g(i), f(g(i)) all can be vectors and all can be lazy
+# lut(g(i))
+# f(warp(i))
+#class Node
+#  def map( lut, options = {} ) # !!!
+#    
+#  end
+#end
+
+
+lazy { a * b } -> lazy { |i,j| lazy { |i,j| a[i,j] * b[i,j] }[i,j] } # ?
+lazy { s } -> s
+lazy { -s } -> lazy { |i| -s[i] }
+lazy { |i,j| s[i,j] }
+lazy { |i| lazy { |j| s[i,j] } }
+lazy( n ) { |i| i }
+lazy( n, m ) { |i,j| i + j }
+lazy( n ) { |i| lazy( m ) { |j| i + j } }
+eager( n ) { |i| i }
+...
+
 tensor indices to enable transpose of lazy array
+ranges (rolling, lazy rolling, lazy ranges)
 test lazyness
-sums/injections? nesting? tensors?
+sums/injections (equality for arrays)? nesting? tensors?
 JIT?
 test type conversions
 fancy README
@@ -52,6 +127,8 @@ proc { |i| proc { |j| i+j } }.call( 5 ).call 3
 
 gem install flay: http://ruby.sadi.st/Flay.html
 
+# donate to yardoc
+
 How to nest/cascade mode-environments?
 (how to specify nested modes for recursive algorithms and called algorithms?)
 ruby and jit compiles, lazy and parallel forwards

data/lib/multiarray.rb

@@ -1,10 +1,49 @@
+# multiarray - Lazy multi-dimensional arrays for Ruby
+# Copyright (C) 2010 Jan Wedekind
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Module#alias_method_chain is defined.
+#
+# @private
+class Module
+
+  unless method_defined? :alias_method_chain
+
+    # Method for creating alias chains.
+    #
+    # @private
+    def alias_method_chain( target, feature, vocalize = target )
+      alias_method "#{vocalize}_without_#{feature}", target
+      alias_method target, "#{vocalize}_with_#{feature}"
+    end
+
+  end
+
+end
+
 # Proc#bind is defined if it does not exist already
+#
+# @private
 class Proc
 
   unless method_defined? :bind
 
     # Proc#bind is defined if it does not exist already
     #
+    # @param [Object] object Object to bind this instance of +Proc+ to.
+    #
     # @private
     def bind( object )
       block, time = self, Time.now
@@ -21,7 +60,7 @@ class Proc
 
 end
 
-# Object#instance_exec is defined if it does not exist already
+# +Object+ is extended with a few methods
 class Object
 
   unless method_defined? :instance_exec
@@ -35,18 +74,316 @@ class Object
 
   end
 
+  # Boolean negation
+  #
+  # @return [FalseClass] Returns +false+.
+  #
+  # @see NilClass#not
+  # @see FalseClass#not
+  def not
+     false
+  end
+
+  # Boolean 'and' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [FalseClass,TrueClass] Returns +other+.
+  #
+  # @see FalseClass#and
+  # @see NilClass#and
+  def and( other )
+    unless other.is_a? Hornetseye::Node
+      other
+    else
+      x, y = other.coerce self
+      x.and y
+    end
+  end
+
+  # Boolean 'or' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [TrueClass] Returns +true+.
+  #
+  # @see FalseClass#or
+  # @see NilClass#or
+  def or( other )
+    unless other.is_a? Hornetseye::Node
+      self
+    else
+      x, y = other.coerce self
+      x.or y
+    end
+  end
+
+  # Element-wise equal operator
+  #
+  # The method calls +self == other+ unless +other+ is of type
+  # Hornetseye::Node. In that case an element-wise comparison using
+  # Hornetseye::Node#eq is performed after coercion.
+  #
+  # @return [FalseClass,TrueClass,Hornetseye::Node] Result of comparison.
+  # @see Hornetseye::Node
+  # @see Hornetseye::Binary_
+  def eq( other )
+    unless other.is_a? Hornetseye::Node
+      self == other
+    else
+      x, y = other.coerce self
+      x.eq y
+    end
+  end
+
+  # Element-wise not-equal operator
+  #
+  # The method calls +( self == other ).not+ unless +other+ is of type
+  # Hornetseye::Node. In that case an element-wise comparison using
+  # Hornetseye::Node#ne is performed after coercion.
+  #
+  # @return [FalseClass,TrueClass,Hornetseye::Node] Result of comparison.
+  # @see Hornetseye::Node
+  # @see Hornetseye::Binary_
+  def ne( other )
+    unless other.is_a? Hornetseye::Node
+      ( self == other ).not
+    else
+      x, y = other.coerce self
+      x.ne y
+    end
+  end
+
+  # Boolean select operation
+  #
+  # @param [Object] a Object to select if +self+ is neither +false+ nor +nil+.
+  # @param [Object] b Object to select if +self+ is +false+ or +nil+.
+  # @return [Object] Returns +a+.
+  #
+  # @see FalseClass#conditional
+  # @see NilClass#conditional
+  def conditional( a, b )
+    a
+  end
+
 end
 
-# Range#min and Range#max are replaced for performance reasons
-class Range
+# +NilClass+ is extended with a few methods
+class NilClass
+
+  # Boolean negation
+  #
+  # @return [FalseClass] Returns +false+.
+  #
+  # @see Object#not
+  # @see FalseClass#not
+  def not
+     true
+  end
+
+  # Boolean 'and' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [FalseClass] Returns +false+.
+  #
+  # @see Object#and
+  # @see FalseClass#and
+  def and( other )
+    unless other.is_a? Hornetseye::Node
+      self
+    else
+      x, y = other.coerce self
+      x.and y
+    end
+  end
+
+  # Boolean 'or' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [FalseClass,TrueClass] Returns +other+.
+  #
+  # @see Object#or
+  # @see FalseClass#or
+  def or( other )
+    unless other.is_a? Hornetseye::Node
+      other
+    else
+      x, y = other.coerce self
+      x.or y
+    end
+  end
+
+  # Boolean select operation
+  #
+  # @param [Object] a Object to select if +self+ is neither +false+ nor +nil+.
+  # @param [Object] b Object to select if +self+ is +false+ or +nil+.
+  # @return [Object] Returns +b+.
+  #
+  # @see Object#conditional
+  # @see FalseClass#conditional
+  def conditional( a, b )
+    b
+  end
+
+  # Check whether this term is compilable
+  #
+  # @return [FalseClass,TrueClass] Returns +false+
+  #
+  # @private
+  def compilable?
+    false
+  end
+
+end
+
+# +FalseClass+ is extended with a few methods
+#
+# @see TrueClass
+class FalseClass
+
+  # Boolean negation
+  #
+  # @return [FalseClass] Returns +true+.
+  #
+  # @see Object#not
+  # @see NilClass#not
+  def not
+    true
+  end
+
+  # Boolean 'and' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [FalseClass] Returns +false+.
+  #
+  # @see Object#and
+  # @see NilClass#and
+  def and( other )
+    unless other.is_a? Hornetseye::Node
+      self
+    else
+      x, y = other.coerce self
+      x.and y
+    end
+  end
+
+  # Boolean 'or' operation
+  #
+  # @param [FalseClass,TrueClass,Object] other Other boolean object.
+  # @return [FalseClass,TrueClass] Returns +other+.
+  #
+  # @see Object#or
+  # @see NilClass#or
+  def or( other )
+    unless other.is_a? Hornetseye::Node
+      other
+    else
+      x, y = other.coerce self
+      x.or y
+    end
+  end
+
+  # Boolean select operation
+  #
+  # @param [Object] a Object to select if +self+ is neither +false+ nor +nil+.
+  # @param [Object] b Object to select if +self+ is +false+ or +nil+.
+  # @return [Object] Returns +b+.
+  #
+  # @see Object#conditional
+  # @see NilClass#conditional
+  def conditional( a, b )
+    b
+  end
+
+end
 
-  public
+# Some methods of +Fixnum+ are modified
+#
+# @private
+class Fixnum
+
+  # +&+ is modified to work with this library
+  #
+  # @private
+  def intand_with_hornetseye( other )
+    if other.is_a? Integer
+      intand_without_hornetseye other
+    else
+      x, y = other.coerce self
+      x & y
+    end
+  end
+
+  alias_method_chain :&, :hornetseye, :intand
+
+  # +|+ is modified to work with this library
+  #
+  # @private
+  def intor_with_hornetseye( other )
+    if other.is_a? Integer
+      intor_without_hornetseye other
+    else
+      x, y = other.coerce self
+      x | y
+    end
+  end
+
+  alias_method_chain :|, :hornetseye, :intor
+
+  # +^+ is modified to work with this library
+  #
+  # @private
+  def intxor_with_hornetseye( other )
+    if other.is_a? Integer
+      intxor_without_hornetseye other
+    else
+      x, y = other.coerce self
+      x ^ y
+    end
+  end
+
+  alias_method_chain :^, :hornetseye, :intxor
+
+  # +<<+ is modified to work with this library
+  #
+  # @private
+  def shl_with_hornetseye( other )
+    if other.is_a? Integer
+      shl_without_hornetseye other
+    else
+      x, y = other.coerce self
+      x << y
+    end
+  end
+
+  alias_method_chain :<<, :hornetseye, :shl
+
+  # +>>+ is modified to work with this library
+  #
+  # @private
+  def shr_with_hornetseye( other )
+    if other.is_a? Integer
+      shr_without_hornetseye other
+    else
+      x, y = other.coerce self
+      x >> y
+    end
+  end
+
+  alias_method_chain :>>, :hornetseye, :shr
+
+end
+
+# +Range+ is extended with a few methods
+class Range
 
   alias_method :orig_min, :min
 
   alias_method :orig_max, :max
 
   # For performance reasons a specialised method for integers is added
+  #
+  # @return [Object] Minimum value of range.
+  #
+  # @private
   def min
     if self.begin.is_a? Integer
       self.begin
@@ -55,7 +392,11 @@ class Range
     end
   end
 
-  # For performance reasons a specialised method for integers is added.
+  # For performance reasons a specialised method for integers is added
+  #
+  # @return [Object] Maximum value of range.
+  #
+  # @private
   def max
     if self.end.is_a? Integer
       exclude_end? ? self.end - 1 : self.end
@@ -64,42 +405,122 @@ class Range
     end
   end
 
-  # Compute the size of a range.
+  # Compute the size of a range
+  #
+  # @return [Integer] Number of discrete values within range.
   def size
     max + 1 - min
   end
 
 end
 
-# Module#alias_method_chain is defined.
-#
-# @private
-class Module
-
-  unless method_defined? :alias_method_chain
-
-    # Method for creating alias chains.
-    #
-    # @private
-    def alias_method_chain( target, feature, vocalize = target )
-      alias_method "#{vocalize}_without_#{feature}", target
-      alias_method target, "#{vocalize}_with_#{feature}"
-    end
-
-  end
-
-end
-
 require 'malloc'
-require 'multiarray/lazy'
-require 'multiarray/list'
+require 'rbconfig'
+require 'set'
+require 'tmpdir'
 require 'multiarray/malloc'
-require 'multiarray/type'
+require 'multiarray/list'
+require 'multiarray/node'
+require 'multiarray/element'
 require 'multiarray/object'
-require 'multiarray/int_'
+require 'multiarray/index'
+require 'multiarray/bool'
 require 'multiarray/int'
-require 'multiarray/pointer_'
 require 'multiarray/pointer'
-require 'multiarray/sequence_'
+require 'multiarray/variable'
+require 'multiarray/lambda'
+require 'multiarray/lookup'
+require 'multiarray/unary'
+require 'multiarray/binary'
+require 'multiarray/operations'
+require 'multiarray/inject'
+require 'multiarray/diagonal'
 require 'multiarray/sequence'
 require 'multiarray/multiarray'
+require 'multiarray/gcctype'
+require 'multiarray/gccvalue'
+require 'multiarray/gcccontext'
+require 'multiarray/gcccache'
+require 'multiarray/gccfunction'
+
+# Namespace of Hornetseye computer vision library
+module Hornetseye
+
+  # Method for performing computations in lazy mode
+  #
+  # @param [Array<Integer>] *shape Optional shape of result. The method
+  # attempts to infer the shape if not specified.
+  # @yield Operation to compute array elements lazily.
+  #
+  # @return [Object,Node] Lazy term to compute later.
+  def lazy( *shape, &action )
+    previous = Thread.current[ :lazy ]
+    Thread.current[ :lazy ] = true
+    begin
+      options = shape.last.is_a?( Hash ) ? shape.pop : {}
+      arity = options[ :arity ] || action.arity
+      if arity <= 0
+        action.call
+      else
+        index = Variable.new shape.empty? ? Hornetseye::INDEX( nil ) :
+                                            Hornetseye::INDEX( shape.pop )
+        term = lazy *( shape + [ :arity => arity - 1 ] ) do |*args|
+          action.call *( args + [ index ] )
+        end
+        term = Node.match( term ).new term unless term.is_a? Node
+        Lambda.new index, term
+      end
+    ensure
+      Thread.current[ :lazy ] = previous
+    end
+  end
+
+  module_function :lazy
+
+  # Method for performing computations in eager mode
+  #
+  # @param [Array<Integer>] *shape Optional shape of result. The method
+  # attempts to infer the shape if not specified.
+  # @yield Operation computing array elements.
+  #
+  # @return [Object,Node] Result of computation.
+  def eager( *shape, &action )
+    previous = Thread.current[ :lazy ]
+    Thread.current[ :lazy ] = false
+    begin
+      retval = lazy *shape, &action
+      retval.is_a?( Node ) ? retval.force : retval
+    ensure
+      Thread.current[ :lazy ] = previous
+    end
+  end
+
+  module_function :eager
+
+  # Method for summing values
+  #
+  # @param [Array<Integer>] *shape Optional shape of result. The method
+  # attempts to infer the shape if not specified.
+  # @yield Operation returning array elements.
+  #
+  # @return [Object,Node] Sum of values.
+  def sum( *shape, &action )
+    options = shape.last.is_a?( Hash ) ? shape.pop : {}
+    arity = options[ :arity ] || action.arity
+    if arity <= 0
+      action.call
+    else
+      index = Variable.new shape.empty? ? Hornetseye::INDEX( nil ) :
+                           Hornetseye::INDEX( shape.pop )
+      term = sum *( shape + [ :arity => arity - 1 ] ) do |*args|
+        action.call *( args + [ index ] )
+      end
+      var1 = Variable.new term.typecode
+      var2 = Variable.new term.typecode
+      Inject.new( term, index, nil, var1 + var2, var1, var2 ).force
+    end
+  end
+
+  module_function :sum
+
+end