multiarray 0.5.2 → 0.6.0

data/lib/multiarray/list.rb

@@ -17,29 +17,55 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Ruby array supporting array views
+  #
+  # @see Malloc
   class List
 
+    # Initialise array
+    #
+    # @param [Integer] n Number of elements.
+    # @option options [Array] :array ([ nil ] * n) Existing Ruby array to create an
+    #         array view.
+    # @option options [Integer] :offset (0) Offset for array view.
     def initialize( n, options = {} )
       @array = options[ :array ] || [ nil ] * n
       @offset = options[ :offset ] || 0
     end
 
+    # Display information about this object
+    #
+    # @return [String] String with information about this object (e.g. "List(5)").
     def inspect
       "List(#{@array.size - @offset})"
     end
 
+    # Display information about this object
+    #
+    # @return [String] String with information about this object (e.g. "List(5)").
     def to_s
-      "List(#{@array[ @offset .. -1 ]})"
+      inspect
     end
 
+    # Create array view with specified offset
+    #
+    # @param [Integer] offset Offset for array view.
+    #
+    # @return [List] The resulting array view.
     def +( offset )
       List.new 0, :array => @array, :offset => @offset + offset
     end
 
+    # Retrieve value of specified typecode
+    #
+    # @param [Class] typecode The type of the value.
     def load( typecode )
       @array[ @offset ]
     end
 
+    # Store value
+    #
+    # @param [Node] value Value to store.
     def save( value )
       @array[ @offset ] = value.get
       value

data/lib/multiarray/lookup.rb

@@ -17,12 +17,25 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Class for lazy array lookup
   class Lookup < Node
 
+    # Create array lookup
+    #
+    # @param [Node] p Object supporting lookup.
+    # @param [Variable] index The array index.
+    # @param [Node] stride The array stride.
     def initialize( p, index, stride )
       @p, @index, @stride = p, index, stride
     end
 
+    def memory
+      if array_type.storage_size != @stride.get * typecode.storage_size
+        raise 'Memory is not contiguous'
+      end
+      @p.memory
+    end
+
     # Get unique descriptor of this object
     #
     # @param [Hash] hash Labels for any variables.
@@ -35,14 +48,33 @@ module Hornetseye
         "#{@stride.descriptor( hash )})"
     end
 
+    # Get type of result of delayed operation
+    #
+    # @return [Class] Type of result.
+    #
+    # @private
     def array_type
       @p.array_type
     end
 
+    # Substitute variables
+    #
+    # Substitute the variables with the values given in the hash.
+    #
+    # @param [Hash] hash Substitutions to apply.
+    #
+    # @return [Node] Term with substitutions applied.
+    #
+    # @private
     def subst( hash )
       @p.subst( hash ).lookup @index.subst( hash ), @stride.subst( hash )
     end
 
+    # Get variables contained in this object
+    #
+    # @return [Set] Returns +Set[ self ]+.
+    #
+    # @private
     def variables
       @p.variables + @index.variables + @stride.variables
     end
@@ -77,6 +109,14 @@ module Hornetseye
       end
     end
 
+    # Skip elements of an array
+    #
+    # @param [Variable] index Variable identifying index of array.
+    # @param [Node] start Wrapped integer with number of elements to skip.
+    #
+    # @return [Node] Lookup object with elements skipped.
+    #
+    # @private
     def skip( index, start )
       if @index == index
         Lookup.new @p.lookup( start, @stride ), @index, @stride
@@ -85,14 +125,34 @@ module Hornetseye
       end
     end
 
+    # Get element if lookup term
+    #
+    # @param [Integer,Node] i Index of desired element.
+    #
+    # @return [Node,Object] Element of lookup term.
+    #
+    # @private
     def element( i )
       Lookup.new @p.element( i ), @index, @stride
     end
 
+    # Extract array view with part of array
+    #
+    # @param [Integer,Node] start Number of elements to skip.
+    # @param [Integer,Node] length Size of array view.
+    #
+    # @return [Node] Array view with the specified elements.
+    #
+    # @private
     def slice( start, length )
       Lookup.new @p.slice( start, length ), @index, @stride
     end
 
+    # Decompose composite elements
+    #
+    # This method decomposes composite elements into array.
+    #
+    # @return [Node] Result of decomposition.
     def decompose
       if typecode < Composite
         Lookup.new @p.decompose, @index, @stride * typecode.num_elements

data/lib/multiarray/lut.rb

