multiarray 0.5.2 → 0.6.0

data/lib/multiarray/composite.rb

@@ -17,26 +17,55 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Base class for composite types
   class Composite < Element
 
     class << self
 
+      # Access element type of composite type
+      #
+      # @return [Class] The element type.
       attr_accessor :element_type
 
+      # Get number of elements of composite type
+      #
+      # @return [Integer] Number of elements.
       attr_accessor :num_elements
 
+      # Memory type required to store elements of this type
+      #
+      # @return [Class] Returns +element_type.memory+.
+      #
+      # @private
       def memory
         element_type.memory
       end
 
+      # Get storage size to store an element of this type
+      #
+      # @return [Integer] Returns +element_type.storage_size * num_elements+.
+      #
+      # @private
       def storage_size
         element_type.storage_size * num_elements
       end
 
+      # Directive for packing/unpacking elements of this type
+      #
+      # @return [String] Returns string with directive.
+      #
+      # @private
       def directive
         element_type.directive * num_elements
       end
 
+      # Get unique descriptor of this class
+      #
+      # @param [Hash] hash Labels for any variables.
+      #
+      # @return [String] Descriptor of this class.
+      #
+      # @private
       def descriptor( hash )
         unless element_type.nil?
           inspect
@@ -45,14 +74,29 @@ module Hornetseye
         end
       end
 
+      # Base type of this data type
+      #
+      # @return [Class] Returns +element_type+.
+      #
+      # @private
       def basetype
         element_type
       end
 
+      # Get list of types of composite type
+      #
+      # @return [Array<Class>] List of types.
+      #
+      # @private
       def typecodes
         [ element_type ] * num_elements
       end
 
+      # Scalar type to this type
+      #
+      # @return [Class] Returns +element_type+.
+      #
+      # @private
       def scalar
         element_type
       end

data/lib/multiarray/diagonal.rb

@@ -22,6 +22,11 @@ module Hornetseye
 
     class << self
 
+      # Check whether objects of this class are finalised computations
+      #
+      # @return [Boolean] Returns +false+.
+      #
+      # @private
       def finalised?
         false
       end
@@ -56,9 +61,9 @@ module Hornetseye
         "#{@block.descriptor( hash )})"
     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
@@ -97,6 +102,8 @@ module Hornetseye
     # @param [Integer,Node] i Index of desired element.
     #
     # @return [Node,Object] Element of diagonal injection.
+    #
+    # @private
     def element( i )
       Diagonal.new @value.element( i ), @index0, @index1, @index2, @initial,
         @block, @var1, @var2
@@ -161,7 +168,7 @@ module Hornetseye
 
     # Check whether this term is compilable
     #
-    # @return [FalseClass,TrueClass] Returns whether this term is compilable.
+    # @return [Boolean] Returns whether this term is compilable.
     #
     # @private
     def compilable?

data/lib/multiarray/element.rb

@@ -32,15 +32,24 @@ module Hornetseye
         construct *ptr.load( self )
       end
 
+      # Construct new object from arguments
+      #
+      # @param [Array<Object>] *args Arguments for constructor.
+      #
+      # @return [Element] New object of this type.
+      #
+      # @private
       def construct( *args )
         new *args
       end
 
       # Type coercion for native elements
       #
-      # @param [Node] other Other native datatype to coerce with.
+      # @param [Class] other Other native datatype to coerce with.
+      #
+      # @return [Class] Result of coercion.
       #
-      # @return [Array<Node>] Result of coercion.
+      # @private
       def coercion( other )
         if self == other
           self
@@ -107,7 +116,7 @@ module Hornetseye
 
     # Check whether this term is compilable
     #
-    # @return [FalseClass,TrueClass] Returns whether this term is compilable.
+    # @return [Boolean] Returns whether this term is compilable.
     #
     # @private
     def compilable?
@@ -118,6 +127,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] Returns +self+.
+    #
+    # @private
     def skip( index, start )
       self
     end
@@ -125,6 +142,8 @@ module Hornetseye
     # Get value of this native element
     #
     # @return [Object] Value of this native element.
