AbsFunctions added

[fmwatson]

Description

Methodology for converting a CIL Function H(x) into the same Function applied to the magnitude of data G(z):=H(|z|), in particular for complex-valued problems. The New CIL Function can be used as
function = SomeCILFunction() fun_applied_to_magnitude = FunctionOfAbs(function)

.proximal() (and .proximal_conjugate()) will be correctly modified for use with Algorithms such as PDHG

For mathematical details see https://doi.org/10.48550/arXiv.2410.22161

[jakobsj]

Thanks very much @fmwatson for adding this absolute value feature! As also discussed in person, it would be a great help for reviewing this if you could add some very basic demonstration code of how a user might use this. One potential (but possibly slightly too simplistic) case could be a complex random valued square MatrixOperator A mapping a vectordata x to a vectordata b and then use the functionality to do ||A* abs(x) - b||_2^2

[fmwatson]

@jakobsj it's hard to put together a non-trivial example with the base tools and Functions available directly from CIL. For example the existing L2NormSquared and L1Norm do not contain an operator, and LeastSquares does but does not define a .proximal(). Because most CIL users have not been working with complex-valued images, these things such as a generalised Tikhonov Function have not been needed. So any non-trivial example really needs a more interesting user provided Function.

A simple example with TotalVariation would only need

tv = TotalVariation(backend='numpy')
tvabs = FunctionOfAbs(tv)

The Function instance tvabs now has correctly defined __call__() and .proximal() methods for TV(|z|) for complex-valued z

(Total Variation itself does not need all of the machinery built into FunctionOfAbs, it will avoid the additional iterations in the proximal calculation)

[jakobsj]

Thank you @fmwatson for the additional information. To progress this I think it would beneficial to have an online meeting, perhaps with other relevant people, and discuss its usage and relation to general complex-valued support and identify potential user-provided or to-be-added-to-CIL functions providing relevant examples - I see lots of cases covered in your paper. I will contact you by email.

[lauramurgatroyd]

Current docs rendering:

[lauramurgatroyd]

Hi @fmwatson, thanks for your PR

I've just had a look at the documentation and made some suggestions

[MargaretDuff]

Hi @fmwatson - just checking in on this PR? Did you have chance to check it with your code? If you are happy, I will review it again and then try and push to merge.