:mod:`torchfilter.filters` ========================== .. py:module:: torchfilter.filters .. autoapi-nested-parse:: Filter implementations; can either be used directly or subclassed. Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: torchfilter.filters.ExtendedInformationFilter torchfilter.filters.ExtendedKalmanFilter torchfilter.filters.ParticleFilter torchfilter.filters.SquareRootUnscentedKalmanFilter torchfilter.filters.UnscentedKalmanFilter torchfilter.filters.VirtualSensorExtendedInformationFilter torchfilter.filters.VirtualSensorExtendedKalmanFilter torchfilter.filters.VirtualSensorSquareRootUnscentedKalmanFilter torchfilter.filters.VirtualSensorUnscentedKalmanFilter .. py:class:: ExtendedInformationFilter(*, dynamics_model: DynamicsModel, measurement_model: KalmanFilterMeasurementModel) Bases: :class:`torchfilter.base.KalmanFilterBase` .. autoapi-inheritance-diagram:: torchfilter.filters.ExtendedInformationFilter :parts: 1 Information form of a Kalman filter; generally equivalent to an EKF but internally parameterizes uncertainties with the inverse covariance matrix. For building estimators with more complex observation spaces (eg images), see ``VirtualSensorExtendedInformationFilter``. .. attribute:: information_vector :annotation: :torch.Tensor Information vector of our posterior; shape should be ``(N, state_dim)``. :type: torch.Tensor .. attribute:: information_matrix :annotation: :torch.Tensor Information matrix of our posterior; shape should be ``(N, state_dim, state_dim)``. :type: torch.Tensor .. method:: belief_covariance(self) -> types.CovarianceTorch :property: Posterior covariance. Shape should be ``(N, state_dim, state_dim)``. .. py:class:: ExtendedKalmanFilter(*, dynamics_model: DynamicsModel, measurement_model: KalmanFilterMeasurementModel, **unused_kwargs) Bases: :class:`torchfilter.base.KalmanFilterBase` .. autoapi-inheritance-diagram:: torchfilter.filters.ExtendedKalmanFilter :parts: 1 Generic differentiable EKF. For building estimators with more complex observation spaces (eg images), see ``VirtualSensorExtendedKalmanFilter``. .. py:class:: ParticleFilter(*, dynamics_model: DynamicsModel, measurement_model: ParticleFilterMeasurementModel, num_particles: int = 100, resample: Optional[bool] = None, soft_resample_alpha: float = 1.0, estimation_method: str = 'weighted_average') Bases: :class:`torchfilter.base.Filter` .. autoapi-inheritance-diagram:: torchfilter.filters.ParticleFilter :parts: 1 Generic differentiable particle filter. .. attribute:: dynamics_model Forward model. :type: torchfilter.base.DynamicsModel .. attribute:: measurement_model Observation model. :type: torchfilter.base.ParticleFilterMeasurementModel .. attribute:: num_particles Number of particles to represent our belief distribution. Defaults to 100. :type: int .. attribute:: resample If True, we resample particles & normalize weights at each timestep. If unset (None), we automatically turn resampling on in eval mode and off in train mode. :type: bool .. attribute:: soft_resample_alpha Tunable constant for differentiable resampling, as described by Karkus et al. in "Particle Filter Networks with Application to Visual Localization": https://arxiv.org/abs/1805.08975 Defaults to 1.0 (disabled). :type: float .. attribute:: estimation_method Method of producing state estimates. Options include: * 'weighted_average': average of particles weighted by their weights. * 'argmax': state of highest weighted particle. :type: str .. attribute:: particle_states :annotation: :torch.Tensor Discrete particles representing our current belief distribution. Shape should be ``(N, M, state_dim)``. :type: torch.Tensor .. attribute:: particle_log_weights :annotation: :torch.Tensor Weights corresponding to each particle, stored as log-likelihoods. Shape should be ``(N, M)``. :type: torch.Tensor .. method:: initialize_beliefs(self, *, mean: types.StatesTorch, covariance: types.CovarianceTorch) -> None Populates initial particles, which will be normally distributed. :param mean: Mean of belief. Shape should be ``(N, state_dim)``. :type mean: torch.Tensor :param covariance: Covariance of belief. Shape should be ``(N, state_dim, state_dim)``. :type covariance: torch.Tensor .. method:: forward(self, *, observations: types.ObservationsTorch, controls: types.ControlsTorch) -> types.StatesTorch Particle filter forward pass, single timestep. :param observations: observation inputs. should be either a dict of tensors or tensor of shape ``(N, ...)``. :type observations: dict or torch.Tensor :param controls: control inputs. should be either a dict of tensors or tensor of shape ``(N, ...)``. :type controls: dict or torch.Tensor :returns: *torch.Tensor* -- Predicted state for each batch element. Shape should be ``(N, state_dim).`` .. py:class:: SquareRootUnscentedKalmanFilter(*, dynamics_model: DynamicsModel, measurement_model: KalmanFilterMeasurementModel, sigma_point_strategy: Optional[utils.SigmaPointStrategy] = None) Bases: :class:`torchfilter.base.KalmanFilterBase` .. autoapi-inheritance-diagram:: torchfilter.filters.SquareRootUnscentedKalmanFilter :parts: 1 Square-root formulation of UKF. From Algorithm 3.1 of Merwe et al [1]. [1] The square-root unscented Kalman filter for state and parameter-estimation. https://ieeexplore.ieee.org/document/940586/ .. method:: belief_covariance(self) -> types.CovarianceTorch :property: Posterior covariance. Shape should be ``(N, state_dim, state_dim)``. .. py:class:: UnscentedKalmanFilter(*, dynamics_model: DynamicsModel, measurement_model: KalmanFilterMeasurementModel, sigma_point_strategy: Optional[utils.SigmaPointStrategy] = None) Bases: :class:`torchfilter.base.KalmanFilterBase` .. autoapi-inheritance-diagram:: torchfilter.filters.UnscentedKalmanFilter :parts: 1 Standard UKF. From Algorithm 2.1 of Merwe et al. [1]. For working with heteroscedastic noise models, we use the weighting approach described in [2]. [1] The square-root unscented Kalman filter for state and parameter-estimation. https://ieeexplore.ieee.org/document/940586/ [2] How to Train Your Differentiable Filter https://al.is.tuebingen.mpg.de/uploads_file/attachment/attachment/617/2020_RSS_WS_alina.pdf .. py:class:: VirtualSensorExtendedInformationFilter(*, dynamics_model: DynamicsModel, virtual_sensor_model: VirtualSensorModel) Bases: :class:`torchfilter.filters`, :class:`torchfilter.filters.ExtendedInformationFilter` .. autoapi-inheritance-diagram:: torchfilter.filters.VirtualSensorExtendedInformationFilter :parts: 1 EIF variant with a virtual sensor model. Assumes measurement model is identity. .. py:class:: VirtualSensorExtendedKalmanFilter(*, dynamics_model: DynamicsModel, virtual_sensor_model: VirtualSensorModel) Bases: :class:`torchfilter.filters`, :class:`torchfilter.filters.ExtendedKalmanFilter` .. autoapi-inheritance-diagram:: torchfilter.filters.VirtualSensorExtendedKalmanFilter :parts: 1 EKF variant with a virtual sensor model. Assumes measurement model is identity. .. py:class:: VirtualSensorSquareRootUnscentedKalmanFilter(*, dynamics_model: DynamicsModel, virtual_sensor_model: VirtualSensorModel, sigma_point_strategy: Optional[utils.SigmaPointStrategy] = None) Bases: :class:`torchfilter.filters`, :class:`torchfilter.filters.SquareRootUnscentedKalmanFilter` .. autoapi-inheritance-diagram:: torchfilter.filters.VirtualSensorSquareRootUnscentedKalmanFilter :parts: 1 Square-root UKF variant with a virtual sensor model. Assumes measurement model is identity. .. py:class:: VirtualSensorUnscentedKalmanFilter(*, dynamics_model: DynamicsModel, virtual_sensor_model: VirtualSensorModel, sigma_point_strategy: Optional[utils.SigmaPointStrategy] = None) Bases: :class:`torchfilter.filters`, :class:`torchfilter.filters.UnscentedKalmanFilter` .. autoapi-inheritance-diagram:: torchfilter.filters.VirtualSensorUnscentedKalmanFilter :parts: 1 UKF variant with a virtual sensor model. Assumes measurement model is identity.