EmrysFilter 0.1.0
State estimation utilities in C++23 using Eigen
Loading...
Searching...
No Matches
Emrys::FormGaussian< Params_ > Class Template Reference

The density of a Gaussian in a square-root or information form: a read-only view. More...

#include <EmrysFilter/Distributions/GaussianForm.h>

Public Types

using ParamsType = Params_
 the parameters it reads
using SpaceType = typename Params_::SpaceType
 the space the values live in
using Scalar = typename Params_::Scalar
 the scalar type
using Index = Eigen::Index
 Eigen's index type.
using VectorType = typename Params_::VectorType
 a value, such as the mean
using DifferenceVectorType = typename Params_::DifferenceVectorType
 a difference, such as a residual
using MatrixType = typename Params_::MatrixType
 a matrix over differences
using MomentsType = typename Params_::MomentsType
 the mean and covariance together

Public Member Functions

Index valueDimension () const
Index differenceDimension () const
SpaceType const & space () const
VectorType const & mean () const
MomentsType moments () const
template<typename Path>
auto marginal () const
template<typename Path>
auto marginal (Index element) const
 marginal<Path>() of repetition element of the repeated block Path starts at (see GaussianParams::marginal(element)).
Scalar logDeterminant () const
MatrixType const & root () const
Scalar logPeak () const
template<typename Derived>
Scalar squaredMahalanobisDistance (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Scalar confidence (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
bool contains (Eigen::MatrixBase< Derived > const &x, Scalar probability) const
template<typename Derived>
Scalar logDensity (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Scalar density (Eigen::MatrixBase< Derived > const &x) const
template<typename Derived>
Derived::PlainObject colorNormals (Eigen::MatrixBase< Derived > const &z) const

Static Public Attributes

static constexpr int ValueDimensionAtCompileTime = Params_::ValueDimensionAtCompileTime
 the length of a value, or Eigen::Dynamic
static constexpr int MaxValueDimensionAtCompileTime = Params_::MaxValueDimensionAtCompileTime
 a bound on the length of a value, or Eigen::Dynamic
static constexpr int DifferenceDimensionAtCompileTime = Params_::DifferenceDimensionAtCompileTime
 the length of a difference and the rows of the covariance, or Eigen::Dynamic
static constexpr int MaxDifferenceDimensionAtCompileTime = Params_::MaxDifferenceDimensionAtCompileTime
 a bound on the length of a difference, or Eigen::Dynamic
static constexpr bool IsParams = false
 a view: it checks its parameters

Detailed Description

template<typename Params_>
class Emrys::FormGaussian< Params_ >

The density of a Gaussian in a square-root or information form: a read-only view.

Represents the same density as Gaussian, evaluated from the root its parameters hold or have cached, never from a covariance:

\[ p(x) = (2\pi)^{-n/2} |\Sigma|^{-1/2} \exp\left(-\tfrac{1}{2} w^T w\right), \]

where the parameters whiten the residual \( r = x \boxminus \mu \) to \( w \) with \( w^T w = r^T \Sigma^{-1} r \), and colors standard normals by a root of \( \Sigma \), each with a triangular product or solve.

Obtained from the parameters' toDensity(), which checks the root and, in the information forms, solves for the mean. What can fail in the parameters, a mean, moments, or a marginal of a precision that is not positive definite, cannot fail here, so the four forms' densities are read alike (decisions.md [form-densities]). It checks the parameters for changes, as Gaussian checks a GaussianParams: reading it after they have changed is a programmer error (decisions.md [view-stamp]). It must not outlive its parameters. SqrtGaussian, InfoGaussian, and SqrtInfoGaussian name it [params-and-density].

Template Parameters
Params_SqrtGaussianParams, InfoGaussianParams, or SqrtInfoGaussianParams
See also
SqrtGaussianParams::toDensity(), InfoGaussianParams::toDensity(), SqrtInfoGaussianParams::toDensity()

Member Function Documentation

◆ colorNormals()

template<typename Params_>
template<typename Derived>
Derived::PlainObject Emrys::FormGaussian< Params_ >::colorNormals ( Eigen::MatrixBase< Derived > const & z) const
inlinenodiscard
Returns
\( A z \) for a root \( A \) of the covariance, \( A A^T = \Sigma \): standard normal draws in the columns of z become draws of the residual, which drawSamples() adds to the mean. \( A \) is the stored root in the square-root form and the inverse of the precision's root in the information forms, applied by a triangular solve.

◆ confidence()

template<typename Params_>
template<typename Derived>
Scalar Emrys::FormGaussian< Params_ >::confidence ( Eigen::MatrixBase< Derived > const & x) const
inlinenodiscard
Returns
the confidence of x, \( F_{\chi^2_k}(d_M^2(x)) \); see Gaussian::confidence()

◆ contains()

template<typename Params_>
template<typename Derived>
bool Emrys::FormGaussian< Params_ >::contains ( Eigen::MatrixBase< Derived > const & x,
Scalar probability ) const
inlinenodiscard
Returns
whether x lies in the probability confidence region; see Gaussian::contains()

◆ density()

template<typename Params_>
template<typename Derived>
Scalar Emrys::FormGaussian< Params_ >::density ( Eigen::MatrixBase< Derived > const & x) const
inlinenodiscard
Returns
the density at x
Warning
Underflows easily in high dimensions; prefer logDensity().

◆ differenceDimension()

template<typename Params_>
Index Emrys::FormGaussian< Params_ >::differenceDimension ( ) const
inlinenodiscard
Returns
the number of rows and columns of the covariance

◆ logDensity()

template<typename Params_>
template<typename Derived>
Scalar Emrys::FormGaussian< Params_ >::logDensity ( Eigen::MatrixBase< Derived > const & x) const
inlinenodiscard
Returns
the log of the density at x, \( \mathrm{logPeak} - \frac{1}{2}d_M^2(x) \)

◆ logDeterminant()

template<typename Params_>
Scalar Emrys::FormGaussian< Params_ >::logDeterminant ( ) const
inlinenodiscard
Returns
the log-determinant \( \log|\Sigma| \) of the covariance, from the root's diagonal

◆ logPeak()

template<typename Params_>
Scalar Emrys::FormGaussian< Params_ >::logPeak ( ) const
inlinenodiscard
Returns
the log of the density at the mean, \( -\frac{1}{2}(d \log 2\pi + \log|\Sigma|) \), with \( d \) the difference dimension

◆ marginal()

template<typename Params_>
template<typename Path>
auto Emrys::FormGaussian< Params_ >::marginal ( ) const
inlinenodiscard
Returns
the marginal of the subspace named by the path Path (a tag or a TagPath), in that subspace, as parameters of the same form: a value, since its matrix is computed (decisions.md [element-marginals]). Never fails: the parameters' own marginal<Path>() fails only where the precision of the rest is singular, which toDensity() has ruled out. The information form's is made from the cached root, as the square-root information form's is (see SqrtInfoGaussianParams::marginal<Path>()), so nothing is factorized again.

◆ mean()

template<typename Params_>
VectorType const & Emrys::FormGaussian< Params_ >::mean ( ) const
inlinenodiscard
Returns
the mean, which toDensity() solved for in the information forms

◆ moments()

template<typename Params_>
MomentsType Emrys::FormGaussian< Params_ >::moments ( ) const
inlinenodiscard
Returns
the mean and the covariance together, the covariance formed from the root and, in the information forms, carried to the differences at the mean as toGaussian() carries it. Never fails, since toDensity() has checked the root.

◆ root()

template<typename Params_>
MatrixType const & Emrys::FormGaussian< Params_ >::root ( ) const
inlinenodiscard
Returns
the square-root form's lower-triangular root \( S \), \( S S^T = \Sigma \), which the closed-form divergences between two of them read (see kullbackLeibler())

◆ space()

template<typename Params_>
SpaceType const & Emrys::FormGaussian< Params_ >::space ( ) const
inlinenodiscard
Returns
the parameters' space

◆ squaredMahalanobisDistance()

template<typename Params_>
template<typename Derived>
Scalar Emrys::FormGaussian< Params_ >::squaredMahalanobisDistance ( Eigen::MatrixBase< Derived > const & x) const
inlinenodiscard
Returns
the squared Mahalanobis distance of x, \( d_M^2(x) = (x \boxminus \mu)^T \Sigma^{-1} (x \boxminus \mu) \), the squared norm of the whitened residual; see Gaussian::squaredMahalanobisDistance()

◆ valueDimension()

template<typename Params_>
Index Emrys::FormGaussian< Params_ >::valueDimension ( ) const
inlinenodiscard
Returns
the number of coordinates of the mean

The documentation for this class was generated from the following file: