feat: imaging shared-state consumer — AnalysisImaging.shared_state_from + mesh preload reuse (phase 2/4)

[Jammy2211]

Summary

The imaging consumer of the multi-exposure shared-state feature (PyAutoArray#379; design locked on PyAutoLens#599 D1–D6 + the regularization amendment). When several exposures of the same lens are fitted as an af.FactorGraphModel (same wavelength with pixel offsets, different wavelengths, or imaging + interferometer), AnalysisImaging(shared_preloads=True) now computes the source-plane mesh once on the lead factor and every exposure reconstructs on that identical mesh — each mapping its own (offset) data grid onto it.

Mirrors the shipped datacube consumer (#566) with the imaging invariance contract: only the mesh geometry is shared; the mapper, mapping matrix, blurred mapping matrix (per-exposure PSFs/offsets) and regularization matrix (may be data-adaptive) are built per-exposure as before. DatasetModel offsets compose naturally — the lead's offset applies when the mesh is traced; each factor's offset applies to its own grid (the existing updated_via_instance_from mesh-grid transform).

API Changes

All additive and backward compatible — no removals or renames.

• AnalysisImaging(... , shared_preloads=False) — opt-in flag (default off; single-dataset behaviour byte-for-byte unchanged).
• AnalysisImaging.shared_state_from(instance) — the lead-factor hook (autofit.Analysis.shared_state_from protocol): builds aa.PreloadsImaging(source_plane_mesh_grid, image_plane_mesh_grid) from one fit of the lead exposure; returns None unless opted in and the model performs an inversion.
• AnalysisImaging.log_likelihood_function(instance, shared=None) / fit_from(instance, preloads=None) / FitImaging(... , preloads=None) — the shared= threading, mirroring feat: datacube shared-state for AnalysisInterferometer via curvature preloads #566.
• TracerToInversion.image_plane_mesh_grid_pg_list / traced_mesh_grid_pg_list consult preloads and return the shared mesh instead of recomputing (image-mesh + mesh ray-trace skipped); mapper_galaxy_dict then builds this dataset's mapper onto the shared mesh.
• FitImaging pytree registration adds preloads to no_flatten (mirrors FitInterferometer).

Depends on the PyAutoArray PR (must merge first).

Test Plan

• python -m pytest test_autolens/ — full suite passes
• New tests in test_autolens/imaging/model/test_analysis_imaging.py:
  • shared_state_from returns PreloadsImaging carrying mesh only (no F, no mapper); preloaded mesh reused by identity; figure_of_merit and log_likelihood_function shared-vs-unshared parity
  • returns None when not opted in / when no inversion
  • end-to-end: 2-factor FactorGraphModel shared-vs-unshared log-likelihood bit-identical (−58.673099306030444); shared_state_from computed once (lead factor only, monkeypatch counter)
• Downstream/base: test_autoarray/ (896) + test_autogalaxy/ (962) pass against the paired branch

Autonomy

--auto run (Autonomy: safe, feature/medium): four-leg ship gate — tests ✅, smoke ✅ (curated subsets, see issue), review ✅ CLEAN, Heart 🟡 YELLOW acknowledged by user (reason set on issue PyAutoArray#379). Ends at PR-open; merge stays human.

Phase 2/4 of the multi_shared_state_examples epic (design: #599). Phase 3 (workspace example sections + workspace_test shared-vs-unshared assertion script + profiling measurement, mirroring the datacube pattern) follows once this merges.

🤖 Generated with Claude Code