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


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

## 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

```{r child='../man/rmdhunks/rxode2-syntax-hunk.Rmd'}
```


## 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:

```{r, echo=FALSE, screenshot.force=FALSE}
library(rxode2)
## rxSyntaxFunctions <- read.csv("syntax-functions.csv");usethis::use_data(rxSyntaxFunctions)
library(DT)
datatable(rxSyntaxFunctions, rownames = FALSE, filter="top", options = list(pageLength = 10, scrollX=T) )
```

Note that `lag(cmt) = ` is equivalent to `alag(cmt) = ` and not the same as `= lag(wt)`

## Reserved keywords

There are a few reserved keywords in a rxode2 model.  They are  in the following table:

```{r, echo=FALSE, screenshot.force=FALSE}
## rxReservedKeywords <- read.csv("reserved-keywords.csv");names(rxReservedKeywords)[1] <- "Reserved Name";usethis::use_data(rxReservedKeywords)
datatable(rxReservedKeywords, rownames = FALSE, filter="top", options = list(pageLength = 10, scrollX=T) )
```

Note that `rxFlag` will always output `11` or `calc_lhs` since that is
where the final variables are calculated, though you can tweak or test
certain parts of `rxode2` by using this flag.

## Bugs and/or deficiencies

- The modulo operator `%%` is currently unsupported. 

## Note

The ODE specification mini-language is parsed with the help of the
open source tool \code{dparser}, Plevyak (2015).
