Package 'odin2' reference manual

Title:	Next generation odin
Description:	Temporary package for rewriting odin.
Authors:	Rich FitzJohn [aut, cre], Wes Hinsley [aut], Thibaut Jombart [ctb], Ed Knock [ctb], Imperial College of Science, Technology and Medicine [cph]
Maintainer:	Rich FitzJohn <[email protected]>
License:	MIT + file LICENSE
Version:	0.3.46
Built:	2026-05-07 14:12:43 UTC
Source:	https://github.com/mrc-ide/odin2

Compile an odin model

Description

Compile an odin model, yielding a dust_system_generator object.

Usage

odin(
  expr,
  ...,
  input_type = NULL,
  quiet = NULL,
  workdir = NULL,
  debug = NULL,
  skip_cache = FALSE,
  compatibility = NULL,
  check_bounds = NULL,
  target = NULL
)
odin(
  expr,
  ...,
  input_type = NULL,
  quiet = NULL,
  workdir = NULL,
  debug = NULL,
  skip_cache = FALSE,
  compatibility = NULL,
  check_bounds = NULL,
  target = NULL
)

Arguments

expr

Odin code as the path to a file (a string), a character vector of code, or as an expression (typically within braces {}).

...

Unused, must be empty. This allows us to add and reorder remaining arguments at will, as all arguments must be specified by name, not position).

input_type

An optional string describing the type of input for expr - must be one of file, text or expression. If given, this skips the type detection logic and odin will throw an error if the wrong type of input is given. Using this may be beneficial in programmatic environments.

quiet

Logical, indicating if compilation messages from pkgbuild should be displayed. Error messages will be displayed on compilation failure regardless of the value used. If NULL is given, then we take the value from DUST_QUIET if set, or FALSE otherwise.

workdir

Optional working directory to use. If NULL, the behaviour depends on the existence of the environment variable DUST_WORKDIR_ROOT. If it is unset we use a session-specific temporary directory (generated by tempfile()). If DUST_WORKDIR_ROOT is set, then we use a stable generated filename within this directory, which allows different sessions to effectively share a cache. If you pass a directory name here as a string, then we will use that directory to write all code, which allows you to inspect the generated code. See vignette("details") for more information.

debug

Passed to pkgbuild::compile_dll, this will build a debug library. If NULL is given, then we take the value from DUST_DEBUG if set, or FALSE otherwise.

skip_cache

Logical, indicating if the cache of previously compiled systems should be skipped. If TRUE then your system will not be looked for in the cache, nor will it be added to the cache after compilation.

compatibility

Compatibility mode to use. Valid options are "warning", which updates code that can be fixed, with warnings, and "error", which will error. The option "silent" will silently rewrite code, but this is not recommended for general use as eventually the compatibility mode will be removed (this option is primarily intended for comparing output of odin1 and odin2 models against old code). The default, NULL, currently corresponds to warning.

check_bounds

Control over static array bounds checking. This is enabled by default, but is prone to false positives, erroring where a read or write appears out of bounds but is actually ok. This argument exists to allow you to disable the check and compile the model anyway. Future versions may allow specific lines to be ignored, which will provide finer control and allow you to use the bits of the checks that are actually helpful. You can also pass TRUE here to mean "error" or FALSE to mean "disabled".

target

Compilation target. If provided, it must be one of cpp or js. In future, we hope to support cuda to enable support compilation to run on NVIDIA GPUs. The default, NULL, falls back on the option odin2.target, and if that is unset we currently select cpp, but this is subject to change once the JavaScript support is complete.

Value

A dust_system_generator object, suitable for using with dust functions (starting from dust2::dust_system_create)

Examples


# A random walk:
gen <- odin({
  initial(x) <- 0
  update(x) <- Normal(x, 1)
})

sys <- dust2::dust_system_create(gen, list(), n_particles = 10)
y <- dust2::dust_system_simulate(sys, 0:100)
matplot(t(y[1, , ]), type = "l", lty = 1, xlab = "Time", ylab = "Value")

