carray 3.0.2 → 3.0.4

data/lib/carray/mask_gap_fill.rb

@@ -15,7 +15,7 @@
 # `strip_mask(:na)`).  Passing both raises ArgumentError.
 #
 # Design / rationale: devel/PROPOSAL_UNMASK_FILL_METHOD.md.  The forward
-# hold is the C primitive #__hold__; backward = flip -> forward -> flip,
+# hold is the C primitive #hold_forward; backward = flip -> forward -> flip,
 # flatten = flatten -> hold -> reshape, and :linear composes
 # linear_section / linear_fetch.  User-facing YARD docs live in
 # yard-stubs/carray_mask.rb.
@@ -29,55 +29,50 @@
 
 class CArray
 
-  # Preserve the C constant-fill primitives under private names so the
-  # Ruby wrappers can delegate the non-method path unchanged.
-  alias __unmask_const__ unmask
-  alias __strip_mask_const__ strip_mask
-  private :__unmask_const__, :__strip_mask_const__
-
   # Sentinel for "no positional fill value given" (distinct from any real
   # fill value, including nil / false / a Symbol).
   MASK_FILL_UNSET = ::Object.new
+  Ractor.make_shareable(MASK_FILL_UNSET)
   private_constant :MASK_FILL_UNSET
 
-  def unmask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
-    if method
-      unless fill.equal?(MASK_FILL_UNSET)
-        raise ArgumentError,
-              "unmask: pass either a constant fill value or method:, not both"
-      end
-      held = __gap_fill__(method, axis)
-      # Copy the filled values in place.  A Face writes through its storage: a
-      # bulk store into its surface would try to cast the storage values to the
-      # surface type (int64 ticks to fixlen, for a time array).
-      if face?
-        parent.value[] = held.parent.value
-      else
+  # unmask / strip_mask with method:, in front of the C constant-fill
+  # primitives, which they reach with super.
+  module GapFill
+    def unmask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
+      if method
+        unless fill.equal?(MASK_FILL_UNSET)
+          raise ArgumentError,
+                "unmask: pass either a constant fill value or method:, not both"
+        end
+        held = gap_fill(method, axis, "unmask")
+        # Copy the filled values in place (a Face takes a Face of its own kind
+        # as it is).
         value[] = held.value
+        if held.has_mask?
+          self.mask = held.mask              # residual leading/trailing mask
+        else
+          super()                   # fully filled: drop the mask
+        end
+        return self
       end
-      if held.has_mask?
-        self.mask = held.mask              # residual leading/trailing mask
-      else
-        __unmask_const__                   # fully filled: drop the mask
-      end
-      return self
+      fill.equal?(MASK_FILL_UNSET) ? super() : super(fill)
     end
-    fill.equal?(MASK_FILL_UNSET) ? __unmask_const__ : __unmask_const__(fill)
-  end
 
-  def strip_mask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
-    if method
-      unless fill.equal?(MASK_FILL_UNSET)
-        raise ArgumentError,
-              "strip_mask: pass either a constant fill value or method:, not both"
+    def strip_mask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
+      if method
+        unless fill.equal?(MASK_FILL_UNSET)
+          raise ArgumentError,
+                "strip_mask: pass either a constant fill value or method:, not both"
+        end
+        return carry_attrs(gap_fill(method, axis, "strip_mask"))
       end
-      return __gap_fill__(method, axis)
-    end
-    if fill.equal?(MASK_FILL_UNSET)
-      raise ArgumentError, "strip_mask: a fill value is required (or method:)"
+      if fill.equal?(MASK_FILL_UNSET)
+        raise ArgumentError, "strip_mask: a fill value is required (or method:)"
+      end
+      carry_attrs(super(fill))
     end
-    __strip_mask_const__(fill)
   end
+  prepend GapFill
 
   private
 
@@ -85,14 +80,15 @@ class CArray
   # unfillable cells stay masked; a fully filled result carries no mask
   # (hold allocates the output mask only when a leading run goes UNDEF;
   # :linear masks only the exterior via mask_invalid).
-  def __gap_fill__ (method, axis)
+  def gap_fill (method, axis, name)
+    axis = normalize_axis(axis, name) unless axis.nil?
     case method
     when :forward, :ffill
-      __hold_axis__(axis, false)
+      hold_along_axis(axis, false)
     when :backward, :bfill
