carray 3.0.2 → 3.0.4

data/lib/carray/basics.rb

@@ -13,9 +13,19 @@
 
 class CArray
 
+  # The order sort puts two object values in (ca_obj_order_cmp in C): a
+  # Float NaN after every other value, NaN ties NaN, other pairs by `<=>`.
+  # nil when `<=>` cannot order the pair; the caller says what refused.
+  private_class_method def self.object_order_cmp (a, b)
+    a_nan = a.is_a?(Float) && a.nan?
+    b_nan = b.is_a?(Float) && b.nan?
+    return (a_nan ? 1 : 0) - (b_nan ? 1 : 0) if a_nan || b_nan
+    a <=> b
+  end
+
   # reshape / flatten / transpose! are defined in C
   # (ext/ca_obj_refer.c and ext/ca_obj_transpose.c).  The bare size-1
-  # insertion primitive is `__insert_axis_size1__` (C); `insert_axis` below
+  # insertion primitive is `insert_size_one_axes` (C); `insert_axis` below
   # is the user-facing method that owns the name and adds `repeat:`.
 
   # @overload insert_axis(*positions, repeat: nil)
@@ -58,7 +68,7 @@ class CArray
 
     # No repeat: -> plain size-1 insertion.  The source-frame C primitive
     # handles normalization, range check and multiplicity directly.
-    return __insert_axis_size1__(*flat) if repeat.nil?
+    return insert_size_one_axes(*flat) if repeat.nil?
 
     # Source frame: each position names the source axis the new axis goes
     # before.  Gaps live in [0, ndim] (ndim = append at end); negatives count
@@ -80,31 +90,31 @@ class CArray
         Array.new(flat.length, repeat)
       end
 
-  # Validate each value.  A positive Integer only; nil is not a valid
-  # per-axis repeat.
-  reps.each do |r|
-    unless r.is_a?(Integer)
-      raise ArgumentError,
-        "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+    # Validate each value.  A positive Integer only; nil is not a valid
+    # per-axis repeat.
+    reps.each do |r|
+      unless r.is_a?(Integer)
+        raise ArgumentError,
+          "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+      end
+      raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
     end
-    raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
-  end
 
-  # Final output layout: stable order by (gap, argument index) keeps
-  # same-gap axes in argument order; the k-th inserted axis lands at output
-  # position gap + k.  This output position only drives broadcast_to; the
-  # insertion itself always goes through the source-frame primitive.
-  order = (0...flat.length).sort_by { |i| [gaps[i], i] }
-  final = {}
-  order.each_with_index { |i, k| final[i] = gaps[i] + k }
+    # Final output layout: stable order by (gap, argument index) keeps
+    # same-gap axes in argument order; the k-th inserted axis lands at output
+    # position gap + k.  This output position only drives broadcast_to; the
+    # insertion itself always goes through the source-frame primitive.
+    order = (0...flat.length).sort_by { |i| [gaps[i], i] }
+    final = {}
+    order.each_with_index { |i, k| final[i] = gaps[i] + k }
 
-  inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
-  return inter unless order.any? { |i| reps[i] > 1 }
+    inter = insert_size_one_axes(*order.map { |i| gaps[i] })
+    return inter unless order.any? { |i| reps[i] > 1 }
 
-  shp = inter.shape
-  order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
-  inter.broadcast_to(*shp)
-end
+    shp = inter.shape
+    order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
+    inter.broadcast_to(*shp)
+  end
 
   # @overload drop_axis
   #   Returns a view of `self` with every size-1 axis dropped.
@@ -142,6 +152,28 @@ end
     return template(:boolean) { 1 }
   end
 
+  # A Face is clipped in its own terms: its comparisons decide which cells are
+  # out of range (a time array reads its bounds as times, a record array
+  # orders by its declared members, a Face that cannot be ordered refuses),
+  # and its store writes the bound or the fill value into them.
+  private def face_clip (min, max, fill_value, lfill, ufill)
+    lfill = fill_value if lfill.nil?
+    ufill = fill_value if ufill.nil?
+    out = copy
+    out[self < min] = lfill.nil? ? min : lfill unless min.nil?
+    out[self > max] = ufill.nil? ? max : ufill unless max.nil?
+    out
+  end
+
+  # An array of +shape+ of the same kind as self: its data type and cell
+  # width, or its Face over a zero storage.  Nothing is written into it, so
+  # it can be built for a read-only Face too.
+  private def blank_like (shape)
+    storage = face_storage
+    out = CArray.new(storage.data_type, shape, bytes: storage.bytes)
+    face? ? out.face_lift(self) : out
+  end
+
   # Sub-region copy (paste / crop), the old C `ca_paste` / `ca_clip` pair.
   # `clip` is reserved for value clamping (clamp to a min/max range), so
   # the read-out side is `crop`.  Kept together as a pair (crop is rare, but paste is reached
