convolver 2.0.0 → 4.0.0

data/lib/convolver/circular_fft_operation.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Calculates same-sized periodic operations through PocketFFT transforms.
+  # @private
+  class CircularFftOperation
+    def initialize(operation, signal, kernel, plan)
+      @dtype = plan.dtype
+      @real_axis = plan.fft_buffers.real_axis
+      @operation = operation
+      @signal = Numo::DFloat.cast(signal)
+      @kernel = fold_kernel(Numo::DFloat.cast(kernel), signal.shape, plan.anchors)
+    end
+
+    def call
+      return complex_product unless real_axis
+
+      real_product(real_axis)
+    end
+
+    def self.real_axis(shape)
+      return nil if shape.empty?
+
+      final_axis = shape.length - 1
+      return final_axis if shape[final_axis].even?
+
+      shape.each_index.select { |axis| shape[axis].even? }.max_by { |axis| shape[axis] }
+    end
+
+    private
+
+    attr_reader :operation, :signal, :kernel, :real_axis, :dtype
+
+    def real_product(real_axis)
+      final_axis = signal.ndim - 1
+      prepared_signal = prepare_real_operand(signal, real_axis, final_axis)
+      prepared_kernel = prepare_real_operand(kernel, real_axis, final_axis)
+      result = real_spectrum_product(prepared_signal, prepared_kernel)
+      result = result.swapaxes(real_axis, final_axis) unless real_axis == final_axis
+      dtype.cast(result)
+    end
+
+    def prepare_real_operand(value, real_axis, final_axis)
+      real_axis == final_axis ? value : value.swapaxes(real_axis, final_axis)
+    end
+
+    def real_spectrum_product(signal_value, kernel_value)
+      signal_spectrum = Numo::Pocketfft.rfftn(signal_value)
+      kernel_spectrum = Numo::Pocketfft.rfftn(kernel_value)
+      kernel_spectrum.inplace.conj if operation == :correlation
+      Numo::Pocketfft.irfftn(signal_spectrum.inplace * kernel_spectrum)
+    end
+
+    def complex_product
+      signal_spectrum = Numo::Pocketfft.fftn(signal)
+      kernel_spectrum = Numo::Pocketfft.fftn(kernel)
+      kernel_spectrum.inplace.conj if operation == :correlation
+      result = Numo::Pocketfft.ifftn(signal_spectrum.inplace * kernel_spectrum).real
+      dtype.cast(result)
+    end
+
+    def fold_kernel(source, signal_shape, anchors)
+      folded = Numo::DFloat.zeros(*signal_shape)
+      source.flatten.each_with_index do |value, flat_index|
+        target = folded_target(flat_index, source.shape, signal_shape, anchors)
+        folded[*target] = folded[*target] + value
+      end
+      folded
+    end
+
+    def folded_target(flat_index, kernel_shape, signal_shape, anchors)
+      remainder = flat_index
+      Array.new(kernel_shape.length).tap do |target|
+        (kernel_shape.length - 1).downto(0) do |axis|
+          coordinate = remainder % kernel_shape[axis]
+          remainder /= kernel_shape[axis]
+          target[axis] = (coordinate - anchors[axis]) % signal_shape[axis]
+        end
+      end
+    end
+  end
+
+  private_constant :CircularFftOperation
+end

