[Features] project_isometric and PolarNewton

[Jutho]

PolarNewton implementation. This is branched off and requires #64 .

[codecov]

Codecov Report

❌ Patch coverage is 96.94656% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/implementations/polar.jl	97.22%	3 Missing ⚠️
src/interface/projections.jl	0.00%	1 Missing ⚠️

Files with missing lines	Coverage Δ
src/MatrixAlgebraKit.jl	100.00% <ø> (ø)
src/implementations/projections.jl	96.00% <100.00%> (+1.00%)	⬆️
src/interface/decompositions.jl	100.00% <100.00%> (ø)
src/interface/polar.jl	80.00% <ø> (-3.34%)	⬇️
src/interface/projections.jl	66.66% <0.00%> (-13.34%)	⬇️
src/implementations/polar.jl	97.97% <97.22%> (-2.03%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Jutho]

Some random benchmark for size(A) == (2000, 1000).

julia> @benchmark left_polar!($Ac, ($W, $P)) setup=(copy!($Ac, $A))
BenchmarkTools.Trial: 24 samples with 1 evaluation per sample.
 Range (min … max):  207.428 ms … 232.445 ms  ┊ GC (min … max): 0.12% … 10.51%
 Time  (median):     208.516 ms               ┊ GC (median):    0.11%
 Time  (mean ± σ):   211.400 ms ±   8.050 ms  ┊ GC (mean ± σ):  1.53% ±  3.52%

   █                                                             
  ▃█▆█▅▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▆ ▁
  207 ms           Histogram: frequency by time          232 ms <

 Memory estimate: 53.57 MiB, allocs estimate: 130.

julia> @benchmark left_polar!($Ac, ($W, $P), PolarNewton()) setup=(copy!($Ac, $A))
BenchmarkTools.Trial: 45 samples with 1 evaluation per sample.
 Range (min … max):  106.843 ms … 133.498 ms  ┊ GC (min … max): 0.00% … 0.33%
 Time  (median):     112.492 ms               ┊ GC (median):    0.41%
 Time  (mean ± σ):   112.160 ms ±   3.850 ms  ┊ GC (mean ± σ):  0.39% ± 0.11%

              ▁ ▁█                                               
  ▃▁▃█▃▆▁▅▅█▃▁█▅██▅▃▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▃ ▁
  107 ms           Histogram: frequency by time          133 ms <

 Memory estimate: 38.79 MiB, allocs estimate: 121.

[Jutho]

Ok I managed to screw up this PR with git rebase on the current main.

[Jutho]

Ok, I managed to recover. So this now includes the PolarNewton implementation, support for not computing the positive definite factor similar to in the QR case, a project_isometric! function that uses the latter functionality, and some more tests.

If the tests pass, this is ready for a review.

[lkdvos]

Overall looks great to me. Left a couple small comments, but otherwise happy to merge.

[lkdvos]

I'm slightly unhappy with project_isometric vs isisometry. Is it at all reasonable to have project_isometry, or does that not really make sense? Happy to leave as is too, just noticing this here.

[Jutho]

That is a good catch. But I would prefer isisometric, as all other checks are also using the adjective form, e.g. ishermitian, ...

I know this constitutes yet another breaking change 😄 .

I guess unitary is the odd duck, as that is both an adjective and a noun.

[Jutho]

In case a breaking change is not warranted, I guess we can take comfort in the fact that the list of is... functions in Base has both nouns and adjectives in there.

[mtfishman]

For what it's worth, I slightly prefer isisometric and project_isometric (and I agree that it is nice if they match).

[lkdvos]

I addressed all the issues except for the isisometric one, for which I opened an issue: #69
I would say to merge this like it is now, so non-breaking, and then add the breaking change when we decide to go to 0.6.0?

[Jutho]

Ok, I'll merge when the tests turn green.