carray 2.0.0 → 3.0.0

data/lib/carray/mkmf.rb

@@ -1,15 +1,10 @@
-# ----------------------------------------------------------------------------
-#
-#  carray/mkmf.rb
-#
-#  This file is part of Ruby/CArray extension library.
-#
-#  Copyright (C) 2005-2020 Hiroki Motoyoshi
-#
-# ----------------------------------------------------------------------------
-
 require 'mkmf'
 
+# Locates an installed Ruby/CArray and wires its header (and, on Windows,
+# its import library) into the extension being configured.  Call this at the
+# top of a companion gem's `extconf.rb`.
+#
+# @return [Boolean] whether every required piece was found.
 def have_carray 
   begin
     require 'carray'
@@ -18,28 +13,10 @@ def have_carray
   end
   $LOAD_PATH.each do |path|
     if File.exist? File.join(path, 'carray.h')
-      dir_config("carray", path, path)      
+      dir_config("carray", path, path)
       break
     end
   end
-=begin  
-  dir_config("carray", $sitearchdir, $sitearchdir)
-  if defined? Gem
-    if Gem::VERSION >= "1.7.0"
-      begin
-        Gem::Specification.find_all_by_name("carray").each do |spec|
-          dir = spec.full_gem_path
-          dir_config("carray", dir, dir)      
-        end
-      rescue Gem::LoadError
-      end
-    else
-      Gem.all_load_paths.grep(/narray/).each do |dir|
-        dir_config("carray", dir, dir)      
-      end
-    end
-  end
-=end
   status = true
   status &= have_header("carray.h")
   if /cygwin|mingw/ =~ RUBY_PLATFORM
@@ -48,79 +25,25 @@ def have_carray
   status
 end
 
