Add user choice for whether `BaseInterferogram` returns the iFFT (real space field)

[PinkShnack]

I want to allow the user to choose whether the field is created at the end of the BaseInterferogram processing, in my case OffAxisHologram. I want the option to not do this Fourier transform, so that I can feed the data directly into nrefocus in Fourier space for propagation. In a combined qpretrieve+nrefocus processing pipeline, this would remove two unnecessary FFT calls.

I think simply adding a parameter no_ifft, with default False, would do the trick. The only thing to keep in mind would be that when the user calls oah.field, oah.amp or oah.phase, they should be then calculated, if no_ifft=True.

In addition, I will be adding a similar idea to nrefocus so that it takes in a Fourier transform and then doesn't need to do the initial FFT.

For consistency, we should have the following params:

• nrefocus should have input_domain='spatial' or 'fourier'
• qpretrieve and nrefocus should have output_domain='spatial' or 'fourier'
• Aliases here could be:
  • spatial = field, real
  • fourier = frequency, fft

[paulmueller]

Sounds good. I would call it skip_ifft=False.
Computation of IFFT on demand makes sense, but raising ValueError with explanation would also be OK IMO.

[PinkShnack]

I also had the idea to have return_field. But skip is clearer.

So there is a reasonable speed benefit of 30% on CPU and 10% on GPU. So worth doing. It's more involved than I first thought, as the iFFT needs some unpadding etc.

---------------------------------------------------------------------------------------------- benchmark: 6 tests ---------------------------------------------------------------------------------------------
Name (time in ms)                                  Min                Max               Mean            StdDev             Median               IQR            Outliers       OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_bm_np_return_field_false[data1-cupy]       2.4776 (1.0)       6.8059 (2.07)      2.6461 (1.0)      0.3088 (2.29)      2.5954 (1.0)      0.0841 (1.0)          7;27  377.9195 (1.0)         222           1
test_bm_np_return_field_later[data1-cupy]       2.7464 (1.11)      3.7805 (1.15)      2.9083 (1.10)     0.1346 (1.0)       2.8767 (1.11)     0.1011 (1.20)        32;17  343.8481 (0.91)        229           1
test_bm_np_return_field_true[data1-cupy]        2.8458 (1.15)      3.2910 (1.0)       2.9549 (1.12)     0.1739 (1.29)      2.8663 (1.10)     0.0887 (1.05)          2;2  338.4209 (0.90)         10           1
test_bm_np_return_field_false[data0-numpy]     17.2136 (6.95)     32.9898 (10.02)    18.6236 (7.04)     2.6317 (19.55)    17.9486 (6.92)     0.6300 (7.49)          3;6   53.6954 (0.14)         52           1
test_bm_np_return_field_true[data0-numpy]      25.2909 (10.21)    41.8576 (12.72)    27.4558 (10.38)    3.5412 (26.30)    26.3025 (10.13)    1.2797 (15.22)         2;5   36.4221 (0.10)         37           1
test_bm_np_return_field_later[data0-numpy]     25.9355 (10.47)    36.0089 (10.94)    27.5261 (10.40)    2.2913 (17.02)    26.9006 (10.36)    0.9847 (11.71)         3;3   36.3291 (0.10)         37           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[PinkShnack]

Notes for myself, so far I have:

• initial layout of output domain param for qpretrieve, and a way to compute the field only on demand, and still using the FFT Cache.
• input and output domain params for nrefocus, allowing fft input and output.
• a way to combine the two packages nicely for direct fft propagation

Still need to:

• verify that the legacy and direct propagation are similar.
• verify that the qpretrieve compute_field after the fact is identical to doing as in legacy.
• create an example in qpretrieve.
• Create a benchmark example that compares direct and legacy pipeline
• handle pyfftw output in nrefocus correctly