torchfilter.utils
¶
Package Contents¶
Classes¶
Sigma point selection in this style of [1]. 

Sigma point selection in the style of [2]. 

Strategy to use for computing sigma weights + selecting sigma points. 

Helper class for performing (batched, differentiable) unscented transforms. 

class
torchfilter.utils.
JulierSigmaPointStrategy
[source]¶ Bases:
torchfilter.utils.SigmaPointStrategy
Sigma point selection in this style of [1].
[1] https://www.cs.unc.edu/~welch/kalman/media/pdf/Julier1997_SPIE_KF.pdf
 Keyword Arguments
lambd (Optional[float]) – Spread parameter; sometimes denoted as kappa. If
None
, we use3  dim
.

lambd
:Optional[float]¶

class
torchfilter.utils.
MerweSigmaPointStrategy
[source]¶ Bases:
torchfilter.utils.SigmaPointStrategy
Sigma point selection in the style of [2].
[2] http://www.gatsby.ucl.ac.uk/~byron/nlds/merwe2003a.pdf
 Keyword Arguments
alpha (float) – Spread parameter. Defaults to
1e2
.kappa (Optional[float]) – Secondary scaling parameter, which is typically set to
0.0
or3  dim
. If None, we use3  dim
.beta (float) – Extra sigma parameter. Defaults to
2
(optimal for Gaussians, as per Section 3.2 in [2]).

alpha
:float = 0.01¶

beta
:float = 2.0¶

kappa
:Optional[float]¶

class
torchfilter.utils.
SigmaPointStrategy
[source]¶ Bases:
abc.ABC
Strategy to use for computing sigma weights + selecting sigma points.

class
torchfilter.utils.
UnscentedTransform
(*, dim: int, sigma_point_strategy: SigmaPointStrategy = JulierSigmaPointStrategy())[source]¶ Helper class for performing (batched, differentiable) unscented transforms.
 Keyword Arguments
dim (int) – Input dimension.
sigma_point_strategy (torchfilter.utils.SigmaPointStrategy, optional) – Strategy to use for sigma point selection. Defaults to Julier.

weights_c
:torch.Tensor¶ Unscented transform covariance weights. Note that this will be initially instantiated on the CPU, and moved in
compute_distribution()
. Type
torch.Tensor

weights_m
:torch.Tensor¶ Unscented transform mean weights. Note that this will be initially instantiated on the CPU, and moved in
compute_distribution()
. Type
torch.Tensor

select_sigma_points
(self, input_mean: torch.Tensor, input_covariance: types.CovarianceTorch) → torch.Tensor[source]¶ Select sigma points.
 Parameters
input_mean (torch.Tensor) – Distribution mean. Shape should be
(N, dim)
.input_covariance (torch.Tensor) – Distribution covariance. Shape should be
(N, dim, dim)
.
 Returns
torch.Tensor – Selected sigma points, with shape
(N, 2 * dim + 1, dim)
.

select_sigma_points_square_root
(self, input_mean: torch.Tensor, input_scale_tril: types.ScaleTrilTorch) → torch.Tensor[source]¶ Select sigma points using square root of covariance.
 Parameters
input_mean (torch.Tensor) – Distribution mean. Shape should be
(N, dim)
.input_scale_tril (torch.Tensor) – Cholesky decomposition of distribution covariance. Shape should be
(N, dim, dim)
.
 Returns
torch.Tensor – Selected sigma points, with shape
(N, 2 * dim + 1, dim)
.

compute_distribution
(self, sigma_points: torch.Tensor) → Tuple[torch.Tensor, types.CovarianceTorch][source]¶ Estimate a distribution from selected sigma points.
 Parameters
sigma_points (torch.Tensor) – Sigma points, with shape
(N, 2 * dim + 1, dim)
. Returns
Tuple[torch.Tensor, torch.Tensor] – Mean and covariance, with shapes
(N, dim)
and(N, dim, dim)
respectively.

compute_distribution_square_root
(self, sigma_points: torch.Tensor, additive_noise_scale_tril: Optional[types.ScaleTrilTorch] = None) → Tuple[torch.Tensor, types.ScaleTrilTorch][source]¶ Estimate a distribution from selected sigma points; square root formulation.
 Parameters
sigma_points (torch.Tensor) – Sigma points, with shape
(N, 2 * dim + 1, dim)
.additive_noise_scale_tril (torch.Tensor, optional) – Parameterizes an additive Gaussian noise term. Should be lowertrinagular, with shape
(N, dim, dim)
.
 Returns
Tuple[torch.Tensor, torch.Tensor] – Mean and square root of covariance, with shapes
(N, dim)
and(N, dim, dim)
respectively.