99  First Derivative Assessments (NM72, NM74)

Introduction to NONMEM 7.6.0

NONMEM 7.2.0 and higher versions normally calculates first derivatives in the FSUBS file for classical NONMEM methods, and does not evaluate them for IMP, SAEM, and BAYES methods. This improves the speed at which the problem is evaluated. However, on occasion such derivatives are needed, for example, when steady state values are to be calculated, or when stochastic differential equations are to be evaluated. In such cases, insert as the first line in a block of abbreviated code (such as $PK, $ERROR, $DES, etc):

FIRSTEM=1

Then, incidental derivatives will be evaluated for the new methods as well. For steady state and stochastic differential equation problems, FIRSTEM=1 needs to be inserted only at the beginning of the $DES block (when ADVANS 6,8,9,13,14,15 are used).

NMTRAN has been modified such that it collects all first derivative computations together, and performs them only if FIRSTEM=1. For example, in the PK subroutine, generated for ..\examples\example1.ctl:

   IF (FIRSTEM == 1) THEN
!                 A00033 = DERIVATIVE OF CL W.R.T. ETA(01)
   A00033=B00002
!                 A00038 = DERIVATIVE OF V1 W.R.T. ETA(02)
   A00038=B00004
!                 A00043 = DERIVATIVE OF Q W.R.T. ETA(03)
   A00043=B00006
!                 A00048 = DERIVATIVE OF V2 W.R.T. ETA(04)
   A00048=B00008
!                 A00051 = DERIVATIVE OF S1 W.R.T. ETA(02)
          A00051=A00038
          GG(01,1,1)=CL
          GG(01,02,1)=A00033
          GG(02,1,1)=V1
          GG(02,03,1)=A00038
          GG(03,1,1)=Q
          GG(03,04,1)=A00043
          GG(04,1,1)=V2
          GG(04,05,1)=A00048
          GG(05,1,1)=S1
          GG(05,03,1)=A00051
          ELSE
          GG(01,1,1)=CL
          GG(02,1,1)=V1
          GG(03,1,1)=Q
          GG(04,1,1)=V2
          GG(05,1,1)=S1
          ENDIF

Every effort has been made to assure that this new process by NMTRAN works for every type of model. However, it may occur that NMTRAN arranges the equations in the wrong order, and your problem may not work correctly, whereas it may have worked correctly in NONMEM 7.1.2 or earlier. Should this occur, the re-arrangement of equations by NMTRAN can be turned off by inserting

$ABBREVIATED NOFASTDER

in the control stream file. If the problem is resolved using this setting, please send your example control stream file to nmconsult, and we will fix the error for the next version.

As of nm75, another variable used to control derivative assessment is DES_DER, which should be placed in $PK:

$PK
…
DES_DER=1

and this will turn on first derivative assessment for the subsequent call to the DES subroutine ($DES block). This is required if it is desired that the Jacobian be analytically evaluated for ODE models (ADVAN8, 9, 13, 14, 15, 16, 17), for IMP, SAEM, BAYES problems that normally do not have first derivatives turned on.

The DES_DER maps to the MITER variable, and can be used in place of setting MITER to 1, as described in guide VIII, section “DIFF EQ SOLVER SETTINGS”.

For very large model problems, NMTRAN can take a long time to produce code and variable names of all of the first derivative components. As of NM74, If 1st derivatives are not required (such as when only simulations are performed, SAEM or BAYES is only performed, or IMPMAP/ITS/FOCE are performed using OPTMAP>0 and ETADER>0), then you can turn off analytical eta first derivative and other first derivative code production with

$ABBREVIATED DERIV1=NO

If this is set by the user, then NMTRAN will generate code that will insert

NOFIRSTDERCODE=1

in the PK, ERROR, PRED, and DES routines. This will inform NONMEM that analytical first derivative code is not available. This reserved variable is defined in the module NMPRD_INT. If a user is writing a user-defined PRED or PK routine in which analytical first derivatives will not be included, whether by NMTRAN, or by the user, the statement NOFIRSTDERCODE=1 should be inserted in the PRED routine.

Please note that any steady state evaluations requested, along with one of the ODE solver ADVANs (6,8,9,13,14,15) requires first derivatives, whether estimation or simulation.

Here are some estimation options that can be executed with no first derivatives.

$EST METHOD=SAEM … ; SAEM has no first derivative requiring components
$EST METHOD=BAYES… ; BAYES has no first derivative requiring components
$EST METHOD=IMP MAPITER=0… ; IMP uses derivatives in MAP
                                                 ; estimation on first iteration, unless MAPITER=0
$EST METHOD=ITS OPTMAP=1 ETADER=2… ; necessary derivatives can be
                                                               ; numerically determined
$EST METHOD=IMP OPTMAP=1 ETADER=2…
$EST METHOD=IMPMAP OPTMAP=1 ETADER=2…

METHOD=NUTS requires first derivatives.