carray 3.0.0 → 3.0.1

data/lib/carray/fuse_source.rb

@@ -0,0 +1,123 @@
+# ---------------------------------------------------------------------------
+#  Reading `CArray.fuse { a + b * c }`.
+#
+#  The block is not called.  Its `a` is the array itself, so calling it would
+#  evaluate the expression eagerly -- which is the thing fuse exists to avoid.
+#  The source is read instead, every name that holds a CArray is given `.lazy`,
+#  and the result is evaluated back in the block's own binding, so `self`,
+#  instance variables, methods and constants are what they were.
+#
+#  Ruby has no macro, so the alternative was to pass the arrays in and take
+#  shadows back -- `fuse(a, b) { |x, y| ... }` -- which names each of them
+#  twice.  Julia writes `@.` for the same reason and does the same thing to
+#  the expression underneath.
+# ---------------------------------------------------------------------------
+
+require "prism"
+
+class CArray
+
+  module FuseSource
+
+    # Runtime coercion, so the rewrite never has to work out what a name
+    # holds: anything that is not an array passes through untouched.
+    def self.shadow (value)
+      value.is_a?(CArray) ? value.lazy : value
+    end
+
+    def self.evaluate (block)
+      result = eval(rewrite(body_source(block)), block.binding,
+                    *block.source_location)
+      # An expression that is just an array is that array; the shadow put
+      # around it has nothing to fuse.
+      result.is_a?(CALazyMarker) ? result.parent : result
+    end
+
+    # -- the block's own text ---------------------------------------------
+
+    def self.body_source (block)
+      text = extract(block)
+      wrapped = "proc " + text
+      node = Prism.parse(wrapped).value
+                  .breadth_first_search { |n| n.is_a?(Prism::BlockNode) }
+      inner = node && node.body
+      unless inner
+        raise ArgumentError,
+              "CArray.fuse could not read an expression out of this block"
+      end
+      wrapped.byteslice(inner.location.start_offset...inner.location.end_offset)
+    end
+
+    def self.extract (block)
+      sequence = RubyVM::InstructionSequence.of(block) rescue nil
+      location = sequence && sequence.to_a[4][:code_location]
+      path     = sequence && (sequence.absolute_path || sequence.path)
+      unless location && path && File.readable?(path)
+        raise ArgumentError,
+              "CArray.fuse cannot read this block's source (defined in irb, " \
+              "eval, or a file that is no longer there).  Write `.lazy` on " \
+              "the operands instead: `a.lazy + b.lazy`."
+      end
+      lines = File.readlines(path)
+      first_line, first_column, last_line, last_column = location
+      # The columns count bytes, not characters, so a line with anything
+      # multi-byte on it slices in the wrong place unless this does too.
+      if first_line == last_line
+        lines[first_line - 1].byteslice(first_column...last_column)
+      else
+        [lines[first_line - 1].byteslice(first_column..),
+         *lines[first_line...(last_line - 1)],
+         lines[last_line - 1].byteslice(0...last_column)].join
+      end
+    end
+
+    # -- the rewrite -------------------------------------------------------
+
+    # The leaves are the names being read.  Everything else keeps its shape:
+    # calls are inserted around leaves and the expression they sit in is
+    # left alone.
+    class Leaves < Prism::Visitor
+      attr_reader :spots
+
+      def initialize
+        @spots = []
+      end
+
+      def visit_local_variable_read_node (node)    = mark(node)
+      def visit_instance_variable_read_node (node) = mark(node)
+      def visit_constant_read_node (node)          = mark(node)
+
+      # `Math::PI` is one name, not `Math` with something after it.
+      def visit_constant_path_node (node)
+        mark(node)
+      end
+
+      def visit_call_node (node)
+        if node.name == :[] || node.name == :[]=
+          # An index is a position, not a value to fuse: `a[i]` shadows `a`
+          # and leaves `i` alone.
+          visit(node.receiver)
+          return
+        end
+        mark(node) if node.receiver.nil? && node.arguments.nil? && node.block.nil?
+        super
+      end
+
+      private
+
+      def mark (node)
+        @spots << [node.location.start_offset, node.location.end_offset]
+      end
+    end
+
+    def self.rewrite (source)
+      visitor = Leaves.new
+      Prism.parse(source).value.accept(visitor)
+      out = source.dup
+      visitor.spots.sort_by { |start, _| -start }.each do |start, stop|
+        out[start...stop] = "::CArray::FuseSource.shadow(#{source[start...stop]})"
+      end
+      out
+    end
+  end
+end

