R: Read a model specification file

mread {mrgsolve} | R Documentation

## Read a model specification file

### Description

`mread` reads and parses the `mrgsolve` model specification file, builds the model, and returns a model object for simulation. `mread_cache` does the same, but caches the compilation result for later use.

### Usage

    mread(
      model,
      project = getOption("mrgsolve.project", getwd()),
      code = NULL,
      file = NULL,
      udll = TRUE,
      ignore.stdout = TRUE,
      raw = FALSE,
      compile = TRUE,
      audit = TRUE,
      quiet = getOption("mrgsolve_mread_quiet", FALSE),
      check.bounds = FALSE,
      warn = TRUE,
      soloc = getOption("mrgsolve.soloc", tempdir()),
      capture = NULL,
      preclean = FALSE,
      recover = FALSE,
      ...
    )

    mread_cache(
      model = NULL,
      project = getOption("mrgsolve.project", getwd()),
      file = paste0(model, ".cpp"),
      code = NULL,
      soloc = getOption("mrgsolve.soloc", tempdir()),
      quiet = FALSE,
      preclean = FALSE,
      capture = NULL,
      ...
    )

    mread_file(file, ...)

### Arguments

`model` | model name
`project` | location of the model specification file an any headers to be included; see also the discussion about model; this argument can be set via `options()` library under details as well as the `modlib` help topic
`code` | a character string with model specification code to be used instead of a model file
`file` | the full file name (with extension, but without path) where the model is specified
`udll` | use unique name for shared object
`ignore.stdout` | passed to system call for compiling model
`raw` | if TRUE, return a list of raw output
`compile` | logical; if `TRUE`, the model will be built
`audit` | check the model specification file for errors
`quiet` | don't print messages when compiling
`check.bounds` | check boundaries of parameter list
`warn` | logical; if `TRUE`, print warning messages that may arise
`soloc` | the directory location where the model shared object is built and stored; see details; this argument can be set via `options()`; if the directory does not exist, 'mread' will attempt to create it.
`capture` | a character vector or comma-separated string of additional model variables to capture; these variables will be added to the capture list for the current call to `mread` only
`preclean` | logical; if `TRUE`, compilation artifacts are cleaned up first
`recover` | if `TRUE`, a list of build will be returned in case the model shared object fails to compile; use this option to and the returned object to collect information assist in debugging
`...` | passed to `update`; also arguments passed to mread from `mread_cache`.

### Details

The `model` argument is required. For typical use, the `file` argument is omitted and the value for `file` is generated from the value for `model`. To determine the source file name, `mrgsolve` will look for a file extension in `model`. A file extension is assumed when it finds a period followed by one to three alpha-numeric characters at the end of the string (e.g. `mymodel.txt` but not `my.model`). If no file extension is found, the extension `.cpp` is assumed (e.g. `file` is `<model-name>.cpp`). If a file extension is found, `file` is `<model-name>`.

Best practice is to avoid using `.` in `model` unless you are using `model` to point to the model specification file name. Otherwise, use `mread_file`.

Use the `soloc` argument to specify a directory location for building the model. This is the location where the model shared object will be stored on disk. The default is a temporary directory, so compilation artifacts are lost when R restarts when the default is used. Changing `soloc` to a persistent directory location will preserve those artifacts across R restarts. Also, if simulation from a single model is being done in separate processes on separate compute nodes, it might be necessary to store these compilation artifacts in a local directory to make them accessible to the different nodes. If the `soloc` directory does not exist, 'mread' will attempt to create it.

Similarly, using `mread_cache` will cache results in the temporary directory and the cache cannot be accessed after the R process is restarted.

### Model Library

`mrgsolve` comes bundled with several precoded PK, PK/PD, and other systems models that are accessible via the `mread` interface.

Models available in the library include:

- PK models: `pk1cmt`, `pk2cmt`, `pk3cmt`, `pk1`, `pk2`, `popex`, `tmdd`

- PKPD models: `irm1`, `irm2`, `irm3`, `irm4`, `emax`, `effect`

- Other models: `viral1`, `viral2`

When the library model is accessed, `mrgsolve` will compile and load the model as you would for any other model. It is only necessary to reference the correct model name and point the `project` argument to the `mrgsolve` model library location via `modlib`.

For more details, see `modlib_pk`, `modlib_pkpd`, `modlib_tmdd`, `modlib_viral`, and `modlib_details` for more information about the state variables and parameters in each model.

### See Also

`mcode`, `mcode_cache`

### Examples

    ## Not run:
    code <- '
    $PARAM CL = 1, VC = 5
    $CMT CENT
    $ODE dxdt_CENT = -(CL/VC)*CENT;
    '

    mod <- mcode("ex_mread", code)

    mod

    mod %>% init(CENT=1000) %>% mrgsim %>% plot

    mod <- mread("irm3", modlib())

    mod

    # if the model is in the file mymodel.cpp
    mod <- mread("mymodel")

    # if the model is in the file mymodel.txt
    mod <- mread(file = "mymodel.txt")

    or

    mod <- mread_file("mymodel.txt")

    ## End(Not run)

[Package mrgsolve version 1.0.4 Index]