Stands for "common reserve". Variables defined in abbreviated codes are stored in MODULE NMPRD4. User-supplied Fortran routines may also store variables in NMPRD4. To differentiate these two sets of variables, the first n1 positions in NMPRD4 are reserved for the use of user-supplied routines. In other words, when both abbreviated code and user-supplied subroutines (or verbatim code) are used in a control stream, the user-supplied subroutine has the first n1 positions in NMPRD4 reserved for its use. The first position used by NM-TRAN for variables defined in abbreviated code is n1+1. Default n1=0 (no reserved storage).

• A special case n1=-1 requests no variables defined in abbreviated codes are stored in NMPRD4. This is used when one would like to avoid the default global scope of variables defined in abbreviated code. With COMRES=-1 the variables in the current abbreviated code block, e.g. $PK, is no longer accessible in other code blocks, e.g. $ERROR.
• Do not use this option when there are no abbreviated codes.

• Abbreviated code, verbatim code, $TABLE, and $SCATTER may explicitly reference variables in reserved positions using COM(I), I between 1 and n1. For example, in addition to output variables defined in abbreviated code by name, one can do

  1	$TABLE COM(1) COM(2)

When tables and scatterplots output certain variables, the values are copied from NMPRD4 in a copying pass. Normally with a given data record, values in NMPRD4 are computed with the previous data record. In order to access the values from the previous copying pass, one can use COMSAV=n2 to designate a SAVE array in NMPRD4 with initial size n2. A variable stored in the SAVE region has a persistent value from one copying pass to the next. Default n2=0. n2 may not exceed n1.

• The SAVE region has size n2 initially, but NM-TRAN may extend it if SAVE variables are used.
• n2=-1 requests no SAVE region used.
• See copying block and COMACT variable.

The option prevents the computation of first derivatives (setting the global variable NOFIRSTDERCODE to 1). For example, one may use the option when only SAEM or BAYES is performed, or IMPMAP/ITS/FOCE are performed using OPTMAP>0 and ETADER>0.

DERIV2=NO prevents the computation of second-order derivatives (needed only for the Laplacian method).

• When PREDPP is not used. DERIV2=NO makes the Laplacian estimation method requested in a subsequent run effectively a FOCE run. This is less efficient than a normal FOCE run and should be avoided.
• When PREDPP is used with DERIV2=NO, one cannot request the Laplacian estimation method in a subsequent run.

DERIV2=NOCOMMON permits the computation of these derivatives, but prevents them from being stored in the global variable NMPRD4. $ESTIMATION METHOD=COND LAPLACIAN may be specified, but variables representing second derivatives are not stored in NMPRD4. Therefore, they cannot be output in tables and scatterplots. In addition, no variables computed in the $PK block may be referenced in the $ERROR block. This is true whether or not these variables happen to have second derivatives, and whether or not the Laplacian method is used.

Code to compute first-partial derivatives with respect to ETA variables is always generated from abbreviated codes. These derivatives are almost always needed by classical NONMEM methods with population data. However, these derivatives are not necessary for the newer Bayesian methods. By default (FASTDER) NONMEM v7.2+ collects (re-arranges) all code for first derivative computation and use them only when needed (when IFIRSTEM=1, see partial derivative indicators). The collection (re-arrangement) of first derivative code can be prevented with option NOFASTDER.

By default (CHECKMU) NONMEM v7.2+ checks the MU model statements in abbreviated code for potential errors. This check can be either time consuming for large control streams or too difficult/error-prone to perform (see examples/tdist6_sim and examples/tdist7). In such cases NOCHECKMU can be used to disable the check.

• DES=FULL: Arrays of the DES routine are stored in non-compact form. With $ESTIMATION METHOD=COND LAPLACIAN, the option NUMERICAL is also required. DES=FULL is the default with ADVAN9 and ADVAN15 and ADVAN17. (Prior to NONMEM 7.4, FULL was required with ADVAN13.)
• DES=COMPACT: Arrays of the DES routine are stored in compact form. Required with Laplacian method; optional otherwise. This is the default, except with ADVAN9 and ADVAN15 and ADVAN17.

