odin (version 1.0.1)

odin: Create an odin model

Description

Create an odin model from a file, text string(s) or expression. The odin_ version is a "standard evaluation" escape hatch.

Usage

odin(x, verbose = NULL, target = NULL, workdir = NULL,
  validate = NULL, pretty = NULL, skip_cache = NULL,
  compiler_warnings = NULL, no_check_unused_equations = NULL,
  no_check_naked_index = NULL)
odin_(x, verbose = NULL, target = NULL, workdir = NULL,
  validate = NULL, pretty = NULL, skip_cache = NULL,
  compiler_warnings = NULL, no_check_unused_equations = NULL,
  no_check_naked_index = NULL)

Arguments

x

Either the name of a file to read, a text string (if length is greater than 1 elements will be joined with newlines) or an expression.

verbose

Logical scalar indicating if the compilation should be verbose. Defaults to the value of the option odin.verbose or FALSE otherwise.

target

Compilation target. Options are "c" and "r", defaulting to the option odin.target or "c" otherwise.

workdir

Directory to use for any generated files. This is only relevant for the "c" target. Defaults to the value of the option odin.workdir or tempdir() otherwise.

validate

Validate the model's intermediate representation against the included schema. Normally this is not needed and is intended primarily for development use. Defaults to the value of the option odin.validate or FALSE otherwise.

pretty

Pretty-print the model's intermediate representation. Normally this is not needed and is intended primarily for development use. Defaults to the value of the option odin.pretty or FALSE otherwise.

skip_cache

Skip odin's cache. This might be useful if the model appears not to compile when you would expect it to. Hopefully this will not be needed often. Defaults to the option odin.skip_cache or FALSE otherwise.

compiler_warnings

Logical scalar indicating if compiler warnings should be converted to R warnings. If this is TRUE, then if any compiler warnings are generated, the compiler output will be displayed (regardless of the value of verbose) within an R warning (suppressible via suppressWarnings and catchable via tryCatch). The default is to default to FALSE unless the global option odin.compiler_warnings is set to TRUE (set with options(odin.compiler_warnings = TRUE)). The default may change to TRUE in future. Warnings are currently a mix of ambiguous syntax in your model (worth fixing) and limitations in the code that odin generates (which you can't fix but I will get on to over time). What is flagged will depend strongly on your platform and what is in your Makevars. I develop odin with -Wall -Wextra -pedantic and still see warnings with both gcc and clang. The compiler output is very simple and may not work on all platforms. Defaults to the option odin.compiler_warnings or FALSE otherwise.

no_check_unused_equations

If TRUE, then don't print messages about unused variables. Defaults to the option odin.no_check_unused_equations or FALSE otherwise.

no_check_naked_index

If TRUE, then if an index variable (i, j, ...) is used outside of an array subset (e.g., x[] <- i) then a notice is printed. The behaviour of this functionality changed in odin version 0.2.0 and this flag is intended to notify users about the change. See https://github.com/mrc-ide/odin/issues/136 for more information. Defaults to the option odin.no_check_naked_index or FALSE otherwise.

Value

A function that can generate the model

User parameters

If the model accepts user parameters, then the parameter to the constructor or the set_user method can be used to control the behaviour when unknown user actions are passed into the model.Possible values are the strings stop (throw an error), warning (issue a warning but keep going), message (print a message and keep going) or ignore (do nothing). Defaults to the option odin.unused_user_action, or warning otherwise. The default behaviour prior to odin version 0.2.0 was equivalent to ignore.

Delay equations with dde

When generating a model one must chose between using the dde package to solve the system or the default deSolve. Future versions may allow this to switch when using run, but for now this requires tweaking the generated code to a point where one must decide at generation. dde implements only the Dormand-Prince 5th order dense output solver, with a delay equation solver that may perform better than the solvers in deSolve. For non-delay equations, deSolve is very likely to outperform the simple solver implemented.

Details

Do not use odin::odin in a package; you almost certainly want to use odin_package instead; see the odin_package vignette for more information.

A generated model can return information about itself; odin_ir

Examples

# NOT RUN {
## Compile the model; exp_decay here is an R6ClassGenerator and will
## generate instances of a model of exponential decay:
exp_decay <- odin::odin({
  deriv(y) <- -0.5 * y
  initial(y) <- 1
}, target = "r")

## Generate an instance; there are no parameters here so all instances
## are the same and this looks a bit pointless.  But this step is
## required because in general you don't want to have to compile the
## model every time it is used (so the generator will go in a
## package).
mod <- exp_decay()

## Run the model for a series of times from 0 to 10:
t <- seq(0, 10, length.out = 101)
y <- mod$run(t)
plot(y, xlab = "Time", ylab = "y", main = "", las = 1)
# }