design: oversampled PSF convolution phase 1/4 — note + ground truth

[Jammy2211]

Overview

Design phase (1 of 4) for oversampled PSF convolution. The Convolver currently requires the PSF to share the image's pixel scale; for modeling we want to evaluate images on an oversampled grid, convolve with an oversampled PSF at that higher resolution, and bin down to the observed resolution. This phase produces the design note and a brute-force numerical ground truth that later phases implement and test against — it makes no library source edits.

Parent task: PyAutoMind/issued/oversampling.md (scored too-large, split 2026-07-08 into design → core API → workspace examples → docs). This run is --auto at effective level supervised (checkpoint-and-continue per PyAutoBrain/AUTONOMY.md): the plan below is the plan-approval record; ship sign-off will park with a batched question on this issue.

Plan

• Survey how Convolver/ConvolverState performs same-resolution PSF convolution today, and how the over_sampling package defines uniform oversampled grids and bins them down.
• Design the convolve_over_sample_size API on Convolver: relationship between the oversampled evaluation grid, the oversampled PSF kernel, and the bin-down step (size 2 = PSF at 2× image resolution).
• Design the Imaging extension: convolve_over_sample_size_lp and convolve_over_sample_size_pixelization, mirroring the existing over_sample_size_lp / over_sample_size_pixelization pattern.
• Trace how PSF convolution enters the inversion and confirm or correct the hypothesis that wiring lands in mapping.py (initial reading shows the actual PSF application lives in abstract.py via psf.convolved_mapping_matrix_from); record why sparse.py is deferred.
• Survey how PyAutoGalaxy/autogalaxy/operate/image.py model-image blurring will consume the new behaviour (design only).
• Specify the adaptive-over-sampling guard: adaptive sub-sizes make 2D convolution ill-defined — raise loudly, no silent fallback.
• Build a standalone brute-force ground-truth computation with a simple analytic oversampled PSF and record the reference numbers.
• Write the design note (oversampling_design.md alongside the phase prompts in PyAutoMind) and post it to this issue.

Detailed implementation plan

Affected Repositories

• PyAutoArray (primary — read/survey only this phase)
• PyAutoGalaxy (read/survey only)
• PyAutoMind (design note + ground-truth script are the shipped artifacts)

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoArray	main	clean
./PyAutoGalaxy	main	clean
./PyAutoMind	main	1 modified (parent-prompt split annotation, rides with registration push)

Suggested branch: feature/psf-oversample-design
Worktree root: ~/Code/PyAutoLabs-wt/psf-oversample-design/

Implementation Steps

1. Read autoarray/operators/convolver.py (~1000 lines: ConvolverState, Convolver) — document how the kernel is embedded/padded and applied at image resolution, and every public entry point (convolve_over_sample_size must serve all of them or explicitly scope which).
2. Read autoarray/operators/over_sampling/ (over_sampler.py, over_sample_util.py, decorator.py) — document how uniform over-sampled grids are constructed and binned down, and which pieces oversampled convolution can reuse.
3. Read autoarray/dataset/imaging/dataset.py — document how over_sample_size_lp / over_sample_size_pixelization flow from the constructor into grids, and design the analogous convolve_over_sample_size_lp / convolve_over_sample_size_pixelization plumbing into the Convolver(s).
4. Read autoarray/inversion/inversion/imaging/{abstract,mapping,sparse}.py and inversion_imaging_util.py — map the actual PSF entry points (convolved_mapping_matrix_from calls in abstract.py, w-tilde kernel use) and decide where oversampled convolution is wired; record the sparse.py deferral rationale.
5. Read autogalaxy/operate/image.py — document the model-image blurring path (blurred_image_2d_from and friends) and what phase 2 must change there.
6. Specify adaptive-guard behaviour: requesting oversampled convolution with an adaptive (per-pixel Array2D) over-sample size raises a clear error.
7. Write the brute-force ground truth: simple analytic PSF (e.g. Gaussian) at over-sample sizes 1 and 2, tiny mask, direct high-resolution convolution + bin-down computed with plain numpy loops; record numbers in the design note. Size 1 must match the existing Convolver output exactly.
8. Write oversampling_design.md covering all of the above with file/line grounding; check it into PyAutoMind next to the phase prompts; post the note to this issue.

Key Files

