carray 3.0.2 → 3.0.4

data/lib/carray/frame/windows.rb

@@ -0,0 +1,117 @@
+# CAFrame windows bounded by a width of a key column.
+
+class CAFrame
+  # Moving windows bounded by a width of the key column +on+ (a time, a
+  # duration or a number) instead of a count of rows: the window of a row
+  # whose key is t holds the rows whose key lies between t - before and
+  # t + after.  +exclude:+ leaves out the lower end (default), the upper end,
+  # both or neither, as CArray#is_between does.  +by:+ names columns that
+  # must match exactly, so each window stays within one station; +interval:+
+  # gives the key's grid step for WindowedFrame#is_complete.  The rows need
+  # not be sorted; the answers come in row order.  A row whose key is
+  # masked, NaN or infinite is in no window and has no window.
+  #
+  #   w = df.windows(on: "time", before: "1 hour", by: "station")
+  #   w.mean("temp")     # => CArray, one value per row
+  #   w.mean             # => frame of the windowed mean of every column
+  #   w.elements         # => the number of rows in each window
+  #
+  # Given +at:+, the windows sit at those points of the key instead of at
+  # the rows, and every answer is one per point: a frame of the reductions
+  # has a row per point, the points as its index and the on: column's name
+  # as its row axis name.  The points need not be sorted or on the rows'
+  # keys.  A grid of points gives windows on a grid; a window with no row
+  # answers as an empty reduction does (+mean+ UNDEF, +count+ 0).  +at:+
+  # cannot be given with +by:+.
+  #
+  #   grid = CArray.time_range(t0, t1, unit: "1 hour")
+  #   df.windows(on: "time", at: grid, after: "3 hours", exclude: :upper).mean
+  #   # => a frame with a row per hour, the mean over [t, t + 3 hours)
+  #
+  # @return [WindowedFrame]
+  def windows (on:, before: nil, after: nil, exclude: :lower, by: nil, interval: nil, at: nil)
+    on_name  = column_key(on, "windows")
+    key      = key_column(on_name, "windows")
+    by_names = by.nil? ? [] : column_keys(by.is_a?(Array) ? by : [by], "windows")
+    by_cols  = by_names.map { |b| key_column(b, "windows") }
+    # The points are taken as they are now: a later write to the array
+    # given changes neither the windows nor a result's index.
+    at = at.copy if at.is_a?(CArray)
+    plan = CAKeyWindowIterator.new(CArray.int64(nrow).seq, on: key,
+                                   before: before, after: after, exclude: exclude,
+                                   by: by_cols.empty? ? nil : by_cols,
+                                   interval: interval, at: at)
+    WindowedFrame.new(self, plan, [on_name, *by_names], at: at)
+  end
+end
+
+# The windows of a CAFrame (CAFrame#windows): the reductions over each row's
+# window, one answer per row, and what each window covered.
+class WindowedFrame
+  include CAFrame::ColumnVerbs
+
+  def initialize (frame, plan, key_names, at: nil)
+    @frame     = frame
+    @plan      = plan
+    @key_names = key_names
+    @at        = at
+  end
+
+  # @overload [](name)
+  #   Returns the CAKeyWindowIterator of one column.
+  #   @return [CAKeyWindowIterator]
+  def [] (name)
+    @plan.for_value(@frame[@frame.__send__(:column_key, name, "windows")])
+  end
+
+  # What each window covered, one value per row: see CAKeyWindowIterator.
+  [:first_addr, :last_addr, :first_key, :last_key, :elements, :is_complete].each do |m|
+    define_method(m, &Ractor.make_shareable(proc { @plan.public_send(m) }))
+  end
+
+  # @overload bounds
+  #   Returns the range each window was asked to cover, as two arrays of the
+  #   key's kind.
+  #   @return [Array(CArray, CArray)]
+  def bounds
+    @plan.bounds
+  end
+
+  # The windowed reductions.  Without names, a frame of every column whose
+  # type has the reduction (the on: and by: columns left out), on the
+  # frame's rows and index; given names, the CArray (one) or the Array of
+  # them (several), as +df[...]+ returns columns.
+  CArray.send(:define_named_methods, self,
+              [:sum, :mean, :min, :max, :prod, :accumulate, :median,
+               :variance, :stddev, :variancep, :stddevp], :window_reduction)
+
+  CArray.send(:define_named_methods, self,
+              [:first, :last, :nunique, :count, :all, :any], :window_value)
+
+  private
+
+  def window_reduction (reduction, *names, min_count: nil, fill_value: nil)
+    window_reduce(reduction, names, min_count: min_count, fill_value: fill_value)
+  end
+
+  def window_value (reduction, *names)
+    window_reduce(reduction, names)
+  end
+
+  # An N-D column (each row a profile) is reduced along the rows, each
+  # window keeping the trailing shape, as a group reduces it.
+  def window_reduce (reduction, names, **keywords)
+    keywords = keywords.compact
+    out = over_named_columns(reduction, names, @key_names) do |col|
+      @plan.for_value(col).public_send(reduction, **keywords)
+    end
+    return out unless names.empty?
+    if @at
+      # Each result has an index of its own, as a group's result has.
+      key = @frame.__send__(:key_column, @key_names.first, "windows")
+      CAFrame.new(out, axis_name: @key_names.first, index: CAFrame.__send__(:key_labels, key, @at.copy))
+    else
+      CAFrame.new(out, axis_name: @frame.axis_name, index: @frame.index)
+    end
+  end
+end

