You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The VNL → Eigen migration (#6403) has been adding Eigen-backed numerics as itk::Math::* / itk::* APIs (itk::Math::SVD, itk::QRDecomposition, itk::*EigenDecomposition, itk::Math::SolveSymmetric, …). @blowekamp raised a concern that this repeats VNL's original mistake: by exposing general-purpose math algorithms through ITK's public API, ITK became their de-facto maintainer and compatibility guarantor for decades. This issue proposes segregating these APIs into a clearly-labeled namespace that marks them as useful conveniences, not part of the core ITK API contract — analogous to Eigen's unsupported/ modules.
The concern
VNL was vendored as an implementation detail, but its symbols leaked into ITK's public surface (GetVnlVector, vnl_matrix in signatures, direct downstream use of vnl_svd, vnl_lbfgsb, …). Result: ITK could not change, upgrade, or remove its numerics backend without breaking downstream projects, and the toolkit inherited a support obligation for general linear algebra that is not its mission.
The replacement campaign is at risk of recreating that coupling one level up. Each new itk::Math::* wrapper is currently indistinguishable — in namespace, header location, and implied support level — from core ITK contract API like itk::Image or itk::ImageFileReader. Downstream projects (ANTs, BRAINSTools, Slicer, elastix) will adopt them as freely as they adopted vnl_svd, and in 20 years ITK would again be unable to swap the backend (today Eigen, tomorrow something else) without a deprecation campaign of this same scale.
Proposal sketch
Place the math-convenience layer in a namespace (and matching header path) that signals its support tier, e.g.:
itk::unsupported::Math::* — mirrors Eigen's precedent exactly: unsupported/Eigen/* modules are robust, widely used, and maintained, but explicitly outside the core Eigen API-stability contract.
Alternatives to bikeshed: itk::convenience::, itk::numerics::, itk::detail:: (too strong — implies "do not use"), or a documented support-tier annotation without a namespace change.
What the tier would mean, concretely:
Usable and tested — shipped, wrapped where appropriate, covered by GTests, not second-class in quality.
No backend-stability promise — the numerical backend (currently Eigen) may change between minor releases; results are guaranteed only to documented tolerances, not bit-exactly.
Shorter deprecation window — signatures may evolve without the multi-release three-state ceremony required for core API.
Not the recommended long-term home — projects needing hard numerical guarantees should depend on a numerics library directly.
Timing matters: the itk::Math::* surface is young (#6454, #6473, #6475, #6487, #6565 merged; #6564/#6568 in review) and downstream adoption is only starting (gated #ifdef ITK_MATH_HAS_SOLVE_SYMMETRIC adoptions in ANTs/BRAINSTools). Renaming/re-tiering now costs little; after one or two releases it becomes another VNL.
Open questions
Namespace name and header layout (itk/unsupported/…? Modules/Core/CommonMath?).
Does the tier apply only to the new Eigen-backed wrappers, or also to long-standing math utilities (itk::Math::abs, itkMath.h constants) that are effectively core contract already?
The VNL → Eigen migration (#6403) has been adding Eigen-backed numerics as
itk::Math::*/itk::*APIs (itk::Math::SVD,itk::QRDecomposition,itk::*EigenDecomposition,itk::Math::SolveSymmetric, …). @blowekamp raised a concern that this repeats VNL's original mistake: by exposing general-purpose math algorithms through ITK's public API, ITK became their de-facto maintainer and compatibility guarantor for decades. This issue proposes segregating these APIs into a clearly-labeled namespace that marks them as useful conveniences, not part of the core ITK API contract — analogous to Eigen'sunsupported/modules.The concern
VNL was vendored as an implementation detail, but its symbols leaked into ITK's public surface (
GetVnlVector,vnl_matrixin signatures, direct downstream use ofvnl_svd,vnl_lbfgsb, …). Result: ITK could not change, upgrade, or remove its numerics backend without breaking downstream projects, and the toolkit inherited a support obligation for general linear algebra that is not its mission.The replacement campaign is at risk of recreating that coupling one level up. Each new
itk::Math::*wrapper is currently indistinguishable — in namespace, header location, and implied support level — from core ITK contract API likeitk::Imageoritk::ImageFileReader. Downstream projects (ANTs, BRAINSTools, Slicer, elastix) will adopt them as freely as they adoptedvnl_svd, and in 20 years ITK would again be unable to swap the backend (today Eigen, tomorrow something else) without a deprecation campaign of this same scale.Proposal sketch
Place the math-convenience layer in a namespace (and matching header path) that signals its support tier, e.g.:
itk::unsupported::Math::*— mirrors Eigen's precedent exactly:unsupported/Eigen/*modules are robust, widely used, and maintained, but explicitly outside the core Eigen API-stability contract.itk::convenience::,itk::numerics::,itk::detail::(too strong — implies "do not use"), or a documented support-tier annotation without a namespace change.What the tier would mean, concretely:
Timing matters: the
itk::Math::*surface is young (#6454, #6473, #6475, #6487, #6565 merged; #6564/#6568 in review) and downstream adoption is only starting (gated#ifdef ITK_MATH_HAS_SOLVE_SYMMETRICadoptions in ANTs/BRAINSTools). Renaming/re-tiering now costs little; after one or two releases it becomes another VNL.Open questions
itk/unsupported/…?Modules/Core/CommonMath?).itk::Math::abs,itkMath.hconstants) that are effectively core contract already?itk::Math::SVDetc. get aliased-and-deprecated into the new namespace or moved outright while adoption is still minimal.Related: #6403 (umbrella migration), #6230 (no transitive Eigen exposure).