@@ -250,6 +282,31 @@ end
 
   # @!endgroup
 
+  # An Integer shift count on an integer array means what it means to
+  # Integer#<< and #>>: negative shifts the other way, and a count past the
+  # width shifts every bit out.  The kernels do that for a count of the
+  # array's own type; this brings a count the type cannot hold -- -1 for a
+  # uint8 array, 300 for an int8 one -- to one it can.
+  module IntegerShiftCount
+    UNSIGNED = [CA_UINT8, CA_UINT16, CA_UINT32, CA_UINT64].freeze
+
+    def << (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self >> -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+
+    def >> (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self << -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+  end
+  # Prepended by carray/lazy, after it has wrapped << and >>: prepended
+  # here, the method lazy aliases as the eager form would be this one.
+
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #
@@ -258,7 +315,14 @@ end
   #   `fill_value` (or `lfill` / `ufill`) is given, out-of-range
   #   cells are replaced by the fill instead of clamped -- pass
   #   `UNDEF` to mask that end. `fill_value` is sugar for symmetric
-  #   dual-fill; `lfill` / `ufill` override per side.
+  #   dual-fill; `lfill` / `ufill` override per side, and a side
+  #   given no fill is still clamped.
+  #
+  #   `min` may not exceed `max` (in any cell, when a bound is an
+  #   array); equal bounds give every unmasked cell that value.
+  #   A NaN in a bound array leaves that cell unbounded on that side,
+  #   as `nil` does for the whole side.  A bound is never UNDEF or
+  #   masked: a missing bound is not read as either, so fill it first.
   #
   #   Boundary is strict `[min, max]`: values equal to a bound
   #   remain unchanged in both the clamped and filled variants.
@@ -272,7 +336,9 @@ end
   #   @param lfill [Object, nil] override below-range fill.
   #   @param ufill [Object, nil] override above-range fill.
   #   @return [CArray] new CArray with clamped or filled values.
-  #   @raise [ArgumentError] when both `min` and `max` are `nil`.
+  #   @raise [ArgumentError] when both `min` and `max` are `nil`,
+  #     when either is `UNDEF` or has a masked cell, or when `min`
+  #     exceeds `max`.
   #   @example
   #     a.clip(0, 10)                          # strict clamp
   #     a.clip(0, 10, -1)                      # both ends -> -1
@@ -281,20 +347,42 @@ end
     if min.nil? && max.nil?
       raise ArgumentError, "clip: at least one of (min, max) must be given"
     end
+    [min, max].each do |bound|
+      undefined = UNDEF.equal?(bound) ||
+                  (bound.is_a?(CArray) && bound.any_masked?) ||
+                  (bound.is_a?(Array) && bound.flatten.any? { |v| UNDEF.equal?(v) })
+      next unless undefined
+      raise ArgumentError, "clip: a bound can not be UNDEF or masked " \
+                           "(fill the bound first; a NaN bound leaves its cell " \
+                           "unbounded, and UNDEF as the fill masks the cells out of range)"
+    end
+    return face_clip(min, max, fill_value, lfill, ufill) if face?
+    if !min.nil? && !max.nil?
+      reversed = if min.is_a?(CArray) then min.gt(max).any
+                 elsif max.is_a?(CArray) then max.lt(min).any
+                 else min > max
+                 end
+      if reversed
+        raise ArgumentError, "clip: min must be less than or equal to max"
+      end
+    end
 
     # `fill_value` as a single argument is sugar applied to both ends; kwargs override.
     lfill = fill_value if lfill.nil?
     ufill = fill_value if ufill.nil?
 
     if lfill.nil? && ufill.nil?
-      return __clip_ki__(min, max) if !min.nil? && !max.nil?
+      return clamp_between(min, max) if !min.nil? && !max.nil?
       return pmax(min) if max.nil?
       return pmin(max)
     end
 
+    # A side without a fill still clamps.
     out = self.copy
-    out[:lt, min] = lfill unless min.nil? || lfill.nil?
-    out[:gt, max] = ufill unless max.nil? || ufill.nil?
+    out = out.pmax(min) if !min.nil? && lfill.nil?
+    out = out.pmin(max) if !max.nil? && ufill.nil?
+    out[self.lt(min)] = lfill unless min.nil? || lfill.nil?
+    out[self.gt(max)] = ufill unless max.nil? || ufill.nil?
     out
   end
 
@@ -483,3 +571,49 @@ class Enumerator::ArithmeticSequence
     return CA_OBJECT(to_a)
   end
 end
+
+class CArray
+  # map_slab / reduce_slab over a Face answer in that Face, as its other
+  # reductions do: each block value is written into a blank of the Face
+  # (which reads a CATime::Element, a string, a Face array ...) and handed
+  # to the slab engine as the storage it became; the result is lifted back
+  # at the end.  A read-only Face has no blank to write into, so its values
+  # are collected as the surface objects they are.  A `data_type:` from the
+  # caller is the caller's, and passes through.
+  module FaceSlabResult
+    def map_slab (**kw, &block)
+      return super unless face? && kw[:data_type].nil? && block
+      return super(**kw, data_type: :object, &block) if read_only?
+      out = super(**kw, data_type: face_storage.data_type) { |slab|
+        face_slab_storage(block.call(slab), slab.shape)
+      }
+      out.face_lift(self)
+    end
+
+    def reduce_slab (**kw, &block)
+      return super unless face? && kw[:data_type].nil? && block
+      return super(**kw, data_type: :object, &block) if read_only?
+      fiber = kw.key?(:init)
+      init  = kw.delete(:init)
+      out = super(**kw, data_type: face_storage.data_type) { |slab|
+        value = if fiber
+                  slab.to_a.flatten.inject(init) { |acc, e| block.call(acc, e) }
+                else
+                  block.call(slab)
+                end
+        face_slab_storage(value, [1])[0]
+      }
+      out.face_lift(self)
+    end
+
+    private
+
+    def face_slab_storage (value, shape)
+      cell = blank_like(shape)
+      cell[] = value
+      cell.__send__(:face_storage)
+    end
+  end
+
+  prepend FaceSlabResult
+end

data/lib/carray/bincount_nd.rb

@@ -78,8 +78,13 @@ class CArray
     #     accumulators; `nil` for pure counts (int64).
     #   @return [BincountND]
     def initialize (lengths:, fiber_shape: [], weights_data_type: nil)
-      @lengths = lengths.map(&:to_i)
-      raise ArgumentError, "lengths must be a non-empty list" if @lengths.empty?
+      raise ArgumentError, "lengths must be a non-empty list" if lengths.empty?
+      lengths.each_with_index do |l, k|
+        unless l.is_a?(Integer)
+          raise TypeError, "lengths[#{k}] must be an Integer (got #{l.inspect})"
+        end
+      end
+      @lengths = lengths.dup
       @lengths.each_with_index do |l, k|
         raise ArgumentError, "lengths[#{k}] must be >= 1" if l < 1
       end
@@ -209,6 +214,7 @@ class CArray
 
       if weights
         raise ArgumentError, "weights given but accumulator is unweighted" unless @weighted
+        # coerce: the accumulator's type, declared by weights_data_type:
         weights = CArray.wrap_readonly(weights, @counts_data_type)
         expected_w_shape = chunk.shape.dup
         expected_w_shape.delete_at(channel_ax)
@@ -269,6 +275,12 @@ class CArray
           term = strides_ext[k] == 1 ? b : b * strides_ext[k]
           ravel = ravel.nil? ? term : ravel + term
         end
+        # A NaN weight drops its sample, as the fiber kernel and histogram
+        # do; bincount itself would add the NaN in.
+        if tweights && tweights.float?
+          nan = tweights.is_nan
+          tweights = tweights.mask_where(nan) if nan.any
+        end
         chunk_counts = ravel.bincount(weights: tweights, length: total_ext)
         @full_counts[] = @full_counts + chunk_counts.reshape(*@full_counts.shape)
       else
@@ -338,6 +350,10 @@ class CArray
   #   @return [BincountND]
   def bincount_nd (lengths:, axis: [-2, -1], weights: nil)
     raise ArgumentError, "lengths must be an Array of per-dim extents" unless lengths.is_a?(Array)
+    axis = [-2, -1] if axis.nil?
+    unless axis.is_a?(Array) && axis.size == 2
+      raise ArgumentError, "bincount_nd: axis: is a [sample, channel] pair (got #{axis.inspect})"
+    end
     sample_ax  = normalize_axis(axis[0], "bincount_nd sample axis")
     channel_ax = normalize_axis(axis[1], "bincount_nd channel axis")
     fiber_shape = shape.dup