convolver 2.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08959da24c94d02889f0067f18f7233578b4b14ec4e58538b144efeef1cbe25f'
-  data.tar.gz: c39df2ebf01a04f93fa62e49bd8a4542e78244868d822d7f47a00cc78b9aaa7e
+  metadata.gz: e56b4c0d87d92abb3f8c79d3d11b8d41c8dcbb6d7055dce615eef07a363b0cc2
+  data.tar.gz: 23c852764b162f082fa380e6932a8c5ad0c400c6d766579d7a087d32cd875825
 SHA512:
-  metadata.gz: 73d425b7851b21dd93cb135ca7ad88aa75f760b41a53ed8a2b72b2a9110e183062c1643af9563f81d59248d50d3f49a531e2bbac6d0c5cdcef6383717e31f73a
-  data.tar.gz: 89ddc9f26950329b9ce2ce3917e5f90057c3c625f2210eb39fcc527cbe7b3f418f14f387665a3be3c1ea44d50beac101907c038c6ef9998998e30c21d61966d2
+  metadata.gz: 7eda50980613f1d03659465daa5b3ece647485ab38355664808497f966f232893de2133649c0e8cd9262606fde99ad3305552db27a5e719901aee6c095b2ac3d
+  data.tar.gz: da94b103db3c1af9f735787584a757ed9683a12556879495f041a88a6f7eb178ef214d871f64e8a18aa498b090c9cec748c4c7d11c534a687099e9d2a3c15ff2

