feat: mass profile self-consistency test suite

[Jammy2211]

Overview

Create a comprehensive self-consistency test suite for every mass profile in PyAutoGalaxy. The suite verifies that convergence, potential, deflections, and shear are internally consistent using generic lensing relations (divergence, gradient, Laplacian) computed via numerical differentiation — independent of the source code implementation. This is the safety net for the broader mass profiles refactoring effort (PyAutoLabs/PyAutoGalaxy#445).

Plan

• Create scripts/mass/ in autolens_workspace_test with one script per profile category (total, dark, stellar, sheets, point)
• Each script instantiates every profile with representative parameters and checks lensing relations: div(α)=2κ, ∇ψ=α, ∇²ψ=2κ
• Profiles returning zeros for convergence or potential are documented as SKIP with clear notes
• Cross-check against existing mass_via_integral/ reference implementations (NFW, Sersic, etc.)
• Support PYAUTO_MASS_FAST env var for quick CI validation (smaller grids, looser tolerances)
• Print summary table at end of each script: PASS/FAIL/SKIP per profile per relation

Detailed implementation plan

Affected Repositories

• autolens_workspace_test (primary)
• PyAutoGalaxy (read-only reference)

Work Classification

Workspace

Branch Survey

Repository	Current Branch	Dirty?
autolens_workspace_test	main	yes (modified datasets, untracked scripts)
PyAutoGalaxy	main	yes (modified CLAUDE.md)

Suggested branch: feature/mass-self-consistency-tests
Worktree root: ~/Code/PyAutoLabs-wt/mass-self-consistency-tests/

Implementation Steps

1. Create scripts/mass/__init__.py and shared utility module scripts/mass/util.py with:

   • check_div_alpha_eq_2kappa(profile, grid) — divergence of deflections vs 2× convergence
   • check_grad_psi_eq_alpha(profile, grid) — gradient of potential vs deflections
   • check_laplacian_psi_eq_2kappa(profile, grid) — Laplacian of potential vs 2× convergence
   • check_shear_consistency(profile, grid) — shear from Hessian vs deflection derivatives
   • make_grid(fast=False) — returns appropriate grid based on PYAUTO_MASS_FAST
   • print_summary_table(results) — formatted PASS/FAIL/SKIP table
   • All checks use np.gradient on 2D native arrays, excluding 2-pixel boundary

2. Write scripts/mass/total.py:

   • Isothermal, IsothermalSph, IsothermalCore, IsothermalCoreSph
   • PowerLaw, PowerLawSph, PowerLawCore, PowerLawCoreSph
   • PowerLawBroken, PowerLawBrokenSph (potential SKIP — returns zeros)
   • PowerLawMultipole (convergence SKIP — returns zeros, physically correct)
   • PIEMass, dPIEMass, dPIEMassSph (potential SKIP for dPIEMass)
   • dPIEPotential, dPIEPotentialSph (potential SKIP — returns zeros)

3. Write scripts/mass/dark.py:

   • NFW, NFWSph (full check + cross-ref with mass_via_integral/nfw.py)
   • gNFW, gNFWSph (cross-ref with mass_via_integral/gnfw.py)
   • cNFW, cNFWSph (convergence + potential SKIP — both return zeros)
   • NFWTruncatedSph (potential SKIP — returns zeros)
   • MCR/Scatter/Virial variants — deflections and convergence only (same underlying math)

4. Write scripts/mass/stellar.py:

   • Sersic, SersicSph (potential SKIP — returns zeros; cross-ref mass_via_integral/sersic.py)
   • SersicCore, SersicCoreSph
   • SersicGradient, SersicGradientSph (cross-ref mass_via_integral/sersic_gradient.py)
   • Gaussian (potential SKIP; cross-ref mass_via_integral/gaussian.py)
   • GaussianGradient
   • Exponential, ExponentialSph
   • DevVaucouleurs, DevVaucouleursSph
   • Chameleon, ChameleonSph (potential SKIP)

5. Write scripts/mass/sheets.py:

   • ExternalShear (convergence SKIP — physically zero)
   • MassSheet (potential SKIP — returns zeros)
   • ExternalPotential

6. Write scripts/mass/point.py:

   • PointMass (potential SKIP — returns zeros)
   • SMBH
   • SMBHBinary

Key Files

• scripts/mass/util.py — shared numerical differentiation utilities
• scripts/mass/total.py — total mass profile tests
• scripts/mass/dark.py — dark matter profile tests
• scripts/mass/stellar.py — stellar mass profile tests
• scripts/mass/sheets.py — sheet/perturbation profile tests
• scripts/mass/point.py — point mass profile tests
• scripts/mass_via_integral/ — existing reference implementations (read-only)

Original Prompt

Click to expand starting prompt

Build a comprehensive self-consistency test suite for every mass profile in PyAutoGalaxy.

Create scripts/mass/ in autolens_workspace_test with scripts that verify the internal mathematical consistency of every mass profile independently of the source code implementation. This is the safety net for the broader mass profiles refactoring effort (z_features/mass_profiles_refactor.md).

One script per mass profile category under scripts/mass/: total.py, dark.py, stellar.py, sheets.py, point.py. Each verifies lensing relations (div(alpha)=2kappa, grad(psi)=alpha, laplacian(psi)=2kappa) via numerical differentiation, cross-checks against mass_via_integral/ reference implementations, and supports PYAUTO_MASS_FAST for quick validation.

[Jammy2211]

Shipped — 2026-05-26

PRs

• feat: mass profile self-consistency test suite #124

Summary

Added scripts/mass/ with 7 files: a shared utility module (util.py) and 5 per-category test scripts (total, dark, stellar, sheets, point) that verify every mass profile's convergence, potential, and deflections are internally self-consistent using numerical differentiation of lensing relations. Results: 56 PASS / 1 FAIL / 69 SKIP across 42 profiles.

Session Notes

• Grid axis convention: autoarray's Grid2D.uniform native arrays have y decreasing along axis 0 — np.gradient needs negative spacing for y-derivatives. This was the main debugging issue.
• Raw array returns: Some profiles (PointMass family) return raw numpy arrays instead of autoarray types for convergence. The utility handles both via _to_native_2d / _to_native_vector helpers.
• NotImplementedError: Several profiles (NFW elliptical, gNFW) raise NotImplementedError for potential_2d_from rather than returning zeros — caught with try/except.
• NFWSph finding: grad(psi)=alpha fails at 11% median error for NFWSph despite laplacian(psi)=2kappa passing at 1%. Worth investigating in Phase 3 (MGE/CSE fallback) — potential-deflection mismatch.
• Phase 1 of epic: This test suite is the safety net for PyAutoGalaxy#445 (mass profiles refactor). Next phase: CSE JAX port (autogalaxy/cse_jax_port.md).