Function beluga::kld_condition

Function Documentation

inline auto beluga::kld_condition(std::size_t min, double epsilon, double z = beluga::detail::kDefaultKldZ)

Returns a callable object that verifies if the KLD condition is being satisfied.

The callable object will compute the minimum number of samples based on a Kullback-Leibler distance epsilon between the maximum likelihood estimate and the true distribution.

Z is the upper standard normal quantile for P, where P is the probability that the error in the estimated distribution will be less than epsilon.

Here are some examples:

P

Z

0.900

1.28155156327703

0.950

1.64485362793663

0.990

2.32634787735669

0.999

3.09023224677087

If the computed value is less than what the min argument specifies, then min will be returned.

See KLD-Sampling: Adaptive Particle Filters fox2001adaptivekldsampling.

Parameters:

  • min – Minimum number of particles that the callable object will return.

  • epsilon – Maximum distance epsilon between the maximum likelihood estimate and the true distrubution.

  • z – Upper standard normal quantile for the probability that the error in the estimated distribution is less than epsilon.

Returns:

A callable object with prototype (std::size_t hash) -> bool. hash

is the spatial hash of the particle being added.

The returned callable object is stateful, tracking the total number of particles and the particle clusters based on the spatial hash.

The return value of the callable will be false when the number of particles is more than the minimum and the KLD condition is satisfied, if not it will be true.

i.e. A return value of true means that you need to keep sampling to satisfy the condition.