+    #
+    # @private
     def get
       @value
     end
@@ -134,6 +153,8 @@ module Hornetseye
     # @param [Object] value New value for native element.
     #
     # @return [Object] Returns +value+.
+    #
+    # @private
     def store( value )
       if @value.respond_to? :store
         @value.store value.simplify.get
@@ -155,6 +176,11 @@ module Hornetseye
       ptr.save self
     end
 
+    # Get array with components of this value
+    #
+    # @return [Array<Object>] Get array with value of this object as single element.
+    #
+    # @private
     def values
       [ @value ]
     end

data/lib/multiarray/elementwise.rb

@@ -54,6 +54,11 @@ module Hornetseye
         inspect
       end
 
+      # Check whether objects of this class are finalised computations
+      #
+      # @return [Boolean] Returns +false+.
+      #
+      # @private
       def finalised?
         false
       end
@@ -80,9 +85,9 @@ module Hornetseye
         "(#{@values.collect { |value| value.descriptor( hash ) }.join ','})"
     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
@@ -139,6 +144,15 @@ module Hornetseye
            self.class.new( *stripped.collect { |elem| elem[ 2 ] } )
     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] Returns element-wise operation with elements skipped on each
+    #         operand.
+    #
+    # @private
     def skip( index, start )
       skipped = *@values.collect { |value| value.skip( index, start ) }
       self.class.new( *skipped ).demand
@@ -149,6 +163,8 @@ module Hornetseye
     # @param [Integer,Node] i Index of desired element.
     #
     # @return [Node,Object] Element of unary operation.
+    #
+    # @private
     def element( i )
       values = @values.collect do |value|
         value.dimension == 0 ? value : value.element( i )
@@ -156,6 +172,14 @@ module Hornetseye
       self.class.new( *values ).demand
     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 )
       values = @values.collect do |value|
         value.dimension == 0 ? value : value.slice( start, length )
@@ -163,6 +187,11 @@ module Hornetseye
       self.class.new( *values ).demand
     end
 
+    # Decompose composite elements
+    #
+    # This method decomposes composite elements into array.
+    #
+    # @return [Node] Result of decomposition.
     def decompose
       values = @values.collect { |value| value.decompose }
       self.class.new( *values ).demand
@@ -170,7 +199,7 @@ module Hornetseye
 
     # Check whether this term is compilable
     #
-    # @return [FalseClass,TrueClass] Returns whether this term is compilable.
+    # @return [Boolean] Returns whether this term is compilable.
     #
     # @private
     def compilable?

data/lib/multiarray/float.rb

@@ -23,18 +23,40 @@ module Hornetseye
 
       attr_accessor :double
 
+      # Memory type required to store elements of this type
+      #
+      # @return [Class] Returns +Malloc+.
+      #
+      # @private
       def memory
         Malloc
       end
 
+      # Get storage size to store an element of this type
+      #
+      # @return [Integer] Returns +4+ or +8+.
+      #
+      # @private
       def storage_size
         double ? 8 : 4
       end
 
+      # Get default value for elements of this type
+      #
+      # @return [Object] Returns +0.0+.
+      #
+      # @private
       def default
         0.0
       end
 
+      # Compute balanced type for binary operation
+      #
+      # @param [Class] other Other native datatype to coerce with.
+      #
+      # @return [Class] Result of coercion.
+      #
+      # @private
       def coercion( other )
         if other < FLOAT_
           Hornetseye::FLOAT( ( double or other.double ) )
@@ -45,6 +67,13 @@ module Hornetseye
         end
       end
 
+      # Type coercion for native elements
+      #
+      # @param [Class] other Other type to coerce with.
+      #
+      # @return [Array<Class>] Result of coercion.
+      #
+      # @private
       def coerce( other )
         if other < FLOAT_
           return other, self
@@ -55,63 +84,118 @@ module Hornetseye
         end
       end
 
+      # Convert to type based on floating point numbers
+      #
+      # @return [Class] Corresponding type based on floating point numbers.
+      #
+      # @private
       def float
         self
       end
 
