convolver 3.0.1 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e56b4c0d87d92abb3f8c79d3d11b8d41c8dcbb6d7055dce615eef07a363b0cc2
-  data.tar.gz: 23c852764b162f082fa380e6932a8c5ad0c400c6d766579d7a087d32cd875825
+  metadata.gz: d27be8d916e59d307ddaef4f74bdb2d6be83fc10e8b12ee3931d5136e9f7457e
+  data.tar.gz: db067d222f36caa4311a2e557aad198a16514092264e2929f6ff7e4fd9005334
 SHA512:
-  metadata.gz: 7eda50980613f1d03659465daa5b3ece647485ab38355664808497f966f232893de2133649c0e8cd9262606fde99ad3305552db27a5e719901aee6c095b2ac3d
-  data.tar.gz: da94b103db3c1af9f735787584a757ed9683a12556879495f041a88a6f7eb178ef214d871f64e8a18aa498b090c9cec748c4c7d11c534a687099e9d2a3c15ff2
+  metadata.gz: 8a3f955a008e8af26f3cae3c00b25854c10497f55dac328db8b063fa4190360c6b7a0ea87e80e4ba1a5511e525108615a0ff2202b412b9b9f700cd992fa5ba1a
+  data.tar.gz: 810fc3b67314bb846ec8363c3fe9ae205e01eef5c10b003eaafa72a3623a27169d1667db07ec0badca20aca19ae0b233e2a0b7a7a2b4fd3a1cc0dccd29655e2c

data/CHANGELOG.md

