10 Plugins

10.1 autodec

Available as of mrgsolve version 1.0.0.

When this plugin is invoked, mrgsolve will search your model code for assignments and automatically declare them as double precision numbers. The following blocks are searched

$PREAMBLE
$MAIN (or $PK)
$ODE (or $DES)
$TABLE (or $ERROR)
$PRED

For example, the following code requires that CL gets assigned a type

$PARAM WT = 70, TVCL = 1.2

$PK
double CL = TVCL * pow(WT/70, 0.75);

This is the default mrgsolve behavior and has been since the beginning.

The autodec plugin lets you write the following

$PLUGIN autodec 

$PARAM WT = 70, TVCL = 1.2

$PK
CL = TVCL * pow(WT/70, 0.75);

mrgsolve will find CL = ... and understand that this is a user initiated variable and will declare it as double for you. Don’t worry about WT = 70 in $PARAM; mrgsolve should already know about that won’t try to declare it.

When you are using the autodec plugin, you can still declare variables as double or int or bool. mrgsolve already finds those variables and will understand to leave those declarations alone. Note that it may still very convenient to declare using the capture type those variables that you want captured into the output

$PLUGIN autodec

$ERROR
capture Y = IPRED * exp(EPS(1));

The capture typedef makes Y a double; we didn’t need to declare it with autodec in play, but decided to declare with capture so that it is copied into the simulated output.

The autodec plugin is intended for more straightforward models where most / all variables are real valued. Because mrgsolve can handle any valid C++ code in these blocks, there is a possibility that the code could get much more complicated, including custom classes and methods. In this case, we recommend to bypass this feature and take control of declaring variables as you would in the default mode.

In case mrgsolve does try to declare (as double) a variable that shouldn’t be handled that way, you can note this name in an environment variable inside your model called MRGSOLVE_AUTODEC_SKIP

$ENV MRGSOLVE_AUTODEC_SKIP = c("my_variable_1")

This can be a vector of variable names to NOT declare when autodec is invoked.

10.2 nm-vars

Available as of mrgsolve version 1.0.0.

The nm-vars plugin provides a more NONMEM-like set of macros to use when coding your compartmental model. Only a small subset of the NONMEM model syntax is replicated here.

F, R, D, ALAG

To set bioavailability for the nth compartment, use Fn
To set the infusion rate for the nth compartment, use Rn
To set the infusion duration for the nth compartment, use Dn
To set the lag time for the nth compartment, use ALAGn

For example

$CMT GUT CENT GUT2

$PK
F1 = 0.87;    // equivalent to F_GUT  = 0.87;
R2 = 2.25;    // equivalent to R_CENT = 2.25;
ALAG3 = 0.25; // equivalent to ALAG_GUT2 = 0.25;

A, A_0, DADT

To refer to the amount in the nth compartment, use A(n)
To refer to the initial amount in the nth compartment, use A_0(n)
To refer to the differential equation for the nth compartment, use DADT(n)

For example

$CMT CMT1 CMT2

$PK
A_0(2) = 50;
  
$DES
DADT(1) = -KA * A(1);
DADT(2) =  KA * A(1) - KE * A(2);

Math

Starting with version 1.0.1, macros are provided for several math functions

EXP(a) gets mapped to exp(a)
LOG(a) gets mapped to log(a)
SQRT(a) gets mapped to sqrt(a)

These are purely for convenience, so that upper-case versions from NMTRAN don’t require conversion to lower-case; this happens automatically via the C++ preprocessor.

Other syntax

Using THETA(n) in model code will resolve to THETAn; this feature is always available, even when nm-vars hasn’t been invoked; we mention it here since it is a fundamental piece of the NONMEM syntax that mrgsolve has internalized
Use T in $DES to refer to the current time in the odesolver rather than SOLVERTIME

Reserved words with nm-vars is invoked

There are some additional reserved words when the nm-vars plugin is invoked

A
A_0
DADT
T

