feat: warn when no light lies behind any mass (#532 phase 4)

[Jammy2211]

Discharges phase 4, the last open item of the @rhayes777 API audit epic PyAutoArray#415. With this merged the whole campaign is done.

The question this answers

@rhayes777 was asked on #532 whether warning on z_lens > z_source would be noise in a real multi-plane setup. He did not answer in 12 days. Rather than hold indefinitely or drop it, the question is settled by construction: the warning ships behind its own filterable category, so a user for whom it is noise silences exactly it, and nothing else:

import warnings
from autolens.lens.tracer import MultiPlaneRedshiftWarning

warnings.filterwarnings("ignore", category=MultiPlaneRedshiftWarning)

It is a warning and never an error. Multi-plane ray tracing genuinely supports geometries that look inverted under two-plane "lens and source" naming, so a flagged configuration may be exactly what the user meant. The existing test asserting an inverted tracer still evaluates to a finite image is kept and extended.

The rule is deliberately narrow

It fires only when no lensable thing lies behind any mass, across more than one redshift plane — i.e. nothing in the tracer can be lensed at all. A system with mass at z=1.0 and light at both 0.5 and 1.5 is a real multi-plane configuration and stays quiet, because some of its light is lensed.

Three false-positive classes found while building this

This is the part worth reviewing, because the first version was wrong and the test suite caught it:

Class	Why it broke	Fix
Pixelized source	carries no LightProfile at all	counted as lensable
Point source	carries neither light profile nor pixelization	counted as lensable
Empty placeholder galaxy	al.Galaxy(redshift=1.0) with nothing in it — a model being composed	check stands down

Counting only LightProfile made the warning fire in ~10 existing legitimate tests, including every pixelized-source case — core PyAutoLens usage, and precisely the noise the reporter asked about. Hence LENSABLE_CLS = (LightProfile, Pixelization, Point, PointSolved) plus the empty-galaxy stand-down.

Evidence it is now quiet: the warning fires in zero tests outside its own regression module, and the suite's total warning count is back to its pre-change baseline of 18 (it peaked at 44 with the naive rule).

I'd also flag: my first implementation silently swallowed an AttributeError from a wrong class reference (ag.MassProfile does not exist), so the warning never fired at all and every check looked like it passed. Caught by testing the reported case explicitly rather than trusting a green suite. The broad except is gone.

API Changes

• New public symbol: autolens.lens.tracer.MultiPlaneRedshiftWarning, a UserWarning subclass.
• New public constant: autolens.lens.tracer.LENSABLE_CLS.
• No signature, name or return-type changes. No behaviour changes beyond an emitted warning — nothing that previously worked stops working, and nothing that previously raised stops raising.

Tracer safety

Redshifts can be free model parameters (a traced subhalo redshift under jax.jit), so only concrete redshifts are compared and a traced redshift makes the check skip rather than coerce a traced boolean — the same is_concrete_scalar gate used across the rest of the audit work. Pinned by a test using a stand-in whose __bool__ raises.

Test Plan

• Full suite: 532 passed, 1 skipped (+13 on this branch). Zero regressions.
• Warning fires on the reported inverted case; message names both sets of redshifts.
• Silencing by category verified.
• Seven legitimate configurations asserted quiet, including genuine multi-plane, lens-with-its-own-light, single-plane, mass-only, light-only and empty.
• The three false-positive classes above each have a regression test.

---

Generated by Claude Code