convolver 1.0.1 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e886e4cc4f0c47a5c0e40209a20ac4b90f9c5fa349c76e9b04889fb8c010fa70
-  data.tar.gz: b656b786753b87ab68d89985262bedbbd3ad0929527a2953acde7af56cde643b
+  metadata.gz: e56b4c0d87d92abb3f8c79d3d11b8d41c8dcbb6d7055dce615eef07a363b0cc2
+  data.tar.gz: 23c852764b162f082fa380e6932a8c5ad0c400c6d766579d7a087d32cd875825
 SHA512:
-  metadata.gz: 187f65c4daf5c25007348d0e3f21e44dda4bccb629f0dab067ac8193aac8977d22a441b79249d35ad4b7c2b17e43e3339db7045c0f83882009556bae6b446425
-  data.tar.gz: 4605ecab87c0027c02c30c82e78298766b311a4e359b178fec8b47427a5c6bfc57a049193173fb38fba3877874e679cf1d96ac41700a5cf090a31c5fa43c9635
+  metadata.gz: 7eda50980613f1d03659465daa5b3ece647485ab38355664808497f966f232893de2133649c0e8cd9262606fde99ad3305552db27a5e719901aee6c095b2ac3d
+  data.tar.gz: da94b103db3c1af9f735787584a757ed9683a12556879495f041a88a6f7eb178ef214d871f64e8a18aa498b090c9cec748c4c7d11c534a687099e9d2a3c15ff2

data/CHANGELOG.md

