feat: twins stellar-plus-dark transformation and diagnostics (lenstwin 3) #805

Affected Repositories

• PyAutoLens (primary; only repo). It depends on PyAutoGalaxy main carrying fix: LM damping parity + stall guards for potential-correction iterative engines #676 (merged 7701202).

Branch Survey

No active.md claim on PyAutoLens.

Suggested branch: feature/lenstwin-p3-stellar-dark

Rulings

• R3: the aperture is a circle of radius θ_E,parent. θ_E is computed for the whole lens model via LensCalc, and the circle is centred on the replaced galaxy's mass centre. M_ref is the projected mass of the replaced component(s) inside it, by grid integration. External shear and other galaxies are untouched and excluded from M_ref.
• R4: the first halo is NFWSph, centred on the light, with a fixed physical r_s.
• R6: the diagnostics plotter lives in the library and follows the aplt conventions.

Implementation Steps

1. autolens/twins/aperture.py: einstein_radius_aperture_from(tracer, grid, centre, **integrator_settings) -> ag.CircularAperture. θ_E comes from ag.LensCalc.from_tracer(tracer).einstein_radius_from(grid); return θ_E alongside the aperture (or as an attribute) so the record can quote it.
2. autolens/twins/transform/stellar_dark.py: ReplaceTotalMassWithStellarPlusDark(galaxy, light, f_dark=0.5 | budget, dark_cls=al.mp.NFWSph, scale_radius_kpc, keep_shear=True, aperture_settings=None, **dark_fixed).
   • Galaxy addressing: verify how galaxies are named in a tracer loaded from tracer.json, and reuse ReferenceModel's roles/naming.
   • light names the galaxy's MGE Basis attribute.
   • apply(twin) must not mutate anything. It deep-copies the tracer, removes the galaxy's total-mass profile(s) (every MassProfile attribute except ExternalShear), and adds a stellar Basis of lmp.Gaussian and the dark profile from ag.MassBudget(aperture, {galaxy: {...}}).solve(...).
   • r_s conversion: cosmology.arcsec_per_kpc_from(redshift=galaxy.redshift) * scale_radius_kpc.
   • gNFW needs coarse aperture_settings, because it does one quad per point.
   • The new tracer must serialise (al.to_dict).
3. Record (TransformationRecord):
   • requested: all arguments.
   • procedure: convention text citing PyAutoGalaxy/docs/api/mass_budget.rst, the derived numbers from MassBudget.solve, θ_E,parent, r_s in kpc and in arcsec, redshift, and cosmology name.
   • changed: component paths.
   • side_effects: shear kept, the twin's own θ_E (reported, not asserted), and the dark centre tied to the light.
   • preserved: ["projected mass of <galaxy> inside theta_E,parent"].
   • The dicts must hold no None values (al.from_dict drops them; see the note in record.py).
   • Make sure the flat truth parameters (Υ, κ_s, r_s, inner slope, f_dark) appear in twin.json via the records.
4. autolens/twins/compare.py: compare(parent, twin, grid=None) -> TwinComparison.
   • Fields: convergence difference, deflection difference (y, x), enclosed-mass profiles M(<R) for both (via ag.mass_angular_within_circle_via_grid_from on a radius list), tangential critical curves for both (LensCalc), θ_E for both, and delta_chi_squared_image. That last one is Σ(I_twin − I_parent)²/σ² over the parent setup's masked grid with the noise map, using Twin.noise_free_image_2d.
   • compare_to_data(twin, dataset) -> float: χ²(twin | data) − χ²(parent | data) via two al.FitImaging; raise for pixelised sources.
5. autolens/twins/plot/twin_plots.py: subplot_twin_comparison(comparison, output_path=None, output_filename="twin_comparison", output_format="png"). Panels: parent image, twin image, (twin − parent)/σ, convergence difference, M(<R) for both, and critical curves overlaid. Follow autolens/lens/plot/tracer_plots.py (helpers from autogalaxy.util.plot_utils, output_figure). Export from autolens/plot/__init__.py.
6. Exports: autolens/twins/__init__.py exports compare, compare_to_data, TwinComparison, einstein_radius_aperture_from, and the transformation under transform.
7. Docs: extend docs/api/twins.rst.
8. Tests (test_autolens/twins/test_stellar_dark.py, test_compare.py; NumPy only, coarse grids):
   • The witness: on a fixture SIE + shear + MGE-light reference with a 50/50 budget, the stellar and dark masses inside θ_E,parent are each 0.5 ± 1e-3 of M_ref, and the shear is unchanged.
   • The record round-trips through dict and through SimulatedTwin save/reload.
   • No mutation; kpc → arcsec conversion; a gNFW inner_slope round trip; a two-galaxy budget raises.
   • compare of a twin with itself is zero; Δχ²_image > 0 for the transformed twin; compare_to_data gives finite numbers on the 7x7 fixture.
   • The subplot writes a PNG.
9. PR body: say the public API grew, and quote R3/R4/R6.

Key Files

• autolens/twins/twin.py, record.py, transform/{__init__,identity}.py, reference.py (galaxy roles)
• PyAutoGalaxy autogalaxy/operate/mass_budget.py, operate/lens_calc.py (LensCalc.from_tracer, einstein_radius_from, tangential_critical_curve_list_from)
• autolens/lens/plot/tracer_plots.py, autolens/plot/__init__.py — plotting conventions
• test_autolens/twins/test_twins.py — the fixture fit directory pattern

Out of scope

The identifiability experiment (phase 4), library ingestion and multi-galaxy normalisation (phase 5, R7), workspace and assistant (phase 6), other transformations.

PyAutoMind draft/feature/autolens/lenstwin_p3_stellar_dark_transform.md (Type: feature · Target: autolens · Difficulty: large · Consequence: judge · Epic: lenstwin · Phase: 3 · Filed: 2026-10-28).

Witness: on a fixture SIE(+shear) reference with an MGE lens light, twin.apply(transform.ReplaceTotalMassWithStellarPlusDark(...)) with a 50/50 budget yields a twin whose stellar and dark projected masses inside θ_E,parent are each 0.5 ± 1e-3 of M_ref, keeps the shear unchanged, and appends a TransformationRecord that round-trips through al.to_dict/al.from_dict and SimulatedTwin.output_to/from_directory; al.twins.compare(baseline, twin) returns Δχ²_image > 0 and Δχ²_image(baseline, baseline) == 0; aplt.subplot_twin_comparison writes a PNG.

What to build: (1) an Einstein-radius aperture helper in autolens/twins/; (2) transform.ReplaceTotalMassWithStellarPlusDark (galaxy, light basis, f_dark or ag.MassBudget, dark class default NFWSph, r_s in kpc via the setup cosmology, keep_shear, aperture settings), non-mutating, with a full TransformationRecord whose preserved names the aperture mass; (3) al.twins.compare (convergence and deflection differences, M(<R), critical curves, θ_E, Δχ²_image) and compare_to_data (Δχ²_data via FitImaging, parametric sources only); (4) the plotter autolens/twins/plot/twin_plots.py::subplot_twin_comparison, exported from aplt (R6); (5) docs in docs/api/twins.rst. Tests on the 7x7 fixtures. Out of scope: phases 4–6, other transformations. Say in the PR that the public API grew.