data/lib/convolver/cost_profiles.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Immutable measured-environment coefficients in seconds; ranks one through three.
+  # @private
+  module CostProfiles
+    MAC = {
+      direct: [[6.55e-6, 3.24e-10, 7.08e-10].freeze, [6.55e-6, 3.24e-10, 7.08e-10].freeze].freeze,
+      fixed: [1.64e-5, 5.12e-5, 1.13e-4].freeze,
+      transform: [8.02e-10, 7.17e-10, 1.54e-9].freeze,
+      indices: { reflect: 1.33e-7, nearest: 1.46e-7, mirror: 1.57e-7, wrap: 3.23e-8 }.freeze,
+      folding: [3.78e-7, 3.99e-7, 5.09e-7].freeze
+    }.freeze
+    X86 = {
+      direct: [[1.59e-5, 3.08e-10, 2.52e-10].freeze, [1.63e-5, 3.22e-10, 3.96e-10].freeze].freeze,
+      fixed: [3.77e-5, 1.20e-4, 1.98e-4].freeze,
+      transform: [2.00e-9, 2.13e-9, 3.13e-9].freeze,
+      indices: { reflect: 2.32e-7, nearest: 2.88e-7, mirror: 2.62e-7, wrap: 1.11e-7 }.freeze,
+      folding: [8.20e-7, 7.51e-7, 9.79e-7].freeze
+    }.freeze
+    ARM = {
+      direct: [[1.88e-5, 5.12e-10, 5.96e-10].freeze, [1.88e-5, 5.12e-10, 5.96e-10].freeze].freeze,
+      fixed: [4.20e-5, 1.20e-4, 2.70e-4].freeze,
+      transform: [3.29e-9, 2.89e-9, 3.74e-9].freeze,
+      indices: { reflect: 2.62e-7, nearest: 3.67e-7, mirror: 2.87e-7, wrap: 1.50e-7 }.freeze,
+      folding: [9.97e-7, 8.80e-7, 1.24e-6].freeze
+    }.freeze
+    def self.for_platform(platform)
+      case platform
+      when /\Aarm64-darwin/ then MAC
+      when /\Ax86_64-linux/ then X86
+      when /\Aaarch64-linux/ then ARM
+      end
+    end
+
+    CURRENT = for_platform(RUBY_PLATFORM)
+
+    def self.for_rank(rank)
+      CURRENT if (1..3).cover?(rank)
+    end
+  end
+
+  private_constant :CostProfiles
+end

data/lib/convolver/fft_buffer_plan.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'convolver/fft_limits'
+require 'convolver/buffer_preparation'
+
+module Convolver
+  # Shares allocation-free FFT dimensions between execution and estimation.
+  # @private
+  class FftBufferPlan
+    attr_reader :transform_shape, :real_axis, :transform_size, :spectrum_size
+
+    def initialize(plan, signal_shape, kernel_shape, limits: BufferLimits::NATIVE)
+      BufferPreparation.new(plan, signal_shape, kernel_shape, limits:).fft!
+      @real_axis = plan.wrap? ? CircularFftOperation.real_axis(signal_shape) : signal_shape.length - 1
+      @transform_shape = select_shape(plan, signal_shape, kernel_shape, FftLimits.new(limits))
+      @transform_size = transform_shape.reduce(1, :*)
+      @spectrum_size = spectrum_elements
+    end
+
+    private
+
+    def select_shape(plan, signal_shape, kernel_shape, limits)
+      return [].freeze if signal_shape.empty?
+      return plan.linear_fft_shape(kernel_shape, limits:) unless plan.wrap?
+
+      limits.validate!(signal_shape, real_axis:)
+      signal_shape.dup.freeze
+    end
+
+    def spectrum_elements
+      return transform_size if transform_shape.empty? || real_axis.nil?
+
+      length = transform_shape[real_axis]
+      transform_size / length * ((length / 2) + 1)
+    end
+  end
+
+  private_constant :FftBufferPlan
+end

