Roots.h File Reference

Square roots of a covariance (decisions.md [sigma-point-axes]): the Axes and Repair concepts that a root of the user's own meets [user-extension-points], the library's axes roots::cholesky(), roots::pivoted(), roots::principal(), roots::symmetric(), and roots::along(), the repair roots::ridge(), the flat list of fallbacks that axes which can fail take, and roots::squareRoot() and roots::squareRootWithReport(), which take a root by them. More...

#include <concepts>
#include <cstddef>
#include <expected>
#include <optional>
#include <tuple>
#include <type_traits>
#include <utility>
#include <variant>
#include <Eigen/Cholesky>
#include <Eigen/Eigenvalues>
#include <Eigen/SVD>
#include <EmrysFilter/Core/Macros.h>
#include <EmrysFilter/Core/Math.h>
#include <EmrysFilter/Core/NumericError.h>
#include <EmrysFilter/Core/Triangularization.h>

Go to the source code of this file.

Classes
struct	Emrys::roots::NoReport
	The report of axes or a repair with nothing to say, as Cholesky's: it either took the root or failed. More...
struct	Emrys::roots::ClampReport
	The report of Pivoted, Principal, and Symmetric: how many pivots or eigenvalues were below zero and taken as zero, which only rounding should give a covariance. More...
struct	Emrys::roots::RidgeReport< Scalar >
	The report of a Ridge: the ridge \( \delta \) it added to the diagonal. More...
struct	Emrys::roots::Cholesky
	Cholesky axes: the lower Cholesky factor \( L \), \( L L^T = P \), by Eigen's LLT, which fails on a covariance that is not positive definite. More...
struct	Emrys::roots::Pivoted
	Pivoted axes: \( \Pi^T L D^{1/2} \) from Eigen's pivoted LDL decomposition \( P = \Pi^T L D L^T \Pi \), with a negative pivot, which rounding can give a singular matrix, taken as zero. More...
struct	Emrys::roots::Principal
	Principal axes: \( U \Lambda^{1/2} \), the eigenvectors of \( P = U \Lambda U^T \) scaled by the roots of their eigenvalues, largest first, with a negative eigenvalue taken as zero, so that it never fails. More...
struct	Emrys::roots::Symmetric
	Symmetric axes: the principal square root \( P^{1/2} = U \Lambda^{1/2} U^T \), the one symmetric positive semidefinite root, with a negative eigenvalue taken as zero, so that it never fails. More...
struct	Emrys::roots::Along< Vector >
	Axes along a direction: a root whose first column is parallel to \( d \), so that a sigma-point rule puts its first pair of points on the line through the mean along \( d \), as a split or a probe of the nonlinearity along \( d \) needs (decisions.md [splitting-hooks]). More...
struct	Emrys::roots::Ridge< Relative, Absolute >
	The ridge repair: the Gershgorin ridge of decisions.md [covariance-repair], added to the diagonal of a covariance whose root failed so that the root can be retried. More...
struct	Emrys::roots::WithFallbacks< Head, Fallbacks >
	Axes that can fail, followed by their fallbacks, tried in order (decisions.md [sigma-point-axes]): a repair, which retries Head on the covariance it repairs, or other axes, which take the root themselves. More...
struct	Emrys::roots::RootWithReport< Matrix, Report >
	A root and the report of the axes that took it, from squareRootWithReport(). More...
struct	Emrys::roots::RootFailure< Report >
	Why squareRootWithReport() failed, and what each entry tried did. More...

Namespaces
namespace	Emrys::roots
	The axes and repairs, each made by its factory (decisions.md [policy-factories]), and the roots taken by them: cholesky(), pivoted(), principal(), symmetric(), along(), ridge(), squareRoot(), and squareRootWithReport().

Concepts
concept	Emrys::Axes
	Axes: a way of taking a root \( S \) of a covariance \( P \), \( S S^T = P \), whose columns carry a sigma-point rule's unit points into the input (decisions.md [sigma-point-axes]).
concept	Emrys::Repair
	A repair: what turns a covariance whose root failed into one to retry (decisions.md [sigma-point-axes]).

Typedefs
template<typename Derived>
using	Emrys::roots::RootMatrix = internal::SquareMatrixOf<Derived>
	The type of a root of the covariance or factor Derived: square, with a row and a column per row of it and its bounds, so that a bounded matrix allocates nothing [allocation].
using	Emrys::roots::DefaultAxes = WithFallbacks<Cholesky, Pivoted>
	The axes every root the library takes uses unless told otherwise, cholesky(pivoted()): the Cholesky factor of a positive definite covariance, and the pivoted root of any other, so it never fails and never repairs (decisions.md [sigma-point-axes]).

Functions
template<typename... Fallbacks>
constexpr auto	Emrys::roots::cholesky (Fallbacks... fallbacks)
template<typename... Fallbacks>
constexpr auto	Emrys::roots::pivoted (Fallbacks... fallbacks)
template<typename... Fallbacks>
constexpr auto	Emrys::roots::principal (Fallbacks... fallbacks)
template<typename... Fallbacks>
constexpr auto	Emrys::roots::symmetric (Fallbacks... fallbacks)
template<typename Derived, typename... Fallbacks>
auto	Emrys::roots::along (Eigen::MatrixBase< Derived > const &direction, Fallbacks... fallbacks)
template<double Relative = 1.0, double Absolute = 0.0>
constexpr Ridge< Relative, Absolute >	Emrys::roots::ridge ()
template<typename Head, typename First, typename... Rest>
constexpr WithFallbacks< Head, First, Rest... >	Emrys::roots::withFallbacks (Head axes, First first, Rest... rest)
template<Axes A, typename Derived>
auto	Emrys::roots::squareRoot (A const &axes, Eigen::MatrixBase< Derived > const &cov)
template<Axes A, typename Derived>
auto	Emrys::roots::squareRootWithReport (A const &axes, Eigen::MatrixBase< Derived > const &cov)

Detailed Description

Square roots of a covariance (decisions.md [sigma-point-axes]): the Axes and Repair concepts that a root of the user's own meets [user-extension-points], the library's axes roots::cholesky(), roots::pivoted(), roots::principal(), roots::symmetric(), and roots::along(), the repair roots::ridge(), the flat list of fallbacks that axes which can fail take, and roots::squareRoot() and roots::squareRootWithReport(), which take a root by them.

Also GaussianError, the reasons a root or a density can fail. Read Gaussian.h next.