The parameters of a hybrid state: a discrete mode, and a component conditioned on each mode. More...

#include <EmrysFilter/Distributions/Hybrid.h>

Public Types
using	ComponentType = Params<Component_>
	the component given one mode
using	Scalar = typename ComponentType::Scalar
	the scalar type
using	SpaceType = typename ComponentType::SpaceType
	the continuous state space
using	ModeSpaceType = ModeSpace_
	the discrete mode space
using	ModesType = CategoricalParams<ModeSpace_, Scalar>
	the weights of the modes
using	MomentsType = typename ComponentType::MomentsType
	a mean and covariance together
using	allocator_type = Allocator_
	the allocator the components come from
using	DensityType = Hybrid<Component_, ModeSpace_, Allocator_>
	the view toDensity() returns
using	ConditionalsType = internal::Buffer<ComponentType, Allocator_>
	The components, one per mode in flat-index order.

Public Member Functions
	HybridParams (ModesType modes, ComponentType const &conditional, Allocator_ const &allocator={})
	Mode weights modes, with conditional as the component in every mode.
	HybridParams (ModesType modes, ConditionalsType conditionals)
	Mode weights modes, and conditionals, one component per mode in flat-index order.
template<typename Conditionals>
	HybridParams (ModesType modes, Conditionals const &conditionals, Allocator_ const &allocator)
	As above, with the components copied into storage from allocator.
	HybridParams (HybridParams const &other, Allocator_ const &allocator)
	Copies the modes and components into storage from allocator.
	HybridParams (HybridParams &&other, Allocator_ const &allocator)
	Moves the modes and components into storage from allocator.
	HybridParams (HybridParams const &)=default
	copies the modes and components
	HybridParams (HybridParams &&) noexcept=default
	moves the modes and components
HybridParams &	operator= (HybridParams const &)=default
	Copies the modes and components, reusing the storage held.
HybridParams &	operator= (HybridParams &&) noexcept=default
	Moves the modes and components.
allocator_type	get_allocator () const
SpaceType const &	space () const
ModeSpace_ const &	modeSpace () const
Eigen::Index	size () const
Eigen::Index	valueDimension () const
Eigen::Index	differenceDimension () const
ModesType const &	modes () const
void	setModes (ModesType modes)
	Replaces the mode weights.
ComponentType const &	conditional (Eigen::Index mode) const &
void	conditional (Eigen::Index mode) const &&=delete
	A component of a temporary would outlive it; copy it from a named hybrid instead.
void	setConditional (Eigen::Index mode, ComponentType const &component)
	Replaces the component given the mode with flat index mode with component, which must be in the hybrid's space, copying into the storage the component holds.
void	setConditional (Eigen::Index mode, ComponentType &&component)
	As above, moving component in.
template<typename F> requires std::invocable<F &, ComponentType &>
decltype(auto)	updateConditional (Eigen::Index mode, F &&f)
template<typename... Values, typename... Paths, std::size_t... N> requires (sizeof...(Values) + sizeof...(Paths) > 0)
ComponentType const &	conditional (AxisIndex< Paths, N > const &... indices) const &
template<typename... Values, typename... Paths, std::size_t... N> requires (sizeof...(Values) + sizeof...(Paths) > 0)
void	conditional (AxisIndex< Paths, N > const &...) const &&=delete
	A component of a temporary would outlive it.
void	swapConditionals (ConditionalsType &conditionals)
	Exchanges the components with conditionals, one per mode on the same space, which must come from an equal allocator: how a filter replaces them without copying.
template<typename Path>
auto	marginal () const &
template<typename Path>
void	marginal () const &&=delete
	A marginal of a temporary would outlive it.
template<typename Path>
auto	marginal (Eigen::Index element) const &
	marginal() of one repetition of a repeated block; see GaussianParams::marginal(element).
template<typename Path>
void	marginal (Eigen::Index element) const &&=delete
	A marginal of a temporary would outlive it.
MixtureParams< Component_, Allocator_ >	toMixture () const
std::expected< void, NumericError >	factorize () const
	Checks the mode weights and factorizes every component that has changed, so that the state's log-density can be read (see ComponentTraits).
template<typename R>
std::expected< void, NumericError >	factorize (R const &repair)
	factorize(), repairing each covariance that is not positive definite by repair (see GaussianParams::factorize(R const &)).
