convolver 3.0.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +31 -2
  3. data/README.md +55 -4
  4. data/ext/convolver/convolve_raw.c +51 -165
  5. data/ext/convolver/convolve_raw.h +5 -19
  6. data/ext/convolver/convolver.c +42 -20
  7. data/ext/convolver/correlate_raw.c +51 -161
  8. data/ext/convolver/correlate_raw.h +5 -19
  9. data/ext/convolver/extconf.rb +1 -0
  10. data/ext/convolver/fft_shape.c +116 -0
  11. data/ext/convolver/fft_shape.h +8 -0
  12. data/ext/convolver/raw_config.h +11 -0
  13. data/ext/convolver/raw_helpers.h +71 -0
  14. data/ext/convolver/raw_loop.h +93 -0
  15. data/lib/convolver/buffer_preparation.rb +4 -4
  16. data/lib/convolver/circular_fft_operation.rb +4 -3
  17. data/lib/convolver/cost_profiles.rb +44 -0
  18. data/lib/convolver/fft_cost.rb +52 -0
  19. data/lib/convolver/fft_estimator.rb +25 -32
  20. data/lib/convolver/linear_fft_operation.rb +4 -2
  21. data/lib/convolver/operation_dtype.rb +42 -0
  22. data/lib/convolver/operation_execution.rb +56 -45
  23. data/lib/convolver/operation_options.rb +4 -5
  24. data/lib/convolver/operation_plan.rb +16 -3
  25. data/lib/convolver/preparation_cost.rb +46 -0
  26. data/lib/convolver/real_fft_shape.rb +2 -61
  27. data/lib/convolver/signal_extension.rb +2 -2
  28. data/lib/convolver/version.rb +1 -1
  29. data/lib/convolver.rb +35 -31
  30. metadata +10 -1
data/lib/convolver.rb CHANGED
@@ -19,8 +19,9 @@ module Convolver
19
19
  class << self
20
20
  # Chooses the likely fastest mathematical convolution implementation.
21
21
  #
22
- # Results use single precision. Inputs must be nonempty arrays of equal
23
- # rank, with at most {MAX_RANK} dimensions. Scalars multiply directly.
22
+ # Results use the dtype selected from both inputs, unless dtype overrides it.
23
+ # Inputs must be nonempty arrays of equal rank, with at most {MAX_RANK}
24
+ # dimensions. Scalars multiply directly.
24
25
  # In valid mode the kernel must fit inside the signal in every dimension.
25
26
  # Full mode permits only constant boundaries; nonconstant boundaries and
26
27
  # nonzero origins are supported only in same mode.
@@ -34,59 +35,62 @@ module Convolver
34
35
  # valid mode requires zero, and other boundaries reject this option
35
36
  # @param origin [Integer, Array<Integer>] offset from the kernel midpoint,
36
37
  # shared across axes or one per axis (default: 0)
37
- # @return [Numo::SFloat] mathematical convolution result
38
+ # @param dtype [Class, nil] Numo::SFloat or Numo::DFloat; nil promotes both inputs.
39
+ # Integer types of 8/16 bits select SFloat; 32/64 bits select DFloat.
40
+ # Only these concrete integer and floating classes are supported.
41
+ # @return [Numo::SFloat, Numo::DFloat] mathematical convolution result
38
42
  # @raise [ArgumentError] if inputs or options are invalid
39
43
  # @raise [RangeError] if planned dimensions, buffers or FFT arithmetic exceed native limits
40
44
  def convolve(signal, kernel, mode: :valid, boundary: :constant,
41
- fill_value: UNSPECIFIED_FILL, origin: 0)
42
- execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).automatic(self)
45
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
46
+ execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).automatic
43
47
  end
44
48
 
45
49
  # Chooses the likely fastest cross-correlation implementation.
46
50
  # Uses the same input and option rules as {.convolve}, without reversing
47
51
  # the kernel's orientation.
48
52
  # @param (see convolve)
49
- # @return [Numo::SFloat] cross-correlation result
53
+ # @return [Numo::SFloat, Numo::DFloat] cross-correlation result
50
54
  # @raise (see convolve)
51
55
  def correlate(signal, kernel, mode: :valid, boundary: :constant,
52
- fill_value: UNSPECIFIED_FILL, origin: 0)
53
- execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).automatic(self)
56
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
57
+ execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).automatic
54
58
  end
55
59
 
56
60
  # Uses the direct native mathematical convolution implementation.
57
61
  # @param (see convolve)
58
- # @return [Numo::SFloat] mathematical convolution result
62
+ # @return [Numo::SFloat, Numo::DFloat] mathematical convolution result
59
63
  # @raise (see convolve)
60
64
  def convolve_basic(signal, kernel, mode: :valid, boundary: :constant,
61
- fill_value: UNSPECIFIED_FILL, origin: 0)
62
- execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).basic
65
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
66
+ execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).basic
63
67
  end
64
68
 
65
69
  # Uses the direct native cross-correlation implementation.
66
70
  # @param (see convolve)
67
- # @return [Numo::SFloat] cross-correlation result
71
+ # @return [Numo::SFloat, Numo::DFloat] cross-correlation result
68
72
  # @raise (see convolve)
69
73
  def correlate_basic(signal, kernel, mode: :valid, boundary: :constant,
70
- fill_value: UNSPECIFIED_FILL, origin: 0)
71
- execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).basic
74
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
75
+ execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).basic
72
76
  end
73
77
 
