FFTW3-Ruby

Ruby FFI bindings for FFTW3 (Fastest Fourier Transform in the West).

The gem exposes the FFTW planning and execution APIs for complex DFT, real-to-complex and complex-to-real transforms, real-to-real transforms, the advanced "many" interface, guru and guru64 planners, wisdom import/export, thread control, and runtime metadata.

Requirements

Ruby 3.1+
FFTW 3.3.x shared libraries installed on the system

Installing FFTW3

Ubuntu / Debian:

sudo apt-get install libfftw3-dev

macOS (Homebrew):

brew install fftw

Installation

Add the gem to your Gemfile:

gem "fftw3-ruby"

Then install dependencies:

bundle install

Precision Support

Runtime precision support depends on which FFTW libraries are installed.

require "fftw3"

FFTW3.available_precisions
FFTW3.double_available?
FFTW3.float_available?
FFTW3.long_double_available?
FFTW3.quad_available?

Notes:

Plan creation is available for any precision whose FFTW library can be loaded.
FFTW3::AlignedMemory#read and #write currently support :double, :float, and :long_double.
:quad library availability can be detected with FFTW3.quad_available?, but high-level buffer read/write helpers are not currently provided for quad buffers.

Core Types

`FFTW3::AlignedMemory`

Aligned buffers allocated with FFTW's allocator.

require "fftw3"

input = FFTW3::AlignedMemory.new(8, type: :complex, precision: :double)
input.write(Array.new(8) { |i| Complex(i, -i) })

input.pointer
input.read
input.free!

Options:

type: accepts :complex or :real
precision: accepts :double, :float, :long_double, or :quad

`FFTW3::Plan`

Factory methods return FFTW3::Plan instances. A plan can be executed in-place with the buffers it was created with, or with compatible alternate buffers via the new-array execute helpers.

`FFTW3::Threads`

Wrapper around FFTW thread initialization, planner thread count, optional planner locking, and the runtime thread callback hook.

`FFTW3::Wisdom`

Import and export FFTW wisdom through strings, files, and IO callbacks.

`FFTW3::Utils`

Small wrappers for FFTW global utility functions such as cleanup, set_timelimit, and alignment_of.

Quick Start

Basic 1D Complex DFT

require "fftw3"

n = 8
input = FFTW3::AlignedMemory.new(n, type: :complex, precision: :double)
output = FFTW3::AlignedMemory.new(n, type: :complex, precision: :double)

data = (0...n).map { |i| Complex(Math.sin(2 * Math::PI * i / n), 0.0) }
input.write(data)

plan = FFTW3::Plan.dft_1d(
  n,
  input,
  output,
  direction: :forward,
  flags: [:estimate]
)

plan.execute
result = output.read

puts result.map { |c| "(%.4f, %.4f)" % [c.real, c.imaginary] }

plan.destroy!
input.free!
output.free!

Real-to-Complex

require "fftw3"

n = 16
input = FFTW3::AlignedMemory.new(n, type: :real)
output = FFTW3::AlignedMemory.new((n / 2) + 1, type: :complex)

input.write(n.times.map { |i| Math.sin(2 * Math::PI * i / n) })

plan = FFTW3::Plan.dft_r2c_1d(n, input, output)
plan.execute

result = output.read

New-array Execute

require "fftw3"

n = 8
input_a = FFTW3::AlignedMemory.new(n, type: :complex)
output_a = FFTW3::AlignedMemory.new(n, type: :complex)
input_b = FFTW3::AlignedMemory.new(n, type: :complex)
output_b = FFTW3::AlignedMemory.new(n, type: :complex)

input_a.write(Array.new(n) { |i| Complex(i, 0.0) })
input_b.write(Array.new(n) { |i| Complex(0.0, i) })

plan = FFTW3::Plan.dft_1d(n, input_a, output_a, direction: :forward)

# Reuse the same plan with different buffers of the same shape.
plan.execute_dft(input_b, output_b)

plan.destroy!
input_a.free!
output_a.free!
input_b.free!
output_b.free!

Threading

Planner Thread Count

