Detailed Description

This virtual class defines the interface that any particles based PDF class must implement in order to be executed by a mrpt::bayes::CParticleFilter.

See the Particle Filter tutorial explaining how to use the particle filter-related classes.

See also: CParticleFilter, CParticleFilterData

Definition at line 31 of file CParticleFilterCapable.h.

#include <mrpt/bayes/CParticleFilterCapable.h>

Inheritance diagram for mrpt::bayes::CParticleFilterCapable:

Classes
struct	TFastDrawAuxVars
	Auxiliary vectors, see CParticleFilterCapable::prepareFastDrawSample for more information. More...

Public Types
using	TParticleProbabilityEvaluator = double()(const bayes::CParticleFilter::TParticleFilterOptions &PF_options, const CParticleFilterCapable obj, size_t index, const void action, const void observation)
	A callback function type for evaluating the probability of m_particles of being selected, used in "fastDrawSample". More...

Public Member Functions
	CParticleFilterCapable ()

virtual	~CParticleFilterCapable ()=default
	Virtual destructor. More...

void	prepareFastDrawSample (const bayes::CParticleFilter::TParticleFilterOptions &PF_options, TParticleProbabilityEvaluator partEvaluator=defaultEvaluator, const void action=nullptr, const void observation=nullptr) const
	Prepares data structures for calling fastDrawSample method next. More...

size_t	fastDrawSample (const bayes::CParticleFilter::TParticleFilterOptions &PF_options) const
	Draws a random sample from the particle filter, in such a way that each particle has a probability proportional to its weight (in the standard PF algorithm). More...

virtual double	getW (size_t i) const =0
	Access to i'th particle (logarithm) weight, where first one is index 0. More...

virtual void	setW (size_t i, double w)=0
	Modifies i'th particle (logarithm) weight, where first one is index 0. More...

virtual size_t	particlesCount () const =0
	Get the m_particles count. More...

void	prediction_and_update (const mrpt::obs::CActionCollection action, const mrpt::obs::CSensoryFrame observation, const bayes::CParticleFilter::TParticleFilterOptions &PF_options)
	Performs the prediction stage of the Particle Filter. More...

virtual void	performSubstitution (const std::vector< size_t > &indx)=0
	Performs the substitution for internal use of resample in particle filter algorithm, don't call it directly. More...

virtual double	normalizeWeights (double *out_max_log_w=nullptr)=0
	Normalize the (logarithmic) weights, such as the maximum weight is zero. More...

virtual double	ESS () const =0
	Returns the normalized ESS (Estimated Sample Size), in the range [0,1]. More...

void	performResampling (const bayes::CParticleFilter::TParticleFilterOptions &PF_options, size_t out_particle_count=0)
	Performs a resample of the m_particles, using the method selected in the constructor. More...

Static Public Member Functions
static double	defaultEvaluator ([[maybe_unused]] const bayes::CParticleFilter::TParticleFilterOptions &PF_options, [[maybe_unused]] const CParticleFilterCapable obj, size_t index, [[maybe_unused]] const void action, [[maybe_unused]] const void *observation)
	The default evaluator function, which simply returns the particle weight. More...

static void	computeResampling (CParticleFilter::TParticleResamplingAlgorithm method, const std::vector< double > &in_logWeights, std::vector< size_t > &out_indexes, size_t out_particle_count=0)
	A static method to perform the computation of the samples resulting from resampling a given set of particles, given their logarithmic weights, and a resampling method. More...

static void	log2linearWeights (const std::vector< double > &in_logWeights, std::vector< double > &out_linWeights)
	A static method to compute the linear, normalized (the sum the unity) weights from log-weights. More...

Protected Member Functions
virtual void	prediction_and_update_pfStandardProposal (const mrpt::obs::CActionCollection action, const mrpt::obs::CSensoryFrame observation, const bayes::CParticleFilter::TParticleFilterOptions &PF_options)
	Performs the particle filter prediction/update stages for the algorithm "pfStandardProposal" (if not implemented in heritated class, it will raise a 'non-implemented' exception). More...

virtual void	prediction_and_update_pfAuxiliaryPFStandard (const mrpt::obs::CActionCollection action, const mrpt::obs::CSensoryFrame observation, const bayes::CParticleFilter::TParticleFilterOptions &PF_options)
	Performs the particle filter prediction/update stages for the algorithm "pfAuxiliaryPFStandard" (if not implemented in heritated class, it will raise a 'non-implemented' exception). More...