data/lib/carray/fusion.rb

@@ -0,0 +1,218 @@
+# ---------------------------------------------------------------------------
+#  Turning a lazy expression into a plan a compiler can read.
+#
+#  A lazy view is already a typed, closed expression graph, and the kernels
+#  already carry the C that computes each operation (CArray.__kernel_body__).
+#  What is missing between them is the reading: which operation each node is,
+#  what its mask does, and where the leaves are.  That is what a plan holds.
+#
+#  Nothing here compiles anything.  A plan is plain data, and CArray itself
+#  never needs one -- it can always walk the view.  What a plan is for is a
+#  second evaluator: hand it to one, and the answer must be the same.
+# ---------------------------------------------------------------------------
+
+class CArray
+
+  module Fusion
+
+    # One value per node, in evaluation order; the last is the result.
+    #
+    #   Op    an operation, reading the nodes named in `args`
+    #   Leaf  an array, the `index`-th of plan.leaves
+    #   Const a scalar written into the expression
+    Op    = Struct.new(:kind, :name, :data_type, :args, :body, :mask, :trapping)
+    Leaf  = Struct.new(:index, :data_type, :masked)
+    Const = Struct.new(:value, :data_type)
+
+    Plan  = Struct.new(:nodes, :leaves, :data_type, :dim, :masked, :signature)
+
+    LAZY_CLASSES = [CAMonOp, CABinOp, CATriOp, CAMonCmp, CABinCmp, CALazyMarker]
+
+    # A lazy node names its operation by an id and the kernels name it by a
+    # symbol.  These are the same operations, spelled the way each side
+    # spells them; the rest are spelled alike.
+    BINOP_NAMES = {
+      :+  => :add,        :-  => :sub,        :*  => :mul,
+      :/  => :div,        :** => :power,      :%  => :mod,
+      :&  => :bit_and_i,  :|  => :bit_or_i,   :^  => :bit_xor_i,
+      :<< => :bit_lshift, :>> => :bit_rshift,
+    }.freeze
+    TRIOP_NAMES = { :__clip_ki__ => :clip }.freeze
+
+    MONOP_BY_ID = CArray::LAZY_MONOP_OP_IDS.invert.freeze
+    BINOP_BY_ID = CArray::LAZY_BINOP_OP_IDS.invert.freeze
+    TRIOP_BY_ID = CArray::LAZY_TRIOP_OP_IDS.invert.freeze
+
+    # Integer division and its relatives raise on a zero divisor, so a cell
+    # the mask excludes must not be computed at all -- the divisor there is
+    # nobody's business (ca_binop_dispatch.c).
+    TRAPPING = %i[div mod quo_i fmod].freeze
+    INTEGERS = %i[int8 int16 int32 int64 uint8 uint16 uint32 uint64].freeze
+
+    class Refused < StandardError; end
+
+    # ---- who computes a plan --------------------------------------------
+    #
+    # CArray can always walk the expression, so nothing has to be registered
+    # and nothing changes when nothing is.  What a registered evaluator adds
+    # is a second way to arrive at the same answer; it is asked, and it may
+    # decline.  The dispatch point stays on CArray's side, which is what
+    # keeps the threshold below a decision about CArray's own walk rather
+    # than one that moves with whatever is installed.
+    #
+    # The evaluator itself is held by CArray (see carray/lazy.rb), so that
+    # materialising an expression need not reach for this file at all until
+    # something has been registered.
+
+    # Reaching a compiled kernel costs about the same whatever the array's
+    # size, and what it buys is the passes the walk would make.  Below this
+    # the walk is the faster answer.  The crossing moves with how wide the
+    # expression is -- measured, thirty thousand cells at one operation, six
+    # thousand at six -- and this brackets those: a one-operation expression
+    # loses a couple of microseconds here, a six-operation one wins ten.
+    THRESHOLD = 10_000
+
+    # Returns the array, or nil where nothing computed it.
+    def self.evaluate (view)
+      return nil unless askable?(view)
+      out = CArray.__alloc_uninit__(view.data_type, view.dim)
+      evaluate_into(view, out) ? out : nil
+    end
+
+    # Fills an array the caller already has.  Called from the store as well,
+    # where making one and copying it over would be most of the work.
+    # Returns true when something computed it.
+    def self.evaluate_into (view, out)
+      evaluator = CArray.expression_evaluator or return false
+      return false unless askable?(view)
+      plan = plan(view) or return false
+      # A marker over an array, or anything else with nothing to compute,
+      # is not worth handing over.
+      return false unless plan.nodes.any? { |n| n.is_a?(Op) }
+      out.mask = 0 if plan.masked && ! out.has_mask?
+      evaluator.call(plan, out) ? true : false
+    rescue StandardError => error
+      CArray.expression_evaluator = nil
+      warn "CArray: the registered expression evaluator raised " \
+           "(#{error.class}: #{error.message}); expressions will be walked " \
+           "from here on"
+      false
+    end
+
+    def self.askable? (view)
+      ! CArray.expression_evaluator.nil? && view.elements >= THRESHOLD
+    end
+
+    # Returns a Plan, or nil where the expression holds something a plan
+    # cannot describe.  Refusing is ordinary: the caller walks instead.
+    def self.plan (view)
+      build(view)
+    rescue Refused
+      nil
+    end
+
+    def self.build (view)
+      raise Refused, "not a lazy expression" unless lazy?(view)
+      w = Walk.new
+      w.visit(view)
+      Plan.new(w.nodes, w.leaves, view.data_type, view.dim,
+               w.leaves.any? { |a| a.has_mask? }, w.signature)
+    end
+
+    def self.lazy? (x)
+      LAZY_CLASSES.any? { |k| x.is_a?(k) }
+    end
+
+    # ---- the walk -------------------------------------------------------
+
+    class Walk
+      attr_reader :nodes, :leaves, :signature
+
+      def initialize
+        @nodes = []
+        @leaves = []
+        @seen = {}
+        @signature = +""
+      end
+
+      def visit (n)
+        @seen[n.object_id] ||= build(n)
+      end
+
+      private
+
+      def build (n)
+        case n
+        when CALazyMarker then visit(n.parent)
+        when CAMonOp      then unary(n)
+        when CABinOp      then binary(n)
+        when CATriOp      then ternary(n)
+        when CScalar      then constant(n)
+        when CArray       then leaf(n)
+        else raise Refused, "#{n.class} in an expression"
+        end
+      end
+
+      def unary (n)
+        name = spell(MONOP_BY_ID, n.__op_id__, {})
+        args = [visit(n.parent)]
+        # A view over one array is masked exactly where that array is
+        # (ca_obj_monop.c).
+        op(:monop, name, n.data_type, args, :pass)
+      end
+
+      def binary (n)
+        name = spell(BINOP_BY_ID, n.__op_id__, BINOP_NAMES)
+        args = [visit(n.parent), visit(n.__binop_right__)]
+        # Boolean `&` and `|` are three-valued: a masked cell whose known
+        # side settles the answer comes back unmasked (ca_obj_binop.c).
+        rule = if n.data_type == :boolean && name == :bit_or_i  then :kleene_or
+               elsif n.data_type == :boolean && name == :bit_and_i then :kleene_and
+               else :union
+               end
+        op(:binop, name, n.data_type, args, rule)
+      end
+
+      def ternary (n)
+        name = spell(TRIOP_BY_ID, n.__op_id__, TRIOP_NAMES)
+        args = [visit(n.parent), visit(n.__triop_op2__), visit(n.__triop_op3__)]
+        op(:triop, name, n.data_type, args, :union)
+      end
+
+      def op (kind, name, type, args, mask)
+        body = CArray.__kernel_body__(kind, name, type) or
+          raise Refused, "#{kind} #{name} has no body at #{type}"
+        note(kind.to_s[0], name, type)
+        push Op.new(kind, name, type, args, body, mask,
+                    TRAPPING.include?(name) && INTEGERS.include?(type))
+      end
+
+      def leaf (n)
+        note("a", n.data_type, n.has_mask? ? 1 : 0)
+        @leaves << n
+        push Leaf.new(@leaves.size - 1, n.data_type, n.has_mask?)
+      end
+
+      def constant (n)
+        note("k", n[0], n.data_type)
+        push Const.new(n[0], n.data_type)
+      end
+
+      def push (node)
+        @nodes << node
+        @nodes.size - 1
+      end
+
+      def spell (table, id, renames)
+        ruby = table[id] or raise Refused, "operation id #{id}"
+        renames.fetch(ruby, ruby)
+      end
+
+      # Two expressions of the same shape compute alike, whatever arrays
+      # they are over, so a consumer can keep one compiled kernel for both.
+      def note (*parts)
+        @signature << parts.join(":") << ";"
+      end
+    end
+  end
+end