+      # Directive for packing/unpacking elements of this type
+      #
+      # @return [String] Returns 'f' or 'd'.
+      #
+      # @private
       def directive
         double ? 'd' : 'f'
       end
 
+      # Return string with information about this class.
+      #
+      # @return [String] Returns a string (e.g. "SFLOAT").
       def inspect
         "#{ double ? 'D' : 'S' }FLOAT"
       end
 
+      # Get unique descriptor of this class
+      #
+      # @param [Hash] hash Labels for any variables.
+      #
+      # @return [String] Descriptor of this class.
+      #
+      # @private
       def descriptor( hash )
         inspect
       end
 
+      # Test equality of classes
+      #
+      # @param [Object] other Object to compare with.
+      #
+      # @return [Boolean] Boolean indicating whether classes are equal.
       def ==( other )
         other.is_a? Class and other < FLOAT_ and double == other.double
       end
 
+      # Compute hash value for this class.
+      #
+      # @return [Fixnum] Hash value
+      #
+      # @private
       def hash
         [ :FLOAT_, double ].hash
       end
 
+      # Equality for hash operations
+      #
+      # @param [Object] other Object to compare with.
+      #
+      # @return [Boolean] Returns +true+ if objects are equal.
+      #
+      # @private
       def eql?( other )
         self == other
       end
 
     end
 
-  end
-
-  module Match
-
-    def fit( *values )
-      if values.all? { |value| value.is_a? Float or value.is_a? Integer }
-        if values.any? { |value| value.is_a? Float }
-          DFLOAT
+    module Match
+
+      # Method for matching elements of type FLOAT_
+      #
+      # @param [Array<Object>] *values Values to find matching native element
+      #        type for.
+      #
+      # @return [Class] Native type fitting all values.
+      #
+      # @see FLOAT_
+      #
+      # @private
+      def fit( *values )
+        if values.all? { |value| value.is_a? Float or value.is_a? Integer }
+          if values.any? { |value| value.is_a? Float }
+            DFLOAT
+          else
+            super *values
+          end
         else
           super *values
         end
-      else
-        super *values
       end
-    end
 
-    def align( context )
-      if self < FLOAT_ and context < FLOAT_
-        context
-      else
-        super context
+      # Perform type alignment
+      #
+      # Align this type to another. This is used to prefer single-precision
+      # floating point in certain cases.
+      #
+      # @param [Class] context Other type to align with.
+      #
+      # @private
+      def align( context )
+        if self < FLOAT_ and context < FLOAT_
+          context
+        else
+          super context
+        end
       end
+
     end
 
-  end
+    Node.extend Match
 
-  Node.extend Match
+  end
 
   SINGLE = false
   DOUBLE = true
@@ -127,12 +211,30 @@ module Hornetseye
   SFLOAT = FLOAT SINGLE
   DFLOAT = FLOAT DOUBLE
 
+  # Shortcut for constructor
+  #
+  # The method calls +SFLOAT.new+.
+  #
+  # @param [Float] value Floating point value.
+  #
+  # @return [SFLOAT] The wrapped floating point value.
+  #
+  # @private
   def SFLOAT( value )
     SFLOAT.new value
   end
 
   module_function :SFLOAT
 
+  # Shortcut for constructor
+  #
+  # The method calls +DFLOAT.new+.
+  #
+  # @param [Float] value Floating point value.
+  #
+  # @return [DFLOAT] The wrapped floating point value.
+  #
+  # @private
   def DFLOAT( value )
     DFLOAT.new value
   end

data/lib/multiarray/gccfunction.rb

@@ -21,40 +21,30 @@ module Hornetseye
 
     class << self
 
-      def run( retval, block )
+      def run( block )
         keys, values, term = block.strip
