Libertem: Support for complex numbers

[uellue]

@fwin22 would like support for complex number input data in order to directly process simulation results with both amplitude and phase. @fwin22, how are real and imaginary part saved? numpy-compatible, i.e. (re, im), or do we have to assemble the components from hand somehow?

Items to check:

• [ ] Input format: .npy (separate issue, #222)
• [x] Review COM calculation
• [x] Multi-channel response for frame picking
• [x] Input format: raw binary
• [x] Back-end support for complex numbers and switching based on type if necessary: numpy, pytorch scipy.sparse
• [x] Support for complex masks as well
• [x] Check for type casts throughout the code
• [x] Test coverage
• [x] Analysis with results as complex, im, re, abs, θ
• [x] Visualization similar to COM

[FWin22]

@uellue either in numpy format ('complex64' or complex'128') or as binary data.

[sk1p]

If you say numpy format, you mean .npy or .npz files, right? And binary data is something compatible with np.fromfile(..)? For the first, we need to add explicit support, the other only needs some small changes in the raw reader.

[uellue]

I meant something that can be used with numpy.memmap with "numpy format". :-)

[FWin22]

yes to both.

[uellue]

@FWin22 Do you perhaps have a test data set? :-)

[sk1p]

On the complex branch, there is now support for working with complex-valued data. There are still a few items to do, namely:

1) Review/fix calculation for center of mass for complex-valued data. I'm pretty sure this is currently not correct.
2) .npy support - should work pretty much like the raw format, with less parameters to specify. We track this in issue #222 so I'll remove it from the list in the issue description.
3) Multi-channel response for frame picking. This needs user interface changes.

[uellue]

Looking for references regarding center of mass for complex numbers, the best I could find was the definition of the center of mass:

That calculation works with complex numbers, too. The resulting center of mass is a complex number. Regarding visualization or interpretation of that I don't have a good idea.

@FWin22, would you use a center of mass calculation on your data, and what is the expected outcome if yes? Would you do that directly or rather convert a complex amplitude to a real intensity before?

If we can't find a sensible definition, we should probably raise a NotImplementedError rather than just calculating something.

[sk1p]

That calculation works with complex numbers, too. The resulting center of mass is a complex number. Regarding visualization or interpretation of that I don't have a good idea.

Yeah, that's what scipy is doing, but I don't think that has a meaningful physical interpretation :grin: I think converting to intensity beforehand is a good idea, as it means the center-of-mass output has the same meaning in complex/real/int/... cases. Maybe, if there is another meaningful way to calculate COM, we could do both for complex data?

[uellue]

@FWin22 would converting to intensity work for you?

[uellue]

After discussions with @FWin22 and @sk1p: Center of mass with complex numbers is currently not required or useful, as far as we can see. A safe fallback is simply applying the mathematical definition and letting the user worry about interpretation, or throwing a warning. In all other cases we simply perform the calculation and let the user handle the interpretation.

For visualization of center of mass, we could simply show x re, x im, y re, y im channels of the result. Magnitude would be well-defined as well, as long as we make sure we square the absolute, not the value itself.

Further transformations of the input data before processing (im, re, abs, abs^2) can be implemented with derived datasets as described in #201.

[uellue]

Works, awesome! 👍