@@ -0,0 +1,102 @@
+# 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 Hornetseye
+
+  class Lut < Node
+
+    class << self
+
+      def finalised?
+        false
+      end
+
+    end
+
+    def initialize( source, table, n )
+      @source, @table = source, table
+      @n = n || @source.shape.first
+    end
+
+    def descriptor( hash )
+      "Lut(#{@source.descriptor( hash )},#{@table.descriptor( hash )},#{@n})"
+    end
+
+    def array_type
+      shape = @table.shape.first( @table.dimension - @n ) + @source.shape[ 1 .. -1 ]
+      Hornetseye::MultiArray @table.typecode, *shape
+    end
+
+    def demand
+      @source.lut @table, :n => @n, :safe => false
+    end
+
+    def subst( hash )
+      self.class.new @source.subst( hash ), @table.subst( hash ), @n
+    end
+
+    def variables
+      @source.variables + @table.variables
+    end
+
+    def strip
+      vars1, values1, term1 = @source.strip
+      vars2, values2, term2 = @table.strip
+      return vars1 + vars2, values1 + values2, self.class.new( term1, term2, @n )
+    end
+
+    def skip( index, start )
+      self.class.new @source.skip( index, start ), @table.skip( index, start ), @n
+    end
+
+    def element( i )
+      source, table = @source, @table
+      if source.dimension > 1
+        source = source.element i
+        self.class.new source, table, @n
+      elsif table.dimension > @n
+        self.class.new source, table.unroll( @n ).element( i ).roll( @n ), @n
+      else
+        super i
+      end
+    end
+
+    def slice( start, length )
+      source, table = @source, @table
+      if source.dimension > 1
+        source = source.slice( start, length ).roll
+        self.class.new( source, table, @n ).unroll
+      elsif table.dimension > @n
+        self.class.new( source,
+                        table.unroll( @n ).slice( start, length ).roll( @n + 1 ),
+                        @n ).unroll
+      else
+        super i
+      end
+    end
+
+    def decompose
+      self.class.new @source, @table.decompose, @n
+    end
+
+    def compilable?
+      @source.compilable? and @table.compilable?
+    end
+
+  end
+
+end
+

data/lib/multiarray/malloc.rb

@@ -17,17 +17,33 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Malloc is extended with a few methods
+  #
+  # @see List
   class Malloc
 
+    # Read typed value
+    #
+    # @param [Class] typecode Load typed value from memory.
+    #
+    # @return [Node] Value from memory.
     def load( typecode )
       read( typecode.storage_size ).unpack( typecode.directive )
     end
 
+    # Write typed value to memory
+    #
+    # @param [Node] value Value to write to memory.
+    #
+    # @return [Node] Returns +value+.
     def save( value )
       write value.values.pack( value.typecode.directive )
       value
     end
 
+    # Display information about this object.
+    #
+    # @return [String] String with information about this object.
     def to_s
       inspect
     end

data/lib/multiarray/methods.rb

@@ -19,9 +19,13 @@ module Hornetseye
 
   module Methods
 
+    # Extend some methods in the specified module.
+    #
+    # @param [Module] mod The mathematics module.
     def Methods.included( mod )
       define_unary_method  mod, :sqrt , :float
       define_unary_method  mod, :log  , :float
+      define_unary_method  mod, :log10, :float
       define_unary_method  mod, :exp  , :float
       define_unary_method  mod, :cos  , :float
       define_unary_method  mod, :sin  , :float
@@ -32,10 +36,18 @@ module Hornetseye
       define_unary_method  mod, :cosh , :float
       define_unary_method  mod, :sinh , :float
       define_unary_method  mod, :tanh , :float
+      define_unary_method  mod, :acosh, :float
+      define_unary_method  mod, :asinh, :float
+      define_unary_method  mod, :atanh, :float
       define_binary_method mod, :atan2, :floating
       define_binary_method mod, :hypot, :floating
     end
 
+    # Extend unary method with capability to handle arrays.
+    #
+    # @param [Module] mod The mathematics module.
+    # @param [Symbol,String] op The unary method to extend.
+    # @param [Symbol,String] conversion A method for doing the type conversion.
     def define_unary_method( mod, op, conversion = :contiguous )
       mod.module_eval do
         define_method( "#{op}_with_hornetseye" ) do |a|
@@ -61,6 +73,11 @@ module Hornetseye
 
     module_function :define_unary_method
 
+    # Extend binary method with capability to handle arrays.
+    #
+    # @param [Module] mod The mathematics module.
+    # @param [Symbol,String] op The binary method to extend.
+    # @param [Symbol,String] conversion A method for doing the type balancing.
     def define_binary_method( mod, op, coercion = :coercion )
       mod.module_eval do
         define_method( "#{op}_with_hornetseye" ) do |a,b|

data/lib/multiarray/multiarray.rb

