fields
This module contains finite-difference regularisers and associated utilities for tensors that contain dense vector fields.
Each function implement the following set of penalties, which can be combined:
- absolute: the absolute energy is the sum of squared values, i.e., \(\mathcal{L} = \frac{1}{2} \sum_c \int f_c\left(\mathbf{x}\right)^2 \mathrm{d}\mathbf{x}\).
- membrane: the membrane energy is the sum of squared first order derivatives, i.e., \(\mathcal{L} = \frac{1}{2} \sum_c \int \lVert \left(\boldsymbol{\nabla}f_c\right)\left(\mathbf{x}\right) \rVert_2^2 \mathrm{d}\mathbf{x}\), where \(\boldsymbol{\nabla}f_c\) is the gradient of the c-th component of the vector field \(\boldsymbol{f}\).
- bending: the bending energy is the sum of squared second order derivatives, i.e., \(\mathcal{L} = \frac{1}{2} \sum_c \int \lVert \left(\mathbf{H}f_c\right)\left(\mathbf{x}\right) \rVert_F^2 \mathrm{d}\mathbf{x}\), where \(\mathbf{H}f_c\) is the Hessian matrix of the c-th component of the vector field \(\boldsymbol{f}\).
We further allow a local weighting of the penalty, which in the case of the membrane energy yields \(\mathcal{L} = \frac{1}{2} \sum_c \int w_c\left(\mathbf{x}\right) \lVert \left(\boldsymbol{\nabla}f_c\right)\left(\mathbf{x}\right) \rVert_2^2 \mathrm{d}\mathbf{x}\).
In practice, \(\boldsymbol{f}\) is a dense discrete field, i.e., \(\mathbf{f} \in \mathbb{R}^{NC}\) (where \(N\) is the number of voxels). All these penalties are then quadratic forms in \(\mathbf{f}\): \(\mathcal{L} = \frac{1}{2}\mathbf{f}^{T}\mathbf{Lf}\). The penalties are implemented using finite difference and, in the absence of local weighting, \(\mathbf{L}\) takes the form of a convolution with a small kernel.
field_matvec
field_matvec(ndim, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
Apply a spatial regularization matrix.
Note
This function computes the matrix-vector product \(\mathbf{L} \times \mathbf{f}\), where \(\mathbf{f}\) is a scalar or vector field and \(\mathbf{L}\) encodes a finite-difference penalty.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ndim |
`int`
|
Number of spatial dimensions |
required |
vec |
`(*batch, *spatial, nc) tensor`
|
Input vector field, with shape |
required |
weight |
`(*batch, *spatial, nc|1) tensor`
|
Weight map, to spatially modulate the regularization.
With shape |
None
|
absolute |
`[sequence of] float`
|
Penalty on absolute values (per channel). |
0
|
membrane |
`[sequence of] float`
|
Penalty on first derivatives (per channel). |
0
|
bending |
`[sequence of] float`
|
Penalty on second derivatives (per channel). |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
out |
`(*batch, *spatial, nc) tensor`
|
Output placeholder |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
out |
`(*batch, *spatial, nc) tensor`
|
|
field_matvec_add
field_matvec_add(ndim, inp, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None, _sub=False)
See field_matvec
field_matvec_add_
field_matvec_add_(ndim, inp, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, _sub=False)
See field_matvec
field_matvec_sub
field_matvec_sub(ndim, inp, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
See field_matvec
field_matvec_sub_
field_matvec_sub_(ndim, inp, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1)
See field_matvec
field_kernel
field_kernel(shape, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None, **backend)
Return the kernel of a Toeplitz regularization matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shape |
`int or list[int]`
|
Number of spatial dimensions or shape of the tensor |
required |
absolute |
`[sequence of] float`
|
Penalty on absolute values (per channel). |
0
|
membrane |
`[sequence of] float`
|
Penalty on first derivatives (per channel). |
0
|
bending |
`[sequence of] float`
|
Penalty on second derivatives (per channel). |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
out |
`(*shape, nc) tensor,` optional
|
Output placeholder |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
out |
`(*shape, nc) tensor`
|
Convolution kernel, with shape |
field_kernel_add
field_kernel_add(ndim, inp, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None, _sub=False)
See flow_kernel
field_kernel_add_
field_kernel_add_(ndim, inp, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, _sub=False)
See flow_kernel
field_kernel_sub
field_kernel_sub(ndim, inp, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
See field_kernel
field_kernel_sub_
field_kernel_sub_(ndim, inp, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1)
See field_kernel
field_diag
field_diag(shape, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None, **backend)
Return the diagonal of a regularization matrix.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shape |
`list[int]`
|
Shape of the tensor |
required |
weight |
`(*batch, *spatial, nc|1) tensor`
|
Weight map, to spatially modulate the regularization.
With shape |
None
|
absolute |
`[sequence of] float`
|
Penalty on absolute values (per channel). |
0
|
membrane |
`[sequence of] float`
|
Penalty on first derivatives (per channel). |
0
|
bending |
`[sequence of] float`
|
Penalty on second derivatives (per channel). |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
out |
`(*batch, *spatial, nc) tensor`
|
Output placeholder, with shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
out |
`(*batch, *spatial, nc) tensor`
|
Diagonal of the regulariser, with shape |
field_diag_add
field_diag_add(ndim, inp, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None, _sub=False)
See field_diag
field_diag_add_
field_diag_add_(ndim, inp, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, _sub=False)
See field_diag
field_diag_sub
field_diag_sub(ndim, inp, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
See field_diag
field_diag_sub_
field_diag_sub_(ndim, inp, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1)
See field_diag
field_precond
field_precond(ndim, mat, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
Apply the preconditioning \((\mathbf{H} + \operatorname{diag}(\mathbf{L}))^{-1} \times \mathbf{f}\).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ndim |
`int`
|
Number of spatial dimensions |
required |
mat |
`(*batch, *spatial, CC) tensor`
|
Preconditioning matrix \(\mathbf{H}\)
with shape |
required |
vec |
`(*batch, *spatial, C) tensor`
|
Point \(\mathbf{f}\) at which to solve the system,
with shape |
required |
weight |
`(*batch, *spatial, nc|1) tensor`
|
Regularization weight map, with shape |
None
|
absolute |
`float`
|
Penalty on absolute values. |
0
|
membrane |
`float`
|
Penalty on first derivatives. |
0
|
bending |
`float`
|
Penalty on second derivatives. |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
out |
`(*batch, *spatial, C) tensor`
|
Output placeholder, with shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
out |
`(*batch, *spatial, C) tensor`
|
Preconditioned vector, with shape |
field_precond_
field_precond_(ndim, mat, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1)
See field_precond
field_forward
field_forward(ndim, mat, vec, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, out=None)
Apply the forward matrix-vector product \((\mathbf{H} + \mathbf{L}) \times \mathbf{f}\).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ndim |
`int`
|
Number of spatial dimensions |
required |
mat |
`(*batch, *spatial, CC) tensor`
|
Matrix field \(\mathbf{H}\) with shape |
required |
vec |
`(*batch, *spatial, C) tensor`
|
Vector field \(\mathbf{f}\), with shape |
required |
weight |
`(*batch, *spatial, nc|1) tensor`
|
Regularization weight map, with shape |
None
|
absolute |
`float`
|
Penalty on absolute values. |
0
|
membrane |
`float`
|
Penalty on first derivatives. |
0
|
bending |
`float`
|
Penalty on second derivatives. |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
out |
`(*batch, *spatial, C) tensor`
|
Output placeholder, with shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
out |
`(*batch, *spatial, C) tensor`
|
Matrix-vector product, with shape |
field_relax_
field_relax_(ndim, field, hes, grd, weight=None, absolute=0, membrane=0, bending=0, bound='dct2', voxel_size=1, nb_iter=1)
Perform relaxation iterations (inplace).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ndim |
`int`
|
Number of spatial dimensions |
required |
field |
`(*batch, *spatial, nc) tensor`
|
Warm start, with shape |
required |
hes |
`(*batch, *spatial, nc*(nc+1)//2) tensor`
|
Input symmetric Hessian, in voxels.
With shape |
required |
grd |
`(*batch, *spatial, nc) tensor`
|
Input gradient, in voxels.
With shape |
required |
weight |
`(*batch, *spatial, 1|nc) tensor`
|
Weight map, to spatially modulate the regularization.
With shape |
None
|
absolute |
`[sequence of] float`
|
Penalty on absolute values. |
0
|
membrane |
`[sequence of] float`
|
Penalty on first derivatives. |
0
|
bending |
`[sequence of] float`
|
Penalty on second derivatives. |
0
|
bound |
`[sequence of] BoundType`
|
Boundary conditions. |
'dft'
|
voxel_size |
`[sequence of] float`
|
Voxel size. |
1
|
nb_iter |
`int`
|
Number of iterations |
1
|
Returns:
| Name | Type | Description |
|---|---|---|
flow |
`(*batch, *spatial, nc) tensor`
|
Refined solution with shape |