docs: adopt LensTool reference-magnitude scaling convention

[Jammy2211]

Overview

Adopt the LensTool reference-magnitude (mag0) convention for the scaling-relation tier across the autolens_workspace examples, replacing the non-standard max(sample-luminosity) anchor. A referee (Limousin 2005/2007, Elíasdóttir 2007, Bergamini 2019) noted the scaling-relation normalization should be anchored to a fixed reference magnitude / luminosity (LensTool's mag0, conventionally the BCG magnitude), not the max luminosity of the current sample, and the exponent should be fixed at the Faber-Jackson value, not fitted. This makes the normalization an interpretable, prior-definable quantity and invariant to which galaxies are in the tier. The change is a strict reparameterization — simulated member physics stays identical.

Scope was validated by grep on current main and an adversarial cross-check (ChatGPT + local verification): the inventory is 3 feature families + 2 production SLaM pipelines (4 sites).

Plan

• Everywhere, replace max(scaling luminosities) with an explicit fixed reference luminosity (fiducial L*, documented as settable to a BCG reference magnitude); luminosity_ratio = L / reference_luminosity; exponent fixed at 0.5.
• Full PIEMD fidelity in the dPIE cluster example: scale ra (core radius), rs (cut radius) and b0 all ∝ L^0.5 — add ra_ref and reparameterize simulator truths so member physics is byte-identical.
• Re-anchor the two "odd" cases (imaging feature example + both SLaM pipelines) off raw-luminosity/free-exponent onto the standard convention (one convention everywhere; no free-exponent variant retained).
• Keep each simulator and its model on the same explicit reference so members stay consistent by construction (avoids the rs-mismatch trap).
• Document the Bergamini kinematic exponents (σ ∝ L^0.27) as the "when kinematics exist" refinement, not the default.
• Regenerate notebooks; smoke-test each phase.

Delivered as three sequential PRs against this issue (size is too large for one clean PR).

Detailed implementation plan

Affected Repositories

• autolens_workspace (primary)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_workspace	main	dirty (stray dataset .fits/.json simulator outputs, unrelated)

Suggested branch: feature/lenstool-scaling-reference-magnitude
(worktree branched from clean origin/main)

Resolved decisions (user, 2026-07-10)

• (a) dPIE core radius ra: scale it ∝ L^0.5 (add ra_ref; update cluster simulator truth for ra too).
• (b) Imaging toy AND SLaM: re-anchor both to the standard fixed-0.5 reference-magnitude convention.
• (c) Bergamini σ ∝ L^0.27: mention in docs as the "when kinematics exist" refinement, not the default.

Reparameterization math

To keep simulated member physics identical when L_ref changes: p_ref_new = p_ref_old * (L_ref_new / L_ref_old)**0.5. Worked truths for fiducial L*=1.0: group theta_E_ref 0.135 → 0.201; cluster b0_ref 0.12 → 0.190, rs_ref 10.0 → 15.8. Trap: simulator and model must share the same explicit reference luminosity, else the cluster's fixed rs values mismatch.

Implementation Steps (phased)

1. PR 1 — Cluster (scripts/cluster/{modeling,start_here,simulator,likelihood_function}.py): explicit reference_luminosity; add ra_ref scaling (∝ L^0.5); simulator truths b0_ref 0.12→0.190, rs_ref 10→15.8, ra scaled from a ref; keep exponent fixed 0.5; rewrite docstrings (α = b0/θ_E at the reference magnitude; Bergamini note). Regenerate cluster notebooks. Smoke.
2. PR 2 — Group + imaging feature examples (scripts/group/features/scaling_relation/* + scripts/imaging/features/scaling_relation/*): group is Isothermal → θ_E reference anchor only (fiducial L* since the BGG has no photometry); imaging moves from scaling_factor·L^freeExp to θ_E_ref·(L/L_ref)^0.5. Check: imaging simulator uses exponent 1.0 (einstein_radius=0.3·L^1.0) — confirm its two members are equal-luminosity (exponent moot) or align the simulator to 0.5 so model and truth match. Regenerate notebooks. Smoke.
3. PR 3 — SLaM production pipelines (scripts/group/slam.py ×2 sites, scripts/group/features/linear_light_profiles/slam.py ×2 sites): re-anchor both source-lp stages to the standard convention. Regenerate notebooks. Smoke.

Do NOT touch (verified false positives)

• scripts/guides/advanced/multi_plane.py:201 — scaling_factor there is cosmology.scaling_factor_between_redshifts_from (name collision).
• group/modeling.py, group/features/multi_gaussian_expansion/modeling.py, imaging|interferometer/features/extra_galaxies/modeling.py, cluster/csv_api.py, modeling_for_luminosities.py — docstring cross-references only.

Key Files

• scripts/cluster/modeling.py, start_here.py, simulator.py, likelihood_function.py — dPIE cluster tier (PR 1).
• scripts/group/features/scaling_relation/{modeling,fit,likelihood_function,simulator}.py — Isothermal group tier (PR 2).
• scripts/imaging/features/scaling_relation/{modeling,fit,likelihood_function,simulator}.py — imaging tier, re-anchor (PR 2).
• scripts/group/slam.py, scripts/group/features/linear_light_profiles/slam.py — production SLaM pipelines, 4 sites (PR 3).
• Notebooks regenerated via PyAutoBuild after each phase.

Testing

python .github/scripts/run_smoke.py per phase. TEST_MODE=2 checks model composition; the reparameterization is structurally safe.

Original Prompt

Click to expand starting prompt

Adopt the LensTool reference-magnitude (mag0) convention for the scaling-relation tier across the autolens_workspace examples, replacing the non-standard max(sample-luminosity) anchor. Referee point (Limousin 2005/2007, Eliasdottir 2007, Bergamini 2019): the scaling-relation normalization should be anchored to a FIXED reference magnitude / reference luminosity (LensTool's mag0, conventionally the BCG magnitude), NOT the max luminosity of the scaling sample; the exponent should be FIXED (Faber-Jackson / fundamental plane), not fitted. DECISION (user-selected): use an explicit fixed reference-luminosity/magnitude CONSTANT documented as settable to the BCG (a fiducial L* where no BCG photometry exists), so einstein_radius_ref/b0_ref = the Einstein radius / lens strength of a galaxy at the reference magnitude. This is a strict reparameterization (alpha_new = alpha_old*(L_ref_new/L_ref_old)**exponent), so simulated member physics MUST stay identical and priors must still bracket the reparameterized truth.

THREE example families are affected (verified by grep on current main), plus a VERIFIED SLaM inventory:

1. cluster/ (modeling.py, start_here.py, likelihood_function.py, simulator.py): dPIE; b0 = b0_ref*(L/L_ref)0.5; exponent already fixed 0.5; rs already scaled ~L0.5. Change the anchor + docstrings; also scale ra.
2. group/features/scaling_relation/ (modeling.py, fit.py, likelihood_function.py, simulator.py): Isothermal (no truncation radius); theta_E = theta_E_ref*(L/L_ref)*0.5; exponent already fixed 0.5. Change the anchor + docstrings. Group BCG has NO photometry (centre only) -> fiducial L.
3. imaging/features/scaling_relation/ (modeling.py, fit.py, likelihood_function.py, simulator.py): the ODD ONE — theta_E = scaling_factor * L**scaling_exponent, both free, no reference ratio. Re-anchor to fixed 0.5.
4. SLaM pipelines: group/slam.py (2 sites) and group/features/linear_light_profiles/slam.py (2 sites) — old free-exponent raw-luminosity form; re-anchor.

RESOLVED DECISIONS (user): scale ra ∝ L^0.5 (full fidelity); re-anchor imaging + SLaM; document Bergamini σ∝L^0.27 as the kinematic refinement. Regenerate notebooks. Files under autolens_workspace/scripts/.

[Jammy2211]

PR 1/3 open: cluster — #267 (behind pending-release).

Adopts the LensTool reference-magnitude (mag0) convention for the cluster dPIE scaling tier: explicit fixed reference luminosity (not max(sample)), exponent fixed at 0.5, and full PIEMD fidelity (ra/rs/b0 all scale ∝ L^0.5; ra was previously flat). Strict reparameterization — b0/rs member physics preserved <1%, ra now scales. Simulator + model share the same reference; cluster dataset regenerated; cluster/simple added to the .gitignore allowlist.

Next: PR 2 (group + imaging feature examples), PR 3 (SLaM pipelines).

[Jammy2211]

Status update — examples done, SLaM deferred.

Shipped + merged:

• PR docs: LensTool reference-magnitude scaling convention (PR 1/3: cluster) #267 (cluster / dPIE) — reference-magnitude anchor, exponent fixed 0.5, full ra/rs/b0 ∝ L^0.5 scaling, dataset regenerated.
• PR docs: LensTool reference-magnitude scaling convention (PR 2/3: group + imaging) #268 (group + imaging feature examples) — reference-magnitude anchor, exponent fixed 0.5; members preserved so no dataset regen.

Deferred (not shipped): the SLaM production pipelines (group/slam.py, group/features/linear_light_profiles/slam.py, 4 sites). These use physical luminosities and the right choice of reference (BGG vs fixed reference magnitude) + prior calibration on einstein_radius_ref needs more thought than a fiducial L_ref=1.0. The author is working out the correct approach separately (a design brief + community consultation are in flight). The in-progress branch was discarded; nothing SLaM was committed.

Leaving this issue open to track the SLaM follow-up.