HFft

An HFft is used to create FFTs. It caches results internally, so when making more than one FFT it is advisable to reuse the same HFft instance.

Methods

new_forward

new_forward(length: integer, dtype: HDataType) -> HFft source

Creates a new HFft instance which will be used to calculate forward FFTs.

If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing setup time (FFT instances created with one planner will never re-use data and buffers with FFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan FFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD FFTs.

Arguments

  • length

An integer denoting the length of the input. For 2D HArray’s, nrows must be provided.

  • dtype

A complex HDataType to indicate the dtype that the HFft will be working with.

Returns

An HFft.

Will return an error if dtype is of a float type.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)

new_inverse

new_inverse(length: integer, dtype: HDataType) -> HFft source

Creates a new HFft instance which will be used to calculate inverse FFTs.

If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing setup time (FFT instances created with one planner will never re-use data and buffers with FFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan FFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD FFTs.

Arguments

  • length

An integer denoting the length of the input. For 2D HArray’s, nrows must be provided.

  • dtype

A complex HDataType to indicate the dtype that the HFft will be working with.

Returns

An HFft.

Will return an error if dtype is of a float type.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_inverse(3L, dtype)

new_real_forward

new_real_forward(length: integer, dtype: HDataType) -> HFft source

Creates a new HFft instance which will be used to calculate real forward FFTs.

If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing setup time (FFT instances created with one planner will never re-use data and buffers with FFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan FFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD FFTs.

Arguments

  • length

An integer denoting the length of the input. For 2D HArray’s, nrows must be provided.

  • dtype

A float HDataType to indicate the dtype that the HFft will be working with.

Returns

An HFft.

Will return an error if dtype is of complex type.

Examples

library(harmonium)
dtype = HDataType$Float32
hfft = HFft$new_real_forward(3L, dtype)

new_real_inverse

new_real_inverse(length: integer, dtype: HDataType) -> HFft source

Creates a new HFft instance which will be used to calculate real inverse FFTs.

If you plan on creating multiple FFT instances, it is recommended to reuse the same planner for all of them. This is because the planner re-uses internal data across FFT instances wherever possible, saving memory and reducing setup time (FFT instances created with one planner will never re-use data and buffers with FFT instances created by a different planner).

In the constructor, the FftPlanner will detect available CPU features. If AVX, SSE, Neon, or WASM SIMD are available, it will set itself up to plan FFTs with the fastest available instruction set. If no SIMD instruction sets are available, the planner will seamlessly fall back to planning non-SIMD FFTs.

Arguments

  • length

An integer denoting the length of the output. For 2D HArray’s, nrows of the output must be provided.

  • dtype

A complex HDataType to indicate the dtype that the HFft will be working with.

Returns

An HFft.

Will return an error if dtype is of float type.

Examples

library(harmonium)
dtype = HDataType$Float32
hfft = HFft$new_real_inverse(3L, dtype)

process

process(harray: HArray) source

Computes the fast fourier transform of an HArray. The FFT computed may be forward or inverse, depending on the HFft created. For a real forward FFT, transforms a real signal of length N to a complex-valued spectrum of length N/2+1 (with N/2 rounded down). For a real inverse FFT, transforms a complex spectrum of length N/2+1 (with N/2 rounded down) to a real-valued signal of length N.

The operation is done in-place for FFT. The operation is done in-place for real FFT, which means the same external pointer will be used to store it. A new HArray is created in this case.

FFT (Fast Fourier Transform) refers to a way the discrete Fourier Transform (DFT) can be calculated efficiently, by using symmetries in the calculated terms. The symmetry is highest when n is a power of 2, and the transform is therefore most efficient for these sizes.

The function does not normalize outputs. Callers must manually normalize the results by scaling each element by 1/sqrt(n). Multiple normalization steps can be merged into one via pairwise multiplication, so when doing a forward FFT followed by an inverse callers can normalize once by scaling each element by 1/n.

Elements in the output are ordered by ascending frequency, with the first element corresponding to frequency 0.

Arguments

  • harray

A complex HArray.

Returns

Will return an error if:

  • The HArray’s dtype is incompatible with the HFft’s dtype.

  • The HArray’s ndim is greater than 2.

Examples

# Forward FFT.
library(harmonium)
arr = array(c(1+1i,2+2i,3+3i,4+4i,5+5i,6+6i), c(3,2))
dtype = HDataType$Complex32
harray = HArray$new_from_values(arr, dtype)
hfft = HFft$new_forward(3L, harray$dtype())
hfft$process(harray)

# Inverse FFT.
arr = array(c(1+1i,2+2i,3+3i,4+4i,5+5i,6+6i), c(3,2))
dtype = HDataType$Complex32
harray = HArray$new_from_values(arr, dtype)
hfft = HFft$new_inverse(3L, harray$dtype())
hfft$process(harray)

dtype

dtype() -> HDataType source

Gets the HFft’s dtype.

Returns

An HDataType.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)
hfft$dtype()

print

print() source

Prints the HFft.

Differently from R’s normal behaviour, print doesn’t return the value invisibly.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)
hfft$print()

# or similarly:
print(hfft)

clone

clone() -> HFft source

Clones the HFft.

Creates a new HFft, with the underlying data pointing to the same place in memory. When HFFT is cloned, thus having more than one reference to the same internal struct, and process is run, it uses the same cached Fft instance, but a new scratch buffer will have to be allocated.

Returns

An HFft.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)
hfft$clone()

is_unique

is_unique() -> bool source

Checks if the object is unique.

Since HFft has a COW (clone-on-write) behaviour, this function is useful to check if a new object will be created or if the change will be done in-place.

Returns

A bool.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)
hfft$is_unique() # TRUE.

hfft2 = hfft$clone()
hfft$is_unique() # FALSE, hfft shares the same inner object with hfft2.

invalidate

invalidate() source

Replaces the inner value of the external pointer, invalidating it. This function is useful to remove one of the shared references of the inner pointer in rust.

Examples

library(harmonium)
dtype = HDataType$Complex32
hfft = HFft$new_forward(3L, dtype)
hfft$invalidate()