dPIE: make Lenstool-native parameterization the default profile

[Jammy2211]

Overview

Make the Lenstool-native parameterization the default dPIE mass profile, so al.mp.dPIEMass / dPIEMassSph expose exactly the parameters readers of Lenstool cluster papers expect (ellipticity, angle_pos, sigma = fiducial v_disp, r_core, r_cut), with the internal ra/rs/b0 parameterization demoted to a clearly-non-standard variant. Re-verify every convention against the Lenstool source/papers, then sweep the downstream workspace (cluster/group examples and the SLaM pipelines, absorbing the deferred lenstool-scaling-slam PR3 from autolens_workspace#265) so the whole stack presents one consistent, standard prescription. End goal: our dPIE perfectly matches the standard Lenstool prescription, so readers of those papers know exactly what our model is doing.

Motivated by the referee comment on the scaling-relation parameterization (Eq. 5) and the follow-up Slack discussion (2026-07): the community convention is reference-anchored Faber–Jackson (σ ∝ L^¼, r_cut ∝ L^½, exponents fixed; normalization the only free parameter), and the dPIE with Lenstool-native parameters is the profile family those papers use.

Plan

• Verify the parameterization conventions against Limousin et al. 2005, Elíasdóttir et al. 2007 (App. A), Bergamini et al. 2019 (Eq. 5) and the Lenstool C source; record the audit in the PR.
• Swap the class hierarchy in PyAutoGalaxy: dPIEMass/dPIEMassSph take the Lenstool-native constructor; internal ra/rs/b0 variant becomes dPIEMassB0/dPIEMassB0Sph plus a dPIEMass.from_b0(...) classmethod.
• Update priors config, exports, unit tests, docstrings.
• Workspace sweep: cluster suite, group scaling_relation, guides, weak a2744 onto the new default with the reference-anchored scaling convention; apply the same convention consistently through the group/cluster SLaM pipelines (absorbs the deferred lenstool-scaling-slam task).
• Re-validate the Lenstool parity scripts in autolens_workspace_test.

Detailed implementation plan

Affected Repositories

• PyAutoGalaxy (primary — library phase)
• autolens_workspace (workspace phase)
• autolens_workspace_test (parity re-validation)

Branch Survey

Repository	Current Branch	Dirty?	Claim
./PyAutoGalaxy	main	clean	claimed by potential-correction-port (PR#505 in flight) — this task queues behind it
./autolens_workspace	main	clean	free
./autolens_workspace_test	main	clean	free

Suggested branch: feature/dpie-lenstool-default
Worktree root: ~/Code/PyAutoLabs-wt/dpie-lenstool-default/ (created by /start_library)
Work classification: Both (library first, workspace follow-up)

Phase 1 — PyAutoGalaxy (library)

All in autogalaxy/profiles/mass/total/dual_pseudo_isothermal_mass.py:

1. Paper/source audit (before code): confirm against Lenstool C source and the papers:
   • sigma is the fiducial v_disp σ_LT, not central σ₀ (σ₀ = √(3/2)·σ_LT — Elíasdóttir 2007 App. A; Bergamini 2019 Eq. 5).
   • b0 = 6·648000·(σ_LT/c)²·(D_LS/D_S) arcsec, distance ratio folded in (Lenstool applies it at deflection time; ours is fully normalized).
   • ellipticity is Lenstool's emass = (a²−b²)/(a²+b²), converted internally to epot = (1−q)/(1+q) = |ell_comps|.
   • r_core/r_cut map 1:1 onto ra/rs (arcsec; kpc variants pre-converted by caller).
   • Scaling-relation form: σ = σ*·(L/L*)^¼, r_cut = r_cut*·(L/L*)^½ anchored to a reference luminosity (BCG/BGG or L*), exponents fixed (Faber–Jackson), only normalization free ⇒ θ_E ∝ L^½.
2. Class swap:
   • Rename current dPIEMass → dPIEMassB0, dPIEMassSph → dPIEMassB0Sph (all math — _ci05f, _mdci05, _pi05, deflections/convergence/potential/hessian — stays here unchanged).
   • Rename dPIEMassLenstool → dPIEMass, dPIEMassLenstoolSph → dPIEMassSph (subclassing the B0 classes; constructor signature centre, ellipticity, angle_pos, sigma, r_core, r_cut, redshift_object, redshift_source, H0, Om0 — H0/Om0 remain flat-float model constants).
   • Move from_lenstool semantics into the default constructor; add dPIEMass.from_b0(centre, ell_comps, ra, rs, b0) / dPIEMassSph.from_b0(...) classmethods returning the B0 variant (the non-standard construction path, per the approved design).
   • Docstrings: default class documents the Lenstool prescription + paper refs; B0 variant explicitly labelled non-standard/internal.
3. Config/exports: update autogalaxy/profiles/mass/total/__init__.py, mass/__init__.py; update autogalaxy/config/priors/mass/total/dual_pseudo_isothermal_mass.yaml (priors keyed per class — sensible Lenstool-style priors on sigma/r_core/r_cut for the default; keep B0 entries).
4. Tests: test_autogalaxy/profiles/mass/total/ — rename/extend so both parameterizations are covered; equivalence test dPIEMass(...) ≡ dPIEMassB0(from converted params); NumPy-only (no JAX in unit tests).
5. Serialization note: any saved results referencing old dPIEMass (ra/rs/b0 signature) will not load into the new class — acceptable (profile shipped 2026-07, no release users yet); call out in PR body.

Phase 2 — autolens_workspace (workspace)

1. scripts/cluster/{modeling,simulator,csv_api,likelihood_function,start_here}.py + scripts/cluster/lenstool/{modeling,data}.py: swap to new default names; express the scaling tier in Lenstool form (reference-anchored: free normalization on the reference member, exponent fixed 0.5, r_cut ∝ L^0.5 truncation scaling).
2. scripts/group/features/scaling_relation/modeling.py: same convention (per the Slack-settled design: einstein_radius_ref on the brightest scaling member, luminosity ratios only).
3. SLaM pipelines (absorbs lenstool-scaling-slam, planned.md): apply the reference-magnitude convention consistently through scripts/group/slam.py + group/cluster-relevant features/*/slam.py variants — the previously-deferred PR3 of autolens_workspace#265.
4. Guides: scripts/guides/profiles/mass.py, light_and_mass_profiles.py; scripts/weak/features/strong_lensing/a2744.py.
5. CSV API: cluster mass.csv profile-name mapping updated in lockstep with the library rename.
6. Notebook regen gotcha (from Feature/gaussian mass #265): generate.py autolens surfaces pre-existing catalogue drift — stage only task-scoped files.

Phase 3 — autolens_workspace_test

• scripts/cluster/{lenstool_parity,likelihood_sanity,csv_api,simulator}.py, scripts/mass/total.py: update names, re-run parity — deflections/convergence/potential must still match Lenstool like-with-like.

Key Files

• PyAutoGalaxy/autogalaxy/profiles/mass/total/dual_pseudo_isothermal_mass.py — the whole profile family (PIEMass, dPIE variants, _b0_from_lenstool_sigma).
• PyAutoGalaxy/autogalaxy/config/priors/mass/total/dual_pseudo_isothermal_mass.yaml — priors per class name.
• autolens_workspace/scripts/cluster/modeling.py — cluster scaling tier (b0 = scaling_factor·L^exp today).
• autolens_workspace_test/scripts/cluster/lenstool_parity.py — the like-with-like Lenstool match.

Notes

• Feature Agent scored this too-large / 4 phases; overridden to the standard 2-stage library→workspace routing under one task — design already settled by the existing dPIEMassLenstool wrapper (PyAutoGalaxy@0a8c6bb4) and the Slack-converged convention.
• dPIEPotential/dPIEPotentialSph (O'Donnell port) are out of scope.
• PyAutoLens needs no source change (re-exports ag.mp).

Original Prompt

Click to expand starting prompt

The final step now is to make our default dPIE the LensTool one, whereas before
I think we made it a classmethod of it, so swap them (e.g. the classmethod can
be the current one which is non standard). Also, compare again to some lens
tool papers to make sure we have the same parameterization, especially given
that SLACK chat, and note that we had some issues making sure our slam.py
pipelines are updated throughout in a consistent fashion. The end goal is for
our dPIE to perfectly match the standard LensTool prescription, so readers of
those papers know exactly what our model is doing.

Full prompt: PyAutoMind/active/dpie_lenstool_default_parameterization.md (context: referee comment on Eq. 5 scaling-relation parameterization + 2026-07 Slack discussion converging on the reference-anchored Faber–Jackson convention).

[Jammy2211]

Paper/convention audit (pre-implementation, read-only)

Verified the current implementation (dual_pseudo_isothermal_mass.py @ main, incl. _b0_from_lenstool_sigma and the dPIEMassLenstool* wrappers) against Elíasdóttir et al. 2007 (arXiv:0710.5636, App. A), Bergamini et al. 2019 (A&A 631, A130), and the existing 6-leg parity script (autolens_workspace_test/scripts/cluster/lenstool_parity.py, which pins the Lenstool C source numerically). All conventions check out; no code-level convention changes are needed for the swap — it is purely a re-parameterization of which class is default.

Convention	Our implementation	Paper/source	Status
Lens strength	b0 = 6·648000·(σ_LT/c)²·(D_LS/D_S) arcsec, distance ratio folded in	E₀ = 6π(D_LS/D_S)(σ_dPIE/c)² rad (A24); ×648000/π → arcsec. Lenstool stores b0 = 6·pia_c2·σ² (set_potfile.c) and applies D_LS/D_S at deflection time (e_grad.c)	✅
E₀-vs-b0 prefactor	deflection factor b0·rs/(rs−ra) with b0 = E₀·(rs²−ra²)/rs²	α = (a+s)/s·E₀·f(R/a,R/s) (A19/A23); algebra: b0·s/(s−a) = E₀·(s+a)/s ✓	✅ (parity leg 6 anchors this against Lenstool-generated deflections)
σ meaning	sigma = fiducial σ_LT (v_disp in .par), never central σ₀	σ₀ = √(3/2)·σ_LT (Elíasdóttir A25 / Bergamini Eq. 5); quoting a measured dispersion as v_disp overestimates mass by 50%	✅ (parity leg 1 cross-checks √(3/2) via the isothermal relation)
Ellipticity	input ellipticity = emass = (a²−b²)/(a²+b²); internal epot = (1−q)/(1+q) = |ell_comps|	ε̂ = (A²−B²)/(A²+B²) (A26) — what .par files and paper tables quote; potential substitution R̃² = X²/(1+ε)² + Y²/(1−ε)² (A21) is exactly our r_em with ε = epot; conversions identical: (1−√(1−ε̂²))/ε̂ ≡ (1−q)/(1+q)	✅
Radii	r_core/r_cut (arcsec) ↔ ra/rs 1:1; kpc variants pre-converted by caller	a (core), s (scale/cut) in A1; Lenstool core_radius/cut_radius	✅
Angle	angle_pos CCW in the tangent plane; WCS flips handled at ingestion (cluster/lenstool/data.py, verified to mas against galcat↔best.par)	Lenstool θ_ε measured anti-clockwise from West, P.A. = θ_ε − 90°	✅ (ingestion-layer concern, documented)
Scaling relation (workspace phase target)	σ_LT,i = σ_ref·(L/L₀)^α, r_cut,i = r_cut_ref·(L/L₀)^β; α = 0.25, β = 0.5 fixed (constant M/L: M ∝ σ²·r_cut ⇒ 2α+β = 1); only the two reference normalizations free, anchored at reference luminosity/magnitude (BCG or mag0)	Limousin+05 / Elíasdóttir+07 §6 / Bergamini+19 Eqs. 4–6 (β_cut = γ−2α+1 generalization; γ=0, α=¼ recovers β=½). Implies θ_E ∝ L^0.5	✅ form already in cluster/group examples (#267/#268); SLaM sweep = this task's phase 2

Notes for implementation:

• Bergamini Eq. 5 context (the referee's point): the community convention fixes the exponents (from Faber–Jackson or measured kinematics) and frees only the reference normalizations — the default priors yaml for the new dPIEMass should put sensible ranges on sigma (km/s), r_core, r_cut (arcsec) mirroring published tables, and the workspace scaling tier expresses everything through the two reference normalizations.
• Elíasdóttir footnote 9: their s is not strictly a truncation radius (ρ ∝ r⁻⁴ beyond, not a hard cut) — keep the docstring language "scale/truncation radius" as-is with the caveat.
• Aperture-vs-fiducial kinematics (Bergamini's c_p projection coefficient, App. C) is out of scope — we take .par-style σ_LT directly; docstrings already warn against feeding measured stellar dispersions.

Audit basis: Elíasdóttir et al. 2007 App. A (A1–A32), Bergamini et al. 2019 (A&A version), Lenstool C source conventions as pinned by the parity script, SMACS J0723 end-to-end reconstruction (cluster/lenstool/, Mahler et al. 2023 model).

Task is queued behind potential-correction-port (PyAutoGalaxy claim, PR #505); library phase starts when that frees.

[Jammy2211]

Library PR Created

PR: #509 (pending-release; full suite 1003 passed; shipped under human-acked pre-existing Heart RED reasons — see session log)

API changes (breaking rename-swap, no numerical changes): dPIEMass/dPIEMassSph = Lenstool-native parameterization (formerly dPIEMassLenstool*); internal (ra, rs, b0) variant → dPIEMassB0/dPIEMassB0Sph + from_b0 classmethods; priors yaml re-keyed; from_lenstool now on the B0 classes.

Workspace impact — option (ii), migration required. Affected downstream scripts (grep-verified):

• autolens_workspace: cluster/{modeling,simulator,csv_api,likelihood_function,start_here}.py, cluster/lenstool/{modeling,data}.py + README, group/features/scaling_relation/modeling.py, guides/profiles/{mass,light_and_mass_profiles}.py, weak/features/strong_lensing/a2744.py (+ generated notebooks)
• autolens_workspace_test: cluster/{lenstool_parity,likelihood_sanity,csv_api,simulator}.py, mass/total.py
• autolens_workspace_developer: visualization_profiling/imaging/cluster.py, scaling_relation_agg/error_make.py, jax_profiling/simulators/cluster.py
• Plus the SLaM scaling-relation sweep (absorbs the deferred lenstool-scaling-slam, PR3 of autolens_workspace#265)

Next: /start_workspace — migrate the scripts onto the new default, express the scaling tier in the reference-anchored Lenstool convention throughout (incl. slam.py pipelines), re-run the 6-leg lenstool_parity.py.

[Jammy2211]

Workspace phase shipped

• autolens_workspace PR: feat: cluster/group examples on Lenstool-native dPIE default + reference-anchored SLaM scaling autolens_workspace#287 (pending-release)
• autolens_workspace_test PR: feat: cluster tests on the Lenstool-native dPIE default autolens_workspace_test#179 (pending-release)
• Both behind the library-first merge gate on PyAutoGalaxy#509.

Highlights: cluster suite now modeled in σ_LT-space (Lenstool .par parameters; scaling tier's single free parameter is sigma_ref in km/s — the referee's interpretable normalization); simple + a2744 datasets converted/regenerated (multiple-image collapse re-verified at ~1e-4"); group SLaM pipelines migrated to the reference-anchored einstein_radius_ref · (L/L_BGG)^0.5 convention (absorbs the deferred lenstool-scaling-slam, PR3 of autolens_workspace#265); 6-leg Lenstool parity + new default-class leg all pass; FD sweeps pass for both parameterizations.

Validation: check_sizes clean; csv_api/guides run clean; modeling + likelihood_function end-to-end in TEST_MODE (N=12); notebooks regenerated (pre-existing potential-correction catalogue drift excluded). Pre-existing, out-of-scope: dPIEPotential grad(ψ)=α FD failure in mass/total.py (O'Donnell profile, untouched); database/scrape/scaling_relation.py intentionally keeps its two-free-parameter compound-prior form (that's what it tests).

Merge order: PyAutoGalaxy#509 → autolens_workspace#287 + autolens_workspace_test#179. Follow-up (unclaimed repo, not in this task): 3 autolens_workspace_developer scripts still reference the old parameterization.

[Jammy2211]

Merged — task complete

All three PRs merged 2026-07-17:

• PyAutoGalaxy#509 (library) — CI green.
• autolens_workspace#287 — CI green (navigator catalogue + smoke all pass).
• autolens_workspace_test#179 — dPIE content green (19/20 smoke); merged with admin override for the single unrelated failure potential_correction/subhalo_recovery.py (statistical dkappa-correlation assertion, already red on main from the potential-correction regression work — not introduced by this task).

Close-out note (bug caught during merge): a2744 start_here composed N=26 instead of N=22 — the default dPIEMass config carries H0/Om0 priors, so a main lens built from a CSV lacking those columns floated the two cosmology constants as free parameters. Fixed by pinning H0/Om0 in the cluster composition loops + adding the columns to the a2744 mass.csv/prep.py (commit on #287). Simulator-written CSVs (simple) already carried them.

The dPIE now matches the standard Lenstool prescription end to end: default dPIEMass/dPIEMassSph take the .par parameters (ellipticity, angle_pos, sigma=v_disp, r_core, r_cut); scaling tiers are reference-anchored (fixed Faber-Jackson exponents, single free normalization); the internal ra/rs/b0 form is dPIEMassB0/dPIEMassB0Sph + from_b0. Closing.

Follow-ups (separate, unclaimed here): pre-existing subhalo_recovery.py smoke failure on main; 3 autolens_workspace_developer scripts still on the old parameterization.