:mod:`torchfilter.utils` ======================== .. py:module:: torchfilter.utils Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: torchfilter.utils.JulierSigmaPointStrategy torchfilter.utils.MerweSigmaPointStrategy torchfilter.utils.SigmaPointStrategy torchfilter.utils.UnscentedTransform .. py:class:: JulierSigmaPointStrategy Bases: :class:`torchfilter.utils.SigmaPointStrategy` .. autoapi-inheritance-diagram:: torchfilter.utils.JulierSigmaPointStrategy :parts: 1 Sigma point selection in this style of [1]. [1] https://www.cs.unc.edu/~welch/kalman/media/pdf/Julier1997_SPIE_KF.pdf :keyword lambd: Spread parameter; sometimes denoted as kappa. If ``None``\ , we use ``3 - dim``. :kwtype lambd: Optional[float] .. attribute:: lambd :annotation: :Optional[float] .. method:: compute_lambda(self, dim: int) -> float Compute sigma point scaling parameter. :param dim: Dimensionality of input vectors. :type dim: int :returns: *float* -- Lambda scaling parameter. .. method:: compute_sigma_weights(self, dim: int) -> Tuple[torch.Tensor, torch.Tensor] Helper for computing sigma weights. :param dim: Dimensionality of input vectors. :type dim: int :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Covariance and mean weights. We expect 1D float32 tensors on the CPU. .. py:class:: MerweSigmaPointStrategy Bases: :class:`torchfilter.utils.SigmaPointStrategy` .. autoapi-inheritance-diagram:: torchfilter.utils.MerweSigmaPointStrategy :parts: 1 Sigma point selection in the style of [2]. [2] http://www.gatsby.ucl.ac.uk/~byron/nlds/merwe2003a.pdf :keyword alpha: Spread parameter. Defaults to ``1e-2``. :kwtype alpha: float :keyword kappa: Secondary scaling parameter, which is typically set to ``0.0`` or ``3 - dim``. If None, we use ``3 - dim``. :kwtype kappa: Optional[float] :keyword beta: Extra sigma parameter. Defaults to ``2`` (optimal for Gaussians, as per Section 3.2 in [2]). :kwtype beta: float .. attribute:: alpha :annotation: :float = 0.01 .. attribute:: beta :annotation: :float = 2.0 .. attribute:: kappa :annotation: :Optional[float] .. method:: compute_lambda(self, dim: int) -> float Compute sigma point scaling parameter. :param dim: Dimensionality of input vectors. :type dim: int :returns: *float* -- Lambda scaling parameter. .. method:: compute_sigma_weights(self, dim: int) -> Tuple[torch.Tensor, torch.Tensor] Helper for computing sigma weights. :param dim: Dimensionality of input vectors. :type dim: int :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Covariance and mean weights. We expect 1D float32 tensors on the CPU. .. py:class:: SigmaPointStrategy Bases: :class:`abc.ABC` .. autoapi-inheritance-diagram:: torchfilter.utils.SigmaPointStrategy :parts: 1 Strategy to use for computing sigma weights + selecting sigma points. .. method:: compute_lambda(self, dim: int) -> float :abstractmethod: Compute sigma point scaling parameter. :param dim: Dimensionality of input vectors. :type dim: int :returns: *float* -- Lambda scaling parameter. .. method:: compute_sigma_weights(self, dim: int) -> Tuple[torch.Tensor, torch.Tensor] :abstractmethod: Helper for computing sigma weights. :param dim: Dimensionality of input vectors. :type dim: int :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Covariance and mean weights. We expect 1D float32 tensors on the CPU. .. py:class:: UnscentedTransform(*, dim: int, sigma_point_strategy: SigmaPointStrategy = JulierSigmaPointStrategy()) Helper class for performing (batched, differentiable) unscented transforms. :keyword dim: Input dimension. :kwtype dim: int :keyword sigma_point_strategy: Strategy to use for sigma point selection. Defaults to Julier. :kwtype sigma_point_strategy: torchfilter.utils.SigmaPointStrategy, optional .. attribute:: weights_c :annotation: :torch.Tensor Unscented transform covariance weights. Note that this will be initially instantiated on the CPU, and moved in ``compute_distribution()``. :type: torch.Tensor .. attribute:: weights_m :annotation: :torch.Tensor Unscented transform mean weights. Note that this will be initially instantiated on the CPU, and moved in ``compute_distribution()``. :type: torch.Tensor .. method:: select_sigma_points(self, input_mean: torch.Tensor, input_covariance: types.CovarianceTorch) -> torch.Tensor Select sigma points. :param input_mean: Distribution mean. Shape should be ``(N, dim)``. :type input_mean: torch.Tensor :param input_covariance: Distribution covariance. Shape should be ``(N, dim, dim)``. :type input_covariance: torch.Tensor :returns: *torch.Tensor* -- Selected sigma points, with shape ``(N, 2 * dim + 1, dim)``. .. method:: select_sigma_points_square_root(self, input_mean: torch.Tensor, input_scale_tril: types.ScaleTrilTorch) -> torch.Tensor Select sigma points using square root of covariance. :param input_mean: Distribution mean. Shape should be ``(N, dim)``. :type input_mean: torch.Tensor :param input_scale_tril: Cholesky decomposition of distribution covariance. Shape should be ``(N, dim, dim)``. :type input_scale_tril: torch.Tensor :returns: *torch.Tensor* -- Selected sigma points, with shape ``(N, 2 * dim + 1, dim)``. .. method:: compute_distribution(self, sigma_points: torch.Tensor) -> Tuple[torch.Tensor, types.CovarianceTorch] Estimate a distribution from selected sigma points. :param sigma_points: Sigma points, with shape ``(N, 2 * dim + 1, dim)``. :type sigma_points: torch.Tensor :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Mean and covariance, with shapes ``(N, dim)`` and ``(N, dim, dim)`` respectively. .. method:: compute_distribution_square_root(self, sigma_points: torch.Tensor, additive_noise_scale_tril: Optional[types.ScaleTrilTorch] = None) -> Tuple[torch.Tensor, types.ScaleTrilTorch] Estimate a distribution from selected sigma points; square root formulation. :param sigma_points: Sigma points, with shape ``(N, 2 * dim + 1, dim)``. :type sigma_points: torch.Tensor :param additive_noise_scale_tril: Parameterizes an additive Gaussian noise term. Should be lower-trinagular, with shape ``(N, dim, dim)``. :type additive_noise_scale_tril: torch.Tensor, optional :returns: *Tuple[torch.Tensor, torch.Tensor]* -- Mean and square root of covariance, with shapes ``(N, dim)`` and ``(N, dim, dim)`` respectively.