[mcencini]

Requested by Matteo · project thread

What changed

Subspace.fit keeps the left singular vectors B of the signals laid out as columns. The two maps now match that:

• project(s) = s @ B.conj(), the inner products ⟨b_k, s⟩
• expand(c) = c @ B.mT, so expand(project(s)) == s for any signal in the span, complex included
• modes = B.mH (resolve_conj'd), which is mri-nufft's MRISubspace layout. MRISubspace expands with conj(modes) and projects with modes, which are exactly expand and project.
• BART's pics -B and bartorch's basis= contract without the conjugate, so they take basis.mT. The docstring and docs/explanations/model-based-reconstruction.md say so.

Why

Before this change, project was s @ B and expand was c @ B.mH. Those two are adjoints of each other, so they agreed with mri-nufft. But they project onto the conjugate of the signals' span. On random complex signals that lie in a rank-3 span, the round trip had 96 % error. Real dictionaries, and dictionaries whose atoms share one global phase, hid this. A dictionary whose phase changes along the train does not, for example one with off-resonance or RF phase cycling. Found while moving mri2qmap's real-coefficient basis rotation upstream (mri2qmap-bartorch).

Validation

• New tests/estimators/test_subspace.py::test_complex_signals_of_the_span_round_trip fails before the change and passes after it. It also checks the modes / mri-nufft relations.
• tests/operator/test_subspace_route.py now runs both a real basis and an off-resonant complex one against mri-nufft's MRISubspace (op and adj_op). All 5+2 pass. Locally I had to stub mrinufft.check_backend, because the installed mri-nufft lacks it, and install finufft.
• pytest tests/estimators tests/operator tests/test_docstring_defaults.py: 285 passed, 32 skipped (CUDA).
• ruff format / ruff check: clean.
• Not run: the full suite, the docs build, and a GPU.

Documentation impact

Subspace.project, expand and modes docstrings, the model-based reconstruction explanation, and a CHANGELOG Unreleased/Fixed entry. For callers with complex, phase-varying dictionaries, coefficients change by a conjugation of the basis. That is the fix.

Checklist

• A new test covers the change and fails before it.
• ruff is clean.
• numpydoc docstrings.
• Comments describe the current code (the history is in the CHANGELOG only).
• Kernels are not touched.
• Docs build not run.

---

Generated by Claude Code