fftw3-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50798c6924b8398dfcd52f1dfe1ee43531fa523b3e15ae4d72ab06c07d90121d
+  data.tar.gz: a7d75f44a6066629ea627b166137e1043871abb65479687685777d18ab3e58bc
+SHA512:
+  metadata.gz: 98ecc76de7b79206228b602070453d7b8db76c523e55ab633a74028c403f079ab79ec54d1128c8e71b236c15cb09a0233b91d8afcdd790dfb1b2a7d8373bf66f
+  data.tar.gz: 8526e3eeec9352cccb66149fd57156903c510e6bbd7e372320c711d16e40de99bb81a17fc199cb8afae8103ed654e311a5f06628fe4101fb6c6a1e8e56363f89

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,399 @@
+# FFTW3-Ruby
+
+Ruby FFI bindings for [FFTW3](http://www.fftw.org/) (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:
+
+```bash
+sudo apt-get install libfftw3-dev
+```
+
+macOS (Homebrew):
+
+```bash
+brew install fftw
+```
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "fftw3-ruby"
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+## Precision Support
+
+Runtime precision support depends on which FFTW libraries are installed.
+
+```ruby
+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.
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+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.
+
+```ruby
+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
+
+```ruby
+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
+
+```ruby
+require "fftw3"
+require "stringio"
+
+io = StringIO.new
+FFTW3::Wisdom.export_to_io(io)
+FFTW3::Wisdom.import_from_io(StringIO.new(io.string))
+```
+
+### System Wisdom
+
+```ruby
+require "fftw3"
+
+FFTW3::Wisdom.import_system
+FFTW3::Wisdom.forget!
+```
+
+## Runtime Metadata and Utilities
+
+```ruby
+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
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+FFTW3 itself is licensed under GPLv2+. Using this gem requires an installed FFTW3 library.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/fftw3/aligned_memory.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module FFTW3
+  class AlignedMemory
+    attr_reader :pointer, :size, :precision, :type
+
+    REAL_SIZES = {
+      double: 8, float: 4, long_double: 16, quad: 16
+    }.freeze
+
+    COMPLEX_SIZES = REAL_SIZES.transform_values { |v| v * 2 }.freeze
+
+    def initialize(count, type: :complex, precision: :double)
+      @precision = precision
+      @type = type
+      @count = count
+
+      sizes = (type == :complex) ? COMPLEX_SIZES : REAL_SIZES
+      @element_size = sizes.fetch(precision)
+      @size = count * @element_size
+
+      ffi = FFTW3::FFI.module_for(precision)
+      pfx = FFTW3::FFI.prefix_for(precision)
+
+      @pointer = case type
+                 when :complex
+                   ffi.send(:"#{pfx}alloc_complex", count)
+                 when :real
+                   ffi.send(:"#{pfx}alloc_real", count)
+                 else
+                   ffi.send(:"#{pfx}malloc", @size)
+                 end
+
+      raise FFTW3::Error::PlanError, "fftw_malloc returned NULL" if @pointer.null?
+
+      @freed_flag = [false]
+      @free_func = ffi.method(:"#{pfx}free")
+      ObjectSpace.define_finalizer(self, self.class.release(@pointer, @free_func, @freed_flag))
+    end
+
+    def write(data)
+      case @type
+      when :real    then write_real(data)
+      when :complex then write_complex(data)
+      end
+    end
+
+    def read
+      case @type
+      when :real    then read_real
+      when :complex then read_complex
+      end
+    end
+
+    def free!
+      return if @freed_flag[0]
+
+      @free_func.call(@pointer)
+      @freed_flag[0] = true
+    end
+
+    private
+
+    def write_real(data)
+      write_numeric_values(data)
+    end
+
+    def read_real
+      read_numeric_values(@count)
+    end
+
+    def write_complex(data)
+      flat = data.flat_map { |c|
+        c.is_a?(Complex) ? [c.real, c.imaginary] : c
+      }
+      write_numeric_values(flat)
+    end
+
+    def read_complex
+      flat = read_numeric_values(@count * 2)
+      flat.each_slice(2).map { |re, im| Complex(re, im) }
+    end
+
+    def write_numeric_values(data)
+      case @precision
+      when :double
+        @pointer.put_array_of_double(0, data)
+      when :float
+        @pointer.put_array_of_float(0, data)
+      when :long_double
+        write_generic_values(data, type: :long_double)
+      else
+        raise_unsupported_precision!(:write)
+      end
+    end
+
+    def read_numeric_values(count)
+      case @precision
+      when :double
+        @pointer.get_array_of_double(0, count)
+      when :float
+        @pointer.get_array_of_float(0, count)
+      when :long_double
+        read_generic_values(count, type: :long_double)
+      else
+        raise_unsupported_precision!(:read)
+      end
+    end
+
+    def write_generic_values(data, type:)
+      value_size = ::FFI.type_size(type)
+      data.each_with_index do |value, index|
+        @pointer.put(type, index * value_size, value)
+      end
+    rescue TypeError
+      raise_unsupported_precision!(:write)
+    end
+
+    def read_generic_values(count, type:)
+      value_size = ::FFI.type_size(type)
+      Array.new(count) do |index|
+        @pointer.get(type, index * value_size)
+      end
+    rescue LoadError, TypeError
+      raise_unsupported_precision!(:read)
+    end
+
+    def raise_unsupported_precision!(action)
+      raise FFTW3::Error::InvalidArgument,
+            "FFI does not support #{action}ing #{@precision} buffers on this platform"
+    end
+
+    def self.release(ptr, free_func, freed_flag)
+      proc {
+        unless freed_flag[0] || ptr.null?
+          free_func.call(ptr)
+          freed_flag[0] = true
+        end
+      }
+    end
+  end
+end

data/lib/fftw3/constants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FFTW3
+  NO_TIMELIMIT    = -1.0
+
+  # Planner flags
+  MEASURE         = 0
+  DESTROY_INPUT   = 1 << 0
+  UNALIGNED       = 1 << 1
+  CONSERVE_MEMORY = 1 << 2
+  EXHAUSTIVE      = 1 << 3
+  PRESERVE_INPUT  = 1 << 4
+  PATIENT         = 1 << 5
+  ESTIMATE        = 1 << 6
+  ESTIMATE_PATIENT = 1 << 7
+  BELIEVE_PCOST    = 1 << 8
+  NO_DFT_R2HC      = 1 << 9
+  NO_NONTHREADED   = 1 << 10
+  NO_BUFFERING     = 1 << 11
+  NO_INDIRECT_OP   = 1 << 12
+  ALLOW_LARGE_GENERIC = 1 << 13
+  NO_RANK_SPLITS      = 1 << 14
+  NO_VRANK_SPLITS     = 1 << 15
+  NO_VRECURSE         = 1 << 16
+  NO_SIMD             = 1 << 17
+  NO_SLOW             = 1 << 18
+  NO_FIXED_RADIX_LARGE_N = 1 << 19
+  ALLOW_PRUNING          = 1 << 20
+  WISDOM_ONLY     = 1 << 21
+
+  # Direction
+  FORWARD  = -1
+  BACKWARD = 1
+
+  # R2R kinds
+  R2HC    = 0
+  HC2R    = 1
+  DHT     = 2
+  REDFT00 = 3
+  REDFT01 = 4
+  REDFT10 = 5
+  REDFT11 = 6
+  RODFT00 = 7
+  RODFT01 = 8
+  RODFT10 = 9
+  RODFT11 = 10
+end

data/lib/fftw3/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FFTW3
+  module Error
+    class PlanError < StandardError; end
+    class LibraryNotFound < StandardError; end
+    class InvalidArgument < StandardError; end
+  end
+end