imwip.solvers

imwip.solvers.differentiation

file: differentiation.py
brief: provides differentiation functionality to ImWIP operators and pylops operators that contain ImWIP operators.
author: Jens Renders

imwip.solvers.differentiation.diff(A, x, to=None, matrix=False)

Given an imwip operator \(A = A(p)\) (where \(p\) represents all the parameters of \(A\)), or a pylops block operator built of those, this function gives the derivative of \(A(p)x\) towards \(p\).

Parameters

A (LinearOperator) – An ImWIP image warping operator or a Pylops block operator containing ImWIP image warping operators.
x (numpy.ndarray) – A raveled image on which A acts
to (string or sequence of strings, optional) – a parameter or list of parameters to which to differentiate.
matrix (bool, optional) – if True, the derviative is returned as a scipy.sparse.coo_matrix. Otherwise it will be returned as LinearOperator. Defaults to false

Returns

The derivative or list of derivatives towards the parameters specified in to

Return type

LinearOperator or scipy.sparse.coo_matrix or list of the same type.

imwip.solvers.invert_dvf

file: invert_dvf.py
brief: Iterative inversion of a DVF, which can be used for approximate adjoint or inverse warps.
author: Jens Renders

imwip.solvers.invert_dvf.invert_dvf_2D(u, v, max_iter=15, verbose=False, backend=None)

Approximately inverts a 2D DVF using the fixed point inversion technique of Chen et al. [CLC+08]

Note

A DVF can usually not be inverted exactly, since the vectors are only defined on integer coordinates while they point at real coordinates.

Parameters

u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
max_iter (int, optional) – Number of fixed point iterations to perform, defaults to 15.
verbose (bool, optional) – whether to show a progress bar, defaults to False.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

Returns

inv_u, inv_v: the two components of the inverted dvf

Return type

numpy.ndarray, numpy.ndarray

imwip.solvers.invert_dvf.invert_dvf_3D(u, v, w, max_iter=15, verbose=False, backend=None)

Approximately inverts a 3D DVF using the fixed point inversion technique of Chen et al. [CLC+08]

Note

A DVF can usually not be inverted exactly, since the vectors are only defined on integer coordinates while they point at real coordinates.

Parameters

u (numpy.ndarray) – First component of the DVF describing the warp
v (numpy.ndarray) – Second component of the DVF describing the warp
w (numpy.ndarray) – Second component of the DVF describing the warp
max_iter (int, optional) – Number of fixed point iterations to perform. Defaults to 15.
verbose (bool, optional) – whether to show a progress bar. Defaults to False.
backend (cpp or numba, optional) – Whether to use the cpp or numba backend. If None, cpp will be used if available, else numba

Returns

inv_u, inv_v, inv_w: the three components of the inverted dvf

Return type

numpy.ndarray, numpy.ndarray, numpy.ndarray

imwip.solvers.solvers

file: solvers.py
brief: a small collection of solvers, which are suitable for most inverse problems involving image warps.
author: Jens Renders

imwip.solvers.solvers.barzilai_borwein(grad_f, x0, f=None, line_search_iter=None, init_step=None, bounds=None, projector=None, max_iter=100, verbose=True, callback=None)

Minimizes a function f using projected gradient descent with the step size of Barzilai and Borwein [BB88] and bounds. The BB stepsize is only defined from the second iteration on. Therefore, the initial step size has to be computed by some other method. By default it will be 1, but it can be specified or it can be searched with a line search.

Note

the function f itself is not a required arguement for this optimizer. It is only needed if you want to use a line search for the intial step size.

Parameters

grad_f (callable) – gradient of the function to be minimized. It should return a 1D numpy.ndarray of the same size as its input (which is the same size as x0).
x0 (numpy.ndarray) – initial guess for the minimum
f (callable, optional) – function to be minimized, used for the line search for the initial step size. Not used if line_search_iter is None. It should return a float
line_search_iter (int, optional) – How many iterations to perform in the line search for the initial stepsize. Leave empty for no line search.
init_step (float, optional) – user specified initial stepsize. Leave empty to use line search.
bounds (tuple of floats or tuple of sequences of floats, optional) – minimum and maximum constraints on the variables. Leave empty for no bounds, and use numpy.inf or -numpy.inf to bound only from one side.
projector (callable, optional) – a custom function that projects the variable on a constraint set.
max_iter (int, optional) – maximum number of iterations to perform
verbose (bool, optional) – whether to show a progress bar, defaults to False.
callback (callable, optional) – If given, this function will be called each iteration. The current estimate of the minimum will be passed as arguement.

Returns

the minimum x, same size as x0

Return type

numpy.ndarray

imwip.solvers.solvers.split_barzilai_borwein(grad_f, x0, f=None, line_search_iter=None, init_step=None, bounds=None, projector=None, max_iter=100, verbose=True, callback=None)

A split version of barzilai_borwein(). Instead of using a single stepsize for all variables, this function allows to group the variables and use a separate stepsize for each group.

Parameters

grad_f (callable) – gradient of the function to be minimized. It should return a list of 1D numpy.ndarray (one for each group of variables) of the same size as its input (which is the same size as x0).
x0 (list of numpy.ndarray) – initial guess for the minimum, one array per group of variables.
f (callable, optional) – function to be minimized, used for the line search for the initial step size. Not used if line_search_iter is None. It should return a float
line_search_iter (int, optional) – How many iterations to perform in the line search for the initial stepsize. Leave empty for no line search.
init_step (float, optional) – user specified initial stepsize. Leave empty to use line search.
bounds (list of bounds as specified in barzilai_borwein()) – minimum and maximum constraints on the variables. Leave empty for no bounds, and use numpy.inf or -numpy.inf to bound only from one side.
projector (callable, optional) – a custom function that projects the variable on a constraint set.
max_iter (int, optional) – maximum number of iterations to perform
verbose (bool, optional) – whether to show a progress bar, defaults to False.
callback (callable, optional) – If given, this function will be called each iteration. The current estimate of the minimum will be passed as arguement.

Returns

the minimum x

Return type

list of numpy.ndarray