feat: cluster-scale visualization — per-plane critical curves/caustics, large-FoV aplt helpers

[Jammy2211]

Overview

Cluster lenses need visualization that galaxy-scale plots don't provide: arcminute fields of view, tens of mass components, multiple source planes each with their own critical curves and caustics, and per-source multiple-image identification at a glance. A prototype exists (autolens_workspace_test/scripts/cluster/visualization.py, bespoke matplotlib) and PyAutoMind's cluster tracker carries a deferred "aplt plotter promotion" item this task subsumes. Autonomy: supervised --auto, in-session one-shot ship authorization (user directive 2026-07-08); Brain research-first suggestion overridden — scope is defined by the prompt + prototype.

Plan

• New autolens/cluster/plot/ package of module-level aplt helpers (the shipped autolens/weak/plot/ pattern), re-exported into aplt:
  • plot_positions_overlay(...) — full-field log-norm image, per-source coloured observed positions, lens/member markers, optional kpc scale bar.
  • plot_image_group_zooms(...) — per-source zoom-panel grid sized to each image group.
  • plot_critical_curves(...) — tangential (+ radial) critical curves for every source plane of a multi-plane tracer, per-plane colours + legend (galaxy-scale defaults assume one source plane).
  • plot_caustics(...) — the corresponding per-plane caustics in source-plane coordinates.
  • subplot_cluster_dataset(...) — combined mosaic.
• Per-plane curves computed via the existing LensCalc multi-plane machinery (use_multi_plane=True, plane_j=j) — no new solver code; numpy-path only (critical-curve solvers are not vmap-safe; documented).
• Sensible large-FoV defaults: marching-grid resolution guidance for arcminute fields, marker sizes, line weights (from the prototype's cluster-tuned values).
• Unit tests in test_autolens/cluster/plot/ (numpy-only, direct module imports per the weak-plot precedent, Agg backend, tmp-path outputs).
• Rewrite autolens_workspace_test/scripts/cluster/visualization.py to consume the promoted aplt helpers, keeping its file-existence assertions (companion PR, library-first merge order).

Affected Repositories

• PyAutoLens (primary) — parallel to the frozen dpie-lenstool-param claim (its diff = docs/api/mass.rst only; disjoint)
• autolens_workspace_test — parallel to the frozen dpie-lenstool-param claim (its diff = scripts/cluster/lenstool_parity.py; disjoint)

Suggested branch: feature/cluster-visualization · Worktree: ~/Code/PyAutoLabs-wt/cluster-visualization/

Original Prompt

Click to expand starting prompt

$(cat PyAutoMind/feature/cluster/9_cluster_visualization.md)

[Jammy2211]

Shipped to PR-open (in-session one-shot authorization).

PRs (library-first merge order): #578 (pending-release ✓) → PyAutoLabs/autolens_workspace_test#152 (pending-release ✓).

Gate record: tests — 6 new unit tests (incl. the physics check that the z=2 plane's tangential curve exceeds the z=1 plane's) + full PyAutoLens suite 342 pass · smoke — the rewritten scripts/cluster/visualization.py integration script ran end-to-end against the branch: all 5 PNGs produced, per-plane assertion passed (z=1: 3 tangential curves, outermost median radius 13.35"; z=2: 1 curve, 22.53" — curve radius grows with source redshift as required) · review surface CLEAN (727 additive insertions in PyAutoLens; the workspace_test −338 is the prototype→helper rewrite) · Heart YELLOW acked in-session.

The deferred 'aplt plotter promotion' item in the cluster tracker is subsumed. Follow-up candidates noted for the flagship Lenstool example (task 8): per-plane caustic × source-position overlay, and Include2D-level integration once the helper API has been exercised on real data. Merge stays with you.

[Jammy2211]

Both PRs merged (PyAutoLens#578, autolens_workspace_test#152). Per-plane cluster visualization is live on main; the integration script guards it. Closing.