ENH: Deprecate the vnl_svd family for the Eigen-backed itk::Math::SVD

[hjmjohnson]

Deprecates the vnl_svd family (vnl_svd, vnl_svd_fixed, vnl_svd_economy, vnl_matrix_inverse) in favor of the Eigen-backed itk::Math::SVD, migrates every in-tree consumer, and build-gates the LINPACK svdc engine out of ITK_FUTURE_LEGACY_REMOVE. The itk::Math::SolveSymmetric/InverseSymmetric (LDLT) work that previously lived here is split out to #6565 so the two review independently.

Commit structure (4 thematic commits)

1. Extend itk::Math::SVD — pseudo-inverse, solve, rank, recompose, null-vector, WellCondition, DeterminantMagnitude; eigenvector sign routed through itkEigenDecompositionSignConvention for backend-stable results.
2. Test the extended surface against vnl_svd on well- and ill-conditioned inputs.
3. Migrate consumers (transforms, DTI reconstruction, image moments, label-map, membership functions, Mahalanobis metrics, Quasi-Newton optimizer, NIfTI/MINC IO, classifier estimators, itk::Matrix::GetInverse). Widely-included headers keep the transitive vnl_svd* include reachable under #if !defined(ITK_LEGACY_REMOVE) && !defined(ITK_FUTURE_LEGACY_REMOVE) so downstream code that relied on it still compiles during the deprecation window.
4. Deprecate the vnl_svd family with the three-state guard (silent default / #warning under ITK_LEGACY_REMOVE / #error under ITK_FUTURE_LEGACY_REMOVE) and build-gate the LINPACK svdc sources.

Downstream validation (forest)

Built against this branch's tip in the ITK downstream forest: ITK, ANTs, BRAINSTools, c3d, SimpleITK all compile clean. The one real regression found — ANTs antsAffineInitializer relying on a transitive vnl_svd_fixed.h via itkTransform.hxx — is fixed by the guarded transitive includes in commit 3. No consumer hit any vnl_svd/vnl_matrix_inverse/itk::Math::SVD compile error. (c3d and SimpleITK additionally needed their own upstream ITK6-migration PRs, unrelated to this change.)

[hjmjohnson]

Scope update (superseded): the itk::Math::SolveSymmetric / InverseSymmetric (Eigen LDLT) work has been split out to #6565. This PR is now the vnl_svd-family deprecation only (vnl_svd, vnl_svd_fixed, vnl_svd_economy, vnl_matrix_inverse → itk::Math::SVD).

[hjmjohnson]

Fixed the ITK.Linux (LegacyRemovedDebugCxx20) failure in 232a2ad — Examples/RegistrationITKv4/ImageRegistration9.cxx still used vnl_svd<double> via a transitive include that this PR guards out under ITK_LEGACY_REMOVE. Migrated it to itk::Math::SVD (svd.U * svd.V.transpose()), matching the sibling test/RegistrationITKv3 example. A full-tree sweep confirms no other vnl_svd/vnl_matrix_inverse consumers remain outside the vendored VNL sources. Builds clean locally.

[blowekamp]

Is the recommendation moving forward going to be to directly use Eigen or use new ITK interfaces?

[hjmjohnson]

Is the recommendation moving forward going to be to directly use Eigen or use new ITK interfaces?

I would say to use the ITK interfaces. A few (or perhaps many now) years ago, at a NA-MIC meeting, several people were lamenting the fact that VXL was exposed to end-users as part of the ITK API, and how that decision both increased the maintenance burden and limited how we could improve ITK. I am trying to avoid that trap with Eigen.

Internally, we can use Eigen directly, but we should provide an ITK API wrapper that does not expose Eigen to consumers of ITK. This will allow future algorithmic changes to be made independent of what Eigen does.

Judicious use of itk::Math::detail namespaces where Eigen interfaces provide performance benefits are used to indicate that, while they are part of the 'technical' public API, conceptually we do not consider them part of the public API, and we do not make any guarantees about backward compatibility for those details.

[blowekamp]

everal people were lamenting the fact that VXL was exposed to end-users as part of the ITK API, and how that decision both increased the maintenance burden and limited how we could improve ITK. I am trying to avoid that trap with Eigen.

I had thought that comment referenced the classes that were derived from VNL object, along with the the operator that operated on VNL objects.

[hjmjohnson]

everal people were lamenting the fact that VXL was exposed to end-users as part of the ITK API, and how that decision both increased the maintenance burden and limited how we could improve ITK. I am trying to avoid that trap with Eigen.

I had thought that comment referenced the classes that were derived from VNL object, along with the the operator that operated on VNL objects.

@blowekamp Do you see this as a step in the wrong direction, or are you concerned about the approach? I'd like to understand your view on the correct approach. Do you think a Zoom call would help?

My approach/motivation: I was trying to replace vnl_ (backed by pre-1999 FORTRAN) -> itk::Math:: (backed by Eigen). In most cases, this provides 2 wins: 1) Performance (limited at the moment, Eigen unlocks other performance improvements that will need to be revisited later), and 2) Almost always better numerical accuracy. Also, Eigen is having a huge (Nvidia-backed) engineering modernization effort going on right now that will hopefully filter into ITK for free.