autolens.Convolver#

class Convolver[source]#

Bases: object

A 2D convolution kernel paired with a mask, providing real-space and FFT-based convolution of images or mapping matrices.

The Convolver is a subclass of Array2D with additional methods for performing point spread function (PSF) convolution. Each entry of the kernel corresponds to the PSF value at the centre of a pixel on a uniform 2D grid.

Two convolution modes are supported:

  • Real-space convolution: Performed directly via sliding-window summation or jax.scipy.signal.convolve. This mode is exact and requires no padding, but becomes computationally expensive for large kernels.

  • FFT-based convolution: Performed by embedding the input image and kernel into padded arrays, transforming them to Fourier space, multiplying, and transforming back. This mode is typically faster for kernels larger than approximately 5×5, but requires careful handling of padding, masking, and kernel centering.

All logic related to FFT padding, mask expansion, linear (non-circular) convolution, and blurring-mask construction is handled by ConvolverState. See the ConvolverState docstring for a detailed description of how masked real-space data are mapped to and from FFT space.

When FFT convolution is enabled, the Convolver expects a corresponding ConvolverState defining the FFT geometry. The padded FFT shape is stored in state.fft_shape and must be consistent with the shape of any arrays passed for convolution. Attempting FFT convolution without a valid state will raise an exception to avoid silent shape or alignment errors.

Parameters:

  • kernel (Array2D) – The raw 2D kernel values. These represent the PSF sampled at pixel centres and may be normalised to sum to unity if normalize=True.

  • state (Optional[ConvolverState]) – Optional ConvolverState instance defining FFT padding, mask expansion, and kernel Fourier transforms. Required when using FFT convolution.

  • normalize (bool) – If True, the kernel values are rescaled such that their sum is unity.

  • use_fft (Optional[bool]) – If True, convolution is performed in Fourier space using the provided ConvolverState. If False, convolution is performed in real space. If None, the default behaviour specified in the configuration is used.

  • *args – Passed to the Array2D constructor.

  • **kwargs – Passed to the Array2D constructor.

Notes

  • When performing real-space convolution, the kernel must have odd dimensions in both axes so that it has a well-defined central pixel.

  • When performing FFT convolution, kernel centering, padding, and mask expansion are handled by ConvolverState.

  • Blurring masks ensure that PSF flux spilling outside the main image mask is included correctly. Omitting them may lead to underestimated PSF wings.

  • For very small kernels, FFT and real-space convolution may differ slightly near mask boundaries due to padding and truncation effects.

Methods

convolved_image_from

Convolve an input masked image with this PSF.

convolved_image_via_real_space_from

Convolve an input masked image with this PSF in real space.

convolved_image_via_real_space_np_from

Convolve an input masked image with this PSF in real space.

convolved_mapping_matrix_from

Convolve a source-plane mapping matrix with this PSF.

convolved_mapping_matrix_via_real_space_from

Convolve a source-plane mapping matrix with this PSF in real space.

convolved_mapping_matrix_via_real_space_np_from

Convolve a source-plane mapping matrix with this PSF in real space.

from_fits

Loads the Convolver from a .fits file.

from_gaussian

Setup the Convolver as a 2D symmetric elliptical Gaussian profile, according to the equation:

mapping_matrix_native_from

Expand a slim mapping matrix (image-plane) and optional blurring mapping matrix into a full native 3D cube (ny, nx, n_src).

no_blur

Setup the Convolver as a kernel which does not convolve any signal, which is simply an array of shape (1, 1) with value 1.

state_from

Attributes

normalized

Normalize the Convolver such that its data_vector values sum to unity.

use_fft

state_from(mask)[source]#
property use_fft#
property normalized: Convolver#

Normalize the Convolver such that its data_vector values sum to unity.

A copy of the kernel is used to avoid mutating the original kernel instance, and no existing state is reused so that any cached FFTs are recomputed for the normalized kernel.

classmethod no_blur(pixel_scales)[source]#

Setup the Convolver as a kernel which does not convolve any signal, which is simply an array of shape (1, 1) with value 1.

Parameters:

pixel_scales – The (y,x) arcsecond-to-pixel units conversion factor of every pixel. If this is input as a float, it is converted to a (float, float).

classmethod from_gaussian(shape_native, pixel_scales, sigma, centre=(0.0, 0.0), axis_ratio=1.0, angle=0.0, normalize=False)[source]#

Setup the Convolver as a 2D symmetric elliptical Gaussian profile, according to the equation:

(1.0 / (sigma * sqrt(2.0*pi))) * exp(-0.5 * (r/sigma)**2)

Parameters:

  • shape_native (Tuple[int, int]) – The 2D shape of the mask the array is paired with.

  • pixel_scales – The (y,x) arcsecond-to-pixel units conversion factor of every pixel. If this is input as a float, it is converted to a (float, float).

  • sigma (float) – The value of sigma in the equation, describing the size and full-width half maximum of the Gaussian.

  • centre (Tuple[float, float]) – The (y,x) central coordinates of the Gaussian.

  • axis_ratio (float) – The axis-ratio of the elliptical Gaussian.

  • angle (float) – The rotational angle of the Gaussian’s ellipse defined counter clockwise from the positive x-axis.

  • normalize (bool) – If True, the Convolver’s array values are normalized such that they sum to 1.0.

classmethod from_fits(file_path, hdu, pixel_scales, origin=(0.0, 0.0), normalize=False)[source]#

Loads the Convolver from a .fits file.

Parameters:

  • file_path (Union[Path, str]) – The path the file is loaded from, including the filename and the .fits extension, e.g. ‘/path/to/filename.fits’

  • hdu (int) – The Header-Data Unit of the .fits file the array data is loaded from.

  • pixel_scales – The (y,x) arcsecond-to-pixel units conversion factor of every pixel. If this is input as a float, it is converted to a (float, float).

  • origin – The (y,x) scaled units origin of the mask’s coordinate system.

  • normalize (bool) – If True, the Convolver’s array values are normalized such that they sum to 1.0.

mapping_matrix_native_from(mapping_matrix, mask, blurring_mapping_matrix=None, blurring_mask=None, use_mixed_precision=False, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Expand a slim mapping matrix (image-plane) and optional blurring mapping matrix into a full native 3D cube (ny, nx, n_src).

This is primarily used for real-space convolution, where the pixel-to-source mapping must be represented on the full image grid.

Parameters:

  • mapping_matrix (ndarray) – Slim mapping matrix for unmasked image pixels, mapping each image pixel to source-plane pixels.

  • mask (Mask2D) – Mask defining which image pixels are unmasked. Used to expand the slim mapping matrix into a native grid.

  • blurring_mapping_matrix (Optional[ndarray]) – Mapping matrix for blurring pixels outside the main mask (e.g. light spilling in from outside). If provided, it is also scattered into the native cube.

  • blurring_mask (Optional[Mask2D]) – Mask defining the blurring region pixels. Must be provided if blurring_mapping_matrix is given and slim_to_native_blurring_tuple is not already cached.

  • use_mixed_precision (bool) – If True, the mapping matrices are cast to single precision (float32) to speed up GPU computations and reduce VRAM usage. If False, double precision (float64) is used for maximum accuracy.

Returns:

Native 3D mapping matrix cube with dimensions (image_y, image_x, sources). Contains contributions from both the main mapping matrix and, if provided, the blurring mapping matrix.

Return type:

ndarray (ny, nx, N_src)

convolved_image_from(image, blurring_image, jax_method='direct', use_mixed_precision=False, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve an input masked image with this PSF.

This method chooses between an FFT-based convolution (default if self.use_fft=True) or a direct real-space convolution, depending on how the Convolver was configured.

In the FFT branch: - The input image (and optional blurring image) are resized / padded to

match the FFT-friendly padded shape (fft_shape) associated with this kernel.

  • The PSF and image are transformed to Fourier space via jax.numpy.fft.rfft2.

  • Convolution is performed as elementwise multiplication.

  • The result is inverse-transformed and cropped back to the masked region.

Padding ensures that the FFT implements linear convolution, not circular, and avoids wrap-around artefacts. The required padding is determined by fft_shape_from(mask). If no precomputed shapes exist, they are computed on the fly. For reproducible behaviour, precompute and set ``fft_shape` on the kernel.

If use_fft=False, convolution falls back to Convolver.convolved_image_via_real_space_from.

Parameters:

  • image – Masked 2D image array to convolve.

  • blurring_image – Masked image containing flux from outside the mask core that blurs into the masked region after convolution. If None, only the direct image is convolved, which may be numerically incorrect if the mask excludes PSF wings.

  • jax_method ({"direct", "fft"}) – Backend passed to jax.scipy.signal.convolve when in real-space mode. Ignored for FFT convolutions.

Returns:

The convolved image in slim (1D masked) format.

Return type:

Array2D

convolved_mapping_matrix_from(mapping_matrix, mask, blurring_mapping_matrix=None, blurring_mask=None, jax_method='direct', use_mixed_precision=False, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve a source-plane mapping matrix with this PSF.

A mapping matrix maps image-plane unmasked pixels to source-plane pixels. This method performs the equivalent operation of PSF convolution on the mapping matrix, so that model visibilities / images can be computed via matrix multiplication instead of explicit convolution.

If use_fft=True, convolution is performed in Fourier space: - The mapping matrix is scattered into a 3D native cube

(ny, nx, n_src).

  • An FFT of this cube is multiplied by the precomputed FFT of the PSF.

  • The inverse FFT is taken and cropped to the mask region.

  • The slim (masked 1D) representation is returned.

If use_fft=False, convolution falls back to Convolver.convolved_mapping_matrix_via_real_space_from.

Notes

  • FFT convolution requires that self.fft_shape and related padding attributes are precomputed. If not, a ValueError is raised with the expected vs actual shapes. This ensures the mapping matrix is padded consistently with the PSF.

  • The optional blurring_mapping_matrix plays the same role as blurring_image in convolved_image_from, accounting for PSF flux that falls into the masked region from outside.

Parameters:

  • mapping_matrix (ndarray of shape (N_pix, N_src)) – Slim mapping matrix from unmasked pixels to source pixels.

  • mask (Mask2D) – Associated mask defining the image grid.

  • blurring_mapping_matrix (ndarray of shape (N_blur, N_src), optional) – Mapping matrix for the blurring region, outside the mask core.

  • jax_method (str) – Backend passed to real-space convolution if use_fft=False.

  • use_mixed_precision (bool) – If True, the FFT is performed using single precision, which provide significant speed up when using a GPU (x4), reduces VRAM use and is expected to have minimal impact on the accuracy of the results. If False, the FFT is performed using double precision, which is the default and is more accurate but slower on a GPU.

Returns:

Convolved mapping matrix in slim form.

Return type:

ndarray of shape (N_pix, N_src)

convolved_image_via_real_space_from(image, blurring_image=None, jax_method='direct', xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve an input masked image with this PSF in real space.

This is the direct method (non-FFT) where convolution is explicitly performed using jax.scipy.signal.convolve with the kernel in native space.

Unlike FFT convolution, this does not require padding shapes, but it is typically much slower for large kernels (> ~5x5).

Parameters:

  • image (ndarray) – Masked image array to convolve.

  • blurring_image (Optional[ndarray]) – Blurring contribution from outside the mask core. If None, only the direct image is convolved (which may be numerically incorrect).

  • jax_method (str) – Method flag for JAX convolution backend (default “direct”).

Returns:

Convolved image in slim format.

Return type:

Array2D

convolved_mapping_matrix_via_real_space_from(mapping_matrix, mask, blurring_mapping_matrix=None, blurring_mask=None, jax_method='direct', xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve a source-plane mapping matrix with this PSF in real space.

Equivalent to convolved_mapping_matrix_from, but using explicit real-space convolution rather than FFTs. This avoids FFT padding issues but is slower for large kernels.

The mapping matrix is expanded into a native cube (ny, nx, n_src), convolved with the kernel (broadcast along the source axis), and reduced back to slim form.

Parameters:

  • mapping_matrix (ndarray) – Slim mapping matrix from unmasked pixels to source pixels.

  • mask – Mask defining the pixelization grid.

  • blurring_mapping_matrix (Optional[ndarray]) – Mapping matrix for blurring region pixels outside the mask core.

  • jax_method (str) – Backend passed to JAX convolution.

Returns:

Convolved mapping matrix in slim form.

Return type:

ndarray (N_pix, N_src)

convolved_image_via_real_space_np_from(image, blurring_image=None, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve an input masked image with this PSF in real space.

This is the direct method (non-FFT) where convolution is explicitly performed using jax.scipy.signal.convolve with the kernel in native space.

Unlike FFT convolution, this does not require padding shapes, but it is typically much slower for large kernels (> ~5x5).

Parameters:

  • image (ndarray) – Masked image array to convolve.

  • blurring_image (Optional[ndarray]) – Blurring contribution from outside the mask core. If None, only the direct image is convolved (which may be numerically incorrect).

  • jax_method – Method flag for JAX convolution backend (default “direct”).

Returns:

Convolved image in slim format.

Return type:

Array2D

convolved_mapping_matrix_via_real_space_np_from(mapping_matrix, mask, blurring_mapping_matrix=None, blurring_mask=None, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/pyautolens/envs/latest/lib/python3.12/site-packages/numpy/__init__.py'>)[source]#

Convolve a source-plane mapping matrix with this PSF in real space.

Equivalent to convolved_mapping_matrix_from, but using explicit real-space convolution rather than FFTs. This avoids FFT padding issues but is slower for large kernels.

The mapping matrix is expanded into a native cube (ny, nx, n_src), convolved with the kernel (broadcast along the source axis), and reduced back to slim form.

Parameters:

  • mapping_matrix (ndarray) – Slim mapping matrix from unmasked pixels to source pixels.

  • mask – Mask defining the pixelization grid.

  • blurring_mapping_matrix (Optional[ndarray]) – Mapping matrix for blurring region pixels outside the mask core.

  • jax_method – Backend passed to JAX convolution.

Returns:

Convolved mapping matrix in slim form.

Return type:

ndarray (N_pix, N_src)