data/lib/convolver/fft_cost.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'convolver/preparation_cost'
+
+module Convolver
+  # Shared transform costs and a lower bound that never constructs an FFT plan.
+  # @private
+  class FftCost
+    REAL = { 1 => 1.0e-9, 2 => 1.0e-9, 3 => 1.5e-9 }.freeze
+    COMPLEX = { 1 => 2.4e-9, 2 => 2.4e-9, 3 => 2.8e-9 }.freeze
+    FIXED = { 0 => 5.0e-6, 1 => 1.5e-5, 2 => 3.0e-5, 3 => 1.0e-4 }.freeze
+    PREPARATION = 1.0e-9
+
+    def self.fixed(rank, profile: nil)
+      return profile.fetch(:fixed).fetch(rank - 1) if profile
+
+      FIXED.fetch(rank, FIXED.values.last)
+    end
+
+    def self.transform(size, rank, real: true, profile: nil)
+      coefficient(rank, real:, profile:) * size * Math.log([size, 2].max)
+    end
+
+    def self.lower_bound(plan, kernel_shape, threshold:)
+      rank = kernel_shape.length
+      profile = plan.cost_profile
+      setup = fixed(rank, profile:)
+      return setup if setup >= threshold || plan.wrap? || rank.zero?
+
+      size = minimum_size(plan.extended_shape, kernel_shape)
+      setup + transform(size, rank, profile:) + (2 * PREPARATION * size) + PreparationCost.new(plan).indices
+    end
+
+    def self.coefficient(rank, real:, profile:)
+      return profile.fetch(:transform).fetch(rank - 1) * (real ? 1 : 2.2) if profile
+
+      costs = real ? REAL : COMPLEX
+      costs.fetch(rank, costs.values.last)
+    end
+    private_class_method :coefficient
+
+    def self.minimum_size(signal_shape, kernel_shape)
+      # Ruby integers avoid overflow: this is only a cost bound, never an allocation.
+      shape = signal_shape.zip(kernel_shape).map { |signal, kernel| signal + kernel - 1 }
+      shape[-1] += 1 if shape[-1].odd?
+      shape.reduce(1, :*)
+    end
+    private_class_method :minimum_size
+  end
+
+  private_constant :FftCost
+end

data/lib/convolver/fft_estimator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'convolver/fft_cost'
+
+module Convolver
+  # Estimates the selected real or complex PocketFFT implementation cost.
+  # @private
+  class FftEstimator
+    AXIS_MOVE_COST = 1.6e-9
+    RESULT_COST = 5.0e-10
+    CORRELATION_COST = 2.0e-10
+
+    def initialize(operation, signal, kernel, plan)
+      @operation = operation
+      @signal = signal
+      @kernel = kernel
+      @plan = plan
+      @profile = plan.cost_profile
+      @buffers = plan.fft_buffers
+      @preparation = PreparationCost.new(plan)
+    end
+
+    def call
+      return FftCost.fixed(0) + preparation.conversion + result_cost if signal.ndim.zero?
+
+      transform_cost + preparation_cost + extra_cost
+    end
+
+    private
+
+    attr_reader :operation, :signal, :kernel, :plan, :buffers, :preparation
+
+    def transform_cost
+      transform = FftCost.transform(buffers.transform_size, signal.ndim,
+                                    real: !buffers.real_axis.nil?, profile: @profile)
+      FftCost.fixed(signal.ndim, profile: @profile) + transform + (AXIS_MOVE_COST * moved_size)
+    end
+
+    def extra_cost
+      correlation_cost = operation == :correlation ? CORRELATION_COST * buffers.spectrum_size : 0.0
+      correlation_cost + preparation.conversion + result_cost
+    end
+
+    def result_cost
+      RESULT_COST * plan.result_size * (plan.dtype::ELEMENT_BYTE_SIZE / 4)
+    end
+
+    def preparation_cost
+      return circular_preparation_cost if plan.wrap?
+
+      (2 * FftCost::PREPARATION * buffers.transform_size) + preparation.extension
+    end
+
+    def circular_preparation_cost
+      (FftCost::PREPARATION * (signal.size + kernel.size)) + preparation.folding(kernel.size)
+    end
+
+    def moved_size
+      buffers.real_axis && buffers.real_axis != signal.ndim - 1 ? 3 * signal.size : 0
+    end
+  end
+
+  private_constant :FftEstimator
+end