-        labels = Hash[ *keys.
-                       zip( ( 0 ... keys.size ).to_a ).flatten ]
-        retval_keys, retval_values, retval_term = retval.strip
-        retval_labels = Hash[ *retval_keys.
-                              zip( ( 0 ... retval_keys.size ).to_a ).flatten ]
-        method_name = ( '_' + retval_term.descriptor( retval_labels ) +
-                        '_' + term.descriptor( labels ) ).
-                      tr( '(),+\-*/%.@?~&|^<=>',
-                          '0123\456789ABCDEFGH' )
+        labels = Hash[ *keys.zip( ( 0 ... keys.size ).to_a ).flatten ]
+        method_name = ( '_' + term.descriptor( labels ) ).
+                            tr( '(),+\-*/%.@?~&|^<=>',
+                                '0123\456789ABCDEFGH' )
         unless GCCCache.respond_to? method_name
           GCCContext.build do |context|
-            function = new context, method_name,
-                           *( retval_keys + keys ).collect { |var| var.meta }
+            function = GCCFunction.new context, method_name,
+                                       *keys.collect { |var| var.meta }
             Thread.current[ :function ] = function
             term_subst = ( 0 ... keys.size ).collect do |i|
-              { keys[i] => function.param( i + retval_keys.size ) }
+              { keys[i] => function.param( i ) }
             end.inject( {} ) { |a,b| a.merge b }
-            retval_subst = ( 0 ... retval_keys.size ).collect do |i|
-              { retval_keys[ i ] => function.param( i ) }
-            end.inject( {} ) { |a,b| a.merge b }
-            # Thread.current[ :function ] = function
             Hornetseye::lazy do
-              retval_term.subst( retval_subst ).store term.subst( term_subst )
+              term.subst( term_subst ).demand
             end
             Thread.current[ :function ] = nil
             function.insn_return
             function.compile
           end
         end
-        args = ( retval_values + values ).collect { |arg| arg.values }.flatten
+        args = values.collect { |arg| arg.values }.flatten
         GCCCache.send method_name, *args
-        retval.simplify
       end
 
     end
@@ -81,7 +71,7 @@ module Hornetseye
 
     def variable( typecode, prefix )
       retval = GCCValue.new( self, id( prefix ) )
-      self << "#{indent}#{GCCType.new( typecode ).identifiers.first} #{retval};\n" # !!!
+      self << "#{indent}#{GCCType.new( typecode ).identifier} #{retval};\n"
       retval
     end
 

data/lib/multiarray/gcctype.rb

@@ -23,41 +23,47 @@ module Hornetseye
       @typecode = typecode
     end
 
-    def identifiers
+    def identifier
       case @typecode
       when nil
-        [ 'void' ]
+        'void'
       when BOOL
-        [ 'char' ]
+        'char'
       when BYTE
-        [ 'char' ]
+        'char'
       when UBYTE
-        [ 'unsigned char' ]
+        'unsigned char'
       when SINT
-        [ 'short int' ]
+        'short int'
       when USINT
-        [ 'unsigned short int' ]
+        'unsigned short int'
       when INT
-        [ 'int' ]
+        'int'
       when UINT
-        [ 'unsigned int' ]
+        'unsigned int'
       when SFLOAT
-        [ 'float' ]
-        when DFLOAT
-        [ 'double' ]
+        'float'
+      when DFLOAT
+        'double'
       else
         if @typecode < Pointer_
-          [ 'void *' ]
+          'void *'
         elsif @typecode < INDEX_
-          [ 'int' ]
-        elsif @typecode < Composite
-          GCCType.new( @typecode.element_type ).identifiers * @typecode.num_elements
+          'int'
         else
           raise "No identifier available for #{@typecode.inspect}"
         end
       end
     end
 
+    def identifiers
+      if @typecode < Composite
+        GCCType.new( @typecode.element_type ).identifiers * @typecode.num_elements
+      else
+        [ GCCType.new( @typecode ).identifier ]
+      end
+    end
+
     def r2c
       case @typecode
       when BOOL
@@ -68,7 +74,7 @@ module Hornetseye
         [ lambda { |expr| "NUM2DBL( #{expr} )" } ]
       else
         if @typecode < Pointer_
-          [ lambda { |expr| "(#{identifiers.first})mallocToPtr( #{expr} )" } ] # !!!
+          [ lambda { |expr| "(#{identifier})mallocToPtr( #{expr} )" } ]
         elsif @typecode < Composite
           GCCType.new( @typecode.element_type ).r2c * @typecode.num_elements
         else