SHT and CHT

[narahahn]

According to Eq. (3.34) in Rafaely, 2015, the forward and inverse discrete spherical harmonic transform are defined as

fnm = Y^-1 * f
f = Y * fnm

where fnm denotes the SHT coefficient vector, f the sound field vector, Y the spherical harmonics matrix, and Y^-1 its pseudo-inverse. In our toolbox, we are using the same matrix Y (see sht_matrix), but it is not used in a consistent way.

https://github.com/spatialaudio/sfa-numpy/blob/43329a7634bb896ea52d31b1edb844d0f0d3f606/examples/modal_beamforming_rigid_array.py#L20-L26

Here, Y_p is used for the synthesis (inverse transform) which follows the convention introduced in [Rafaely, 2015].

https://github.com/spatialaudio/sfa-numpy/blob/43329a7634bb896ea52d31b1edb844d0f0d3f606/examples/modal_beamforming_rigid_array.py#L28-L40

In the following part (PWD), however, Y_p is used for the analysis (forward transform).

The user should also note that Y_p is different for the analysis (with weights)

Y_p = micarray.modal.angular.sht_matrix(N, azi, elev, weights)

and synthesis (without weights)

Y_p = micarray.modal.angular.sht_matrix(N, azi, elev)

The same applies to CHT.

In my opinion, we need to specify the usage of the SHT and CHT matrices in the document or in the docstrings.

[narahahn]

I just changed the title of this issue, since it's about the usage of the matrices. There is nothing wrong with the matrices themselves.

[trettberg]

There seem to be (at least) two issues here:

1. The example is clearly inconsistent.
2. What convention shall we use for transform matrices?

Currently the output sht_matrix is meant to be interpreted as a forward transform (analysis) matrix. This seems to be common for DFT matrices, e.g. scipy.linalg.dft or Matlab's dft_matrix. Under this convention, the generation of p in the first example is wrong.

But it is maybe better to treat sht_matrix as the inverse transform (synthesis) matrix? One could argue that the "basis functions" are "more basic" than the coefficient functionals. Should we change to this convention?

Either way it really needs better documentation.

[trettberg]

@narahahn and @spors agreed to use the convention of Rafaely, 2015: The returns of sht_matrix and cht_matrix shall be interpreted as inverse transform (synthesis) matrices from now on.

[trettberg]

Turns out the docstrings of sht_matrix and cht_matrix are inconsistent, too. :(