require "fftw3"

n = 1024
input = FFTW3::AlignedMemory.new(n, type: :complex)
output = FFTW3::AlignedMemory.new(n, type: :complex)

FFTW3::Threads.init
FFTW3::Threads.plan_with_nthreads(4)

plan = FFTW3::Plan.dft_1d(n, input, output, direction: :forward, flags: [:measure])
plan.execute

FFTW3::Threads.planner_nthreads
plan.destroy!
input.free!
output.free!
FFTW3::Threads.cleanup

Planner Locking

require "fftw3"

FFTW3::Threads.init
FFTW3::Threads.make_planner_thread_safe
FFTW3::Threads.cleanup

make_planner_thread_safe returns nil when the linked FFTW build does not expose that function.

Custom Thread Backend Callback

threads_set_callback is optional in FFTW. Check support before using it, and set it before creating plans.

require "fftw3"

if FFTW3::Threads.set_callback_supported?
  marker = FFI::MemoryPointer.new(:int)
  marker.write_int(7)

  FFTW3::Threads.set_callback(data: marker) do |work, jobdata, elsize, njobs, data_ptr|
    njobs.times do |index|
      work.call(jobdata + (elsize * index))
    end
  end

  # Reset to the default FFTW backend.
  FFTW3::Threads.set_callback(nil)
end

Wisdom

String and File APIs

require "fftw3"

wisdom = FFTW3::Wisdom.export_to_string
FFTW3::Wisdom.import_from_string(wisdom)

FFTW3::Wisdom.export_to_file("wisdom.fftw")
FFTW3::Wisdom.import_from_file("wisdom.fftw")

IO Callback APIs

require "fftw3"
require "stringio"

io = StringIO.new
FFTW3::Wisdom.export_to_io(io)
FFTW3::Wisdom.import_from_io(StringIO.new(io.string))

System Wisdom

require "fftw3"

FFTW3::Wisdom.import_system
FFTW3::Wisdom.forget!

Runtime Metadata and Utilities

require "fftw3"

input = FFTW3::AlignedMemory.new(8, type: :complex)

FFTW3.version
FFTW3.compiler
FFTW3.codelet_optimizations

FFTW3::Utils.set_timelimit(0.25)
FFTW3::Utils.alignment_of(input.pointer)
FFTW3::Utils.cleanup
input.free!

API Reference

Top-level `FFTW3`

Method	Description
`available_precisions`	Returns the precisions whose FFTW libraries can be loaded
`double_available?` / `float_available?` / `long_double_available?` / `quad_available?`	Per-precision availability checks
`version`	Linked FFTW version string
`compiler`	Linked FFTW compiler string
`codelet_optimizations`	Linked FFTW codelet optimization string

`FFTW3::Plan` Factory Methods

Method group	Methods
Complex DFT	`dft_1d`, `dft_2d`, `dft_3d`, `dft`
Real-to-complex	`dft_r2c_1d`, `dft_r2c_2d`, `dft_r2c_3d`, `dft_r2c`
Complex-to-real	`dft_c2r_1d`, `dft_c2r_2d`, `dft_c2r_3d`, `dft_c2r`
Real-to-real	`r2r_1d`, `r2r_2d`, `r2r_3d`, `r2r`
Advanced / batched	`many_dft`, `many_dft_r2c`, `many_dft_c2r`, `many_r2r`
Guru	`guru_dft`, `guru_split_dft`, `guru_dft_r2c`, `guru_split_dft_r2c`, `guru_dft_c2r`, `guru_split_dft_c2r`, `guru_r2r`
Guru64	`guru64_dft`, `guru64_split_dft`, `guru64_dft_r2c`, `guru64_split_dft_r2c`, `guru64_dft_c2r`, `guru64_split_dft_c2r`, `guru64_r2r`

Notes:

dft_* and many_dft use direction:.
guru_dft and guru64_dft use sign:.
Guru and guru64 dimension arrays use hashes shaped like { n:, is:, os: }.

`FFTW3::Plan` Instance Methods

