convolver 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c83dcadafabcbb8a971258601e61697a35d73afc28e7341bbe9d6f5fee887e3
-  data.tar.gz: dfc6018d6b2ae5a9ea7570036874f036961e9925c18e41116b481b4604f0cc56
+  metadata.gz: 4c27f2aa98b988627391d0a9812c6b8e0a59e65cf4a506592d95f43d1a02e3ae
+  data.tar.gz: ede25a5203ed707bd3ca726eb513ceb44746bc5a04c294396d368ab3785b2c4c
 SHA512:
-  metadata.gz: 41b62c830ba924ddc25abcf92363fcf474477d806e4040d7c694496ed1eda15d3929e4bfeea2597b7ee372baa28c44991d69c9941cfa7db753070ca8bac7b90c
-  data.tar.gz: 0fd4024a1a4eb0c1b0a6059e6f606508e048dc4a6e56d5499e0c5b94d85669ba17831472a0c3167e1361b8b25ec299d665cab3a4bc38162c363c756dddb60ecc
+  metadata.gz: aaf0fc6ab38eedbe06c2082b8ffaa2cdbfab45b3340aadf7c87839d28aa97dbb3be1e22a99c3aef25207b656741c69763bb177003d74e440ce7d6653be22aff8
+  data.tar.gz: 20b127fa09a8c6b449e74183da3fa91a93603bc17701b4991543de6095ae64023ef217c166d5a7ef999a241de125c7278e6f1e2b3d895f5ec0d0fe2665188bd5

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+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).
+
+## [1.0.0] - 2026-07-21
+
+### Added
+
+- Native C quality tasks for strict compiler warnings (`c:lint`), GCC/gcovr
+  coverage (`c:coverage`), and ASan/UBSan checks (`c:sanitize`).
+- GitHub Actions reporting and downloadable HTML and Cobertura artifacts for C
+  coverage.
+- RuboCop checks with Rake and RSpec plugins.
+- SimpleCov reporting for the Ruby test suite.
+- Support for Ruby 4.0 in the CI test matrix.
+- Monthly scheduled CI runs to detect dependency and toolchain regressions.
+- Ruby branch-coverage reporting and additional coverage of native input
+  validation.
+
+### Changed
+
+- **Breaking:** Replaced the unmaintained `narray` dependency with
+  `numo-narray-alt`. Public methods now accept `Numo::NArray` values and return
+  `Numo::SFloat` results instead of legacy `NArray` values.
+- **Breaking:** Raised the minimum supported Ruby version to 3.2.
+- Replaced the `fftw3` gem and external FFTW library with `numo-pocketfft`,
+  removing the system FFTW installation requirement.
+- Renamed the FFT-backed implementation from `convolve_fftw3` to
+  `convolve_fft`. The old name remains as a deprecated compatibility alias.
+- Clarified that the operations calculate valid cross-correlation and expanded
+  the README and YARD documentation for input, output, and shape behaviour.
+- Replaced the retired Travis CI configuration with GitHub Actions.
+- Improved gem metadata and limited packaged files to the library, native
+  extension, documentation, and licence.
+
+### Fixed
+
+- Reject non-Numo inputs, empty arrays, unequal ranks, kernels larger than their
+  signals, and ranks unsupported by the native implementation with descriptive
+  `ArgumentError` messages.
+- Updated the native extension to use the maintained Numo C API and removed the
+  legacy untyped-data compatibility code.
+
+[1.0.0]: https://github.com/neilslater/convolver/compare/v0.3.2...v1.0.0

data/README.md

@@ -1,86 +1,99 @@
 # Convolver
 
