Stochastic models appear in many domains as they are easy to write out, but hard to analyse without running many realisations of the process. dust provides an engine for running stochastic models, taking care of many bookkeeping details such as:

  • Running stochastic models in parallel on multi-core machines
  • Running models massively in parallel on GPU without writing any low-level code
  • Reducing output by filtering over steps or intermediate outputs
  • Providing useful verbs for working with stochastic models (for initialisation, state setting, parameter updating, and inspection)
  • Combining multiple realisations due to stochastic variability and due to different parameter sets

Get started

Two vignettes provide an overview of the package, depending on your tastes:

There are further vignettes describing details:

And several on the random number generator, around which dust is built:

The C++ API is documented in a separate set of documentation

You can also read our open access paper describing dust and some related tools that use it:

FitzJohn, Knock, Whittles, Perez-Guizman, Bhatia, Guntoro, Watson, Whittaker, Ferguson, Cori, Baguelin, Lees 2021: Reproducible parallel inference and simulation of stochastic state space models using odin, dust, and mcstate, Wellcome Open Research 5, 288


The dust package, while designed to be user-friendly, is lower-level than many users need. The odin.dust package provides a way of compiling stochastic odin models to work with dust. For example, to create a parallel epidemiological model, one might write simply:

sir <- odin.dust::odin_dust({
  update(S) <- S - n_SI
  update(I) <- I + n_SI - n_IR
  update(R) <- R + n_IR

  n_IR <- rbinom(I, 1 - exp(-beta * I / (S + I + R)))
  n_SI <- rbinom(S, 1 - exp(-gamma))

  initial(S) <- S_ini
  initial(I) <- I_ini
  initial(R) <- 0

  S_ini <- user(1000)
  I_ini <- user(10)
  beta <- user(0.2)
  gamma <- user(0.1)


We use dust to power several epidemiological models. Public examples include:

  • sircovid - a large model (over 15k states) of COVID-19 in the UK
  • gonovaxdust - a model of gonorrhoea infection with vaccination


To install dust:

# install.packages("drat") # -- if you don't have drat installed

You will need a compiler to install dependencies for the package, and to build any models with dust. dust uses pkgbuild to build its shared libraries so use pkgbuild::check_build_tools() to see if your system is ok to use.

The development version of the package can be installed directly from GitHub if you prefer with:

remotes::install_github("mrc-ide/dust", upgrade = FALSE)


MIT © Imperial College of Science, Technology and Medicine