data/lib/carray/histogram.rb

@@ -94,8 +94,8 @@
 #  Each sample contributes `w[i]` instead of 1 to its target cell.
 #
 #  * **weights.shape** = chunk.shape minus the channel axis (= fiber + (A,)).
-#  * **dtype** is locked at construction (= the entry method's `weights:` kwarg
-#    fixes weighted vs unweighted; subsequent adds must match).  Counts dtype:
+#  * **The data type** is locked at construction (= the entry method's `weights:` kwarg
+#    fixes weighted vs unweighted; subsequent adds must match).  Counts type:
 #    int64 unweighted, float64 weighted.  Weighted counts are always float64:
 #    the fused scatter kernel requires float64 weights, so integer weights are
 #    taken as float64 (= integer weighted counts are not supported).
@@ -118,7 +118,7 @@
 #  ### Composition
 #
 #  `h1 + h2` returns a new Histogram with cells summed elementwise.  Both
-#  operands must agree on edges / fiber_shape / include_max / weighted dtype
+#  operands must agree on edges / fiber_shape / include_max / weighted data type
 #  (= the structure-level semantic guard); cells themselves are just
 #  integer / float tallies.  See the `+` method.
 #
@@ -135,7 +135,7 @@ class CArray
   # {BincountND} instead.
   class Histogram
 
