convolver 3.0.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e56b4c0d87d92abb3f8c79d3d11b8d41c8dcbb6d7055dce615eef07a363b0cc2
-  data.tar.gz: 23c852764b162f082fa380e6932a8c5ad0c400c6d766579d7a087d32cd875825
+  metadata.gz: 0461fd5af32c0104f8214df035709fea95c2b50f21f63d1b88c7999cadcafd29
+  data.tar.gz: 770518e0498a79c213c3be551f7749d6e20139a9fd327357f1d3608c0cbb72fd
 SHA512:
-  metadata.gz: 7eda50980613f1d03659465daa5b3ece647485ab38355664808497f966f232893de2133649c0e8cd9262606fde99ad3305552db27a5e719901aee6c095b2ac3d
-  data.tar.gz: da94b103db3c1af9f735787584a757ed9683a12556879495f041a88a6f7eb178ef214d871f64e8a18aa498b090c9cec748c4c7d11c534a687099e9d2a3c15ff2
+  metadata.gz: 40b871a7ad8883742b27ff4b05ae830f38cbdd7f09f3fc6ef85fd26166bbc9613fe3fc7b3d73bd47f6ce45642dfa3e4b884bc69f9b88bc69028a043d5da5e4de
+  data.tar.gz: 506e52bd6f023d6fb169589e1763fe2a3668baf5158a04e545dd8bbc4de151e4b03ece49a51dd9b6d1b0f71666a662d9a148a269ecd96cd73c9ce6d0a2c0fa2b

data/CHANGELOG.md

@@ -5,7 +5,36 @@ 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]
+## [4.0.0] - 2026-10-06
+
+### Added
+
+- Optional `dtype: Numo::SFloat` or `dtype: Numo::DFloat` on all calculation
+  and estimator methods, with matching result types and genuine native double
+  arithmetic. Omitted or nil dtype selects precision from both operands.
+
+### Changed
+
+- **Breaking, v4.0.0:** Automatically promote SFloat and 8/16-bit integer
+  inputs to SFloat, and DFloat and 32/64-bit integer inputs to DFloat; the
+  wider floating candidate wins independently of operand order.
+- **Breaking:** Reject Bit, RObject, complex arrays and custom NArray subclasses,
+  including with an explicit floating dtype. Integer results are not supported.
+- Reuse a single operation plan during automatic dispatch and account for
+  selected dtype and input conversion in cost estimates and buffer checks.
+- Bound FFT shape search in native code and skip FFT planning when a cheap
+  cost bound already favors direct execution.
+- Calibrate direct/FFT selection for ranks one through three on arm64 macOS
+  and x86_64/aarch64 Linux, including dtype, fixed setup, continuous kernel
+  costs, boundary indexing and periodic folding. Retain the existing heuristic
+  on other platforms and higher ranks.
+
+### Fixed
+
+- Cast both inputs and fill to the resolved dtype before boundary preparation,
+  periodic folding and arithmetic, consistently across direct and FFT paths.
+  `dtype: Numo::SFloat` selects single-precision inputs/results, but does not
+  guarantee bit-for-bit version 3 results. FFT work remains double precision.
 
 ## [3.0.1] - 2026-10-04
 
@@ -133,7 +162,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/v3.0.0...HEAD
+[Unreleased]: https://github.com/neilslater/convolver/compare/v3.0.1...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

data/README.md

@@ -53,13 +53,12 @@ convolve(signal, kernel)[n]  = sum_j signal[n - j] * kernel[j]
 
 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.
+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.
+complete overlap are returned. Both inputs determine the floating result dtype,
+or you can select it explicitly with `dtype:`.
 
 The automatic, direct, and FFT implementations are available for both
 operations:
