MaskedFFT

class pygrog.operator.MaskedFFT(grid_shape=None, image_shape=None, mask=None, density=None, smaps=None, stack_shape=None, device=None, *, toeplitz=None, plan=None, coords=None, dcf=None)

Bases: SolveMixin

Masked FFT / IFFT operator for gridded k-space data.

Accepts either a pre-built plan (from interpolate() with grid=True) together with explicit mask / density tensors, or raw shapes and masks (for users who already have a Cartesian undersampling pattern and skip GROG entirely).

Parameters:

• grid_shape (tuple[int, ...]) – Oversampled Cartesian k-space grid, e.g. (nz, ny, nx).

• image_shape (tuple[int, ...]) – Target image shape (center-crop), e.g. (nz, ny, nx).

• mask (torch.Tensor) – Binary sampling mask, real-valued, shape (*stack_shape, *grid_shape) or (*grid_shape,) for unstacked plans. 1 = sampled, 0 = not sampled.

• density (torch.Tensor | None, optional) – Density-compensation grid (sum of squared GROG weights), real-valued, same shape as mask. Required for GrogToeplitzOp() construction; if None the Toeplitz normal operator is disabled.

• smaps (torch.Tensor | None, optional) – (n_coils, *image_shape) sensitivity maps. None → no coil combination.

• stack_shape (tuple[int, ...], optional) – Stack prefix, e.g. (n_slices,) or (T, n_slices). Inferred from the leading axes of mask that are not part of grid_shape when not provided.

• device (str | torch.device | None, optional) – Compute device.

• toeplitz (bool | None, optional) – Use Toeplitz embedding for normal(). None → auto: enabled on CPU, disabled on CUDA.

• plan (object | None, optional) – Pre-built plan (ignored except for logging; all required metadata is passed via the other arguments).

Methods

__init__
adjoint	Gridded k-space to image.
forward	Image to gridded k-space.
normal	Self-adjoint application: A^H A image.
solve	Solve \(\arg\min_x \|A x - b\|^2 + \lambda^2 \|x\|^2\).

adjoint(kspace_grid)

Gridded k-space to image.

Parameters:

kspace_grid (torch.Tensor) – Input gridded k-space, shape (*B, *S, n_coils, *grid_shape) (or without coil axis if smaps are set and caller pre-combined).

Returns:

(*B, *S, *image_shape) if smaps are set (SENSE-combined), else (*B, *S, n_coils, *image_shape).

Return type:

torch.Tensor

Note

This function uses torch internally, and will convert all its array argument to torch tensors, but will respect the device they are allocated on. The outputs will be converted back to the original array module and device.

forward(image)

Image to gridded k-space.

Parameters:

image (torch.Tensor) – Input image, shape (*B, *S, *image_shape) if smaps set, else (*B, *S, n_coils, *image_shape).

Returns:

(*B, *S, n_coils, *grid_shape).

Return type:

torch.Tensor

Note

This function uses torch internally, and will convert all its array argument to torch tensors, but will respect the device they are allocated on. The outputs will be converted back to the original array module and device.

normal(image)

Self-adjoint application: A^H A image.

When self.toeplitz is True (requires density to be set), uses a pre-computed PSF on grid_shape (built lazily on first call). Otherwise falls back to forward(adjoint(image)) (with pygrog convention: adjoint = A (image→kspace), forward = A^H (kspace→image)).

Note

This function uses torch internally, and will convert all its array argument to torch tensors, but will respect the device they are allocated on. The outputs will be converted back to the original array module and device.