Method	Description
`execute`	Execute with the buffers used to create the plan
`execute_dft`	New-array execute for complex DFT
`execute_dft_r2c`	New-array execute for real-to-complex DFT
`execute_dft_c2r`	New-array execute for complex-to-real DFT
`execute_r2r`	New-array execute for real-to-real transforms
`execute_split_dft`	New-array execute for split-complex guru DFT
`execute_split_dft_r2c`	New-array execute for split real-to-complex guru DFT
`execute_split_dft_c2r`	New-array execute for split complex-to-real guru DFT
`flops`	Returns `{ add:, mul:, fma: }`
`cost`	FFTW plan cost
`estimate_cost`	FFTW estimated plan cost
`to_s` / `description`	String representation of the plan
`print(io = $stdout)`	Write the plan description to an IO object
`destroy!`	Destroy the underlying FFTW plan

`FFTW3::Threads`

Method	Description
`init`	Initialize FFTW thread support
`plan_with_nthreads(n)`	Set planner and execution thread count
`cleanup`	Release FFTW thread state
`planner_nthreads`	Read configured thread count when supported
`make_planner_thread_safe`	Enable FFTW's optional planner lock when supported
`set_callback_supported?`	Check whether `threads_set_callback` is available
`set_callback(callback = nil, data: nil, &block)`	Install or clear FFTW's runtime threading callback

`FFTW3::Wisdom`

Method	Description
`export_to_string` / `import_from_string`	Wisdom through Ruby strings
`export_to_file` / `import_from_file`	Wisdom through filesystem paths
`export_to_io` / `import_from_io`	Wisdom through Ruby IO callbacks
`import_system`	Best-effort import from the system wisdom store
`forget!`	Clear loaded wisdom

`FFTW3::Utils`

Method	Description
`cleanup`	Call FFTW global cleanup
`set_timelimit(seconds)`	Set the FFTW planner time limit
`alignment_of(pointer)`	Query FFTW's alignment classification for a pointer

Constants

Planner flags:

FFTW3::ESTIMATE
FFTW3::MEASURE
FFTW3::PATIENT
FFTW3::EXHAUSTIVE
FFTW3::PRESERVE_INPUT
FFTW3::DESTROY_INPUT
FFTW3::WISDOM_ONLY
Additional exported flags such as FFTW3::ESTIMATE_PATIENT, FFTW3::ALLOW_PRUNING, and FFTW3::NO_SIMD

Direction constants:

FFTW3::FORWARD
FFTW3::BACKWARD
:forward and :backward are also accepted where direction symbols are supported

R2R kinds:

FFTW3::R2HC
FFTW3::HC2R
FFTW3::DHT
FFTW3::REDFT00, REDFT01, REDFT10, REDFT11
FFTW3::RODFT00, RODFT01, RODFT10, RODFT11

Development

bundle install
bundle exec rake spec

License

The gem is available as open source under the terms of the MIT License.

FFTW3 itself is licensed under GPLv2+. Using this gem requires an installed FFTW3 library.

FFTW3-Ruby

Requirements

Installing FFTW3

Installation

Precision Support

Core Types

FFTW3::AlignedMemory

FFTW3::Plan

FFTW3::Threads

FFTW3::Wisdom

FFTW3::Utils

Quick Start

Basic 1D Complex DFT

Real-to-Complex

New-array Execute

Threading

Planner Thread Count

Planner Locking

Custom Thread Backend Callback

Wisdom

String and File APIs

IO Callback APIs

System Wisdom

Runtime Metadata and Utilities

API Reference

Top-level FFTW3

FFTW3::Plan Factory Methods

FFTW3::Plan Instance Methods

FFTW3::Threads

FFTW3::Wisdom

FFTW3::Utils

Constants

Development

License

`FFTW3::AlignedMemory`

`FFTW3::Plan`

`FFTW3::Threads`

`FFTW3::Wisdom`

`FFTW3::Utils`

Top-level `FFTW3`

`FFTW3::Plan` Factory Methods

`FFTW3::Plan` Instance Methods

`FFTW3::Threads`

`FFTW3::Wisdom`

`FFTW3::Utils`