convolver 2.0.0 → 3.0.1

data/lib/convolver/operation_shapes.rb

@@ -1,33 +1,46 @@
 # frozen_string_literal: true
 
+require 'convolver/real_fft_shape'
+require 'convolver/fft_limits'
+
 module Convolver
   # Calculates and validates output, extension, and FFT dimensions.
+  # @private
   class OperationShapes
     SIZE_MAX = (1 << ([0].pack('J').bytesize * 8)) - 1
 
     attr_reader :padding_before, :padding_after, :result_shape,
                 :extended_shape, :result_size, :extended_size
 
-    def initialize(signal_shape, kernel_shape, mode:, anchors:)
+    def initialize(signal_shape, kernel_shape, operation:, mode:, anchors:)
+      @operation = operation
       @mode = mode
       calculate_shapes(signal_shape, kernel_shape, anchors)
       validate_sizes!
     end
 
-    def linear_fft_shape(kernel_shape)
-      checked_shape(
-        extended_shape.zip(kernel_shape).map { |signal_size, kernel_size| signal_size + kernel_size - 1 },
-        'FFT shape'
-      )
+    def linear_fft_shape(kernel_shape, limits: FftLimits.new)
+      return [].freeze if kernel_shape.empty?
+
+      RealFftShape.new(linear_result_shape(kernel_shape), size_max: SIZE_MAX, limits:).call
     end
 
     def linear_fft_size(kernel_shape)
       checked_product(linear_fft_shape(kernel_shape), 'FFT size')
     end
 
+    def linear_spectrum_size(kernel_shape)
+      shape = linear_fft_shape(kernel_shape)
+      return 1 if shape.empty?
+
+      spectrum_shape = shape.dup
+      spectrum_shape[-1] = (spectrum_shape[-1] / 2) + 1
+      checked_product(spectrum_shape, 'FFT spectrum size')
+    end
+
     private
 
-    attr_reader :mode
+    attr_reader :operation, :mode
 
     def calculate_shapes(signal_shape, kernel_shape, anchors)
       @padding_before, @padding_after, @result_shape = shapes_for(signal_shape, kernel_shape, anchors)
@@ -53,8 +66,15 @@ module Convolver
     end
 
     def same_shapes(signal_shape, kernel_shape, anchors)
-      before = anchors.dup.freeze
-      after = kernel_shape.zip(anchors).map { |kernel_size, anchor| kernel_size - 1 - anchor }.freeze
+      correlation_before = anchors.dup
+      correlation_after = kernel_shape.zip(anchors).map { |kernel_size, anchor| kernel_size - 1 - anchor }
+      before, after = if operation == :correlation
+                        [correlation_before, correlation_after]
+                      else
+                        [correlation_after, correlation_before]
+                      end
+      before.freeze
+      after.freeze
       [before, after, signal_shape.dup]
     end
 
@@ -90,6 +110,19 @@ module Convolver
         product * size
       end
     end
+
+    def linear_result_shape(kernel_shape)
+      shape = extended_shape.zip(kernel_shape).map do |signal_size, kernel_size|
+        checked_add(signal_size, kernel_size - 1, 'FFT shape')
+      end
+      checked_shape(shape, 'FFT shape')
+    end
+
+    def checked_add(left, right, description)
+      return left + right if right <= SIZE_MAX - left
+
+      raise RangeError, "#{description} exceeds native implementation limit"
+    end
   end
 
   private_constant :OperationShapes