data/lib/carray/frame.rb

@@ -6,11 +6,15 @@
 # devel/MEMO_DATAFRAME_ON_CARRAY.md for the design.
 
 require 'carray/frame/frame'
+require 'carray/frame/column_verbs'
 require 'carray/frame/verbs'
 require 'carray/frame/convert'
 require 'carray/frame/io'
 require 'carray/frame/records'
 require 'carray/frame/group'
 require 'carray/frame/join'
+require 'carray/frame/windows'
 require 'carray/frame/concat'
 require 'carray/frame/sort'
+require 'carray/frame/reshape'
+require 'carray/frame/describe'

data/lib/carray/fuse_source.rb

@@ -11,6 +11,12 @@
 #  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.
+#
+#  Reading and rewriting a block gives the same text every time it is
+#  called, so it is done once per block -- per place in the source -- and
+#  kept.  What is kept is a lambda that takes the block's free locals as
+#  arguments and is run with the block's `self`; a call only reads the
+#  locals.
 # ---------------------------------------------------------------------------
 
 require "prism"
@@ -26,13 +32,117 @@ class CArray
     end
 
     def self.evaluate (block)
-      result = eval(rewrite(body_source(block)), block.binding,
-                    *block.source_location)
+      result = compiled(block).call(block)
       # 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
 
