Replace OPR's SVDs with Gram-matrix factorizations

[ShantanuKodgirwar]

Last of the series. Follows #90, #91, #93, #94 and the benchmark PR.

This changes default numerical output — hence 0.2.8 → 0.3.0 rather than a patch bump.

Why

Two thirds of an OPR iteration is linear algebra, not ptychography:

stage	ms/iter	share
orthogonalizeIncoherentModes	199.9	39.6%
orthogonalizeProbeStack	133.8	26.5%
position loop and everything else	170.8	33.9%

And probe_stack grows linearly in frames and modes — 10.4 GB at 512 px / 890 frames /
6 modes, before the transient the SVD needs on top. On a 32 GB card that is the binding
constraint, so this is as much a memory change as a speed one.

What changed

orthogonalizeProbeStack ran a full SVD of the (Np², nFrames) stack, allocating a
(Np², nFrames) U it then throws most of away. gram_tsvd gets the same rank-k subspace from
the (nFrames, nFrames) Gram matrix instead.

orthogonalizeIncoherentModes ran one small SVD per frame in a Python loop. The batched
form factorizes all frames at once, in frame chunks so the transpose scratch stays bounded
rather than allocating a second copy of the whole stack.

	364 px, 202 fr, 4 modes	512 px, 890 fr, 6 modes
orthogonalizeIncoherentModes	4.1x	1.8x
gram_tsvd vs full SVD	1.8x, 5.3x less peak memory	1.9x, 4.3x less

The batched advantage shrinks with size — the loop's cost is mostly per-frame launch overhead,
which is exactly what batching removes; at large sizes the factorization itself dominates.

End to end, 364 px / 202 frames / 4 modes over 30 iterations:

variant	ms/iter	peak GB	speedup	memory
numpy full SVD (previous default)	518.8	3.18	1.00x	—
OPR_tsvd_type="gram" only	452.5	1.67	1.15x	1.90x
OPR_fast_orthogonalization only	360.9	3.36	1.44x	0.95x
both (new defaults)	296.3	1.85	1.75x	1.72x

svd on the Gram matrix, not eigh

Mathematically identical — for a Hermitian positive semi-definite matrix the SVD and the
eigendecomposition coincide, and svd returns descending order for free. The practical reason is
that cupy.linalg.eigh is not importable in every CuPy/CUDA install (it routes through
cupyx.cusolver; here it fails on libcusolver.so.11). The implementation deliberately does not
depend on it.

On the numerics — please read this bit

A naive elementwise comparison of the probe reports relative error 2.0, which looks
catastrophic and is not. Mode vectors are defined only up to a per-mode global phase, and the
Gram route makes a different arbitrary choice than LAPACK. A phase flip is exactly relative
error 2.

Everything gauge-independent agrees:

quantity	agreement
object	1.4e-07
error metric	4.6e-08
mode powers	4.1e-07, 1.1e-06
|probe|	8.0e-07
mode vectors, after aligning phase	8.2e-07, 1.7e-04

Over a longer run the object does drift, because the solver amplifies any perturbation. At
364 px / 202 frames / 30 iterations the Gram route moves the object by 1.6e-02 — while
perturbing the initial object of the unmodified path by a relative 1e-6, below the float32
resolution of the inputs, moves it by 2.8e-02. The change sits inside the algorithm's own
sensitivity to its inputs, and the error metric agrees to 9.3e-05.

Escape hatch, and it is tested

params.OPR_tsvd_type="numpy"params.OPR_fast_orthogonalization=False

recovers the previous output. A regression golden pins that path, so the claim is verified rather
than asserted.

Tests

• tests/Engines/test_opr_linalg.py — gram_tsvd unit tests, on CPU so CI covers them even
  though OPR itself is GPU-only. Includes rank clamping and rank-deficient input.
• tests/regression/test_opr_regression.py — the legacy golden, and the gauge-invariant
  comparison above.

Suite goes 61 → 71 passing.

Incidental fixes in the same functions

• orthogonalizeProbeStack dispatches through getArrayModule instead of calling cp directly
• the "numpy" path no longer mutates the caller's singular values in place
• an unknown OPR_tsvd_type now raises, instead of failing later with an unbound name

Note

notes/gram_orthogonalization.md is a full walkthrough of why the Gram route gives the same
answer and where the speedup comes from — written for someone who has not thought about this
before.