mrpro.operators.GridSamplingOp

class mrpro.operators.GridSamplingOp[source]

Bases: LinearOperator

Grid Sampling Operator.

Given an “input” tensor and a “grid”, computes the output by taking the input values at the locations determined by grid with interpolation. Thus, the output size will be determined by the grid size. For the adjoint to be defined, the grid and the shape of the “input” has to be known.

__init__(grid_z: Tensor | None, grid_y: Tensor, grid_x: Tensor, input_shape: SpatialDimension | None = None, interpolation_mode: Literal['bilinear', 'nearest', 'bicubic'] = 'bilinear', padding_mode: Literal['zeros', 'border', 'reflection'] = 'zeros', align_corners: bool = False)[source]

Initialize Sampling Operator.

Parameters:

grid_z (Tensor | None) – Z-component of sampling grid. Shape (*batchdim, z,y,x). Values should be in [-1, 1.]. Use None for a 2D interpolation along y and x.
grid_y (Tensor) – Y-component of sampling grid. Shape (*batchdim, z, y, x) or (*batchdim, y, x) if grid_z is None. Values should be in [-1, 1.].
grid_x (Tensor) – X-component of sampling grid. Shape (*batchdim, z, y, x) or (*batchdim, y, x) if grid_z is None. Values should be in [-1, 1.].
input_shape (SpatialDimension | None, default: None) – Used in the adjoint. The z, y, x shape of the domain of the operator. If grid_z is None, only y and x will be used.
interpolation_mode (Literal['bilinear', 'nearest', 'bicubic'], default: 'bilinear') – mode used for interpolation. bilinear is trilinear in 3D, bicubic is only supported in 2D.
padding_mode (Literal['zeros', 'border', 'reflection'], default: 'zeros') – how the input of the forward is padded.
align_corners (bool, default: False) – if True, the corner pixels of the input and output tensors are aligned, and thus preserve the values at those pixels

classmethod from_displacement(displacement_z: Tensor | None, displacement_y: Tensor, displacement_x: Tensor, interpolation_mode: Literal['bilinear', 'nearest', 'bicubic'] = 'bilinear', padding_mode: Literal['zeros', 'border', 'reflection'] = 'zeros') → Self[source]

Create a GridSamplingOp from a displacement.

The displacement is expected to describe a pull operation in voxel units. Let’s assume we have an input image \(i(x,y)\) and a displacement \(d_x(x,y)\) and \(d_y(x,y)\) then the output image \(o(x,y)\) will be calculated as: .. math:

o(x,y) = i(x + d_x(x,y), y + d_y(x,y))

Parameters:

displacement_z (Tensor | None) – Z-component of the displacement. Use None for a 2D interpolation along y and x. Shape is *batchdim, z,y,x. Values should describe the displacement in voxel.
displacement_y (Tensor) – Y-component of sampling grid. Shape is *batchdim, z,y,x or *batchdim, y,x if displacement_z is None. Values should describe the displacement in voxel. Values should describe the displacement in voxel.
displacement_x (Tensor) – X-component of sampling grid. Shape is *batchdim, z,y,x or *batchdim, y,x if displacement_z is None. Values should describe the displacement in voxel. Values should describe the displacement in voxel.
interpolation_mode (Literal['bilinear', 'nearest', 'bicubic'], default: 'bilinear') – mode used for interpolation. bilinear is trilinear in 3D, bicubic is only supported in 2D.
padding_mode (Literal['zeros', 'border', 'reflection'], default: 'zeros') – how the input of the forward is padded.

property H: LinearOperator[source]

Adjoint operator.

Obtains the adjoint of an instance of this operator as an AdjointLinearOperator, which itself is a an LinearOperator that can be applied to tensors.

Note: linear_operator.H.H == linear_operator

property gram: LinearOperator[source]

Gram operator.

For a LinearOperator \(A\), the self-adjoint Gram operator is defined as \(A^H A\).

Note

This is the inherited default implementation.

__call__(x: Tensor) → tuple[Tensor][source]

Apply the GridSampling operator.

This operator samples an input tensor x at locations specified by a grid. The grid coordinates are normalized to [-1, 1]. The output tensor’s spatial dimensions are determined by the grid’s dimensions. Interpolation is used if grid points do not fall exactly on input tensor elements.

Parameters:: x (Tensor) – Input tensor to be sampled.
Returns:: Output tensor containing sampled values.