# A random walk:
gen <- odin({
  initial(x) <- 0
  update(x) <- Normal(x, 1)
})

sys <- dust2::dust_system_create(gen, list(), n_particles = 10)
y <- dust2::dust_system_simulate(sys, 0:100)
matplot(t(y[1, , ]), type = "l", lty = 1, xlab = "Time", ylab = "Value")

Explain an odin error

Description

Explain error codes produced by odin. When odin fails to parse your code (e.g., via odin() or odin_validate()) it will return an error with a code. You can use odin_error_explain to get more information on that code. By default we will print an explanation to the screen, but you can control this behaviour via the how argument. All error codes can be found in vignette("errors").

Usage

odin_error_explain(code, how = "pretty")
odin_error_explain(code, how = "pretty")

Arguments

code

The error code, as a string, in the form Exxxx (a capital "E" followed by four numbers)

how

How to explain the error. Options are pretty (render pretty text in the console), plain (display plain text in the console) and link (browse to the online help).

Value

Nothing, this is called for its side effect only

Examples

odin_error_explain("E1006")
odin_error_explain("E1006")

Migrate odin code

Description

Migrate odin code. This function takes a path to existing odin code and writes out migrated code to a new file. It is possible that no code will be migrated, in which case the written contents will be identical to those read.

Usage

odin_migrate(path, dest)
odin_migrate(path, dest)

Arguments

path

Path of the odin code to read

dest

Path of the destination code. It can be the same as dest, in which case the file will be overwritten.

Value

Nothing; called for side effects only

Examples


# A file 'path' contains odin code using old features:
writeLines(readLines(path))

# Migrate this file in place (by overwriting)
odin_migrate(path, path)

writeLines(readLines(path))
# A file 'path' contains odin code using old features:
writeLines(readLines(path))

# Migrate this file in place (by overwriting)
odin_migrate(path, path)

writeLines(readLines(path))

Update odin code in package

Description

Update generated code in a package that uses odin and dust to provide a model. This will generate new dust code in inst/dust and from that generate a full model in src, and an R interface in R/dust.R, along with the cpp11 attributes that are needed to use the model.

Usage

odin_package(path, quiet = FALSE, compatibility = NULL, check_bounds = NULL)
odin_package(path, quiet = FALSE, compatibility = NULL, check_bounds = NULL)

Arguments

path

Path to the package root (the directory that contains DESCRIPTION), or any path within that package.

quiet

compatibility

check_bounds

Details

This function is powered by dust2::dust_package, and the same pre-requisites apply here:

For your DESCRIPTION file:

dust2 must be in Imports
cpp11, dust2 and monty must be in LinkingTo

For your NAMESPACE file:

you must have a suitable useDynLib() call with .registration = TRUE

If you do not satisfy these requirements, dust2::dust_package will fail with a message indicating actions you should take. Once set up, generally things will keep working.

If you want your packages to build on GitHub actions, or be installable via remotes::install_github you should add to your DESCRIPTION:

Remotes: mrc-ide/dust2, mrc-ide/monty

Note that you do not need to include odin2 itself as a dependency.

Value

Invisibly, the path to the package. However, this function is typically called for its side effect of updating files in inst/dust and src within this package after you have changed the odin code in inst/odin.

Examples



# An example package structure
fs::dir_tree(path)

# Generate odin code:
odin_package(path)

# Resulting files:
fs::dir_tree(path)

# An example package structure
fs::dir_tree(path)

# Generate odin code:
odin_package(path)

# Resulting files:
fs::dir_tree(path)

Show generated odin code

Description

Show generated code from compiling an odin model.

Usage

odin_show(
  expr,
  input_type = NULL,
  compatibility = NULL,
  check_bounds = NULL,
  what = NULL
)
odin_show(
  expr,
  input_type = NULL,
  compatibility = NULL,
  check_bounds = NULL,
  what = NULL
)

