A One-Compartment Model in mrgsolve

From the One-Compartment Equations to an mrgsolve Model

A pharmacometric model is not fully specified by its equations alone. The software implementation must also identify which quantities are parameters, which variable represents the evolving drug amount, how the dose enters the system, and what is reported as the model output. This tutorial builds a fixed-parameter, one-compartment intravenous bolus model in mrgsolve and checks the simulation against its analytical solution.

The model describes drug amount in the central compartment after a single instantaneous dose. It assumes linear elimination, constant clearance and volume, and no input after the bolus. It is a simulation example, not an estimation workflow: the parameter values are supplied rather than estimated from data. Use a consistent time unit throughout; here, time is in hours, clearance in L/h, volume in L, amount in mg, and concentration in mg/L.

The state variable is an amount, not a concentration. That choice matters: clearance has units of volume per time, so the elimination rate in amount per time is \(CL\times C(t)=CL\times A(t)/V\). The resulting rate is negative because elimination reduces the amount in the compartment.

Analytical Solution as an Implementation Check

Separating variables in the state equation gives \(dA/A=-(CL/V)dt\). Integrating from time zero to \(t\), and using \(A(0)=D\), gives \(\ln A(t)-\ln D=-(CL/V)t\). Exponentiating and dividing by \(V\) yields the amount and concentration predictions:

This solution provides an independent numerical check on the differential equation implemented by mrgsolve. It also makes the model's implications explicit: the concentration immediately after the bolus is \(D/V\), and the concentration declines exponentially at rate \(CL/V\). These statements depend on the model assumptions above; they are not general properties of every pharmacokinetic model.

Writing the Model File

A minimal mrgsolve model file can declare the two parameters, create the central amount compartment, define its differential equation, and calculate a concentration output. The following content can be saved as one_cmt_iv.cpp:

$PARAM CL = 5, V = 50
$CMT CENT
$ODE
dxdt_CENT = -(CL/V)*CENT;
$TABLE
double CP = CENT/V;
$CAPTURE CP

The blocks have distinct roles. $PARAM declares model parameters and assigns the default values used in this example. $CMT CENT declares the central compartment state named CENT; without a separate initial-state specification, it starts at zero before the dose is administered. $ODE defines the derivative of that state. The symbol dxdt_CENT is mrgsolve's derivative for CENT, so the assignment implements \(dA/dt=-(CL/V)A\).

In $TABLE, the local variable CP is calculated from the current state and volume. $CAPTURE CP makes CP available as a reported output. The state CENT is also available in simulation output. Naming the output CP signals that it is a predicted concentration; it does not create another state or affect the differential equation.

mrgsolve does not enforce the units written in comments or in a modeler's documentation. The analyst must ensure that the dose amount, volume, clearance, and time scale agree. For example, if time is measured in hours, clearance must be expressed per hour, not per day, unless an explicit conversion is made.

Running a Bolus Simulation

After saving the file in the working project directory, load and compile it, create a dose event into compartment 1, and request output every two hours through 24 hours:

library(mrgsolve)
mod <- mread("one_cmt_iv", project = ".")
dose <- ev(amt = 1000, time = 0, cmt = 1)
out <- mrgsim(mod, events = dose, end = 24, delta = 2)

Here the event amount is 1,000 mg, and cmt = 1 refers to the first compartment declared by $CMT, CENT. The event time is zero hours. The output grid requests times separated by two hours; it does not change the dose or the model equations. Inspecting the returned time, CENT, and CP columns lets the analyst compare the simulated state and concentration with their expected values.

Changing a Parameter and Interpreting the Effect

The parameterization also clarifies how clearance and volume enter the implemented model. Clearance and volume appear together in the rate \(CL/V\), while volume additionally converts amount to concentration. The following example changes clearance while holding dose and volume fixed; it is a direct simulation scenario, not a claim about a clinical intervention.

Diagnostics, Alternatives, and Limitations

A reliable implementation is checked at several levels, not merely by confirming that the software runs. First, inspect the model file for the intended parameter values and state name. Second, check the event amount, event time, and compartment assignment. Third, compare a few simulated values with the analytical solution. For this model, the initial post-bolus concentration is \(1000/50=20\) mg/L, and concentration must decline smoothly under positive clearance and volume. An output that increases, becomes negative, or has the wrong scale indicates a likely coding, event, parameter, or unit problem.

A useful additional check is dimensional. The ratio \(CL/V\) must have units of inverse time so its product with time can appear in an exponential. The derivative \(-(CL/V)CENT\) must have units of amount per time. If CP is intended as concentration, CENT/V must have units of amount per volume. These checks often expose a clearance or time-unit mismatch before it becomes a confusing plot.

A hand-calculated analytical solution is the most direct alternative for this simple model and is an excellent verification reference, but it is less flexible for models whose equations do not have a convenient closed form. An estimation-oriented model in software such as nlmixr2 serves a different workflow: it can represent models for fitting to data, whereas this mrgsolve example assigns fixed parameters and simulates from them. Translating a model between tools requires checking the model definitions and event meanings; similar-looking code does not by itself guarantee equivalent behavior.

This implementation is deliberately limited. It has one compartment, one instantaneous intravenous dose, no random effects, no residual error, no covariates, and no parameter estimation. It does not demonstrate infusion input, repeated dosing, or additional structural processes. Those features require their own model and event specifications; adding them without explicit definitions would change the model being simulated.