@@ -83,6 +82,41 @@ Convolver.convolve(signal, kernel,
                    origin: 0)
 ```
 
+### Input and result precision
+
+`dtype:` accepts `Numo::SFloat`, `Numo::DFloat`, or `nil` (automatic, the
+default). Automatic selection maps each input type using this table, then
+chooses DFloat if either input maps to DFloat, otherwise SFloat:
+
+| Input type | Automatic floating type |
+| --- | --- |
+| `SFloat`, `Int8`, `UInt8`, `Int16`, `UInt16` | `Numo::SFloat` |
+| `DFloat`, `Int32`, `UInt32`, `Int64`, `UInt64` | `Numo::DFloat` |
+
+The input type names above are classes in `Numo`. Both operands must be instances
+of these concrete classes. Bit, RObject, complex arrays, custom subclasses and
+ordinary Ruby arrays are rejected, even with an explicit `dtype:`. Integer
+results and complex arithmetic are not supported.
+
+```ruby
+signal = Numo::SFloat[1, 2, 3]
+kernel = Numo::DFloat[0.25, 0.75]
+Convolver.convolve(signal, kernel)                     # DFloat result
+Convolver.convolve(signal, kernel, dtype: Numo::SFloat) # SFloat result
+```
+
+Both inputs are cast to the selected dtype before extension, folding or
+arithmetic. Inputs are never mutated. `fill_value` is cast to this same dtype
+and never promotes the result. Ordinary floating conversion applies, including
+rounding, overflow to infinity and underflow; NaN and infinity are not rejected.
+Non-finite propagation and rounding can differ between algorithms.
+
+Direct products and accumulation use the selected precision. PocketFFT uses
+double-precision working buffers for either result dtype. The returned class
+is independent of algorithm selection. Integer inputs become approximate
+floating computations: DFloat represents every 32-bit integer, but not every
+64-bit integer, and neither dtype guarantees exact integer convolution.
+
 ### Output modes
 
 `mode:` controls the returned extent independently in each dimension:
@@ -153,6 +187,14 @@ Convolver.predict_correlate_basic_time(signal, kernel, mode: :same, boundary: :n
 Convolver.predict_correlate_fft_time(signal, kernel, mode: :same, boundary: :wrap)
 ```
 
+Estimates are machine-dependent heuristics, including input conversion, boundary
+preparation and periodic kernel folding. Automatic selection avoids FFT planning
+when a cheap lower bound already favors direct calculation. Ranks one through
+three use calibrated profiles on arm64 macOS and x86_64/aarch64 Linux; other
+platforms and higher ranks retain the general heuristic. Algorithm choices
+can change as estimates improve; benchmark the explicit methods for workloads
+where the choice matters.
+
 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.
@@ -160,6 +202,15 @@ 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 3
+
+Version 4 changes default result types and values: DFloat and 32/64-bit integer
+inputs now select DFloat. Pass `dtype: Numo::SFloat` to request single-precision
+inputs and results. This retains the version 3 result type, but does not promise
+identical numerical results: version 4 consistently casts both inputs before
+processing, whereas version 3's direct and FFT paths could round differently.
+The input-class restrictions listed above also apply with a dtype override.
+
 ### Migrating from version 2
 
 Version 2's `convolve*` methods calculated cross-correlation. Version 3 corrects

data/ext/convolver/convolve_raw.c

@@ -1,171 +1,57 @@
-// ext/convolver/convolve_raw.c
-
 #include "convolve_raw.h"
+#include "raw_helpers.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;
-}
-
-////////////////////////////////////////////////////////////////////////////////////////////////////
-//
-//  Convolve
-//
-
-void convolve_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 convolution 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[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 );
-    }
-    _mm_store_ps( v, simd_t );
+#define RAW_INDEX(j) (kernel_size - 1 - (j))
+#if defined(__SSE__)
+#define RAW_SIMD 1
 #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[kernel_size - 1 - j] ] * kernel_ptr[j];
-    }
+#define RAW_SIMD 0
 #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[kernel_size - 1 - j] ] * kernel_ptr[ j ];
-    }
-
-#if CONVOLVER_USE_SSE
-    out_ptr[i] = v[0] + v[1] + v[2] + v[3] + t;
+#define RAW_NAME convolve_raw
+#define RAW_TYPE float
+#define RAW_LANES 4
+#define RAW_VECTOR __m128
+#define RAW_ZERO _mm_setzero_ps
+#define RAW_LOAD _mm_loadu_ps
+#define RAW_STORE _mm_storeu_ps
+#define RAW_ADD _mm_add_ps
+#define RAW_MUL _mm_mul_ps
+#include "raw_loop.h"
+#undef RAW_NAME
+#undef RAW_TYPE
+#undef RAW_LANES
+#undef RAW_VECTOR
+#undef RAW_ZERO
+#undef RAW_LOAD
+#undef RAW_STORE
+#undef RAW_ADD
+#undef RAW_MUL
+#undef RAW_SIMD
+
+#if defined(__SSE2__)
+#define RAW_SIMD 1
 #else
-    out_ptr[i] = t;
+#define RAW_SIMD 0
 #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 );
-}
+#define RAW_NAME convolve_raw_double
+#define RAW_TYPE double
+#define RAW_LANES 2
+#define RAW_VECTOR __m128d
+#define RAW_ZERO _mm_setzero_pd
+#define RAW_LOAD _mm_loadu_pd
+#define RAW_STORE _mm_storeu_pd
+#define RAW_ADD _mm_add_pd
+#define RAW_MUL _mm_mul_pd
+#include "raw_loop.h"
+#undef RAW_NAME
+#undef RAW_TYPE
+#undef RAW_LANES
+#undef RAW_VECTOR
+#undef RAW_ZERO
+#undef RAW_LOAD
+#undef RAW_STORE
+#undef RAW_ADD
+#undef RAW_MUL
+#undef RAW_SIMD
+
+#undef RAW_INDEX

