2.3 numerical API review#
Review date: 2026-10-29. This review promotes the documented NumPy/CPU APIs in API stability and support. It supersedes July’s open graduation checklist; Progress so far retains that historical snapshot.
What changed in this review#
The review covered construction and query validation, coefficient filtering, reference and accelerated dispatch, shape/dtype/boundary behavior, persistent plans, buffers, reconstruction, convergence, and the existing release gates.
New regressions exposed and corrected these issues:
TensorSpline’s absolute grid tolerance could accept nonuniform construction coordinates expressed in very small physical units.
Symmetric degree-4 O-MOMS reported the wrong polynomial degree.
Adaptive regression’s normal equations lost accuracy for large coordinate offsets; integer sample arithmetic could overflow before conversion.
Sparse interpolation could wrap unsigned sample differences, and its evaluator could overflow integer products.
Fractional autocorrelation did not reduce distant frequencies into one period before truncating its alias sum.
Recursive smoothing could overflow or lose normalization at large finite regularization parameters, or lose small tails across large sample ranges.
Affine validation treated empty batches differently across evaluators, could discard imaginary geometry, and did not report a plain NPY file as an invalid coefficient archive.
Changing cached plan settings could leave the original factorization, frequency response, or interpolation geometry active.
Independent numerical references#
tests/test_tensorspline_independent_reference.py builds basis functions
from SciPy B-splines and finite differences of lower-degree splines. It forms
dense cardinal systems with explicit boundary extension, independently of
SplineOps’ support indexing and recursive/FFT/banded coefficient filters.
It covers B-spline degrees 0–9, O-MOMS degrees 0–5, symmetric discontinuity
conventions, all three boundaries, lengths 1/2/9, and mixed 3-D complex models.
The derivative construction follows Blu, Thevenaz and Unser’s
MOMS formulation.
tests/test_stability_numerics.py adds an independent box-constrained dual
optimizer for denoising, clamped cubic piecewise-polynomial derivatives for
Differentials, and a direct block-transform and energy check for Haar. These
complement the existing dense smoothing references, projection quadrature,
affine SciPy comparisons, property tests, archive fixtures, and workflow soaks.
Compatibility evidence#
The affine persistence and differential buffer APIs have passed repeated registration and volume-feature workflows since July, including cross-platform standard soaks and benchmark runs. The 2.3 release preparation added minimum dependency checks and installed-wheel numerical checks. The current workflows rerun this evidence for the proposed release revision; a historical green run does not replace checks on the final commit.
The review keeps existing imports and archive schemas. Plan settings now reject
reassignment: construct a new plan to change a fixed operator. The regression
objective is documented with the implemented 0.5 squared-error factor;
existing lambda semantics do not change. Corrected numerical edge cases are
listed in the changelog.
Follow-up repository review#
A second pass covered the Python modules, native buffer and concurrency
contracts, fallback dispatch, package contents, examples, and release and
documentation workflows. It found additional numerical-range gaps despite
the existing suite passing. tests/test_audit_edge_cases.py records the
new regressions:
Distant TensorSpline queries follow their named boundary mode without overflowing integer stencil conversion. Exact integer arithmetic checks queries whose physical-to-sample conversion exceeds float64’s range. Large affine translations also agree across the SciPy and NumPy backends, including reuse of prepared coefficients.
Independent decimal arithmetic checks radial smoothing responses when intermediate powers or products overflow or underflow.
Upsampled time axes contain exactly one coordinate per output sample, including factors for which a floating-point step adds an extra endpoint.
Image SNR remains unchanged when both signals are rescaled. MSE can still underflow to zero or overflow to infinity when its true value is outside float64’s range; this no longer corrupts SNR.
Integer configuration rejects booleans before conversion, consistently across supported NumPy versions.
Numerical utility imports do not initialize the plotting stack; a fresh interpreter checks this separation with warnings treated as errors.
The documentation deployment now treats Sphinx warnings as failures. These checks complement the independent algorithm references; they do not imply that every finite floating-point input or every optional backend is supported.
Limits of the decision#
CPU API stability is independent of experimental CuPy support. The three smoothing formulations remain distinct, differential angular maps remain 2-D, and order-5 wavelets keep approximate source taps. Stability does not add new boundaries, unsupported shapes, GPU guarantees, or universal speed claims. Future extensions need their own contract and independent numerical checks.