virtual void	prediction_and_update_pfOptimalProposal (const mrpt::obs::CActionCollection action, const mrpt::obs::CSensoryFrame observation, const bayes::CParticleFilter::TParticleFilterOptions &PF_options)
	Performs the particle filter prediction/update stages for the algorithm "pfOptimalProposal" (if not implemented in heritated class, it will raise a 'non-implemented' exception). More...

virtual void	prediction_and_update_pfAuxiliaryPFOptimal (const mrpt::obs::CActionCollection action, const mrpt::obs::CSensoryFrame observation, const bayes::CParticleFilter::TParticleFilterOptions &PF_options)
	Performs the particle filter prediction/update stages for the algorithm "pfAuxiliaryPFOptimal" (if not implemented in heritated class, it will raise a 'non-implemented' exception). More...

Protected Attributes
TFastDrawAuxVars	m_fastDrawAuxiliary
	Auxiliary vectors, see CParticleFilterCapable::prepareFastDrawSample for more information. More...

Static Private Attributes
static const unsigned	PARTICLE_FILTER_CAPABLE_FAST_DRAW_BINS

Friends
class	CParticleFilter

Member Typedef Documentation

◆ TParticleProbabilityEvaluator

using mrpt::bayes::CParticleFilterCapable::TParticleProbabilityEvaluator = double (*)( const bayes::CParticleFilter::TParticleFilterOptions& PF_options, const CParticleFilterCapable* obj, size_t index, const void* action, const void* observation)

A callback function type for evaluating the probability of m_particles of being selected, used in "fastDrawSample".

The default evaluator function "defaultEvaluator" simply returns the particle weight.

Parameters

index	This is the index of the particle its probability is being computed.
action	The value of this is the parameter passed to "prepareFastDrawSample"
observation	The value of this is the parameter passed to "prepareFastDrawSample" The action and the observation are declared as "void*" for a greater flexibility.

See also: prepareFastDrawSample

Definition at line 60 of file CParticleFilterCapable.h.

Constructor & Destructor Documentation

◆ CParticleFilterCapable()

mrpt::bayes::CParticleFilterCapable::CParticleFilterCapable ( )

inline

Definition at line 39 of file CParticleFilterCapable.h.

◆ ~CParticleFilterCapable()

virtual mrpt::bayes::CParticleFilterCapable::~CParticleFilterCapable ( )

virtualdefault

Virtual destructor.

Member Function Documentation

◆ computeResampling()

void CParticleFilterCapable::computeResampling	(	CParticleFilter::TParticleResamplingAlgorithm	method,
		const std::vector< double > &	in_logWeights,
		std::vector< size_t > &	out_indexes,
		size_t	out_particle_count = `0`
	)

static

A static method to perform the computation of the samples resulting from resampling a given set of particles, given their logarithmic weights, and a resampling method.

It returns the sequence of indexes from the resampling. The number of output samples is the same than the input population. This generic method just computes these indexes, to actually perform a resampling in a particle filter object, call performResampling

Parameters

[in] out_particle_count The desired number of output particles after resampling; 0 means don't modify the current number.

See also: performResampling

Definition at line 61 of file CParticleFilterCapable.cpp.

References ASSERT_, mrpt::random::CRandomGenerator::drawUniform(), mrpt::random::CRandomGenerator::drawUniformVector(), mrpt::format(), mrpt::random::getRandomGenerator(), mrpt::math::maximum(), MRPT_END, MRPT_START, mrpt::bayes::CParticleFilter::prMultinomial, mrpt::bayes::CParticleFilter::prResidual, mrpt::bayes::CParticleFilter::prStratified, mrpt::bayes::CParticleFilter::prSystematic, R, and THROW_EXCEPTION.

Here is the call graph for this function:

◆ defaultEvaluator()

static double mrpt::bayes::CParticleFilterCapable::defaultEvaluator	(	[[maybe_unused] ] const bayes::CParticleFilter::TParticleFilterOptions &	PF_options,
		[[maybe_unused] ] const CParticleFilterCapable *	obj,
		size_t	index,
		[[maybe_unused] ] const void *	action,
		[[maybe_unused] ] const void *	observation
	)

inlinestatic

The default evaluator function, which simply returns the particle weight.

The action and the observation are declared as "void*" for a greater flexibility.

See also: prepareFastDrawSample

Definition at line 68 of file CParticleFilterCapable.h.