data/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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
@@ -81,7 +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/v2.0.0...HEAD
+[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

@@ -3,16 +3,14 @@
 [![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 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
+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:
@@ -21,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'
 
@@ -45,32 +37,44 @@ 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]
 ```
 
-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:
+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.
 
-`Convolver.convolve` normally chooses the implementation automatically. The
-implementations can also be called directly for application-specific
-benchmarking:
+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.
+
+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)
 ```
 
-Both implementations and the automatic method accept the same options:
+Every calculation method accepts the same options:
 
 ```ruby
 Convolver.convolve(signal, kernel,
@@ -113,45 +117,89 @@ 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
+### Kernel origin and alignment
 
-`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`:
+`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`:
 
-```ruby
-anchor = (K / 2) + origin
+```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. 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 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:
+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)
 ```
 
-`Convolver.convolve_fftw3` remains as a deprecated alias for `convolve_fft` to
-ease migration from Convolver 0.x and forwards all options.
+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_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_valid(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_valid(VALUE self, VALUE signal, VALUE kern
   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_valid(VALUE self, VALUE signal, VALUE kern
   }
 
   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, "correlate_basic_valid", convolver_correlate_basic_valid, 2);
   rb_define_singleton_method(mConvolver, "convolve_basic_valid", convolver_convolve_basic_valid, 2);
 }

data/ext/convolver/correlate_raw.c

@@ -0,0 +1,167 @@
+// ext/convolver/correlate_raw.c
+
+#include "correlate_raw.h"
+
+static inline size_t checked_add( size_t left, size_t right, const char *description ) {
+  if ( right > SIZE_MAX - left ) {
+    rb_raise( rb_eRangeError, "%s exceeds native implementation limit", description );
+  }
+  return left + right;
+}
+
+static inline size_t checked_multiply( size_t left, size_t right, const char *description ) {
+  if ( left != 0 && right > SIZE_MAX / left ) {
+    rb_raise( rb_eRangeError, "%s exceeds native implementation limit", description );
+  }
+  return left * right;
+}
+
+static inline size_t size_from_shape( int rank, const size_t *shape, const char *description ) {
+  size_t size = 1;
+  int i;
+  for ( i = 0; i < rank; i++ ) {
+    size = checked_multiply( size, shape[i], description );
+  }
+  return size;
+}
+
+// Sets reverse indices
+static inline void corner_reset( int rank, const size_t *shape, size_t *rev_indices ) {
+  int i;
+  for ( i = 0; i < rank; i++ ) { rev_indices[i] = shape[i] - 1; }
+}
+
+// Counts indices down, returns number of ranks that reset
+static inline int corner_dec( int rank, const size_t *shape, size_t *rev_indices ) {
+  int i = 0;
+  (void) rank;
+  while ( ! rev_indices[i]-- ) {
+    rev_indices[i] = shape[i] - 1;
+    i++;
+  }
+  return i;
+}
+
+// Generates co-increment steps by rank boundaries crossed, for the outer position as inner position is incremented by 1
+static inline void calc_co_increment(
+    int rank, const size_t *outer_shape, const size_t *inner_shape, size_t *co_increment ) {
+  size_t factor = 1;
+  int i;
+  co_increment[0] = 1; // co-increment is always 1 in lowest rank
+  for ( i = 0; i < rank; i++ ) {
+    size_t skipped = checked_multiply( factor, outer_shape[i] - inner_shape[i], "array offset" );
+    co_increment[i+1] = checked_add( co_increment[i], skipped, "array offset" );
+    factor = checked_multiply( factor, outer_shape[i], "array size" );
+  }
+}
+
+static inline size_t maximum_offset(
+    int rank, const size_t *outer_shape, const size_t *inner_shape, const char *description ) {
+  size_t factor = 1;
+  size_t offset = 0;
+  int i;
+  for ( i = 0; i < rank; i++ ) {
+    size_t dimension_offset = checked_multiply( factor, inner_shape[i] - 1, description );
+    offset = checked_add( offset, dimension_offset, description );
+    factor = checked_multiply( factor, outer_shape[i], "array size" );
+  }
+  return offset;
+}
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Correlate
+//
+
+void correlate_raw(
+    int in_rank, const size_t *in_shape, const float *in_ptr,
+    int kernel_rank, const size_t *kernel_shape, const float *kernel_ptr,
+    int out_rank, const size_t *out_shape, float *out_ptr ) {
+  size_t i, j, input_size, kernel_size, kernel_aligned, out_size, offset;
+  size_t maximum_input_offset;
+  size_t out_co_incr[LARGEST_RANK + 1], kernel_co_incr[LARGEST_RANK + 1];
+  size_t ker_q[LARGEST_RANK], out_q[LARGEST_RANK];
+  size_t *kernel_co_incr_cache;
+  VALUE cache_storage = 0;
+
+  kernel_size = size_from_shape( kernel_rank, kernel_shape, "kernel size" );
+  kernel_aligned = kernel_size - kernel_size % 4;
+  out_size = size_from_shape( out_rank, out_shape, "output size" );
+  input_size = size_from_shape( in_rank, in_shape, "input size" );
+
+  calc_co_increment( in_rank, in_shape, out_shape, out_co_incr );
+  calc_co_increment( in_rank, in_shape, kernel_shape, kernel_co_incr );
+  maximum_input_offset = checked_add(
+    maximum_offset( in_rank, in_shape, out_shape, "input offset" ),
+    maximum_offset( in_rank, in_shape, kernel_shape, "input offset" ),
+    "input offset"
+  );
+  if ( maximum_input_offset >= input_size ) {
+    rb_raise( rb_eRangeError, "input offset exceeds native implementation limit" );
+  }
+
+  kernel_co_incr_cache = RB_ALLOCV_N( size_t, cache_storage, kernel_size );
+  kernel_co_incr_cache[0] = 0;
+
+  corner_reset( kernel_rank, kernel_shape, ker_q );
+  for ( i = 1; i < kernel_size; i++ ) {
+    kernel_co_incr_cache[i] = checked_add(
+      kernel_co_incr_cache[i-1],
+      kernel_co_incr[ corner_dec( kernel_rank, kernel_shape, ker_q ) ],
+      "kernel offset"
+    );
+  }
+
+  offset = 0;
+  corner_reset( out_rank, out_shape, out_q );
+
+  // Main correlation loop
+  for ( i = 0; i < out_size; i++ ) {
+#if CONVOLVER_USE_SSE
+    __m128 simd_x, simd_y, simd_t;
+    float v[4];
+    simd_t = _mm_setzero_ps();
+#endif
+    float t = 0.0;
+
+#if CONVOLVER_USE_SSE
+    // Contiguous kernel views need not start on a 16-byte boundary.
+    for ( j = 0; j < kernel_aligned; j +=4 ) {
+      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_x = _mm_mul_ps( simd_x, simd_y );
+      simd_t = _mm_add_ps( simd_x, simd_t );
+    }
+    _mm_store_ps( v, simd_t );
+#else
+    // 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];
+    }
+#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 ];
+    }
+
+#if CONVOLVER_USE_SSE
+    out_ptr[i] = v[0] + v[1] + v[2] + v[3] + t;
+#else
+    out_ptr[i] = t;
+#endif
+
+    if ( i + 1 < out_size ) {
+      offset = checked_add(
+        offset,
+        out_co_incr[ corner_dec( out_rank, out_shape, out_q ) ],
+        "input offset"
+      );
+    }
+  }
+
+  RB_ALLOCV_END( cache_storage );
+}