-def check_fortran
-
-  SRC_EXT << "f" << "f90" << "f95"
-
-  fortran = with_config("fortran", "gfortran")
-  fflags  = with_config("fflags", "")
-
-  case fortran
-  when /\Ag77/
-    libdir = File.dirname(`#{fortran} --print-file-name=libg2c.a`)
-    dir_config("g2c", possible_includes, [libdir]+possible_libs)
-    have_library("g2c")
-    fc = fortran
-    fflags << " -O2 -g "
-  when /\Agfortran/
-    libdir = File.dirname(`#{fortran} --print-file-name=libgfortran.a`)
-    dir_config("gfortran", possible_includes, [libdir]+possible_libs)
-    have_library("gfortran")
-    fc = fortran
-    fflags << " -O2 -g -fPIC "
-  when /\Aintel/, /\Aifort/, /\Aifc/
-    libdir = File.join(File.dirname(File.dirname(`which ifort`)), "lib")
-    dir_config("ifcore", possible_includes, [libdir]+possible_libs)
-    have_library("ifcore")
-    have_library("ifport")
-    have_library("imf")
-    have_library("irc")
-    have_library("svml")
-    have_library("unwind")
-    fc = "ifort"
-    fflags << " -O2 -fPIC "
-  when /\Afujitsu/, /\Afrt/
-    libdir = File.join(File.dirname(File.dirname(`which frt`)), "lib")
-    dir_config("fj9f6", nil, libdir)
-    $LIBS = " -lfj9i6 -lfj9f6"
-    fc = "frt"
-    fflags = " -O -fw "
-  else
-    puts "unknown fortran option <#{fortran}>"
-    exit(1)
-  end
-  at_exit {
-    if File.file?("Makefile")
-      makefile = File.read("Makefile")
-      unless makefile =~ /^FC=/
-        makefile.sub!(/^COPY =.*$/, 
-                      '\0' + "\n\n" +
-                      "FC=#{fc}\n" +
-                      "FFLAGS=#{fflags}\n")
-      end
-      open("Makefile", "w") { |io| io.write(makefile) }
-    end
-  }
-
-  return "--with-fortran='#{fortran}' --with-fflags='#{fflags}'"
-
-end
-
+# @!visibility private
 def possible_prefix (*postfixes)
   dirs = [
-    File.expand_path("~/usr"),   ### user's home / usr
-    File.expand_path("~/local"), ### user's home / local
-    File.expand_path("~"),       ### user's home
-    "/opt/local",                ### MacPorts
-    "/opt/homebrew",             ### Homebrew
-    "/opt",                      ### UNIX 
-    "/sw/local",                 ### Mac Fink
-    "/sw/",                      ### Mac Fink
-    "/usr/X11R6",                ### UNIX X11
-    "/usr/local",                ### UNIX
-    "/usr",                      ### UNIX
-    "/"                          ### UNIX
-  ]
+    ENV["CONDA_PREFIX"],           ### active conda / mamba env
+    ENV["HOMEBREW_PREFIX"],        ### Homebrew (non-standard install path)
+    File.expand_path("~/usr"),     ### user's home / usr
+    File.expand_path("~/local"),   ### user's home / local
+    File.expand_path("~/.local"),  ### user's home / .local (XDG, pip --user)
+    File.expand_path("~"),         ### user's home
+    "/opt/local",                  ### MacPorts
+    "/opt/homebrew",               ### Homebrew (Apple Silicon)
+    "/opt",                        ### UNIX
+    "/sw/local",                   ### Mac Fink
+    "/sw/",                        ### Mac Fink
+    "/usr/X11R6",                  ### UNIX X11
+    "/usr/local",                  ### UNIX
+    "/usr",                        ### UNIX
+    "/"                            ### UNIX
+  ].compact
   if postfixes
     dirs = postfixes.inject(dirs) { |list, postfix|
       list + dirs.map{|d| File.join(d, postfix) }
@@ -129,8 +52,10 @@ def possible_prefix (*postfixes)
   return dirs.select{|d| File.directory?(d)}
 end
 
+# @!visibility private
 POSSIBLE_PREFIX = possible_prefix()
 
+# @!visibility private
 def possible_libs (*postfixes)
   dirs = possible_prefix().map{|prefix| File.join(prefix, "lib") }
   if postfixes
@@ -141,12 +66,110 @@ def possible_libs (*postfixes)
   return dirs.select{|d| File.directory?(d)}
 end
 
+# @!visibility private
 def possible_includes (*postfixes)
   dirs = possible_prefix().map{|prefix| File.join(prefix, "include") }
   if postfixes
     dirs = postfixes.inject(dirs) { |list, postfix|
       list + dirs.map{|d| File.join(d, postfix) }
     }
-  end 
+  end
   return dirs.select{|d| File.directory?(d)}
 end
+
+# Configure include/library search for a dependency, preferring its own
+# build description over brute-force prefix probing.
+#
+# If the dependency ships a pkg-config file (`<pkg>.pc`), use it to obtain
+# cflags / libs and stop.  Otherwise fall back to scanning possible_includes
+# / possible_libs (the only option for hand-rolled scientific libraries
+# that do not provide a `.pc` file, e.g. nn / ngmath / FITPACK).
+#
+#   carray_dir_config("gsl")           # gsl.pc -> done
+#   carray_dir_config("nn")            # no .pc -> possible_* probe
+#   carray_dir_config("foo", "libfoo") # search foo.pc / libfoo.pc as "libfoo"
+#
+def carray_dir_config (name, pkg = name)
+  return true if pkg_config(pkg)
+  dir_config(name, possible_includes, possible_libs)
+  true
+end
+
+# --- pluggable Fortran backend registry
+#
+# CArray no longer tries to enumerate every Fortran compiler.  Only
+# gfortran ships out of the box.  A companion gem (or a user's extconf)
+# that needs another compiler registers a backend *before* calling
+# check_fortran:
+#
+#   register_fortran_backend(/ifx|ifort/) do |fc|
+#     libdir = ...                              # locate the runtime
+#     dir_config("ifcore", possible_includes, [libdir] + possible_libs)
+#     have_library("ifcore")
+#   end
+#   check_fortran("--with-fortran=ifx")
+#
+# A backend receives the compiler command and is responsible only for
+# linking that compiler's runtime library (dir_config + have_library).
+#
+# @!visibility private
+FORTRAN_BACKENDS = {}
+
+# Registers a Fortran runtime backend for {check_fortran} to pick up.  Only
+# gfortran ships out of the box; a companion gem that needs another compiler
+# registers its own before calling {check_fortran}.  The block receives the
+# compiler command and is responsible only for linking that compiler's
+# runtime library (`dir_config` + `have_library`).
+#
+# @param pattern [Regexp] matched against the configured compiler command.
+# @yieldparam fc [String] the compiler command.
+# @return [void]
+def register_fortran_backend (pattern, &block)
+  FORTRAN_BACKENDS[pattern] = block
+end
+
+# gfortran: the one compiler CArray supports out of the box.
+register_fortran_backend(/gfortran/) do |fc|
+  libdir = File.dirname(`#{fc} --print-file-name=libgfortran.a`.strip)
+  dir_config("gfortran", possible_includes, [libdir] + possible_libs)
+  have_library("gfortran")
+end
+
+# Configures the extension to compile Fortran sources, selecting the compiler
+# from `--with-fortran` (default `gfortran`) and its flags from
+# `--with-fflags`.  The matching backend registered by
+# {register_fortran_backend} links that compiler's runtime; an unmatched
+# compiler warns and leaves the runtime to `LIBS` / `--with-fflags`.
+#
+# @return [void]
+def check_fortran
+
+  SRC_EXT << "f" << "f90" << "f95"
+
+  fc     = with_config("fortran", "gfortran")
+  fflags = with_config("fflags", "-O2 -g -fPIC")
+
+  _pattern, backend = FORTRAN_BACKENDS.find { |pat, _| pat =~ fc }
+  if backend
+    backend.call(fc)
+  else
+    warn "carray/mkmf: no backend for fortran '#{fc}'; " \
+         "register one with register_fortran_backend or pass the " \
+         "runtime via LIBS / --with-fflags"
+  end
+
+  at_exit do
+    if File.file?("Makefile")
+      makefile = File.read("Makefile")
+      unless makefile =~ /^FC=/
+        makefile.sub!(/^COPY =.*$/,
+                      '\0' + "\n\n" +
+                      "FC=#{fc}\n" +
+                      "FFLAGS=#{fflags}\n")
+      end
+      File.write("Makefile", makefile)
+    end
+  end
+
+  return fc
+end

data/lib/carray/runtime.rb

@@ -0,0 +1,108 @@
+# Load-bearing Ruby support that the core depends on at run time.  Unlike
+# carray/basics.rb (convenience methods kept eager merely because they are
+# frequent), the definitions here are NOT optional: removing or lazy-loading
+# them breaks core behaviour.  Keep this file eager-loaded.
+
+class CArray
+
+  # String fallback for the global cast functions CA_INT32(data) etc.  The C
+  # dispatcher (ext/carray_cast.c) handles every other input class in C and
+  # delegates only String here, because the whitespace / `,` / `;` /
+  # `_`->UNDEF parser is far more natural (and maintainable) in Ruby.
+  # +type+ arrives as the data_type Symbol.  Required: without it
+  # +CA_INT32("1 2 3")+ and friends raise.
+  def self.__cast_string__ (type, v) # :nodoc:
+    if type == CA_OBJECT
+      return CScalar.new(CA_OBJECT) { v }
+    elsif type == CA_BOOLEAN
+      v = v.dup
+      v.tr!('^01',"1")
+      v.tr!('01',"\x0\x1")
+      return CArray.boolean(v.length).load_binary(v)
+    else
+      case v
+      when /;/
+        v = v.strip.split(/\s*;\s*/).
+                         map{|s| s.split(/\s+|\s*,\s*/).map{|x| x=='_' ? UNDEF : x} }
+      else
+        v = v.strip.split(/\s+|\s*,\s*/).map{|x| x=='_' ? UNDEF : x}
+      end
+      return CArray.new(type, CArray.guess_array_shape(v)).tap { |a| a[] = v }
+    end
+  end
+  private_class_method :__cast_string__
+
+  # CA_OBJECT escape for the weighted-sum kernel (mkkernel object_escape:).
+  # The C dispatcher (carray_kernels.c rb_ca_wsum_ki) intercepts CA_OBJECT
+  # source and forwards here verbatim, because a per-cell object weighted sum
+  # is more naturally (and exactly, for Rational / BigDecimal weights) a
+  # +(self * weights).sum+ composition than a dedicated :object kernel branch.
+  #
+  # +weights+ is a Ruby Numeric scalar (W-A1) or a same-shape CArray; the 1-D
+  # axis-broadcast form (W-A2) is not supported for object weights (pass a
+  # scalar or a full-shape weight), matching CArray's explicit-broadcast rule.
+  # +opts+ is the trailing options Hash (axis:/keep_axis:/min_count:/
+  # fill_value:) forwarded verbatim by the C escape; it goes straight to +sum+.
+  def __wsum_object__ (weights, opts = {}) # :nodoc:
+    (self * weights).sum(**opts)
+  end
+  private :__wsum_object__
+
+  # CA_OBJECT escape for the weighted-mean kernel.  Weighted mean is
+  # +Σ(w*v) / Σw+ over the cells valid after mask overlay (a masked value OR a
+  # masked weight drops the cell from BOTH sums).  The denominator is guarded:
+  # an empty / all-masked slab or weights summing to zero yields UNDEF (the
+  # object analogue of the numeric kernel's 0/0 -> NaN, since objects have no
+  # NaN).  Weight forms and +opts+ as in {#__wsum_object__}.
+  def __wmean_object__ (weights, opts = {}) # :nodoc:
+    axis      = opts[:axis]
+    keep_axis = opts[:keep_axis]
+    prod = self * weights
+    wv   = (weights.is_a?(CArray) ? weights : self * 0 + weights).copy
+    wv[prod.is_masked] = UNDEF if prod.has_mask?
+    nopt = { axis: axis, keep_axis: keep_axis }
+    nopt[:min_count] = opts[:min_count] unless opts[:min_count].nil?
+    num = prod.sum(**nopt)
+    den = wv.sum(axis: axis, keep_axis: keep_axis)
+    result =
+      if axis
+        den = den.copy
+        den[den.eq(0)] = UNDEF          # zero / empty denominator -> undetermined
+        num / den                        # UNDEF propagates cell-wise
+      elsif den.equal?(UNDEF) || den == 0
+        UNDEF
+      else
+        num / den
+      end
+    fill_value = opts[:fill_value]
+    return result if fill_value.nil?
+    if result.is_a?(CArray)
+      result[result.is_masked] = fill_value if result.has_mask?
+      result
+    else
+      result.equal?(UNDEF) ? fill_value : result
+    end
+  end
+  private :__wmean_object__
+
+end
+
+class CAUnboundRepeat
+  # Overrides {CArray#template} for unbound-repeat views.
+  #
+  # The C-level `CArray#template` allocates an entity sized to `self.shape`,
+  # which for a CAUnboundRepeat would include the inflated unbound (`:*`)
+  # axes — semantically wrong (unbound axes are not yet bound to a size)
+  # and a memory bomb on broadcast patterns.  Required for correctness.
+  #
+  # This override allocates at the **parent's compact shape** instead, then
+  # rewraps the result with the same `spec` so the returned view preserves
+  # the unbound broadcast pattern.
+  #
+  # @param argv [Array] forwarded to {CArray#template} (data_type, bytes:, ...)
+  # @yield forwarded to {CArray#template}
+  # @return [CAUnboundRepeat] new entity wrapped with the original unbound spec
+  def template (*argv, &block)
+    return parent.template(*argv,&block)[*spec.map{|x| x != :* ? nil : x}]
+  end
+end