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:
-
vignette("design")describes the problemsdusttries to solve (read on package website) -
vignette("dust")describesdustby example, showing two simple models and the methods that can drive them (read on package website)
There are further vignettes describing details:
-
vignette("multi")on simulating multiple parameter sets at once -
vignette("data")on running a bootstrap particle filter -
vignette("gpu")on creating and running models on GPUs
And several on the random number generator, around which dust is built:
-
vignette("rng")on the parallel random number generator used -
vignette("rng_algorithms")on the details of algorithms used to sample from some distributions -
vignette("rng_package")on using the generators from other packages
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:
Higher-level
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)
})Use-cases
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
Installation
Please install from our r-universe:
install.packages(
"dust",
repos = c("https://mrc-ide.r-universe.dev", "https://cloud.r-project.org"))If you prefer, you can install from GitHub with remotes:
remotes::install_github("mrc-ide/dust")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.