@@ -5,6 +5,85 @@ 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]
+
+## [3.0.1] - 2026-10-04
+
+### Changed
+
+- Require `numo-pocketfft >= 0.7.0` and allow `numo-narray-alt < 0.12`,
+  enabling the NArray 0.11 series.
+
+### Fixed
+
+- Read the logical values of contiguous signal and kernel slices in direct
+  convolution and correlation, including unaligned SSE kernels and scalar views.
+- Retain a representable exact FFT shape when an optional fast candidate exceeds
+  the native element limit.
+- Reject unrepresentable FFT buffers and native integer arithmetic before
+  allocation, including preparation, inverse staging and work buffers. Automatic
+  selection retains a safe direct path when FFT exceeds its limits.
+
+## [3.0.0] - 2026-08-22
+
+### Added
+
+- Added the `correlate`, `correlate_basic`, and `correlate_fft` calculation
+  methods for cross-correlation, preserving the numerical operation exposed by
+  the version 2 `convolve*` methods.
+- Added `predict_correlate_basic_time` and `predict_correlate_fft_time` as the
+  corresponding estimator family.
+- Added distinct native correlation and convolution primitives whose hot loops
+  perform the required traversal directly without materializing a reversed
+  kernel.
+
+### Changed
+
+- **Breaking:** Changed `convolve`, `convolve_basic`, and `convolve_fft` to
+  calculate mathematical discrete convolution. Version 2 users who need
+  unchanged results must rename these calls to their `correlate*` counterparts.
+- **Breaking:** Changed the `predict_convolve_*_time` methods to estimate the
+  new mathematical convolution implementations.
+- Defined operation-specific `:same` alignment. Correlation uses
+  `signal[i + j - anchor]`; convolution uses
+  `signal[i + anchor - j]`. This places the extra boundary sample for an even
+  kernel on opposite sides.
+- Reworked linear PocketFFT calculations around real transforms and checked
+  exact/even or 2/3/5-smooth transform shapes. Circular calculations use real
+  transforms when an axis is even and retain complex transforms for all-odd
+  shapes.
+
+### Removed
+
+- **Breaking:** Removed the deprecated `convolve_fftw3` compatibility method.
+  Use `correlate_fft` to preserve version 2 results or `convolve_fft` for
+  mathematical convolution.
+
+## [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 +133,8 @@ 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/v3.0.0...HEAD
+[3.0.0]: https://github.com/neilslater/convolver/compare/v2.0.0...v3.0.0
+[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,16 +1,16 @@
 # 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
-[`Numo::Pocketfft`](https://github.com/yoshoku/numo-pocketfft)-based
+Convolver calculates mathematical convolution and cross-correlation between
+multidimensional
+[`Numo::NArray`](https://github.com/yoshoku/numo-narray-alt) values. Both
+operations support configurable output extents and signal boundary extensions.
+Convolver chooses between a direct native implementation for smaller inputs
+and a [`Numo::Pocketfft`](https://github.com/yoshoku/numo-pocketfft)-based
 implementation for larger inputs.
 
-Version 1.0 replaces the unmaintained `narray` and `fftw3` gems with
-`numo-narray-alt` and `numo-pocketfft`.
-
 ## Installation
 
 Add Convolver to your application's Gemfile:
@@ -19,22 +19,16 @@ Add Convolver to your application's Gemfile:
 gem 'convolver'
 ```
 
-Then run:
-
-```sh
-bundle install
-```
-
-Alternatively, install it directly:
-
-```sh
-gem install convolver
-```
-
-No external FFT library is required; PocketFFT is bundled by its Ruby gem.
+Then run `bundle install`, or install the gem directly with
+`gem install convolver`. No external FFT library is required; PocketFFT is
+bundled by its Ruby gem.
 
 ## Usage
 
+`convolve` calculates mathematical discrete convolution. `correlate`
+calculates cross-correlation, following the public naming convention used by
+NumPy and SciPy:
+
 ```ruby
 require 'convolver'
 
@@ -43,46 +37,169 @@ kernel = Numo::SFloat[1.3, -0.5]
 
 Convolver.convolve(signal, kernel)
 # => Numo::SFloat#shape=[2]
+#    [0.37, 0.45]
+
+Convolver.correlate(signal, kernel)
+# => Numo::SFloat#shape=[2]
 #    [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:
+For real one-dimensional inputs, the two valid operations are:
 
-```ruby
-signal_size - kernel_size + 1
+```text
+correlate(signal, kernel)[p] = sum_j signal[p + j] * conjugate(kernel[j])
+convolve(signal, kernel)[n]  = sum_j signal[n - j] * kernel[j]
 ```
 
-Inputs are converted to single-precision floats internally, and results are
-returned as `Numo::SFloat`. Supplying `Numo::SFloat` inputs avoids conversion in
-the direct implementation.
+The formulas apply component-wise to multidimensional arrays. Correlation
+conventionally conjugates the second operand, although Convolver's current
+single-precision real input contract makes conjugation invisible.
+
+With no keywords, 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. Inputs are converted to single-precision floats
+internally and results are returned as `Numo::SFloat`. Supplying
+`Numo::SFloat` inputs avoids conversion in the direct implementation.
 
-`Convolver.convolve` normally chooses the implementation automatically. The
-implementations can also be called directly for application-specific
-benchmarking:
+The automatic, direct, and FFT implementations are available for both
+operations:
 
 ```ruby
+Convolver.convolve(signal, kernel)
 Convolver.convolve_basic(signal, kernel)
 Convolver.convolve_fft(signal, kernel)
+
+Convolver.correlate(signal, kernel)
+Convolver.correlate_basic(signal, kernel)
+Convolver.correlate_fft(signal, kernel)
+```
+
+Every calculation method accepts the same options:
+
+```ruby
+Convolver.convolve(signal, kernel,
+                   mode: :same,
+                   boundary: :reflect,
+                   origin: 0)
 ```
 
-`Convolver.convolve_fftw3` remains as a deprecated alias for `convolve_fft` to
-ease migration from Convolver 0.x.
+### 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 and alignment
+
+`origin:` shifts the stored-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`:
+
+```text
+anchor = floor(K / 2) + origin
+
+correlation[i] = sum_j extended_signal[i + j - anchor] * kernel[j]
+convolution[i] = sum_j extended_signal[i + anchor - j] * kernel[j]
+```
+
+The anchor must remain within the kernel. Correlation pads `anchor` samples
+before the signal and `K - 1 - anchor` after it; convolution swaps those
+widths. Odd centered kernels therefore align alike. For an even centered
+kernel, correlation puts the extra sample before the signal and convolution
+puts it after the signal. Positive origins move correlation toward lower signal
+indices and convolution toward higher signal indices.
+
+Nonzero origins are supported only for `:same`; `:valid` and `:full` require
+zero.
+
+### Estimators
+
+The estimator methods accept and validate the same options as their calculation
+families:
+
+```ruby
+Convolver.predict_convolve_basic_time(signal, kernel, mode: :same, boundary: :nearest)
+Convolver.predict_convolve_fft_time(signal, kernel, mode: :same, boundary: :wrap)
+
+Convolver.predict_correlate_basic_time(signal, kernel, mode: :same, boundary: :nearest)
+Convolver.predict_correlate_fft_time(signal, kernel, mode: :same, boundary: :wrap)
+```
+
+Calculations and estimators reject unrepresentable buffer sizes with `RangeError`
+before allocation. FFT planning also checks conservative PocketFFT integer and
+work-buffer limits, including full complex staging for real inverse transforms.
+Automatic selection uses direct calculation when FFT exceeds its limits and the
+direct path remains valid. These checks do not reserve memory; ordinary allocator
+exhaustion still raises `NoMemoryError`.
+
+### Migrating from version 2
+
+Version 2's `convolve*` methods calculated cross-correlation. Version 3 corrects
+the terminology and changes every `convolve*` method to mathematical
+convolution. Asymmetric kernels make the result change visible.
+
+To preserve version 2 results, rename the complete method family:
+
+| Version 2 | Version 3 equivalent |
+| --- | --- |
+| `convolve` | `correlate` |
+| `convolve_basic` | `correlate_basic` |
+| `convolve_fft` | `correlate_fft` |
+| `predict_convolve_basic_time` | `predict_correlate_basic_time` |
+| `predict_convolve_fft_time` | `predict_correlate_fft_time` |
+| `convolve_fftw3` | `correlate_fft` |
+
+`convolve_fftw3` has been removed. No `cross_correlate` aliases are provided;
+the standard `correlate` name denotes cross-correlation explicitly documented
+above.
 
 ## Contributing
 
-Install the development dependencies, then run the main suite:
+Install the development dependencies, then run the complete local gate:
 
 ```sh
 bundle install
 bundle exec rake
 bundle exec rubocop
+bundle exec ncs-rubocop-conf-audit
 bundle exec rake c:lint
+bundle exec bundle-audit check --update
+bundle exec rake docs:check
 ```
 
-The Ruby specs exercise both the Ruby API and native extension. Additional
-native-code checks are available:
+The Ruby specs exercise both the Ruby API and native extension and enforce 95%
+line and branch coverage for the Ruby library. Dependency auditing refreshes
+the advisory database and requires network access. The documentation check
+rejects YARD warnings and undocumented public API objects; private implementation
+classes are marked `@private`. Additional native-code checks are available:
 
 ```sh
 bundle exec rake c:coverage  # Requires GCC and gcovr

data/ext/convolver/convolve_raw.c

@@ -72,8 +72,6 @@ static inline size_t maximum_offset(
 //
 //  Convolve
 //
-//    Benchmark: 640x480 image, 8x8 kernel, 1000 iterations. 12.3 seconds.
-//
 
 void convolve_raw(
     int in_rank, const size_t *in_shape, const float *in_ptr,
@@ -117,7 +115,7 @@ void convolve_raw(
   offset = 0;
   corner_reset( out_rank, out_shape, out_q );
 
-  // Main convolve loop
+  // Main convolution loop
   for ( i = 0; i < out_size; i++ ) {
 #if CONVOLVER_USE_SSE
     __m128 simd_x, simd_y, simd_t;
@@ -127,12 +125,16 @@ void convolve_raw(
     float t = 0.0;
 
 #if CONVOLVER_USE_SSE
-    // Use SIMD for all the aligned values in groups of 4
+    // Contiguous kernel views need not start on a 16-byte boundary.
     for ( j = 0; j < kernel_aligned; j +=4 ) {
-      simd_x = _mm_load_ps( kernel_ptr + j );
+      simd_x = _mm_loadu_ps( kernel_ptr + j );
       // Yes the backwards alignment is correct
-      simd_y = _mm_set_ps( in_ptr[ offset + kernel_co_incr_cache[j+3] ], in_ptr[ offset + kernel_co_incr_cache[j+2] ],
-                           in_ptr[ offset + kernel_co_incr_cache[j+1] ], in_ptr[ offset + kernel_co_incr_cache[j] ] );
+      simd_y = _mm_set_ps(
+        in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - (j+3)] ],
+        in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - (j+2)] ],
+        in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - (j+1)] ],
+        in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - j] ]
+      );
       simd_x = _mm_mul_ps( simd_x, simd_y );
       simd_t = _mm_add_ps( simd_x, simd_t );
     }
@@ -141,13 +143,13 @@ void convolve_raw(
     // SSE is unavailable on architectures such as Apple Silicon.
     // Use the same calculation without x86-specific intrinsics.
     for ( j = 0; j < kernel_aligned; j++ ) {
-      t += in_ptr[ offset + kernel_co_incr_cache[j] ] * kernel_ptr[j];
+      t += in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - j] ] * kernel_ptr[j];
     }
 #endif
 
     // Complete any remaining 1,2 or 3 items one at a time
     for ( j = kernel_aligned; j < kernel_size; j++ ) {
-      t += in_ptr[ offset + kernel_co_incr_cache[j] ] * kernel_ptr[ j ];
+      t += in_ptr[ offset + kernel_co_incr_cache[kernel_size - 1 - j] ] * kernel_ptr[ j ];
     }
 
 #if CONVOLVER_USE_SSE

data/ext/convolver/convolve_raw.h

@@ -8,6 +8,8 @@
 #ifndef CONVOLVE_RAW_H
 #define CONVOLVE_RAW_H
 
+#ifndef CONVOLVER_RAW_CONFIG
+#define CONVOLVER_RAW_CONFIG
 #include <ruby.h>
 #if defined(__SSE__)
 #include <xmmintrin.h>
@@ -16,6 +18,7 @@
 #define CONVOLVER_USE_SSE 0
 #endif
 #define LARGEST_RANK 16
+#endif
 
 void convolve_raw(
     int in_rank, const size_t *in_shape, const float *in_ptr,

data/ext/convolver/convolver.c

@@ -2,10 +2,33 @@
 #include <numo/narray.h>
 #include <numo/intern.h>
 
+#include "correlate_raw.h"
 #include "convolve_raw.h"
 
 static VALUE mConvolver;
 
+/* Contiguous views share their backing storage but start at a byte offset. */
+static const float *logical_pointer_for_read(VALUE value) {
+  return (const float *)(na_get_pointer_for_read(value) + na_get_offset(value));
+}
+
+static VALUE contiguous_sfloat(VALUE value) {
+  narray_t *narray;
+
+  value = rb_funcall(numo_cSFloat, rb_intern("cast"), 1, value);
+  GetNArray(value, narray);
+  /* A scalar has no strides; Numo's contiguous check requires an axis. */
+  if (narray->ndim > 0 && !RTEST(na_check_contiguous(value))) {
+    value = na_copy(value);
+  }
+  return value;
+}
+
+enum convolver_operation {
+  CONVOLVER_CORRELATION,
+  CONVOLVER_CONVOLUTION
+};
+
 static void copy_shape(int rank, const size_t *source, size_t *target) {
   int i;
 
@@ -14,15 +37,7 @@ 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)
- *   @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_basic_valid(VALUE signal, VALUE kernel, enum convolver_operation operation) {
   volatile VALUE signal_value;
   volatile VALUE kernel_value;
   volatile VALUE result_value;
@@ -35,20 +50,12 @@ static VALUE convolver_convolve_basic(VALUE self, VALUE signal, VALUE kernel) {
   size_t result_shape[LARGEST_RANK];
   size_t numo_result_shape[LARGEST_RANK];
 
-  (void)self;
-
   if (!rb_obj_is_kind_of(signal, numo_cNArray) || !rb_obj_is_kind_of(kernel, numo_cNArray)) {
     rb_raise(rb_eArgError, "signal and kernel must be Numo::NArray values");
   }
 
-  signal_value = rb_funcall(numo_cSFloat, rb_intern("cast"), 1, signal);
-  kernel_value = rb_funcall(numo_cSFloat, rb_intern("cast"), 1, kernel);
-  if (!RTEST(na_check_contiguous(signal_value))) {
-    signal_value = na_copy(signal_value);
-  }
-  if (!RTEST(na_check_contiguous(kernel_value))) {
-    kernel_value = na_copy(kernel_value);
-  }
+  signal_value = contiguous_sfloat(signal);
+  kernel_value = contiguous_sfloat(kernel);
   GetNArray(signal_value, signal_narray);
   GetNArray(kernel_value, kernel_narray);
 
@@ -76,16 +83,53 @@ static VALUE convolver_convolve_basic(VALUE self, VALUE signal, VALUE kernel) {
   }
 
   result_value = nary_new(numo_cSFloat, rank, numo_result_shape);
-  convolve_raw(
-    rank, signal_shape, (float *)na_get_pointer_for_read(signal_value),
-    rank, kernel_shape, (float *)na_get_pointer_for_read(kernel_value),
-    rank, result_shape, (float *)na_get_pointer_for_write(result_value)
-  );
+  if (operation == CONVOLVER_CORRELATION) {
+    correlate_raw(
+      rank, signal_shape, logical_pointer_for_read(signal_value),
+      rank, kernel_shape, logical_pointer_for_read(kernel_value),
+      rank, result_shape, (float *)na_get_pointer_for_write(result_value)
+    );
+  } else {
+    convolve_raw(
+      rank, signal_shape, logical_pointer_for_read(signal_value),
+      rank, kernel_shape, logical_pointer_for_read(kernel_value),
+      rank, result_shape, (float *)na_get_pointer_for_write(result_value)
+    );
+  }
 
   return result_value;
 }
 
+/*
+ * Calculates a valid cross-correlation using the direct native implementation.
+ *
+ * @private
+ * @overload correlate_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_correlate_basic_valid(VALUE self, VALUE signal, VALUE kernel) {
+  (void)self;
+  return convolver_basic_valid(signal, kernel, CONVOLVER_CORRELATION);
+}
+
+/*
+ * Calculates a valid mathematical convolution using the direct native implementation.
+ *
+ * @private
+ * @overload convolve_basic_valid(signal, kernel)
+ *   @param signal [Numo::NArray] input values
+ *   @param kernel [Numo::NArray] convolution kernel
+ *   @return [Numo::SFloat] valid mathematical convolution result
+ */
+static VALUE convolver_convolve_basic_valid(VALUE self, VALUE signal, VALUE kernel) {
+  (void)self;
+  return convolver_basic_valid(signal, kernel, CONVOLVER_CONVOLUTION);
+}
+
 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, "correlate_basic_valid", convolver_correlate_basic_valid, 2);
+  rb_define_singleton_method(mConvolver, "convolve_basic_valid", convolver_convolve_basic_valid, 2);
 }