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 themodlib
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 frommread_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.
Examples
if (FALSE) {
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")
}