Rename twa to max_twa_parent, update docs

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/articles/compiled_models.Rmd b/docs/articles/compiled_models.Rmd
new file mode 100644
index 00000000..8b5d731a
--- /dev/null
+++ b/docs/articles/compiled_models.Rmd
@@ -0,0 +1,107 @@
+---
+title: "Performance benefit by using compiled model definitions in mkin"
+author: "Johannes Ranke"
+date: "`r Sys.Date()`"
+output:
+  html_document:
+    theme: united
+    toc: true
+    toc_float: true
+    mathjax: null
+vignette: >
+  %\VignetteIndexEntry{Performance benefit by using compiled model definitions in mkin}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+library(knitr)
+opts_chunk$set(tidy = FALSE, cache = FALSE)
+```
+
+## Model that can also be solved with Eigenvalues
+
+This evaluation is taken from the example section of mkinfit. When using an mkin version
+equal to or greater than 0.9-36 and a C compiler (gcc) is available, you will see
+a message that the model is being compiled from autogenerated C code when
+defining a model using mkinmod. The `mkinmod()` function checks for presence of
+the gcc compiler using
+
+```{r check_gcc}
+Sys.which("gcc")
+```
+First, we build a simple degradation model for a parent compound with one metabolite.
+
+```{r create_SFO_SFO}
+library("mkin")
+SFO_SFO <- mkinmod(
+  parent = mkinsub("SFO", "m1"),
+  m1 = mkinsub("SFO"))
+```
+
+We can compare the performance of the Eigenvalue based solution against the
+compiled version and the R implementation of the differential equations using
+the benchmark package.
+
+
+```{r benchmark_SFO_SFO, fig.height = 3}
+if (require(rbenchmark)) {
+  b.1 <- benchmark(
+    "deSolve, not compiled" = mkinfit(SFO_SFO, FOCUS_2006_D,
+                                      solution_type = "deSolve",
+                                      use_compiled = FALSE, quiet = TRUE),
+    "Eigenvalue based" = mkinfit(SFO_SFO, FOCUS_2006_D,
+                                 solution_type = "eigen", quiet = TRUE),
+    "deSolve, compiled" = mkinfit(SFO_SFO, FOCUS_2006_D,
+                                  solution_type = "deSolve", quiet = TRUE),
+    replications = 3)
+  print(b.1)
+  factor_SFO_SFO <- round(b.1["1", "relative"])
+} else {
+  factor_SFO_SFO <- NA
+  print("R package benchmark is not available")
+}
+```
+
+We see that using the compiled model is by a factor of around 
+`r factor_SFO_SFO`
+faster than using the R version with the default ode solver, and it is even
+faster than the Eigenvalue based solution implemented in R which does not need
+iterative solution of the ODEs.
+
+
+## Model that can not be solved with Eigenvalues
+
+This evaluation is also taken from the example section of mkinfit.
+
+```{r benchmark_FOMC_SFO, fig.height = 3}
+if (require(rbenchmark)) {
+  FOMC_SFO <- mkinmod(
+    parent = mkinsub("FOMC", "m1"),
+    m1 = mkinsub( "SFO"))
+
+  b.2 <- benchmark(
+    "deSolve, not compiled" = mkinfit(FOMC_SFO, FOCUS_2006_D,
+                                      use_compiled = FALSE, quiet = TRUE),
+    "deSolve, compiled" = mkinfit(FOMC_SFO, FOCUS_2006_D, quiet = TRUE),
+    replications = 3)
+  print(b.2)
+  factor_FOMC_SFO <- round(b.2["1", "relative"])
+} else {
+  factor_FOMC_SFO <- NA
+  print("R package benchmark is not available")
+}
+```
+
+Here we get a performance benefit of a factor of
+`r factor_FOMC_SFO`
+using the version of the differential equation model compiled from C code!
+
+This vignette was built with mkin `r packageVersion("mkin")` on
+
+```{r sessionInfo, echo = FALSE}
+cat(capture.output(sessionInfo())[1:3], sep = "\n")
+if(!inherits(try(cpuinfo <- readLines("/proc/cpuinfo")), "try-error")) {
+  cat(gsub("model name\t: ", "CPU model: ", cpuinfo[grep("model name", cpuinfo)[1]]))
+}
+```