Merge pull request #55 from mrc-ide/mrc-5687

Update README

README.md

@@ -1,15 +1,48 @@
-# odin2
+# odin2 <img src='man/figures/logo.png' align="right" height="139" />
 
 <!-- badges: start -->
 [![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)
 [![R build status](https://github.com/mrc-ide/odin2/workflows/R-CMD-check/badge.svg)](https://github.com/mrc-ide/odin2/actions)
-[![Build status]()](https://buildkite.com/mrc-ide/mrcide/odin2?branch=main)
 [![codecov.io](https://codecov.io/github/mrc-ide/odin2/coverage.svg?branch=main)](https://codecov.io/github/mrc-ide/odin2?branch=main)
 <!-- badges: end -->
 
+`odin2` implements a high-level language for describing and implementing ordinary differential equations and difference equations in R.  It provides a "[domain specific language](https://en.wikipedia.org/wiki/Domain-specific_language)" (DSL) which _looks_ like R but is compiled directly to C++, using [`dust2`](https://mrc-ide.github.io/dust2/) to solve your system and to provide an interface to particle filters.  You can then use [`monty`](https://mrc-ide.github.io/monty/) to fit your models using MCMC.
+
+* The DSL is _declarative_ reflecting the mathematical nature of the equations.
+* It includes support for equations that involve vectors, matrices and higher dimensional arrays (up to 8!), including a high-level array indexing notation that removes the need for explicit looping.
+* Supports both discrete-time (possibly stochastic) models, as well as continuous-time ODE models.
+* Interpolation functions can be used to include time-varying quantities into the model (piecewise constant, linear and spline interpolation is supported).
+* The equations are analysed before compilation so that parts that do not depend on time are not included in time-dependent calculations.
+* Supports user-supplied parameters for any part of the system.
+* Supports a large number of mathematical functions (see the [functions vignette](https://mrc-ide.github.io/odin2/articles/functions.html) for a complete list).
+
+## Documentation
+
+* See [the introductory vignette](https://mrc-ide.github.io/odin2/articles/odin2.html) for a tutorial-style introduction to `odin2`
+* A [tutorial-style guide](https://mrc-ide.github.io/odin2/articles/fitting.html) to using `odin2` with `dust2` and `monty` to fit models to data
+* A [reference-style guide](https://mrc-ide.github.io/odin2/articles/functions.html) to the syntax and supported functions
+* If you have used [`odin` version 1](https://mrc-ide.github.io/odin) before, see the [migration guide](https://mrc-ide.github.io/odin2/articles/migrating.html) to see what has changed.
+* Because `odin2` compiles to `dust2`, see [its documention](https://mrc-ide.github.io/dust2) and in particular the [list of functions that you can use](https://mrc-ide.github.io/dust2/reference/index.html)
+
+## Roadmap
+
+The package is currently ready for use for adventurous users.  It will eventually become [`odin`](https://mrc-ide.github.io/odin) and replace that version on CRAN (i.e., it will simply become version 2.0.0 of `odin`, and `odin2` will cease to be a package name that you will see).  It also replaces [odin.dust](https://mrc-ide.github.io/odin.dust).  It exists separately for now to facilitate development and use alongside the original `odin`.
+
+See [this list](https://mrc-ide.github.io/odin2/articles/migrating.html#missing-features) of missing features from version 1 of odin before using.
+
+Over the next few months we will be expanding the automatic differentiation support, generating code for other host languages and improving the ergonomics of the package.
+
 ## Installation
 
-To install `odin2`:
+Please install from our r-universe:
+
+```r
+install.packages(
+  "odin2",
+  repos = c("https://mrc-ide.r-universe.dev", "https://cloud.r-project.org"))
+```
+
+If you prefer, you can install from GitHub with `remotes`:
 
 ```r
 remotes::install_github("mrc-ide/odin2", upgrade = FALSE)

vignettes/helpers.R

@@ -0,0 +1,6 @@
+lang_output <- function(x, lang) {
+  cat(c(sprintf("```%s", lang), x, "```"), sep = "\n")
+}
+cpp_output <- function(x) lang_output(x, "cpp")
+r_output <- function(x) lang_output(x, "r")
+plain_output <- function(x) lang_output(x, "plain")

vignettes/migrating.Rmd

@@ -12,9 +12,14 @@ knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>"
 )
+source("helpers.R")
 ```
 
-This vignette discusses key differences with odin version 1 (`odin1` in this document).
+This vignette discusses key differences with odin version 1.
+
+```{r}
+library(odin2)
+```
 
 # New features
 
@@ -43,10 +48,8 @@ This list is incomplete, and we'll expand it as we work through the tests.  We'r
 
 Things we do plan on implementing:
 
-* Arrays (partial implementation is complete)
 * Debugging print statements (only recently introduced into odin)
 * Interpolation with array output
-* Transformation of output
 * Non-variable output from ODEs with `output()` (`mrc-5497`)
 * Delay differential equations, e.g. `y_lag <- delay(y, tau)` (`mrc-5434`)
 * Compile-time parameter substitution (`mrc-5575`)
@@ -226,3 +229,58 @@ The relationship between packages has changed.  Previously `mcstate` "knew" abou
 ## Much slower compilation time
 
 Because we now compile to C++ via `dust2`, the compilation times have massively increased.  Previously, compilation of a simple model took less than a second, but now this will take 6 seconds or so.  You can alleviate this to a degree during development by specifying `debug = TRUE` when compiling, which reduces this down to about 3 seconds.  These times are from my workstation but I expect the relative differences to hold (we're probably 10x slower than previously but can be "only" 5x slower if you turn off optimisation).  If you were previously using `odin.dust` you should notice little change here.
+
+# Updating old code
+
+If you compile odin code that contains any of the changes above, it will try and update the code to the new version and keep going:
+
+```{r}
+gen <- odin2::odin({
+  initial(x) <- 1
+  deriv(x) <- x + a / t
+  a <- user(2)
+}, quiet = TRUE, debug = TRUE)
+```
+
+This model contains two issues that can be easily rewritten; the solution to this rewriting is printed to screen and the model is compiled as if you had rewritten them.
+
+Not everything can be rewritten, especially changes involving `step`:
+
+```{r, error = TRUE, purl = FALSE}
+gen <- odin2::odin({
+  initial(x) <- 1
+  update(x) <- x + a / step
+  a <- user(2)
+}, quiet = TRUE, debug = TRUE)
+```
+
+In this case, odin errors and tries to indicate where you have work to do (and directs you to this document!)
+
+For code saved into a file, you can use `odin_migrate` to migrate code from the old syntax to the new; this will preserve comments and formatting except for code that is rewritten so it should be fairly unintrusive.
+
+```{r, include = FALSE}
+path <- tempfile(fileext = ".R")
+writeLines(c(
+  "initial(x) <- 1",
+  "deriv(x) <- x + a / t",
+  "a <- user(2)"),
+  path)
+```
+
+For example, in `path` (a temporary file for this vignette) we have saved the code from above:
+
+```{r echo = FALSE, results = "asis"}
+r_output(readLines(path))
+```
+
+We can migrate this in-place with:
+
+```{r}
+odin_migrate(path, path)
+```
+
+and now the code contains:
+
+```{r echo = FALSE, results = "asis"}
+r_output(readLines(path))
+```