feat: add stellar + dark + lmp light-and-mass profiles guide

[Jammy2211]

Overview

Follow-up to #178 (shipped via #179). This task adds
scripts/guides/profiles/light_and_mass_profiles.py to autolens_workspace, the third and
final guide in the profiles/ folder — paired with light.py (#86 / #87) and mass.py
(#179). Where those two cover pure light and parametric lens mass respectively, this
guide covers the stellar + dark + combined light-and-mass profiles that decompose a
lens galaxy into its constituent matter components.

Scope:

• Stellar mass profiles in al.mp.* (Sersic, Chameleon, Gaussian, GaussianGradient,
  SersicCore, SersicGradient, DevVaucouleurs, Exponential + *Sph variants).
• Dark-matter mass profiles in al.mp.* — the NFW family (NFW, gNFW, cNFW, NFWTruncated)
  plus their MCR (mass-concentration), virial-mass, and scatter variants.
• Combined light-and-mass profiles in al.lmp.* — one object emits both
  image_2d_from (light) and convergence_2d_from (mass) through a shared
  mass_to_light_ratio.
• Linear combined light-and-mass profiles in al.lmp_linear.* — the inversion-aware
  variant of the lmp family.

This completes the three-guide set agreed in #178: pure light, pure lensing mass, and
matter-decomposition.

Plan

• Add scripts/guides/profiles/light_and_mass_profiles.py to autolens_workspace,
  structured as a single-page tour of every stellar / dark / lmp / lmp_linear profile.
• Mirror the section flow of light.py and mass.py so the three guides read as a coherent
  set; use the same """__Section__""" docstring-as-prose style.
• Detailed stellar example uses al.mp.Sersic (stellar mass parameterised by intensity +
  effective_radius + sersic_index + mass_to_light_ratio); show convergence_2d_from and the
  lensed source image through a Tracer.
• Detailed dark example uses al.mp.NFW; show convergence_2d_from, plot in log10 to
  highlight the cuspy profile, explain kappa_s / scale_radius.
• Dedicated section for the NFW variant menagerie — MCR (Duffy / Ludlow concentration-mass
  relations), Virial-mass parameterisations, Scatter (Ludlow-with-scatter), and Truncated.
  One-liner construction + a sentence on when to use each.
• Combined-light-and-mass section uses al.lmp.Sersic and shows that the same object emits
  both image_2d_from (light) and convergence_2d_from (mass) via the shared
  mass_to_light_ratio parameter — this is the headline feature of the lmp namespace.
• Linear combined-light-and-mass section explains al.lmp_linear.* (intensity-via-inversion
  variant) and notes the linear semantics carry over from lp_linear.* to the joint
  light+mass treatment; points readers to scripts/imaging/features/linear_light_profiles/
  for the workflow.
• Composing-a-decomposed-bulge+halo-model section builds a realistic af.Model with a
  stellar Sersic mass + NFW halo on the lens galaxy and prints model.info, then realises
  an instance via prior medians and drops it into a Tracer.
• Remaining Profiles Walkthrough compact-lists every stellar / dark / lmp / lmp_linear
  profile not already shown, with one short convergence_2d_from (or image_2d_from for
  the lmp light side) block per profile.

Detailed implementation plan

Affected Repositories

• autolens_workspace (primary) — new guide
• PyAutoLens — read-only reference
• PyAutoGalaxy — read-only reference

Work Classification

Workspace (autolens_workspace only).

Branch Survey

Repository	Current Branch	Dirty?	Notes
./autolens_workspace	main	dirty (smoke-run dataset noise)	worktree gets a clean copy
./PyAutoLens	main	clean	reference only
./PyAutoGalaxy	main	clean	reference only

Suggested branch: feature/light-mass-profiles-guide
Worktree root: ~/Code/PyAutoLabs-wt/light-mass-profiles-guide/
Routing: workspace-dev → /start_workspace.

Section Layout (11 sections)

1. Overview & Docs URL — explain the three-guide split: light.py (light), mass.py
   (parametric lens mass), this guide (stellar + dark + lmp decomposition). Link to the
   published API reference.
2. All Profiles (Survey) — catalogue of every stellar / dark / lmp / lmp_linear class
   with one-line construction, no quantity evaluation.
3. Stellar Mass Detailed Example — al.mp.Sersic(intensity=..., effective_radius=..., sersic_index=..., mass_to_light_ratio=...). Plot convergence_2d_from and the lensed
   source image via Tracer.
4. Dark Mass Detailed Example — al.mp.NFW(centre, ell_comps, kappa_s, scale_radius).
   Plot convergence_2d_from (linear) and convergence_2d_from (log10) to show the cusp.
5. NFW Variants — gNFW (free inner slope), cNFW (cored NFW), NFWTruncated,
   NFWMCR* (Duffy / Ludlow concentration-mass relations remove one free parameter),
   NFWMCRScatter* (Ludlow with concentration scatter), *VirialMassConc* (parameterised
   by M_200 + concentration). One-line construction per family + a sentence on when each
   is appropriate.
6. Combined Light + Mass Profiles (al.lmp) — al.lmp.Sersic showing the same object
   evaluates image_2d_from (light) AND convergence_2d_from (mass) via shared
   mass_to_light_ratio. Plot both side-by-side. This is the headline feature.
7. Linear Combined Light + Mass (al.lmp_linear) — one-line API; explain the intensity-
   via-inversion semantics carry over from al.lp_linear. Point to
   imaging/features/linear_light_profiles/ for the fitting workflow.
8. Composing a Decomposed Bulge+Halo Model — af.Model(al.Galaxy, redshift=0.5, bulge=af.Model(al.mp.Sersic), dark=af.Model(al.mp.NFW)) for the lens; bog-standard
   Sersic for the source. Print model.info. Note the API is identical to swapping a
   parametric Isothermal.
9. Model Instance from Decomposed Model — instance_from_prior_medians() on the
   collection; build a Tracer; plot tracer.image_2d_from.
10. Remaining Profiles Walkthrough — compact convergence_2d_from block per stellar /
    dark / lmp / lmp_linear profile not yet shown. For al.lmp.* profiles also show
    image_2d_from to drive home the dual-output property.
11. Back-References — closing pointer to light.py and mass.py as the companion
    guides in the same folder.

Verification Approach

1. Verify constructor signatures by reading source before adding each profile — light.py
   bit on SersicCore.intensity_break and mass.py bit on dPIEMass(ell_comps=(0,0)) are
   the same gotcha to avoid.
2. Verify plotting compatibility — same np.hypot / Array2D wrap pattern from
   mass.py for vector quantities. lmp image_2d_from should return Array2D like the
   light side; convergence_2d_from likewise.
3. Smoke-run the new script under PYAUTO_TEST_MODE=2 + all skip flags before
   /ship_workspace.

Key Files

• autolens_workspace/scripts/guides/profiles/light_and_mass_profiles.py — new
• autolens_workspace/.script_sizes.json — refresh
• autolens_workspace/scripts/guides/profiles/__init__.py — already exists, no change

Style / constraint notes

• Workspace docstring-as-prose style ("""__Section__""" headers).
• Science-teaching prose stays on Opus.
• Mirror the section flow of light.py / mass.py so the three guides read as a triplet.
• Out of curated smoke_tests.txt (small-subset policy).

Original Prompt

Click to expand starting prompt

Follow-up to mass_profiles.md (issue #178, shipped via #179): add a
scripts/guides/profiles/light_and_mass_profiles.py guide to
autolens_workspace, paired with the existing light.py (#86/#87) and
mass.py (#179) guides in the same folder.

Scope (per user direction):

• Stellar mass profiles in al.mp.* (Sersic, Chameleon, Gaussian,
  GaussianGradient, SersicCore, SersicGradient, DevVaucouleurs,
  Exponential + *Sph variants).
• Dark-matter mass profiles in al.mp.* (NFW family: NFW, gNFW, cNFW,
  NFWTruncated, plus their MCR / virial-mass / scatter variants).
• Combined light-and-mass profiles in al.lmp.* (one object emitting
  both image_2d_from and convergence_2d_from via a shared
  mass_to_light_ratio).
• Linear combined light-and-mass profiles in al.lmp_linear.* —
  include alongside the standard lmp profiles.

Section flow mirrors light.py / mass.py so the three guides read as
a coherent set.

[Jammy2211]

Shipped — 2026-05-18

PRs

• docs: add stellar + dark + lmp light-and-mass profiles guide #181 (merged)

Summary

Added scripts/guides/profiles/light_and_mass_profiles.py to autolens_workspace, completing the three-guide profiles/ set (light, mass, light-and-mass). Covers stellar mass profiles (al.mp.Sersic family), the full dark-matter NFW menagerie (al.mp.NFW, gNFW, cNFW, NFWTruncated + their MCR / Virial / Scatter reparameterisations), the combined al.lmp.* namespace whose objects emit both image_2d_from (light) and convergence_2d_from (mass) via a shared mass_to_light_ratio, and the linear inversion-aware al.lmp_linear.* variant.

The headline Combined Light + Mass Profiles section demonstrates the dual-output property side-by-side, and a Composing a Decomposed Bulge+Halo Model section walks through the canonical recipe of attaching a stellar Sersic mass + NFW halo to one lens galaxy so their convergences sum during the fit.

Session Notes

• Three-guide trilogy complete: light.py (fix: restore observational datasets and clear 28 autolens integration failures #86/fix: enable fits_make / png_make smoke tests #87) → mass.py (docs: add mass profiles guide at scripts/guides/profiles/mass.py #179) → light_and_mass_profiles.py (docs: add stellar + dark + lmp light-and-mass profiles guide #181). The fold here puts pure light, parametric lens mass, and matter decomposition each in their own page, paired by the same section flow.
• NFW variants section consolidated: rather than listing every variant blow-by-blow, the guide explains the axis each variant adds (inner_slope / core / truncation / MCR / Virial / scatter) and shows one representative plot. This keeps the section readable even though the namespace exposes ~17 NFW classes.
• al.lmp dual-output is the headline: the rest of the guide builds toward demonstrating that al.lmp.Sersic.image_2d_from and al.lmp.Sersic.convergence_2d_from come from the same parametric Sersic shape with mass_to_light_ratio as the single conversion knob. This is what users are most likely to actually use in a decomposed lens-mass fit.
• al.lmp_linear constructor is identical to al.lmp despite the "linear" name — the difference only shows up inside a model fit, where the inversion solves intensity rather than treating it as a free non-linear parameter. The guide notes this and points to the existing imaging/features/linear_light_profiles/ package for the workflow.
• Out-of-scope, possible follow-ups:
  • al.lmp.* / al.lmp_linear.* are not yet documented on the PyAutoLens API reference page (docs/api/mass.rst). The mass.py issue (feat: add mass profiles guide at scripts/guides/profiles/mass.py #178) also noted gaps for ExternalPotential, SMBH*, dPIE*, several NFW variants. Worth a single library docs-sync PR if you want full reference coverage.
  • GaussianGradient uses a different parameter set from SersicGradient (mass_to_light_ratio_base + mass_to_light_gradient + mass_to_light_radius vs. just mass_to_light_gradient). Worth checking whether this inconsistency is intentional.