-      __hold_axis__(axis, true)
+      hold_along_axis(axis, true)
     when :linear
-      __gap_fill_linear__(axis)
+      gap_fill_linear(axis)
     else
       raise ArgumentError,
             "unmask/strip_mask: unknown method: #{method.inspect} " \
@@ -100,22 +96,21 @@ class CArray
     end
   end
 
-  # Forward (backward = false) or backward (true) hold along `axis`
-  # (axis nil = flatten).  Backward reuses the forward primitive on the
+  # Forward (backward = false) or backward (true) hold along `axis`, already
+  # normalised by gap_fill (axis nil = flatten).  Backward reuses the forward primitive on the
   # reversed view; flatten flattens, holds axis 0, reshapes back.
-  def __hold_axis__ (axis, backward)
+  def hold_along_axis (axis, backward)
     if axis.nil?
       flat = flatten
       flat = flat.reverse if backward
-      held = flat.send(:__hold__, 0)
+      held = flat.send(:hold_forward, 0)
       held = held.reverse if backward
       held.reshape(*shape)
     else
-      ax = axis < 0 ? axis + ndim : axis
       if backward
-        flip(ax).send(:__hold__, ax).flip(ax)
+        flip(axis).send(:hold_forward, axis).flip(axis)
       else
-        send(:__hold__, ax)
+        send(:hold_forward, axis)
       end
     end
   end
@@ -123,64 +118,89 @@ class CArray
   # Linear-by-index gap fill: interpolate each masked cell from the two
   # bracketing valid cells, x = cell index along the axis.  Cells outside the
   # valid range (leading/trailing) stay masked.  A Face goes through its own
-  # linear_fetch, which keeps its unit and rounds to its grid; whether that
-  # means anything is the Face's call (an ORDERABLE numeric one answers, the
-  # rest raise from there), so this gate only asks that it be one.
-  def __gap_fill_linear__ (axis)
-    unless numeric? || face?
+  # linear_fetch, which keeps its unit and rounds to its grid.  Defining one
+  # is how a Face says it interpolates: without it, the core linear_fetch
+  # reads the Face's storage and fails from inside.
+  def gap_fill_linear (axis)
+    if face?
+      unless interpolable?
+        raise ArgumentError,
+              "unmask/strip_mask(method: :linear): #{self.class} does not " \
+              "interpolate (it defines no linear_fetch of its own); " \
+              "use method: :forward or :backward"
+      end
+    elsif ! numeric?
       raise ArgumentError,
             "unmask/strip_mask(method: :linear): numeric or time data_type " \
             "required (got #{data_type_name})"
     end
     if axis.nil?
-      return __linear_fiber__(flatten).reshape(*shape)
+      return linear_fill_fiber(flatten).reshape(*shape)
     end
-    ax = axis < 0 ? axis + ndim : axis
-    if ax < 0 || ax >= ndim
-      raise ArgumentError, "axis #{axis} out of range for ndim #{ndim}"
+    ax = axis
+    # A fiber comes back in self's own type (a Face's linear_fetch has already
+    # rounded to its grid), so the result assembles in that type and the
+    # present cells are never carried through float64.
+    out = face? ? template : value.copy
+    each_fiber_key(ax) do |key|
+      out[*key] = linear_fill_fiber(self[*key])
     end
-    # A Face assembles in storage space -- its linear_fetch has already rounded
-    # to the grid, so there is nothing left to hold in float64.  A numeric
-    # array assembles in float64 and casts back once at the end.
-    out  = face? ? template : float64.copy
-    sink = face? ? out.parent : out
-    __each_fiber_key__(ax) do |key|
-      fiber = __linear_fiber__(self[*key])
-      sink[*key] = face? ? fiber.parent : fiber
-    end
-    face? ? out : out.to_type(data_type)
+    out
   end
 
