convolver 1.0.1 → 3.0.1

data/lib/convolver.rb

@@ -5,105 +5,136 @@ require 'numo/pocketfft'
 require 'convolver/convolver'
 require 'convolver/version'
 
-# Valid 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 direct native implementation.
+  # 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 implementation for a valid cross-correlation.
-    #
-    # The inputs must have the same rank, and the kernel must not be larger than
-    # the signal in any dimension. The result shape is:
+    # Chooses the likely fastest mathematical convolution implementation.
     #
-    #   signal.shape.zip(kernel.shape).map { |signal_size, kernel_size| signal_size - kernel_size + 1 }
+    # 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 values
-    # @param kernel [Numo::NArray] correlation kernel
-    # @return [Numo::SFloat] valid cross-correlation result
-    # @raise [ArgumentError] if the inputs have incompatible ranks or shapes
-    def convolve(signal, kernel)
-      validate_inputs!(signal, kernel)
-      return convolve_basic(signal, kernel) if signal.size < 1000 || kernel.size < 100
+    # @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)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).automatic(self)
+    end
 
-      basic_time_predicted = predict_convolve_basic_time(signal, kernel)
-      return convolve_basic(signal, kernel) if basic_time_predicted < 0.1
+    # 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
 
-      fft_time_predicted = predict_convolve_fft_time(signal, kernel)
-      return convolve_fft(signal, kernel) if fft_time_predicted < 2 * basic_time_predicted
+    # 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)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).basic
+    end
 
-      convolve_basic(signal, kernel)
+    # 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 a valid cross-correlation.
-    #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
-    # @return [Numo::SFloat] valid cross-correlation result
-    # @raise [ArgumentError] if the inputs have incompatible ranks or shapes
-    def convolve_fft(signal, kernel)
-      validate_inputs!(signal, kernel)
-      ranges = kernel.shape.zip(signal.shape).map { |kernel_size, signal_size| (kernel_size - 1)...signal_size }
-      full_convolution = Numo::Pocketfft.fftconvolve(signal, kernel.reverse)
-
-      Numo::SFloat.cast(full_convolution[*ranges])
+    # 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)
+      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.
-    # @return [Numo::SFloat] valid cross-correlation result
-    def convolve_fftw3(signal, kernel)
-      warn 'Convolver.convolve_fftw3 is deprecated; use .convolve_fft instead', uplevel: 1
-      convolve_fft(signal, kernel)
+    # Uses PocketFFT to calculate cross-correlation.
+    # @param (see convolve)
+    # @return [Numo::SFloat] cross-correlation result
+    # @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}.
-    #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
+    # This is a heuristic for algorithm selection, not a timing measurement.
+    # @param (see convolve)
     # @return [Float] machine-specific relative cost estimate
-    def predict_convolve_fft_time(signal, kernel)
-      validate_inputs!(signal, kernel)
-      output_size = result_shape(signal.shape, kernel.shape).inject(:*)
-      16 * 4.55e-08 * output_size * Math.log(output_size)
+    # @raise (see convolve)
+    def predict_convolve_fft_time(signal, kernel, mode: :valid, boundary: :constant,
+                                  fill_value: UNSPECIFIED_FILL, origin: 0)
+      execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).fft_time
     end
 
-    # Estimates the relative cost of {.convolve_basic}.
-    #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
+    # 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)
-      validate_inputs!(signal, kernel)
-      outputs = result_shape(signal.shape, kernel.shape).inject(:*)
-      4.54e-12 * (outputs * signal.size * kernel.size)
+    # @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
 
-    private
-
-    def result_shape(signal_shape, kernel_shape)
-      signal_shape.zip(kernel_shape).map { |signal_size, kernel_size| signal_size - kernel_size + 1 }
+    # 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 validate_inputs!(signal, kernel)
-      validate_types!(signal, kernel)
-      validate_shapes!(signal, kernel)
+    # 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 validate_types!(signal, kernel)
-      unless signal.is_a?(Numo::NArray) && kernel.is_a?(Numo::NArray)
-        raise ArgumentError, 'signal and kernel must be Numo::NArray values'
-      end
-      raise ArgumentError, 'signal and kernel must not be empty' if signal.empty? || kernel.empty?
-    end
+    private
 
-    def validate_shapes!(signal, kernel)
-      raise ArgumentError, 'signal and kernel must have equal rank' unless signal.ndim == kernel.ndim
-      raise ArgumentError, "maximum supported rank is #{MAX_RANK}" if signal.ndim > MAX_RANK
-      return if signal.shape.zip(kernel.shape).all? { |signal_size, kernel_size| signal_size >= kernel_size }
+    private :convolve_basic_valid, :correlate_basic_valid
 
-      raise ArgumentError, 'kernel must not be larger than signal in any dimension'
+    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: 1.0.1
+  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 valid cross-correlation for multidimensional Numo::NArray values,
-  with native and FFT implementations.
+description: Fast mathematical convolution and cross-correlation for multidimensional
+  Numo::NArray values, with configurable output and boundary modes.
 email:
 - slobo777@gmail.com
 executables: []
@@ -64,8 +64,23 @@ 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
 licenses:
@@ -80,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -89,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: []