• PyAutoArray/autoarray/operators/convolver.py — current same-resolution convolution (ConvolverState, Convolver)
• PyAutoArray/autoarray/operators/over_sampling/over_sampler.py — uniform over-sampling + bin-down machinery
• PyAutoArray/autoarray/dataset/imaging/dataset.py — Imaging constructor to extend in phase 2
• PyAutoArray/autoarray/inversion/inversion/imaging/abstract.py — actual PSF application in the inversion (convolved_mapping_matrix_from)
• PyAutoArray/autoarray/inversion/inversion/imaging/mapping.py / sparse.py — wiring target / deferred
• PyAutoGalaxy/autogalaxy/operate/image.py — model-image blurring consumer (phase 2 scope, surveyed here)

Acceptance

• Design note answers every scope point with file/line grounding.
• Ground-truth script runs; its reference numbers are recorded in the note.
• No edits to PyAutoArray/PyAutoGalaxy source.

Original Prompt

Click to expand starting prompt

Oversampled PSF convolution — phase 1: design note + numerical ground truth

Type: feature
Target: PyAutoArray
Repos:

• PyAutoArray
  Difficulty: medium
  Autonomy: supervised
  Priority: normal
  Status: formalised

Phase 1 of 4 of feature/autoarray/oversampling.md (split by the Feature Agent
on 2026-07-08 — the parent scored too-large). This phase produces the design
and the numerical reference result; no source-code edits to the libraries.

Background (from the parent prompt)

A point spread function blurs images via 2D convolution, implemented in
@PyAutoArray/autoarray/operators/convolver.py. The source code currently
requires PSF blurring to occur at the same resolution (pixel scale) as the
image. For modeling, convolution can instead be performed at a higher
resolution: evaluate the image on an oversampled grid, blur with an
oversampled PSF, then downsample (bin) to the observed image resolution.
Oversampling machinery lives in @PyAutoArray/autoarray/operators/over_sampling.

Adaptive (per-pixel) over-sample sizes make 2D PSF convolution ill-defined —
this design assumes uniform (non-adaptive) over sampling only.

Deliverables

1. Design note (posted to the phase GitHub issue, and saved alongside this
   prompt as oversampling_design.md) covering:
   • How Convolver gains a convolve_over_sample_size integer: the mapping
     between the oversampled evaluation grid, the oversampled PSF kernel, and
     the binning-down step to image resolution (e.g. size 2 = PSF at 2× the
     image resolution).
   • How Imaging (@PyAutoArray/autoarray/dataset/imaging/dataset.py) gains
     convolve_over_sample_size_lp and convolve_over_sample_size_pixelization
     attributes for the light-profile and pixelization operations respectively,
     alongside the existing over_sample_size_lp / over_sample_size_pixelization.
   • How PSF convolution enters the inversion path: read
     @PyAutoArray/autoarray/inversion/inversion/imaging and its parents.
     The working hypothesis is that oversampled convolution can be wired into
     mapping.py; sparse.py is explicitly deferred to future work — confirm
     or correct this and record why.
   • How model-image blurring in @PyAutoGalaxy/autogalaxy/operate/image.py
     consumes the new Convolver behaviour (survey only — implementation is
     phase 2).
   • How the code should behave when adaptive over sampling is requested
     together with oversampled convolution (expect: raise loudly, no silent
     fallback).
2. Numerical ground truth: a standalone brute-force reference computation
   (script or notebook-style scratch, checked in with this phase) using a
   simple analytic oversampled PSF, producing the number(s) the phase-2 unit
   tests and phase-3 workspace test will assert against.

Acceptance

• Design note answers every point above with file/line grounding.
• Ground-truth script runs and its result is recorded in the design note.
• No edits to PyAutoArray/PyAutoGalaxy source.

Parent: feature/autoarray/oversampling.md. Next: oversampling_phase_2_core_api.md.

[Jammy2211]

Phase 1 complete — design note + numerical ground truth ready for review

Both deliverables are done and pushed to PyAutoMind (feature/autoarray/oversampling_design.md + oversampling_ground_truth.py, commit c5ee140). No PyAutoArray/PyAutoGalaxy source was touched, per the phase-1 contract. Highlights:

• Core design: oversampled convolution reuses the existing Convolver machinery verbatim on an upscaled mask (image mask → fine mask at ps/s), plus one new piece of index bookkeeping (a cached permutation between autoarray's per-pixel sub-block ordering and the fine mask's row-major slim ordering) and an s×s mean bin-down. No new convolution code paths.
• Hypothesis corrected: the inversion's PSF application is not in mapping.py — it is in the shared parent AbstractInversionImaging.operated_mapping_matrix_list (abstract.py:104-116), which InversionImagingMapping inherits. Wiring there serves the mapping formalism as intended. sparse.py and the preloaded linear-func fast path consume psf.kernel.native directly and are deferred with loud guards.
• New finding: the mapper's mapping_matrix is already binned to image resolution via sub_fraction, so phase 2 needs a mapping_matrix_over_sampled variant (rows = sub-pixels) — the FFT cube grows ×s² in memory, flagged as the main phase-2 risk (profile before defaulting on).
• Ground truth: independent brute-force numpy implementation; at s=1 it matches the installed Convolver to 5.6e-17 (machine precision); s=2 reference numbers are recorded in the note (effect size up to ~2.4% of peak on the test scene — the feature matters).

Full design note (canonical copy: PyAutoMind/feature/autoarray/oversampling_design.md)

See the file in PyAutoMind for the authoritative version with the results table; summary of sections:

1. Core insight — Convolver on an upscaled mask + permutation + mean bin-down.
2. Convolver.convolve_over_sample_size: int = 1 — fine-resolution kernel semantics (s=2 → PSF at 2× image resolution, 9×9 fine kernel for a 5×5 native one), state_from builds the fine ConvolverState, s=1 is a strict no-op, kernel/pixel-scale validation raises KernelException.
3. Imaging gains convolve_over_sample_size_lp / convolve_over_sample_size_pixelization (int, default 1). Phase-2 rule: when >1, the matching over_sample_size_* must be a uniform int equal to it (raise otherwise); blurring grid gets over_sample_size=s; one PSF supplied at the finer resolution if the two sizes differ.
4. Inversion wiring in AbstractInversionImaging.operated_mapping_matrix_list; mapper emits sub-resolution mapping matrix; sparse + linear-func paths guarded and deferred.
5. PyAutoGalaxy: over_sample decorator gains binned: bool = True pass-through; _blurred_image_2d_from switches on psf.convolve_over_sample_size; padded/unmasked visualization images stay at image resolution (documented limitation).
6. Adaptive guard: convolve_over_sample_size_* are plain ints; adaptive over_sample_size_* alongside s>1 raises DatasetException at Imaging.__init__; Convolver re-asserts uniformity.
7. Ground-truth numbers (s=1 parity 5.6e-17; s=2 reference values for phases 2-3).
8. Phase-2 execution sketch (5 steps, each with tests).

---

⏸ Checkpoint — supervised --auto run parking for design sign-off

What was being done: phase 1 of 4 of the oversampled-PSF feature (parent task split by sizing; this issue is the design phase). Design + ground truth are complete; the next step is phase 2 (core library API), which is a separate task that should start from this design.

The fork: the design makes three scoping decisions that phase 2 will implement, and they deserve a human eye before code is written:

1. Coupling rule — convolve_over_sample_size_lp > 1 requires over_sample_size_lp to be a uniform int equal to it (the k*s generalisation is deferred). Alternative: implement the multiple-of rule now (more flexible, slightly more bin logic).
2. Convolver input contract — for s>1 the existing method names (convolved_image_from etc.) accept over-sampled inputs, with a loud shape check; alternative: new *_over_sampled_from method names (more explicit, more API surface).
3. Pixelization scope — phase 2 wires the mapping formalism only; sparse.py + linear-func fast paths raise loudly when combined with s>1 (deferred to future work, per the parent prompt).

Recommendation: approve as designed (options 1 and 2 keep phase 2 minimal; option 3 is what the parent prompt asked for).

What happens on each answer:

• "Approved" (or silence + relaunch): run /start_dev feature/autoarray/oversampling_phase_2_core_api.md --auto — phase 2 starts from this note verbatim.
• Amendments: reply with the numbered point(s) to change; the design note is updated and phase 2 starts from the amended version.
• "Rework": phase 1 reopens in this task's worktree.

Task psf-oversample-design is now parked awaiting-input in PyAutoMind/active.md.

🤖 Generated with Claude Code

[Jammy2211]

✅ Design approved unchanged by @Jammy2211 (all three scoping decisions as recommended). Phase 1 is complete — launching phase 2 (core library API): /start_dev feature/autoarray/oversampling_phase_2_core_api.md --auto. Phase 2 will implement oversampling_design.md verbatim and track in its own issue.

🤖 Generated with Claude Code