New functions for float FFT and vector operations

lucianomartin commented 2 years ago

We would like to add some functions to lib_xs3_math. They have been implemented in lib_dsp.

The functions are all the ones present in the following files:

The work on this part of the code is still ongoing. The documentation must be completed and more functions may be added in the future.

As a first step, would it be possible to have an estimate of how much time porting the functions above to lib_xs3_math would take?

astewart-xmos commented 2 years ago

This is addressed as a part of PR #95.

I haven't directly duplicated these functions in lib_xs3_math. I've changed them to be more consistent with the behavior (and naming) of other operations in the library.

Below is what I've added. The new header file xs3_vect_f32.h (included via xs3_math.h) contains the declarations for each of these.

If there are any problems here or any of these are inadequate, please let me know.

`xs3_vect_f32_max_exponent( )`

exponent_t xs3_vect_f32_max_exponent(
    float vector[], 
    unsigned length);

Examine the float vector to find the largest exponent among its elements. The value returned is the largest exponent (as given by FSEXP) plus 30.

The value returned is also the minimum exponent that can be used to convert vector[] into a 32-bit BFP vector. Any smaller exponent will cause some elements to saturate when converting to BFP.

xs3_vect_f32_to_s32() is used to convert the mantissas.

If additional headroom is needed (e.g. for FFTs), add the required headroom to the returned exponent and you'll get extra headroom.

`xs3_vect_f32_to_s32( )`

void xs3_vect_f32_to_s32(
    int32_t a[],
    const float b[], 
    const unsigned length,
    const exponent_t a_exp);

Converts the float vector b[] into an 32-bit BFP vector a[] with exponent a_exp. xs3_vect_f32_max_exponent() can be used to get an appropriate value for a_exp.

This function can also be used to convert the float vector into a desired fixed-point format.

If the same address is given for b[] and a[], the operation can be safely performed in-place on the vector.

`xs3_vect_s32_to_f32()`

void xs3_vect_s32_to_f32(
    float a[],
    const int32_t b[], 
    const unsigned length, 
    const exponent_t b_exp);

This is the reverse of xs3_vect_f32_to_s32(). Convert a 32-bit BFP vector to a vector of floats.

This time b_exp is the exponent associated with the input vector. Again, this operation can be performed in-place on b[].

`xs3_vect_f32_dot()`

float xs3_vect_f32_dot(
    const float b[],
    const float c[],
    const unsigned length);

Compute the inner product of two float vectors.

Note: This function is based on dsp_vect_dot_prod_fast_xs3(), not on dsp_vect_dot_prod_xs3(). As best I can tell, the two are functionally equivalent, so I went with the faster implementation.

`xs3_vect_f32_fft_forward( )`

complex_float_t* xs3_vect_f32_fft_forward(
    float x[],
    const unsigned fft_length);

Perform forward FFT on a vector of float. Converts to BFP, does FFT and converts back to float.

Supports same FFT lengths as xs3_fft_dit(). Operation is performed in-place.

Returned pointer is just &x[0] cast to complex_float_t*. Note that length of the resulting vector is half that of the input because its elements are complex.

`xs3_vect_f32_fft_inverse( )`


float* xs3_vect_f32_fft_inverse(
    complex_float_t X[],
    const unsigned fft_length);

Reverse of xs3_vect_f32_fft_forward().

fft_length is the full FFT length -- twice the length of the complex vector X[].

The returned pointer is just &X[0] cast to float*. Note that the length of the resulting vector is fft_length.

keithm-xmos commented 2 years ago

@lucianomartin and @mbanth, can you review what @astewart-xmos implemented here to ensure it satisfies the request? If it does then we will try to get this enhancement merged ASAP.

mbanth commented 2 years ago

I have compared the descriptions given here by @astewart-xmos to the functions in lib_dsp given by @lucianomartin. At that level, it all looks good. I have not tried to review the code changes in Pull Request #95.

I have one minor question mostly out of curiosity, what happens if xs3_vect_f32_fft_forward( ) receives an odd fft_length?

lucianomartin commented 2 years ago

I second the comment by @mbanth. The descriptions look like what we wanted, but I haven't looked at the code. When our app is ready, we will be able to test the upcoming version of lib_xs3_math and we will be able to give more feedback.

astewart-xmos commented 2 years ago

I have one minor question mostly out of curiosity, what happens if xs3_vect_f32_fft_forward( ) receives an odd fft_length?

Apologies for somehow overlooking this question previously. Odd FFT lengths are not supported. FFT lengths must be a power of 2

xmos / lib_xcore_math