data/lib/convolver/real_fft_shape.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'convolver/fft_limits'
+
+module Convolver
+  # Selects a safe real-transform shape from exact/even and fast candidates.
+  # @private
+  class RealFftShape
+    def initialize(minimum_shape, size_max:, limits: nil)
+      @minimum_shape = minimum_shape
+      @size_max = size_max
+      @limits = limits
+    end
+
+    def call
+      exact_shape = even_final_axis(minimum_shape)
+      candidates = [exact_shape, fast_shape(exact_shape)].compact.select { |shape| admissible?(shape) }
+      (candidates.min_by { |shape| transform_cost(shape) } || raise_rejection).freeze
+    end
+
+    private
+
+    attr_reader :minimum_shape, :size_max, :limits
+
+    def admissible?(shape)
+      return false unless representable?(shape)
+
+      limits&.validate!(shape, real_axis: shape.length - 1)
+      true
+    rescue FftUnavailable => e
+      @rejection ||= e
+      false
+    end
+
+    def raise_rejection
+      raise @rejection if @rejection
+
+      raise_overflow
+    end
+
+    def fast_shape(exact_shape)
+      fast_shape = exact_shape.map.with_index do |size, axis|
+        next_fast_size(size, even: axis == exact_shape.length - 1)
+      end
+      fast_shape if fast_shape.all?
+    end
+
+    def even_final_axis(shape)
+      result = shape.dup
+      result[-1] = checked_add(result[-1], 1) if result[-1].odd?
+      result.freeze
+    end
+
+    def next_fast_size(target, even:)
+      best = nil
+      each_power(5) do |power_of_five|
+        each_power(3, power_of_five) do |power_of_three|
+          candidate = doubled_candidate(power_of_three, target, even)
+          best = candidate if candidate && (!best || candidate < best)
+        end
+      end
+      best
+    end
+
+    def each_power(factor, initial = 1)
+      value = initial
+      loop do
+        yield value
+        break if value > size_max / factor
+
+        value *= factor
+      end
+    end
+
+    def doubled_candidate(initial, target, even)
+      candidate = initial
+      while candidate < target || (even && candidate.odd?)
+        return nil if candidate > size_max / 2
+
+        candidate *= 2
+      end
+      candidate
+    end
+
+    def transform_cost(shape)
+      shape.reduce(:*) * shape.sum { |size| Math.log2(size) + large_factor_penalty(size) }
+    end
+
+    def large_factor_penalty(size)
+      prime_factors(size).sum do |factor|
+        factor > 7 ? 1.5 * (Math.log2(factor) - 3) : 0.0
+      end
+    end
+
+    def prime_factors(value)
+      factors = []
+      divisor = 2
+      while divisor * divisor <= value
+        value = extract_factor(value, divisor, factors)
+        divisor += divisor == 2 ? 1 : 2
+      end
+      factors << value if value > 1
+      factors
+    end
+
+    def extract_factor(value, divisor, factors)
+      while (value % divisor).zero?
+        factors << divisor
+        value /= divisor
+      end
+      value
+    end
+
+    def representable?(shape)
+      shape.reduce(1) do |product, size|
+        return false if !product.zero? && size > size_max / product
+
+        product * size
+      end
+      true
+    end
+
+    def checked_add(left, right)
+      return left + right if right <= size_max - left
+
+      raise_overflow
+    end
+
+    def raise_overflow
+      raise(limits ? FftUnavailable : RangeError, 'FFT shape exceeds native implementation limit')
+    end
+  end
+
+  private_constant :RealFftShape
+end

data/lib/convolver/signal_extension.rb

@@ -2,6 +2,7 @@
 
 module Convolver
   # Extends a signal according to one operation's boundary policy.
+  # @private
   class SignalExtension
     def initialize(shapes, boundary:, fill_value:)
       @shapes = shapes

data/lib/convolver/version.rb

@@ -2,5 +2,5 @@
 
 module Convolver
   # Current gem version.
-  VERSION = '2.0.0'
+  VERSION = '3.0.1'
 end

data/lib/convolver.rb

@@ -5,153 +5,136 @@ require 'numo/pocketfft'
 require 'convolver/convolver'
 require 'convolver/version'
 
-# Cross-correlation operations for Numo::NArray values.
+# Mathematical convolution and cross-correlation for Numo::NArray values.
 module Convolver
   # Maximum number of dimensions supported by the implementations.
   MAX_RANK = 16
 
   require 'convolver/operation_plan'
+  require 'convolver/linear_fft_operation'
+  require 'convolver/circular_fft_operation'
+  require 'convolver/fft_estimator'
+  require 'convolver/operation_execution'
 
   class << self