◆ ESS()

virtual double mrpt::bayes::CParticleFilterCapable::ESS ( ) const

pure virtual

Returns the normalized ESS (Estimated Sample Size), in the range [0,1].

Note that you do NOT need to normalize the weights before calling this.

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ fastDrawSample()

size_t CParticleFilterCapable::fastDrawSample ( const bayes::CParticleFilter::TParticleFilterOptions & PF_options ) const

Draws a random sample from the particle filter, in such a way that each particle has a probability proportional to its weight (in the standard PF algorithm).

This method can be used to generate a variable number of m_particles when resampling: to vary the number of m_particles in the filter. See prepareFastDrawSample for more information, or the Particle Filter tutorial.

NOTES:

You MUST call "prepareFastDrawSample" ONCE before calling this method. That method must be called after modifying the particle filter (executing one step, resampling, etc...)
This method returns ONE index for the selected ("drawn") particle, in the range [0,M-1]
You do not need to call "normalizeWeights" before calling this.
See also
prepareFastDrawSample

Definition at line 478 of file CParticleFilterCapable.cpp.

References mrpt::bayes::CParticleFilter::TParticleFilterOptions::adaptiveSampleSize, mrpt::random::CRandomGenerator::drawUniform(), mrpt::random::getRandomGenerator(), MRPT_END, MRPT_END_WITH_CLEAN_UP, MRPT_START, mrpt::bayes::CParticleFilter::prMultinomial, mrpt::bayes::CParticleFilter::TParticleFilterOptions::resamplingMethod, and THROW_EXCEPTION.

Referenced by mrpt::hmtslam::CLSLAM_RBPF_2DLASER::prediction_and_update_pfAuxiliaryPFOptimal().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getW()

virtual double mrpt::bayes::CParticleFilterCapable::getW ( size_t i ) const

pure virtual

Access to i'th particle (logarithm) weight, where first one is index 0.

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ log2linearWeights()

void CParticleFilterCapable::log2linearWeights	(	const std::vector< double > &	in_logWeights,
		std::vector< double > &	out_linWeights
	)

static

A static method to compute the linear, normalized (the sum the unity) weights from log-weights.

See also: performResampling

Definition at line 544 of file CParticleFilterCapable.cpp.

References ASSERT_, MRPT_END, and MRPT_START.

◆ normalizeWeights()

virtual double mrpt::bayes::CParticleFilterCapable::normalizeWeights ( double * out_max_log_w = nullptr )

pure virtual

Normalize the (logarithmic) weights, such as the maximum weight is zero.

Parameters

out_max_log_w If provided, will return with the maximum log_w before normalizing, such as new_weights = old_weights - max_log_w.

Returns: The max/min ratio of weights ("dynamic range")

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ particlesCount()

virtual size_t mrpt::bayes::CParticleFilterCapable::particlesCount ( ) const

pure virtual

Get the m_particles count.

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ performResampling()

void CParticleFilterCapable::performResampling	(	const bayes::CParticleFilter::TParticleFilterOptions &	PF_options,
		size_t	out_particle_count = `0`
	)

Performs a resample of the m_particles, using the method selected in the constructor.

After computing the surviving samples, this method internally calls "performSubstitution" to actually perform the particle replacement. This method is called automatically by CParticleFilter::execute, andshould not be invoked manually normally. To just obtaining the sequence of resampled indexes from a sequence of weights, use "resample"

Parameters

[in] out_particle_count The desired number of output particles after resampling; 0 means don't modify the current number.

See also: resample

Definition at line 29 of file CParticleFilterCapable.cpp.

References ASSERT_, MRPT_END, MRPT_START, and mrpt::bayes::CParticleFilter::TParticleFilterOptions::resamplingMethod.

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ performSubstitution()

virtual void mrpt::bayes::CParticleFilterCapable::performSubstitution ( const std::vector< size_t > & indx )

pure virtual

Performs the substitution for internal use of resample in particle filter algorithm, don't call it directly.

Parameters

indx	The indices of current m_particles to be saved as the new m_particles set.

◆ prediction_and_update()

void CParticleFilterCapable::prediction_and_update	(	const mrpt::obs::CActionCollection *	action,
		const mrpt::obs::CSensoryFrame *	observation,
		const bayes::CParticleFilter::TParticleFilterOptions &	PF_options
	)

Performs the prediction stage of the Particle Filter.

This method simply selects the appropiate protected method according to the particle filter algorithm to run.

See also: prediction_and_update_pfStandardProposal,prediction_and_update_pfAuxiliaryPFStandard,prediction_and_update_pfOptimalProposal,prediction_and_update_pfAuxiliaryPFOptimal

Definition at line 273 of file CParticleFilterCapable.cpp.

References mrpt::bayes::CParticleFilter::TParticleFilterOptions::PF_algorithm, mrpt::bayes::CParticleFilter::pfAuxiliaryPFOptimal, mrpt::bayes::CParticleFilter::pfAuxiliaryPFStandard, mrpt::bayes::CParticleFilter::pfOptimalProposal, mrpt::bayes::CParticleFilter::pfStandardProposal, and THROW_EXCEPTION.

Referenced by mrpt::bayes::CParticleFilter::executeOn().

Here is the caller graph for this function:

◆ prediction_and_update_pfAuxiliaryPFOptimal()

void CParticleFilterCapable::prediction_and_update_pfAuxiliaryPFOptimal	(	const mrpt::obs::CActionCollection *	action,
		const mrpt::obs::CSensoryFrame *	observation,
		const bayes::CParticleFilter::TParticleFilterOptions &	PF_options
	)

protectedvirtual

Performs the particle filter prediction/update stages for the algorithm "pfAuxiliaryPFOptimal" (if not implemented in heritated class, it will raise a 'non-implemented' exception).

See also: prediction_and_update

Reimplemented in mrpt::hmtslam::CLocalMetricHypothesis, mrpt::slam::CMonteCarloLocalization2D, mrpt::slam::CMonteCarloLocalization3D, and mrpt::maps::CMultiMetricMapPDF.

Definition at line 345 of file CParticleFilterCapable.cpp.

References THROW_EXCEPTION.

◆ prediction_and_update_pfAuxiliaryPFStandard()

void CParticleFilterCapable::prediction_and_update_pfAuxiliaryPFStandard	(	const mrpt::obs::CActionCollection *	action,
		const mrpt::obs::CSensoryFrame *	observation,
		const bayes::CParticleFilter::TParticleFilterOptions &	PF_options
	)

protectedvirtual

Performs the particle filter prediction/update stages for the algorithm "pfAuxiliaryPFStandard" (if not implemented in heritated class, it will raise a 'non-implemented' exception).

See also: prediction_and_update

Reimplemented in mrpt::slam::CMonteCarloLocalization2D, mrpt::maps::CMultiMetricMapPDF, and mrpt::slam::CMonteCarloLocalization3D.

Definition at line 320 of file CParticleFilterCapable.cpp.

References THROW_EXCEPTION.

◆ prediction_and_update_pfOptimalProposal()

void CParticleFilterCapable::prediction_and_update_pfOptimalProposal	(	const mrpt::obs::CActionCollection *	action,
		const mrpt::obs::CSensoryFrame *	observation,
		const bayes::CParticleFilter::TParticleFilterOptions &	PF_options
	)

protectedvirtual

Performs the particle filter prediction/update stages for the algorithm "pfOptimalProposal" (if not implemented in heritated class, it will raise a 'non-implemented' exception).

See also: prediction_and_update

Reimplemented in mrpt::hmtslam::CLocalMetricHypothesis, and mrpt::maps::CMultiMetricMapPDF.

Definition at line 333 of file CParticleFilterCapable.cpp.

References THROW_EXCEPTION.

◆ prediction_and_update_pfStandardProposal()

void CParticleFilterCapable::prediction_and_update_pfStandardProposal	(	const mrpt::obs::CActionCollection *	action,
		const mrpt::obs::CSensoryFrame *	observation,
		const bayes::CParticleFilter::TParticleFilterOptions &	PF_options
	)

protectedvirtual

Performs the particle filter prediction/update stages for the algorithm "pfStandardProposal" (if not implemented in heritated class, it will raise a 'non-implemented' exception).

See also: prediction_and_update

Reimplemented in CRangeBearingParticleFilter, mrpt::slam::CMonteCarloLocalization2D, mrpt::maps::CMultiMetricMapPDF, and mrpt::slam::CMonteCarloLocalization3D.

Definition at line 307 of file CParticleFilterCapable.cpp.

References THROW_EXCEPTION.

◆ prepareFastDrawSample()

void CParticleFilterCapable::prepareFastDrawSample	(	const bayes::CParticleFilter::TParticleFilterOptions &	PF_options,
		TParticleProbabilityEvaluator	partEvaluator = `defaultEvaluator`,
		const void *	action = `nullptr`,
		const void *	observation = `nullptr`
	)		const

Prepares data structures for calling fastDrawSample method next.

This method must be called once before using "fastDrawSample" (calling this more than once has no effect, but it takes time for nothing!) The behavior depends on the configuration of the PF (see CParticleFilter::TParticleFilterOptions):

DYNAMIC SAMPLE SIZE=NO: In this case this method fills out an internal array (m_fastDrawAuxiliary.alreadyDrawnIndexes) with the random indexes generated according to the selected resample scheme in TParticleFilterOptions. Those indexes are read sequentially by subsequent calls to fastDrawSample.
DYNAMIC SAMPLE SIZE=YES: Then:
- If TParticleFilterOptions.resamplingMethod = prMultinomial, the internal buffers will be filled out (m_fastDrawAuxiliary.CDF, CDF_indexes & PDF) and then fastDrawSample can be called an arbitrary number of times to generate random indexes.
- For the rest of resampling algorithms, an exception will be raised since they are not appropriate for a dynamic (unknown in advance) number of particles.

The function pointed by "partEvaluator" should take into account the particle filter algorithm selected in "m_PFAlgorithm". If called without arguments (defaultEvaluator), the default behavior is to draw samples with a probability proportional to their current weights. The action and the observation are declared as "void*" for a greater flexibility. For a more detailed information see the Particle Filter tutorial. Custom supplied "partEvaluator" functions must take into account the previous particle weight, i.e. multiplying the current observation likelihood by the weights.

See also: fastDrawSample

Definition at line 359 of file CParticleFilterCapable.cpp.

References mrpt::bayes::CParticleFilter::TParticleFilterOptions::adaptiveSampleSize, ASSERT_, mrpt::math::maximum(), MRPT_CHECK_NORMAL_NUMBER, MRPT_END, MRPT_END_WITH_CLEAN_UP, MRPT_START, mrpt::bayes::CParticleFilter::prMultinomial, mrpt::bayes::CParticleFilter::TParticleFilterOptions::resamplingMethod, and THROW_EXCEPTION.

Referenced by mrpt::hmtslam::CLSLAM_RBPF_2DLASER::prediction_and_update_pfAuxiliaryPFOptimal().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setW()

virtual void mrpt::bayes::CParticleFilterCapable::setW	(	size_t	i,
		double	w
	)

pure virtual

Modifies i'th particle (logarithm) weight, where first one is index 0.

Friends And Related Function Documentation

◆ CParticleFilter

friend class CParticleFilter

friend

Definition at line 33 of file CParticleFilterCapable.h.

Member Data Documentation

◆ m_fastDrawAuxiliary

TFastDrawAuxVars mrpt::bayes::CParticleFilterCapable::m_fastDrawAuxiliary

mutableprotected

Auxiliary vectors, see CParticleFilterCapable::prepareFastDrawSample for more information.

Definition at line 282 of file CParticleFilterCapable.h.

◆ PARTICLE_FILTER_CAPABLE_FAST_DRAW_BINS

const unsigned CParticleFilterCapable::PARTICLE_FILTER_CAPABLE_FAST_DRAW_BINS

staticprivate

Initial value:

=

20

Definition at line 36 of file CParticleFilterCapable.h.

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Private Attributes

Friends

Member Typedef Documentation

◆ TParticleProbabilityEvaluator

Constructor & Destructor Documentation

◆ CParticleFilterCapable()

◆ ~CParticleFilterCapable()

Member Function Documentation

◆ computeResampling()

◆ defaultEvaluator()

◆ ESS()

◆ fastDrawSample()

◆ getW()

◆ log2linearWeights()

◆ normalizeWeights()

◆ particlesCount()

◆ performResampling()

◆ performSubstitution()

◆ prediction_and_update()

◆ prediction_and_update_pfAuxiliaryPFOptimal()

◆ prediction_and_update_pfAuxiliaryPFStandard()

◆ prediction_and_update_pfOptimalProposal()

◆ prediction_and_update_pfStandardProposal()

◆ prepareFastDrawSample()

◆ setW()

Friends And Related Function Documentation

◆ CParticleFilter

Member Data Documentation

◆ m_fastDrawAuxiliary

◆ PARTICLE_FILTER_CAPABLE_FAST_DRAW_BINS