---
title: "RxODE ODE solving syntax"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{RxODE ODE solving syntax}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r, echo=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>")
```

## Introduction

This briefly describes the syntax used to define models 
that `RxODE` will translate into R-callable compiled code. It also
describes the communication of variables between `R` and the
`RxODE` modeling specification.

## Example

```
   # An RxODE 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 `RxODE` 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` 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** (`lag(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 RxODE data specification is found in [RxODE
  events vignette](https://nlmixrdevelopment.github.io/RxODE/articles/RxODE-event-types.html).
- 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)`
- 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 `<-`.

Additionally, assignment can be done with the `~` operator, which
causes RxODE to use the variable/expression while solving but suppress
output to either the matrix or data-frame returned in R. The
suppression works with **simple assignments** and **time-derivative**
assignments.  All other variable/assignments do not produce output,
but are used for the solving.

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,
however, no character nor integer expressions are currently supported. 

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`).  Notice
that the modulo operator `%` is currently unsupported.

You may also access the R's functions in the [R math
libraries](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Numerical-analysis-subroutines),
like `lgammafn` for the log gamma function.

There are certain variable names that are in the `RxODE` event tables.
To avoid confusion, the following event table-related items cannot be
used in a RxODE model specification:

- `rate`
- `amt`
- `ss`
- `addl`
- `evid`
- `ii`
- `dvid`


The `RxODE` 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](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Mathematical-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 `RxODE` 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 `solve()` or be in the
supplied event data-set.

Sometimes RxODE generates variables that are fed back to RxODE.
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.


## 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 `RxODE`
`solve()` method:

```
m1 <- RxODE(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).

## Bugs and/or deficiencies

- The modulo operator `%` is currently unsupported. 
- `else if`  is not currently supported 
- Conditional statements inside a single statement like `ifelse` are
  not currently supported.
- Logical expressions within a statement are not supported, that is
  `(cmt==2)*1+(cmt==3)*4` is not supported