+    # -- one compiled form per block --------------------------------------
+
+    # Keyed by the block's instruction sequence, which is the same object
+    # every time the same block is called and a different one for each
+    # block, even two on one line.  Where Ruby has weak keys, a block whose
+    # code is unloaded takes its entry with it.
+    def self.new_sites
+      defined?(ObjectSpace::WeakKeyMap) ? ObjectSpace::WeakKeyMap.new
+                                        : {}.compare_by_identity
+    end
+    SITES = new_sites
+
+    # A Ractor other than the main one keeps its own table, and evaluates
+    # every block in its frame: the empty scope a lambda is compiled in is
+    # the top of a file, which only the main Ractor has.
+    def self.compiled (block)
+      site = RubyVM::InstructionSequence.of(block)
+      return compile(block) unless site
+      sites = Ractor.current == Ractor.main ? SITES : (Ractor.current[:carray_fuse_sites] ||= new_sites)
+      sites[site] || (sites[site] = compile(block))
+    end
+
+    # The block's free locals, handed to a lambda that was compiled without
+    # them.  `self` is the block's own, so instance variables and methods
+    # are what they were.
+    Compiled = Struct.new(:locals, :lambda) do
+      def call (block)
+        scope = block.binding
+        values = locals.map { |name| scope.local_variable_get(name) }
+        scope.receiver.instance_exec(*values, &lambda)
+      end
+    end
+
+    # A block that needs its own frame -- it assigns to a local outside it,
+    # or yields, or asks for its binding -- is evaluated there every time;
+    # only the rewrite is kept.
+    InFrame = Struct.new(:text, :file, :line) do
+      def call (block)
+        eval(text, block.binding, file, line)
+      end
+    end
+
+    # Calls that mean something only in the frame they are made from.
+    FRAME_BOUND = %i[binding local_variables block_given? __method__ __dir__
+                     eval].freeze
+
+    FRAME_BOUND_NODES = [Prism::YieldNode, Prism::SuperNode,
+                         Prism::ForwardingSuperNode, Prism::ReturnNode,
+                         Prism::BreakNode, Prism::NextNode,
+                         Prism::RedoNode].freeze
+
+    def self.compile (block)
+      body = body_source(block)
+      text = rewrite(body)
+      file, line = block.source_location
+      scope = block.binding
+      locals, needs_frame = free_locals(body, scope.local_variables)
+      return InFrame.new(text, file, line) if needs_frame || Ractor.current != Ractor.main
+      Compiled.new(locals, compile_lambda(text, locals, scope, file, line))
+    end
+
+    # Read on its own, a body names a local from outside as a call with no
+    # receiver and no arguments, so every one of them is found this way.  A
+    # body that assigns to one has to keep its frame.
+    def self.free_locals (body, outer)
+      reads = []
+      needs_frame = false
+      Prism.parse(body).value.breadth_first_search do |node|
+        case node
+        when Prism::CallNode
+          reads << node.name if node.variable_call? && outer.include?(node.name)
+          needs_frame = true if node.receiver.nil? && FRAME_BOUND.include?(node.name)
+        when *FRAME_BOUND_NODES
+          needs_frame = true
+        else
+          if node.class.name.match?(/\APrism::LocalVariable\w*(Write|Target)Node\z/) &&
+             outer.include?(node.name)
+            needs_frame = true
+          end
+        end
+        false
+      end
+      [reads.uniq, needs_frame]
+    end
+
+    # Constants resolve as they do where the block was written: each module
+    # it sits in is reopened around the lambda, outermost first.  The
+    # refinements active there are activated again.  None of it sees the
+    # frame of the call that compiles it.
+    def self.compile_lambda (text, locals, scope, file, line)
+      nesting = scope.eval("Module.nesting").reverse
+      refinements = scope.eval("Module.used_modules")
+      Thread.current[:__carray_fuse_scope__] = [nesting, refinements]
+      code = refinements.each_index.map { |i|
+        "using Thread.current[:__carray_fuse_scope__][1][#{i}];"
+      }.join + "lambda { |#{locals.join(", ")}| #{text}\n}"
+      (nesting.size - 1).downto(0) do |i|
+        code = "Thread.current[:__carray_fuse_scope__][0][#{i}]" \
+               ".module_eval(#{code.dump}, #{file.dump}, #{line})"
+      end
+      EMPTY_SCOPE.call.eval(code, file, line)
+    ensure
+      Thread.current[:__carray_fuse_scope__] = nil
+    end
+
     # -- the block's own text ---------------------------------------------
 
     def self.body_source (block)
@@ -121,3 +231,9 @@ class CArray
     end
   end
 end
+
+# A scope with no locals and no refinements in it, for compiling a block's
+# expression where it can neither see nor hold on to the frame of the call
+# that happens to compile it.  Both are true only of the top of a file.
+CArray::FuseSource::EMPTY_SCOPE = -> { binding }
+CArray::FuseSource.private_constant :EMPTY_SCOPE

data/lib/carray/fusion.rb

@@ -2,7 +2,9 @@
 #  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__).
+#  already carry the C that computes each operation (CArray.__kernel_body__,
+#  with CArray.__kernel_helpers__ for the functions a body calls beyond the
+#  C standard library).
 #  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.
 #
@@ -17,16 +19,54 @@ class CArray
 
     # 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)
