convolver 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e886e4cc4f0c47a5c0e40209a20ac4b90f9c5fa349c76e9b04889fb8c010fa70
-  data.tar.gz: b656b786753b87ab68d89985262bedbbd3ad0929527a2953acde7af56cde643b
+  metadata.gz: '08959da24c94d02889f0067f18f7233578b4b14ec4e58538b144efeef1cbe25f'
+  data.tar.gz: c39df2ebf01a04f93fa62e49bd8a4542e78244868d822d7f47a00cc78b9aaa7e
 SHA512:
-  metadata.gz: 187f65c4daf5c25007348d0e3f21e44dda4bccb629f0dab067ac8193aac8977d22a441b79249d35ad4b7c2b17e43e3339db7045c0f83882009556bae6b446425
-  data.tar.gz: 4605ecab87c0027c02c30c82e78298766b311a4e359b178fec8b47427a5c6bfc57a049193173fb38fba3877874e679cf1d96ac41700a5cf090a31c5fa43c9635
+  metadata.gz: 73d425b7851b21dd93cb135ca7ad88aa75f760b41a53ed8a2b72b2a9110e183062c1643af9563f81d59248d50d3f49a531e2bbac6d0c5cdcef6383717e31f73a
+  data.tar.gz: 89ddc9f26950329b9ce2ce3917e5f90057c3c625f2210eb39fcc527cbe7b3f418f14f387665a3be3c1ea44d50beac101907c038c6ef9998998e30c21d61966d2

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [2.0.0] - 2026-08-20
+
+### Added
+
+- Added `:valid`, `:same`, and `:full` output modes to every calculation and
+  estimator method.
+- Added constant, nearest, reflect, mirror, and wrap signal boundary extensions,
+  including nonzero constant fill and kernels larger than the signal where the
+  output mode permits them.
+- Added scalar and per-axis kernel origins with an explicit even-kernel
+  alignment convention.
+- Added an origin-aware circular PocketFFT correlation path for periodic
+  same-sized output.
+
+### Changed
+
+- **Breaking:** Raised the minimum supported Ruby version to 3.3.
+- Adopted `ncs_rubocop_conf` 0.1.0 as the versioned RuboCop policy, added
+  exception auditing, and began tracking the development dependency lockfile.
+- Made algorithm selection and both public time estimators account for output
+  shape, boundary extension, kernel folding, and FFT working shape.
+- Moved the native valid-only calculation behind a shared Ruby orchestration
+  layer so direct and FFT implementations use identical option validation and
+  boundary semantics.
+
 ## [1.0.1] - 2026-07-29
 
 ### Fixed
@@ -54,5 +81,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated the native extension to use the maintained Numo C API and removed the
   legacy untyped-data compatibility code.
 
+[Unreleased]: https://github.com/neilslater/convolver/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/neilslater/convolver/compare/v1.0.1...v2.0.0
 [1.0.1]: https://github.com/neilslater/convolver/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/neilslater/convolver/compare/v0.3.2...v1.0.0

data/README.md

@@ -1,10 +1,12 @@
 # Convolver
 