data/ext/convolver/convolve_raw.h

@@ -1,28 +1,14 @@
-// ext/convolver/convolve_raw.h
-
-////////////////////////////////////////////////////////////////////////////////////////////////
-//
-// Declarations of narray helper functions
-//
-
 #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>
-#define CONVOLVER_USE_SSE 1
-#else
-#define CONVOLVER_USE_SSE 0
-#endif
-#define LARGEST_RANK 16
-#endif
+#include "raw_config.h"
 
 void convolve_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 );
 
+void convolve_raw_double(
+    int in_rank, const size_t *in_shape, const double *in_ptr,
+    int kernel_rank, const size_t *kernel_shape, const double *kernel_ptr,
+    int out_rank, const size_t *out_shape, double *out_ptr );
 #endif

data/ext/convolver/convolver.c

@@ -4,18 +4,18 @@
 
 #include "correlate_raw.h"
 #include "convolve_raw.h"
+#include "fft_shape.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 const void *logical_pointer_for_read(VALUE value) {
+  return (const void *)(na_get_pointer_for_read(value) + na_get_offset(value));
 }
 
-static VALUE contiguous_sfloat(VALUE value) {
+static VALUE contiguous_float(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))) {
@@ -54,8 +54,13 @@ static VALUE convolver_basic_valid(VALUE signal, VALUE kernel, enum convolver_op
     rb_raise(rb_eArgError, "signal and kernel must be Numo::NArray values");
   }
 
-  signal_value = contiguous_sfloat(signal);
-  kernel_value = contiguous_sfloat(kernel);
+  VALUE dtype = CLASS_OF(signal);
+  if ((dtype != numo_cSFloat && dtype != numo_cDFloat) || CLASS_OF(kernel) != dtype) {
+    rb_raise(rb_eArgError, "native inputs must have matching SFloat or DFloat dtypes");
+  }
+
+  signal_value = contiguous_float(signal);
+  kernel_value = contiguous_float(kernel);
   GetNArray(signal_value, signal_narray);
   GetNArray(kernel_value, kernel_narray);
 
@@ -82,19 +87,35 @@ static VALUE convolver_basic_valid(VALUE signal, VALUE kernel, enum convolver_op
     numo_result_shape[rank - i - 1] = (size_t)result_shape[i];
   }
 
-  result_value = nary_new(numo_cSFloat, rank, numo_result_shape);
-  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)
-    );
+  result_value = nary_new(dtype, rank, numo_result_shape);
+  if (dtype == numo_cSFloat) {
+    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)
+      );
+    }
   } 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)
-    );
+    if (operation == CONVOLVER_CORRELATION) {
+      correlate_raw_double(
+        rank, signal_shape, logical_pointer_for_read(signal_value),
+        rank, kernel_shape, logical_pointer_for_read(kernel_value),
+        rank, result_shape, (double *)na_get_pointer_for_write(result_value)
+      );
+    } else {
+      convolve_raw_double(
+        rank, signal_shape, logical_pointer_for_read(signal_value),
+        rank, kernel_shape, logical_pointer_for_read(kernel_value),
+        rank, result_shape, (double *)na_get_pointer_for_write(result_value)
+      );
+    }
   }
 
   return result_value;
@@ -107,7 +128,7 @@ static VALUE convolver_basic_valid(VALUE signal, VALUE kernel, enum convolver_op
  * @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
+ *   @return [Numo::SFloat, Numo::DFloat] valid cross-correlation result
  */
 static VALUE convolver_correlate_basic_valid(VALUE self, VALUE signal, VALUE kernel) {
   (void)self;
@@ -121,7 +142,7 @@ static VALUE convolver_correlate_basic_valid(VALUE self, VALUE signal, VALUE ker
  * @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
+ *   @return [Numo::SFloat, Numo::DFloat] valid mathematical convolution result
  */
 static VALUE convolver_convolve_basic_valid(VALUE self, VALUE signal, VALUE kernel) {
   (void)self;
@@ -130,6 +151,7 @@ static VALUE convolver_convolve_basic_valid(VALUE self, VALUE signal, VALUE kern
 
 void Init_convolver(void) {
   mConvolver = rb_define_module("Convolver");
+  convolver_init_fft_shape(mConvolver);
   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);
 }