data/lib/convolver/fft_limits.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'convolver/buffer_limits'
+
+# Internal allocation and arithmetic checks for the PocketFFT paths.
+module Convolver
+  # Only FFT representability failures permit automatic direct fallback.
+  # @private
+  class FftUnavailable < RangeError; end
+
+  # Bounds PocketFFT buffers and signed arithmetic without constructing plans.
+  # @private
+  class FftLimits
+    def initialize(buffers = BufferLimits::NATIVE)
+      @buffers = buffers
+    end
+
+    def validate!(shape, real_axis:)
+      total = buffers.product!(shape, 'FFT size', error: FftUnavailable)
+      validate_buffers!(shape, total, real_axis)
+      # The wrapper casts total to int before dividing it by the axis length.
+      integer!(total, buffers.int_max, 'FFT total size')
+      # Real forward computes int z_step = (z / 2 + 1) * 2.
+      integer!(shape[real_axis], buffers.int_max - 2, 'FFT real stride') if real_axis
+      validate_axes!(shape)
+    end
+
+    private
+
+    attr_reader :buffers
+
+    def validate_axes!(shape)
+      # FFTPACK twiddle counts are <= 2n complex / 3n real. Bluestein m < 4n,
+      # so each variable allocation is <= 128n bytes, including inner twiddles.
+      # The 16n int bound also protects signed intermediates at the inner m.
+      shape.each do |length|
+        integer!(length, buffers.int_max / 16, 'FFT axis arithmetic')
+        buffer!(length, 128, 'FFT axis work buffer')
+      end
+    end
+
+    def validate_buffers!(shape, total, real_axis)
+      buffer!(total, 8, 'FFT spatial buffer')
+      return buffer!(total, 16, 'FFT complex buffer') unless real_axis
+
+      spectrum = total / shape[real_axis] * ((shape[real_axis] / 2) + 1)
+      buffer!(spectrum, 16, 'FFT spectrum buffer')
+      buffer!(total, 16, 'FFT inverse staging buffer')
+      buffer!(total, 8, 'FFT inverse output buffer')
+    end
+
+    def buffer!(count, width, description)
+      buffers.buffer!(count, width, description, error: FftUnavailable)
+    end
+
+    def integer!(value, maximum, description)
+      return if value <= maximum
+
+      raise FftUnavailable, "#{description} exceeds native integer limit"
+    end
+  end
+
+  private_constant :FftUnavailable, :FftLimits
+end

data/lib/convolver/linear_fft_operation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Calculates a valid linear operation through real PocketFFT transforms.
+  # @private
+  class LinearFftOperation
+    def initialize(operation, signal, kernel, plan)
+      @dtype = plan.dtype
+      @operation = operation
+      @signal = signal
+      @kernel = kernel
+      @transform_shape = plan.fft_buffers.transform_shape
+    end
+
+    def call
+      signal_padded = zero_padded(signal)
+      kernel_padded = zero_padded(kernel)
+      full_result = real_spectrum_product(signal_padded, kernel_padded)
+      cropped = full_result[*valid_ranges]
+      dtype == Numo::DFloat ? cropped.dup : dtype.cast(cropped)
+    end
+
+    private
+
+    attr_reader :operation, :signal, :kernel, :transform_shape, :dtype
+
+    def zero_padded(value)
+      Numo::DFloat.zeros(*transform_shape).tap do |padded|
+        padded[*value.shape.map { |size| 0...size }] = value
+      end
+    end
+
+    def real_spectrum_product(signal_value, kernel_value)
+      signal_spectrum = Numo::Pocketfft.rfftn(signal_value)
+      kernel_spectrum = Numo::Pocketfft.rfftn(kernel_value)
+      kernel_spectrum.inplace.conj if operation == :correlation
+      Numo::Pocketfft.irfftn(signal_spectrum.inplace * kernel_spectrum)
+    end
+
+    def valid_ranges
+      signal.shape.zip(kernel.shape).map do |signal_size, kernel_size|
+        if operation == :correlation
+          0...(signal_size - kernel_size + 1)
+        else
+          (kernel_size - 1)...signal_size
+        end
+      end
+    end
+  end
+
+  private_constant :LinearFftOperation
+end