-    # Chooses the likely fastest cross-correlation implementation.
+    # Chooses the likely fastest mathematical convolution implementation.
     #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
-    # @param mode [:valid, :same, :full] returned output extent
-    # @param boundary [:constant, :nearest, :reflect, :mirror, :wrap] signal extension
-    # @param fill_value [Numeric] constant extension value
-    # @param origin [Integer, Array<Integer>] kernel origin shift
-    # @return [Numo::SFloat] cross-correlation result
-    # @raise [ArgumentError] if inputs or options are incompatible
+    # Results use single precision. Inputs must be nonempty arrays of equal
+    # rank, with at most {MAX_RANK} dimensions. Scalars multiply directly.
+    # In valid mode the kernel must fit inside the signal in every dimension.
+    # Full mode permits only constant boundaries; nonconstant boundaries and
+    # nonzero origins are supported only in same mode.
+    #
+    # @param signal [Numo::NArray] input signal
+    # @param kernel [Numo::NArray] convolution kernel
+    # @param mode [:valid, :same, :full] output extent (default: :valid)
+    # @param boundary [:constant, :nearest, :reflect, :mirror, :wrap]
+    #   signal extension policy (default: :constant)
+    # @param fill_value [Numeric] constant boundary value (default: 0);
+    #   valid mode requires zero, and other boundaries reject this option
+    # @param origin [Integer, Array<Integer>] offset from the kernel midpoint,
+    #   shared across axes or one per axis (default: 0)
+    # @return [Numo::SFloat] mathematical convolution result
+    # @raise [ArgumentError] if inputs or options are invalid
+    # @raise [RangeError] if planned dimensions, buffers or FFT arithmetic exceed native limits
     def convolve(signal, kernel, mode: :valid, boundary: :constant,
                  fill_value: UNSPECIFIED_FILL, origin: 0)
-      plan = operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      options = operation_options(mode, boundary, fill_value, origin)
-
-      return convolve_basic(signal, kernel, **options) if plan.extended_size < 1000 || kernel.size < 100
-
-      basic_time_predicted = predict_convolve_basic_time(signal, kernel, **options)
-      return convolve_basic(signal, kernel, **options) if basic_time_predicted < 0.1
-
-      fft_time_predicted = predict_convolve_fft_time(signal, kernel, **options)
-      return convolve_fft(signal, kernel, **options) if fft_time_predicted < 2 * basic_time_predicted
-
-      convolve_basic(signal, kernel, **options)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).automatic(self)
     end
 
-    # Uses the direct native valid primitive after applying the requested signal
-    # extension in Ruby.
-    #
+    # Chooses the likely fastest cross-correlation implementation.
+    # Uses the same input and option rules as {.convolve}, without reversing
+    # the kernel's orientation.
+    # @param (see convolve)
     # @return [Numo::SFloat] cross-correlation result
+    # @raise (see convolve)
+    def correlate(signal, kernel, mode: :valid, boundary: :constant,
+                  fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).automatic(self)
+    end
+
+    # Uses the direct native mathematical convolution implementation.
+    # @param (see convolve)
+    # @return [Numo::SFloat] mathematical convolution result
+    # @raise (see convolve)
     def convolve_basic(signal, kernel, mode: :valid, boundary: :constant,
                        fill_value: UNSPECIFIED_FILL, origin: 0)
-      plan = operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      convolve_basic_valid(plan.extend_signal(signal), kernel)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).basic
     end
 
-    # Uses PocketFFT to calculate the requested cross-correlation.
-    #
-    # Periodic same-sized results use a circular transform. Other combinations
-    # use the shared extension plan and PocketFFT's linear convolution.
-    #
+    # Uses the direct native cross-correlation implementation.
+    # @param (see convolve)
     # @return [Numo::SFloat] cross-correlation result