@@ -17,26 +17,42 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # This class provides methods for initialising multi-dimensional arrays
   class MultiArray
 
     class << self
 
+      # Create new multi-dimensional array
+      #
+      # @param [Class] typecode The type of elements
+      # @param [Array<Integer>] *shape The shape of the multi-dimensional array.
       def new( typecode, *shape )
         options = shape.last.is_a?( Hash ) ? shape.pop : {}
         count = options[ :count ] || 1
         if shape.empty?
-          memory = typecode.memory.new typecode.storage_size * count
+          memory = options[ :memory ] ||
+                   typecode.memory.new( typecode.storage_size * count )
           Hornetseye::Pointer( typecode ).new memory
         else
           size = shape.pop
           stride = shape.inject( 1 ) { |a,b| a * b }
           Hornetseye::lazy( size ) do |index|
-            pointer = new typecode, *( shape + [ :count => count * size ] )
+            pointer = new typecode, *( shape + [ :count => count * size,
+                                                 :memory => options[ :memory ] ] )
             Lookup.new pointer, index, INT.new( stride )
           end
         end
       end
 
+      # Convert Ruby array to uniform multi-dimensional array
+      #
+      # Type matching is used to find a common element type. Furthermore the required
+      # shape of the array is determined. Finally the elements are coopied to the
+      # resulting array.
+      #
+      # @param [Array<Object>] *args
+      #
+      # @return [Node] Uniform multi-dimensional array.
       def []( *args )
         target = Node.fit args
         target[ *args ]
@@ -46,6 +62,12 @@ module Hornetseye
 
   end
 
+  # Create multi-dimensional array type
+  #
+  # @param [Class] element_type Type of elements.
+  # @param [Array<Integer>] *shape Shape of array type.
+  #
+  # @return [Class] The array type.
   def MultiArray( element_type, *shape )
     if shape.empty?
       element_type

data/lib/multiarray/node.rb

@@ -66,17 +66,27 @@ module Hornetseye
         self
       end
 
+      # Base type of this data type
+      #
+      # @return [Class] Returns +element_type+.
+      #
+      # @private
       def basetype
         self
       end
 
+      # Get list of types of composite type
+      #
+      # @return [Array<Class>] List of types.
+      #
+      # @private
       def typecodes
         [ self ]
       end
 
-      # Array type of this term
+      # Get type of result of delayed operation
       #
-      # @return [Class] Resulting array type.
+      # @return [Class] Type of result.
       #
       # @private
       def array_type
@@ -90,6 +100,12 @@ module Hornetseye
         Hornetseye::Pointer( self )
       end
 
+      # Generate index array of this type
+      #
+      # @param [Object] offset First value.
+      # @param [Object] offset Increment for consecutive values.
+      #
+      # @return [Object] Returns +offset+.
       def indgen( offset = 0, increment = 1 )
         offset
       end
@@ -101,6 +117,14 @@ module Hornetseye
         []
       end
 
+      def width
+        shape[0]
+      end
+
+      def height
+        shape[1]
+      end
+
       # Get size (number of elements) of this value
       #
       # @return [Integer] Returns +1+.
@@ -108,6 +132,9 @@ module Hornetseye
         1
       end
 
+      # Check whether the type is an empty array
+      #
+      # @return [Boolean] Returns whether this type represents an empty array.
       def empty?
         size == 0
       end
@@ -135,10 +162,16 @@ module Hornetseye
         BOOL
       end
 
+      # Get corresponding scalar type
+      #
+      # @return [Class] Returns +self+.
       def scalar
         self
       end
 
+      # Get corresponding type based on floating-point scalars
+      #
+      # @return [Class] Corresponding type based on floating-point scalars.
       def float_scalar
         float.scalar
       end
@@ -150,29 +183,52 @@ module Hornetseye
         other.coercion( self ).bool
       end
 
+      # Get corresponding maximal integer type
+      #
+      # @return [Class] Returns +self+.
+      #
+      # @private
       def maxint
         self
       end
 
+      # Get maximum integer based datatype for binary operation
+      #
+      # @return [Class] Returns type based on maximum integer.
       def coercion_maxint( other )
         coercion( other ).maxint
       end
 
-      # Get corresponding floating-point datatype
+      # Convert to type based on floating point numbers
+      #
+      # @return [Class] Corresponding type based on floating point numbers.
       #
-      # @return [Class] Returns +DFLOAT+.
+      # @private
       def float
         DFLOAT
       end
 
+      # Get floating point based datatype for binary operation
+      #
+      # @return [Class] Returns type based on floating point numbers.
       def floating( other )
         other.coercion( self ).float
       end
 
