[Jammy2211]

Closes #640. Community proposal: PyAutoLabs/.github#35 (@HRSAstro).

Summary

Adds an optional primary beam P to interferometer fitting. P lives on the Interferometer dataset as an image on the real-space mask (user-supplied, or the new Gaussian helper with FWHM = 1.13 λ/D). The visibilities are modelled as those of the apparent sky P × I, so every light profile, linear light profile and pixelization reconstructs the true sky I: the transformers apply P on the slim grid in their forward transforms (visibilities_from, transform_mapping_matrix), and the sparse w-tilde inversion carries it on the sparse operator (primary_beam_slim), folding P into the mapper triplet weights (A' = P·A) and the linear-function blocks so F' = Mᵀ P W̃ P M, D' = Mᵀ P D̃. The dirty image, dirty beam and w-tilde kernel are unchanged (image_from stays the un-beamed adjoint), so cached SparseTerms serve any beam. The simulator accepts P. mapped_reconstructed_data_dict stays the true-sky image; model visibilities pick P up in the transformer.

A warning is emitted when any unmasked P is 0 (curvature rank-deficient for source pixels seen only there); no floor is applied (human decision on the plan).

Deviation from the plan: InversionInterferometerSparseNumba (the default CPU route) uses the raw mapper weights and would have silently ignored P; the factory now routes there only when P is None or exactly all ones (primary_beam_is_trivial), and the class raises if built with a non-trivial P. A precomputed sparse_operator passed to an Interferometer that has a P is re-created with P attached.

API Changes

Additive only: Interferometer(primary_beam=) (+ from_fits(primary_beam_path=, primary_beam_hdu=), from_sparse_terms(primary_beam=), from_stream), SimulatorInterferometer(primary_beam=), TransformerDFT/TransformerNUFFT(primary_beam=) + .with_primary_beam(), aa.primary_beam_gaussian_from(mask, frequency_hz, dish_diameter_m, pb_factor=1.13, centre=), InterferometerSparseOperator.primary_beam_slim, mapper_util.sparse_triplets_from(slim_weights=). Results with no beam are bit-identical to before.
See full details below.

Test Plan

• Witness: P=None and P=ones bit-for-bit (np.array_equal) on numpy and under jax.jit for transformer outputs, sparse/mapping curvature and data vectors, reconstruction, fast_chi_squared, mapped images; brute force on the 7×7 Delaunay fixture with a non-trivial P: sparse curvature == Lᵀ diag(P) W̃ diag(P) L and data vector == Lᵀ diag(P) D̃ to 1e-10 for one mapper, func list + mapper, two mappers, func list + two mappers, func list only.
• Dense vs sparse with P; DFT vs NUFFT; array-free from_sparse_terms(primary_beam=) vs in-memory; transformer equivalences (DFT, NUFFT, JAX); P through all six dataset rebuild sites; shape mismatch raises; P=0 warns; dirty image/beam unchanged; simulator parity incl. jit; Gaussian helper peak/half-max; slim_weights; dirty_model_image_natural_from.
• Worktree runs: pytest test_autoarray -q → 2136 passed, 4 xfailed; pytest test_autogalaxy/interferometer test_autogalaxy/operate -q against this branch → 141 passed; import autoarray with jax/jaxlib/nufftax blocked by an import hook works and never imports them.

Heart YELLOW acknowledged by the human on 2026-10-21 (manifest drift 1 mismatch; release validation stale: source moved since rehearsal (PyAutoArray) — a consequence of #641).

Follow-ups (not in this PR): persist P in PyAutoGalaxy analysis.py save_attributes + aggregator rebuild; workspace example + docs; a forced interferometer_route="numba" with a non-trivial P falls back to the FFT route instead of raising; the P=0 warning repeats on each dataset rebuild.

Full API Changes (for automation & release notes)

Added

• aa.primary_beam_gaussian_from(mask, frequency_hz, dish_diameter_m, pb_factor=1.13, centre=(0.0, 0.0)) — Gaussian primary beam Array2D on the mask
• Interferometer(..., primary_beam=None); Interferometer.primary_beam, .primary_beam_slim; from_fits(primary_beam_path=None, primary_beam_hdu=0); from_sparse_terms(..., primary_beam=None); from_stream(..., primary_beam=None)
• SimulatorInterferometer(..., primary_beam=None)
• TransformerDFT(..., primary_beam=None), TransformerNUFFT(..., primary_beam=None), .with_primary_beam(primary_beam)
• InterferometerSparseOperator.primary_beam_slim (field); inversion_interferometer_util.primary_beam_is_trivial(primary_beam_slim)
• mapper_util.sparse_triplets_from(..., slim_weights=None)

Changed Behaviour

• InversionInterferometerSparseNumba raises when built with a non-trivial primary beam; the factory routes such datasets to the FFT sparse path.
• transformer.visibilities_from / transform_mapping_matrix multiply by P on the slim grid when the transformer carries one; image_from does not (documented).

Generated by the PyAutoLabs agent workflow.

🤖 Generated with Claude Code