+    #   Op      an operation, reading the nodes named in `args`
+    #   Leaf    an array, the `index`-th of plan.leaves, read at the cell
+    #           being computed
+    #   Shifted the same, read `offset` cells away along each axis -- what
+    #           CArray#shift makes.  A cell that falls outside the array is
+    #           `fill` where `bounds` says :fill and masked where it says
+    #           :mask.  `masked` says whether the array itself has a mask.
+    #   Const   a scalar written into the expression
+    #
+    # A Shifted node reads cells other than the one being computed, so an
+    # evaluator that writes its output over one of the plan's leaves must
+    # not compute one that is read shifted: a cell it reads may already
+    # have been written.
+    #
+    # A comparison's body is the one for the data type it compares; what it
+    # answers is boolean, which is the node's data_type.
+    # An Op's fields:
+    #
+    #   kind       :monop, :binop, :triop, :moncmp or :bincmp
+    #   name       the operation as the kernels name it (:add, :sqrt, :ipow)
+    #   args       indices of the nodes it reads, in operand order
+    #   body       its C, from CArray.__kernel_body__: `#1`, `#2`, ... are
+    #              the operands and the next number is the result; `<type>`
+    #              is CArray's name for the type (float64_t)
+    #   mask       how the result is masked: :pass (as its one operand),
+    #              :union (where any operand is), :kleene_or / :kleene_and
+    #              (boolean | and &, unmasked where the known side settles it),
+    #              :select (where the first operand is, else where the
+    #              operand it chooses is: the second where it is true, the
+    #              third where it is false)
+    #   trapping   true where a masked cell must not be computed at all
+    #
+    # What a reader may rely on: the node classes, the kinds, the names, the
+    # mask rules and the fields above keep the meaning they have here.  New
+    # ones are added -- a node class, a kind, an operation, a mask rule --
+    # and an evaluator that meets one it does not know declines the plan
+    # (returns false).  It does not raise: raising takes it out of service
+    # for the rest of the process.  Declining is what lets CArray add to
+    # the plan without a new evaluator being released at the same time.
+    Op      = Struct.new(:kind, :name, :data_type, :args, :body, :mask, :trapping)
+    Leaf    = Struct.new(:index, :data_type, :masked)
+    Shifted = Struct.new(:index, :data_type, :masked, :offset, :bounds, :fill)
+    Const   = Struct.new(:value, :data_type)
 
     Plan  = Struct.new(:nodes, :leaves, :data_type, :dim, :masked, :signature)
 
     LAZY_CLASSES = [CAMonOp, CABinOp, CATriOp, CAMonCmp, CABinCmp, CALazyMarker]
+    Ractor.make_shareable(LAZY_CLASSES)
 
     # 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
@@ -37,17 +77,21 @@ class CArray
       :&  => :bit_and_i,  :|  => :bit_or_i,   :^  => :bit_xor_i,
       :<< => :bit_lshift, :>> => :bit_rshift,
     }.freeze