+      # Convert to type based on bytes
+      #
+      # @return [Class] Corresponding type based on bytes.
+      #
+      # @private
       def byte
         BYTE
       end
 
+      # Get byte-based datatype for binary operation
+      #
+      # @param [Class] other The other type.
+      #
+      # @return [Class] Returns type based on bytes.
       def coercion_byte( other )
         coercion( other ).byte
       end
@@ -182,6 +238,11 @@ module Hornetseye
         Hornetseye::MultiArray( t.typecode, *shape ).coercion t
       end
 
+      # Convert to different element type
+      #
+      # @param [Class] dest Element type to convert to.
+      #
+      # @return [Class] Type based on the different element type.
       def to_type( dest )
         dest
       end
@@ -197,7 +258,7 @@ module Hornetseye
 
       # Category operator
       #
-      # @return [FalseClass,TrueClass] Check for equality or kind.
+      # @return [Boolean] Check for equality or kind.
       def ===( other )
         ( other == self ) or ( other.is_a? self ) or ( other.class == self )
       end
@@ -230,22 +291,29 @@ module Hornetseye
 
       # Check whether this term is compilable
       #
-      # @return [FalseClass,TrueClass] Returns +true+.
+      # @return [Boolean] Returns +true+.
       #
       # @private
       def compilable?
         true
       end
 
+      # Check whether objects of this class are finalised computations
+      #
+      # @return [Boolean] Returns +true+.
+      #
+      # @private
       def finalised?
         true
       end
 
     end
 
-    # Array type of this term
+    # Get type of result of delayed operation
+    #
+    # @return [Class] Type of result.
     #
-    # @return [Class] Resulting array type.
+    # @private
     def array_type
       self.class.array_type
     end
@@ -275,6 +343,14 @@ module Hornetseye
       array_type.shape
     end
 
+    def width
+      array_type.width
+    end
+
+    def height
+      array_type.height
+    end
+
     # Get size (number of elements) of this value
     #
     # @return [Integer] Returns +array_type.size+.
@@ -282,6 +358,9 @@ module Hornetseye
       array_type.size
     end
 
+    # Check whether this object is an empty array.
+    #
+    # @return [Boolean] Returns whether this object is an empty array.
     def empty?
       array_type.empty?
     end
@@ -337,7 +416,7 @@ module Hornetseye
           else
             retval = '[ '
             for i in 0 ... array_type.num_elements
-              x = Hornetseye::lazy { element i }
+              x = element i
               if x.dimension > 0
                 if i > 0
                   retval += ",\n  "
@@ -400,6 +479,9 @@ module Hornetseye
       'Node()'
     end
 
+    # Duplicate object
+    #
+    # @return [Node] Duplicate of +self+.
     def dup
       retval = array_type.new
       retval[] = self
@@ -421,13 +503,18 @@ module Hornetseye
 
     # Check whether this term is compilable
     #
-    # @return [FalseClass,TrueClass] Returns +typecode.compilable?+.
+    # @return [Boolean] Returns +typecode.compilable?+.
     #
     # @private
     def compilable?
       typecode.compilable?
     end
 
+    # Check whether this object is a finalised computation
+    #
+    # @return [Boolean] Returns +self.class.finalised?+.
+    #
+    # @private
     def finalised?
       self.class.finalised?
     end
@@ -479,10 +566,11 @@ module Hornetseye
       if indices.empty?
         check_shape value
         unless compilable? and value.compilable? and dimension > 0
-          store value
+          Store.new( self, value ).demand
         else
-          GCCFunction.run self, value
+          GCCFunction.run Store.new( self, value )
         end
+        value
       else
         if indices.last.is_a? Range
           view = slice indices.last.min, indices.last.size
@@ -538,16 +626,17 @@ module Hornetseye
         self
       elsif finalised?
         get
+      elsif compilable?
+        retval = pointer_type.new
+        GCCFunction.run Store.new( retval, self )
+        retval.demand.get
       else
-        unless compilable?
-          Hornetseye::lazy do
-            retval = array_type.new
-            retval[] = self
-            retval.get
-          end
-        else
-          GCCFunction.run( pointer_type.new, self ).get
-        end
+        Store.new( array_type.new, self ).demand.get
+        #Hornetseye::lazy do
+        #  retval = array_type.new
+        #  retval[] = self
+        #  retval.get
+        #end
       end
     end
 
@@ -582,6 +671,11 @@ module Hornetseye
       end
     end
 
+    # Decompose composite elements
+    #
+    # This method decomposes composite elements into array.
+    #
+    # @return [Node] Returns +self+.
     def decompose
       self
     end