|
|
| ParticleSet (Allocator_ const &allocator) |
| | Constructs an empty set that allocates through allocator.
|
| | ParticleSet (Capacity capacity, Allocator_ const &allocator={}) |
| | Constructs an empty set in a FixedSizeSpace that reserves room for capacity particles.
|
|
| ParticleSet (Index valueDimension, Allocator_ const &allocator={}) |
| | Constructs an empty set whose particles will have valueDimension coordinates.
|
template<typename StatesDerived>
requires internal::SizedByLength<Space_> |
| | ParticleSet (Eigen::MatrixBase< StatesDerived > const &states, Allocator_ const &allocator={}) |
| | Constructs a set from the columns of states, with equal weights summing to one.
|
template<typename StatesDerived, typename WeightsDerived>
requires internal::SizedByLength<Space_> |
| | ParticleSet (Eigen::MatrixBase< StatesDerived > const &states, Eigen::DenseBase< WeightsDerived > const &logWeights, Allocator_ const &allocator={}) |
| | Constructs a set from the columns of states with the log-weights logWeights.
|
|
| ParticleSet (Space_ space, Allocator_ const &allocator={}) |
| | Constructs an empty set in space.
|
|
| ParticleSet (Space_ space, Capacity capacity, Allocator_ const &allocator={}) |
| | Constructs an empty set in space that reserves room for capacity particles.
|
| | ParticleSet (Space_ space, Index valueDimension, Allocator_ const &allocator={}) |
| | Constructs an empty set in space whose particles will have valueDimension coordinates.
|
|
template<typename StatesDerived> |
| | ParticleSet (Space_ space, Eigen::MatrixBase< StatesDerived > const &states, Allocator_ const &allocator={}) |
| | Constructs a set in space from the columns of states, with equal weights summing to one.
|
|
template<typename StatesDerived, typename WeightsDerived> |
| | ParticleSet (Space_ space, Eigen::MatrixBase< StatesDerived > const &states, Eigen::DenseBase< WeightsDerived > const &logWeights, Allocator_ const &allocator={}) |
| | Constructs a set in space from the columns of states with the log-weights logWeights.
|
| | ParticleSet (ParticleSet const &other) |
| | Copies the particles and any stored bandwidth into storage from other's allocator, with its capacity (see Allocation).
|
|
| ParticleSet (ParticleSet const &other, Allocator_ const &allocator) |
| | Copies the particles and any stored bandwidth into storage from allocator, with other's capacity and no resample record.
|
|
| ParticleSet (ParticleSet &&other) noexcept |
| | Takes other's particles and storage; a view of other may not be read afterward.
|
|
| ParticleSet (ParticleSet &&other, Allocator_ const &allocator) |
| | Moves other's particles into storage from allocator, taking its storage when the allocators are equal.
|
|
ParticleSet & | operator= (ParticleSet const &other) |
| | Copies other's particles, weights, space, and bandwidth into this set's storage, which keeps its allocator and capacity, and clears its resample record, as a copy has none.
|
| ParticleSet & | operator= (ParticleSet &&other) noexcept |
| | Takes other's storage when the allocators are equal or propagate, otherwise copies into this set's storage, which keeps its capacity; either way it takes other's resample record.
|
| allocator_type | get_allocator () const |
| Index | size () const |
| bool | empty () const |
| std::optional< Index > | capacity () const |
| void | setCapacity (Index capacity) |
| | Reserves room for capacity particles, and for the scratch resample() uses, and makes holding more a precondition violation.
|
| Index | valueDimension () const |
| Index | differenceDimension () const |
| Space_ const & | space () const |
| StatesType | states () const |
| LogWeightsType | logWeights () const |
| ConstStateType | state (Index i) const |
| Scalar | logWeight (Index i) const |
| std::optional< MatrixType > const & | bandwidth () const |
| std::expected< MatrixType, WeightError > | kdeBandwidth () const |
|
template<ExecutionPolicy P> |
| std::expected< MatrixType, WeightError > | kdeBandwidth (P &&policy) const |
| | kdeBandwidth() under policy: Silverman's rule's total weight, effective sample size, and covariance are reductions over the particles (see Execution policies).
|
| template<MatrixExpression Bandwidth> |
| void | setBandwidth (Bandwidth &&bandwidth) |
| | Stores bandwidth as the kernel covariance.
|
|
void | clearBandwidth () |
| | Forgets the stored bandwidth, so kdeBandwidth() returns to Silverman's rule.
|
| void | resizeParticles (Index n) |
| | Resizes every particle state to n coordinates and clears the bandwidth.
|
| template<typename Path, typename Derived> |
| void | insert (Index element, Eigen::MatrixBase< Derived > const &states) |
| | Inserts the state entries states, one column per particle, into the resizable block named by the tag path Path, before its element element.
|
| template<typename Path> |
| void | erase (Index element, Index count=1) |
| | Removes count elements of the resizable block named by the tag path Path from every particle, starting at its element element.
|
|
void | clear () |
| | Removes every particle; the space, bandwidth, capacity, and scratch stay.
|
| template<typename StatesDerived> |
| void | assign (Eigen::MatrixBase< StatesDerived > const &states) |
| | Replaces the particles with the columns of states, with equal weights summing to one.
|
| template<typename StatesDerived, typename WeightsDerived> |
| void | assign (Eigen::MatrixBase< StatesDerived > const &states, Eigen::DenseBase< WeightsDerived > const &logWeights) |
| | Replaces the particles and weights.
|
| template<typename Derived> |
| Index | add (Scalar logWeight, Eigen::MatrixBase< Derived > const &state) |
| | Appends a particle.
|
|
template<typename OtherAllocator> |
| void | append (ParticleSet< Space_, Scalar_, OtherAllocator > const &other) |
| | Appends copies of other's particles, which must be in the same space.
|
|
void | remove (Index i) |
| | Removes particle i by moving the last particle into its place.
|
|
template<typename Derived> |
| void | setState (Index i, Eigen::MatrixBase< Derived > const &state) |
| | Sets particle i's state, normalized by the space.
|
| template<typename Derived> |
| void | setStates (Eigen::MatrixBase< Derived > const &states) |
| | Sets every state at once.
|
|
void | setLogWeight (Index i, Scalar logWeight) |
| | Sets particle i's log-weight.
|
|
template<typename Derived> |
| void | setLogWeights (Eigen::DenseBase< Derived > const &logWeights) |
| | Sets every log-weight at once; logWeights has one entry per particle.
|
|
void | scaleWeight (Index i, Scalar logScale) |
| | Multiplies the weight of particle i by \( e^{\mathrm{logScale}} \).
|
|
void | scaleWeights (Scalar logScale) |
| | Multiplies every weight by \( e^{\mathrm{logScale}} \).
|
| template<typename Derived> |
| void | scaleWeights (Eigen::DenseBase< Derived > const &logScales) |
| | Multiplies weight i by \( e^{\mathrm{logScales}_i} \), e.g.
|
| std::expected< Scalar, WeightError > | logTotalWeight () const |
|
template<ExecutionPolicy P> |
| std::expected< Scalar, WeightError > | logTotalWeight (P &&policy) const |
| | logTotalWeight() under policy: a reduction over the particles (see Execution policies).
|
| std::expected< void, WeightError > | normalize () |
| | Scales the weights so they sum to one.
|
|
template<ExecutionPolicy P> |
| std::expected< void, WeightError > | normalize (P &&policy) |
| | normalize() under policy: the total is a reduction over the particles, and scaling the weights a whole-array operation (see Execution policies).
|
| std::expected< WeightArrayType, WeightError > | normalizedWeights () const |
| std::expected< Scalar, WeightError > | ess () const |
|
template<ExecutionPolicy P> |
| std::expected< Scalar, WeightError > | ess (P &&policy) const |
| | ess() under policy: two reductions over the particles (see Execution policies).
|
| std::expected< MomentsType, WeightError > | moments () const |
|
template<ExecutionPolicy P> |
| std::expected< MomentsType, WeightError > | moments (P &&policy) const |
| | moments() under policy: reductions over the particles, which match Sequential's to rounding (see Execution policies).
|
| template<typename F> |
| void | forEach (F &&f) |
| | Calls f on each particle as a MutableParticle&, returning nothing; reweight() takes one that returns a log scale factor.
|
| template<ExecutionPolicy P, typename F> |
| void | forEach (P &&policy, F &&f) |
| | forEach() under policy, a for-each over the particles (see Execution policies).
|
|
template<typename F> |
| void | reweight (F &&f) |
| | Calls f on each particle as a MutableParticle&, as forEach() does, and adds what it returns, a log scale factor in a floating-point type, to that particle's log-weight.
|
|
template<ExecutionPolicy P, typename F> |
| void | reweight (P &&policy, F &&f) |
| | reweight() under policy, as forEach() under it runs.
|
template<bool ReturnRemovedWeight = false, typename Pred>
requires (!ReturnRemovedWeight && !ExecutionPolicy<Pred>) |
| void | removeIf (Pred pred) |
| | Removes every particle for which pred(logWeight, state) is true.
|
template<bool ReturnRemovedWeight, typename Pred>
requires (ReturnRemovedWeight && !ExecutionPolicy<Pred>) |
| std::expected< Scalar, WeightError > | removeIf (Pred pred) |
| | As above, returning the log of the removed fraction of the total weight, or the WeightError that left the set unchanged.
|
template<bool ReturnRemovedWeight = false, ExecutionPolicy P, typename Pred>
requires (!ReturnRemovedWeight) |
| void | removeIf (P &&policy, Pred pred) |
| | removeIf() under policy: pred runs as a for-each over the particles, and the particles kept are compacted, in order, through the scratch (see Execution policies).
|
template<bool ReturnRemovedWeight, ExecutionPolicy P, typename Pred>
requires ReturnRemovedWeight |
| std::expected< Scalar, WeightError > | removeIf (P &&policy, Pred pred) |
| | As above, returning the log of the removed fraction of the total weight, or the WeightError that left the set unchanged.
|
| std::expected< Scalar, WeightError > | pruneBelow (Scalar logThreshold) |
| | Removes every particle whose normalized log-weight is below logThreshold, and normalizes the weights of the rest; the heaviest particle is always kept, the first of them if several are.
|
| std::expected< Scalar, WeightError > | pruneTail (Scalar logFraction) |
| | Removes the lightest particles, as many as can be while their combined normalized weight stays below \( e^{\mathrm{logFraction}} \), and normalizes the weights of the rest.
|
| std::expected< Scalar, WeightError > | pruneToSize (Index maxSize) |
| | Removes the lightest particles until at most maxSize, at least one, remain, and normalizes the weights of the rest.
|
template<std::uniform_random_bit_generator G, typename R = resamplers::Systematic>
requires Resampler<R, Scalar, G> |
| std::expected< void, WeightError > | resample (G &rng, Index newSize, R const &resampler={}) |
| | Replaces the particles with newSize draws chosen by resampler in proportion to their weights, then sets every weight to \( 1/\mathrm{newSize} \).
|
template<std::uniform_random_bit_generator G, typename R = resamplers::Systematic>
requires Resampler<R, Scalar, G> |
| std::expected< void, WeightError > | resample (G &rng, R const &resampler={}) |
| | Resamples to the current size().
|
template<ExecutionPolicy P, std::uniform_random_bit_generator G, typename R = resamplers::Systematic>
requires Resampler<R, Scalar, G> |
| std::expected< void, WeightError > | resample (P &&policy, G &rng, Index newSize, R const &resampler={}) |
| | resample() under policy: the total weight is a reduction, the linear weights a whole-array expression on each chunk, the gather of the ancestors' states a for-each, and resampler runs under policy if it can (see ResamplerUnder), drawing from rng in the order the sequential form does.
|
template<ExecutionPolicy P, std::uniform_random_bit_generator G, typename R = resamplers::Systematic>
requires Resampler<R, Scalar, G> |
| std::expected< void, WeightError > | resample (P &&policy, G &rng, R const &resampler={}) |
| | resample() to the current size() under policy.
|
| std::span< Index const > | ancestors () const |
| Index | resampleCount () const |
|
template<typename Path> |
| auto | marginal () const & |
| | marginal() of the subspace named by the tag path Path (see idx()), whose space is that subspace with its parameters.
|
|
template<typename Path> |
| void | marginal () const &&=delete |
| | A marginal of a temporary would outlive it.
|
|
template<typename Path> |
| auto | marginal (Index element) const & |
| | marginal() of one repetition of a repeated block; see GaussianParams::marginal(element).
|
|
template<typename Path> |
| void | marginal (Index element) const &&=delete |
| | A marginal of a temporary would outlive it.
|
| template<typename GivenPath, typename Derived> |
| auto | conditional (Eigen::MatrixBase< Derived > const &values) const |
| std::expected< DensityType, NumericError > | toDensity () const & |
| | Validates the weights and builds a kernel density estimate with kdeBandwidth(): the stored bandwidth if there is one, otherwise Silverman's rule.
|
|
void | toDensity () const &&=delete |
| | A density of a temporary would outlive it.
|
| template<MatrixExpression Bandwidth> |
| std::expected< DensityType, NumericError > | toDensity (Bandwidth &&bandwidth) const & |
| | Validates the weights and builds a kernel density estimate with bandwidth bandwidth, of which only the lower triangle is read.
|
|
template<MatrixExpression Bandwidth> |
| void | toDensity (Bandwidth &&bandwidth) const &&=delete |
| | A density of a temporary would outlive it.
|
template<Space Space_, RealScalar Scalar_ = double, typename Allocator_ = DefaultAllocator>
class Emrys::ParticleSet< Space_, Scalar_, Allocator_ >
A set of weighted samples: the empirical distribution.
\[ \hat p(x) = \sum_i \hat w_i \, \delta(x - x_i), \qquad \hat w_i = w_i / \textstyle\sum_j w_j. \]
The weighted particle approximation of Arulampalam et al. (2002), §II, kept as a matrix of states and an array of log-weights.
Particle states are the columns of states(), with valueDimension() rows; their log-weights are logWeights(). Both are maps over storage the set keeps through its allocator (see Allocation), valid until the set's particles are added, removed, or resized. Weights need not be normalized; a log-weight of -inf is a zero weight. Particles are addressed by index, and the set has no begin() and end(): loop over the indices, or call forEach(). Removal may reorder the remaining particles. Statistics that need normalized weights, such as moments(), return a WeightError if the weights cannot be normalized (see logTotalWeight()).
A set given a Capacity reserves room for that many particles once, along with the scratch that resample() uses, so that resampling and replacing particles at a steady size allocate nothing. Holding more particles than the capacity is a precondition violation.
A set may carry a kernel bandwidth: the shared covariance \( H \) of the Gaussian kernels in its kernel density estimate, with differenceDimension() rows. kdeBandwidth() is the stored bandwidth if there is one, and Silverman's rule otherwise. Conditionals store their exact bandwidth this way. resample() clears a stored bandwidth, since it describes the cloud before the draw; other changes of the states keep it, so it can go stale; call clearBandwidth() to return to Silverman's rule.
A set of weighted points has no density of its own, so toDensity() returns its kernel density estimate: it validates the weights, factorizes a bandwidth, and returns a KernelDensity, which checks this object for changes: reading it after this object has changed in any way is a programmer error caught by EMRYS_FILTER_ASSERT (decisions.md [view-stamp]). So is changing the set from inside a forEach() or removeIf() callback.
marginal() returns a read-only view of a subset of the state entries, which checks only this object's size and structure: states, weights, and bandwidth may change under it, but reading it after particles are added, removed, resampled, or resized, or this object is assigned to, is a programmer error. Neither view may outlive this object, and neither may be made from a temporary.
The space's size always matches the states'. insert() and erase() grow and shrink one resizable block of the space in place, and resizeParticles() resizes a space with a single resizable block.
- Template Parameters
-
| Space_ | space of the states, which sets their dimensions and storage bounds (see Spaces): states are normalized when stored, and moments are tangent-space moments |
| Scalar_ | scalar type, double by default |
| Allocator_ | allocator for the states, weights, and scratch (see Allocation) |
- See also
- class KernelDensity, Resamplers
1.18.0