adjoint(x: Tensor) → tuple[Tensor][source]

Apply the adjoint of the GridSampling operator.

This operation is the adjoint of the forward grid sampling. It effectively “scatters” the values from the input tensor x (which is in the grid’s domain) back to a tensor in the original input domain of the forward operation, using the same grid and interpolation settings.

Parameters:: x (Tensor) – Input tensor, corresponding to the output of the forward operation.
Returns:: Output tensor in the original input domain of the forward operation.

forward(x: Tensor) → tuple[Tensor][source]: Apply forward of GridSamplingOp.

Note

Prefer calling the instance of the GridSamplingOp operator as operator(x) over directly calling this method. See this PyTorch discussion.

operator_norm(initial_value: Tensor, dim: Sequence[int] | None, max_iterations: int = 20, relative_tolerance: float = 1e-4, absolute_tolerance: float = 1e-5, callback: Callable[[Tensor], None] | None = None) → Tensor[source]

Power iteration for computing the operator norm of the operator.

Parameters:

initial_value (Tensor) – initial value to start the iteration; must be element of the domain. if the initial value contains a zero-vector for one of the considered problems, the function throws an ValueError.
dim (Sequence[int] | None) –
The dimensions of the tensors on which the operator operates. The choice of dim determines how the operator norm is inperpreted. For example, for a matrix-vector multiplication with a batched matrix tensor of shape (batch1, batch2, row, column) and a batched input tensor of shape (batch1, batch2, row):
- If dim=None, the operator is considered as a block diagonal matrix with batch1*batch2 blocks and the result is a tensor containing a single norm value (shape (1, 1, 1)).
- If dim=(-1), batch1*batch2 matrices are considered, and for each a separate operator norm is computed.
- If dim=(-2,-1), batch1 matrices with batch2 blocks are considered, and for each matrix a separate operator norm is computed.
Thus, the choice of dim determines implicitly determines the domain of the operator.
max_iterations (int, default: 20) – maximum number of iterations
relative_tolerance (float, default: 1e-4) – absolute tolerance for the change of the operator-norm at each iteration; if set to zero, the maximal number of iterations is the only stopping criterion used to stop the power iteration.
absolute_tolerance (float, default: 1e-5) – absolute tolerance for the change of the operator-norm at each iteration; if set to zero, the maximal number of iterations is the only stopping criterion used to stop the power iteration.
callback (Callable[[Tensor], None] | None, default: None) – user-provided function to be called at each iteration

Returns:

An estimaton of the operator norm. Shape corresponds to the shape of the input tensor initial_value with the dimensions specified in dim reduced to a single value. The pointwise multiplication of initial_value with the result of the operator norm will always be well-defined.

__add__(other: LinearOperator | Tensor | complex) → LinearOperator[source]

__add__(other: Operator[Tensor, tuple[Tensor]]) → Operator[Tensor, tuple[Tensor]]

Operator addition.

Returns lambda x: self(x) + other(x) if other is a operator, lambda x: self(x) + other if other is a tensor

__and__(other: LinearOperator) → LinearOperatorMatrix[source]

Vertical stacking of two LinearOperators.

A&B is a LinearOperatorMatrix with two rows, with (A&B)(x) == (A(x), B(x)). See mrpro.operators.LinearOperatorMatrix for more information.

__matmul__(other: LinearOperator) → LinearOperator[source]

__matmul__(other: Operator[Unpack[Tin2], tuple[Tensor]] | Operator[Unpack[Tin2], tuple[Tensor, ...]]) → Operator[Unpack[Tin2], tuple[Tensor]]

Operator composition.

Returns lambda x: self(other(x))

__mul__(other: Tensor | complex) → LinearOperator[source]

Operator elementwise left multiplication with tensor/scalar.

Returns lambda x: self(x*other)

__or__(other: LinearOperator) → LinearOperatorMatrix[source]

Horizontal stacking of two LinearOperators.

A|B is a LinearOperatorMatrix with two columns, with (A|B)(x1,x2) == A(x1) + B(x2). See mrpro.operators.LinearOperatorMatrix for more information.

__radd__(other: Tensor | complex) → LinearOperator[source]

Operator addition.

Returns lambda x: self(x) + other*x

__rmul__(other: Tensor | complex) → LinearOperator[source]

Operator elementwise right multiplication with tensor/scalar.

Returns lambda x: other*self(x)