-  # 1-D linear-by-index fill of a single (possibly masked) fiber.  Present
-  # cells reproduce exactly; interior masked cells interpolate; exterior
-  # masked cells become UNDEF (linear_section returns NaN out of range,
-  # mask_invalid marks it).  Returns the same kind as `vec`: a Face fiber
-  # comes back as that Face, on its own unit.
-  def __linear_fiber__ (vec)
-    n = vec.elements
-    present = vec.is_not_masked
+  # Whether linear interpolation can fill this array: a numeric array, or a
+  # Face that defines a linear_fetch of its own -- which is how a Face says it
+  # interpolates (the core linear_fetch would read its storage).
+  private def interpolable?
+    face? ? self.class.instance_method(:linear_fetch).owner != CArray : numeric?   # type-label: asks what the Face can do, names nothing
+  end
+
+  # 1-D linear-by-index fill of a single (possibly masked) fiber.
+  def linear_fill_fiber (vec)
+    vec.send(:linear_fill_along, CArray.float64(vec.elements) { |i| i.to_f })
+  end
+
+  # Fill the masked cells of this 1-D array by linear interpolation against
+  # the coordinate `x` (same length, ascending over the present cells).
+  # The one rule both the core (x = cell position) and CAFrame (x = index)
+  # use: present cells come back exactly as they are, in this array's own
+  # type; a masked cell inside the span of the present ones takes the
+  # interpolated value; one outside it stays masked.  Outside is where
+  # linear_section answers NaN -- a property of x, not of the values, so a
+  # NaN or Inf stored in a present cell is left alone.  A Face goes through
+  # its own linear_fetch, which keeps its unit and rounds to its grid.
+  def linear_fill_along (x)
+    present = is_not_masked
     # Fewer than two valid points -> nothing to interpolate between; leave
-    # every masked cell masked (the copy carries vec's mask).
-    if present.count(true) < 2
-      return vec.face? ? vec.copy : vec.float64.copy
-    end
-    pos  = CArray.float64(n) { |i| i.to_f }
-    addr = pos[present].linear_section(pos)   # valid positions -> monotonic grid
-    if vec.face?
+    # every masked cell masked.
+    return copy if present.count(true) < 2
+    addr = x[present].linear_section(x)       # valid positions -> monotonic grid
+    if face?
       # The Face's linear_fetch already masks the exterior (out of range) and
-      # lands on its own grid, so it needs no cast and no mask_invalid.
-      return vec[present].linear_fetch(addr)
+      # lands on its own grid.
+      return self[present].linear_fetch(addr)
     end
-    vval = vec.value.float64[present]         # valid values
-    # Mark the out-of-range NaN before casting back: for an integer data_type
-    # the cast turns NaN into 0, and mask_invalid then has nothing left to find.
-    vval.linear_fetch(addr).mask_invalid.to_type(vec.data_type)
+    v = value[present]
+    # A complex value interpolates its real and imaginary parts.
+    interp = v.complex? ? v.linear_fetch(addr) : v.float64.linear_fetch(addr)
+    # An integer array takes the nearest integer, half away from zero (as a
+    # time Face lands on its own grid), rounded before the store would cut
+    # the fraction off.
+    interp = interp.round if integer?
+    # Built from the values alone, so a fully filled result carries no mask.
+    out      = value.copy
+    masked   = is_masked
+    fill     = masked & addr.is_finite
+    exterior = masked & fill.not
+    out[fill] = interp[fill] if fill.any
+    out[exterior] = UNDEF if exterior.any
+    out
   end
 
   # Yield an index key (Array with `nil` at `axis`, integers elsewhere)
   # for every fiber along `axis`.  `self[*key]` is that fiber as a masked
   # 1-D view.
-  def __each_fiber_key__ (axis)
+  def each_fiber_key (axis)
     outer = shape
     outer_dims = outer.each_index.reject { |k| k == axis }.map { |k| outer[k] }
     idx = Array.new(outer_dims.size, 0)
@@ -196,7 +216,7 @@ class CArray
       end
     end
   end
-  private :__hold_axis__, :__gap_fill_linear__, :__linear_fiber__,
-          :__each_fiber_key__
+  private :hold_along_axis, :gap_fill_linear, :linear_fill_fiber,
+          :each_fiber_key
 
 end

data/lib/carray/math.rb

@@ -3,23 +3,30 @@ module CAMath
   module_function
 
   # Module-function front-ends for binop math methods registered on
-  # CArray by mkkernel. The first argument is auto-wrapped to CArray
-  # via `CArray.wrap_readonly`, so `CAMath.hypot(3, arr)` continues to
-  # work. Integer input is unsupported at the kernel layer -- the
-  # caller must cast to float64 explicitly (e.g.
-  # `arr.as_float64.hypot(...)`).
+  # CArray by mkkernel.  A CArray first argument answers through its own
+  # method, in its own data_type; any other first argument, and an
+  # integer CArray for a function defined only on floats, is taken as
+  # float64, so `CAMath.hypot(3, arr)` works.
 
   # @overload expm1(x)
