feat: potential_correction subpackage — gravitational imaging (phase 3)

[Jammy2211]

Summary

Phase 3 of porting the gravitational-imaging (potential correction) technique into the PyAuto stack (#618): the technique itself, as a new autolens/potential_correction/ subpackage (exported as al.pc, mirroring the autolens/weak precedent). It provides the δψ mesh paired to the data grid, the δψ-only linear inversion of an image residual (FitDpsiImaging), the joint source+δψ inversion with full covariance (FitDpsiSrcImaging), source factories (analytic + pixelized-ITP), af.Analysis classes for evidence-based hyper-parameter sampling, anchor-point rescaling (Suyu's scheme) and the multi-panel fit visualizations.

Ported from Cao et al. 2025's potential_correction package — from the author's updated 2026 tree (modern API: Tracer(galaxies=…), apply_over_sampling, aa.Settings, current AdaptImages), with the numpy evidence formulation of the published GitHub version (https://github.com/caoxiaoyue/lensing_potential_correction). All modules cite it and https://github.com/caoxiaoyue/potential_correction_paper. NumPy/numba only — the JAX fast paths (jax_ops kernels) and the iterative LM correction engine (IterFitDpsiSrcImaging) follow as Phase 4.

Builds on Phase 1 (PyAutoArray#390: mask derivative operators, coarse-mesh interpolation, CurvatureMask/FourthOrderMask regularizations) and Phase 2 (PyAutoGalaxy#505: input pixelized mass profiles).

Notable port improvements over the original:

• A DpsiLinearObj adapter lets every regularization build the δψ regularization matrix through the standard regularization_matrix_from(linear_obj=…) interface (mask-based schemes read .mask, kernel schemes read .source_plane_mesh_grid) — replacing the original's isinstance dispatch and its bespoke covariance_reg classes (autoarray's existing GaussianKernel/ExponentialKernel/MaternKernel are used instead).
• The silent try/except-swallowing rescaled_dpsi fallback is replaced by an explicit anchor-validity check; failed joint inversions return a logged penalty likelihood rather than a printed traceback.
• arc_mask_from is reimplemented on scipy.ndimage (8-connectivity), dropping the original's scikit-image dependency; no new dependencies are introduced.
• Dense@sparse products are coerced to plain arrays at the fit seams (the original relied on jnp coercions).

API Changes

Added only — nothing removed or changed. One new subpackage autolens.potential_correction, exported as al.pc: mesh (RegularDpsiMesh, PairRegularDpsiMesh), pixelizations (DpsiPixelization, DpsiSrcPixelization, DpsiLinearObj), source factories (SrcFactory, AnalyticSrcFactory, PixSrcFactoryITP), fits (FitDpsiImaging, FitDpsiSrcImaging), analyses (DpsiInvAnalysis, DpsiSrcInvAnalysis), plus al.pc.util and al.pc.visualize.
See full details below.

Test Plan

• 25 new tests: hand-computed evidence terms via matrix injection (the original package's unit-test pattern), operator/gradient/PSF-matrix exactness on analytic functions, anchor-plane rescaling exactness, DpsiLinearObj working through both mask-based and kernel regularizations, mesh pairing (partition of unity, linear-function exactness, divisibility/sparsity errors), and end-to-end finite evidence for both FitDpsiImaging and the joint FitDpsiSrcImaging on the real masked_imaging_7x7 fixture (real inversion, current API).
• Full test_autolens suite run before commit (execution contract).
• Follow-up (workspace_test): end-to-end parity vs the original repo's golden outputs on its demo dataset.

Full API Changes (for automation & release notes)

Added

• al.pc.RegularDpsiMesh(factor=1) — the δψ-mesh model component (coarsening factor).
• al.pc.PairRegularDpsiMesh(mask, pixel_scale, dpsi_factor=2) — pairs the δψ mesh to the data grid: cleaned masks, coarse binning, bilinear δψ→data interpolation matrix, sparse 1st/2nd derivative operators of both grids.
• al.pc.DpsiPixelization(mesh, regularization) / al.pc.DpsiSrcPixelization(dpsi_pixelization, src_pixelization) — model components sampled by the analyses.
• al.pc.DpsiLinearObj(mask, points) — linear-object adapter through which any AbstractRegularization builds the δψ regularization matrix.
• al.pc.SrcFactory / AnalyticSrcFactory(source_galaxy) / PixSrcFactoryITP(points, values) — source brightness + gradient evaluation (Delaunay-ITP variant; per-point cross sizes from Voronoi cell areas, with a scipy fallback when aa.Mesh2DVoronoi is unavailable).
• al.pc.FitDpsiImaging(...) — δψ-only linear inversion of an image residual; log_evidence, solve_dpsi, rescaled_dpsi.
• al.pc.FitDpsiSrcImaging(...) — joint source+δψ inversion (block mapping matrix [F_src | −B·D_s·D_ψ], block-diagonal regularization); log_evidence, solve_src_dpsi, best_fit_source/best_fit_dpsi, draw_random_solutions, rescaled_dpsi.
• al.pc.DpsiInvAnalysis / al.pc.DpsiSrcInvAnalysis — af.Analysis classes with evidence likelihoods (failed inversions → logged −1e8 penalty) and fit visualization.
• al.pc.util — gradient_points_from, source_gradient_from, source_gradient_matrix_from, dpsi_gradient_matrix_from, psf_matrix_from, inverse_covariance_matrix_from, log_det_mat, dpsi_rescale_factors_from, split_cross_from, arc_mask_from.
• al.pc.visualize — imshow_masked_data, show_image_irregular(_interpolate), show_fit_dpsi, show_fit_dpsi_src.
• docs/api/potential_correction.rst + docs index entry.

Migration

• None — additive only.

Generated by the PyAutoLabs agent workflow.