data/lib/convolver/operation_dtype.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Resolves public precision without allocating operand copies.
+  # @private
+  class OperationDtype
+    SINGLE_INPUTS = [Numo::SFloat, Numo::Int8, Numo::UInt8, Numo::Int16, Numo::UInt16].freeze
+    DOUBLE_INPUTS = [Numo::DFloat, Numo::Int32, Numo::UInt32, Numo::Int64, Numo::UInt64].freeze
+    INPUTS = (SINGLE_INPUTS + DOUBLE_INPUTS).freeze
+    OUTPUTS = [Numo::SFloat, Numo::DFloat].freeze
+
+    def self.resolve(signal, kernel, dtype)
+      validate_inputs!(signal, kernel)
+      validate_dtype!(dtype)
+      types = [signal.class, kernel.class]
+      dtype || (types.any? { |type| DOUBLE_INPUTS.include?(type) } ? Numo::DFloat : Numo::SFloat)
+    end
+
+    def self.validate_inputs!(signal, kernel)
+      unless signal.is_a?(Numo::NArray) && kernel.is_a?(Numo::NArray)
+        raise ArgumentError, 'signal and kernel must be Numo::NArray values'
+      end
+
+      return if [signal.class, kernel.class].all? { |type| INPUTS.include?(type) }
+
+      raise ArgumentError, 'unsupported signal or kernel dtype'
+    end
+
+    def self.validate_dtype!(dtype)
+      return if dtype.nil? || OUTPUTS.include?(dtype)
+
+      raise ArgumentError, 'dtype must be Numo::SFloat, Numo::DFloat, or nil'
+    end
+
+    def self.cast_fill(value, dtype)
+      # A scalar IEEE float conversion, without allocating a Numo buffer before preflight.
+      dtype == Numo::SFloat ? [value].pack('f').unpack1('f') : value
+    end
+  end
+
+  private_constant :OperationDtype
+end

