Summary

An easy to use library for SMC algorithms (Sequential Monte Carlo, AKA particle filters).

The main features are:

1. Parallelized implementation of SMC with adaptive resampling, including efficient implementations of multinomial, stratified, and systematic resampling.
2. Flexible interfaces for designing proposals, including generic-type particles.
3. Basic PMCMC integration into the probabilistic programming language Blang for declarative inference of static parameters.

Installation

There are several ways to install:

Integrate to a gradle script

Simply add the following lines (replacing 1.0.2 by the current version (see git tags)):

repositories {
 mavenCentral()
 jcenter()
 maven {
    url "http://www.stat.ubc.ca/~bouchard/maven/"
  }
}

dependencies {
  compile group: 'ca.ubc.stat', name: 'simplesmc', version: '1.0.2'
}

Compile using the provided gradle script

• Check out the source git clone [email protected]:alexandrebouchard/simplesmc.git
• Compile using gradle installApp
• Add the jars in build/install/simplesmc/lib/ into your classpath

Use in eclipse

• Check out the source git clone [email protected]:alexandrebouchard/simplesmc.git
• Type gradle eclipse from the root of the repository
• From eclipse:
  • Import in File menu
  • Import existing projects into workspace
  • Select the root
  • Deselect Copy projects into workspace to avoid having duplicates

Simple SMC example

We show here a simple example where the target distribution is a finite HMM. This is only for test purpose, to ensure that the estimate of the log normalization is close to the true value.

Note the only step required to customize the SMC algorithm to more complex and interesting problem is to create a class that implements simplesmc.ProblemSpecification.

// Create a synthetic dataset
Random random = new Random(1);
ToyHMMParams hmmParams = new ToyHMMParams(5);
Pair<List<Integer>, List<Integer>> generated = HMMUtils.generate(random, hmmParams, 10);
List<Integer> observations = generated.getRight();

// Here we can compute the exact log Z using sum product since we have a discrete HMM
double exactLogZ = HMMUtils.exactDataLogProbability(hmmParams, observations);
System.out.println("exact = " + exactLogZ);

// Run SMC to ensure correctness of our implementation
HMMProblemSpecification proposal = new HMMProblemSpecification(hmmParams, observations);
SMCOptions options = new SMCOptions();
options.nParticles = 1_000;
SMCAlgorithm<Integer> smc = new SMCAlgorithm<>(proposal, options);

// Check they agree within 1%
double approxLogZ = smc.sample().logNormEstimate();
System.out.println("estimate = " + approxLogZ);
double tol = Math.abs(exactLogZ / 100.0);
System.out.println("tol = " + tol);
Assert.assertEquals(exactLogZ, approxLogZ, tol);

_{From:simplesmc.TestSMC}

Simple PMCMC example

See this link for an example of a main class for a probabilistic program that samples from the posterior of a static parameter using PMCMC (more precisely, only PMMH is supported at the moment). The main customization is the Model class, which declaratively specifies the priors on the static parameters.

Running this class will create a folder called results/ in which your experiments will be automatically organized. Note that you should have R in your path for creation of some plots from the MCMC output.

The Option (and OptionSet) annotations specifies command line options (respectively, classes specifying more command line options. For example the command line option -nThreads 8 is defined and explained in the class SMCOption via the field smcOption. See TestPMCMC and its OptionSets for more, or type -help to see the full list with instructions.

_{From:simplesmc.TestPMCMC}