Numerical methods roadmap

This page tracks numerical methods that belong in jaxstro because they are generic, JAX-native, and broadly useful across downstream astronomy packages. The boundary is deliberate: jaxstro provides trustworthy numerical primitives; Fluxax owns filters and photometry workflows, Progenax owns population and stellar-model policy, and data packages own their archive-specific schemas.

Implementation Checklist¶

• Core 1D B-spline evaluation. Basis evaluation, spline evaluation, clamped open-uniform knots, and a PyTree wrapper for fixed knots and coefficients.

• B-spline follow-ups, batch 1. Design matrices, derivatives, and fixed-knot least-squares fitting.

• B-spline follow-ups, later batches. de Boor evaluation, antiderivatives, smoothing penalties, adaptive knots, and tensor-product construction.

• Shape-preserving interpolation. Cubic Hermite and monotone PCHIP-style interpolation for table-like functions where overshoot is unacceptable.

• Natural cubic spline interpolation. Coefficient solve, clamped evaluation, SciPy parity tests, PyTree wrapper, and FD-vs-AD validation for smooth anchor-table interpolation.

• Regular-grid interpolation. Bilinear, trilinear, and static-rank ND interpolation for gridded models with explicit clamp/fill/reject policies.

• Numerical differentiation diagnostics. Public finite-difference, directional-derivative, and Jacobian-check utilities in jaxstro.testing.

• Complete fixed quadrature. Canonical sampled-data rules, one shared Gaussian recurrence engine, Legendre, Jacobi, generalized Laguerre, both Hermite conventions, Clenshaw-Curtis, Fejer I and II, fixed tanh-sinh, explicit domains and measures, and a JAX-transformable fixed evaluator.

• Adaptive one-dimensional quadrature. Gauss-Kronrod pairs, nested Clenshaw-Curtis, adaptive tanh-sinh, Romberg variants, deterministic status precedence, fixed-capacity work evidence, and an analytic and failure-envelope validation suite. All five methods have first-order accepted-formula replay derivatives; replay is the default, explicit stop remains available, and an alpha quantity adapter normalizes into the same raw engine.

• Multidimensional quadrature over finite hyperrectangles. Fixed and globally adaptive tensor rules, adaptive Genz-Malik cubature, fixed and dimension-adaptive Smolyak sparse grids, deterministic Sobol integration, fixed-look scrambled Sobol intervals, and bounded sequential randomized QMC share typed status and work records while retaining family-specific error meanings. First-order accepted-formula replay and heterogeneous alpha quantity axes are implemented. Full release, observed-memory, and rendered documentation certification remain open gates rather than hidden non-claims.

• Root-finding and monotone inversion. Bracket discovery, vectorized independent solves, and monotone inverse interpolation for CDF-like tables.

• Linear algebra primitives. Weighted least squares, QR/SVD solve wrappers, covariance/correlation helpers, and positive-definite jitter tools.

• Astro-relevant special functions. Stable Planck kernels, normalized log-weight helpers, and orthogonal polynomial bases without owning downstream domain semantics.

• Sampling and grid utilities. Log grids, geometric bin centers/edges, conservative binning, and stratified sampling.

• Provenance and trust reports. Deterministic JSON/Markdown summaries that connect numerical methods to their validation anchors.

• Optimization helpers, first slice. Robust residual losses, objective summaries, fixed-iteration Armijo backtracking, and convergence diagnostics without becoming an optimizer stack.

• ODE helpers, first slice. Fixed-step Euler, midpoint/RK2, RK4, and leapfrog or velocity-Verlet with scan-friendly APIs and analytic validation.

• Linear-operator helpers, first slice. Dense, diagonal, scaled, sum/product, transpose/rmatvec, and block composition as small PyTrees.

• Distribution kernels, first slice. Stable logpdf/CDF/inverse-CDF helpers for generic families and truncated variants.

• Geometry helpers, first slice. Vector normalization, angular distance, rotations, quaternions, rigid transforms, and composition helpers.

• Autodiff helpers, first slice. JVP/VJP/HVP, Jacobian-vector, vector-Jacobian, Gauss-Newton, and generic Fisher-style products.

• Runtime provenance, first slice. Artifact hashing, environment snapshots, method manifests, and deterministic JSON/Markdown rendering.

• Random helpers, first slice. Explicit key streams, resampling methods, seed manifests, and shape-stable APIs.

• Structured 1D mesh helpers, first slice. Cell centers/volumes, face geometry, finite-volume stencils, and conservative remap.

Acceptance Standard¶

Each checked item needs three pieces of evidence:

1. A public API with explicit boundary behavior.

2. Unit tests for mathematical identities and transform compatibility.

3. FD-vs-AD validation for differentiable paths, linked from Validation.

The detailed chunk plan lives in docs/plans/2026-06-22-jaxstro-numerics-roadmap.md.