Guide to odin docs

Rich FitzJohn

2024-07-01

odin has grown from just one package to a series of packages; this document aims to help orient you to the right place to understand how pieces fit together and where to find help.

The packages

• odin contains the domain specific language (DSL), and the original implementation suitable for simple use. It can compile continuous time (ODE) and discrete time models to C, R or JavaScript. It contains no ability to do inference.
• dust contains an engine for running odin-style models in parallel. It supports both continuous time and discrete time models, but does not “know” anything about odin. This is the lower level support that many users will end up engaging with eventually.
• odin.dust is a package for compiling odin models to work with dust. It will likely merge into odin once dust is on CRAN.
• mcstate is a package for performing inference with odin models compiled to work with dust. It implements a particle filter, particle MCMC and other statistical methods.

Documentation

• Introduction to odin: a tour of the original odin’s features
• Discrete time models:
• Functions available in odin: a brief summary of available functions in odin. This applies to both odin and odin.dust models, but with the conditions discussed in the porting guide
• Debugging odin code: this applies to both odin and odin.dust models
• SIR models in odin.dust: shows how to use odin.dust to explore a stochastic SIR model, without doing inference on it
• Porting odin models to odin.dust: Differences between the original version of odin and the subset of the DSL supported by odin.dust

The documentation for mcstate concerns mostly performing inference with odin.dust models

• An introduction: walks through performing inference with a simple SIR model
• Deterministic models: describes how to create deterministic models from your stochastic models, and how these can speed up your inference.
• Running inference on models with multiple parameter sets at once: for example a model where parameters are structured by region.
• Parallelisation of inference: the two ways that you can parallelise models (at the chain and particle level), tradeoffs and how to control this.
• Other, less generally useful articles include: A strategy for restarting a pMCMC inference in time, Iterated filtering - an algorithm familiar to pomp users, comparison of our particle filter with a Kalman filter.

The documentation for dust is typically more advanced, but will be useful at times for users of odin.dust models

• The ideas in dust: discusses what dust models can do, and how they try to help you.
• Introduction to dust: covers manually building a dust model (which you are unlikely to want to do) but also covers what dust models can do, by example.
• Working with multiple parameter sets: covers building dust objects that simultaneously run for multiple parameter sets at once. This is the only source of documentation for this at present.
• Comparing models and data: covers details of the lower-level model/data comparison.
• Random number generation: covers details of how the random number generation works, how it can generate numbers in parallel, and performance differences with R’s built-in generators.
• Running models on a GPU: lower-level details of running models on the GPU
• Other, even more specialised topics such as details of the random number algorithms, using the dust RNG in other packages and generating random numbers in highly-parallel situations.

Missing topics:

• Using ODE models with odin.dust
• The DSL for comparing models and data
• Higher-level documentation of multiple parameter sets at once
• Higher-level documentation for running models on a GPU
• Lower-level documentation on the relationship between deterministic and stochastic models
• More details on constructing transformation functions in mcstate

Each package also comes with reference documentation, which contains examples and detailed help for individual functions.

• odin
• odin.dust
• dust
• mcstate

The TypeScript ecosystem

In addition to the above, we are growing our ability to work with JavaScript models - the main output of this is wodin, an interface for running odin models on the web, which you can see at epimodels.dide.ic.ac.uk.

• wodin: wodin itself
• dopri-js: an ODE solver in TypeScript allowing smooth interpolation of its solutions
• dfoptim: derivative-free optimisation methods for TypeScript
• odin-js: TypeScript support for running continuous time odin models
• dust-js: An implementation of part of the dust interface in TypeScript
• random-js: Another random number library for JavaScript

Roadmap

• Eventually we will merge odin.dust into odin (once dust is on CRAN)
• We may deprecate the original discrete time interface
• We will implement some of the missing features mentioned in the porting guide within odin.dust
• We are designing a DSL for mcstate to make the inference part of the system nicer to work with; this will include an overhaul of the nested models.