It is an error to use one of these symbols as the name of a parameter or compartment or to try to declare them as variables.

mrgsolve syntax that is still required

There are a lot of differences remaining between mrgsolve and NONMEM syntax. We mention a few here to make the point

mrgsolve continues to require pow(base, exponent) rather than base**exponent
mrgsolve continues to require a semi-colon at the end of each statement (this is a C++ requirement)
mrgsolve continues to require that user-defined variables are declared with a type, except when the autodec plugin (Section 10.1) is invoked

An example

There is an example of this syntax (along with autodec features) in the internal model library

mod <- modlib("nm-like")
see(mod)

. 
. Model file:  nm-like.cpp 
. $PROB Model written with some nonmem-like syntax features
. 
. $PLUGIN nm-vars autodec
. 
. $PARAM
. THETA1 = 1, THETA2 = 21, THETA3 = 1.3, WT = 70, F1I = 0.5, D2I = 2
. KIN = 100, KOUT = 0.1, IC50 = 10, IMAX = 0.9
. 
. $CMT @number 3
. 
. $PK
. CL = THETA(1) * pow(WT/70, 0.75); 
. V  = THETA(2); 
. KA = THETA(3);
. 
. F1 = F1I;
. D2 = D2I;
. A_0(3) = KIN / KOUT;
. 
. $DES 
. CP = A(2)/V;
. INH = IMAX*CP/(IC50 + CP);
.   
. DADT(1) = -KA*A(1);
. DADT(2) =  KA*A(1) - (CL/V)*A(2);
. DADT(3) =  KIN * (1-INH) - KOUT * A(3);
. 
. $ERROR
. CP = A(2)/V;

10.3 tad

Purpose Advanced calculation time after dose within your model. We call this “advanced” because it lets you track doses in multiple compartments. See the note below about a simpler way to calculate time after dose that should work fine if doses are only in a single compartment. This functionality is provided by mrgsolve.

Usage

First, tell mrgsolve that you want to use the tad plugin

$PLUGIN tad

The create tadose objects, one for each compartment where you want to track time after dose. One approach is to do this in [ global ]

[plugin] tad

[ global ] 
mrg::tadose tad_cmt_1(1); 
mrg::tadose tad_cmt_2(2);

Notice that we pass the compartment number that we want to track in each case and also that we refer to the mrg:: namespace for the tadose class.

The tadose objects contain the following (public) members

cmt the compartment to track
told the time of last dose; defaults to -1e9
had_dose indicates if a dose has already been given for the current individual
tad(self) the function to call to calculate time after dose
- the self object (Section 2.3.12) must be passed as the only argument
- when the member function is called prior to the first administered dose, a value of -1.0 is returned
reset() resets the state of the object; be sure to reset prior to simulating a new individual

As an example, you can call the reset() method on one of the tadose objects

tad_cmt_1.reset();

You can find the source code for this object here.

A working example model that tracks doses in compartments 1 and 2 is provided here

[plugin] tad

[ global ] 
mrg::tadose tad_cmt_1(1); 
mrg::tadose tad_cmt_2(2);

[ pkmodel ] cmt = "GUT,CENT", depot = TRUE

[ param ] CL = 1, V = 20, KA = 1

[ main ] 
capture tad1 = tad_cmt_1.tad(self); 
capture tad2 = tad_cmt_2.tad(self);

Static approach

Another approach would be to make these static in [ main ] but this approach would only work if you only use these in [ main ]; the [ global ] approach is preferable since then you can access the object in any block (function).

10.3.1 Note

Note there is a simpler way to calculate time after dose when only dosing into a single compartment

[ main ]
double tad = self.tad();

The self object (Section 2.3.21) contains a tad() member which will track time after dose. Note that this needs to be called every record.

10.4 evtools

Purpose

