**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:

- 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;- 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.

## Module summary¶

`FeynmanKac` |
Abstract base class for Feynman-Kac models. |

`SMC` |
Metaclass for SMC algorithms. |

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