-[![Gem Version](https://badge.fury.io/rb/convolver.png)](http://badge.fury.io/rb/convolver)
-[![Build Status](https://api.travis-ci.com/neilslater/convolver.png?branch=master)](https://travis-ci.com/github/neilslater/convolver)
-[![Coverage Status](https://coveralls.io/repos/neilslater/convolver/badge.png?branch=master)](https://coveralls.io/r/neilslater/convolver?branch=master)
-[![Code Climate](https://codeclimate.com/github/neilslater/convolver.png)](https://codeclimate.com/github/neilslater/convolver)
+[![Gem Version](https://badge.fury.io/rb/convolver.svg)](https://badge.fury.io/rb/convolver)
 
-Calculates discrete convolution between two multi-dimensional arrays of floats.
-See http://en.wikipedia.org/wiki/Convolution
+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
+implementation for larger inputs.
 
-## Installation
+Version 1.0 replaces the unmaintained `narray` and `fftw3` gems with
+`numo-narray-alt` and `numo-pocketfft`.
 
-### Dependency: FFTW3
+## Installation
 
-Before you install *convolver*, you should install the FFTW3 library on your system.
-See http://www.fftw.org/ for details.
+Add Convolver to your application's Gemfile:
 
-On macOS with Homebrew, the `fftw3` Ruby gem needs to be told where Homebrew
-installed the headers and libraries:
+```ruby
+gem 'convolver'
+```
 
-    brew install fftw
-    bundle config set --local build.fftw3 "--with-fftw3-dir=$(brew --prefix fftw)"
-    bundle install
+Then run:
 
-The local Bundler setting is written to `.bundle/config`, which is intentionally
-not committed because the Homebrew prefix depends on the machine.
+```sh
+bundle install
+```
 
-### Known warning with Ruby 3.4
+Alternatively, install it directly:
 
-The first use of `NArray` may emit this warning:
+```sh
+gem install convolver
+```
 
-    warning: undefining the allocator of T_DATA class NArray
+No external FFT library is required; PocketFFT is bundled by its Ruby gem.
 
-This comes from the legacy native allocation API used by `narray` 0.6.1.2. Ruby
-disables the inherited allocator when the first native NArray object is created.
-The warning does not affect convolver's results; removing it properly requires a
-fix in `narray` or a future migration to a maintained NArray implementation.
+## Usage
 
-### Installing the gem
+```ruby
+require 'convolver'
 
-Add this line to your application's Gemfile:
+signal = Numo::SFloat[0.3, 0.4, 0.5]
+kernel = Numo::SFloat[1.3, -0.5]
 
-    gem 'convolver'
+Convolver.convolve(signal, kernel)
+# => Numo::SFloat#shape=[2]
+#    [0.19, 0.27]
+```
 
-And then execute:
+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:
 
-    $ bundle
+```ruby
+signal_size - kernel_size + 1
+```
 
-Or install it yourself as:
+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.
 
-    $ gem install convolver
+`Convolver.convolve` normally chooses the implementation automatically. The
+implementations can also be called directly for application-specific
+benchmarking:
 
-## Usage
+```ruby
+Convolver.convolve_basic(signal, kernel)
+Convolver.convolve_fft(signal, kernel)
+```
 
-Basic convolution:
+`Convolver.convolve_fftw3` remains as a deprecated alias for `convolve_fft` to
+ease migration from Convolver 0.x.
 
-    a = NArray[0.3,0.4,0.5]
-    b = NArray[1.3, -0.5]
-    c = Convolver.convolve( a, b )
-    => NArray.float(2): [ 0.19, 0.27 ]
-
- * Convolver only works on single-precision floats internally. It will cast NArray types to this, if
-possible, prior to calculating. For best speed, use NArray.sfloat arrays.
+## Contributing
 
- * The output is smaller than the input, it only contains fully-calculated values. The output size
-is the original size, minus the kernel size, plus 1, in each dimension.
+Install the development dependencies, then run the main suite:
 
- * Convolver expects input a and kernel b to have the same rank, and for the kernel to be same size
-or smaller in all dimensions as the input.
+```sh
+bundle install
+bundle exec rake
+bundle exec rubocop
+bundle exec rake c:lint
+```
 
- * Convolver.convolve will try to choose the faster of two approaches it has coded. In general,
-small convolutions are processed directly by multiplying out all combinations and summing them,
-and large convolutions are processed using FFTW3 to convert to frequency space where convolution
-is simpler and faster to calculate, then convert back.
+The Ruby specs exercise both the Ruby API and native extension. Additional
+native-code checks are available:
 
-## Contributing
+```sh
+bundle exec rake c:coverage  # Requires GCC and gcovr
+bundle exec rake c:sanitize  # Requires Linux and GCC
+```
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+`c:coverage` writes HTML and Cobertura reports under `coverage/c`. CI uploads
+the reports as a `c-coverage` artifact. The sanitizer task uses AddressSanitizer
+and UndefinedBehaviorSanitizer.
 
 ## Contributors
 
- * [Dima Ermilov](https://github.com/adworse) contributed fix to support compiling under Windows.
+- [Dima Ermilov](https://github.com/adworse) contributed the original Windows
+  compilation support.

data/ext/convolver/convolve_raw.c

@@ -2,7 +2,7 @@
 
 #include "convolve_raw.h"
 
-inline int size_from_shape( int rank, int *shape ) {
+static inline int size_from_shape( int rank, int *shape ) {
   int size = 1;
   int i;
   for ( i = 0; i < rank; i++ ) { size *= shape[i]; }
@@ -10,15 +10,16 @@ inline int size_from_shape( int rank, int *shape ) {
 }
 
 // Sets reverse indices
-inline void corner_reset( int rank, int *shape, int *rev_indices ) {
+static inline void corner_reset( int rank, int *shape, int *rev_indices ) {
   int i;
   for ( i = 0; i < rank; i++ ) { rev_indices[i] = shape[i] - 1; }
   return;
 }
 
 // Counts indices down, returns number of ranks that reset
-inline int corner_dec( int rank, int *shape, int *rev_indices ) {
+static inline int corner_dec( int rank, int *shape, int *rev_indices ) {
   int i = 0;
+  (void) rank;
   while ( ! rev_indices[i]-- ) {
     rev_indices[i] = shape[i] - 1;
     i++;
@@ -27,7 +28,7 @@ inline int corner_dec( int rank, int *shape, int *rev_indices ) {
 }
 
 // Generates co-increment steps by rank boundaries crossed, for the outer position as inner position is incremented by 1
-inline void calc_co_increment( int rank, int *outer_shape, int *inner_shape, int *co_increment ) {
+static inline void calc_co_increment( int rank, int *outer_shape, int *inner_shape, int *co_increment ) {
   int i, factor;
   co_increment[0] = 1; // co-increment is always 1 in lowest rank
   factor = 1;
@@ -48,12 +49,11 @@ void convolve_raw(
     int in_rank, int *in_shape, float *in_ptr,
     int kernel_rank, int *kernel_shape, float *kernel_ptr,
     int out_rank, int *out_shape, float *out_ptr ) {
-  int i, j, in_size, kernel_size, kernel_aligned, out_size, offset;
+  int i, j, kernel_size, kernel_aligned, out_size, offset;
   int out_co_incr[LARGEST_RANK], kernel_co_incr[LARGEST_RANK];
   int ker_q[LARGEST_RANK], out_q[LARGEST_RANK];
   int *kernel_co_incr_cache;
 
-  in_size = size_from_shape( in_rank, in_shape );
   kernel_size = size_from_shape( kernel_rank, kernel_shape );
   kernel_aligned = 4 * (kernel_size/4);
   out_size = size_from_shape( out_rank, out_shape );

data/ext/convolver/convolve_raw.h

@@ -15,8 +15,6 @@
 #else
 #define CONVOLVER_USE_SSE 0
 #endif
-#include "narray_shared.h"
-
 #define LARGEST_RANK 16
 
 void convolve_raw(

data/ext/convolver/convolver.c

@@ -1,118 +1,89 @@
-// ext/convolver/convolver.c
-
+#include <limits.h>
 #include <ruby.h>
-#include "narray.h"
-#include <stdio.h>
+#include <numo/narray.h>
+#include <numo/intern.h>
 
-#include "narray_shared.h"
 #include "convolve_raw.h"
 
-////////////////////////////////////////////////////////////////////////////////////////////////////
-
-// To hold the module object
-VALUE Convolver = Qnil;
-
-/* @overload fit_kernel_backwards( fft_temp_space, kernel )
- * @!visibility private
- * Over-writes fft_temp_space at edges with a reversed copy of kernel, in such a way that
- * an FFTW3-based convolve has a result set in an easy-to-extract position later. This is
- * implemented as a native extension for convenience and speed - to do this with methods provided
- * by narray gem would take several complex steps and be inefficient.
- * @param [NArray<sfloat>] fft_temp_space target array for pre-fft copy of kernel, is over-written
- * @param [NArray] kernel must be same size or smaller than fft_temp_space in each dimension
- * @return [nil]
- */
-static VALUE narray_fit_backwards( VALUE self, VALUE a, VALUE b ) {
-  struct NARRAY *na_a, *na_b;
-  volatile VALUE val_a, val_b;
-  int target_rank, i;
-  int shift_by[LARGEST_RANK];
-
-  val_a = na_cast_object(a, NA_SFLOAT);
-  GetNArray( val_a, na_a );
-
-  val_b = na_cast_object(b, NA_SFLOAT);
-  GetNArray( val_b, na_b );
-
-  if ( na_a->rank != na_b->rank ) {
-    rb_raise( rb_eArgError, "narray a must have equal rank to narray b (a rank %d, b rank %d)", na_a->rank,  na_b->rank );
-  }
-
-  if ( na_a->rank > LARGEST_RANK ) {
-    rb_raise( rb_eArgError, "exceeded maximum narray rank for convolve of %d", LARGEST_RANK );
-  }
+static VALUE mConvolver;
 
-  target_rank = na_a->rank;
+static void copy_shape(int rank, const size_t *source, int *target) {
+  int i;
 
-  for ( i = 0; i < target_rank; i++ ) {
-    if ( ( na_a->shape[i] - na_b->shape[i] ) < 0 ) {
-      rb_raise( rb_eArgError, "no space for backward fit" );
+  for (i = 0; i < rank; i++) {
+    if (source[rank - i - 1] > INT_MAX) {
+      rb_raise(rb_eArgError, "array dimension exceeds native implementation limit");
     }
-    shift_by[i] = na_b->shape[i] >> 1;
+    target[i] = (int)source[rank - i - 1];
   }
-
-  fit_backwards_raw(
-    target_rank,
-    na_a->shape, (float*) na_a->ptr,
-    na_b->shape, (float*) na_b->ptr,
-    shift_by );
-
-  return Qnil;
 }
 
-
-/* @overload convolve_basic( signal, kernel )
- * Calculates convolution of an array of floats representing a signal, with a second array representing
- * a kernel. The two parameters must have the same rank. The output has same rank, its size in each dimension d is given by
- *  signal.shape[d] - kernel.shape[d] + 1
- * @param [NArray] signal must be same size or larger than kernel in each dimension
- * @param [NArray] kernel must be same size or smaller than signal in each dimension
- * @return [NArray] result of convolving signal with kernel
+/*
+ * 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 narray_convolve( VALUE self, VALUE a, VALUE b ) {
-  struct NARRAY *na_a, *na_b, *na_c;
-  volatile VALUE val_a, val_b, val_c;
-  int target_rank, i;
-  int target_shape[LARGEST_RANK];
-
-  val_a = na_cast_object(a, NA_SFLOAT);
-  GetNArray( val_a, na_a );
+static VALUE convolver_convolve_basic(VALUE self, VALUE signal, VALUE kernel) {
+  volatile VALUE signal_value;
+  volatile VALUE kernel_value;
+  volatile VALUE result_value;
+  narray_t *signal_narray;
+  narray_t *kernel_narray;
+  int rank;
+  int i;
+  int signal_shape[LARGEST_RANK];
+  int kernel_shape[LARGEST_RANK];
+  int 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");
+  }
 
-  val_b = na_cast_object(b, NA_SFLOAT);
-  GetNArray( val_b, na_b );
+  signal_value = rb_funcall(numo_cSFloat, rb_intern("cast"), 1, signal);
+  kernel_value = rb_funcall(numo_cSFloat, rb_intern("cast"), 1, kernel);
+  GetNArray(signal_value, signal_narray);
+  GetNArray(kernel_value, kernel_narray);
 
-  if ( na_a->rank != na_b->rank ) {
-    rb_raise( rb_eArgError, "narray a must have equal rank to narray b (a rack %d, b rank %d)", na_a->rank,  na_b->rank );
+  if (signal_narray->size == 0 || kernel_narray->size == 0) {
+    rb_raise(rb_eArgError, "signal and kernel must not be empty");
   }
 
-  if ( na_a->rank > LARGEST_RANK ) {
-    rb_raise( rb_eArgError, "exceeded maximum narray rank for convolve of %d", LARGEST_RANK );
+  if (signal_narray->ndim != kernel_narray->ndim) {
+    rb_raise(rb_eArgError, "signal and kernel must have equal rank");
+  }
+  if (signal_narray->ndim > LARGEST_RANK) {
+    rb_raise(rb_eArgError, "maximum supported rank is %d", LARGEST_RANK);
   }
 
-  target_rank = na_a->rank;
+  rank = signal_narray->ndim;
+  copy_shape(rank, signal_narray->shape, signal_shape);
+  copy_shape(rank, kernel_narray->shape, kernel_shape);
 
-  for ( i = 0; i < target_rank; i++ ) {
-    target_shape[i] = na_a->shape[i] - na_b->shape[i] + 1;
-    if ( target_shape[i] < 1 ) {
-      rb_raise( rb_eArgError, "narray b is bigger in one or more dimensions than narray a" );
+  for (i = 0; i < rank; i++) {
+    result_shape[i] = signal_shape[i] - kernel_shape[i] + 1;
+    if (result_shape[i] < 1) {
+      rb_raise(rb_eArgError, "kernel must not be larger than signal in any dimension");
     }
+    numo_result_shape[rank - i - 1] = (size_t)result_shape[i];
   }
 
-  val_c = na_make_object( NA_SFLOAT, target_rank, target_shape, CLASS_OF( val_a ) );
-  GetNArray( val_c, na_c );
-
+  result_value = nary_new(numo_cSFloat, rank, numo_result_shape);
   convolve_raw(
-    target_rank, na_a->shape, (float*) na_a->ptr,
-    target_rank, na_b->shape, (float*) na_b->ptr,
-    target_rank, target_shape, (float*) na_c->ptr );
+    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)
+  );
 
-  return val_c;
+  return result_value;
 }
 
-void Init_convolver() {
-  Convolver = rb_define_module( "Convolver" );
-  rb_define_singleton_method( Convolver, "convolve_basic", narray_convolve, 2 );
-
-  // private method
-  rb_define_singleton_method( Convolver, "fit_kernel_backwards", narray_fit_backwards, 2 );
+void Init_convolver(void) {
+  mConvolver = rb_define_module("Convolver");
+  rb_define_singleton_method(mConvolver, "convolve_basic", convolver_convolve_basic, 2);
 }

data/ext/convolver/extconf.rb

@@ -1,37 +1,50 @@
 # frozen_string_literal: true
 
-# ext/convolver/extconf.rb
 require 'mkmf'
-require 'rubygems'
+require 'numo/narray/alt'
 
-# Following code stolen shamelessly from fftw3 gem:
-narray_dir = begin
-  File.dirname(Gem.find_files('narray.h').first)
-rescue StandardError
-  $sitearchdir
-end
-if /cygwin|mingw/ =~ RUBY_PLATFORM
-  dir_config('narray', narray_dir, "#{narray_dir}/src")
-else
-  dir_config('narray', narray_dir, narray_dir)
+$LOAD_PATH.each do |load_path|
+  next unless File.exist?(File.join(load_path, 'numo/numo/narray.h'))
+
+  $INCFLAGS = "-I#{File.join(load_path, 'numo')} #{$INCFLAGS}"
+  break
 end
 
-unless have_header('narray.h') && have_header('narray_config.h')
-  print <<-ERROR_MESSAGE
-   ** configure error **
-   Header narray.h or narray_config.h is not found. If you have these files in
-   /narraydir/include, try the following:
+abort 'numo/narray.h not found' unless have_header('numo/narray.h')
 
-   % ruby extconf.rb --with-narray-include=/narraydir/include
+if RUBY_PLATFORM.match?(/mswin|cygwin|mingw/)
+  $LOAD_PATH.each do |load_path|
+    next unless File.exist?(File.join(load_path, 'numo/narray/libnarray.a'))
 
-  ERROR_MESSAGE
-  exit(-1)
+    $LDFLAGS = "-L#{File.join(load_path, 'numo/narray')} #{$LDFLAGS}"
+    break
+  end
+  abort 'libnarray.a not found' unless have_library('narray', 'nary_new')
 end
 
-# This also stolen from fftw3 gem (and not confirmed for Windows platforms - please let me know if it works!)
-if /cygwin|mingw/ =~ RUBY_PLATFORM
-  have_library('narray') || raise('ERROR: narray library is not found')
+if RUBY_PLATFORM.include?('darwin') && Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.1') &&
+   try_link('int main(void) { return 0; }', '-Wl,-undefined,dynamic_lookup')
+  $LDFLAGS << ' -Wl,-undefined,dynamic_lookup'
+end
+
+case ENV.fetch('CONVOLVER_NATIVE_MODE', 'release')
+when 'release'
+  $CFLAGS << ' -O3 -funroll-loops'
+when 'lint'
+  $CFLAGS << ' -std=gnu2x -O0 -g -Wall -Wextra -Wpedantic -Wformat=2 -Werror'
+  if RbConfig::CONFIG.fetch('CC').match?(/clang/) || RbConfig::CONFIG.fetch('host_os').match?(/darwin/)
+    $CFLAGS << ' -Wno-c23-extensions -Wno-strict-prototypes -Wno-unused-parameter'
+    $CFLAGS << ' -Wno-default-const-init-field-unsafe'
+  end
+when 'coverage'
+  $CFLAGS << ' -O0 -g --coverage'
+  $LDFLAGS << ' --coverage'
+when 'sanitize'
+  sanitizer_flags = ' -O1 -g -fsanitize=address,undefined -fno-omit-frame-pointer'
+  $CFLAGS << sanitizer_flags
+  $LDFLAGS << ' -fsanitize=address,undefined'
+else
+  abort "Unknown CONVOLVER_NATIVE_MODE: #{ENV.fetch('CONVOLVER_NATIVE_MODE', nil)}"
 end
 
-$CFLAGS << ' -O3 -funroll-loops'
 create_makefile('convolver/convolver')

data/lib/convolver/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Convolver
-  VERSION = '0.4.0'
+  # Current gem version.
+  VERSION = '1.0.0'
 end