[subhk]

Summary

Fixes the findings of a full review of the package, one commit per area. The most serious gave silently wrong results, corrupted memory or crashed long runs:

• Legendre values went wrong above lmax ≈ 1900 (Float32 point evaluation above lmax ≈ 240): the recurrence seed underflowed to a denormal.
• A rejected cfg.lmax/mmax/mres assignment still stored the new value, and the next transform wrote out of bounds under @inbounds.
• Distributed calls leaked MPI communicators and died after about 1,000 calls. Vector/QST batches scrambled any layout but a θ-split one.
• Rotation gradients were 33–54% off for complex targets, and the GPU rotation cache could return another rotation's blocks.

Commits

Commit	Fixes
fix: keep the Legendre recurrence accurate beyond lmax ≈ 1900	exponent tracking in the CPU recurrence, as on the GPU
fix: validate config changes first and make create_config defaults exact	setter validation; exact default nlat on non-Gauss grids; 2 GiB cap on automatic tables
fix: sweep Wigner matrices by degree and guard mmax < lmax rotations	O(lmax⁴) → O(lmax³) rotations; pencil rotations no longer drop orders above mmax; Real angles
fix: reuse MPI topologies and honour pencil layouts in distributed calls	communicator leak; batch and fixed-order layouts; :quad axisymmetric synthesis; Float32 and real inputs
fix: accurate Float32 GPU tables, bounded caches, pinned staging buffers	Float32 accuracy (2.8e-4 → 2e-7); weakly owned, bounded caches; cache key; :quad evaluators; gpu_*_safe; point evaluation; pinning on Julia 1.11+
fix: reverse-mode AD on PencilArrays, exact rotation adjoints	distributed Zygote/ForwardDiff through the public API; exact rotation adjoint; robust pullbacks; zgrad_* memory
fix!: use the Euclidean gradient convention for vorticity losses	consistent gradients across the API (behaviour change)
fix: real FFTs into strided and padded buffers	use_rfft=true into views and strided scratch
fix: bounds-check @sht_loop before its @inbounds loop	out-of-range writes such as the one in examples/loop_demo.jl
fix: define every export and lift the Julia 1.12 compat cap	DistAnalysisPlan/DistPlan defined; precompile warnings; julia = "1.10"
ci: test :quad again, run GPU kernels on the CPU backend, fix benchmark	SHTNSKIT_PHI_SCALE hid :quad; new gpu-host-reference job; benchmark used SH_mul_mx wrongly
docs: document where conventions differ from SHTns	toroidal sign, odd negative orders in LM_cplx, SH_mul_mx layout

Behaviour changes

Worth a release note, and probably a minor version bump:

• grad_loss_vorticity_Tlm and loss_and_grad_vorticity_Tlm return m > 0 entries doubled: they now give the Euclidean gradient, like grad_enstrophy_Tlm and Zygote.
• create_config on :regular, :regular_poles and :driscoll_healy grids without nlat (or with exactly nlat = lmax+2) gives 2lmax+1 latitudes (2(lmax+1) for Driscoll–Healy). Code that hard-codes the old size gets a DimensionMismatch.
• create_regular_config no longer precomputes Legendre tables above 2 GiB; prepare_plm_tables! still does.
• Some calls now raise ArgumentError instead of returning wrong data:
  • assigning an mmax the grid can't resolve;
  • l-split spectral batches;
  • order-mixing rotations on mmax < lmax layouts (pencil and GPU);
  • rank-varying cotangents on replicated distributed energies.
• Float32 input to the 1-D and 2-D distributed analysis returns ComplexF32.
• A few pullbacks return one tangent per positional argument, where they returned an extra keyword tangent before.
• Pencils from create_spectral_pencil/create_spatial_pencil share a cached topology per communicator.