fiery.diffeo

Scaling-and-squaring and geodesic shooting layers in PyTorch.

Attributes

default_backend `module-attribute`

default_backend = interpol

Backend used by every layer and function that is not given an explicit backend= argument. Defaults to interpol.

Classes

Exp

Exp(bound='circulant', steps=8, anagrad=False, backend=None)

Bases: Module

Exponentiate a stationary velocity field by scaling and squaring.

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions.	`'circulant'`
`steps`	`int`	Number of scaling and squaring steps.	`8`
`anagrad`	`bool`	Use analytical gradients instead of autograd.	`False`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Notes

The number of equivalent Euler integration steps is 2**steps.

Analytical gradients use less memory than autograd gradients, as they do not require storing intermediate time steps during scaling and squaring. However, they may be slightly less accurate.

In differential equation terms, autograd corresponds to the strategy "discretize then optimize", whereas analytical gradients correspond to the strategy "optimize then discretize".

Methods:

BCH

BCH(bound='circulant', order=2, backend=None)

Bases: Module

Compose two stationary velocity fields using the BCH formula.

The Baker-Campbell-Hausdorff (BCH) formula gives the velocity field z such that exp(z) = exp(x) o exp(y), as a series of nested Lie brackets of x and y. The series is truncated at order.

See: https://en.wikipedia.org/wiki/BCH_formula

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions.	`'circulant'`
`order`	`(1, 2, 3, 4)`	Maximum order used in the BCH series.	`1`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Shoot

Shoot(metric=default_metric, steps=None, fast=True, backend=None)

Bases: Module

Exponentiate an initial velocity field by geodesic shooting.

Returns the forward transform.

Parameters:

Name	Type	Description	Default
`metric`	`Metric`	A Riemannian metric.	`default_metric`
`steps`	`int`	Number of Euler integration steps. If None, use an educated guess based on the magnitude of the initial velocity.	`None`
`fast`	`bool`	Use a faster but slightly less accurate integration scheme.	`True`
`backend`	`module`	Backend to use to implement pullback and pushforward. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

ShootInv

ShootInv(metric=default_metric, steps=None, fast=True, backend=None)

Bases: Module

Exponentiate an initial velocity field by geodesic shooting.

Returns the inverse transform.

Parameters:

Name	Type	Description	Default
`metric`	`Metric`	A Riemannian metric.	`default_metric`
`steps`	`int`	Number of Euler integration steps. If None, use an educated guess based on the magnitude of the initial velocity.	`None`
`fast`	`bool`	Use a faster but slightly less accurate integration scheme.	`True`
`backend`	`module`	Backend to use to implement pullback and pushforward. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

ShootBoth

ShootBoth(metric=default_metric, steps=None, fast=True, backend=None)

Bases: Module

Exponentiate an initial velocity field by geodesic shooting.

Returns both the forward and the inverse transform.

Parameters:

Name	Type	Description	Default
`metric`	`Metric`	A Riemannian metric.	`default_metric`
`steps`	`int`	Number of Euler integration steps. If None, use an educated guess based on the magnitude of the initial velocity.	`None`
`fast`	`bool`	Use a faster but slightly less accurate integration scheme.	`True`
`backend`	`module`	Backend to use to implement pullback and pushforward. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Compose

Compose(bound='circulant', backend=None)

Bases: Module

Compose two displacement fields.

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions.	`'circulant'`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Pull

Pull(bound='wrap', backend=None)

Bases: Module

Warp an image using a displacement field.

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'wrap', 'reflect', 'mirror'}`	Boundary conditions. If warping a displacement field, can also be one of the metric bounds: {'circulant', 'neumann', 'dirichlet', 'sliding'}	`'wrap'`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Push

Push(bound='wrap', normalize=False, backend=None)

Bases: Module

Splat an image using a displacement field.

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'wrap', 'reflect', 'mirror'}`	Boundary conditions. If splatting a displacement field, can also be one of the metric bounds: {'circulant', 'neumann', 'dirichlet', 'sliding'}	`'wrap'`
`normalize`	`bool`	Whether to divide the pushed values by the number of values pushed onto each voxel (i.e., the result of `Count`).	`False`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Count

Count(bound='wrap', backend=None)

Bases: Module

Splat an image of ones using a displacement field.

Parameters:

Name	Type	Description	Default
`bound`	`[list of] {'wrap', 'reflect', 'mirror'}`	Boundary conditions. If splatting a displacement field, can also be one of the metric bounds: {'circulant', 'neumann', 'dirichlet', 'sliding'}	`'wrap'`
`backend`	`module`	Backend to use to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`None`

Methods:

Functions:

compose

compose(flow_left, flow_right, bound='circulant', has_identity=False, backend=interpol)

Compute the composition flow_left o flow_right

Parameters:

Name	Type	Description	Default
`flow_left`	`(..., *shape, D) tensor`	Left-hand side field.	required
`flow_right`	`(..., *shape, D) tensor`	Right-hand side field.	required
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions.	`'circulant'`
`has_identity`	`bool`	Whether the inputs are transformation (True) or displacement (False) fields.	`False`
`backend`	`module`	Backend used to resample `flow_left`.	`interpol`

Returns:

Name	Type	Description
`flow`	`(..., *shape, D) tensor`	Composed field, in the same convention as the inputs.

bch

bch(vel_left, vel_right, order=2, bound='circulant', backend=default_backend)

Compose two stationary velocity fields with the BCH formula.

Finds the velocity field v such that exp(v) = exp(vel_left) o exp(vel_right), using the Baker-Campbell-Hausdorff series truncated at order. The series is built from nested Lie brackets of the two inputs, so a higher order is more accurate but costs more brackets.

See: https://en.wikipedia.org/wiki/BCH_formula

Parameters:

Name	Type	Description	Default
`vel_left`	`(B, *shape, D) tensor`	Left-hand side velocity field.	required
`vel_right`	`(B, *shape, D) tensor`	Right-hand side velocity field.	required
`order`	`(1, 2, 3, 4)`	Truncation order of the BCH series.	`1`
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions.	`'circulant'`
`backend`	`module`	Backend used to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`default_backend`

Returns:

Name	Type	Description
`vel`	`(B, *shape, D) tensor`	Composed velocity field.

Raises:

Type	Description
`ValueError`	If `order` is greater than 4.

exp

exp(vel, steps=8, bound='circulant', anagrad=False, backend=default_backend)

Exponentiate a stationary velocity field by scaling and squaring.

Parameters:

Name	Type	Description	Default
`vel`	`([batch], *spatial, dim) tensor`	Stationary velocity field.	required
`steps`	`int`	Number of scaling and squaring steps (corresponding to 2**steps integration steps).	`8`
`bound`	`[list of] {'circulant', 'neumann', 'dirichlet', 'sliding'}`	Boundary conditions	`'circulant'`
`anagrad`	`bool`	Use analytical gradients rather than autodiff gradients in the backward pass. Should be more memory efficient and (maybe) faster.	`False`
`backend`	`module`	Backend used to implement resampling. Must be one of the modules under `fiery.diffeo.backends`.	`default_backend`

Returns:

Name	Type	Description
`flow`	`([batch], *spatial, dim) tensor`	Exponentiated displacement field.

fiery.diffeo

Attributes

default_backend module-attribute

Classes

Exp

Methods:

BCH

Methods:

Shoot

Methods:

ShootInv

Methods:

ShootBoth

Methods:

Compose

Methods:

Pull

Methods:

Push

Methods:

Count

Methods:

Functions:

compose

bch

exp

default_backend `module-attribute`