The evtools plugin is a set of functions and classes you can use to implement dosing regimens from inside your model. It first became available in mrgsolve 1.4.1. The most common use for this plugin is when you want to implement dynamic dosing simulations where the dose amount or the dosing interval is able to change based on how the system has advanced up to a certain point. For example, you might have a PKPD model for an oncology drug that includes a PK model for the drug as well as a dynamic model for platelets where a decline in platelets is driven by the drug concentration. In this case you might monitor platelets at different clinical visits and reduce the or hold dose or increase the dosing interval in response to Grade 3 or Grade 4 thrombocytopenia. For a real-world example, see this paper that we published in 2024.

Usage

Like all other plugins, you must invoke evtools in the $PLUGIN block

$PLUGIN evtools

10.4.1 Note about when events are processed

The syntax detailed below will show you how to trigger doses or other events from within your model. We frequently want to dose as soon as a certain condition is met; for example a compartment gets driven to a critical value or maybe we just get to a certain time. If we only dose when these conditions are met, the doses are said to happen “now” … at that specific time in the simulation when the condition is met. In contrast, your simulation might need to give the dose at some future time. Those doses are given “later” or in the future rather than now. If you are executing doses “now”, it can be important where in the model (which block) you write this code.

We recommend you write the code required for doses or events triggered from within your model in the $EVENT block that was first made available in mrgsolve version 1.5.2. The $EVENT block gets processed after the system advances in time, but immediately before the $TABLE block. An alternative is putting this code in $ERROR (or $TABLE). These are very similar options in that the events happen after advancing, but there is a very subtle difference in what you’ll see in the output at the time the event or dose happens but no difference in subsequent records. We recommend that you don’t put the actual dose execution in $PK (or $MAIN); this is particularly important for events happening “now” (see discussion above). While there may be some configuration of a regimen object there, we recommend any dose execution happens in $EVENT (or $ERROR).

10.4.2 Namespace

All the functionality made available by the evtools plugin is located in a namespace called evt. So you will need to prefix all functions and classes with evt::. For example, you can read about a function called bolus below; when you call that function, you need to refer to evt::bolus, locating that function in the evt namespace.

10.4.3 Event object type

Chapter 11 introduces a C++ event object called mrg::evdata. The evt namespace provides an easier-to-remember typedef for that object called evt::ev. So if a function returns an event object, you can use evt::ev for that type. For example, to create an event object for a bolus dose

evt::ev dose = evt::bolus(100, 1);

which is equivalent to

mrg::evdata dose evt::bolus(100, 1);

10.4.4 Simple administration of single doses now

The evt namespace allows you to easily administer single bolus or infusion doses. The functions are

void evt::bolus(self, <amt>, <cmt>) where
- self is the the self object, described in Section 2.3.12
- <amt> is the dose amount (type double)
- <cmt> is the dosing compartment (type int)
void evt::infuse(self, <amt>, <cmt>, <rate>) where
- self is the the self object, described in Section 2.3.12
- <amt> is the dose amount (type double)
- <cmt> is the dosing compartment (type int)
- <rate> is the infusion rate (type double)

Note that, for all these functions, self is passed as the first argument, there is no return value, and there is no time specified for the dose. All doses invoked this way are given now, as-is; so you should only call these functions when the model code has decided it is time to administer a dose.

Important: Because doses are given now, these functions should always be called in $TABLE (i.e., $ERROR) or $EVENT.

10.4.5 Replace amount in a compartment now

With mrgsolve version 1.5.1, there is also a function to replace the amount in a given compartment

void evt::replace(self, <amt>, <cmt>) where
- self is the the self object, described in Section 2.3.12
- <amt> is the replacement amount (type double)
- <cmt> is the replacement compartment (type int)

The replace functionality works just like evt::bolus() described above, but the compartment is reset prior to adding <amt>.

10.4.6 Reset the system now

System reset is accomplished with EVID 3. Starting with mrgsolve 1.5.2, a function is provided to do this

void evt::reset(self) where
- self is the self object, described in Section 2.3.12