1

REPLACE left_string = right_string

There are several different forms of the REPLACE option. They do not affect verbatim code.

When $ABBR REPLACE is coded, NM-TRAN produces two files: FORIG contains the original (pre-replacement) abbreviated code, and task specification records $TABLE and $SCATTER. FREPL contains the new (post-replacement) abbreviated code and task specification records.

1
2
3
4
5
6
7

  $ABBR REPLACE PI=3.14159265
  $ABBR REPLACE THETA(CL)=THETA(4)
  $ABBR REPLACE ETA(CL)=ETA(5)
  $ABBR REPLACE K34="3,4"
   ...
  CL=PI*THETA(CL)*EXP(ETA(CL))
  PRINT *,OMEGA(K34)

1
2

  CL=3.14159265*THETA(4)*EXP(ETA(5))
  PRINT *,OMEGA(3,4)

1
2
3
4
5

  $ABBR REPLACE A(DEPOT)=A(1)
  $ABBR REPLACE DADT(DEPOT)=DADT(1)
    ...
  $DES
   DADT(DEPOT)=-KA*A(DEPOT)

1

  $ABBR REPLACE VAR(d)=VAR(n1,n2,..,nk)

1
2
3

  IF (d==1) VAR(d)=VAR(n1)
  IF (d==2) VAR(d)=VAR(n2)
   ...

1
2
3
4

$ABBR REPLACE THETA(OCC)=THETA(4,7)
  ...
$PK
TVCL=THETA(OCC)

1
2

IF (OCC==1) TVCL=THETA(4)
IF (OCC==2) TVCL=THETA(7)

1
2
3
4

  $PK ...
     IF(DOSN.EQ.1) F1=1
     IF(DOSN.EQ.2) F1=1*EXP(ETA(2))
     IF(DOSN.EQ.3) F1=1*EXP(ETA(3))

1
2
3
4

$ABBR REPLACE ETA(DOSN)=ETA(0,2,3)
$PK ....
  F1=1
  IF (DOSN>1) F1=1*EXP(ETA(DOSN))

1

  $ABBR REPLACE VAR(p_d)=VAR(n1,n2,..,nk)

1
2
3
4
5
6

  $ABBR REPLACE THETA(SID_KA)=THETA(4,6)
  $ABBR REPLACE THETA(SID_CL)=THETA(5,7)
     ...
  $PK
  KA=THETA(SID_KA)
  CL=THETA(SID_CL)

1
2
3
4
5

  $PK
  IF (SID==1) KA=THETA(4)
  IF (SID==2) KA=THETA(6)
  IF (SID==1) CL=THETA(5)
  IF (SID==2) CL=THETA(7)

1
2
3
4
5
6

  $ABBR REPLACE ETA(OCC_CL)=ETA(5,3)
  $ABBR REPLACE ETA(OCC_V) =ETA(6,4)
     ...
  $PK
  CL=TVCL*EXP(ETA(1)+ETA(OCC_CL))
  V =TVV *EXP(ETA(2)+ETA(OCC_V))

