convolver 1.0.1 → 3.0.1

data/lib/convolver/operation_execution.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Coordinates validation, implementation selection, and one operation family.
+  # @private
+  class OperationExecution
+    DIRECT_OPERATION_COST = { 1 => 6.8e-10, 2 => 5.9e-10, 3 => 4.5e-10 }.freeze
+    EXTENSION_COST = 1.0e-9
+    FFT_SPEEDUP_MARGIN = 0.8
+
+    METHODS = {
+      correlation: {
+        basic: :correlate_basic,
+        fft: :correlate_fft,
+        predict_basic: :predict_correlate_basic_time,
+        predict_fft: :predict_correlate_fft_time
+      },
+      convolution: {
+        basic: :convolve_basic,
+        fft: :convolve_fft,
+        predict_basic: :predict_convolve_basic_time,
+        predict_fft: :predict_convolve_fft_time
+      }
+    }.freeze
+
+    def initialize(operation, signal, kernel, mode:, boundary:, fill_value:, origin:)
+      @operation = operation
+      @signal = signal
+      @kernel = kernel
+      @mode = mode
+      @boundary = boundary
+      @fill_value = fill_value
+      @origin = origin
+    end
+
+    def automatic(receiver)
+      return invoke(receiver, :basic) if plan.extended_size < 1000
+
+      direct_time = invoke(receiver, :predict_basic)
+      return invoke(receiver, :fft) if automatic_fft_time(receiver) < FFT_SPEEDUP_MARGIN * direct_time
+
+      invoke(receiver, :basic)
+    end
+
+    def basic
+      plan.validate_basic!
+      extended_signal = plan.extend_signal(signal)
+      return Convolver.send(:correlate_basic_valid, extended_signal, kernel) if operation == :correlation
+
+      Convolver.send(:convolve_basic_valid, extended_signal, kernel)
+    end
+
+    def fft
+      plan.fft_buffers
+      return Numo::SFloat.cast(signal) * Numo::SFloat.cast(kernel) if signal.ndim.zero?
+
+      fft_operation.call
+    end
+
+    def fft_time
+      FftEstimator.new(operation, signal, kernel, plan).call
+    end
+
+    def basic_time
+      plan.validate_basic!
+      calculation_cost = direct_operation_cost * plan.result_size * kernel.size
+      extension_cost = plan.valid? ? 0.0 : EXTENSION_COST * plan.extended_size
+      calculation_cost + extension_cost
+    end
+
+    private
+
+    attr_reader :operation, :signal, :kernel, :mode, :boundary, :fill_value, :origin
+
+    def plan
+      @plan ||= OperationPlan.new(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+    end
+
+    def invoke(receiver, method)
+      receiver.public_send(METHODS.fetch(operation).fetch(method), signal, kernel, **public_options)
+    end
+
+    def public_options
+      options = { mode:, boundary:, origin: }
+      options[:fill_value] = fill_value unless fill_value.equal?(UNSPECIFIED_FILL)
+      options
+    end
+
+    def fft_operation
+      return CircularFftOperation.new(operation, signal, kernel, plan) if plan.wrap?
+
+      LinearFftOperation.new(operation, plan.extend_signal(signal), kernel, plan)
+    end
+
+    def automatic_fft_time(receiver)
+      invoke(receiver, :predict_fft)
+    rescue FftUnavailable
+      Float::INFINITY
+    end
+
+    def direct_operation_cost
+      DIRECT_OPERATION_COST.fetch(signal.ndim, DIRECT_OPERATION_COST.values.last)
+    end
+  end
+
+  private_constant :OperationExecution
+end

data/lib/convolver/operation_options.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Validates and normalizes one convolution or correlation operation.
+  # @private
+  class OperationOptions
+    OPERATIONS = %i[convolution correlation].freeze
+    MODES = %i[valid same full].freeze
+    BOUNDARIES = %i[constant nearest reflect mirror wrap].freeze
+
+    attr_reader :operation, :mode, :boundary, :fill_value, :origins, :anchors
+
+    def initialize(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      validate_inputs!(signal, kernel)
+      validate_vocabulary!(operation, mode, boundary)
+      assign_options(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      validate_combinations!(signal.shape, kernel.shape)
+    end
+
+    private
+
+    def validate_inputs!(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?
+      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
+    end
+
+    def validate_vocabulary!(operation, mode, boundary)
+      raise ArgumentError, "operation must be one of #{OPERATIONS.inspect}" unless OPERATIONS.include?(operation)
+      raise ArgumentError, "mode must be one of #{MODES.inspect}" unless MODES.include?(mode)
+      return if BOUNDARIES.include?(boundary)
+
+      raise ArgumentError, "boundary must be one of #{BOUNDARIES.inspect}"
+    end
+
+    def assign_options(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      @operation = operation
+      @mode = mode
+      @boundary = boundary
+      @fill_value_given = !fill_value.equal?(UNSPECIFIED_FILL)
+      @fill_value = normalize_fill_value(fill_value)
+      @origins = normalize_origins(origin, signal.ndim)
+      @anchors = kernel.shape.zip(@origins).map.with_index do |(kernel_size, axis_origin), axis|
+        normalize_anchor(kernel_size, axis_origin, axis)
+      end.freeze
+    end
+
+    def normalize_fill_value(fill_value)
+      value = fill_value.equal?(UNSPECIFIED_FILL) ? 0.0 : fill_value
+      unless value.is_a?(Numeric) && !value.is_a?(Complex)
+        raise ArgumentError, 'fill_value must be a real numeric value'
+      end
+
+      value.to_f
+    end
+
+    def normalize_origins(origin, rank)
+      origins = case origin
+                when Integer then Array.new(rank, origin)
+                when Array then origin.dup
+                else
+                  raise ArgumentError, 'origin must be an Integer or an Array of one Integer per dimension'
+                end
+
+      unless origins.length == rank && origins.all?(Integer)
+        raise ArgumentError, 'origin must contain one Integer per dimension'
+      end
+
+      origins.freeze
+    end
+
+    def normalize_anchor(kernel_size, origin, axis)
+      anchor = (kernel_size / 2) + origin
+      return anchor if anchor.between?(0, kernel_size - 1)
+
+      raise ArgumentError,
+            "origin #{origin} is out of range for kernel dimension #{axis} of size #{kernel_size}"
+    end
+
+    def validate_combinations!(signal_shape, kernel_shape)
+      validate_mode_combination!(signal_shape, kernel_shape)
+      validate_fill_combination!
+      validate_origin_combination!
+    end
+
+    def validate_mode_combination!(signal_shape, kernel_shape)
+      return validate_valid_options!(signal_shape, kernel_shape) if mode == :valid
+      return unless mode == :full && boundary != :constant
+
+      raise ArgumentError, 'mode: :full only supports boundary: :constant'
+    end
+
+    def validate_fill_combination!
+      return unless boundary != :constant && @fill_value_given
+
+      raise ArgumentError, 'fill_value is only supported with boundary: :constant'
+    end
+
+    def validate_origin_combination!
+      return if mode == :same || origins.all?(&:zero?)
+
+      raise ArgumentError, 'nonzero origin is only supported with mode: :same'
+    end
+
+    def validate_valid_options!(signal_shape, kernel_shape)
+      unless signal_shape.zip(kernel_shape).all? { |signal_size, kernel_size| signal_size >= kernel_size }
+        raise ArgumentError, 'kernel must not be larger than signal in any dimension'
+      end
+      raise ArgumentError, 'mode: :valid only supports boundary: :constant' unless boundary == :constant
+      raise ArgumentError, 'mode: :valid requires fill_value: 0' unless fill_value.zero?
+    end
+  end
+
+  private_constant :OperationOptions
+end

data/lib/convolver/operation_plan.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'convolver/operation_options'
+require 'convolver/operation_shapes'
+require 'convolver/signal_extension'
+require 'convolver/fft_buffer_plan'
+
+# Internal planning and extension support for Convolver's public operations.
+module Convolver
+  # Distinguishes an omitted fill_value keyword from an explicitly supplied
+  # value. This lets non-constant boundaries reject even an explicit zero.
+  # @private
+  UNSPECIFIED_FILL = Object.new.freeze
+
+  # Validated dimensions and boundary-extension details for one operation.
+  # @private
+  class OperationPlan
+    extend Forwardable
+
+    def_delegators :options, :operation, :mode, :boundary, :fill_value, :origins, :anchors
+    def_delegators :shapes, :padding_before, :padding_after, :result_shape,
+                   :extended_shape, :result_size, :extended_size, :linear_fft_shape,
+                   :linear_fft_size, :linear_spectrum_size
+
+    def initialize(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      @options = OperationOptions.new(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      @signal_shape = signal.shape.freeze
+      @kernel_shape = kernel.shape.freeze
+      @shapes = OperationShapes.new(
+        signal.shape, kernel.shape, operation:, mode:, anchors: options.anchors
+      )
+    end
+
+    def valid?
+      mode == :valid
+    end
+
+    def wrap?
+      mode == :same && boundary == :wrap
+    end
+
+    def extend_signal(signal)
+      return signal if valid?
+
+      SignalExtension.new(shapes, boundary:, fill_value:).call(signal)
+    end
+
+    def validate_basic!
+      BufferPreparation.new(self, @signal_shape, @kernel_shape).basic!
+    end
+
+    def fft_buffers
+      @fft_buffers ||= FftBufferPlan.new(self, @signal_shape, @kernel_shape)
+    end
+
+    private
+
+    attr_reader :options, :shapes
+  end
+
+  private_constant :OperationPlan, :UNSPECIFIED_FILL
+end

data/lib/convolver/operation_shapes.rb

@@ -0,0 +1,129 @@
+# 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, operation:, mode:, anchors:)
+      @operation = operation
+      @mode = mode
+      calculate_shapes(signal_shape, kernel_shape, anchors)
+      validate_sizes!
+    end
+
+    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 :operation, :mode
+
+    def calculate_shapes(signal_shape, kernel_shape, anchors)
+      @padding_before, @padding_after, @result_shape = shapes_for(signal_shape, kernel_shape, anchors)
+      @extended_shape = signal_shape.zip(padding_before, padding_after).map do |signal_size, before, after|
+        signal_size + before + after
+      end
+    end
+
+    def shapes_for(signal_shape, kernel_shape, anchors)
+      case mode
+      when :valid then valid_shapes(signal_shape, kernel_shape)
+      when :same then same_shapes(signal_shape, kernel_shape, anchors)
+      when :full then full_shapes(signal_shape, kernel_shape)
+      end
+    end
+
+    def valid_shapes(signal_shape, kernel_shape)
+      result = signal_shape.zip(kernel_shape).map do |signal_size, kernel_size|
+        signal_size - kernel_size + 1
+      end
+      zeros = Array.new(signal_shape.length, 0).freeze
+      [zeros, zeros, result]
+    end
+
+    def same_shapes(signal_shape, kernel_shape, anchors)
+      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
+
+    def full_shapes(signal_shape, kernel_shape)
+      padding = kernel_shape.map { |kernel_size| kernel_size - 1 }.freeze
+      result = signal_shape.zip(kernel_shape).map { |signal_size, kernel_size| signal_size + kernel_size - 1 }
+      [padding, padding, result]
+    end
+
+    def validate_sizes!
+      @padding_before, @padding_after, @result_shape, @extended_shape = [
+        [padding_before, 'padding shape'],
+        [padding_after, 'padding shape'],
+        [result_shape, 'result shape'],
+        [extended_shape, 'extended signal shape']
+      ].map { |shape, description| checked_shape(shape, description).freeze }
+      @result_size = checked_product(result_shape, 'result size')
+      @extended_size = checked_product(extended_shape, 'extended signal size')
+    end
+
+    def checked_shape(shape, description)
+      return shape if shape.all? { |size| size.between?(0, SIZE_MAX) }
+
+      raise RangeError, "#{description} exceeds native implementation limit"
+    end
+
+    def checked_product(shape, description)
+      shape.reduce(1) do |product, size|
+        if !product.zero? && size > SIZE_MAX / product
+          raise RangeError, "#{description} exceeds native implementation limit"
+        end
+
+        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
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Extends a signal according to one operation's boundary policy.
+  # @private
+  class SignalExtension
+    def initialize(shapes, boundary:, fill_value:)
+      @shapes = shapes
+      @boundary = boundary
+      @fill_value = fill_value
+    end
+
+    def call(signal)
+      source = Numo::SFloat.cast(signal)
+      return constant_extension(source) if boundary == :constant
+
+      source[*extension_indices]
+    end
+
+    private
+
+    attr_reader :shapes, :boundary, :fill_value
+
+    def constant_extension(source)
+      extended = Numo::SFloat.new(*shapes.extended_shape).fill(fill_value)
+      ranges = source.shape.zip(shapes.padding_before).map do |signal_size, before|
+        before...(before + signal_size)
+      end
+      extended[*ranges] = source
+      extended
+    end
+
+    def extension_indices
+      shapes.extended_shape.zip(shapes.padding_before).map.with_index do |(length, before), axis|
+        Array.new(length) { |offset| boundary_index(offset - before, signal_size(axis, before)) }
+      end
+    end
+
+    def signal_size(axis, before)
+      shapes.extended_shape[axis] - before - shapes.padding_after[axis]
+    end
+
+    def boundary_index(position, size)
+      case boundary
+      when :nearest then position.clamp(0, size - 1)
+      when :wrap then position % size
+      when :reflect then reflect_index(position, size)
+      when :mirror then mirror_index(position, size)
+      end
+    end
+
+    def reflect_index(position, size)
+      residue = position % (2 * size)
+      residue < size ? residue : (2 * size) - 1 - residue
+    end
+
+    def mirror_index(position, size)
+      return 0 if size == 1
+
+      period = 2 * (size - 1)
+      residue = position % period
+      residue < size ? residue : period - residue
+    end
+  end
+
+  private_constant :SignalExtension
+end

data/lib/convolver/version.rb

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