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
1e-2
.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 lower-trinagular, 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.