data/lib/convolver/operation_execution.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Convolver
+  # Coordinates validation, implementation selection, and one operation family.
+  # @private
+  class OperationExecution
+    DIRECT_OPERATION_COST = { 1 => 3.8e-10, 2 => 5.9e-10, 3 => 4.5e-10 }.freeze
+    DOUBLE_OPERATION_COST = { 1 => 3.9e-10, 2 => 6.0e-10, 3 => 4.6e-10 }.freeze
+    LARGE_KERNEL_COST = 6.5e-10
+    FFT_SPEEDUP_MARGIN = 0.8
+    CALIBRATED_FFT_SPEEDUP_MARGIN = 0.9
+
+    def initialize(operation, signal, kernel, mode:, boundary:, fill_value:, origin:, dtype:)
+      @operation = operation
+      @signal = signal
+      @kernel = kernel
+      @mode = mode
+      @boundary = boundary
+      @fill_value = fill_value
+      @origin = origin
+      @dtype = dtype
+    end
+
+    def automatic
+      return basic if plan.result_shape.empty?
+
+      threshold = fft_margin * basic_time
+      return basic if FftCost.lower_bound(plan, kernel.shape, threshold:) >= threshold
+      return fft if automatic_fft_time < threshold
+
+      basic
+    end
+
+    def basic
+      plan.validate_basic!
+      prepared_signal, prepared_kernel = prepared_inputs
+      extended_signal = plan.extend_signal(prepared_signal)
+      return Convolver.send(:correlate_basic_valid, extended_signal, prepared_kernel) if operation == :correlation
+
+      Convolver.send(:convolve_basic_valid, extended_signal, prepared_kernel)
+    end
+
+    def fft
+      plan.fft_buffers
+      return prepared_inputs.reduce(:*) if signal.ndim.zero?
+
+      fft_operation.call
+    end
+
+    def fft_time
+      FftEstimator.new(operation, signal, kernel, plan).call
+    end
+
+    def basic_time
+      plan.validate_basic!
+      calculation_cost + preparation_cost
+    end
+
+    private
+
+    attr_reader :operation, :signal, :kernel, :mode, :boundary, :fill_value, :origin, :dtype
+
+    def plan
+      @plan ||= OperationPlan.new(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:, dtype:)
+    end
+
+    def prepared_inputs
+      @prepared_inputs ||= [plan.dtype.cast(signal), plan.dtype.cast(kernel)]
+    end
+
+    def fft_operation
+      prepared_signal, prepared_kernel = prepared_inputs
+      return CircularFftOperation.new(operation, prepared_signal, prepared_kernel, plan) if plan.wrap?
+
+      LinearFftOperation.new(operation, plan.extend_signal(prepared_signal), prepared_kernel, plan)
+    end
+
+    def automatic_fft_time
+      fft_time
+    rescue FftUnavailable
+      Float::INFINITY
+    end
+
+    def preparation_cost
+      costs = PreparationCost.new(plan)
+      costs.conversion + costs.extension
+    end
+
+    def direct_operation_cost
+      return LARGE_KERNEL_COST if kernel.size > 64 && signal.ndim != 2
+
+      costs = plan.dtype == Numo::DFloat ? DOUBLE_OPERATION_COST : DIRECT_OPERATION_COST
+      costs.fetch(signal.ndim, costs.values.last)
+    end
+
+    def calculation_cost
+      return calibrated_calculation_cost if plan.cost_profile
+
+      direct_operation_cost * plan.result_size * kernel.size
+    end
+
+    def calibrated_calculation_cost
+      fixed, short, long = plan.cost_profile.fetch(:direct).fetch(plan.dtype == Numo::DFloat ? 1 : 0)
+      fixed + (kernel_work(short, long) * plan.result_size)
+    end
+
+    def kernel_work(short, long)
+      size = kernel.size
+      (short * [size, 64].min) + (long * [size - 64, 0].max)
+    end
+
+    def fft_margin
+      plan.cost_profile ? CALIBRATED_FFT_SPEEDUP_MARGIN : FFT_SPEEDUP_MARGIN
+    end
+  end
+
+  private_constant :OperationExecution
+end

data/lib/convolver/operation_options.rb

@@ -1,39 +1,42 @@
 # frozen_string_literal: true
 
 module Convolver
-  # Validates and normalizes the options for a correlation operation.
+  # Validates and normalizes one convolution or correlation operation.
+  # @private
   class OperationOptions
+    OPERATIONS = %i[convolution correlation].freeze
     MODES = %i[valid same full].freeze
     BOUNDARIES = %i[constant nearest reflect mirror wrap].freeze
 
-    attr_reader :mode, :boundary, :fill_value, :origins, :anchors
+    attr_reader :operation, :mode, :boundary, :fill_value, :origins, :anchors, :dtype
 
-    def initialize(signal, kernel, mode:, boundary:, fill_value:, origin:)
+    def initialize(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:, dtype:)
+      @dtype = OperationDtype.resolve(signal, kernel, dtype)
       validate_inputs!(signal, kernel)