-    TRIOP_NAMES = { :__clip_ki__ => :clip }.freeze
+    TRIOP_NAMES = { :clamp_between => :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
+    # A Float or Complex array to an Integer power is its own node, ipow,
+    # which `**` makes and no table above names.
+    BINOP_BY_ID = CArray::LAZY_BINOP_OP_IDS.invert
+                    .merge(CABinOp::OP_IPOWER => :ipow).freeze
+    # The lazy then_else is its own triop, select, which no method names.
+    TRIOP_BY_ID = CArray::LAZY_TRIOP_OP_IDS.invert
+                    .merge(CATriOp::OP_SELECT => :select).freeze
+    MONCMP_BY_ID = CArray::LAZY_MONCMP_OP_IDS.invert.freeze
+    # The table holds both spellings of each comparison (`lt` and `<`); the
+    # kernels are named by the word.
+    BINCMP_BY_ID = CArray::LAZY_BINCMP_OP_IDS
+                     .select { |name, _| name.to_s.match?(/\A[a-z]/) }.invert.freeze
 
     class Refused < StandardError; end
 
@@ -74,29 +118,100 @@ class CArray
 
     # 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
+      plan = worth_asking(view) or return nil
+      out = CArray.__alloc_uninit__(view.data_type, view.shape)
+      ask(plan, 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)
+      plan = worth_asking(view) or return false
+      ask(plan, out)
+    end
+
+    # The plan to hand over, or nil.  A marker over an array, or anything
+    # else with nothing to compute, is not worth handing over.  Nothing here
+    # is the evaluator's doing, so nothing here retires it: an array that
+    # raises when it is looked at (a CAObject whose backing is gone) raises
+    # again in the walk, where the caller sees it.
+    def self.worth_asking (view)
+      return nil unless askable?(view)
+      plan = plan(view) or return nil
+      plan.nodes.any? { |n| n.is_a?(Op) } ? plan : nil
+    rescue StandardError
+      nil
+    end
+
+    def self.ask (plan, 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
+      return false if overlaps?(plan, out)
+      return false unless ready_mask(plan, out)
+      begin
+        evaluator.call(plan, out) ? true : false
+      rescue AddressBasis::Failure
+        # Raised by CArray lending the arrays or taking them back: a refusal,
+        # or an array that cannot be read.  The walk meets the same array.
+        false
+      rescue StandardError => error
+        retire(error)
+        false
+      end
+    end
+
+    # The walk leaves the destination masked where the expression is, so a
+    # destination that arrives masked loses its mask to an expression that
+    # has none.  A destination that cannot hold a mask (a value array) is
+    # left to the walk, which says so.
+    def self.ready_mask (plan, out)
+      if plan.masked
+        out.mask = 0 unless out.has_mask?
+      elsif out.has_mask?
+        out.mask = 0
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    # Whether the destination shares storage with a leaf it would read.  An
+    # evaluator computes cell by cell, so writing a cell another leaf reads
+    # later -- `z[] = y + y` with z and y overlapping slices of one array --
+    # reads what it has just written.  The walk reads every operand before
+    # it writes.  The destination itself as a leaf is fine as long as it is
+    # read at the cell being written, not shifted.
+    def self.overlaps? (plan, out)
+      mine = storages(out)
+      shifted = plan.nodes.grep(Shifted).map(&:index)
+      plan.leaves.each_with_index.any? do |leaf, index|
+        if leaf.equal?(out)
+          shifted.include?(index)
+        else
+          storages(leaf).any? { |r| mine.any? { |m| m.send(:storage_overlaps?, r) } }
+        end
+      end
+    end
+
+    # The arrays that hold an array's cells: its root, or each parent's
+    # where a view stands over several.  Two of them share storage when
+    # they are one array, or entities whose memory overlaps (an array and a
+    # wrap_memory_view of it).
+    def self.storages (array, found = [])
+      root = array.root_array
+      if ! root.entity? && root.respond_to?(:parents)
+        root.parents.each { |parent| storages(parent, found) }
+      else
+        found << root
+      end
+      found
+    end
+
+    def self.retire (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)
@@ -115,8 +230,9 @@ class CArray
       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)
+      masked = w.leaves.any? { |a| a.has_mask? } ||
+               w.nodes.any? { |n| n.is_a?(Shifted) && n.bounds.include?(:mask) }
+      Plan.new(w.nodes, w.leaves, view.data_type, view.shape, masked, w.signature)
     end
 
     def self.lazy? (x)
@@ -131,6 +247,7 @@ class CArray
       def initialize
         @nodes = []
         @leaves = []
+        @leaf_index = {}
         @seen = {}
         @signature = +""
       end
@@ -147,6 +264,9 @@ class CArray
         when CAMonOp      then unary(n)
         when CABinOp      then binary(n)
         when CATriOp      then ternary(n)
+        when CAMonCmp     then unary_comparison(n)
+        when CABinCmp     then binary_comparison(n)
+        when CAShift      then shifted(n)
         when CScalar      then constant(n)
         when CArray       then leaf(n)
         else raise Refused, "#{n.class} in an expression"
@@ -154,11 +274,24 @@ class CArray
       end
 
       def unary (n)
+        return conversion(n) if n.__op_id__ >= CAMonOp::CAST_BASE
         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)
+        op(:monop, name, n.data_type, args, :pass, n.__trapping__)
+      end
+
+      # A cast node is named by the type it converts to, cast_<data_type>,
+      # and its body is keyed by the type it converts from.
+      def conversion (n)
+        from = n.parent.data_type
+        name = :"cast_#{n.data_type}"
+        body = CArray.__kernel_body__(:monop, name, from) or
+          raise Refused, "monop #{name} has no body at #{from}"
+        args = [visit(n.parent)]
+        note("c", name, from, args.join(","))
+        push Op.new(:monop, name, n.data_type, args, body, :pass, n.__trapping__)
       end
 
       def binary (n)
@@ -170,32 +303,112 @@ class CArray
                elsif n.data_type == :boolean && name == :bit_and_i then :kleene_and
                else :union
                end
-        op(:binop, name, n.data_type, args, rule)
+        op(:binop, name, n.data_type, args, rule, n.__trapping__)
       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)
