Beliefs
Types
ParticleFilters.jl provides two types of particle beliefs. ParticleCollection is little more than a vector of unweighted particles. WeightedParticleBelief allows for different weights for each of the particles.
Both are subtypes of AbstractParticleBelief and implement the same particle belief interface. For probability mass calculations (the pdf function), a dictionary containing the normalized sum of weights for all identical particles is created on the first call and cached for efficient future querying.
You should not access the fields of ParticleCollection or WeightedParticleBelief directly. Use the provided interface instead to ensure that internal data structures are maintained correctly.
ParticleFilters.ParticleCollection — TypeParticleCollection{S}Unweighted particle belief consisting of equally important particles of type S.
ParticleFilters.WeightedParticleBelief — TypeWeightedParticleBelief{S}Weighted particle belief consisting of particles of type S and their associated weights.
An alias table is used for efficient sampling.
Interface
Standard POMDPs.jl Distribution Interface
The following functions from the POMDPs.jl distributions interface (a subset of the Distributions.jl interface) provide basic ways of interacting with particle beliefs as distributions (click on each for documentation):
Particle Interface
These functions provide read only access to the particles, weights, and other aspects of the beliefs (click on each for docstrings):
n_particlesparticlesweightsweighted_particlesweight_sumweightparticleParticleFilters.probdicteffective_sample_size
To change the particles or weights in a belief, the following functions are provided:
Interface Docstrings
Base.rand — Functionrand(rng::AbstractRNG, d::Any)Return a random element from distribution or space d.
If d is a state or transition distribution, the sample will be a state; if d is an action distribution, the sample will be an action or if d is an observation distribution, the sample will be an observation.
Distributions.pdf — Functionpdf(d::Any, x::Any)Evaluate the probability density of distribution d at sample x.
Distributions.support — Functionsupport(d::Any)Return an iterable object containing the possible values that can be sampled from distribution d. Values with zero probability may be skipped.
StatsBase.mode — Functionmode(d::Any)Return the most likely value in a distribution d.
Statistics.mean — Functionmean(d::Any)Return the mean of a distribution d.
ParticleFilters.n_particles — Functionn_particles(b::AbstractParticleBelief)Return the number of particles.
ParticleFilters.particles — Functionparticles(b::AbstractParticleBelief)Return an iterator over the particles.
ParticleFilters.weights — Functionweights(b::AbstractParticleBelief)Return an iterator over the weights.
ParticleFilters.weighted_particles — Functionweighted_particles(b::AbstractParticleBelief)Return an iterator over particle-weight pairs.
ParticleFilters.weight_sum — Functionweight_sum(b::AbstractParticleBelief)Return the sum of the weights of the particle collection.
ParticleFilters.weight — Functionweight(b::AbstractParticleBelief, i)Return the weight for particle i.
ParticleFilters.particle — Functionparticle(b::AbstractParticleBelief, i)Return particle i.
ParticleFilters.probdict — Functionprobdict(b::AbstractParticleBelief)Return a dictionary mapping states to probabilities.
The probability is the normalized sum of the weights for all matching particles.
For ParticleCollection and WeightedParticleBelief, the result is cached for efficiency so the calculation is only performed the first time this is called. There is a default implementation for all AbstractParticleBeliefs, but it is inefficient (it creates a new dictionary every time). New AbstractParticleBelief implementations should provide an efficient implementation.
ParticleFilters.effective_sample_size — Functioneffective_sample_size(b::AbstractParticleBelief)Calculate the effective sample size of a particle belief.
The effective sample size is $1/\sum_i \hat{w}_i^2$ where $\hat{w}_i = w_i / \sum_i w_i$.
ParticleFilters.set_particle! — Functionset_particle!(b::AbstractParticleBelief, i, s)Change the particle at index i without changing the weight.
This may not work for beliefs with immutable particle storage.
Example
set_particle!(b, 3, s)ParticleFilters.set_weight! — Functionset_weight!(b::AbstractParticleBelief, i, w)Change the weight at index i without changing the particle.
ParticleFilters.set_pair! — Functionset_pair!(b::AbstractParticleBelief{S}, i, sw::Pair{S,Float64})Change both the particle and weight at index i. This will also adjust the weight sum and probabilities appropriately.
Example
set_pair!(b, 3, s=>0.5)ParticleFilters.push_pair! — Functionpush_pair!(b::AbstractParticleBelief{S}, sw::Pair{S,Float64})Push a new particle and weight pair onto the end of the belief. This will also adjust the weight sum and probabilities appropriately.
Example
push_pair!(b, s=>0.5)