@@ -5,7 +5,58 @@ 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.1] - 2026-10-06
+
+### Added
+
+- Packaged Markdown references for calculation rules and terminology.
+- `rake docs:build` to generate linked API and reference pages; the existing
+  documentation gate also builds the pages and checks local links and anchors.
+
+### Changed
+
+- Explain public methods through purpose and worked examples, with shared
+  option rules and clear precision, alignment and memory-limit descriptions.
+- Shorten README around common usage and preserve detailed rules in the reference.
+  Calculation behavior, supported inputs and method signatures are unchanged.
+
+### Fixed
+
+- Preserve the public module overview in generated documentation, clarify valid
+  convolution indexing, and correct inherited method/error descriptions.
+- Repair changelog comparison links, using the original source commit for the
+  untagged 3.0.0 version.
+
+## [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,8 +184,10 @@ 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
+[4.0.1]: https://github.com/neilslater/convolver/compare/v4.0.0...v4.0.1
+[4.0.0]: https://github.com/neilslater/convolver/compare/v3.0.1...v4.0.0
+[3.0.1]: https://github.com/neilslater/convolver/compare/9c12a003b3b8675c9cbde0556c586da6635d872e...v3.0.1
+[3.0.0]: https://github.com/neilslater/convolver/compare/v2.0.0...9c12a003b3b8675c9cbde0556c586da6635d872e
 [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,13 +3,12 @@
 [![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 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.
+Convolver combines numeric sequences or grids with a kernel of weights. Use it
+for operations such as smoothing readings, applying an image filter or matching
+a pattern. Inputs are [`Numo::NArray`](https://github.com/yoshoku/numo-narray-alt)
+arrays. Convolver chooses between direct calculation and
+[`PocketFFT`](https://github.com/yoshoku/numo-pocketfft) transforms using estimates
+of their cost.
 
 ## Installation
 
@@ -19,146 +18,106 @@ Add Convolver to your application's Gemfile:
 gem 'convolver'
 ```
 
-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.
+Then run `bundle install`, or install it directly with `gem install convolver`.
+Ruby 3.3 or newer and a toolchain able to build native extensions are required.
+No external FFT library is needed; PocketFFT is bundled by its Ruby gem.
 
-## Usage
+## Start with a small example
 
-`convolve` calculates mathematical discrete convolution. `correlate`
-calculates cross-correlation, following the public naming convention used by
-NumPy and SciPy:
+A kernel assigns a weight to each value in a moving window. Convolution reverses
+those weights within the window; cross-correlation keeps their stored order.
+Pass the original kernel to either method.
 
 ```ruby
 require 'convolver'
 
-signal = Numo::SFloat[0.3, 0.4, 0.5]
-kernel = Numo::SFloat[1.3, -0.5]
+signal = Numo::DFloat[1, 2, 4, 8, 16]
+kernel = Numo::DFloat[1, 2, 3]
 
-Convolver.convolve(signal, kernel)
-# => Numo::SFloat#shape=[2]
-#    [0.37, 0.45]
-
-Convolver.correlate(signal, kernel)
-# => Numo::SFloat#shape=[2]
-#    [0.19, 0.27]
+Convolver.convolve(signal, kernel).to_a  # => [11.0, 22.0, 44.0]
+Convolver.correlate(signal, kernel).to_a # => [17.0, 34.0, 68.0]
 ```
 
-For real one-dimensional inputs, the two valid operations are:
-
-```text
-correlate(signal, kernel)[p] = sum_j signal[p + j] * conjugate(kernel[j])
-convolve(signal, kernel)[n]  = sum_j signal[n - j] * kernel[j]
-```
+The first convolution result is `1*3 + 2*2 + 4*1 = 11`. The corresponding
+correlation result is `1*1 + 2*2 + 4*3 = 17`. Neither method modifies its inputs.
 
-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.
+Use `convolve` for mathematical convolution, such as applying a smoothing kernel
+or combining independent probability distributions. Use `correlate` to compare
+windows with a pattern. Correlation here is a sum of products, not a normalized
+correlation coefficient.
 
-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.
+## Keep the input size or include the edges
 
-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)
+By default, Convolver returns only complete windows. `mode:` changes the output
+size along each dimension, where `S` is the signal size and `K` the kernel size:
 
-Convolver.correlate(signal, kernel)
-Convolver.correlate_basic(signal, kernel)
-Convolver.correlate_fft(signal, kernel)
-```
+| Mode | Positions included | Result size |
+| --- | --- | --- |
+| `:valid` (default) | Complete windows inside the signal | `S - K + 1` |
+| `:same` | One output for each signal position | `S` |
+| `:full` | All positions with any signal overlap | `S + K - 1` |
 
-Every calculation method accepts the same options:
+For example, a centered moving average can keep the input size and reflect
+values at the edges:
 
 ```ruby
-Convolver.convolve(signal, kernel,
-                   mode: :same,
-                   boundary: :reflect,
-                   origin: 0)
+signal = Numo::DFloat[1, 2, 4, 8, 16]
+kernel = Numo::DFloat.ones(3) / 3
+smoothed = Convolver.convolve(signal, kernel, mode: :same, boundary: :reflect)
+smoothed.shape # => [5]
+smoothed.to_a.map { |value| value.round(3) } # => [1.333, 2.333, 4.667, 9.333, 13.333]
 ```
 
-### 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` |
+Boundary choices are constant fill, nearest value, reflection with or without
+repeating the endpoint, and periodic wrap. `:same` supports all of them;
+`:full` supports constant fill only. For nonconstant boundaries, omit
+`fill_value:` entirely, even when its value would be zero.
 
-`: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.
+The [calculation rules](docs/rules.md) show each boundary, allowed option
+combinations, and how `origin:` aligns odd- and even-length kernels.
 
-### Boundary extension
+## Choose precision and calculation path
 
-For a one-dimensional signal `a b c d`, `boundary:` selects values outside the
-stored signal:
+The result is `Numo::SFloat` or `Numo::DFloat`, chosen from both inputs.
+`dtype: nil` means automatic selection; either floating class can be requested
+explicitly:
 
-| 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]
+```ruby
+signal = Numo::DFloat[1, 2, 4]
+kernel = Numo::DFloat[1, 2]
+Convolver.convolve(signal, kernel, dtype: Numo::SFloat).class # => Numo::SFloat
 ```
 
-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.
+Integer inputs are accepted according to the supported-class table in the
+rules, but results and arithmetic are floating-point. Convert to a floating
+array before dividing to make kernel weights. A later `dtype:` override cannot
+recover information already lost to integer division or rounding.
 
-Nonzero origins are supported only for `:same`; `:valid` and `:full` require
-zero.
+Start with `convolve` or `correlate` for automatic selection. To request a
+particular path, use `convolve_basic` / `correlate_basic` for direct calculation
+or `convolve_fft` / `correlate_fft` for FFT calculation. Both return the same
+shape and class; rounding can differ, so compare values with suitable tolerances.
+Neither automatic selection nor the `predict_*_time` estimates guarantee the
+fastest method or a measured running time.
 
-### Estimators
+## Reference documentation
 
-The estimator methods accept and validate the same options as their calculation
-families:
+- [Input and calculation rules](docs/rules.md): exact supported classes,
+  precision, output formulas, boundaries, alignment, estimates and memory limits.
+- [Terminology](docs/terminology.md): explanations of the words used in the API.
 
-```ruby
-Convolver.predict_convolve_basic_time(signal, kernel, mode: :same, boundary: :nearest)
-Convolver.predict_convolve_fft_time(signal, kernel, mode: :same, boundary: :wrap)
+These reference files are included in the gem. From a development checkout,
+`bundle exec rake docs:build` builds the API reference and these pages together
+in `doc/index.html`.
 
-Convolver.predict_correlate_basic_time(signal, kernel, mode: :same, boundary: :nearest)
-Convolver.predict_correlate_fft_time(signal, kernel, mode: :same, boundary: :wrap)
-```
+### Migrating from version 3
 
-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`.
+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
 
@@ -198,8 +157,9 @@ bundle exec rake docs:check
 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:
+builds the linked pages in `doc/`, checks local link destinations and anchors,
+and 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/docs/rules.md

@@ -0,0 +1,206 @@
+# Convolver input and calculation rules
+
+These rules describe Convolver 4. They apply to both convolution and
+cross-correlation. See the [terminology](terminology.md) for unfamiliar words,
+or [README](../README.md) for installation and a quick example.
+
+## Choose an operation
+
+Use `Convolver.convolve` for mathematical convolution and `Convolver.correlate`
+for cross-correlation. Both slide a kernel over a signal, multiply paired values
+and add the products. Convolution reverses the kernel within each window;
+correlation keeps its stored order. Pass the kernel in its original order in
+either case: Convolver performs the named operation itself.
+
+```ruby
+require 'convolver'
+
+signal = Numo::DFloat[1, 2, 4, 8, 16]
+kernel = Numo::DFloat[1, 2, 3]
+
+Convolver.convolve(signal, kernel).to_a  # => [11.0, 22.0, 44.0]
+Convolver.correlate(signal, kernel).to_a # => [17.0, 34.0, 68.0]
+```
+
+For the first window, convolution calculates `1*3 + 2*2 + 4*1 = 11`.
+Correlation calculates `1*1 + 2*2 + 4*3 = 17`.
+
+Each operation has three entry points:
+
+| Choice | Convolution | Cross-correlation |
+| --- | --- | --- |
+| Automatic choice | `convolve` | `correlate` |
+| Direct calculation | `convolve_basic` | `correlate_basic` |
+| FFT calculation | `convolve_fft` | `correlate_fft` |
+
+Start with the automatic methods. They estimate which implementation is likely
+to be faster; they do not guarantee the fastest choice for every machine or
+input. Explicit methods are useful for measurements or when a workload needs a
+particular calculation path.
+
+## Supply compatible arrays
+
+Both inputs must be nonempty Numo arrays with the same number of dimensions,
+up to `Convolver::MAX_RANK` (16). Their sizes may differ. Two zero-dimensional
+arrays are supported and their scalar values are multiplied.
+
+The supported input classes and their automatic floating types are:
+
+| Input class in `Numo` | Automatic floating type |
+| --- | --- |
+| `SFloat`, `Int8`, `UInt8`, `Int16`, `UInt16` | `Numo::SFloat` |
+| `DFloat`, `Int32`, `UInt32`, `Int64`, `UInt64` | `Numo::DFloat` |
+
+Inputs must be instances of these concrete classes. Ordinary Ruby arrays,
+`Numo::Bit`, complex arrays, `Numo::RObject` and custom subclasses are rejected,
+even when `dtype:` is supplied. Supported array views, including slices and
+reversed views, are accepted. Neither input is modified.
+
+## Choose precision
+
+By default, Convolver maps each input using the table above. If either maps to
+`Numo::DFloat`, the result is DFloat; otherwise it is SFloat. Swapping the input
+types does not change this choice. `dtype: nil` means the same as omitting it.
+
+Use `dtype: Numo::SFloat` or `dtype: Numo::DFloat` to choose explicitly. These
+classes and `nil` are the only accepted dtype values. Both inputs and any
+constant fill are converted to the chosen type before preparing boundary
+values or calculating. The fill value does not influence the choice of dtype.
+
+Choose floating inputs before dividing to make kernel weights. Integer division
+can discard fractions before Convolver sees them:
+
+```ruby
+Numo::Int16.ones(3) / 3  # => integer weights [0, 0, 0]
+Numo::DFloat.ones(3) / 3 # => floating weights, each approximately one third
+```
+
+A later dtype override cannot recover information already lost to integer
+division or floating-point rounding. Integer inputs produce approximate floating
+calculations, not integer results. DFloat can represent every 32-bit integer,
+but not every 64-bit integer. Neither result type guarantees exact integer
+convolution.
+
+The direct path multiplies and adds in the chosen precision. The FFT path uses
+double-precision working buffers, then returns the chosen result type. Shapes
+and result classes agree across paths, but rounding can differ. Compare numeric
+results with a tolerance appropriate to the data and precision.
+
+Normal floating conversion applies, including overflow to infinity and
+underflow. NaN and infinity are accepted, but their propagation can differ
+between calculation paths.
+
+## Choose output size
+
+`mode:` controls the size of the result. In this table, `S` is the signal size
+and `K` the kernel size along one dimension. Apply the rule to each dimension.
+
+| Mode | Positions included | Result size |
+| --- | --- | --- |
+| `:valid` (default) | Only windows fully inside the stored signal | `S - K + 1` |
+| `:same` | One output aligned with each stored signal position | `S` |
+| `:full` | All positions with any stored-signal overlap | `S + K - 1` |
+
+In valid mode, the kernel must fit inside the signal in every dimension. Larger
+kernels are permitted in same and full modes. Equal numbers of dimensions are
+still required; a one-dimensional kernel is not automatically applied to each
+row of a two-dimensional signal.
+
+For one-dimensional valid results, returned index `p` starts at zero:
+
+```text
+convolve(signal, kernel)[p]  = sum_j signal[p + K - 1 - j] * kernel[j]
+correlate(signal, kernel)[p] = sum_j signal[p + j] * kernel[j]
+```
+
+Here `j` runs from zero to `K - 1`. For multiple dimensions, apply the index
+rule along every dimension and sum over all kernel positions. Convolver accepts
+real inputs only, so correlation has no visible complex-conjugation step.
+
+## Choose values beyond the edges
+
+`boundary:` supplies values outside the stored signal. For a signal `a b c d`,
+the following table shows examples immediately before and after it:
+
+| Boundary | Before | Stored signal | After |
+| --- | --- | --- | --- |
+| `:constant` (default) | `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` |
+
+Reflect repeats the edge sample; mirror does not. Wrap treats the signal as
+repeating. These rules work along every dimension, including dimensions of
+length one and extensions wider than the stored signal.
+
+For constant boundaries, `fill_value:` sets `k` and must be a real numeric
+value. Omitting it uses zero. For all other boundaries, omit `fill_value:`
+entirely: even an explicit `fill_value: 0` is rejected.
+
+Some generated method signatures show `UNSPECIFIED_FILL`. This is Convolver's
+internal marker for an omitted argument, not a value callers should pass. It
+lets Convolver distinguish omission from an explicitly supplied zero.
+
+The permitted combinations are:
+
+| Mode | Boundary | Fill | Origin |
+| --- | --- | --- | --- |
+| `:valid` | `:constant` only | Omitted or zero | Zero |
+| `:same` | Any listed boundary | Real numeric for constant; omit for others | Within the range below |
+| `:full` | `:constant` only | Omitted or real numeric | Zero |
+
+Mode and boundary names must be the symbols shown, not strings.
+
+## Align the kernel
+
+`origin:` adjusts kernel alignment in same mode. Supply an integer for all
+dimensions, or an array containing one integer per dimension. The default is
+zero. For a kernel dimension of length `K`:
+
+```text
+anchor = floor(K / 2) + origin
+```
+
+The anchor must be a kernel index: `0 <= anchor < K`. For example, a kernel of
+length three allows origins -1, 0 and 1; length four allows -2, -1, 0 and 1.
+Valid and full modes require zero origins.
+
+For a same-mode output at position `i`, with boundary values supplied as above:
+
+```text
+convolution[i] = sum_j extended_signal[i + anchor - j] * kernel[j]
+correlation[i] = sum_j extended_signal[i + j - anchor] * kernel[j]
+```
+
+With origin zero, odd-length kernels use the same alignment for both operations.
+For even-length kernels, correlation needs the extra boundary sample before the
+signal, and convolution needs it after. Increasing the origin moves convolution
+windows toward higher signal indices and correlation windows toward lower ones.
+
+## Interpret estimates and failures
+
+`predict_convolve_basic_time`, `predict_convolve_fft_time`,
+`predict_correlate_basic_time` and `predict_correlate_fft_time` accept the same
+inputs and options as the calculation methods. They return comparative cost
+estimates, not measured elapsed times. Smaller estimates suggest less work.
+They do not execute the convolution or allocate its result array.
+
+The estimates account for input conversion, boundary preparation and periodic
+kernel folding. Ranks one through three use calibrated profiles for arm64 macOS
+and x86_64/aarch64 Linux. Other platforms and higher ranks use a general
+heuristic. These profiles describe broad platform families, not measurements
+of the caller's particular CPU. Automatic selection can change as estimates
+improve.
+
+Invalid inputs or option combinations raise `ArgumentError`. Calculations and
+estimators reject unrepresentable planned dimensions or buffers with
+`RangeError`. FFT checks include conservative native integer and working-buffer
+limits. Automatic calculation can use direct execution if FFT exceeds its
+limits and the direct path is still valid.
+
+These checks do not reserve RAM or guarantee enough memory is available.
+Ordinary allocation failures still raise `NoMemoryError`.
+
+For older applications, see the [README](../README.md) sections on the version 3
+precision migration and version 2 operation-name migration.

data/docs/terminology.md

@@ -0,0 +1,30 @@
+# Convolver terminology
+
+This glossary explains the words used in the [calculation rules](rules.md) and
+API reference. See [README](../README.md) for installation and usage.
+
+| Term | Meaning in Convolver |
+| --- | --- |
+| Signal | The input data being processed: for example, a sequence of readings or a grid of pixel values. It is the first argument. |
+| Kernel | The second input array. Its values supply the weights multiplied with a window of signal values. |
+| Window | The signal positions paired with the kernel to calculate one output value. A window can include values supplied by a boundary rule. |
+| Convolution | Sliding multiplication and addition with the kernel reversed within each window. Call `convolve`; do not reverse the supplied kernel yourself. |
+| Cross-correlation | Sliding multiplication and addition with the kernel in its stored order. Call `correlate`. It can measure agreement with a pattern; this is not a normalized correlation coefficient. |
+| Dimension, axis, rank | A sequence has one dimension; a grid has two. An axis is one of those dimensions, and rank is their count. Rank here is not matrix rank from linear algebra. |
+| Shape | The size along each dimension. Shape `[3, 5]` describes a grid with three rows and five columns, containing 15 values. |
+| Scalar | A single value held in a zero-dimensional Numo array. Its shape is `[]`, unlike a one-element sequence with shape `[1]`. |
+| Output extent | The size of the returned array along each dimension. `mode:` selects valid, same or full output. |
+| Boundary, extension | A rule supplying values beyond the stored signal's edges. Extension does not modify the input array. |
+| Fill value | The value supplied outside the signal for `boundary: :constant`. It defaults to zero and must be omitted for other boundaries. |
+| Anchor, origin | The anchor is the kernel index used for same-mode alignment. The origin shifts that index from `floor(kernel_size / 2)` along each dimension. |
+| Dtype | The class describing how array values are stored. Convolver returns `Numo::SFloat` (single precision) or `Numo::DFloat` (double precision). |
+| Promotion | Automatic selection of a floating type from both inputs. DFloat wins if either input maps to it; otherwise SFloat is used. |
+| Precision, rounding | Floating types retain a limited number of significant digits. Rounding replaces a value with a nearby representable value; double precision retains more digits than single precision. |
+| Tolerance | An allowed numerical difference when comparing results. It accounts for rounding; suitable values depend on the scale of the data and the precision used. |
+| View | An array referring to selected or rearranged values of another array, such as a slice or reversed sequence. Convolver uses the view's logical order. |
+| Direct calculation | Computing the sliding products and sums directly. Convolver implements this path in its native extension. |
+| FFT | Fast Fourier transform: a way to express data in frequency components. The FFT path uses transforms to calculate the same convolution or correlation, with potentially different rounding and memory use. |
+| Working buffer | Temporary storage used during calculation. Its size and precision can differ from the returned array. |
+| Folding | Adding kernel values that land on the same periodic position. This is preparation used for wrap boundaries, not a change to the stored input. |
+| Relative cost, heuristic | An approximate comparison used to choose a calculation path. It is not a measured duration or a guarantee of which path will be fastest. |
+| Native limit | A size or arithmetic limit of the underlying native implementation. Passing these checks does not guarantee that physical memory is available. |