std::expected< DensityType, NumericError >	toDensity () const &
	Checks the mode weights and factorizes every component that has changed (factorize()).
void	toDensity () const &&=delete
	A density of a temporary would outlive it.
template<typename R>
std::expected< DensityType, NumericError >	toDensity (R const &repair) &
	toDensity(), repairing covariances that are not positive definite by repair (see factorize(R const &)): x.toDensity(roots::ridge()).
template<typename R>
void	toDensity (R const &) &&=delete
	A density of a temporary would outlive it.

Static Public Attributes
static constexpr int	ValueDimensionAtCompileTime = ComponentType::ValueDimensionAtCompileTime
	the length of a value, or Eigen::Dynamic
static constexpr int	MaxValueDimensionAtCompileTime = ComponentType::MaxValueDimensionAtCompileTime
	a bound on the length of a value, or Eigen::Dynamic
static constexpr int	DifferenceDimensionAtCompileTime = ComponentType::DifferenceDimensionAtCompileTime
	the length of a difference and the rows of a covariance, or Eigen::Dynamic
static constexpr int	MaxDifferenceDimensionAtCompileTime = ComponentType::MaxDifferenceDimensionAtCompileTime
	a bound on the length of a difference, or Eigen::Dynamic
static constexpr bool	IsParams = true
	its own parameters, which views check

Detailed Description

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>
class Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >

The parameters of a hybrid state: a discrete mode, and a component conditioned on each mode.

The density, evaluated by its Hybrid from toDensity(), is \( p(x, m) = P(m) \, p_m(x) \), with ModeSpace_ a discrete space (see Discrete spaces) and one component (see Component) for each of its values: a Gaussian, which makes the hybrid a HybridGaussian, \( p_m = \mathcal{N}(\mu_m, \Sigma_m) \), or any other component. This is the state of an ImmFilter, where the modes are maneuver regimes or sensor states; a grid of Kalman filters, whose cells can't be revived as modes can, is a GridGaussianParams (decisions.md [rao-blackwellized-core]). Unlike a Mixture, every component is labeled by its mode, and there is exactly one per mode.

A hybrid is itself a component (decisions.md [component-first]): its log-density is the log-sum-exp over its modes, and several hybrids on one mode space collapse into one whose mode probabilities are their weighted sums and whose conditional for mode \( m \) is the collapse of theirs with weights \( w_c P_c(m) \), which keeps each mode's mean and covariance. So a Mixture of hybrids is a mixture of IMM states [filters-and-recursions].

The components come from the allocator (see Allocation). The modes are a CategoricalParams, one weight per value of the mode space, which need not sum to one, as a mixture's weights need not: the state is \( p(x, m) \propto w_m \, p_m(x) \), and toDensity() checks the weights and factorizes the components before the density is read. The moments and the collapses read the components, so they are the density's: they mean something only once every component is a distribution (decisions.md [params-and-density]).

auto x = HybridGaussianParams<State, Mode>{CategoricalParams<Mode>{}, initial};  // every mode starts at initial
x.modes().toDensity()->probability<Turn>();   // probability of turning, any sensor state
x.conditional<Turn, Inlier>();          // the GaussianParams given that mode
x.marginal<Position>();                  // each mode's log-weight and position, read in place
auto const density = x.toDensity();
density->collapsed();                    // one GaussianParams, moment-matched over the modes
density->collapse<Maneuver>();           // HybridGaussianParams<State, Maneuver>, grouped by maneuver

Template Parameters

Component_	the component given a mode (see Component), which sets the continuous state space and the scalar
ModeSpace_	the discrete mode space (see Discrete spaces)
Allocator_	allocator for the components (see Allocation)

See also: class Hybrid, HybridGaussianParams, class MixtureParams

Member Function Documentation

