particles.core

Core module.

Overview

This module defines the following core objects:

  • FeynmanKac: the base class for Feynman-Kac models;

  • SMC: the base class for SMC algorithms;

  • multiSMC: a function to run a SMC algorithm several times, in parallel and/or with varying options.

You don’t need to import this module: these objects are automatically imported when you import the package itself:

import particles
help(particles.SMC)  # should work

Each of these three objects have extensive docstrings (click on the links above if you are reading the HTML version of this file). However, here is a brief summary for the first two.

The FeynmanKac abstract class

A Feynman-Kac model is basically a mathematical model for the operations that we want to perform when running a particle filter. In particular:

  • The distribution M_0(dx_0) says how we want to simulate the particles at time 0.

  • the Markov kernel M_t(x_{t-1}, dx_t) says how we want to simulate particle X_t at time t, given an ancestor X_{t-1}.

  • the weighting function G_t(x_{t-1}, x_t) says how we want to reweight at time t a particle X_t and its ancestor is X_{t-1}.

For more details on Feynman-Kac models and their properties, see Chapter 5 of the book.

To define a Feynman-Kac model in particles, one should, in principle:

  1. sub-class FeynmanKac (define a class that inherits from it) and define certain methods such as M0, M, G, see the documentation of FeynmanKac for more details;

  2. instantiate (define an object that belongs to) that sub-class.

In many cases however, you do not need to do this manually:

  • module state_space_models defines classes that automatically generate the bootstrap, guided or auxiliary Feynman-Kac model associated to a given state-space model; see the documentation of that module.

  • Similarly, module smc_samplers defines classes that automatically generates FeynmanKac objects for SMC tempering, IBIS and so on. Again, check the documentation of that module.

That said, it is not terribly complicated to define manually a Feynman-Kac model, and there may be cases where this might be useful. There is even a basic example in the tutorials if you are interested.

SMC class

SMC is the class that define SMC samplers. To get you started:

import particles
... # define a FeynmanKac object in some way, see above
pf = particles.SMC(fk=my_fk_model, N=100)
pf.run()

The code above simply runs a particle filter with N=100 particles for the chosen Feynman-Kac model. When this is done, object pf contains several attributes, such as:

  • X: the current set of particles (at the final time);

  • W: their weights;

  • cpu_time: as the name suggests;

  • and so on.

SMC objects are iterators, making it possible to run the algorithm step by step: replace the last line above by:

next(step) # do iteration 0
next(step) # do iteration 1
pf.run() # do iterations 2, ... until completion (dataset is exhausted)
All options, minus model, are optional. Perhaps the most important ones are:

  • qmc: if set to True, runs SQMC (the quasi-Monte Carlo version of SMC)

  • resampling: the chosen resampling scheme; see resampling module.

  • store_history: whether we should store the particles at all iterations;

    useful in particular for smoothing, see smoothing module.

See the documentation of SMC for more details.

Functions

multiSMC([nruns, nprocs, out_func, collect])

Run SMC algorithms in parallel, for different combinations of parameters.

Classes

FeynmanKac(T)

Abstract base class for Feynman-Kac models.

SMC([fk, N, qmc, resampling, ESSrmin, ...])

Metaclass for SMC algorithms.