+[![CI](https://github.com/neilslater/convolver/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/neilslater/convolver/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/convolver.svg)](https://badge.fury.io/rb/convolver)
 
-Convolver calculates valid cross-correlations between multidimensional
-[`Numo::NArray`](https://github.com/yoshoku/numo-narray-alt) values. It chooses
-between a direct native implementation for smaller inputs and a
+Convolver calculates cross-correlations between multidimensional
+[`Numo::NArray`](https://github.com/yoshoku/numo-narray-alt) values, with
+configurable output extents and signal boundary extensions. It chooses between
+a direct native implementation for smaller inputs and a
 [`Numo::Pocketfft`](https://github.com/yoshoku/numo-pocketfft)-based
 implementation for larger inputs.
 
@@ -46,9 +48,10 @@ Convolver.convolve(signal, kernel)
 #    [0.19, 0.27]
 ```
 
-The signal and kernel must have the same rank, and the kernel must be no larger
-than the signal in any dimension. Convolver returns only positions at which the
-kernel overlaps the signal completely. The result size in each dimension is:
+With no keywords, Convolver preserves its original valid-correlation behavior:
+the signal and kernel must have the same rank, the kernel must be no larger
+than the signal in any dimension, and only positions with complete overlap are
+returned. The result size in each dimension is:
 
 ```ruby
 signal_size - kernel_size + 1
@@ -67,8 +70,74 @@ Convolver.convolve_basic(signal, kernel)
 Convolver.convolve_fft(signal, kernel)
 ```
 
+Both implementations and the automatic method accept the same options:
+
+```ruby
+Convolver.convolve(signal, kernel,
+                   mode: :same,
+                   boundary: :reflect,
+                   origin: 0)
+```
+
+### Output modes
+
+`mode:` controls the returned extent independently in each dimension:
+
+| Mode | Meaning | Result size |
+| --- | --- | --- |
+| `:valid` | Kernel overlaps the stored signal completely | `S - K + 1` |
+| `:same` | One result aligned with each stored signal position | `S` |
+| `:full` | Every kernel position with any stored-signal overlap | `S + K - 1` |
+
+`:valid` is the default and accepts only the default `boundary: :constant`,
+`fill_value: 0.0`, and `origin: 0`. `:full` supports constant extension only.
+`:same` supports every boundary described below. Kernels larger than the signal
+are supported by `:same` and `:full`, but not by `:valid`. `mode:` and
+`boundary:` accept only the symbols listed here.
+
+### Boundary extension
+
+For a one-dimensional signal `a b c d`, `boundary:` selects values outside the
+stored signal:
+
+| Boundary | Extended sequence |
+| --- | --- |
+| `:constant` | `k k k k | a b c d | k k k k` |
+| `:nearest` | `a a a a | a b c d | d d d d` |
+| `:reflect` | `d c b a | a b c d | d c b a` |
+| `:mirror` | `d c b | a b c d | c b a` |
+| `:wrap` | `a b c d | a b c d | a b c d` |
+
+`fill_value:` sets `k` for `:constant` and defaults to zero. It must not be
+passed with another boundary. `:reflect` repeats the edge sample; `:mirror`
+does not. All boundary modes work across every dimension, including
+length-one axes and extensions wider than the stored signal.
+
+### Kernel origin
+
+`origin:` shifts the kernel anchor for `:same`. It accepts one integer applied
+to every dimension or an array with one integer per dimension. For a kernel
+dimension of length `K`:
+
+```ruby
+anchor = (K / 2) + origin
+```
+
+The anchor must remain within the kernel. Positive origins sample farther
+toward lower signal indices. With the default origin, an even kernel gives the
+extra boundary sample to the lower-index, or left, side: a length-four kernel
+uses two samples before and one after the aligned signal position. Nonzero
+origins are supported only for `:same`; `:valid` and `:full` require zero.
+
+The estimator methods accept and validate the same options:
+
+```ruby
+Convolver.predict_convolve_basic_time(signal, kernel, mode: :same, boundary: :nearest)
+Convolver.predict_convolve_fft_time(signal, kernel, mode: :same, boundary: :wrap)
+```
+
 `Convolver.convolve_fftw3` remains as a deprecated alias for `convolve_fft` to
-ease migration from Convolver 0.x.
+ease migration from Convolver 0.x and forwards all options.
 
 ## Contributing
 

data/ext/convolver/convolver.c

@@ -17,12 +17,12 @@ static void copy_shape(int rank, const size_t *source, size_t *target) {
 /*
  * Calculates a valid cross-correlation using the direct native implementation.
  *
- * @overload convolve_basic(signal, kernel)
+ * @overload convolve_basic_valid(signal, kernel)
  *   @param signal [Numo::NArray] input values
  *   @param kernel [Numo::NArray] correlation kernel
  *   @return [Numo::SFloat] valid cross-correlation result
  */
-static VALUE convolver_convolve_basic(VALUE self, VALUE signal, VALUE kernel) {
+static VALUE convolver_convolve_basic_valid(VALUE self, VALUE signal, VALUE kernel) {
   volatile VALUE signal_value;
   volatile VALUE kernel_value;
   volatile VALUE result_value;
@@ -87,5 +87,5 @@ static VALUE convolver_convolve_basic(VALUE self, VALUE signal, VALUE kernel) {
 
 void Init_convolver(void) {
   mConvolver = rb_define_module("Convolver");
-  rb_define_singleton_method(mConvolver, "convolve_basic", convolver_convolve_basic, 2);
+  rb_define_singleton_method(mConvolver, "convolve_basic_valid", convolver_convolve_basic_valid, 2);
 }

data/lib/convolver/operation_options.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Validates and normalizes the options for a correlation operation.
+  class OperationOptions
+    MODES = %i[valid same full].freeze
+    BOUNDARIES = %i[constant nearest reflect mirror wrap].freeze
+
+    attr_reader :mode, :boundary, :fill_value, :origins, :anchors
+
+    def initialize(signal, kernel, mode:, boundary:, fill_value:, origin:)
+      validate_inputs!(signal, kernel)
+      validate_vocabulary!(mode, boundary)
+      assign_options(signal, kernel, 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!(mode, boundary)
+      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, mode:, boundary:, fill_value:, origin:)
+      @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,48 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'convolver/operation_options'
+require 'convolver/operation_shapes'
+require 'convolver/signal_extension'
+
+# 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.
+  UNSPECIFIED_FILL = Object.new.freeze
+
+  # Validated dimensions and boundary-extension details for one correlation.
+  class OperationPlan
+    extend Forwardable
+
+    def_delegators :options, :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
+
+    def initialize(signal, kernel, mode:, boundary:, fill_value:, origin:)
+      @options = OperationOptions.new(signal, kernel, mode:, boundary:, fill_value:, origin:)
+      @shapes = OperationShapes.new(signal.shape, kernel.shape, 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
+
+    private
+
+    attr_reader :options, :shapes
+  end
+
+  private_constant :OperationPlan, :UNSPECIFIED_FILL
+end

data/lib/convolver/operation_shapes.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Calculates and validates output, extension, and FFT dimensions.
+  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:)
+      @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'
+      )
+    end
+
+    def linear_fft_size(kernel_shape)
+      checked_product(linear_fft_shape(kernel_shape), 'FFT size')
+    end
+
+    private
+
+    attr_reader :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)
+      before = anchors.dup.freeze
+      after = kernel_shape.zip(anchors).map { |kernel_size, anchor| kernel_size - 1 - anchor }.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
+  end
+
+  private_constant :OperationShapes
+end

data/lib/convolver/signal_extension.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Extends a signal according to one operation's boundary policy.
+  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 = '2.0.0'
 end

data/lib/convolver.rb

@@ -5,105 +5,153 @@ require 'numo/pocketfft'
 require 'convolver/convolver'
 require 'convolver/version'
 
-# Valid cross-correlation operations for Numo::NArray values.
+# Cross-correlation operations 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'
+
   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:
-    #
-    #   signal.shape.zip(kernel.shape).map { |signal_size, kernel_size| signal_size - kernel_size + 1 }
+    # Chooses the likely fastest cross-correlation implementation.
     #
     # @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
-
-      basic_time_predicted = predict_convolve_basic_time(signal, kernel)
-      return convolve_basic(signal, kernel) if basic_time_predicted < 0.1
-
-      fft_time_predicted = predict_convolve_fft_time(signal, kernel)
-      return convolve_fft(signal, kernel) if fft_time_predicted < 2 * basic_time_predicted
+    # @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
+    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)
+    end
 
-      convolve_basic(signal, kernel)
+    # Uses the direct native valid primitive after applying the requested signal
+    # extension in Ruby.
+    #
+    # @return [Numo::SFloat] cross-correlation result
+    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)
     end
 
-    # Uses PocketFFT to calculate a valid cross-correlation.
+    # Uses PocketFFT to calculate the requested 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)
+    # Periodic same-sized results use a circular transform. Other combinations
+    # use the shared extension plan and PocketFFT's linear convolution.
+    #
+    # @return [Numo::SFloat] cross-correlation result
+    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?
 
-      Numo::SFloat.cast(full_convolution[*ranges])
+      convolve_fft_valid(plan.extend_signal(signal), kernel)
     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)
+    # @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
-      convolve_fft(signal, kernel)
+      options = operation_options(mode, boundary, fill_value, origin)
+      convolve_fft(signal, kernel, **options)
     end
 
-    # Estimates the relative cost of {.convolve_fft}.
+    # Estimates the relative cost of {.convolve_fft} for the requested options.
     #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
     # @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)
+    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))
     end
 
-    # Estimates the relative cost of {.convolve_basic}.
+    # Estimates the relative cost of {.convolve_basic} for the requested options.
     #
-    # @param signal [Numo::NArray] input values
-    # @param kernel [Numo::NArray] correlation kernel
     # @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)
+    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
 
-    def result_shape(signal_shape, kernel_shape)
-      signal_shape.zip(kernel_shape).map { |signal_size, kernel_size| signal_size - kernel_size + 1 }
+    private :convolve_basic_valid
+
+    def operation_plan(signal, kernel, mode:, boundary:, fill_value:, origin:)
+      OperationPlan.new(signal, kernel, mode:, boundary:, fill_value:, origin:)
+    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 validate_inputs!(signal, kernel)
-      validate_types!(signal, kernel)
-      validate_shapes!(signal, kernel)
+    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)
+    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
     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'
+    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
-      raise ArgumentError, 'signal and kernel must not be empty' if signal.empty? || kernel.empty?
     end
 
-    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 }
+    def fft_preparation_size(plan, signal, kernel)
+      return signal.size + kernel.size if plan.wrap?
+      return 0 if plan.valid?
 
-      raise ArgumentError, 'kernel must not be larger than signal in any dimension'
+      plan.extended_size
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: convolver
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Neil Slater
@@ -49,8 +49,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.8'
-description: Fast valid cross-correlation for multidimensional Numo::NArray values,
-  with native and FFT implementations.
+description: Fast cross-correlation for multidimensional Numo::NArray values, with
+  configurable output and boundary modes.
 email:
 - slobo777@gmail.com
 executables: []
@@ -66,6 +66,10 @@ files:
 - ext/convolver/convolver.c
 - ext/convolver/extconf.rb
 - lib/convolver.rb
+- lib/convolver/operation_options.rb
+- lib/convolver/operation_plan.rb
+- lib/convolver/operation_shapes.rb
+- lib/convolver/signal_extension.rb
 - lib/convolver/version.rb
 homepage: https://github.com/neilslater/convolver
 licenses:
@@ -80,7 +84,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:
   - - ">="