Update docs

daniellga · Jun 18, 2024 · 52a3f11 · 52a3f11
1 parent b755cdd
commit 52a3f11
Show file tree

Hide file tree

Showing 23 changed files with 2,759 additions and 58 deletions.
diff --git a/_docs/contents/hfftplanner.qmd b/_docs/contents/hfftplanner.qmd
@@ -0,0 +1,158 @@
+---
+title: HFftPlanner
+---
+
+## new
+
+`new(dtype: HDataType) -> HFftPlanner` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L65) </span> \
+
+Creates a new `HFftPlanner` instance. \
+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
+
+* `dtype` \
+A complex `HDataType` to indicate the dtype that the `HFftPlanner` will be working with. \
+
+#### Returns
+
+An `HFftPlanner`. \
+Will return an error if dtype is of a float type. \
+
+#### Examples
+
+```r
+library(harmonium)
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+fft_planner = HFftPlanner$new(harray$dtype())
+```
+
+_________
+
+## fft
+
+`fft(harray: HArray)` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L115) </span> \
+
+Computes the fast fourier transform of a complex `HArray`. \
+The operation is done in-place. \
+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 `HFftPlanner`'s dtype. \
+* The `HArray`'s `ndim` is greater than 2. \
+
+#### Examples
+
+```r
+library(harmonium)
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+fft_planner = HFftPlanner$new(harray$dtype())
+fft_planner$fft(harray)
+```
+
+_________
+
+## ifft
+
+`ifft(harray: HArray)` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L158) </span> \
+
+Computes the inverse fast fourier transform of a complex `HArray`. \
+The operation is done in-place. \
+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`. \
+
+#### Arguments
+
+* `harray` \
+A complex `HArray`. \
+
+#### Returns
+
+Will return an error if:
+* The `HArray`'s dtype is incompatible with the `HFftPlanner`'s dtype. \
+* The `HArray`'s `ndim` is greater than 2. \
+
+#### Examples
+
+```r
+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)
+fft_planner = HFftPlanner$new(harray$dtype())
+fft_planner$ifft(harray)
+```
+
+_________
+
+## dtype
+
+`dtype() -> HDataType` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L185) </span> \
+
+Gets the `HFftPlanner`'s dtype.
+
+#### Returns
+
+An `HDataType`.
+
+#### Examples
+
+```r
+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)
+fft_planner = HFftPlanner$new(harray$dtype())
+fft_planner$dtype()
+```
+
+_________
+
+## print
+
+`print()` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L212) </span> \
+
+Print the `HFftPlanner`. \
+Differently from R's normal behaviour, `print` doesn't return the value invisibly. \
+
+#### Examples
+
+```r
+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)
+fft_planner = HFftPlanner$new(harray$dtype())
+fft_planner$print()
+
+# or similarly:
+print(fft_planner)
+```
+
+_________
diff --git a/_docs/contents/hrealfftplanner.qmd b/_docs/contents/hrealfftplanner.qmd
@@ -0,0 +1,169 @@
+---
+title: HRealFftPlanner
+---
+
+## new
+
+`new(dtype: HDataType) -> HRealFftPlanner` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L253) </span> \
+
+Creates a new `HRealFftPlanner` instance. \
+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
+
+* `dtype` \
+A float `HDataType` to indicate the dtype that the `HFftPlanner` will be working with. \
+
+#### Returns
+
+An `HRealFftPlanner`. \
+Will return an error if dtype is of a complex type. \
+
+#### Examples
+
+```r
+library(harmonium)
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+real_fft_planner = HRealFftPlanner$new(harray$dtype())
+```
+
+_________
+
+## rfft
+
+`rfft(harray: HArray)` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L305) </span> \
+
+Computes the fast fourier transform of a float `HArray`. Transforms a real signal of length `N` to a complex-valued spectrum of length `N/2+1` (with `N/2` rounded down). \
+The operation is not done in-place, although the same external pointer is used to store the new HArray. \
+The FFT of a real signal is Hermitian-symmetric, X[i] = conj(X[-i]) so the output contains only the positive frequencies
+below the Nyquist frequency. \
+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 float `HArray`. \
+
+#### Returns
+
+Will return an error if:
+* The `HArray`'s dtype is incompatible with the `HFftPlanner`'s dtype. \
+* The `HArray`'s `ndim` is greater than 2. \
+
+#### Examples
+
+```r
+library(harmonium)
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+real_fft_planner = HRealFftPlanner$new(harray$dtype())
+real_fft_planner$rfft(harray)
+```
+
+_________
+
+## irfft
+
+`irfft(harray: HArray, length: integer)` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L357) </span> \
+
+Computes the inverse fast fourier transform of a complex `HArray`. 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 not done in-place, although the same external pointer is used to store the new HArray. \
+The FFT of a real signal is Hermitian-symmetric, X[i] = conj(X[-i]) so the output contains only the positive frequencies
+below the Nyquist frequency. \
+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`. \
+
+#### Arguments
+
+* `harray` \
+A complex `HArray`. The `HArray`'s dtype must be the complex equivalent of the `HRealFftPlanner`'s dtype. For example if `HRealFftPlanner` dtype is `Float64`,
+the `HArray`'s dtype must be `Complex64`. \
+* `length` \
+An integer. The output length of the signal. Since the spectrum is `N/2+1`, the length can be `N` and `N+1`, if `N` is even, or can be `N` and `N-1` if `N` is odd.  \
+
+#### Returns
+
+Will return an error if:
+* The `HArray`'s dtype is incompatible with the `HFftPlanner`'s dtype. \
+* The `HArray`'s `ndim` is greater than 2. \
+* The `length` argument is not compatible with the spectrum length. \
+
+#### Examples
+
+```r
+library(harmonium)
+r = as.double(sample(100, 4, replace = TRUE))
+i = as.double(sample(100, 3, replace = TRUE))
+arr = array(complex(real=r, imaginary=c(0,i)), c(4,1))
+dtype = HDataType$Complex32
+harray = HArray$new_from_values(arr, dtype)
+real_fft_planner = HRealFftPlanner$new(HDataType$Float32)
+real_fft_planner$irfft(harray, 7L)
+```
+
+_________
+
+## dtype
+
+`dtype() -> HDataType` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L388) </span> \
+
+Gets the `HRealFftPlanner`'s dtype.
+
+#### Returns
+
+An `HDataType`.
+
+#### Examples
+
+```r
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+real_fft_planner = HRealFftPlanner$new(harray$dtype())
+real_fft_planner$dtype()
+```
+
+_________
+
+## print
+
+`print()` <span style="float: right;"> [source](https://github.com/daniellga/harmonium/tree/master/r-harmonium/src/rust/src/hfft.rs#L415) </span> \
+
+Print the `HRealFftPlanner`. \
+Differently from R's normal behaviour, `print` doesn't return the value invisibly. \
+
+#### Examples
+
+```r
+arr = array(c(1,2,3,4,5,6,7,8,9,10,11,12), c(3,4))
+dtype = HDataType$Float32
+harray = HArray$new_from_values(arr, dtype)
+real_fft_planner = HRealFftPlanner$new(harray$dtype())
+real_fft_planner$print()
+
+# or similarly:
+print(real_fft_planner)
+```
+
+_________
diff --git a/docs/about.html b/docs/about.html
@@ -158,6 +158,12 @@
   <a href="./contents/hfft.html" class="sidebar-item-text sidebar-link">
  <span class="menu-text">HFft</span></a>
   </div>
+</li>
+          <li class="sidebar-item">
+  <div class="sidebar-item-container"> 
+  <a href="./contents/hfftplanner.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text">HFftPlanner</span></a>
+  </div>
 </li>
           <li class="sidebar-item">
   <div class="sidebar-item-container"> 
@@ -182,6 +188,12 @@
   <a href="./contents/hpolynomialdegree.html" class="sidebar-item-text sidebar-link">
  <span class="menu-text">HPolynomialDegree</span></a>
   </div>
+</li>
+          <li class="sidebar-item">
+  <div class="sidebar-item-container"> 
+  <a href="./contents/hrealfftplanner.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text">HRealFftPlanner</span></a>
+  </div>
 </li>
           <li class="sidebar-item">
   <div class="sidebar-item-container"> 

diff --git a/docs/contents/harray.html b/docs/contents/harray.html
@@ -192,6 +192,12 @@
   <a href="../contents/hfft.html" class="sidebar-item-text sidebar-link">
  <span class="menu-text">HFft</span></a>
   </div>
+</li>
+          <li class="sidebar-item">
+  <div class="sidebar-item-container"> 
+  <a href="../contents/hfftplanner.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text">HFftPlanner</span></a>
+  </div>
 </li>
           <li class="sidebar-item">
   <div class="sidebar-item-container"> 
@@ -216,6 +222,12 @@
   <a href="../contents/hpolynomialdegree.html" class="sidebar-item-text sidebar-link">
  <span class="menu-text">HPolynomialDegree</span></a>
   </div>
+</li>
+          <li class="sidebar-item">
+  <div class="sidebar-item-container"> 
+  <a href="../contents/hrealfftplanner.html" class="sidebar-item-text sidebar-link">
+ <span class="menu-text">HRealFftPlanner</span></a>
+  </div>
 </li>
           <li class="sidebar-item">
   <div class="sidebar-item-container">