docs: normalize __PSF Convolution__ docstring section across simulator.py examples

[Jammy2211]

Overview

Standardize how the PSF convolution / convolve_over_sample_size input is documented across every simulator.py example in both autolens_workspace and autogalaxy_workspace. The reference simulators get a dedicated __PSF Convolution__ docstring section (in __Contents__), with the over-sample note written as docstring prose rather than a run of # comments. All other example simulators simply gain the convolve_over_sample_size=1 input on their from_gaussian(...) call, with no extra prose (users are assumed to have read the base simulator.py).

Plan

• Give the reference simulators (imaging/simulator.py in both workspaces, plus group/simulator.py in autolens) a __PSF Convolution__ section: header, __Contents__ entry, and the over-sample explanation converted from # comments into docstring prose.
• autogalaxy imaging/simulator.py is upgraded from its inline one-liner to the full section (galaxy terminology, ag.).
• Every other simulator with a real-space Gaussian PSF (38 files) gets convolve_over_sample_size=1 added as the first argument to its from_gaussian(...) call — no header, no prose.
• Interferometer / point-source-multiple / weak-base simulators (no real-space PSF) are out of scope.
• CRLF autogalaxy files edited CRLF-safe so each diff stays a single line.

Detailed implementation plan

Affected Repositories

• autolens_workspace (primary)
• autogalaxy_workspace

Branch Survey

Repository	Current Branch	Dirty?
./autolens_workspace	main	clean (source); generated data products only
./autogalaxy_workspace	main	clean (source); generated data products only

Suggested branch: feature/psf-convolution-docstring

Implementation Steps

1. Tier A (full section, 3 files): autolens_workspace/scripts/imaging/simulator.py (add header + Contents entry + prose-ify the existing # over-sample note), autogalaxy_workspace/scripts/imaging/simulator.py (upgrade inline one-liner → full section), autolens_workspace/scripts/group/simulator.py (mirror imaging).
2. Tier B (input-only, 38 files): insert convolve_over_sample_size=1, as the first arg of each from_gaussian(...) call. Handles single-call, list-comprehension (multi/), and indented variants. CRLF-safe for the 10 autogalaxy CRLF files.
3. Regenerate notebooks for both workspaces (PyAutoBuild generate.py).
4. Smoke-check representative simulators run end-to-end.

Key Files

• autolens_workspace/scripts/imaging/simulator.py — canonical reference (already carries the prose + convolve_over_sample_size code; needs header/Contents/prose-ify).
• autogalaxy_workspace/scripts/imaging/simulator.py — upgrade to full section.
• autolens_workspace/scripts/group/simulator.py — mirror imaging.
• 38 further simulator.py files with from_gaussian — input-only edit.

Original Prompt

Click to expand starting prompt

The new workspaces document the PSF convolution. The reference documentation style is:

"""
All CCD imaging data (e.g. Hubble Space Telescope, Euclid) are blurred by the telescope optics when they are imaged.

The Point Spread Function (PSF) describes the blurring of the image by the telescope optics, in the form of a
two dimensional convolution kernel. The lens modeling scripts use this PSF when fitting the data, to account for
this blurring of the image.

In this example, use a simple 2D Gaussian PSF, which is convolved with the image of the lens and source galaxies
when simulating the dataset.
"""
psf_convolve_over_sample_size = 1

Requirements: each reference simulator.py gets a __PSF Convolution__ docstring section (in Contents), with the over-sample note as docstring prose (not # comments). Other simulators that fold PSF under __Simulate__ don't need the header but should list the input as =1 on the from_gaussian call. group/simulator.py gets the same doc as imaging/simulator.py. Applies to both autogalaxy_workspace and autolens_workspace.

[Jammy2211]

Shipped (awaiting merge)

Both workspace PRs are open behind pending-release:

• autolens_workspace: docs: __PSF Convolution__ section across simulator.py examples #258
• autogalaxy_workspace: docs: __PSF Convolution__ section across simulator.py examples autogalaxy_workspace#124

What changed — 41 simulator.py files with a real-space Gaussian PSF:

• Tier A (full section, 3 files): imaging/simulator.py (both workspaces) and autolens group/simulator.py gained a __PSF Convolution__ docstring section (added to __Contents__), with the over-sample note converted from # comments into docstring prose.
• Tier B (input-only, 38 files): convolve_over_sample_size=1 added as the first argument to from_gaussian(...). The 10 autogalaxy CRLF files were edited CRLF-safe (one-line diffs).
• Interferometer / point-source-multiple / weak-base simulators (no real-space PSF) were correctly out of scope.

Validation: all 40 changed scripts compile; 5 representative simulators (both Tier-A references, a list-comp Tier-B, a CRLF Tier-B) run end-to-end under fast-mode flags. Notebooks + navigator catalogue regenerated. Heart was YELLOW at ship (all reasons pre-existing/unrelated; acknowledged).

One judgment call to flag: the over-sample note references guides/advanced/over_sampling.py in all three Tier-A files. The autolens imaging/simulator.py also references its own __Oversampled PSF__ appendix (which exists there); group/simulator.py and autogalaxy imaging/simulator.py do not have that appendix, so their note stops at the guide reference to avoid a dangling link. Say the word if you'd like the __Oversampled PSF__ appendix ported into those two as well.