Docs for Half-complex should describe connection with sine/cosine expansion

[dlfivefifty]

I'm surprised the docs for "Half-complex" don't explain that the transform gives the coefficients in cos/sin series:

julia> m = 5; θ = range(0,2π; length=m+1)[1:m];

julia> FFTW.r2r(cos.(2θ), FFTW.R2HC) # only non-zero is in entry corresponding to cos(2θ)
5-element Vector{Float64}:
  0.0
 -2.220446049250313e-16
  2.5
 -6.709199951388644e-16
 -2.310772834960631e-17

julia> FFTW.r2r(sin.(θ), FFTW.R2HC) # only non-zero is in entry corresponding to sin(θ)
5-element Vector{Float64}:
  1.1102230246251565e-16
 -2.139456371091744e-16
  1.5843448587791657e-16
  0.0
 -2.5

This is particular important in multiple dimensions since it gives precisely the coefficients in the tensor product basis, which is clearer than the explanation in the docs:

julia> FFTW.r2r(sin.(θ) .* cos.(2φ'), FFTW.R2HC) # only non-zero is in entry corresponding to sin(θ)*cos(2φ)
5×6 Matrix{Float64}:
  0.0           0.0           3.33067e-16  0.0          0.0           0.0
  0.0           0.0          -6.41837e-16  0.0          0.0           0.0
  0.0           0.0           4.75303e-16  0.0          0.0           0.0
  1.11022e-16  -5.55112e-17  -5.55112e-17  1.11022e-16  9.61481e-17  -9.61481e-17
 -1.77636e-15  -1.11022e-16  -7.5          2.22045e-16  3.07674e-15  -2.88444e-15

[matteo-frigo]

It depends upon what you mean by "sin/cos series". In a naive interpretation of your comment, the coefficient in the transformed array should be 5 (or perhaps 1), but definitely not 2.5. In addition, if you compute FFTW.r2r(cos(0 * θ), FFTW.R2HC), you get 5 as coefficient, whereas all other frequencies have coefficient 2.5.

The position that FFTW takes is that sines and cosines are a historical relic and only complex exponentials exist. Your cos(2 * theta) input is just the sum of two complex exponentials, from which it is "obvious" that the coefficient should be 2.5 and not 5 (where the other 2.5 at negative frequency is redundant and not stored). cos(0 * theta) is one complex exponential. This convention at least has the advantage that frequency 0 is not in any way special.

Anyway, that's why things are the way they are, but we are not fascist about this. If you have a suggested text for that section in the manual, we'll be happy to talk about it.

[dlfivefifty]

That’s an odd position since sines/cosines preserve realness of the function, which is very important in many PDE applications. Yes in 1D you can reinterpret it as a symmetry property of the coefficients but as the current docs make clear it doesn’t generalise to higher dimensions in a natural way.

I’ll try to come up with a suitable text.