◆ conditional() [1/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

template<typename... Values, typename... Paths, std::size_t... N>
requires (sizeof...(Values) + sizeof...(Paths) > 0)

ComponentType const & Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::conditional ( AxisIndex< Paths, N > const &... indices ) const &

inlinenodiscard

Returns: the component given the mode with the named values Values and the indices indices of axes without names, one per axis (see valueOf() and at()): conditional<Turn>(at<Cell>(3))

◆ conditional() [2/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

ComponentType const & Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::conditional ( Eigen::Index mode ) const &

inlinenodiscard

Returns: the component given the mode with flat index mode, \( p(x \mid m) \)

◆ differenceDimension()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

Eigen::Index Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::differenceDimension ( ) const

inlinenodiscard

Returns: the number of rows and columns of every component's covariance (see Spaces)

◆ factorize() [1/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

std::expected< void, NumericError > Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::factorize ( ) const

inlinenodiscard

Checks the mode weights and factorizes every component that has changed, so that the state's log-density can be read (see ComponentTraits).

It is const because it writes only the components' cached factorizations, so it is not safe on one object from two threads at once until it has succeeded; after that it only reads (see Distributions).

Returns: nothing on success, the WeightError of mode weights that fail to define a distribution, or the GaussianError of the first component that failed

◆ factorize() [2/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

template<typename R>

std::expected< void, NumericError > Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::factorize ( R const & repair )

inlinenodiscard

factorize(), repairing each covariance that is not positive definite by repair (see GaussianParams::factorize(R const &)).

Every repair is tried before any is kept, as MixtureParams::factorize(R const &) does, so a component that can't be repaired leaves the state as it was.

Returns: nothing on success, the WeightError of mode weights that fail to define a distribution, or the GaussianError of the first component that could not be repaired

◆ get_allocator()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

allocator_type Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::get_allocator ( ) const

inlinenodiscard

Returns: the allocator the components come from

◆ marginal()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

template<typename Path>

auto Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::marginal ( ) const &

inlinenodiscard

Returns: a read-only view of the subspace named by the tag path Path (see idx()) of the continuous state, whose space is that subspace with its parameters: a range over the modes that gives each one's log-weight and its component's marginal in turn, copying nothing (decisions.md [element-marginals]). It checks this object's shape; copy() gives a Hybrid of the marginals.

See also: class MixtureMarginal

◆ modes()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

ModesType const & Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::modes ( ) const

inlinenodiscard

Returns: the weights of the modes, proportional to \( P(m) \)

◆ modeSpace()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

ModeSpace_ const & Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::modeSpace ( ) const

inlinenodiscard

Returns: the discrete mode space

◆ size()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

Eigen::Index Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::size ( ) const

inlinenodiscard

Returns: the number of modes

◆ space()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

SpaceType const & Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::space ( ) const

inlinenodiscard

Returns: the continuous state space

◆ toDensity() [1/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

std::expected< DensityType, NumericError > Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::toDensity ( ) const &

inlinenodiscard

Checks the mode weights and factorizes every component that has changed (factorize()).

Returns: a Hybrid that checks this object, or the NumericError from factorize()

◆ toDensity() [2/2]

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

template<typename R>

std::expected< DensityType, NumericError > Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::toDensity ( R const & repair ) &

inlinenodiscard

toDensity(), repairing covariances that are not positive definite by repair (see factorize(R const &)): x.toDensity(roots::ridge()).

Returns: a Hybrid that checks this object, or the NumericError from factorize(R const &)

◆ toMixture()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

MixtureParams< Component_, Allocator_ > Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::toMixture ( ) const

inlinenodiscard

Returns: the state as an unlabeled Mixture, one component per mode, weighted by the mode weights, for its toDensity(), marginals, and sampling. It has this state's allocator.

◆ updateConditional()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

template<typename F>
requires std::invocable<F &, ComponentType &>

decltype(auto) Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::updateConditional	(	Eigen::Index	mode,
		F &&	f )

inline

Returns: f called with the component given the mode with flat index mode, to change it in place, as a filter's step does; f must keep its space, which is asserted after

◆ valueDimension()

template<internal::ComponentOrInfoForm Component_, DiscreteSpace ModeSpace_, typename Allocator_ = DefaultAllocator>

Eigen::Index Emrys::HybridParams< Component_, ModeSpace_, Allocator_ >::valueDimension ( ) const

inlinenodiscard

Returns: the number of coordinates of every component's mean (see Spaces)

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

EmrysFilter/Distributions/Hybrid.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ conditional() [1/2]

◆ conditional() [2/2]

◆ differenceDimension()

◆ factorize() [1/2]

◆ factorize() [2/2]

◆ get_allocator()

◆ marginal()

◆ modes()

◆ modeSpace()

◆ size()

◆ space()

◆ toDensity() [1/2]

◆ toDensity() [2/2]

◆ toMixture()

◆ updateConditional()

◆ valueDimension()