74
78
  # Uses PocketFFT to calculate mathematical convolution.
75
79
  # @param (see convolve)
76
- # @return [Numo::SFloat] mathematical convolution result
80
+ # @return [Numo::SFloat, Numo::DFloat] mathematical convolution result
77
81
  # @raise (see convolve)
78
82
  def convolve_fft(signal, kernel, mode: :valid, boundary: :constant,
79
- fill_value: UNSPECIFIED_FILL, origin: 0)
80
- execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).fft
83
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
84
+ execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).fft
81
85
  end
82
86
 
83
87
  # Uses PocketFFT to calculate cross-correlation.
84
88
  # @param (see convolve)
85
- # @return [Numo::SFloat] cross-correlation result
89
+ # @return [Numo::SFloat, Numo::DFloat] cross-correlation result
86
90
  # @raise (see convolve)
87
91
  def correlate_fft(signal, kernel, mode: :valid, boundary: :constant,
88
- fill_value: UNSPECIFIED_FILL, origin: 0)
89
- execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).fft
92
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
93
+ execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).fft
90
94
  end
91
95
 
92
96
  # Estimates the relative cost of {.convolve_fft}.
@@ -95,8 +99,8 @@ module Convolver
95
99
  # @return [Float] machine-specific relative cost estimate
96
100
  # @raise (see convolve)
97
101
  def predict_convolve_fft_time(signal, kernel, mode: :valid, boundary: :constant,
98
- fill_value: UNSPECIFIED_FILL, origin: 0)
99
- execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).fft_time
102
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
103
+ execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).fft_time
100
104
  end
101
105
 
102
106
  # Estimates the relative cost of {.correlate_fft}.
@@ -105,8 +109,8 @@ module Convolver
105
109
  # @return [Float] machine-specific relative cost estimate
106
110
  # @raise (see convolve)
107
111
  def predict_correlate_fft_time(signal, kernel, mode: :valid, boundary: :constant,
108
- fill_value: UNSPECIFIED_FILL, origin: 0)
109
- execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).fft_time
112
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
113
+ execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).fft_time
110
114
  end
111
115
 
112
116
  # Estimates the relative cost of {.convolve_basic}.
@@ -115,8 +119,8 @@ module Convolver
115
119
  # @return [Float] machine-specific relative cost estimate
116
120
  # @raise (see convolve)
117
121
  def predict_convolve_basic_time(signal, kernel, mode: :valid, boundary: :constant,
118
- fill_value: UNSPECIFIED_FILL, origin: 0)
119
- execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:).basic_time
122
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
123
+ execution(:convolution, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).basic_time
120
124
  end
121
125
 
122
126
  # Estimates the relative cost of {.correlate_basic}.
@@ -125,16 +129,16 @@ module Convolver
125
129
  # @return [Float] machine-specific relative cost estimate
126
130
  # @raise (see convolve)
127
131
  def predict_correlate_basic_time(signal, kernel, mode: :valid, boundary: :constant,
128
- fill_value: UNSPECIFIED_FILL, origin: 0)
129
- execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:).basic_time
132
+ fill_value: UNSPECIFIED_FILL, origin: 0, dtype: nil)
133
+ execution(:correlation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:).basic_time
130
134
  end
131
135
 
132
136
  private
133
137
 
134
- private :convolve_basic_valid, :correlate_basic_valid
138
+ private :convolve_basic_valid, :correlate_basic_valid, :fft_fast_shape, :fft_shape_cost
135
139
 
136
- def execution(operation, signal, kernel, mode:, boundary:, fill_value:, origin:)
137
- OperationExecution.new(operation, signal, kernel, mode:, boundary:, fill_value:, origin:)
140
+ def execution(operation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:)
141
+ OperationExecution.new(operation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:)
138
142
  end
139
143
  end
140
144
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: convolver
3
3
  version: !ruby/object:Gem::Version
4
- version: 3.0.1
4
+ version: 4.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Neil Slater
@@ -67,18 +67,27 @@ files:
67
67
  - ext/convolver/correlate_raw.c
68
68
  - ext/convolver/correlate_raw.h
69
69
  - ext/convolver/extconf.rb
70
+ - ext/convolver/fft_shape.c
71
+ - ext/convolver/fft_shape.h
72
+ - ext/convolver/raw_config.h
73
+ - ext/convolver/raw_helpers.h
74
+ - ext/convolver/raw_loop.h
70
75
  - lib/convolver.rb
71
76
  - lib/convolver/buffer_limits.rb
72
77
  - lib/convolver/buffer_preparation.rb
73
78
  - lib/convolver/circular_fft_operation.rb
79
+ - lib/convolver/cost_profiles.rb
74
80
  - lib/convolver/fft_buffer_plan.rb
81
+ - lib/convolver/fft_cost.rb
75
82
  - lib/convolver/fft_estimator.rb
76
83
  - lib/convolver/fft_limits.rb
77
84
  - lib/convolver/linear_fft_operation.rb
85
+ - lib/convolver/operation_dtype.rb
78
86
  - lib/convolver/operation_execution.rb
79
87
  - lib/convolver/operation_options.rb
80
88
  - lib/convolver/operation_plan.rb
81
89
  - lib/convolver/operation_shapes.rb
90
+ - lib/convolver/preparation_cost.rb
82
91
  - lib/convolver/real_fft_shape.rb
83
92
  - lib/convolver/signal_extension.rb
84
93
  - lib/convolver/version.rb