-  #   Returns `exp(x) - 1` element-wise as float64.
+  #   Returns `exp(x) - 1` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#expm1}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def expm1(x);  CArray.wrap_readonly(x, :float64).expm1;  end
+  def expm1(x)
+    x.is_a?(CArray) ? x.expm1 : CArray.wrap_readonly(x, :float64).expm1
+  end
 
   # @overload log1p(x)
-  #   Returns `log(1 + x)` element-wise as float64.
+  #   Returns `log(1 + x)` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#log1p}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def log1p(x);  CArray.wrap_readonly(x, :float64).log1p;  end
+  def log1p(x)
+    x.is_a?(CArray) ? x.log1p : CArray.wrap_readonly(x, :float64).log1p
+  end
 
   # @overload atan2(y, x)
   #   Returns the element-wise arc tangent of `y / x` with quadrant
@@ -27,21 +34,21 @@ module CAMath
   #   @param y [CArray, Numeric] numerator.
   #   @param x [CArray, Numeric] denominator.
   #   @return [CArray]
-  def atan2(y, x);     CArray.wrap_readonly(y, :float64).atan2(x);     end
+  def atan2(y, x); float_operand(y).atan2(x); end
 
   # @overload hypot(x, y)
   #   Returns the element-wise Euclidean distance `sqrt(x^2 + y^2)`.
   #   @param x [CArray, Numeric] first leg.
   #   @param y [CArray, Numeric] second leg.
   #   @return [CArray]
-  def hypot(x, y);     CArray.wrap_readonly(x, :float64).hypot(y);     end
+  def hypot(x, y); float_operand(x).hypot(y); end
 
   # @overload copysign(x, y)
   #   Returns `|x|` with the sign of `y`, element-wise.
   #   @param x [CArray, Numeric] magnitude source.
   #   @param y [CArray, Numeric] sign source.
   #   @return [CArray]
-  def copysign(x, y);  CArray.wrap_readonly(x, :float64).copysign(y);  end
+  def copysign(x, y); float_operand(x).copysign(y); end
 
   # @overload logaddexp(x, y)
   #   Returns `log(exp(x) + exp(y))` computed to avoid overflow,
@@ -49,7 +56,7 @@ module CAMath
   #   @param x [CArray, Numeric] first log-space value.
   #   @param y [CArray, Numeric] second log-space value.
   #   @return [CArray]
-  def logaddexp(x, y); CArray.wrap_readonly(x, :float64).logaddexp(y); end
+  def logaddexp(x, y); float_operand(x).logaddexp(y); end
 
   # @overload nextafter(x, y)
   #   Returns the next representable float from `x` toward `y`,
@@ -57,21 +64,27 @@ module CAMath
   #   @param x [CArray, Numeric] starting value.
   #   @param y [CArray, Numeric] direction target.
   #   @return [CArray]
-  def nextafter(x, y); CArray.wrap_readonly(x, :float64).nextafter(y); end
+  def nextafter(x, y); float_operand(x).nextafter(y); end
 
   # @overload fmod(x, y)
   #   Returns the C-style `fmod(x, y)` element-wise (sign follows `x`).
   #   @param x [CArray, Numeric] dividend.
   #   @param y [CArray, Numeric] divisor.
   #   @return [CArray]
