16 Modification of Execution
1 Version Identification
NONMEM is an evolving program, and changes are made from time to time. Version and level numbers together identify a particular instance of NONMEM. The first line of a NONMEM output report gives version and level numbers. These numbers identify the instance of NONMEM used to generate the output. As a result of implementing bug fixes that are announced in an email or newsletter, the level number is automatically changed.
In SIZES.f90 there is a level number given in a DATA statement similar to the following:
MODULE VERSION
CHARACTER(LEN=80) :: LEV
DATA LEV/'7.6.0'/ ! Version No.
END MODULE VERSIONDo not change this version number.
2 Bug Fixes in NONMEM 7.6
Bug fixes to NONMEM 7.6 will be issued to nmusers, and uploaded to https://nonmem.iconplc.com/nonmem760/nm760_bug_list.pdf
3 SIZES
Certain constants are used by NONMEM to control array and buffer sizes, and may be changed by the user, many of them by using the $SIZES record in their control stream file.
For permanent changes, values may be changed in SIZES.f90. Values that are changed in SIZES.f90 take affect after all the appropriate NONMEM source modules have been recompiled and, if a binary library is used, after the binary library has been rebuilt. Note that PREDPP and NM-TRAN Routines also use constants from SIZES. If you change a constant in SIZES, comments will tell you if other components of the NONMEM system should be recompiled.
Several of the constants in SIZES are of special interest.
3.1 Changing the Number of Theta’s, Eta’s, and Epsilon’s
LTH gives the maximum number of theta’s allowable. LVR2 controls the maximum number of eta’s permitted when the Laplacian Method is used.
The values in SIZES on the distribution medium are as follows.
PARAMETER (LTH=100)
PARAMETER (LVR=30)
PARAMETER (LVR2=20)NM-TRAN dynamically sizes LTH and LVR for you, which can be over-ridden by the user, by inserting the following line in the beginning of the control stream file, for example:
$SIZES LTH=150 LVR=60 LVR2=60Constants LTH, LVR, and LVR2 may also be permanently increased in SIZES.f90, but you should not decrease them.
3.2 Increasing the Number of Observations per Individual Record
As of NONMEM 7.3, the maximum number of observations for a given individual is assessed by NMTRAN. It is possible that the calculation may be inadequate. If this constant is not adequate, NONMEM will produce an error message such as the following.
TOT. NO. OF OBSERVATIONS IN INDIVIDUAL REC NO. 1 (IN INDIVIDUAL REC ORDERING)
EXCEEDS 250To increase this limit, add the following record as the first executable line in the control stream file:
$SIZES NO=500And re-run the problem again.
3.3 Changing the Size of Common NMPRD4 (LNP4)
Common NMPRD4 is used for communication between NONMEM and the PRED subroutine (and also for communication between user-supplied routines for PREDPP). To change its size, specifiy in the control stream file,
$SIZES LNP4=5000Or some other appropriate. Typically, users who write abbreviated code will consider making this change only when the following error message is produced by NM-TRAN:
288 SIZE OF NMPRD4 EXCEEDED; LNP4 IS TOO SMALL IN NMTRAN AND NONMEMWhen abbreviated code is not used, positions in NMPRD4 are assigned explicitly in user-supplied code. Users can determine for themselves if the common area is too small for their needs.
3.4 Changing the Size of NONMEM Buffers (LIMxx)
See Changing the Size of NONMEM Buffers in Introduction to NONMEM 7.6, nm760.pdf.
3.5 Increasing the Number of Mixture Models
Should NMTRAN fail to provide a sufficient size for number of mixture models, the size can be changed, by inserting the following line at the beginning of the control stream file:
$SIZES MMX=15Change the value MMX to the desired value.
3.6 Increasing the Number of Individual Records in the Data Set
See Changing the Size of NONMEM Buffers in Introduction to NONMEM 7.6, nm760.pdf.
3.7 Increasing the Max. No. of Points of Support with Nonparametric Estimate
With the Nonparametric method ($NONPARAMETRIC), the points of support are the posthoc estimates of each eta, which is essentially equal to the number of individuals in the data set. (An individual record has a value of the ID data item that is different from that of the previous individual record.)
This limit is set by constant LSUPP. If this constant is not adequate, NONMEM will produce an error message such as the following.
NONPARAMETRIC ESTIMATE NOT OBTAINABLE WHEN NO. OF INDIVIDUALS
EXCEEDS 4050Change the value LSUPP to the desired value.
$SIZES LSUPP=60004 Modifying System Action in the Event of Floating Point Exceptions
Floating point arithmetic (e.g., division by zero, overflow, or underflow) sometimes occur during a NONMEM run. See Users Guide V, Chapter 13, Section 4.5. The ANSI FORTRAN 95 standard does not specify what should happen when a floating point exception occurs. Consequently, each operating system and compiler takes a different action, ranging from an immediate abort of the program to continuation with no warning that such an event occurred. Some systems, however, permit the user to control the situation. We recommend that installers check the FORTRAN Users Guide or equivalent documentation for their system and learn how to give their users some means of controlling the actions taken by their system.
It is always safe to ignore floating point underflow, provided that the resulting value is set to zero; this is the default action specified by the IEEE 764 standard for floating point arithmetic. For other error conditions, the run should stop and produce as much diagnostic information as possible when an error occurs, so that the cause of the errors can be investigated. Second, if the user concludes that the errors are benign and are unavoidable, it should be possible for him to cause the errors to be ignored.
See Section 2.1.3 for code that can be used with Sun FORTRAN compilers.
With some compilers, a compiler option can be used to specify how floating point exceptions are handled. For example, with Intel Visual Fortran, we suggest the option
/fpe:0With Sun FORTRAN, we suggest
-fnonstdThese options request that the program stop if floating-point overflow, division by zero, or an invalid operation exception occurs. With Sun, the message “illegal instruction” appears. Both also request that underflow to zero occur for excessively tiny quantities.
If the compiler produces fatal error messages, or if you are concerned about warning messages, contact the NONMEM consultant. Do not attempt to fix the source code yourself! Phone at (301) 944-6807 or send e-mail to nmconsult@iconplc.com.
5 NONMEM Routines CRIT, MIX, PRIOR, CONTR, CCONTR, CONSTRAINT, USMETA, SPTWO
These are NONMEM dummy routines (“stubs”) that may be replaced by user-written subroutines. Specify the name of the routine on the $SUBROUTINES record, as in this example.
$SUBROUTINES .... MIX=subname ...NM-TRAN opens the file named “subname” and copies it to FSUBS.
Similarly, if the $MIX block of abbreviated code is present, then a generated code for MIX is present in FSUBS, or, if NM-TRAN Library routines are used, the NM-TRAN Library MIX routine must be included in the NONMEM executable.
Because NONMEM routines are obtained from a binary library (nonmem.a or nonmem.lib), the linker uses the MIX subroutine in FSUBS (or the NM-TRAN library) rather than the MIX routine from NONMEM.
6 PREDPP Routines, INFN, TRANS
These are PREDPP routines that may be replaced by user-written subroutines. Again, this is done by specifying the name of the routine on the $SUBROUTINES record, as in this example.
$SUBROUTINES .... INFN=subnameNM-TRAN opens the file named “subname” and copies it to FSUBS. The information in FREPORT causes NMLINK6 to omit PREDPP’s INFN routine from the list of files in LINK.LNK.
7 User Utility Routines
User-supplied routines and NM-TRAN verbatim code may contain calls to other user-supplied subroutines, which are referred to as user utility routines. Such routines may be included in the NONMEM executable module. First, they may be listed as OTHER routines on the $SUBROUTINES record, as in this example.
$SUBROUTINES .... OTHER=BSPLINENM-TRAN opens the file named “BSPLINE” and copies it to FSUBS. It is compiled and included in the NONMEM executable.
A second way permits pre-compiled routines or libraries to be included automatically. The OTHER option is not used. Instead, the nmfe76 shell script or nmfe76.bat batch file should be modified. Locate the line u= or set u=, respectively.
Two examples of how this line might be changed are given for UNIX, and two examples are given for MS-DOS:
UNIX:
set u="/.../.../mylib.a"
MSDOS:
Set u=BSPLINES.obj
set u="\...\...\mylib.lib"In the first examples, an object module BSPLINE is included in the NONMEM executable whether or not it is used in a given run. In the second example, /.../.../mylib.a stands for the full path of a binary library. Modules from this library are included only if actually called. In both nmfe76 and nmfe76.bat, the order presented to the linker is: nonmem library followed by user library or modules ($n \(u in UNIX and %n% %u% in MS-DOS).
As a result, the user utility routines cannot themselves call NONMEM utility routines such as CHOL or SUPP.
If they do call NONMEM routines, the order must be reversed (\)u $n in UNIX and %u% %n% in MS-DOS). This must be done with care because a routine in a user library having the same name as a NONMEM routine will be used instead of the NONMEM routine.
8 User Supplied Routines
Users may choose to substitute their own subroutines for certain default NONMEM-PREDPP routines, as follows:
NONMEM routines: CRIT, MIX, PRIOR, CONTR, CCONTR, CONSTRAINT, USMETA, SPTWO.
PREDPP routines: INFN and TRANS.
Users may also supply their own complete PK, ERROR, MODEL, DES, and AES sub-routines, rather than use NM-TRAN abbreviated code ($PK, etc.). They may also supply a TOL subroutine rather than supply a value on the $SUBROUTINES record.
NONMEM and PREDPP should be installed in such a manner that substitutions are possible.
Substitutions are specified to NM-TRAN on the $SUBROUTINES record. For example, if a user-supplied MIX routine is used with file name MIXUSER, the option MIX=MIXUSER appears on the $SUBROUTINES record. NM-TRAN uses such information in two ways:
Substitutions are documented in the FREPORT file, which contains a complete description of the composition of the NONMEM-PREDPP executable. All user-supplied subroutines are copied to file FSUBS, to help in the construction of the actual executable.
9 User Files
A user might supply a subroutine that requires I/O. FORTRAN logical units in the range 51-2000 may be used. If user files are output, it can be important to close them properly before the NONMEM run terminates. Use of the NONMEM utility FILES can help perform this function.
10 The Files Utility
Whenever a FORTRAN OPEN statement or a CLOSE statement is executed in a user-supplied routine, NONMEM should be informed. This should be done as follows. Immediately after the OPEN or CLOSE statement is executed, a call should be issued to a NONMEM utility subroutine called FILES. The form of the call is simply:
CALL FILES (IUNIT)where IUNIT is the number of the logical unit involved in the OPEN or CLOSE statement. When this is done, if a file is open when NONMEM terminates, the file is properly closed.
If reads or writes are issued to a given unit, but no OPEN statement for this unit is exe-cuted, then when ICALL is 0, a call to FILES should be issued (before any I/O statement.
11 NM-TRAN Include Lines
The NM-TRAN control file may contain one or more lines of the form
INCLUDE filenameThe file with name “filename” is an NM-TRAN include file. NMTRAN opens the include file, reads it to end-of-file and includes its contents in place of the INCLUDE record. The contents of the include file may be any portion of an NM-TRAN control stream: control records and/or abbreviated code.
12 Uninstalling NONMEM 7
NONMEM may be uninstalled with the following DOS command
rmdir /q /s nonmemdiror unix command:
rm –r nonmemdir