+    # @raise (see convolve)
+    def correlate_basic(signal, kernel, mode: :valid, boundary: :constant,
+                        fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).basic
+    end
+
+    # Uses PocketFFT to calculate mathematical convolution.
+    # @param (see convolve)
+    # @return [Numo::SFloat] mathematical convolution result
+    # @raise (see convolve)
     def convolve_fft(signal, kernel, mode: :valid, boundary: :constant,
                      fill_value: UNSPECIFIED_FILL, origin: 0)
-      plan = operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      return convolve_fft_wrap(signal, kernel, plan) if plan.wrap?
-
-      convolve_fft_valid(plan.extend_signal(signal), kernel)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).fft
     end
 
-    # Compatibility alias for the former FFTW3-backed implementation.
-    #
-    # @deprecated Use {.convolve_fft}; Convolver no longer uses FFTW3.
+    # Uses PocketFFT to calculate cross-correlation.
+    # @param (see convolve)
     # @return [Numo::SFloat] cross-correlation result
-    def convolve_fftw3(signal, kernel, mode: :valid, boundary: :constant,
-                       fill_value: UNSPECIFIED_FILL, origin: 0)
-      warn 'Convolver.convolve_fftw3 is deprecated; use .convolve_fft instead', uplevel: 1
-      options = operation_options(mode, boundary, fill_value, origin)
-      convolve_fft(signal, kernel, **options)
+    # @raise (see convolve)
+    def correlate_fft(signal, kernel, mode: :valid, boundary: :constant,
+                      fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).fft
     end
 
-    # Estimates the relative cost of {.convolve_fft} for the requested options.
-    #
+    # Estimates the relative cost of {.convolve_fft}.
+    # This is a heuristic for algorithm selection, not a timing measurement.
+    # @param (see convolve)
     # @return [Float] machine-specific relative cost estimate
+    # @raise (see convolve)
     def predict_convolve_fft_time(signal, kernel, mode: :valid, boundary: :constant,
                                   fill_value: UNSPECIFIED_FILL, origin: 0)
-      plan = operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      transform_size = plan.wrap? ? signal.size : plan.linear_fft_size(kernel.shape)
-      transform_cost = 16 * 4.55e-08 * transform_size * Math.log(transform_size)
-      transform_cost + (4.55e-08 * fft_preparation_size(plan, signal, kernel))
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).fft_time
     end
 
-    # Estimates the relative cost of {.convolve_basic} for the requested options.
-    #
+    # Estimates the relative cost of {.correlate_fft}.
+    # This is a heuristic for algorithm selection, not a timing measurement.
+    # @param (see convolve)
     # @return [Float] machine-specific relative cost estimate
-    def predict_convolve_basic_time(signal, kernel, mode: :valid, boundary: :constant,
-                                    fill_value: UNSPECIFIED_FILL, origin: 0)
-      plan = operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      operations = plan.result_size * plan.extended_size * kernel.size
-      operations += plan.extended_size unless plan.valid?
-      4.54e-12 * operations
-    end
-
-    private
-
-    private :convolve_basic_valid
-
-    def operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      OperationPlan.new(signal, kernel, mode:, boundary:, fill_value:, origin:)
+    # @raise (see convolve)
+    def predict_correlate_fft_time(signal, kernel, mode: :valid, boundary: :constant,
+                                   fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).fft_time
     end
 
-    def operation_options(mode, boundary, fill_value, origin)
-      options = { mode:, boundary:, origin: }
-      options[:fill_value] = fill_value unless fill_value.equal?(UNSPECIFIED_FILL)
-      options
-    end
-
-    def convolve_fft_valid(signal, kernel)
-      ranges = kernel.shape.zip(signal.shape).map do |kernel_size, signal_size|
-        (kernel_size - 1)...signal_size
-      end
-      full_convolution = Numo::Pocketfft.fftconvolve(signal, kernel.reverse)
-
-      Numo::SFloat.cast(full_convolution[*ranges])
-    end
-
-    def convolve_fft_wrap(signal, kernel, plan)
-      signal_value = Numo::DFloat.cast(signal)
-      folded_kernel = fold_kernel(Numo::DFloat.cast(kernel), signal.shape, plan.anchors)
-      spectrum = Numo::Pocketfft.fftn(signal_value) * Numo::Pocketfft.fftn(folded_kernel).conj
-
-      Numo::SFloat.cast(Numo::Pocketfft.ifftn(spectrum).real)
+    # Estimates the relative cost of {.convolve_basic}.
+    # This is a heuristic for algorithm selection, not a timing measurement.
+    # @param (see convolve)
+    # @return [Float] machine-specific relative cost estimate
+    # @raise (see convolve)
+    def predict_convolve_basic_time(signal, kernel, mode: :valid, boundary: :constant,
+                                    fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).basic_time
     end
 