-  def fmod(x, y);      CArray.wrap_readonly(x, :float64).fmod(y);      end
+  def fmod(x, y);      (x.is_a?(CArray) ? x : CArray.wrap_readonly(x, :float64)).fmod(y); end
+
+  # A float or complex CArray as it is; anything else as float64.
+  def float_operand(x)
+    x.is_a?(CArray) && (x.float? || x.complex?) ? x : CArray.wrap_readonly(x, :float64)
+  end
+  private_class_method :float_operand
 
   # @overload min(*argv)
   #   Returns the element-wise minimum of the given CArray and other
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running min.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def min (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -80,7 +93,7 @@ module CAMath
         out.pmin!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end
@@ -90,7 +103,7 @@ module CAMath
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running max.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def max (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -99,7 +112,7 @@ module CAMath
         out.pmax!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end

data/lib/carray/meld_reduce.rb

@@ -16,7 +16,7 @@
 #
 # Fast path activates when:
 #   - axis kwarg is a single Integer (or absent for flat reduce)
-#   - no mask on CAMeld or any parent (skipna needs per-cell dispatch;
+#   - no mask on CAMeld or any parent (skipping masked cells needs per-cell dispatch;
 #     the decompose would not see correct mask propagation across parents)
 #   - no non-:axis kwargs (min_count / fill_value / keep_axis / etc. punt
 #     to super; those change finalisation semantics)
@@ -36,7 +36,7 @@ class CAMeld
 
   def sum(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       parents.map(&:sum).inject(:+)
     elsif meld_axis_normalized?(axis)
@@ -52,7 +52,10 @@ class CAMeld
   # @return [CArray, Numeric]
   def mean(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The combine divides in Float; an object array's mean stays exact
+    # (Rational, Integer division) on the core path.
+    return super if object?
+    axis = meld_fast_path_axis(kw)
     # `mean` has no identity: an empty set of contributors has no defined
     # mean (0/0 = NaN).  Punt to super, which returns UNDEF: a reduction
     # with no contributors yields the identity where one exists and UNDEF
@@ -63,9 +66,9 @@ class CAMeld
       total_count = parents.map(&:elements).inject(:+)
       total_sum / total_count.to_f
     elsif meld_axis_normalized?(axis)
-      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
       total_sum = parents.map { |p| p.sum(axis: axis) }.inject(:+)
-      total_count = parents.map { |p| p.dim[meld_axis] }.inject(:+)
+      total_count = parents.map { |p| p.shape[meld_axis] }.inject(:+)
       total_sum / total_count.to_f
     else
       non_meld_axis_decompose(:mean, axis)
@@ -78,15 +81,15 @@ class CAMeld
   # @return [CArray, Numeric]
   def min(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     # `min` has no identity — empty parent list / all-empty parents punt to
     # super for UNDEF.
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:min).min
+      meld_combine_flat(:min)
     elsif meld_axis_normalized?(axis)
-      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
-      nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.shape[meld_axis] == 0 }
       CArray.stack(nonempty.map { |p| p.min(axis: axis) }).min(axis: 0)
     else
       non_meld_axis_decompose(:min, axis)
@@ -99,13 +102,13 @@ class CAMeld
   # @return [CArray, Numeric]
   def max(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:max).max
+      meld_combine_flat(:max)
     elsif meld_axis_normalized?(axis)
-      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
-      nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.shape[meld_axis] == 0 }
       CArray.stack(nonempty.map { |p| p.max(axis: axis) }).max(axis: 0)
     else
       non_meld_axis_decompose(:max, axis)
@@ -160,7 +163,7 @@ class CAMeld
   private
 
   def meld_axis_normalized?(axis)
-    (axis < 0 ? axis + ndim : axis) == meld_axis
+    normalize_axis(axis) == meld_axis
   end
 
   # Fast path fires when: no mask anywhere, no non-:axis kwargs, and axis
@@ -168,18 +171,40 @@ class CAMeld
   # more elaborate (min_count / fill_value / keep_axis / multi-axis /
   # mask propagation) punts to super.
   def meld_reduce_fast_path_ok?(kw)
+    return false unless CArray.__fast_paths_enabled__
+    # The mask of a meld is a meld built in C, with no parents list.
+    return false unless parents
     return false unless (kw.keys - [:axis]).empty?
     axis = kw[:axis]
     unless axis.nil?
-      return false unless axis.is_a?(Integer)
-      norm = axis < 0 ? axis + ndim : axis
-      return false unless norm >= 0 && norm < ndim
+      return false unless axis.is_a?(Integer) && axis >= -ndim && axis < ndim   # axis-check: a gate only; super normalizes
     end
     return false if has_mask?
     parents.each { |p| return false if p.has_mask? }
+    # A meld of Face arrays keeps its parents in their Face; the per-parent
+    # calls would reach the Face's own reductions, which answer in the Face's
+    # terms (or refuse), not in storage.
+    parents.each { |p| return false if p.face? }
     true
   end
 
+  # The axis a fast path reduces along.  A 1-D meld has only the meld axis,
+  # and reducing it is reducing the whole array: the answer is a scalar, as
+  # for the flat call.
+  def meld_fast_path_axis(kw)
+    ndim == 1 ? nil : kw[:axis]
+  end
+
+  # The per-parent answers of a whole-array min / max, combined by core's
+  # own min / max so NaN loses the way it loses inside one parent (Ruby's
+  # Array#min would raise on it).
+  def meld_combine_flat(op)
+    vals = parents.reject { |p| p.elements == 0 }.map(&op)
+    part = CArray.new(data_type, [vals.size])
+    vals.each_with_index { |v, i| part[i] = v }
+    part.public_send(op)
+  end
+
   # Non-meld-axis decompose: each parent reduces the same axis independently,
   # then the K per-parent results are concatenated back along the meld axis.
   # Materialised to entity (`.copy`) to match CArray#reduce entity semantics.
@@ -191,14 +216,20 @@ class CAMeld
   # meld_axis branch and never reaches here.)
   def non_meld_axis_decompose(op, axis)
     parts = parents.map { |p| p.public_send(op, axis: axis) }
-    axis_norm = axis < 0 ? axis + ndim : axis
+    axis_norm = normalize_axis(axis)
     new_meld_axis = axis_norm < meld_axis ? meld_axis - 1 : meld_axis
     CArray.meld(parts, axis: new_meld_axis).copy
   end
 
   def variance_family(args, kw, sample:, sqrt:)
     return yield unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The merge works in Float; an object array's variance stays exact
+    # (Rational, BigDecimal) on the core path.
+    return yield if object?
+    # The merge squares the difference of means, which for complex values is
+    # not |δ|²; the core path computes the variance of a complex array.
+    return yield if complex?
+    axis = meld_fast_path_axis(kw)
     # Empty-parent / short-parent handling — Welford needs n >= 2 per parent
     # to recover m2 from p.variance for sample, n >= 1 for variancep (n=1
     # gives m2=0, fine).  Any parent below its threshold punts to super,
@@ -208,7 +239,7 @@ class CAMeld
       return yield if parents.any? { |p| p.elements < min_n }
       finalize_scalar(welford_flat, sample, sqrt)
     elsif meld_axis_normalized?(axis)
-      return yield if parents.any? { |p| p.dim[meld_axis] < min_n }
+      return yield if parents.any? { |p| p.shape[meld_axis] < min_n }
       finalize_vector(welford_axis(axis), sample, sqrt)
     else
       # Non-meld-axis: each parent's variance/stddev is independent along
@@ -255,7 +286,7 @@ class CAMeld
     mean = nil
     m2 = nil
     parents.each do |p|
-      np = p.dim[meld_axis]
+      np = p.shape[meld_axis]
       mp = p.mean(axis: axis)
       # variance is undefined at n=1; for variancep with n=1, m2_p = 0 by
       # definition (variance_family already gated n >= min_n).

data/lib/carray/methods/align_addr.rb

@@ -85,8 +85,10 @@ class CArray
   #     b_on_grid = b_data.project(ib)
   #
   #   `direction:` (`:round` / `:floor` / `:ceil`) and `tolerance:` are
-  #   forwarded to {#locate_nearest_addr}: out-of-range grid points, and points
-  #   whose nearest value is farther than `tolerance`, come back masked.
+  #   forwarded to {#locate_nearest_addr}: grid points with no match in the
+  #   direction (before an array's first value under `:floor`, after its last
+  #   under `:ceil`), and points whose match is farther than `tolerance`, come
+  #   back masked.
   #
   #   @param arrays [Array<CArray>] one or more arrays (Array / Range coerced
   #     via `to_ca`).
@@ -94,8 +96,10 @@ class CArray
   #     `nil` uses the first array verbatim.
   #   @param direction [:round, :floor, :ceil] rounding rule for the nearest
   #     match.
-  #   @param tolerance [Numeric, nil] maximum accepted distance; farther grid
-  #     points are masked. `nil` disables the check.
+  #   @param tolerance [Numeric, String, CATimedelta::Element, nil] maximum
+  #     accepted distance; farther grid points are masked. For time keys it
+  #     is a duration (`"10 minutes"` or a CATimedelta value), as in
+  #     {#locate_nearest_addr}. `nil` disables the check.
   #   @return [Array<CArray>] `[common, idx_0, idx_1, ...]`.
   #   @raise [ArgumentError] when no array is given (or `direction` is invalid,
   #     raised by {#locate_nearest_addr}).