Arguments

expr

Odin code as the path to a file (a string), a character vector of code, or as an expression (typically within braces {}).

input_type

compatibility

check_bounds

what

Optional string, being a single method to show. Popular options are update, rhs and compare_data.

Value

A character vector, with class odin_code that has a pretty-print method defined. Returns NULL if what was given but the model lacks this part.

Examples

# Show generated code for the whole system
odin_show({
  initial(x) <- 1
  update(x) <- a
  a <- Normal(x, 1)
})

# Just the update method
odin_show({
  initial(x) <- 1
  update(x) <- a
  a <- Normal(x, 1)
}, what = "update")
# Show generated code for the whole system
odin_show({
  initial(x) <- 1
  update(x) <- a
  a <- Normal(x, 1)
})

# Just the update method
odin_show({
  initial(x) <- 1
  update(x) <- a
  a <- Normal(x, 1)
}, what = "update")

Validate odin code

Description

Validate odin code. This is primarily intended for use within other applications.

Usage

odin_validate(
  expr,
  input_type = NULL,
  compatibility = NULL,
  check_bounds = NULL
)
odin_validate(
  expr,
  input_type = NULL,
  compatibility = NULL,
  check_bounds = NULL
)

Arguments

expr

Odin code as the path to a file (a string), a character vector of code, or as an expression (typically within braces {}).

input_type

compatibility

check_bounds

Value

A list with elements:

success: boolean, TRUE if validation was successful
result: Metadata about the model; see Details above for the format.
error: Either NULL (if success is TRUE) or an error; see Details above for interpreting this value.
compatibility: A data.frame of compatibility issues. This is formatted similarly to src within error (see above), but also includes type (a code for the compatibility issue), description (a human-readable description of the issue), original (the original expression) and value (the final expression).

The intention is that we won't throw generally from this function.

Result

On successful validation, we return a list with metadata about the model. Currently this contains:

time: The time mode of the model (a string of either "discrete" or "continuous")
parameters: A data.frame describing parameters. Currently the only column is name.
variables: A data.frame describing the model variables. Currently the only column is name.
data: A data.frame describing data used by the model (if it supports this). Currently the only column is name.

Errors

Most errors will have class odin_parse_error. These will print context information if rethrown. They have fields:

message: The headline error message
code: The odin error code, as listed in vignette("errors"), and used by odin_error_explain
src: Source information about the error. This is a data.frame with columns index (the expression number), expr (a list column with the expression), start (the starting line; possibly NA), end (the finishing line; possibly NA), str (the string containing the literal value of the expression; possibly NA) and migrated (a logical, indicating if the source has been automatically migrated from odin1 code). If any of start, end or str is NA, all will be, for all rows.

You can get the full rendered message using conditionMessage() on the error object.

Examples

# A successful validation:
odin_validate({
  initial(x) <- 1
  deriv(x) <- a
  a <- parameter()
})

# A failure:
odin_validate({
  initial(x) <- 1
  deriv(x) <- a
})

# Migration warnings
odin_validate({
  initial(x)
  deriv(x) <- a
  a <- user()
})
# A successful validation:
odin_validate({
  initial(x) <- 1
  deriv(x) <- a
  a <- parameter()
})

# A failure:
odin_validate({
  initial(x) <- 1
  deriv(x) <- a
})

# Migration warnings
odin_validate({
  initial(x)
  deriv(x) <- a
  a <- user()
})

Package 'odin2'

Help Index

Compile an odin model

Description

Usage

Arguments

Value

Examples

Explain an odin error

Description

Usage

Arguments

Value

Examples

Migrate odin code

Description

Usage

Arguments

Value

Examples

Update odin code in package

Description

Usage

Arguments

Details

Value

See Also

Examples

Show generated odin code

Description

Usage

Arguments

Value

Examples

Validate odin code

Description

Usage

Arguments

Value

Result

Errors

Examples