Module S.Genarray

Creates a new array, just as Bigarray.Genarray.create does, but guarantees that it is aligned so one gets the better performance from FFTW.

Remark: In order to deserialize such a bigarray, this module must be linked to the program as the deserialization function also aligns the data.

Double precision complex array.

Double precision float array.

Coordinates of elements or dimensions of an ND array (therefore the length of such an array of coordinates must be equal to the number of dimensions of the matrix).

dft dir i o returns a plan for computing the FFT in the direction dir from i to o. i and o must have the same number of (logical) dimensions and may be equal. If i, ofsi and o, ofso are respectively the same, the transform is done in-place. If not, the sub-matrices should not overlap. Raises Fftw3.Sig.Failure if the plan cannot be created.

Note that FFTW computes an unnormalized DFT: computing a forward followed by a backward transform (or vice versa) results in the original array scaled by N, the product of the lofical dimensions Array.fold_left ( * ) 1 ni = Array.fold_left ( * ) 1 no.

• meas controls how much time is dedicated to the creation of the plan. Default: Measure. Beware that, unless ~meas is Estimate, creating a plan requires some trials that will destroy the content of the arrays.

• destroy_input specifies that an out-of-place transform may overwrite its input array. Overwriting input may sometimes allow more efficient algorithms to be employed. Default: false (i.e. perserve the content of the input array) except for c2r and HC2R.

• unaligned specifies that the algorithm may not impose any alignment requirements. You normally do not need this flag unless you want to use the plan with other unaligned arrays (using the guru interface). Default: false meaning that alignment may be used to speed up the computations (when in and out are aligned of course).

Subarrays

Fftw3 allows you to perform the FFT transform on subarrays defined by offset, strides and dimensions. (Only the offset specification is dependent on the layout, the other two are the same regardless of whether the matrix has a C or FORTRAN layout.)

• ni is the array with an entry for each dimension k of i. ni.(k) indicates how many increments inci.(k) we want to consider in the dimension k. Of course, the ni.(k) must be small enough so that the the subarrays fits in i, i.e., for all k, ofsi.(k) + (ni.(k) - 1) abs(inci.(k)) must be < dim i k (c_layout) or <= dim i k (fortran_layout). If ni.(k) = 0, it means that we want the larger dimension ni.(k) that the choice of ofsi.(k) and inci.(k) allow. In this case, ni.(k) will be overwritten with the dimension that was automatically determined. Note that ni.(k) = 1 means that the direction k is to be ignored (i.e. the kth index is constant with value ofsi.(k)).

• ofsi the initial element in the input array. Default: [|0;...;0|] for c_layout and [|1;...;1|] for fortran_layout.

• inci an array of increments for each (physical) dimension of the input array i. inci.(k) can be negative, indicating that the range ofsi.(k) .. ofsi.(k) + (ni.(k) - 1) abs(inc.(k)) is traversed backward. This is the same behavior is as lacaml (LAPACK). If the increment inci.(k) = 0, that means that the dimension k must be ignored (i.e. the index in dimension k is constant with value ofsi.(k)). Default: [|1;...;1|].

• no same as ni but for output. no must denote a transform of the same dimensions as ni i.e., neglecting the dimensions 1, the two matrices must be the same.

• ofso same as ofsi but for output.

• inco same as inci but for output.

For example, if one wants the submatrix indicated by the stars of the following (C layout) matrix:

            a = [[x x x x x x     one sets:  ofs = [|1; 1|]
                  x * x * x x                inc = [|1; 2|]
 	          x * x * x x	             dim = [|2; 2|]
	          x x x x x x ]]

The slice represented by the stars

            a = [[x * x x x
                  x * x x x
                  x * x x x ]]

is defined by ofs = [|0; 1|] and inc = [|1; 0|]

Multiple transforms

FFTW allows to compute several transforms at once by specifying submatrices of i and o. This is more efficient than to create a different plan for each transform. It is your responsability to ensure that the many submatrices do not overlap.

• howmany_n is an array of the (logical) dimensions of the array indexing the many transforms. Default: [| |], i.e. only a single transform is performed. If howmanyi is given but no howmany_n, then the maximum dimensions possible by the dimensions of i (resp. o) are used. A value of 0 for a dimension also means to make it as large as possible.

• howmanyi is a list of vectors [v1;...;vp] generating the lattice of multiple arrays. In other words, if a is an element of (vector) index k in the "first" array, then the same element in the other arrays is at indices k + i₁ * v1 + ... + iₚ * vp. The dimension of each vᵢ must be equal to the number of dimensions of the input array i.

• howmanyo same as howmanyi but for output.

For example, for the two subarrays are identified by * and +

            a = [[x * + * +
                  x x x x x
                  x * + * +
                  x x x x x ]]

one sets: ofsi = [|0; 1|], inci = [|2; 2|] and howmanyi = [ [|0; 1|] ] (or ofso, inco and howmanyo if it is an output array).

r2c i o returns a plan for computing the forward transform from the real array i to the complex array o. Note that the last (for the C layout, or first for the fortran layout) dimension of o must be d/2+1 where d denotes the last dimension of i.

See Fftw3.Sig.Genarray.dft for the meaning of the other optional parameters.

c2r i o returns a plan for computing the backward transform from the complex array i to the complex array o. Note that, by default, executing the plan returned by c2r destroys the input array i. You can use ~destroy_input:false to generate a plan that does not modify i at the expense of being slower — it is only possible in 1D and if no such plan can be created, Fftw3.Sig.Failure is raised.

See Fftw3.Sig.Genarray.dft for the meaning of the other optional parameters.

r2r kind i o returns a plan for computing the transform from the complex array i to the complex array o. The type of transform along the dimension k is given by kind.(k) (you must give as many kinds as there are dimensions to the input array i).

Note that the default value of destroy_input is false but you may want to change it to true, especially in case one of the r2r_kind is HC2R in order to allow the use of more efficient algorithms. Try this if Fftw3.Sig.Failure is raised.

See Fftw3.Sig.Genarray.dft for the meaning of optional parameters.