-      validate_vocabulary!(mode, boundary)
-      assign_options(signal, kernel, mode:, boundary:, fill_value:, origin:)
+      validate_vocabulary!(operation, mode, boundary)
+      assign_options(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
       validate_combinations!(signal.shape, kernel.shape)
+      @fill_value = OperationDtype.cast_fill(@fill_value, @dtype)
     end
 
     private
 
     def validate_inputs!(signal, kernel)
-      unless signal.is_a?(Numo::NArray) && kernel.is_a?(Numo::NArray)
-        raise ArgumentError, 'signal and kernel must be Numo::NArray values'
-      end
       raise ArgumentError, 'signal and kernel must not be empty' if signal.empty? || kernel.empty?
       raise ArgumentError, 'signal and kernel must have equal rank' unless signal.ndim == kernel.ndim
       raise ArgumentError, "maximum supported rank is #{MAX_RANK}" if signal.ndim > MAX_RANK
     end
 
-    def validate_vocabulary!(mode, boundary)
+    def validate_vocabulary!(operation, mode, boundary)
+      raise ArgumentError, "operation must be one of #{OPERATIONS.inspect}" unless OPERATIONS.include?(operation)
       raise ArgumentError, "mode must be one of #{MODES.inspect}" unless MODES.include?(mode)
       return if BOUNDARIES.include?(boundary)
 
       raise ArgumentError, "boundary must be one of #{BOUNDARIES.inspect}"
     end
 
-    def assign_options(signal, kernel, mode:, boundary:, fill_value:, origin:)
+    def assign_options(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:)
+      @operation = operation
       @mode = mode
       @boundary = boundary
       @fill_value_given = !fill_value.equal?(UNSPECIFIED_FILL)

data/lib/convolver/operation_plan.rb

@@ -1,28 +1,41 @@
 # frozen_string_literal: true
 
 require 'forwardable'
+require 'convolver/cost_profiles'
+require 'convolver/operation_dtype'
 require 'convolver/operation_options'
 require 'convolver/operation_shapes'
 require 'convolver/signal_extension'
+require 'convolver/fft_buffer_plan'
 
 # Internal planning and extension support for Convolver's public operations.
 module Convolver
   # Distinguishes an omitted fill_value keyword from an explicitly supplied
   # value. This lets non-constant boundaries reject even an explicit zero.
+  # @private
   UNSPECIFIED_FILL = Object.new.freeze
 
-  # Validated dimensions and boundary-extension details for one correlation.
+  # Validated dimensions and boundary-extension details for one operation.
+  # @private
   class OperationPlan
     extend Forwardable
 
-    def_delegators :options, :mode, :boundary, :fill_value, :origins, :anchors
+    def_delegators :options, :operation, :mode, :boundary, :fill_value, :origins, :anchors, :dtype
     def_delegators :shapes, :padding_before, :padding_after, :result_shape,
                    :extended_shape, :result_size, :extended_size, :linear_fft_shape,
-                   :linear_fft_size
+                   :linear_fft_size, :linear_spectrum_size
 
-    def initialize(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      @options = OperationOptions.new(signal, kernel, mode:, boundary:, fill_value:, origin:)
-      @shapes = OperationShapes.new(signal.shape, kernel.shape, mode:, anchors: options.anchors)
+    attr_reader :conversion_size, :cost_profile
+
+    def initialize(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:, dtype: nil)
+      @options = OperationOptions.new(signal, kernel, operation:, mode:, boundary:, fill_value:, origin:, dtype:)
+      @conversion_size = input_conversion_size(signal, kernel)
+      @signal_shape = signal.shape.freeze
+      @kernel_shape = kernel.shape.freeze
+      @cost_profile = CostProfiles.for_rank(@signal_shape.length)
+      @shapes = OperationShapes.new(
+        signal.shape, kernel.shape, operation:, mode:, anchors: options.anchors
+      )
     end
 
     def valid?
@@ -39,9 +52,24 @@ module Convolver
       SignalExtension.new(shapes, boundary:, fill_value:).call(signal)
     end
 
+    def validate_basic!
+      return if @basic_validated
+
+      BufferPreparation.new(self, @signal_shape, @kernel_shape).basic!
+      @basic_validated = true
+    end
+
+    def fft_buffers
+      @fft_buffers ||= FftBufferPlan.new(self, @signal_shape, @kernel_shape)
+    end
+
     private
 
     attr_reader :options, :shapes
+
+    def input_conversion_size(signal, kernel)
+      [signal, kernel].sum { |input| input.instance_of?(dtype) ? 0 : input.size }
+    end
   end
 
   private_constant :OperationPlan, :UNSPECIFIED_FILL