-    # @overload initialize(edges:, fiber_shape: [], include_max: false, weights_dtype: nil)
+    # @overload initialize(edges:, fiber_shape: [], include_max: false, weights_data_type: nil)
     #   Allocates a new histogram accumulator.
     #   @param edges [Array<CArray, Array<Numeric>>] one edges array
     #     per histogram dimension; each must be 1-D sorted ascending
@@ -145,11 +145,11 @@ class CArray
     #   @param include_max [Boolean, Array<Boolean>] whether values
     #     equal to the last edge fold into the last bin; a scalar
     #     broadcasts across dimensions.
-    #   @param weights_dtype [Symbol, nil] `data_type` of the
+    #   @param weights_data_type [Symbol, nil] `data_type` of the
     #     accumulator when weighted; `nil` for a count-only
     #     accumulator (int64 counts).
     #   @return [Histogram]
-    def initialize (edges:, fiber_shape: [], include_max: false, weights_dtype: nil)
+    def initialize (edges:, fiber_shape: [], include_max: false, weights_data_type: nil)
       @edges_list = edges.map { |e| CArray.wrap_readonly(e, :float64) }
       raise ArgumentError, "edges must be a non-empty list" if @edges_list.empty?
       @edges_list.each_with_index do |e, k|
@@ -166,11 +166,11 @@ class CArray
                      else
                        [!!include_max] * @m
                      end
-      @weighted = !weights_dtype.nil?
-      @counts_dtype = @weighted ? weights_dtype : :int64
+      @weighted = !weights_data_type.nil?
+      @counts_data_type = @weighted ? weights_data_type : :int64
       ext_dims = @n_list.map { |n| n + 2 }
       ext_shape = @fiber_shape + ext_dims
