8  Simulation sequence

This section is intended to help the user understand the steps mrgsolve takes when working through a simulation problem. The focus is on the order in which mrgsolve calls different user-defined functions as well as when parameter updates and output writing happens during the simulation sequence.

8.1 Functions to call

The model specification results in the definition of five functions that mrgsolve calls during the simulation sequence. Naming them by their code block identifiers, the functions are

  1. $PREAMBLE
  2. $MAIN
  3. $ODE
  4. $EVENT
  5. $TABLE

8.2 Problem initiation

Just prior to starting the problem (when NEWIND is equal to 0), mrgsolve calls $PREAMBLE.This function is only called once during the simulation sequence. The goal of $PREAMBLE is to allow the user to work with different C++ data structures to get them ready for the simulation run.

8.3 Subject initiation

After the $PREAMBLE call, mrgsolve simulates each ID in the data set, one after another. mrgsolve runs this sequence just prior to simulating a given ID

  1. Copy any parameters that are found in the idata_set to the working parameter list
  2. Copy any parameters that are found in the data_set to the working parameter list, with the copy being taken from the first actual data set row for that individual. If the first actual data set record in the data set is not the first record for the individual, mrgsolve still copies from the first data set record as long as the fillbak argument to mrgsim is TRUE.
  3. Set initial estimates from the base initial estimate list
  4. Copy initial estimates from idata_set if they are found there.
  5. Call $MAIN
  6. Start simulating the records for that individual

8.4 Sequence for a single record

mrgsolve executes this sequence while working from record to record for a given ID

  1. If nocb (next observation carried backward) is TRUE, then parameters are copied from the current record if that is an actual data set record. Note that if nocb is FALSE then locf (first observation carried forward) is assumed to be TRUE (see below). This is the last parameters will be copied from any input data set prior to advancing the system (when locf is being used). Therefore, when parameter columns are found in both an idata_set and a data_set, it will be the value found in the data_set that will overwrite both the base list and any parameter value that was copied from an idata_set. It is not an error to have different parameter values in an idata_set and a data-set, but the value found in the data_set will be used when this happens. More on parameters and the parameter update sequence can be found in Section 12.3 and Section 1.1.
  2. $MAIN is called
  3. The system is advanced via $ODE or $PKMODEL, whichever one is invoked in the model specification file.
  4. If the current record is a dosing record, the dose is implemented (e.g. bolus made or infusion started).
  5. If the system is advancing according to locf, then parameters are copied from the current record if that is an actual data set record. This is in contrast to nocb advance (see above).
  6. The $EVENT function is called
  7. The $TABLE function is called
  8. If the current record is marked for inclusion in the simulated output, results are written to the output matrix.
  9. Continue to the next record in the individual.
  10. Once the last record is processed in an individual, a new individual is started.