Planned

• Optional array bounds checking, during runtime (in the latter case with a performance penalty once enabled).

Hoped

• Support for multinomial samples and other vector-valued functions

user() becomes parameter()

This might be the largest user-visible change, and can be automatically migrated.

Previously, to support parameters you might write

a <- user(4)

which says that a is a user-supplied parameter with a default value of 4. In most cases this now simply becomes

a <- parameter(4)

The integer argument accepted by user has now changed:

• user(integer = TRUE) becomes parameter(type = "integer")
• user(integer = FALSE) becomes parameter(type = "real")

This translation can be done automatically in most cases, and will be done (with a warning) by default if possible. You should update your code with the suggested fix, however, as this translation will be removed in a future version.

Compare keyword is now removed.

In comparisons such as

compare(d) ~ Normal(0, 1)

The compare keyword, and the ~ only occur together. This has been simplified, and is now written as:

d ~ Normal(0, 1)

which reads as: d is normally distributed with a mean of 0 and standard deviation of 1.

Vector parameters assign without array indices

Previously, if you had a vector parameter you had to write

a[] <- parameter()
dim(a) <- 10

(though with user(), as in the previous section). However, the array index here does not really add anything as we already know how many dimensions a has from the dim call. So now you should write

a <- parameter()
dim(a) <- 10

which makes it clearer that all of a is assigned by the parameter call.

Vector/matrix/array parameters whose size is determined by input require rank argument

What a mouthful. Previously you might have written

a[, ] <- user()
dim(a) <- user()

which means “a is a matrix whose dimensions are determined by the input we are given on initialisation”. Because of the previous change the first line changes to

a <- parameter()

but that means that we no longer know that a has two dimensions. That’s ok because we’ve moved the responsibility for this into the dim() assignment line anyway (internally). So for now you write

dim(a) <- parameter(rank = 2)

which conveys the same intent. We may make this slightly more friendly in future (see vignette("functions")).

Interpolate results assign without array indices

Previously, if you had an interpolate() call that returned a vector (or higher-dimension array) you had to write

v[] <- interpolate(a, b, "constant")

but now you should drop the [], as for the parameter() case above, as you are replacing all of v at once, writing:

v <- interpolate(a, b, "constant")

Discrete-time models have a more solid time basis

Previously, discrete time models used step to count steps forward as unsigned integers, usually from zero. Many models added a parameter (or constant) dt representing the timestep and then a variable time which represented the time as a real-valued number. For example you might have dt of 0.25 and then your model stops at times [0, 0.25, 0.5, 0.75, 1] for steps [0, 1, 2, 3, 4].

We formalise this approach now having discrete time systems be explicitly in terms of the same time basis as ODE models (that is, some real valued time axis). When you initialise a model you pass in dt, which must be an even divisor of 1 (so 0.5, 0.25, 0.2, etc). We then take steps of this size. The wrinkle is that (at least for now) the model will only return control back to you, or state back to you, at integer-valued times. We may relax this in future to allow returning at any time value that is a multiple of dt.

This will cause a few issues for using old code, which we cover below.

time <- step * dt

a <- if (step %% freq == 0) b else c

a <- if (time * dt / m == 0) b else c

The name of the time variable in continuous time models has changed

Previously, time was t but we have moved this to time to be a little more explicit. We can automatically migrate your code in many cases, unless you have defined a variable time already.

Random number function calls have changed

Previously we used the same names as R’s random-number-drawing functions, for example rbinom for drawing from a binomial distribution. This has changed to use the distribution name instead.

The motivating reason for this change was that in odin we might write

rbinom(size, prob)

but if you were writing this in R you would write

rbinom(1, size, prob)

with the first argument being the number of draws from the distribution in question. This departure in arguments feels needlessly confusing! If you were using odin without odin.dust then this did compile to a call to one of R’s underlying random number functions so this connection was reasonable but from version 2 we use monty’s parallelisable random number distributions.

The mapping is:

• rbeta() to Beta
• rbinom() to Binomial
• rcauchy() to Cauchy
• rchisq() to ChiSquared (unsupported for now)
• rexp() to Exponential
• rf() to F (unsupported for now)
• rgamma() to Gamma
• rgeometric() to Geometric (unsupported for now)
• rhyper() to Hypergeometric
• rlogis() to Logistic (unsupported for now)
• rlnorm() to LogNormal
• rnbinom() to NegativeBinomial
• rnorm() to Normal
• rpois() to Poisson
• rt() to T (unsupported for now)
• runif() to Uniform
• rweibull() to Weibull

(Not all of these are implemented yet).

System size cannot be changed after creation

This limitation comes from our implementation in dust2 and it is possible to relax it in some settings. However, it is fairly important for efficiently running the system within a pMCMC context where we save state periodically.

If your system has a parameter that affects the number of state variables in the system (e.g., the number of age categories that a compartment is stratified by), you may not change this after initialisation. This will be prevented by the parser once arrays are implemented.

Changes in the way arrays are handled

The two-argument form of dim() has been removed, as we did not believe it was used and it is confusingly different to R. Previously you could write dim(x, 3) to get the length of the third dimension of x; this is no longer supported. Please let us know if this is a problem.

delay() cannot be used in discrete time models

This was removed in odin.dust and the limitation remains, at least for now. We may enable this later if required, please let us know. The reason for this change is that the way that delays are handled in continuous time is fundamentally different to how we would do this in discrete time (particularly with stochastic expressions), but we do not have a good motivating reason to develop this.

delay() results assign without array indices

Previously, if you had a delay() call that returned a vector (or higher-dimension array) you had to write

v[] <- delay(a, tau)

but now you should drop the [], as for the parameter() and interpolate() cases above, as you are replacing all of v at once, writing:

v <- delay(a, tau)

The first argument to delay() must be the name of an equation

Previously, you could delay an expression (e.g., x <- delay(a + b, 1)). For simplicity in implementation we have dropped this and require that the first argument is a symbol. We might change this later, but in the current version it makes the syntax around handling delayed arrays a little more consistent (see above).

The ‘default’ argument to delay() has been removed

Previously, you could write

x <- delay(y, tau, default)

to provide a default argument to the delayed value before tau time had elapsed. This was not widely advertised or used, and has been removed.

The delay time must be constant

We require that the delay time is known at first model initialisation and not updated subsequently (i.e., that it is numeric, a literal value assigned to symbol or a paramter with constant = TRUE).

Much slower compilation time

Because we now compile to C++ via dust2, the compilation times have massively increased. Previously, compilation of a simple model took less than a second, but now this will take 6 seconds or so. You can alleviate this to a degree during development by specifying debug = TRUE when compiling, which reduces this down to about 3 seconds. These times are from my workstation but I expect the relative differences to hold (we’re probably 10x slower than previously but can be “only” 5x slower if you turn off optimisation). If you were previously using odin.dust you should notice little change here.