1
2
3
4
5

  $PK
  IF (OCC==1) CL=TVCL(EXP(ETA(1)+ETA(5))
  IF (OCC==2) CL=TVCL(EXP(ETA(1)+ETA(3))
  IF (OCC==1) V=TVV(EXP(ETA(2)+ETA(6))
  IF (OCC==2) V=TVV(EXP(ETA(1)+ETA(4))

1

      $ABBR REPLACE VAR(p1,p2,...,pk)=VAR(n1,n2,...,nk)

1

  $ABBR REPLACE THETA(CL,V1,Q,V2)=THETA(1,2,3,4)

1
2
3
4

  $ABBR REPLACE THETA(CL)=THETA(1)
  $ABBR REPLACE THETA(V1)=THETA(2)
  $ABBR REPLACE THETA(Q)=THETA(3)
  $ABBR REPLACE THETA(V2)=THETA(4)

1

, start TO end [BY interval]

1
2
3

  $ABBR REPLACE THETA(SID_KA)=THETA(10:4 by 3) ; order: 10,7,4
  $ABBR REPLACE THETA(SID_KA)=THETA(4 to 10 by -3) ; order: 10,7,4
  $ABBR REPLACE THETA(SID_KA)=THETA(10 to 4) ; order: 10,9,8,7,6,5,4

1

  $ABBR REPLACE THETA(SID_KA)=THETA(,4 to 13 by 3,25 to 37 by 4)

1

  $ABBR REPLACE THETA(SID_KA)=THETA(4,7,10,13,25,29,33,37)

1
2

  ;! Usage
  DECLARE [INTEGER] [DOWHILE] name [(dimension [,dimension])] ...

One or more variable names may be declared using the $ABBR DECLARE statement.

• Variable types. DECLARE ... INTEGER and DECLARE ... DOWHILE (for DOWHILE loop indices only) declare integers that can serve as indices of arrays. Otherwise declared variables are double precision reals, and they become random variables if assigned from an expression involving ETA or EPS.

• Arrays. One and two dimensional array can be declared using parentheses. The dimension can be a constant, variable, or expression (including SIZES constants like NO or LVR). For example

  1	$ABBR DECLARE A,B(10),C(1,NO-1),INTEGER I J ;# only I is INTEGER.

• Initialization. All declared variables are initalized (or filled) with 0.
• Multiple $ABBR DECLARE are allowed. After the first the DECLARE keyword is optional and declarations are comma- or space-separated. No other $ABBR options may follow DECLARE option(s).
• Declared variables have global scope, thus they are available in abbreviated code blocks.

• Output. Elements of a declared array may be displayed in WRITE/PRINT statement using indices.

  1 2	PRINT *,B(1),B(2) ;! allowed PRINT *,B ;! not allowed

  They cannot be output by $TABLE. The workaround is to code, e.g.,

  1 2 3

  ;#... code assigning values to B(1) etc. ... B1=B(1) $TABLE B1

In NONMEM v7.4+, a series of routines are available that protect against domain violations, divide by zero, and floating point overflows. Each of these routines start with the letter P, followed by the name of the mathematical operation they are to perform. For example, PLOG is the protective code routine that performs the LOG operation. In addition, there are first derivative (such as PLOGD1), and second derivative (such as PLOGD2) companion routines available which NMTRAN uses for computing analytical derivatives. The source code of these routines are available in source/PROTECT.f90. If you wish to modify their behavior, then copy PROTECT.f90 to your run directory as (say) myprotect.f90, modify it, then refer to this modified code with

1

$SUBROUTINES OTHER=myprotect.f90

The OTHER option is not needed if the P functions are coded explicitly or implicitly via $ABBR PROTECT.

The following protective code routines are available. For all routines, if x=NAN, x is converted to machine precision value first. If x>INFNTY (Double pecision INFNTY is approximately 1.0E+154), then x is converted to INFNTY first. SMALLZ denotes the small positive floating point number limit (approximately 2.8E-103).

The option

1

$ABBR PROTECT

requests automatical replacement of functions with the protect counterparts.

Note that the any P function name that is used explicitly or implicitly via $ABBR PROTECT may not be used for a user-defined variable name.

1
2

; Usage
$ABBR FUNCTION function_name(input_vector_name,dimension[,usage])

User-supplied functions are permitted in abbreviated code with reserved names such as FUNCA, FUNCB, etc., and argument vectors with reserved names VECTRA, VECTRB, etc. NONMEM v7.4+ supports extended reserved names FUNCxy and FUNCxyz, with each of x, y, z as an alphabetic character A-Z, so that FUNCAB or FUNCABC are supported. Similarly for vector names VECTRAB, VECTRABC, etc. are supported. Reserved argument vectors and arrays have dimension 9 and each reserved function may appear in abbreviated code at most 9 times. (See abbreviated functions).

NONMEM v7.4+ supports $ABBR FUNCTION for user-defined function and argument vector declaration:

1

  $ABBR FUNCTION function_name(input_vector_name,dimension,usage)

• function_name: the name of the function.
• input_vector_name: the name of an input vector that may be used to pass arguments to the function.
• dimension: the length of input_vector_name. It is a property of both the function and of the input vector.
• usage: the maximum number of times the function may appear in the abbreviated code, that is, the maximum number of occurances of function_name. It is not an error if there are fewer occurances. If usage is omitted, NMTRAN will supply the exact number. If usage is coded, NMTRAN will generate an error message if function_name appears in abbreviated code more than "usage" number of times.

In addition a vector and its length may be declared separately:

1

  $ABBR VECTOR input_vector_name (dimension)

For example,

1

  $ABBR FUNCTION BIVARIATE(VBI,5,3)

defines VBI as a vector of length 5, to be used as the argument of function BIVARIATE. When BIVARIATE is defined, the value 5 is passed to its argument NDIM. Function BIVARIATE may appear in abbreviated code at most 3 times. BIVARIATE should be specified in a source code file listed in the $SUBROUTINES record:

1

  $SUBROUTINES OTHER=filename

so that one can use it in abbreviated code:

1
2
3
4
5
6
7
8
9

  $PK ...
  VBI(1)=RHO
  VBI(2)=5
  VBI(3)=6
  VBI(4)=1 ;#  0 = Upper tail as in Drezner & Wesolowsky
           ;#  1 = Bottom tail;
  VBI(5)=1 ;#  0 = 3 pt approximation
           ;#  1 = 5 point approximation;
  BV=BIVARIATE(VBI)

See examples/bivariate for the full example.

By default, there may be up to 100 different user-defined functions, which includes functions with reserved names and userdefined names. There may also be up to 100 different vectors of input arguments, which includes vectors with reserved names and user-defined names. Constants NFUNCX and NVECX in SIZES may be used to change these numbers.

It is preferable that a unique vector should be associated each function to assure that each vector-function pair are set up with comparable dimensions. This is not necessary. Any user-defined vector or function may be used with any reserved vector or reserved function, subject to the same restriction. For example:

1
2

  $ABBR FUNCTION BIVARIATE(VBI,5)
  $ABBR FUNCTION BIVARIATEQ(VQI,10)

In abbreviated code, any of the following are permitted:

1
2
3
4

  BVI=BIVARIATE(VBI)
  BVQ=BIVARIATE(VQI)
  BVQI=BIVARIATEQ(VBI)
  BVQQ=BIVARIATEQ(VQI)

NM-TRAN would give a warning:

1
2
3

(WARNING  133) DIMENSION OF VECTOR IS LESS THAN
               WHAT IS EXPECTED BY FUNCTION
BVQI=BIVARIATEQ(VBI(001),FNC002_1(1,001),FNC002_2(1,1,001),10)

This is because vector VBI has dimension 5 and function BIVARIATEQ was declared with dimension 10.

A vector and its length may be declared independently of a function, and vice versa. The asterisk is used as a placeholder, e.g.,

1
2
3
4
5

  $ABBR FUNCTION BIVARIATE(*,5)
  ;# when BIVARIATE is called, NDIM will be 5
  $ABBR FUNCTION BIVARIATEQ(*,10)
  ;# when BIVARIATEQ is called, NDIM will be 10
  $ABBR VECTOR VQI(15)

The $ABBREV FUNCTION record may be used to override the default settings for any of the reserved function or vectors. For example,

1

  $ABBR FUNCTION FUNCA(VECTRA,25,5)

VECTRA will be defined with length 25, not 9 as for a reserved function. The code for the function should have NDIM as an argument:

1

  FUNCTION VECTRA(X,X1,X2,NDIM)

NDIM should be used instead of 9 for vector and array dimensions.