carray 2.0.1 → 3.0.1

data/lib/carray/core_extensions.rb

@@ -0,0 +1,297 @@
+# ----------------------------------------------------------------------------
+#
+#  carray/core_extensions.rb
+#
+#  Refinement that restores the carray-flavoured monkey patches on
+#  Float / Integer / Rational / Numeric / TrueClass / FalseClass
+#  for files that opt in with `using CArray::CoreExtensions`.
+#
+#  Provides:
+#    - Postfix math on Float/Integer/Rational (sqrt, exp, log, sin, ...)
+#      enabling scalar/CArray polymorphism: the same expression
+#      `(0.0415*(t-218.8)).tanh` works whether t is a Float or a CArray.
+#    - The same postfix math on Complex, so an expression written for a
+#      complex CArray still reads for a single cell taken out of it.
+#    - Angle normalisation on Numeric (deg_360 / deg_180 / rad_2pi / rad_pi).
+#    - Comparison helpers on Numeric (#eq / #ne) for symmetric usage:
+#      `5.eq(ca)` dispatches to `ca.eq(5)`.
+#    - Symmetric bitwise operators on Integer / TrueClass / FalseClass
+#      so that `5 | bool_ca`, `0xff & flag_ca`, `1 << position_ca` work
+#      without writing CA_INT(5) on the left.
+#
+#  None of these are loaded by default `require "carray"`. Each file
+#  that wants any of them must opt in:
+#
+#      using CArray::CoreExtensions
+#
+#  Refinements are lexically scoped to the file (or class/module body)
+#  where `using` is written. Methods defined in that scope resolve
+#  the refined methods at call time regardless of who is calling.
+#
+#  This file is auto-loaded on first reference to CArray::CoreExtensions.
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+  # Refinement carrying the carray-flavoured additions to Float / Integer /
+  # Rational / Numeric / TrueClass / FalseClass, for files that opt in with
+  # `using CArray::CoreExtensions`.
+  #
+  # It provides postfix math on scalars (so `(0.0415*(t-218.8)).tanh` reads
+  # the same whether `t` is a Float, a Complex or a CArray), angle
+  # normalisation, and comparison helpers.  Being a refinement, it is
+  # lexically scoped: nothing changes for code that does not opt in.
+  module CoreExtensions
+
+    # @!visibility private
+    MATH_METHODS = %i[
+      sqrt exp log log10
+      sin cos tan sinh cosh tanh
+      asin acos atan asinh acosh atanh
+    ].freeze
+
+    [Float, Integer, Rational].each do |klass|
+      refine(klass) do
+        MATH_METHODS.each do |m|
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{m}
+              Math.#{m}(self)
+            end
+          RUBY
+        end
+        def rad
+          self.to_f * Math::PI / 180.0
+        end
+        def deg
+          self.to_f * 180.0 / Math::PI
+        end
+        def distance(other)
+          (self.to_f - other.to_f).abs
+        end
+        # M.1 (PyTorch alignment) scalar polymorphism additions.
+        # `trunc` is left to Ruby's built-in semantics (Float#truncate
+        # returns Integer when arg=0) — its CArray counterpart preserves
+        # data type, so scalar-side use should call .to_f.trunc explicitly.
+        # Math.expm1 / Math.log1p don't exist in stdlib; hand-roll.
+        def expm1
+          Math.exp(self) - 1.0
+        end
+        def log1p
+          Math.log(1.0 + self)
+        end
+        def rsqrt
+          1.0 / Math.sqrt(self)
+        end
+        def square
+          self * self
+        end
+        def signbit
+          self.negative?
+        end
+      end
+    end
+
+    # The subset of MATH_METHODS that CArray's complex kernels implement,
+    # plus the two elementwise helpers that also accept complex input.
+    #
+    # Absent, because a complex CArray raises CArray::DataTypeError for
+    # them: log10 (C99 has no clog10) and expm1 / log1p (no complex form
+    # in C99 either).  Leaving them undefined on Complex keeps the scalar
+    # side failing wherever the array side fails.  rad / deg / distance /
+    # signbit are absent for the same reason from the other direction:
+    # they go through #to_f, which Complex does not have.
+    #
+    # @!visibility private
+    COMPLEX_MATH_METHODS = %i[
+      sqrt exp log
+      sin cos tan sinh cosh tanh
+      asin acos atan asinh acosh atanh
+      square rsqrt
+    ].freeze
+
+    # Complex is not handled the way Float / Integer / Rational are.
+    # Math.tanh(Complex(1,2)) raises RangeError -- of the stdlib Math
+    # methods only Math.sqrt accepts a Complex -- so the complex forms
+    # need their own implementation.
+    #
+    # Each one runs the value through a one-element cmplx128 CScalar, so
+    # the answer comes from the very kernel the array form would have
+    # used.  That is the point: the branch cuts of csqrt / clog / casin /
+    # cacosh / catanh, and the sign of a zero on either side of them, are
+    # whatever the platform's C99 complex.h says they are, and they are
+    # not the same everywhere.  On this machine, for instance,
+    # catanh(-1+0i) yields -Infinity+(pi/4)i where C99 Annex G describes
+    # -Infinity+0i.  A hand-written Complex implementation would have to
+    # reproduce each such quirk to agree with the array form, and would
+    # stop agreeing on the next platform; delegating agrees by
+    # construction on all of them.  The cost is one CScalar per call
+    # (~0.4 microseconds), which is the right trade for a scalar
+    # convenience whose whole purpose is to read the same as the array.
+    #
+    # `square` is delegated rather than written as `self * self`: Ruby's
+    # Complex multiplication and C's `double _Complex` multiplication part
+    # ways on infinities (Complex(1, Inf) squared gives -Inf+Inf*i in Ruby
+    # and -Inf+NaN*i in C).
+    refine Complex do
+      COMPLEX_MATH_METHODS.each do |m|
+        module_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{m}
+            CA_CMPLX128(self).#{m}[0]
+          end
+        RUBY
+      end
+    end
+
+    refine Numeric do
+      def deg_360
+        a = self.to_f
+        fa = a / 360.0
+        if a >= 0
+          (fa - fa.floor) * 360.0
+        else
+          (fa - fa.ceil + 1) * 360.0
+        end
+      end
+
+      def deg_180
+        a = self.to_f
+        fa = (a + 180.0) / 360.0
+        b = if a >= 0
+              (fa - fa.floor) * 360.0 - 180.0
+            else
+              (fa - fa.ceil) * 360.0 - 180.0
+            end
+        b += 360.0 if b <= -180.0
+        b
+      end
+
+      def rad_2pi
+        a = self.to_f
+        two_pi = 2 * Math::PI
+        fa = a / two_pi
+        if a >= 0
+          (fa - fa.floor) * two_pi
+        else
+          (fa - fa.ceil + 1) * two_pi
+        end
+      end
+
+      def rad_pi
+        a = self.to_f
+        two_pi = 2 * Math::PI
+        fa = (a + Math::PI) / two_pi
+        b = if a >= 0
+              (fa - fa.floor) * two_pi - Math::PI
+            else
+              (fa - fa.ceil) * two_pi - Math::PI
+            end
+        b += two_pi if b <= -Math::PI
+        b
+      end
+
+      def eq(other)
+        if CArray === other
+          other.eq(self)
+        else
+          self == other
+        end
+      end
+
+      def ne(other)
+        if CArray === other
+          other.ne(self)
+        else
+          self != other
+        end
+      end
+    end
+
+    refine Integer do
+      def |(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_or(self)
+          else
+            l, r = other.coerce(self)
+            l | r
+          end
+        else
+          super
+        end
+      end
+
+      def &(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_and(self)
+          else
+            l, r = other.coerce(self)
+            l & r
+          end
+        else
+          super
+        end
+      end
+
+      def ^(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_xor(self)
+          else
+            l, r = other.coerce(self)
+            l ^ r
+          end
+        else
+          super
+        end
+      end
+
+      def <<(other)
+        if CArray === other
+          l, r = other.coerce(self)
+          l << r
+        else
+          super
+        end
+      end
+
+      def >>(other)
+        if CArray === other
+          l, r = other.coerce(self)
+          l >> r
+        else
+          super
+        end
+      end
+    end
+
+    [TrueClass, FalseClass].each do |klass|
+      refine(klass) do
+        def |(other)
+          if CArray === other && other.boolean?
+            other.bit_or(self)
+          else
+            super
+          end
+        end
+
+        def &(other)
+          if CArray === other && other.boolean?
+            other.bit_and(self)
+          else
+            super
+          end
+        end
+
+        def ^(other)
+          if CArray === other && other.boolean?
+            other.bit_xor(self)
+          else
+            super
+          end
+        end
+      end
+    end
+
+  end # module CoreExtensions
+end # class CArray

data/lib/carray/data_type_extension.rb

@@ -0,0 +1,250 @@
+#  Numo / NumPy-style factory class methods, gathered here as a
+#  best-effort soft compatibility layer.
+#
+#  Rationale (the apology this file owes the rest of carray):
+#
+#  carray's native idiom for building arrays is the typed
+#  constructor (CArray.float64(3, 3) { 0 }, CA_INT([1, 2, 3]), and
+#  friends).  The methods below -- zeros / ones / eye / identity /
+#  linspace / arange / full / meshgrid -- duplicate that
+#  functionality with NumPy / Numo-flavoured names.  They exist
+#  for one specific reason: when a user is porting a NumPy or Numo
+#  example program over to carray, the first thing they hit is
+#  the array-creation entry point, and "I have to learn a whole
+#  different API just to call zeros" is the worst place to lose
+#  someone.  Having these helpers means a paste from
+#
+#     np.zeros((3, 3))            -> CArray.zeros([3, 3])
+#     np.full((3, 3), 7)          -> CArray.full([3, 3], 7)
+#     np.linspace(0.0, 1.0, 5)    -> CArray.linspace(0.0, 1.0, 5)
+#     Numo::DFloat.zeros(3, 3)    -> CArray::Float64.zeros(3, 3)
+#
+#  works with minimal rewriting.  Both the splat-shape carray-ish
+#  form (CArray.zeros(3, 3)) and the array-shape NumPy-ish form
+#  (CArray.zeros([3, 3])) are accepted by the shape-taking
+#  factories.
+#
+#  The methods land on CArray itself and on every typed class
+#  (CArray::Int32, CArray::Float64, etc.) via the
+#  DataTypeExtension module declared (empty) in
+#  lib/carray/construct.rb.  Required AFTER construct.rb in
+#  lib/carray.rb so the module exists -- the extends in construct
+#  see this file's method additions transparently.
+#
+#  meshgrid was previously in this file; it is now in
+#  lib/carray/methods/meshgrid.rb (autoloaded on first call).
+#
+#  These helpers are not the "main" carray API.  When writing new
+#  carray-flavoured code, prefer the typed constructors.  Use
+#  these when porting external code or when a NumPy / Numo
+#  spelling reads more naturally to the audience.
+
+class CArray
+
+  module DataTypeExtension
+
+    def guess_data_type_from_values (*values)
+      if values.all? {|v| v == true || v == false }
+        CA_BOOLEAN
+      elsif values.all? { |v| v.is_a?(Integer) }
+        CA_INT64
+      elsif values.all? { |v| v.is_a?(Float) }
+        CA_FLOAT64
+      elsif values.all? { |v| v.is_a?(Complex) }
+        CA_CMPLX128
+      else
+        CA_OBJECT
+      end
+    end
+
+    private :guess_data_type_from_values
+
+    # Normalize a shape argument list: accept both
+    #
+    #   foo(3, 4)     # splat (carray-style)
+    #   foo([3, 4])   # Array (NumPy-style: foo((3, 4)))
+    #
+    # so users can paste NumPy / Numo example code with minimal
+    # rewriting.
+    def normalize_shape (args)
+      if args.size == 1 && args.first.is_a?(Array)
+        args.first
+      else
+        args
+      end
+    end
+
+    private :normalize_shape
+
+    # @overload zeros(*shape)
+    #   Returns a new CArray of the given shape filled with zeros.
+    #   Shape accepts both splat Integers and a single Array. When
+    #   called on a typed class the `data_type` is taken from the
+    #   class; otherwise it defaults to `CA_FLOAT64`.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>] shape
+    #     of the result.
+    #   @return [CArray]
+    def zeros (*args)
+      CArray.new(self::DataType || CA_FLOAT64, normalize_shape(args)).zero
+    end
+
+    # @overload ones(*shape)
+    #   Returns a new CArray of the given shape filled with ones.
+    #   Same shape and `data_type` rules as {#zeros}.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>]
+    #   @return [CArray]
+    def ones (*args)
+      CArray.new(self::DataType || CA_FLOAT64, normalize_shape(args)).one
+    end
+
+    # @overload eye(n, m = n, k = 0)
+    #   Returns a 2-D CArray with ones on the `k`-th diagonal and
+    #   zeros elsewhere.
+    #   @param n [Integer] number of rows.
+    #   @param m [Integer] number of columns; defaults to `n`.
+    #   @param k [Integer] diagonal offset (positive above the main
+    #     diagonal, negative below).
+    #   @return [CArray] shape `(n, m)`.
+    def eye (n, m = nil, k = 0)
+      m ||= n
+      mat = CArray.new(self::DataType || CA_FLOAT64, [n, m])
+      if k >= 0
+        count = [n, m - k].min
+        start = k
+      else
+        count = [n + k, m].min
+        start = (-k) * m
+      end
+      if count > 0
+        mat[[start, count, m+1]] = 1
+      end
+      mat
+    end
+
+    # @overload identity(n)
+    #   Returns the `n` by `n` identity matrix.
+    #   @param n [Integer] matrix size.
+    #   @return [CArray] shape `(n, n)`.
+    def identity (n)
+      mat = CArray.new(self::DataType || CA_FLOAT64, [n, n])
+      mat[[nil,n+1]] = 1
+      mat
+    end
+
+    # @overload linspace(x1, x2, n = 100)
+    #   Returns a 1-D CArray of `n` values evenly spaced from `x1`
+    #   to `x2` inclusive, matching NumPy's `linspace`. For an integer
+    #   target `data_type`, values are computed in float64 with the
+    #   linspace step `(x2 - x1) / (n - 1)`, then floored to the target
+    #   type — the rule `np.linspace(x1, x2, n, dtype=int)` uses (round
+    #   toward -infinity, not toward zero). Both endpoints are hit
+    #   exactly for integer output when `x1` and `x2` are
+    #   integer-valued.
+    #
+    #   Called on `CArray` itself (module method) integer inputs promote
+    #   to `CA_FLOAT64` and the result is a float array. Called via an
+    #   integer subclass (`CArray::Int32.linspace(...)`), the result is
+    #   an integer array with floor semantics.
+    #
+    #   @param x1 [Numeric] first value.
+    #   @param x2 [Numeric] last value.
+    #   @param n [Integer] number of samples.
+    #   @return [CArray]
+    def linspace (x1, x2, n = 100)
+      data_type = self::DataType
+      unless data_type
+        guess = guess_data_type_from_values(x1, x2)
+        guess = CA_FLOAT64 if guess == CA_INT64
+        data_type = guess
+      end
+      #  span is float-only ("N evenly-spaced integers" is ambiguous —
+      #  see basics.rb).  Route non-float targets through a float64
+      #  span, then floor + cast; this matches np.linspace(dtype=int)
+      #  bit for bit (floor rounds toward -infinity so negative
+      #  midpoints go the same way as numpy's integer linspace).
+      float_out = CArray.new(CA_FLOAT64, [n]).span(x1.to_f..x2.to_f)
+      return float_out if data_type == CA_FLOAT64
+      float_out.floor.to_type(data_type)
+    end
+
+    # @overload arange(stop)
+    #   Returns a 1-D CArray with values `0, 1, ..., stop - 1`.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @return [CArray]
+    # @overload arange(start, stop)
+    #   Returns `start, start + 1, ..., stop - 1`.
+    #   @param start [Numeric] inclusive lower bound.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @return [CArray]
+    # @overload arange(start, stop, step)
+    #   Returns values from `start` to `stop` (exclusive) stepping
+    #   by `step`.
+    #   @param start [Numeric] inclusive lower bound.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @param step [Numeric] spacing.
+    #   @return [CArray]
+    def arange (*args)
+      case args.size
+      when 3
+        start, stop, step = *args
+      when 2
+        start, stop = *args
+        step = 1
+      when 1
+        start = 0
+        stop, = *args
+        step = 1
+      else
+        raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1..3)"
+      end
+      raise ArgumentError, "step must not be 0" if step == 0
+      data_type = self::DataType
+      data_type ||= guess_data_type_from_values(start, stop, step)
+      #  Element count comes from the arguments as given, not from the
+      #  target data type: CArray::Int32.arange(0, 1, 0.25) counts four
+      #  elements from the float step and truncates them on store.
+      #  Integer arguments count exactly (divmod) so that a step dividing
+      #  the span evenly does not gain a spurious element through float
+      #  rounding.
+      span = stop - start
+      if span.is_a?(Integer) && step.is_a?(Integer)
+        q, r = span.divmod(step)
+        n = r.zero? ? q : q + 1
+      else
+        n = (span.to_f / step).ceil
+      end
+      n = 0 if n < 0
+      CArray.new(data_type, [n]).seq(start, step)
+    end
+
+    # @overload full(shape, fill_value)
+    #   Returns a new CArray of the given shape filled with
+    #   `fill_value`. `shape` accepts an Integer or an Array of
+    #   Integers. The `data_type` is inferred from `fill_value`
+    #   when the receiver is not a typed class.
+    #   @param shape [Integer, Array<Integer>]
+    #   @param fill_value [Object] value used to fill the array.
+    #   @return [CArray]
+    def full (shape, fill_value)
+      data_type = self::DataType
+      data_type ||= guess_data_type_from_values(fill_value)
+      shape = [shape] unless shape.is_a?(Array)
+      CArray.new(data_type, shape).fill(fill_value)
+    end
+
+    # @overload empty(*shape)
+    #   Returns a new CArray of the given shape whose contents are
+    #   **uninitialised**. The caller must overwrite the array
+    #   before reading from it. `CA_OBJECT` silently falls back to
+    #   a zero-VALUE init required for GC safety.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>]
+    #   @return [CArray]
+    def empty (*args)
+      CArray.__alloc_uninit__(self::DataType || CA_FLOAT64,
+                              normalize_shape(args))
+    end
+
+  end
+
+end
+

data/lib/carray/fixlen_string.rb

@@ -0,0 +1,95 @@
+# ----------------------------------------------------------------------------
+#
+#  CAFixlenString high-level construction surface.
+#
+#  CAFixlenString itself (the string interpretation of CA_FIXLEN storage) lives
+#  in ext/ca_obj_string.c.  This file provides the ergonomic builder that packs
+#  Ruby Strings into a fixed-width CA_FIXLEN entity and wraps it via
+#  CAFixlenString.wrap.
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+
+  # Build a CAFixlenString (fixed-width String array over CA_FIXLEN storage).
+  #
+  #   CArray.fixlen_string(["ab", "cde"], bytes: 4)   # explicit slot width
+  #   CArray.fixlen_string(["ab", "cde"])             # width = max bytesize
+  #   CArray.fixlen_string([a, nil, b], bytes: 8)     # nil → masked element
+  #
+  # The bounded slot width is the storage seam CAFixlenString exposes.
+  # `truncate:` controls what happens when
+  # a value exceeds `bytes` (only reachable when `bytes` is given explicitly;
+  # the auto width can never overflow):
+  #
+  #   :error   (default) raise ArgumentError on overflow — loud data loss
+  #   :silent  let the native fixlen store keep the leading `bytes` bytes
+  #
+  # The overflow policy lives at this construction surface, not at per-cell
+  # `fix[i] = v` (which always truncates silently via the native fixlen store).
+  # A CArray source is normalised through a String Face
+  # ({CArray.string_face_of}): a raw CA_FIXLEN of matching width wraps
+  # zero-copy, other string-bearing arrays materialise, numeric is rejected.
+  # @overload fixlen_string(values, bytes: nil, truncate: :error)
+  #   @param values [Array<String, nil>] source values.
+  #   @param bytes [Integer, nil] slot width; defaults to the max bytesize.
+  #   @param truncate [Symbol] `:error` or `:silent`.
+  #   @return [CAFixlenString]
+  # @overload fixlen_string(ca, bytes: nil, truncate: :error)
+  #   @param ca [CArray] a String Face, CA_OBJECT, or raw CA_FIXLEN array.
+  #   @return [CAFixlenString]
+  #   @raise [CArray::DataTypeError] if `ca` is numeric / boolean.
+  # @overload fixlen_string(n, bytes: nil, truncate: :error) { |i| ... }
+  #   @param n [Integer] element count.
+  #   @param bytes [Integer, nil] slot width; defaults to the max bytesize.
+  #   @param truncate [Symbol] `:error` or `:silent`.
+  #   @return [CAFixlenString]
+  def self.fixlen_string (arg, bytes: nil, truncate: :error, &block)
+    if arg.is_a?(CArray)
+      return string_face_of(arg).to_fixlen_string(bytes: bytes, truncate: truncate)
+    end
+    unless [:error, :silent].include?(truncate)
+      raise ArgumentError, "truncate: must be :error or :silent (got #{truncate.inspect})"
+    end
+    if block
+      n = Integer(arg)
+      if block.arity == 0
+        v = block.call
+        values = Array.new(n) { v }
+      else
+        values = Array.new(n) { |i| block.call(i) }
+      end
+    else
+      values = arg.to_a
+    end
+
+    width = bytes || values.compact.map { |s| s.to_s.bytesize }.max || 1
+    width = 1 if width < 1
+
+    if truncate == :error
+      values.each_with_index do |s, i|
+        next if s.nil?
+        b = s.to_s.bytesize
+        if b > width
+          raise ArgumentError,
+                "CArray.fixlen_string: value at #{i} is #{b} bytes, exceeds slot width #{width} " \
+                "(use truncate: :silent to keep the leading bytes)"
+        end
+      end
+    end
+
+    entity = CArray.new(CA_FIXLEN, [values.size], :bytes => width)
+    values.each_with_index do |s, i|
+      entity[i] = s.nil? ? UNDEF : s.to_s
+    end
+    CAFixlenString.wrap(entity)
+  end
+
+end
+
+# Mutable fixed-width String Face: L1 ops + in-place variants.  In-place
+# transforms re-store through the native fixlen path (silent truncate).
+class CAFixlenString
+  include CArray::StringOperationMixin
+  include CArray::StringOperationMixin::Mutable
+end