-      @full_counts = CArray.public_send(@counts_dtype, *ext_shape).fill(0)
+      @full_counts = CArray.public_send(@counts_data_type, *ext_shape).fill(0)
       @sample_axis  = nil
       @channel_axis = nil
     end
@@ -321,7 +321,7 @@ class CArray
 
       if weights
         raise ArgumentError, "weights given but accumulator is unweighted" unless @weighted
-        weights = CArray.wrap_readonly(weights, @counts_dtype)
+        weights = CArray.wrap_readonly(weights, @counts_data_type)
         expected_w_shape = chunk.shape.dup
         expected_w_shape.delete_at(channel_ax)
         unless weights.shape == expected_w_shape
@@ -379,7 +379,7 @@ class CArray
                                edges: @edges_list,
                                fiber_shape: @fiber_shape,
                                include_max: @include_max,
-                               weights_dtype: @weighted ? @counts_dtype : nil)
+                               weights_data_type: @weighted ? @counts_data_type : nil)
       rf = result.instance_variable_get(:@full_counts)
       rf[] = @full_counts + other.full_counts
       result.instance_variable_set(:@sample_axis, @sample_axis)
@@ -401,7 +401,7 @@ class CArray
     # arr.shape = fiber_shape + (last M bin axes).
     # Reduce along the last M axes, returns shape fiber_shape (or scalar).
     #
-    # `accumulate` preserves dtype (= int64 stays int64, float64 stays float64),
+    # `accumulate` preserves the data type (= int64 stays int64, float64 stays float64),
     # unlike `sum` which always lifts to float64.  Caveat: int64 overflows at
     # ~9.2e18 (silent wrap); weighted float64 loses precision past 2^53 but
     # does not overflow.  Realistic histograms do not hit these limits.
@@ -497,15 +497,15 @@ class CArray
     [sample_ax, channel_ax].sort.reverse.each { |p| fiber_shape.delete_at(p) }
 
     # Weighted counts are float64-only (the fused scatter kernel requires
-    # float64 weights and float64 counts), so the dtype is fixed here rather
-    # than derived from the weights' own dtype.
-    weights_dtype = (:float64 if weights)
+    # float64 weights and float64 counts), so the type is fixed here rather
+    # than derived from the weights' own type.
+    weights_data_type = (:float64 if weights)
 
     h = Histogram.send(:new,
                       edges: edges,
                       fiber_shape: fiber_shape,
                       include_max: include_max,
-                      weights_dtype: weights_dtype)
+                      weights_data_type: weights_data_type)
     h.add(arr, axis: axis, weights: weights)
     h
   end

data/lib/carray/inspect.rb

@@ -49,13 +49,7 @@ class CArray::Inspector  # :nodoc:
   end
 
   def get_shape
-    case @carray.obj_type
-    when CA_OBJ_UNBOUND_REPEAT
-      dim = @carray.spec
-    else
-      dim = @carray.shape
-    end
-    return dim
+    return @carray.shape
   end
 
   def get_info_list

data/lib/carray/iterator.rb

@@ -14,8 +14,8 @@
 #  those are NOT part of the common contract because some members legitimately
 #  omit them (a window has no map, a group has no within-piece min_index).
 #
-#  The retired 2.0 generic dispatch (calculate / filter / evaluate over a
-#  kernel_at_addr slot) is preserved at `samples/caiterator/iterator.{rb,c}`.
+#  The 2.0 generic dispatch (calculate / filter / evaluate over a
+#  kernel_at_addr slot) was retired in 3.0.
 #
 # ----------------------------------------------------------------------------
 
@@ -37,7 +37,8 @@ class CAIterator
   # A member that genuinely cannot provide one overrides it to raise with its
   # own reason.
   [
-    :sum, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,   # tier 1
+    :sum, :accumulate, :prod, :mean, :min, :max,                      # tier 1
+    :variance, :stddev, :all, :any,
     :variancep, :stddevp, :minmax,                                    # tier 2
     :min_index, :max_index, :min_addr, :max_addr,                     # position
     :wsum, :wmean,                                                    # weighted