-    def fold_kernel(kernel, signal_shape, anchors)
-      folded = Numo::DFloat.zeros(*signal_shape)
-      kernel.flatten.each_with_index do |value, flat_index|
-        target = folded_kernel_target(flat_index, kernel.shape, signal_shape, anchors)
-        folded[*target] = folded[*target] + value
-      end
-      folded
+    # Estimates the relative cost of {.correlate_basic}.
+    # This is a heuristic for algorithm selection, not a timing measurement.
+    # @param (see convolve)
+    # @return [Float] machine-specific relative cost estimate
+    # @raise (see convolve)
+    def predict_correlate_basic_time(signal, kernel, mode: :valid, boundary: :constant,
+                                     fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).basic_time
     end
 
-    def folded_kernel_target(flat_index, kernel_shape, signal_shape, anchors)
-      remainder = flat_index
-      Array.new(kernel_shape.length).tap do |target|
-        (kernel_shape.length - 1).downto(0) do |axis|
-          coordinate = remainder % kernel_shape[axis]
-          remainder /= kernel_shape[axis]
-          target[axis] = (coordinate - anchors[axis]) % signal_shape[axis]
-        end
-      end
-    end
+    private
 
-    def fft_preparation_size(plan, signal, kernel)
-      return signal.size + kernel.size if plan.wrap?
-      return 0 if plan.valid?
+    private :convolve_basic_valid, :correlate_basic_valid
 
-      plan.extended_size
+    def execution(operation, signal, kernel, mode:, boundary:, fill_value:, origin:)
+      OperationExecution.new(operation, signal, kernel, mode:, boundary:, fill_value:, origin:)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: convolver
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Neil Slater
@@ -18,7 +18,7 @@ dependencies:
         version: 0.9.9
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -28,14 +28,14 @@ dependencies:
         version: 0.9.9
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: numo-pocketfft
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: 0.7.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.8'
@@ -45,12 +45,12 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: 0.7.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.8'
-description: Fast cross-correlation for multidimensional Numo::NArray values, with
-  configurable output and boundary modes.
+description: Fast mathematical convolution and cross-correlation for multidimensional
+  Numo::NArray values, with configurable output and boundary modes.
 email:
 - slobo777@gmail.com
 executables: []
@@ -64,11 +64,22 @@ files:
 - ext/convolver/convolve_raw.c
 - ext/convolver/convolve_raw.h
 - ext/convolver/convolver.c
+- ext/convolver/correlate_raw.c
+- ext/convolver/correlate_raw.h
 - ext/convolver/extconf.rb
 - lib/convolver.rb
+- lib/convolver/buffer_limits.rb
+- lib/convolver/buffer_preparation.rb
+- lib/convolver/circular_fft_operation.rb
+- lib/convolver/fft_buffer_plan.rb
+- lib/convolver/fft_estimator.rb
+- lib/convolver/fft_limits.rb
+- lib/convolver/linear_fft_operation.rb
+- lib/convolver/operation_execution.rb
 - lib/convolver/operation_options.rb
 - lib/convolver/operation_plan.rb
 - lib/convolver/operation_shapes.rb
+- lib/convolver/real_fft_shape.rb
 - lib/convolver/signal_extension.rb
 - lib/convolver/version.rb
 homepage: https://github.com/neilslater/convolver
@@ -93,5 +104,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Fast cross-correlation for Numo::NArray
+summary: Fast convolution and cross-correlation for Numo::NArray
 test_files: []