## Introduction

This briefly describes the syntax used to define models that
`rxode2`

will translate into R-callable compiled code. It
also describes the communication of variables between `R`

and
the `rxode2`

modeling specification.

Below is a commented example to quickly show the capabilities of
`rxode2`

syntax.

## Example

```
# An rxode2 model specification (this line is a comment).
if(comed==0){ # concomitant medication (con-med)?
F = 1.0; # full bioavailability w.o. con-med
}
else {
F = 0.80; # 20% reduced bioavailability
}
C2 = centr/V2; # concentration in the central compartment
C3 = peri/V3; # concentration in the peripheral compartment
# ODE describing the PK and PD
d/dt(depot) = -KA*depot;
d/dt(centr) = F*KA*depot - CL*C2 - Q*C2 + Q*C3;
d/dt(peri) = Q*C2 - Q*C3;
d/dt(eff) = Kin - Kout*(1-C2/(EC50+C2))*eff;
```

## Syntax

An `rxode2`

model specification consists of one or more
statements optionally terminated by semi-colons `;`

and
optional comments (comments are delimited by `#`

and an
end-of-line).

A block of statements is a set of statements delimited by curly
braces, `{ ... }`

.

Statements can be either assignments, conditional
`if`

/`else if`

/`else`

,
`while`

loops (can be exited by `break`

), special
statements, or printing statements (for debugging/testing)

Assignment statements can be:

**simple**assignments, where the left hand is an identifier (i.e., variable)special

**time-derivative**assignments, where the left hand specifies the change of the amount in the corresponding state variable (compartment) with respect to time e.g.,`d/dt(depot)`

:special

**initial-condition**assignments where the left hand specifies the compartment of the initial condition being specified, e.g.`depot(0) = 0`

special model event changes including

**bioavailability**(`f(depot)=1`

),**lag time**(`alag(depot)=0`

),**modeled rate**(`rate(depot)=2`

) and**modeled duration**(`dur(depot)=2`

). An example of these model features and the event specification for the modeled infusions the rxode2 data specification is found in rxode2 events vignette.special

**change point syntax, or model times**. These model times are specified by`mtime(var)=time`

special

**Jacobian-derivative**assignments, where the left hand specifies the change in the compartment ode with respect to a variable. For example, if`d/dt(y) = dy`

, then a Jacobian for this compartment can be specified as`df(y)/dy(dy) = 1`

. There may be some advantage to obtaining the solution or specifying the Jacobian for very stiff ODE systems. However, for the few stiff systems we tried with LSODA, this actually slightly slowed down the solving.

Note that assignment can be done by `=`

,
`<-`

or `~`

.

When assigning with the `~`

operator, the **simple
assignments** and **time-derivative** assignments
will not be output.

Special statements can be:

**Compartment declaration statements**, which can change the default dosing compartment and the assumed compartment number(s) as well as add extra compartment names at the end (useful for multiple-endpoint nlmixr models); These are specified by`cmt(compartmentName)`

**Parameter declaration statements**, which can make sure the input parameters are in a certain order instead of ordering the parameters by the order they are parsed. This is useful for keeping the parameter order the same when using 2 different ODE models. These are specified by`param(par1, par2,...)`

An example model is shown below:

```
# simple assignment
C2 = centr/V2;
# time-derivative assignment
d/dt(centr) = F*KA*depot - CL*C2 - Q*C2 + Q*C3;
```

Expressions in assignment and `if`

statements can be
numeric or logical.

Numeric expressions can include the following numeric operators
`+, -, *, /, ^`

and those mathematical functions defined in
the C or the R math libraries (e.g., `fabs`

,
`exp`

, `log`

, `sin`

,
`abs`

).

You may also access the R’s functions in the R
math libraries, like `lgammafn`

for the log gamma
function.

The `rxode2`

syntax is case-sensitive, i.e.,
`ABC`

is different than `abc`

, `Abc`

,
`ABc`

, etc.

### Identifiers

Like R, Identifiers (variable names) may consist of one or more
alphanumeric, underscore `_`

or period `.`

characters, but the first character cannot be a digit or underscore
`_`

.

Identifiers in a model specification can refer to:

- State variables in the dynamic system (e.g., compartments in a pharmacokinetics model).
- Implied input variable,
`t`

(time),`tlast`

(last time point), and`podo`

(oral dose, in the undocumented case of absorption transit models). - Special constants like
`pi`

or R’s predefined constants. - Model parameters (e.g.,
`ka`

rate of absorption,`CL`

clearance, etc.) - Others, as created by assignments as part of the model
specification; these are referred as
*LHS*(left-hand side) variable.

Currently, the `rxode2`

modeling language only recognizes
system state variables and “parameters”, thus, any values that need to
be passed from R to the ODE model (e.g., `age`

) should be
either passed in the `params`

argument of the integrator
function `rxSolve()`

or be in the supplied event
data-set.

There are certain variable names that are in the `rxode2`

event tables. To avoid confusion, the following event table-related
items cannot be assigned, or used as a state but can be accessed in the
rxode2 code:

`cmt`

`dvid`

`addl`

`ss`

`rate`

`id`

However the following variables are cannot be used in a model specification:

`evid`

`ii`

Sometimes rxode2 generates variables that are fed back to rxode2.
Similarly, nlmixr generates some variables that are used in nlmixr
estimation and simulation. These variables start with the either the
`rx`

or `nlmixr`

prefixes. To avoid any problems,
it is suggested to not use these variables starting with either the
`rx`

or `nlmixr`

prefixes.

## Logical Operators

Logical operators support the standard R operators `==`

,
`!=`

`>=`

`<=`

`>`

and `<`

. Like R these can be in `if()`

or
`while()`

statements, `ifelse()`

expressions.
Additionally they can be in a standard assignment. For instance, the
following is valid:

`cov1 = covm*(sexf == "female") + covm*(sexf != "female")`

Notice that you can also use character expressions in comparisons.
This convenience comes at a cost since character comparisons are slower
than numeric expressions. Unlike R, `as.numeric`

or
`as.integer`

for these logical statements is not only not
needed, but will cause an syntax error if you try to use the
function.

## Interface and data handling between R and the generated C code

Users specify which variables are the dynamic system’s state
variables via the `d/dt(identifier)`

operator as part of the
model specification, and which are model parameters via the
`params=`

argument in `rxode2`

`solve()`

method:

```
m1 <- rxode2(model = ode, modName = "m1")
# model parameters -- a named vector is required
theta <-
c(KA=0.29, CL=18.6, V2=40.2, Q=10.5, V3=297, Kin=1, Kout=1, EC50=200)
# state variables and their amounts at time 0 (the use of names is
# encouraged, but not required)
inits <- c(depot=0, centr=0, peri=0, eff=1)
# qd1 is an eventTable specification with a set of dosing and sampling
# records (code not shown here)
solve(theta, event = qd1, inits = inits)
```

The values of these variables at pre-specified time points are saved
during model fitting/integration and returned as part of the fitted
values (see the function `eventTable`

, in particular its
member function `add.sampling`

function to define a set of
time points when to capture the values of these variables) and returned
as part of the modeling output.

The ODE specification mini-language is parsed with the help of the
open source tool *DParser*, Plevyak (2015).

## Supported functions

All the supported functions in rxode2 can be seen with the
`rxSupportedFuns()`

.

A brief description of the built-in functions are in the following table:

```
#> rxode2 2.0.13.9000 using 1 threads (see ?getRxThreads)
#> no cache: create with `rxCreateCache()`
```

Note that `lag(cmt) =`

is equivalent to
`alag(cmt) =`

and not the same as `= lag(wt)`