+        # select is masked where its condition is, or where the branch the
+        # condition chooses is (ca_obj_triop.c).
+        rule = name == :select ? :select : :union
+        op(:triop, name, n.data_type, args, rule, n.__trapping__)
+      end
+
+      # A comparison is masked where its operands are (ca_obj_moncmp.c,
+      # ca_obj_bincmp.c): there is no three-valued comparison.
+      def unary_comparison (n)
+        name = spell(MONCMP_BY_ID, n.__op_id__, {})
+        operand = n.parent
+        args = [visit(operand)]
+        comparison(:moncmp, name, operand.data_type, args, :pass, n.__trapping__)
+      end
+
+      def binary_comparison (n)
+        name = spell(BINCMP_BY_ID, n.__op_id__, {})
+        right = n.__bincmp_right__
+        # Both sides are already of the type compared (CABinCmp casts one
+        # to the other); a pair that is not has no single body.
+        unless n.parent.data_type == right.data_type
+          raise Refused, "#{name} between #{n.parent.data_type} and #{right.data_type}"
+        end
+        args = [visit(n.parent), visit(right)]
+        comparison(:bincmp, name, n.parent.data_type, args, :union, n.__trapping__)
       end
 
-      def op (kind, name, type, args, mask)
+      # `trapping`: the node skips the cells its operands mask rather than
+      # computing them -- one that can raise on a cell or calls Ruby for it.
+      # Each lazy view answers it from the rule its own kernel follows.
+      def comparison (kind, name, compared, args, mask, trapping)
+        body = CArray.__kernel_body__(kind, name, compared) or
+          raise Refused, "#{kind} #{name} has no body at #{compared}"
+        # A body written against its compared type or a tolerance (`feq`)
+        # needs more than its operands substituted.
+        if body.match?(/<\w+>|\btol\b/)
+          raise Refused, "#{kind} #{name} needs more than its operands"
+        end
+        note(kind.to_s[0..3], name, compared, args.join(","))
+        push Op.new(kind, name, :boolean, args, body, mask, trapping)
+      end
+
+      def op (kind, name, type, args, mask, trapping)
         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))
+        note(kind.to_s[0], name, type, args.join(","))
+        push Op.new(kind, name, type, args, body, mask, trapping)
       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?)
+        index = leaf_index(n)
+        note("a", index, n.data_type, n.has_mask? ? 1 : 0)
+        push Leaf.new(index, n.data_type, n.has_mask?)
+      end
+
+      # A shift of an array is that array read elsewhere, so it is the
+      # array that becomes a leaf.  A shift of anything else -- an
+      # expression, say -- has no array to read and is taken as a whole.
+      def shifted (n)
+        array = n.parent
+        bounds = n.__boundary_rule_of_each_axis__
+        if Fusion.lazy?(array) || array.shape != n.shape ||
+           ! bounds.all? { |b| b == :fill || b == :mask }
+          return leaf(n)
+        end
+        offset = n.start
+        # The fill as a cell of the array holds it: a boolean array is
+        # filled with true or false, not with the Integer it was given.
+        fill = bounds.include?(:fill) ? as_cell(n.fill_value, array.data_type) : nil
+        index = leaf_index(array)
+        note("s", index, array.data_type, array.has_mask? ? 1 : 0,
+             offset.join(","), bounds.join(","), fill.inspect)
+        push Shifted.new(index, array.data_type, array.has_mask?,
+                         offset, bounds, fill)
       end
 
+      # A leaf the address bases would refuse to lend cannot be read by an
+      # evaluator, so the expression is not described.
+      def leaf_index (array)
+        @leaf_index.fetch(array.object_id) do
+          if (reason = AddressBasis.classify(array)[:refusal])
+            raise Refused, "a leaf: #{reason}"
+          end
+          @leaves << array
+          @leaf_index[array.object_id] = @leaves.size - 1
+        end
+      end
+
+      # A masked scalar has no value to write into the expression.
       def constant (n)
-        note("k", n[0], n.data_type)
-        push Const.new(n[0], n.data_type)
+        raise Refused, "a masked scalar" if n.has_mask? && n.is_masked[0]
+        value = n[0]
+        note("k", value.inspect, n.data_type)
+        push Const.new(value, n.data_type)
+      end
+
+      def as_cell (value, data_type)
+        cell = CScalar.new(data_type)
+        cell[0] = value
+        cell[0]
       end
 
       def push (node)
@@ -210,6 +423,8 @@ class CArray
 
       # Two expressions of the same shape compute alike, whatever arrays
       # they are over, so a consumer can keep one compiled kernel for both.
+      # The shape includes which node each operation reads and which leaf
+      # each read is: `(a - b) - b` and `(a - b) - a` differ only there.
       def note (*parts)
         @signature << parts.join(":") << ";"
       end