You can also reset and dose, which is accomplished with EVID 4 as a bolus

void evt::reset(self, <amt>, <cmt>) where
- self is the self object, described in Section 2.3.12
- <amt> is the bolus dose amount
- <cmt> is the dosing compartment

or an infusion

void evt::reset(self, <amt>, <cmt>, <rate>) where
- self is the self object, described in Section 2.3.12
- <amt> is the infusion dose amount
- <cmt> is the dosing compartment
- <rate> is the infusion rate

10.4.7 Customized dosing, replacement, or reset potentially given later

The evt namespace also provides variants of these functions which return the event object to you so you can modify some of the attributes (e.g., schedule the dose in the future) prior to sending the object back to mrgsolve for processing. These functions are

evt::ev evt::bolus(<amt>, <cmt>) where
- <amt> is the dose amount (type double)
- <cmt> is the dosing compartment (type double)
evt::ev evt::infuse(<amt>, <cmt>, <rate>) where
- <amt> is the dose amount (type double)
- <cmt> is the dosing compartment (type double)
- <rate> is the infusion rate (type double)
evt::ev evt::replace(<amt>, <cmt>) where
- <amt> is the new amount (type double)
- <cmt> is the replacement compartment (type double)
evt::ev evt::reset()
evt::ev evt::reset(<amt>, <cmt>) where
- <amt> is a dose amount (type double)
- <cmt> is the dosing compartment (type double)

For example, if I want to give a dose of 100 mg infused over 2 hours, getting the object back prior to sending to mrgsolve

evt::ev dose = evt::infuse(100, 100.0/2.0, 2);

Note that we don’t pass in the self object here; just the dose amount, compartment, and rate for infusions. These functions also return and event object (type evt::ev) that you can work with. See Section 11.5 for documentation of those attributes.

To send the event back to mrgsolve, you’ll have to push it with

self.push(dose);

evt::push(self, dose);

More about push() below.

10.4.8 Insert non-dosing event or observation records

These records will never appear in the simulated output, but will ensure the model “stops” at these times so, for example, monitoring can take place and decisions made about future behavior or events in the simulation. The function is:

ev::evt evt::tgrid(<start>, <end>, <delta>) where
- <start> is the time when the grid is to start (type double)
- <end> is the time when the grid is to end (type double)
- <delta> is the time step between <start> and <end> (type double)

To request a time grid over a week of simulation (168 hours), stopping every hour with EVID set to 33, the workflow looks like:

$EVENT

evt::ev obs = evt::tgrid(0, 168, 1);
evt::evid(obs, 33);
self.push(obs);

The default EVID for the obs object above is 0, but we’ve changed that to 33 using evt::evid(). The 33 EVID doesn’t mean anything specific to mrgsolve, but it could function as a signal to the modeler that one of these special time stops has been encountered in the simulation

$EVENT

if(EVID==33) {
  // Do something ...
}

Note that, starting with mrgsolve version 1.6.1, EVID values less than 100 (but not EVID 0) will always trigger the ODE solver to restart, creating a discontinuity in the simulation. There’s always a small performance hit when the ODE solver resets, so just use these wisely. If you need to monitor something with an internal time grid but you don’t need a hard discontinuity in the simulation, use EVID OF 100 or more; these function just like observation records (EVID 0) with no ODE solver reset, but also do not have special handling in mrgsolve.

Whether you choose to introduce a discontinuity or not, you should consider specifying a “custom” EVID for these new records in the simulation to be able to distinguish these records from other records in the simulation.

10.4.9 API for customizing doses

Section 11.5 shows you some low-level ways to customize the event object the evt namespace provides some API for making these changes.

10.4.9.1 Set dose interval

Use evt::ii() to set a dosing interval

evt::ev dose = evt::bolus(100, 1);
evt::ii(dose, 12);
self.push(dose);

Arguments:

an event object (evt::ev)
a dosing interval (<double>)