FORTRAN-77 compiler
reportsChapter III - How to Install and Test NONMEM
This chapter describes how to install and test NONMEM itself. It is convenient, but not necessary, to work in a disk area reserved for this purpose. In UNIX, for example, you might work in a dedicated directory called (say) /export/home/nmvi/nm. In MS-DOS, you might work in a dedicated directory called (say) c:\nmvi\nm.
It is assumed that you have already read the source code for single or double precision NONMEM into a disk file, as shown in Appendix 3. It is also assumed that you have already read file SIZES from the NONMEM distribution medium ("SIZES") into the same directory.
SIZES is a FORTRAN include file. It is inserted into the NONMEM source modules by the compiler in response to INCLUDE statements in the source code. With NONMEM VI, the format of the INCLUDE statements is
INCLUDE ’../SIZES’
This specifies that the file SIZES in the directory above the current directory should be used. The format of the INCLUDE statement is the same for all components of the NONMEM system (NONMEM, PREDPP, NM-TRAN, NM-TRAN library routines.) Since each component is installed in its own directory immediately below the NONMEM VI directory "nmvi", they all use the same SIZES file. As a result, a constant that is used in more than one component needs to be changed only once, although each component that uses the constant will have to be recompiled.
After it has been read to disk it must be given the name SIZES with these exceptions:
For IBM CMS, the file must be named SIZES FORTRAN A For VAX/VMS and OpenVMS, the file must be named SIZES.FOR For Watcom FORTRAN 77 and PC DOS, the file must be named SIZES.for |
This chapter guides you through the following steps:
|
1. |
Separate the file into smaller files (Optional). |
|
2. |
Make any required changes to the source code. |
|
3. |
Compile NONMEM and build a binary library. |
|
4. |
Create a simple test case. |
|
5. |
Build a NONMEM executable and run the test case. |
The single large NONMEM file, as read from the distribution medium, consists of 178 separate subroutines. They are arranged in alphabetical order. You may choose at this time to separate the single large file into smaller files, for the following reasons:
|
• |
You may have to modify the NONMEM source code before compiling it and the single large file may be too large for your system’s editor. |
|
• |
When bugs are found in NONMEM, the fixes are described via email to NONMEM users and technical newsletters. Sometimes, replacement subroutines are supplied. You must modify the individual subroutines and recompile portions of NONMEM. It is faster and less costly to do this when the file has been separated. |
|
• |
Advanced users of NONMEM may choose to substitute their own FORTRAN subroutines for certain NONMEM dummy subroutines. It is easier to do this when the file has been separated. |
A disadvantage to separating the source files is that some compilers, e.g., Microsoft FORTRAN 5.1, do not allow easy specification of large numbers of object modules when the linker is invoked. Similarly, for VAX/VMS and OpenVMS, the compiler does not allow easy specification of large numbers of source modules, and the procedure described in 1.1 following should be used. If none of the above considerations apply, it is reasonable to compile the single large source file. Only one object module will then be created.
Locate an END statement approximately half way through the file and split the file there using system utilities such as the CMS COPY command. You may do this as often as necessary to reduce the size of the resulting files, being careful to split the files after END statements. Subroutines CCONTR, CONTR, CRIT, INLETA, MIX, PRIOR, SPTWO, USMETA should be placed in separate files to allow easy replacement by user-supplied versions, especially in the UNIX environment. (These subroutines are "dummy", or "stub", routines which can be replaced by user-written code in advanced applications of NONMEM.)
For VAX/VMS and OpenVMS, put the NONMEM main program (from the line starting CDNONMEM through the END statement that precedes CDNORAN) in a file NONMEM.FOR, and the block data routine (from the line starting CDBLKDAT through the END statement that precedes CDCCONTR) in a file BLKDAT.FOR, and leave the remainder in file NMD.FOR.
Alternately, you may choose to separate the NONMEM source file into 178 separate files corresponding to the 178 separate FORTRAN subroutines. This can be done easily using FORTRAN utility program SEP which can be read from file "SEP" of the distribution medium. SEP also strips trailing blanks from each line of source code, which reduces the disk space occupied by the individual source files on some operating systems.
PROGRAM SEP
CHARACTER*80 IREC
LOGICAL OPEN
OPEN=.FALSE.
10 READ (5,800,ERR=20,END=30) IREC
800 FORMAT (A)
IF (IREC(1:2).EQ.’CD’) THEN
IF (OPEN) CLOSE(3)
I=INDEX(IREC,’ ’)
C NEXT STATEMENT FOR MS-DOS AND VAX-VMS AND MANY UNIX SYSTEMS
IREC(I:)=’.for’
C NEXT STATEMENT FOR SOME UNIX SYSTEMS
C IREC(I:)=’.f’
I=INDEX(IREC,’ ’)
OPEN (3,FILE=IREC(3:I))
REWIND 3
OPEN=.TRUE.
GO TO 10
ENDIF
DO 40 I=80,1,-1
IF (IREC(I:I).NE.’ ’) GO TO 50
40 CONTINUE
50 WRITE (3,800) IREC(1:I)
GO TO 10
C ERROR TERMINATION
20 STOP 4
C NORMAL PROGRAM TERMINATION
30 STOP
END
A special version, SEPG77, is used by
CDSETUP6.BAT when the g77 or g95 compiler is specified in
the MS-DOS environment. In addition to the usual
functionality, SEPG77 also makes some code changes that are
difficult to implement within CDSETUP6.BAT. (In particular,
SEPG77 eliminates the call to COMMITQQ from the FLU routine,
and modifies file names in BLKDAT from
1/’nul’,’con’,’PRDERR’,’INTER’,’nul’/
to
1/’nul’,’CONOUT$’,’PRDERR’,’INTER’,’nul’/’
as discussed in Section 2.2.)
IMPORTANT: The SEP program appends the characters ".for" to the end of each FORTRAN source file’s name, to conform with the file-naming convention of many operating systems, including MS-DOS, VAX/VMS, OpenVMS, and Sun UNIX.
With CMS, inactivate this line by placing "C" in column 1.
C IREC(I:)=’.for’
It is possible that some Fortran compilers may require a different extension. If you cannot compile "sep.for" in the next step, but must rename the file in order to compile it (e.g., to "sep.f"), then inactivate the line IREC(I:)=’.for’ by placing "C" in column 1 and activate the line IREC(I:)=’.f’ by replacing "C" in column 1 with a blank. Or, change the extension ".for" to the appropriate characters. Remember to change the extension whenever it appears in the coding examples in this guide.
You will use the SEP program several times to separate various files. Compile the program and save the SEP executable for reuse.
If you are unable to compile and run SEP, see the readme file on the distribution medium for advice on problems that are due to an incorrect Fortran installation or configuration.
|
UNIX: |
mv sep sep.f f77 -o sep sep.f
|
MS-DOS: |
rename sep sep.for fl32 sep.for
|
CMS: |
FORTVS SEP
The input file, read from unit 5, is the single large file as read from the distribution medium. If use of unit 5 causes a problem with an operating system, the unit number should be changed to some other value such as 8. For MS-DOS, assume that the file to be separated is called nmd. For UNIX, assume that the file to be separated is called NMD. For CMS, NMD FORTRAN A. If you are working with the single precision version, you may have given the file the name nms or NMS FORTRAN A. With SEP, each output file is given the same name as the subroutine it contains.
|
UNIX: |
sep < NMD
|
MS-DOS: |
sep < nmd
|
CMS: |
FILEDEF 5 DISK NMD FORTRAN A LOAD SEP ( START
For certain operating systems, the resulting separate files may need further modification. For example, in CMS each file may have to be renamed from "FILE xxxxx A" to "xxxxx FORTRAN A". Here is an easy way to do this in CMS.
|
CMS: |
Make a file called REN EXEC A containing
the statement:
RENAME &1 &2 A &2 FORTRAN
A
Input the following commands:
LIST FILE ( EXEC RENAME CMS EXEC A NMD EXEC A NMD EXEC REN
The file NMD EXEC A contains the names of all NONMEM subroutines. It is used again later.
Once the single large file has been separated, you may choose to erase it from disk to save space.
You now may need to make certain changes to NONMEM source code. Changes to BEGIN, BLKDAT and FLU are required for almost all systems other than Microsoft Windows with Microsoft PowerStation Fortran. The other changes are optional. Some reflect problems special to I/O on certain operating systems. You can wait to apply these optional changes until after you have attempted to compile and run NONMEM. If no problems occur, do not make the changes.
BEGIN is a user-installation routine. It is called with the first executable statement of the NONMEM program. It allows the user to cause NONMEM to execute statements needed with certain operating systems. Here are some examples of such statements.
NONMEM reads control information from FORTRAN unit 5 and writes its output report to FORTRAN unit 6. Some operating systems (e.g., CTSS and Microsoft Windows 3.0) require that units 5 and 6 be explicitly opened within the program. On some platforms (e.g., Microsoft Fortran 5.1 running under OS/2) unit 5 must be explicitly opened to avoid an illegal rewind command on unit 5. Although with Microsoft Fortran PowerStation and DIGITAL Visual Fortran, units 5 and 6 need not be explicitly opened, there are advantages to doing so.
Accordingly, the BEGIN routine on the distribution medium contains the following code:
SUBROUTINE BEGIN
OPEN (5,FILE=’FCON’)
REWIND 5
OPEN (6,FILE=’OUTPUT’)
REWIND 6
RETURN
END
Prior to each run, copy the NONMEM control stream to a file named FCON. (Users of NM-TRAN will not have to do this because NM-TRAN gives this name to the NONMEM control stream which it creates.) After each run, rename file OUTPUT as desired. Be sure to do so or the contents of the file will be re-written in the next run!
Operating systems such as CMS and UNIX "preconnect" units 5 and 6; examples of how to make use of these preconnections are given in Section 4.3 of this chapter. With these operating systems, units 5 and 6 need not be explicitly opened by NONMEM. Use your operating systems’ editor to make the above statements inactive by placing the character ’C’ in column 1:
C OPEN (5,FILE=’FCON’) C REWIND 5 C OPEN (6,FILE=’OUTPUT’) C REWIND 6
This change is made for you automatically by the Unix SETUP utility provided on the NONMEM installation CD.
With VAX/VMS and OpenVMS, change the second OPEN statement to:
OPEN (6,FILE=’OUTPUT.LIS’,CARRIAGECONTROL=’LIST’)
Additional control information may be necessary within the OPEN statements, depending on the operating system. More complicated code can be devised.
NONMEM requires more than 20 files to be
open during a run. A user with SVS
FORTRAN-77 compiler
reports
that this instruction is needed to allow more than 20 open files:
I=_INIT_HANDLE_COUNT(%VAL(50))
A user with Watcom FORTRAN 77 suggests these instructions:
INCLUDE ’FSUBLIB.FI’
INTEGER NEW_LIMIT
NEW_LIMIT=GROWHANDLES(60)
Such instructions can be placed in BEGIN.
See Section 4.4 below for the MS-DOS equivalent.
Some operating systems (e.g., Sun UNIX) permit a special call at the start of program execution in order to modify the action taken by the operating system in the event of floating point exceptions (see Section 2.1.3 and 2.10); such calls can be placed in BEGIN.
Code that can be used with Sun FORTRAN compilers follows:
i=ieee_handler("set","common",SIGFPE_ABORT)
This requests that the program stop with the message "illegal instruction" if floating-point overflow, division by zero, or an invalid operation exception occurs.
Another way to achieve this is by use of the Fortran compiler option "-fnonstd", which requests "Abort on exceptions". This option is recommended for Unix installations in the readme file (see Section 2.10).
BLKDAT is a FORTRAN block data routine assigning certain NONMEM file names and values to machine-dependent constants. The names and values appearing in the data statements of this routine on the distribution medium are appropriate to a machine with INTEL floating point architecture and running in an MS-DOS window under Microsoft Windows (e.g., 95 and XP). Changes may be required for all other types of computers and operating systems. The UNIX installation utility SETUP makes these changes automatically.
The following DATA statement stores the character strings ’nul’, ’con’, and ’nul’, respectively, in character variables FNSTP, FNINT, and FNULL, the character string ’PRDERR’ in character variable FNERR, and the character string ’INTER’ in character variable FNINTR, thus assigning certain file names.
DATA FNSTP,FNINT,FNERR,FNINTR,FNULL 1/’nul’,’con’,’PRDERR’,’INTER’,’nul’/
The file names are used in FORTRAN OPEN statements. Character values ’nul’ have the effect of suppressing the output to the files FNSTP and FNULL. Character values ’con’ have the effect of directing output to FNINT to the terminal. Character values may have to be changed for other operating systems. Here are some examples:
|
With UNIX, change both ’nul’ and ’con’ to ’/dev/null’. The statements will then be as follows: DATA FNSTP,FNINT,FNERR,FNINTR,FNULL 1/’/dev/null’,’/dev/null’,’PRDERR’,’INTER’,’/dev/null’/ This is done automatically by the Unix SETUP utility. However, if the gfortran compiler is used (e.g., with Linux), then there is a run-time error if /dev/null is opened more than once, and the statement should be changed to DATA FNSTP,FNINT,FNERR,FNINTR,FNULL 1/’/dev/null’,’con’,’PRDERR’,’INTER’,’/dev/null’/ This is also done automatically by the Unix SETUP utility. With the g77 and g95 compilers (which can be used with Windows), the statement should be changed to 1/’nul’,’CONOUT$’,’PRDERR’,’INTER’,’nul’/’ This is done automatically by SEPG77. SEPG77 is used instead of SEP by CDSETUP6.BAT when the g77 or g95 compiler is used. With some compilers (e.g., MIPSpro Compiler Version 7.20 and HP-UX FORTRAN) there may be a run-time error referring to FORTRAN Unit 34. If so, the statements should be changed as follows, and the contents of JUNKFILE should be ignored: DATA FNSTP,FNINT,FNERR,FNINTR,FNULL 1/’/dev/null’,’/dev/null’,’PRDERR’,’INTER’,’JUNKFILE’/ With PC-DOS, change ’nul’ to ’nul:’. With NDP FORTRAN, change ’nul’ to ’NUL’. With VAX/VMS, change ’nul’ to ’NLA0:’. With CMS, change the character values to ddnames which can be assigned to DUMMY (or TERMINAL, if you wish to see this output) using the FILEDEF command. E.g.,: DATA FNSTP,FNINT,FNERR,FNINTR,FNULL 1/’FILE1’,’FILE2’,’PRDERR’,’INTER’,’FILE3’/ |
FNSTP contains the name of a file for the FORTRAN STOP message. This file is opened only when certain changes are made to subroutine CFILES, as described in section 2.5. If these changes are made, be careful to place in FNSTP only the name of the terminal output file or the name of a dummy file.
FNINT contains the name of a special file for intermediate output from the Estimation Step. The Estimation Step, which performs the search for the parameter estimates, can take a long time. NONMEM users can request that intermediate output be produced so that the progress made during the search can be evaluated. If this output can be observed while NONMEM is running, users can choose whether or not to allow a long-running job to continue. Intermediate output is normally written to two files: the output report and the special file whose name is found in FNINT. When NONMEM runs on an interactive system, there are two reasons to use the special file:
|
• |
With a single-tasking operating system such as CMS, there is no way to see the output report file until the run terminates. The special file can be assigned to the terminal, giving the user a "window" on the progress of the search. |
|
• |
With a multi-tasking operating system such as UNIX, NONMEM can be run in the background, and the output report can be examined while NONMEM is running. If the system uses a large buffer size, the contents of the report file on disk may lag far behind the lines actually written by the program. The special file can be assigned to an unbuffered file (such as the terminal), again providing more timely information. |
With MS-DOS and Microsoft FORTRAN, FNINT might contain one of the following to display the intermediate output on the console or in a window: ’ERR’ (if no windowing system is used), ’USER’ (with QuickWin), or ’con’ (with Windows 3 or Windows 95) (this is the default).
With MS-DOS and SVS
FORTRAN-77, FNINT might
contain ’CON’.
FNERR contains the name of a file for
error messages from the PRED subroutine, the PRED Error
File. By default, the name of the file is PRDERR. NONMEM
writes to this file only if the PRED subroutine returns an
error code indicating an abnormal condition in PRED. This
file should never be suppressed. NONMEM users should always
carefully review its contents after every run in which the
final line of the output report states:
THERE ARE ERROR MESSAGES IN FILE PRDERR
If the name of the file is changed, be careful not to change
it to the name of any other file used in a NONMEM
run.
FNINTR contains the name of a file in which iteration estimates are printed at each iteration of the Estimation Step in the original parameterization, the Intermediate Estimates File. By default, the name of the file is INTER. NONMEM writes to this file only for those iterations whose summaries appear in intermediate output, and only when a MSFO is used. The file exists only during the duration of the run.
FNULL contains the name of the Null file. FNULL must be set to the name of the device for junk output.
NONMEM uses 25 work files. This should be essentially transparent to the user. Names for these files are placed in character variables FN07 and FN10-FN37 by the following DATA statements:
DATA FN07,FN10,FN11,FN12,FN13,FN14,FN15,FN16/’FILE07’,’FILE10’, 1’FILE11’,’FILE12’,’FILE13’,’FILE14’,’FILE15’,’FILE16’/ DATA FN17,FN18,FN19,FN20,FN21,FN22,FN23,FN24,FN25,FN26,FN27 1/’FILE17’,’FILE18’,’FILE19’,’FILE20’,’FILE21’,’FILE22’,’FILE23’, 2’FILE24’,’FILE25’,’FILE26’,’FILE27’/ DATA FN31,FN32,FN33/’FILE31’,’FILE32’,’FILE33’, 1’FILE35’,’FILE36’,’FILE37’,
FN28-30 (FILE28-FILE30) and FN34 (FILE34) are not used in NONMEM VI 1.0.
The names FILE07, FILE10, FILE11, etc., are used in FORTRAN OPEN statements. If these names are not acceptable to your operating system, or if other names are preferred, the character values ’FILE07’ etc. should be changed.
NONMEM subroutines use certain machine dependent constants. They are:
|
REPS |
Machine Precision. This is the smallest floating point number representable in the machine such that when it is added to 1, the resulting sum is not 1. |
|
TOL |
Machine Tolerance. This is the smallest floating point number representable in the machine, divided by machine precision. |
LARGE
|
Machine Infinity. This is the largest floating point number representable in the machine. |
|
EPS |
Mantissa length. This is the number 2**(-m), where m is the number of binary digits occurring in the floating point mantissa. |
SREPS
|
Same as REPS, but always single precision. |
|
STOL |
Same as TOL, but always single precision. |
|
ILG |
The largest single precision number representable in the machine. |
In single precision NONMEM, these six numbers are represented as integer values in the integer variables IREPS, ITOL, LARGE, IEPS, ISREPS, ISTOL.
In double precision NONMEM, double precision versions of REPS, TOL, and LARGE are placed as pairs of integer values in two-dimensional integer arrays IREPS, ITOL, and LARGE. Single precision versions of EPS, SREPS and STOL are placed as integer values in the integer variables IEPS, ISREPS, and ISTOL. ILG is placed as an integer value in the integer variable ILG.
The integer values in BLKDAT are made equivalent via FORTRAN EQUIVALENCE statements to floating point variables of the appropriate precisions.
The DATA statements in the BLKDAT routine on the distribution medium contain values appropriate to the INTEL architecture for floating point numbers. DATA statements appropriate to certain other computer architectures are also coded in BLKDAT, but they are made inactive by the presence of the character ’C’ in column 1. Both single and double precision versions of BLKDAT contain constants for IEEE, VAX, and IBM mainframe chip. The single precision version of BLKDAT also contains constants for CRAY X-MP, Y-MP and C90, and for CYBER 205.
To activate the constants for an architecture other than INTEL, proceed as follows. First, place ’C’ in column 1 of both DATA statements for INTEL architecture, including continuation lines (which have "1" in column 6). Second, replace ’C’ with ’ ’ (space) in column 1 of the DATA statements for your computer’s architecture, including continuation lines. For example, if double precision NONMEM is being installed and VAX constants are desired, change the relevant lines to appear as follows:
*
* VAX CONSTANTS
*
DATA IREPS,ITOL,LARGE,IEPS/9472,0,7168,0,
1 -32769,-1,13440/
DATA ISREPS,ISTOL,ILG/13568,3072,-32769/
.
.
.
*
* INTEL CHIP CONSTANTS
*
C DATA IREPS,ITOL,LARGE,IEPS/0,1018167296,0,55574528,
C 1 -1,2146435071,864026624/
C DATA ISREPS,ISTOL,ILG/872415232,201326592,2139095039/
The choices of BLKDAT constants may be
described as follows:†:
----------
|
VAX |
Refers to any machine implementing the VAX D_floating data type for REAL*8 quantities. For the purposes of running NONMEM, where the number of binary digits in the mantissa of a floating point number is more important than the number of binary digits in its exponent, the D_floating data type, rather than the G_floating data type, should be used, providing the former is implemented in hardware rather than software. If the VAX G_floating data type is preferred, use the following constants: |
DATA IREPS,ITOL,LARGE,IEPS/13968,0,832,0,
1 -32769,-1,13440/
DATA ISREPS,ISTOL,ILG/13568,3072,-32769/
|
|
IEEE |
Refers to any machine implementing the IEEE standard for floating point data representation (e.g., Sun2, Sun3, Sun4, Sparc, Silicon Graphics, Macintosh II and Power PC, HP, and many other computers). |
The constants are the same as INTEL constants, but the order of the double precision word is different. The UNIX SETUP utility changes INTEL constants to IEEE constants by default. The argument "intel" may be specified to leave the constants unchanged, e.g., when using Linux on a PC.
Do not use these constants for the CRAY T90.
IBM MAINFRAME
|
Refers to any machine implementing IBM 370 internal floating point data representation (e.g., IBM 370, 4341, 3081, or AMDAHL mainframes, or Data General Eclipse MV type machines). |
INTEL CHIP
|
Refers to any machine using the INTEL 8087, 80287, 80387, 80487, Pentium, or compatible chips for floating point arithmetic (e.g., IBM PC, PC/AT, or other "286", "386", or "486" machines). This also includes the OPUS532, which uses a National Semiconductor chip, the DECStation 5000, which uses a MIPS RS3000 chip, and the DEC Alpha. Single precision INTEL values are identical to single precision IEEE values. |
CRAY X-MP, CYBER 205
|
Only single precision values are given.
These machines have very large word lengths. Single
precision on these machines is comparable to double
precision on the other computers listed. Do not use
these constants for the CRAY T90. DATA IREPS,ITOL,LARGE,IEPS/0377224000000000000000B, 1 0277214000000000000000B, 2 0577777777777777777777B, 3 0377214000000000000000B/ DATA ISREPS,ISTOL/0377224000000000000000B, 1 0277214000000000000000B/ If the value of ILG is needed with this compiler, the NONMEM consultant may be able to help. |
If you have a machine not listed in the BLKDAT routine, and are uncertain about the appropriate values for your machine, the NONMEM consultant may be able to help.
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 BLKDAT, there is a level number given
in a DATA statement similar to the following†:
----------
DATA LEV/’1.0’/
Changing this number in BLKDAT, e.g. changing 1.0 to 1.1, will never be necessary, but the user may choose to do this in order to establish a record in BLKDAT that the bug fixes were implemented.
NONMEM uses many external files. The following DATA statement defines the unit numbers used by NONMEM:
DATA UN/1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22, 1 23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40/
The numbers 1, 38, 39 and 40 are currently unused; these are essentially place-holders.
Some of the units numbers may be unacceptable to a given operating system. If your operating system restricts the use of (say) unit 2, change the second value in the list from 2 to a number which is not used by NONMEM and which is acceptable to your operating system. Note that the use of unit 5 for input and unit 6 for output is hard-coded throughout the source code; changes to the fifth and sixth values of the UN array will have no effect.
A complete listing of unit numbers and corresponding file names can be found in Chapter IX.
Some operating systems may have a problem with the large number of files used by NONMEM. See Sections 2.1.2 and 4.4.
FLU is a user-installation routine. It is called by NONMEM to unload ("flush") the buffer of an I/O unit. Buffer unloading is controlled in an operating system-specific way, and often a compiler will provide a run-time function that unloads a buffer. Whenever possible, such a function call should be coded into FLU. FLU has one argument, I, which is the number of the Fortran logical unit whose buffer is to be unloaded.
The FLU routine on the distribution medium contains the following code, which is appropriate for the Microsoft Fortran PowerStation and DIGITAL Visual Fortran compilers:
SUBROUTINE FLU (I) CALL COMMITQQ(I) RETURN END
An example of FLU appropriate for Sun FORTRAN follows; the UNIX installation utility SETUP makes this change automatically:
SUBROUTINE FLU (I) CALL FLUSH(I) RETURN END
The following code examples were suggested by NONMEM users and have not been tested by the NONMEM Project Group. The statements below replace CALL COMMITQQ(I).
For HP-UX FORTRAN:
INTEGER UNITID EXTERNAL FFLUSH UNITID=FSTREAM(I) CALL FFLUSH(%VAL(UNITID))
For Watcom FORTRAN 77:
INCLUDE ’FSUBLIB.FI’ INTEGER ISTAT ISTAT=FLUSHUNIT(I)
For VAX/VMS and OpenVMS:
CALL SYS$FLUSH(%VAL(FOR$RAB(I)))
If none of the above work for a given system and the compiler’s documentation does not describe how buffers can be unloaded, the CALL statement may be de-activated:
C CALL COMMITQQ(I)
This is done automatically by SEPG77, which is used (rather than SEP) by CDSETUP6.BAT when the g77 and g95 compilers are used.
Please check any emails or newsletters that may have been sent with your copy of NONMEM and make any source code modifications suggested there.
See also Chapter 1, Section 7, for internet sites of interest.
The remaining changes to the source code are optional.
Subroutine CFILES is the last subroutine executed during a NONMEM run. It terminates with a STOP command. On some systems, this generates a "STOP" message on FORTRAN unit 6, which then appears at the end of the output report, possibly in a place which is unaesthetic, e.g., on a page containing a scatterplot. Users may prefer not to see this message. If so, prior to the STOP command, the subroutine can disconnect unit 6 from the output file and reconnect it to the file named in FNSTP. See Section 2.1.1. To make this happen, replace the characters ’C1’ everywhere they appear in the subroutine with blanks. There are three such instances.
A CALL statement to a system routine may have to be inserted as the first statement in the main program NONMEM. For example, some operating systems (e.g., CRAY CTSS) require a special library subroutine call at the start of program execution in order to initialize a core image. A Macintosh user reported that a call from the main program to a Macintosh Toolbox routine was needed to expand the amount of storage available for local variables.
The following changes have been recommended by NONMEM users to avoid run-time I/O errors on certain systems. They should be made only for the systems indicated.
This change is necessary to permit lines
longer than 132 characters in a table file.
Locate in OUTPT:
OPEN (UN(9),FILE=PATH(1:II-1)) OPEN (UN(9),FILE=PATH(1:II-1))
Change to
OPEN (UN(9),FILE=PATH(1:II-1),RECL=32762) OPEN (UN(9),FILE=PATH(1:II-1),RECL=32762)
A similar change is needed in NONMEM
routine SUPER.
Locate:
OPEN(UN(9),FILE=TABLNM(1:I-1)) OPEN(UN(9),FILE=TABLNM(1:I-1))
Change to
OPEN(UN(9),FILE=TABLNM(1:I-1),RECL=32762) OPEN(UN(9),FILE=TABLNM(1:I-1),RECL=32762)
If run-time errors occur having to do with file 11, locate in NONMEM routine OFILES:
OPEN (UN(11),FILE=FN11,FORM=’UNFORMATTED’)
Change to
OPEN (UN(11),FILE=FN11,FORM=’UNFORMATTED’,RECL=13000)
A value equal to 3*(LIM2+2)*4, where LIM2 has the value to which it is set in SIZES, may be used in place of 13000.
A similar change may be necessary for other work files.
On the CRAY and other computers which have a 64-bit integer word length, certain lines of output may be printed incorrectly. For example, the output of the illustrative examples may contain header lines like the following:
TH 1 TH 2 TH 3 OM11 OM13 OM15 OM33
Characters "OM13" should be "OM12", "OM15" should be "OM13", and so forth. The error does not affect the numerical values printed under these headers. In order to obtain the correct header lines, NONMEM subroutine STCHAR should be changed as follows.
Locate the line:
CHARACTER*4 OMC,SGC
Change it to:
CHARACTER*8 OMC,SGC
Certain constants are used by NONMEM to control array and buffer sizes, and may be changed by the user. These constants are set to values by PARAMETER statements in the include file SIZES. These values may be changed.
Values that are changed in SIZES take affect after all the appropriate NONMEM source modules have been recompiled and, if a binary library is used (see Section 3). after the binary library has been rebuilt.
Note that PREDPP and NM-TRAN and the NM-TRAN Library 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. Appendix 2 lists all the constants and the components in which they appear.
Several of the constants in SIZES are of special interest.
LTH gives the maximum number of
theta’s allowable. It must be between 1 and 70.
LVR gives the maximum number of eta’s plus
epsilon’s allowable. It must be between 1 and 70.
LVR2 controls the maximum number of eta’s permitted
when the Laplacian Method is used. It must be between 1 and
70.
LPAR gives the maximum number of
parameters that can be estimated (not fixed in some
way).†
----------
The values in SIZES on the distribution medium are as follows.
PARAMETER (LTH=40) PARAMETER (LVR=30) PARAMETER (LVR2=10) PARAMETER (LPAR=70)
These constants may be increased or decreased. Other constants are derived from LTH, LVR, LVR2 and LPAR. Such constants may also have to be increased or decreased, as described by comments in SIZES. The values of the derived constants in the version of NONMEM being distributed are as follows.
PARAMETER (LPAR2=66) PARAMETER (LPAR3=2850) PARAMETER (MTHVR=40)
The following discussion of the size of the NONMEM executable applied to NONMEM V. Although the numbers are different with NONMEM VI, the same general principles apply. Note that, for any given set of constants, the NONMEM VI executable is larger than the NONMEM V executable. However, increases in computer memory sizes have made this issue less important than it was in the past.
With the default values, the run-time size of the NONMEM executable for the first illustrative run (chapter I, user-developed PRED) is more than 6MB (including space for arrays). This is considerably more than what was required by NONMEM IV, and this may be too large for computers with less than 12MB RAM. It is possible to reduce the size of the NONMEM executable by decreasing LTH, LVR, LVR2, and the constants derived from them.
For example, if these constants are decreased to their effective values in NONMEM IV, the run-time size of the NONMEM executable is only 1.8 MB. The complete set of constants when LTH, LVR, and LVR2 have their NONMEM IV values is as follows:
PARAMETER (LTH=20) PARAMETER (LVR=10) PARAMETER (LVR2=10) PARAMETER (LPAR=30) PARAMETER (LPAR2=28) PARAMETER (LPAR3=2850) PARAMETER (MTHVR=20)
If too many theta’s, eta’s, or epsilon’s are defined in a model and NM-TRAN is not used, NONMEM will produce messages similar to the following.
LENGTH OF THETA INAPPROPRIATE DIMENSION OF OMEGA INAPPROPRIATE DIMENSION OF OMEGA PLUS DIMENSION OF SIGMA EXCEEDS 30
If constants LTH or LVR are increased, you must recompile NONMEM, NM-TRAN, PREDPP, and NM-TRAN library routines.
Increasing LVR2 (the maximum number of eta’s permitted when the Laplacian method is used) has a large impact on the size of the NONMEM executable. you must recompile NONMEM and NM-TRAN. Note that constant LVR2 may be exceeded in a particular NONMEM run when NONMEM is instructed to use the numerical method of computing second derivatives. LVR2 need only be increased if analytic second derivatives are preferred.
The number of data records per individual record is effectively unlimited, as is the total number of data records. However, NONMEM limits the number of observation records per individual record to 250. (An observation record is one containing an observation, i.e., where the missing dependent variable item MDV is 0.)
This limit is set by constant NO. 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 250 SEE INSTALLATION GUIDE
This limit can be increased.
To increase this limit, locate
PARAMETER (NO=250)
Change the value 250 to the desired value. NM-TRAN does not detect the fact that a data set exceeds this limit. If constant NO is increased, you must recompile NONMEM, NM-TRAN and the NM-TRAN library subroutines.
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, locate
PARAMETER (LNP4=1000)
Change the value 1000 to the desired value.
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 NONMEM
This message is discussed extensively in Chapter V, Section 2.4. Various strategies for avoiding it without changing NONMEM are discussed. See also Chapter VI, Section 2.1.1.
When 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.
If LPN4 is changed, you must recompile NONMEM, NM-TRAN, and the NM-TRAN library subroutines.
The entire data set is not necessarily stored in memory at one time. It is stored in a temporary disk file, and parts of it are brought into a memory buffer as needed. Some other large arrays are also stored on disk files. Of course, memory-file swapping of data set information leads to increased computer run-time. So the bigger the buffer size, the shorter may be the run time.
The sizes of the NONMEM buffers are set by constants LIM1-LIM7 and LIM11, respectively. These constants are set in, and are unique to, SIZES. If these constants are not adequate, NONMEM will produce error messages such as the following.
TOT NO. OF DATA RECS IN BUFFER 1 IS LESS THAN NO. OF DATA RECS IN INDIVIDUAL REC NO. 1 (IN INDIVIDUAL REC ORDERING) SEE INSTALLATION GUIDE
The user must than change the value of the constant in SIZES (in this case, LIM1, giving the size of buffer 1). It is necessary to recompile at least the specific NONMEM routines described below, although it may be easier to recompile all of NONMEM. In either case, if a binary library was built, it must be re-built (see Section 3).
Description of Buffers
A number of contiguous data records are stored in memory at any one time in an area called here buffer 1. If a large enough memory area can be made available for this purpose, then the entire data set can be stored in memory throughout the NONMEM run, and computing costs can be decreased. This section describes how to gauge and how to set the size of buffer 1. There are six other buffers like buffer 1, and this section also describes how their sizes may be set.
For each data record, NONMEM generates prediction, residual and weighted residual data items; these data items comprise the residual record. Buffer 2 holds a number of contiguous residual records. NONMEM generates information about each individual record; this information constitutes the individual header record. Buffer 3 holds a number of contiguous individual header records. For each individual record, NONMEM generates values for ETA variables; these values comprise the ETA record. Buffer 4 holds a number of contiguous ETA records. For each individual record, NONMEM generates information about the component models of a mixture model; this information constitutes the mixture model record. Buffer 5 holds a number of contiguous mixture model records. For each data record, NONMEM stores values of PRED-defined items to be displayed; these values comprise the PRED-defined record. Buffer 6 holds a number of contiguous PRED-defined records. For each data record of a given individual record, NONMEM stores the values found in common NMPRD4; these values comprise the NMPRD4 record. Buffer 7 holds a number of contiguous NMPRD4 records for a single individual only. For each problem in a NONMEM run, NONMEM generates information about the problem; this constitutes the problem header record. Buffer 11 holds a number of contiguous problem header records.
Buffers 1-7 and 11 should not be confused with I/O buffers which are used by the operating system.
The following calculation of buffer sizes is for double precision NONMEM. For single precision NONMEM, references to "8 byte double precision computer words" should be replaced by references to "4 byte single computer words", and the constant 8 should be replaced by constant 4 where appropriate.
The size of buffer 1 is related to the number, LIM1, of data records stored in memory at any one time. A large proportion of data sets will consist of no more than 400 data records. Consequently, the size of buffer 1 has been set to allow LIM1=400 data records. The least number of data records allowable must exceed the largest number of data records used with any one individual, which rarely will be as large as 400. Each data record consists of twenty 4 byte single precision computer words. The allocation of memory for buffer 1 is 20*(LIM1+2)∗4 = 8040∗4 = 32,160 bytes. This allocation may be increased or decreased. To allow m data records to be stored in memory at one time, change LIM1=400 to LIM1=m and recompile DAT1.
The size of buffer 2 is related to the number, LIM2, of residual records stored in memory at any one time. The size of buffer 2 has been set to allow LIM2=400 residual records. The least number of residual records allowable must exceed the largest number of data records used with any one individual, which rarely will be as large as 400. Each residual data record consists of three 4 byte single precision computer words. The allocation of memory for buffer 2 is 3*(LIM2+2)∗4 = 1206∗4 = 4824 bytes. This allocation may be increased or decreased. To allow m residual records to be stored in memory at one time, change LIM2=400 to LIM2=m and recompile DAT2.
The size of buffer 3 is related to the number, LIM3, of individual header records stored in memory at any one time. The size of buffer 3 has been set to allow LIM3=200 individual header records. Each individual header record consists of four 4 byte computer words. The allocation of memory for buffer 3 is 4*(LIM3+1)∗4 = 804∗4 = 3216 bytes. This allocation may be increased or decreased. To allow m individual header records to be stored in memory at one time, change LIM3=200 to LIM3=m and recompile DAT3.
The size of buffer 4 is related to the number, LIM4, of ETA records stored in memory at any one time. The size of buffer 4 has been set to allow LIM4=50 ETA records. Each ETA record consists of 4*LVR 8 byte double precision computer words. The allocation of memory for buffer 4 is 4*LVR*(LIM4+2)∗8 = 6240∗8 = 49920. This allocation may be increased or decreased. To allow m ETA records to be stored in memory at one time, change LIM4=50 to LIM4=m and recompile DAT4.
The size of buffer 5 is related to the number, LIM5, of mixture model records stored in memory at any one time. The size of buffer 5 has been set to allow LIM5=200 mixture model records. Each mixture model record consists of five 4 byte single precision computer words. The allocation of memory for buffer 5 is 5*(LIM5+2)∗4 = 5050∗4 = 4040 bytes. This allocation may be increased or decreased. To allow m ETA records to be stored in memory at one time, change LIM5=200 to LIM5=m and recompile DAT5.
The size of buffer 6 is related to the number, LIM6, of PRED-defined records stored in memory at any one time. The size of buffer 6 has been set to allow LIM6=400 PRED-defined records. The least number of PRED-defined records allowable must exceed the largest number of data records used with any one individual, which rarely will be as large as 400. Each PRED-defined record consists of twenty 8 byte double precision computer words. The allocation of memory for buffer 6 is 20*(LIM6+2)∗8 = 4040∗8 = 64320 bytes. This allocation may be increased or decreased. To allow m PRED-defined records to be stored in memory at one time, change LIM6=400 to LIM6=m and recompile DAT6.
The size of buffer 7 is related to the number, LIM7, of NMPRD4 records stored in memory at any one time. The size of buffer 7 has been set to allow LIM7=2 NMPRD4 records, which is generally fewer than the number of NMPRD4 records existing for any given individual. Each NMPRD4 record consists of 4*LNP4 8 byte double precision computer words. The allocation of memory for buffer 7 is 4∗LNP4∗8 = 32000 bytes. To allow m NMPRD4 records to be stored in memory at one time, change LIM7=200 to LIM7=m and recompile DAT7.
The size of buffer 11 is related to the number, LIM11, of problem header records stored in memory at any one time. The size of buffer 11 has been set to allow LIM11=25 problem header records. Each problem header record consists of forty-two 4 byte integer computer words. The allocation of memory for buffer 11 is 42*(LIM11+2)∗4= 1134∗4 = 4536 bytes. This allocation may be increased or decreased. To allow m problem header records to be stored in memory at one time, change LIM11=25 to LIM11=m and recompile DAT11.
With NONMEM VI, there are also buffers 15 and 16. The sizes of these buffers are related to constants LIM15 and LIM16. These buffers are used in DAT15 and DAT16. If LIM16 is , not adequate, NONMEM will produce error messages such as the following.
TOT NO. OF RESIDUAL RECS IN BUFFER 16 IS LESS THAN NO. OF DATA RECS WITH SOME INDIVIDUAL SEE INSTALLATION GUIDE
LIM16 should be increased and DAT16 should be recompiled.
(Buffer 13 and LIM13 are defined but not used in NONMEM VI 1.0.)
NONMEM limits the number of mixture model subpopulations to 10.
This limit is set by constant MMX. If this constant is not adequate, NM-TRAN will produce an error message.
To increase this limit, locate
PARAMETER (MMX=10)
Change the value 10 to the desired value. You must recompile both NONMEM and NM-TRAN.
The number of individual records is effectively unlimited. However, NONMEM limits the number of individual records to 1000. (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 MAXIDS. If this constant is not adequate, NONMEM will produce an error message such as the following.
TOT NO. OF INDIVIDUALS, 1001, IS GREATER THAN MAXIDS, 1000. INCREASE MAXIDS IN SIZES
To increase this limit, locate
PARAMETER (MAXIDS=1000)
Change the value 1000 to the desired value. NM-TRAN does not detect the fact that a data set exceeds this limit. You must recompile both NONMEM and NM-TRAN.
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 4050
To increase this limit, locate
PARAMETER (LSUPP=4050)
Change the value 4050 to the desired value. NM-TRAN does not detect the fact that a data set exceeds this limit.
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 77 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 754 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 DIGITAL Visual Fortran, we suggest the option
/fpe:0
With Sun FORTRAN, we suggest
-fnonstd
These 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.
You should now compile NONMEM using a FORTRAN 77 compiler and save the resulting object code in a file or files for later use. If NONMEM has been kept in one large file, it presumably can be compiled in this form. If it has been separated into two or more files, each must be compiled separately.
We suggest that a binary library be built because the use of such a library may help prevent linker error messages referring to duplicate entry names. Such messages occur with some linkers when NONMEM and PREDPP stubs (such as MIX and INFN) are replaced by user-supplied subroutines, e.g., when a mixture model is used. However, even if a binary library is not used, some linkers may permit duplicate versions of these routines, and will choose the appropriate version depending on the order in which they are presented by the command that creates the NONMEM executable. The NONMEM consultant can offer assistance if a difficulty arises when an attempt is made to replace a NONMEM or PREDPP stub.
Even if the (MS-DOS) CDSETUP6.BAT or (Unix) SETUP utility is not used, the information in Appendices 3, 4 and 5 may be of help in choosing compiler options.
In the following UNIX example, the files containing source code have names ending with .f, and the files containing object code have names ending with .o. It is recommended that they be stored in a binary library called nonmem.a. In the CMS example, the object modules have file type TEXT and are stored in a binary library called NMD TXTLIB A. (You can use a different name than NMD). In the MS-DOS example, the object modules have names ending with .obj and are stored in a binary library called nonmem.lib.
UNIX:
f77 -c -O -fnonstd *.for >& emsgs.txt
Note: The option -O requests optimization. The option may be specified differently for some compilers. Please consult your compiler’s documentation. Use the same options when compiling PREDPP and when compiling FSUBS; see Chapter VII.
Examine the "emsgs.txt" file. There should be no error messages.
It is recommended that a binary library be built.†
ar ruv nonmem.a *.o
This is the System V form of the ar command. With Sun UNIX, use one of these commands:
Solaris 1:
/usr/5bin/ar ruv nonmem.a *.o
Solaris 2:
/usr/ccs/bin/ar ruv nonmem.a *.o
With other versions of UNIX, it may be necessary to use the ranlib command after ar:
ar ruv nonmem.a *.o ranlib nonmem.a
If disk space is limited, you may now
erase all object (".o") files except nonmem.o and
blkdat.o, which must remain in this directory.
----------
MS-DOS:
|
Using PowerStation Fortran: |
fl32 /c /G4 /Ox /Op *.for > emsgs.txt
|
• /G3 should be used when compiling
for an INTEL 80386 processor. |
|
Using DIGITAL Visual Fortran: |
df /c /optimize:1 /fpe:0 *.for > emsgs.txt
With either compiler, examine the "emsgs.txt" file. There should be no error messages. Warning and informational messages (such as "some interprocedural optimizations may be disabled ...") may be ignored. It is recommended that a binary library be built.
link /lib /out:nonmem.lib *.obj
If disk space is limited, you may now erase all object (".obj") files except nonmem.obj and blkdat.obj, which must remain in this directory.
|
CMS: |
Make a file called COMPILE EXEC A
containing the statement:
EXEC FORTVS &2
(Omit ’EXEC’ if FORTVS is a MODULE rather than
an EXEC.)
Make a file called ADDNMD EXEC A
containing the statement:
TXTLIB ADD NMD &2
Make a file called ERASE2 EXEC A
containing the statement:
ERASE &2 TEXT A
Input the following commands:
NMD EXEC COMPILE
If the compiles are successful, input the following commands:
TXTLIB GEN NMD NONMEM NMD EXEC ADDNMD
You should now erase all LISTING files and
all TEXT files for routines in NMD.
BLKDAT TEXT A will be needed later and must be
recreated.
ERASE * LISTING NMD EXEC ERASE2 FORTVS BLKDAT
For VAX/VMS and OpenVMS:
$ library/object/create nmd.olb nmd.obj
A user of Watcom FORTRAN 77 suggests this command to build nonmem.lib:
wlib -q nonmem @nonmem.lbc
The file nonmem.lbc contains a list of all the object modules, each preceded by the characters "+-". For example, the first two lines are as follows:
+-begin.obj +-blkdat.obj
Note that NONMEM is incomplete at this point because the PRED subroutine is missing. PRED will be compiled later and linked with the NONMEM object modules.
Several problems can arise during the compiles.
NONMEM contains code that is not part of the FORTRAN 77 standard (see Chapter I, Section 2.2). If your compiler allows a choice between strict FORTRAN 77 vs. non-standard FORTRAN, use the latter option.
If your compiler allows a choice between optimized and non-optimized compiles, we suggest that you use the optimizer feature. If NONMEM does not seem to behave correctly, try recompiling without this feature before you conclude that there may be a bug in NONMEM.
If a floating point exception occurs during a NONMEM run, it may be useful to re-run the problem using non-optimized compiles in order to obtain diagnostic information such as name of the subroutine in which the exception occurred and the line number, or to make it possible to use a debugging tool to get even more information.
Some optimizing compilers may be unable to compile certain subroutines (e.g., INPT) because of their size. INPT may be compiled without optimization without adversely affecting NONMEM run times because it does not perform any time-consuming tasks. In general, it should always be possible to combine non-optimized with optimized object code. For routines other than INPT, consult with the NONMEM consultant.
Compiler error messages such as the following are possible:
Cannot open file SIZES Cannot open INCLUDE file "SIZES" Unable to open include data set
Make sure the file SIZES is located in the directory above that of the NONMEM source code.
In a case-sensitive operating system such as UNIX, the file SIZES may have been stored with the lower-case name sizes. Rename the file:
mv sizes SIZES
The include file may require an extension when stored on disk. See the introductory paragraphs of this chapter. Some FORTRAN compilers may not permit INCLUDE statements. If this is the case with your compiler, please contact the NONMEM consultant.
You may observe that certain IMSL subroutines are included with NONMEM. Please do not substitute local versions of these routines. The routines distributed with NONMEM are somewhat different from the standard versions.
You can expect to see certain warning messages from the compiler. Normally, the compiled code will be correct. You may prefer to suppress these messages with appropriate compiler options.
For example, you may be warned that NONMEM includes hollerith data, hollerith data assigned to INTEGER variables, and EQUIVALENCE statements referring to different data types. Some compilers may also warn you of dummy arguments which are not used in subroutines such as CCONTR, CONTR, CRIT, and MIX. (These subroutines are "dummy", or "stub", routines which can be replaced by user-written code in advanced applications of NONMEM.)
There may be many warning messages such as the following because of the include file SIZES:
Warning: local variable "lth" never used
VAX/VMS and OpenVMS users may see multiple instances of the following informational messages. They should be ignored.
%FORT-I-CHACONCONTD, Character or Hollerith constant continued across
lines; may be non-portable
%FORT-I-DEFSTAUNK, Default STATUS= ’UNKNOWN’ used in OPEN statement
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 (410) 696-3098 or send e-mail to nmconsult@globomaxnm.com.
The simplest NONMEM test case is given in NONMEM Users Guide, Part I, figures 1 and 2. It does not use PREDPP or NM-TRAN.
Figure 1 is a PRED subroutine. Read this subroutine from file "PRED1" of the distribution medium. or create it using your system editor. If you are installing single precision NONMEM, delete the third line ("DOUBLE PRECISION ...").
Figure 2 is a NONMEM control stream, complete with data. Read this control file from file "CONTROL1" of the distribution medium, or create it using your system editor. If you use an editor, be extremely careful to enter the file exactly as shown. Shifting a value by even one column may affect the results. Five of the lines are reproduced here, followed by a ruler to indicate the column assignments:
ITEM 0 3 0 0 1
320 .27 1.71
STRC 3 1 1
THTA 1.7 .102 29.
DIAG 2
4 8 1 1 2 2 2 3
2 6 0 4 8 2
Now compile the PRED subroutine and link it with NONMEM.
For UNIX, assume that NONMEM has been compiled in the directory /export/home/nmvi/nm. Assume that the pred subroutine is in file pred1.for.
UNIX:
If nonmem.a was built as suggested, the command
is:
set n=/export/home/nmvi/nm f77 -O -fnonstd pred1.for $n/blkdat.o $n/nonmem.a
If nonmem.a was not built, the command is:
f77 -O -fnonstd pred1.for /export/home/nmvi/nm/*.o
Either command produces a executable called a.out.
For MS-DOS, assume that NONMEM has been compiled in the directory c:\nmvi\nm and that a binary library nonmem.lib was built. Assume that the pred subroutine is in file pred1.for.
|
MS-DOS: |
|
Using PowerStation Fortran: |
set ndir=c:\nmvi\nm set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib fl32 /G4 /Ox /Op pred1.for %n% set n= set ndir=
Use the same option (/G3, /G4, or /G5) as for the compilation of NONMEM itself.
Using DIGITAL Visual Fortran:
set ndir=c:\nmvi\nm set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib df /optimize:1 /fpe:0 pred1.for %n% set n= set ndir=
If nonmem.lib was not built, as may be the case with Watcom FORTRAN 77, replace the line starting set n= with the following:
set n=%ndir%\*.obj
For CMS, assume that NONMEM has been compiled and placed in the file NMD TXTLIB A. Assume that the PRED subroutine is in file PRED1 FORTRAN A. Note that BLKDAT must be explicitly loaded because it is never actually called, and that the file BLKDAT TEXT A MUST exist on the local disk.
|
CMS: |
FORTVS PRED1 FORTRAN A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB NMD LOAD NONMEM BLKDAT PRED1
For UNIX, assume the control stream is
stored in file control1. UNIX "redirection" is
used to preconnect FORTRAN’s standard input (unit 5)
to control1 and standard output (unit 6) to report1 (the
file that will contain the output report). Work files FILE07
and FILE10-FILE37 are automatically created and deleted
during the run†.
----------
|
UNIX: |
a.out < control1 > report1
In Sun UNIX, and possibly in other versions of UNIX, messages relating to IEEE floating point exceptions are written to standard error, which defaults to the terminal. It is desirable to capture these messages. The first command stores the messages in the same file as the output report; the second stores them in a separate file.
Using the C-shell:
a.out < control1 >& report1 (a.out < control1 > report1) >& errors1
Using the Bourne shell:
a.out < control1 1> report1 2>&1 a.out < control1 1> report1 2> errors1
For MS-DOS, assume the control stream is stored in file control1. Work files FILE07 and FILE10-FILE33 are automatically created and deleted during the run†.
|
MS-DOS: |
copy control1 fcon pred1 rename output report1
For CMS, assume that the control stream is
stored in file CONTROL1 DATA A, and that the output report
is to be written in file REPORT1 LISTING A. Assume also that
BLKDAT was modified to so that the special file for
intermediate output from the Estimation Step is called
FILE2, as suggested in Section 2.1.1, and that this output
is to be written to the terminal. Work files FILE07 and
FILE10-FILE33 are automatically created and deleted during
the run‡.
----------
|
CMS: |
FILEDEF FILE2 TERMINAL ( LRECL 133 FILEDEF 5 DISK CONTROL1 DATA A FILEDEF 6 DISK REPORT1 LISTING A (LRECL 133 START
If you do not want to see intermediate output from the Estimation Step at the terminal, use this file definition statement for FILE2:
FILEDEF FILE2 DUMMY ( LRECL 133
For the IBM operating system OS/370, DD statements are needed for all files used during the run, including FILE07 and FILE10-FILE33. For CMS, they are optional; See Chapter VII.
See Chapter IX for a discussion of the characteristics of all NONMEM files. Recommended DCB subparameters are given for IBM OS/370.
For VAX/VMS, the following commands can be used assuming that an executable program NONMEM.EXE has been built and that file TEST1.DAT contains the input stream:
$ ASSIGN/USER TEST1.DAT FOR005 $ ASSIGN/USER TEST1.OUT FOR006 $ RUN NONMEM
The run may fail immediately without producing any output and possibly with a message indicating that a floating point exception has occurred. With Microsoft PowerStation Fortran and DIGITAL Visual Fortran, for example, there may be a console message such as:
RUN-TIME ERROR M6201: MATH-SQRT: DOMAIN ERROR.
This can happen when the wrong constants are activated in BLKDAT, e.g., the IEEE constants are used on a computer with INTEL floating point architecture.
The following message may also occur when the wrong constants are used:
PROGRAM TERMINATED: WITH NMPR12-13, LAPLACIAN METHOD MUST BE USED
Some operating systems may have a problem with the large number of files used by NONMEM.
In MS-DOS, it may be necessary to modify the system file CONFIG.SYS. Insert the line (or change files= from its original value):
files=64
The system must be rebooted after the change is made.
With SVS 
FORTRAN-77, a change to NONMEM’s BEGIN routine may be
necessary. See Section 2.1.2 above.
Compare the output report to Figures 3a-18 of Users Guide, Part I. You may see some slight discrepancies in some of the figures, especially in Figures 5, 8, 9, 10, and 11. The values printed on these pages are sensitive to differences in computer arithmetic and precision. However, the final value of the objective function (8.940, see Figure 6) and the final parameter estimates (1.94, .102, 32.0, and .899, see Figure 7) should always be the same to the number of significant digits (3) that are printed. If a serious problem such as an operating system interrupt or an error message from NONMEM occurs, the most likely causes are as follows:
|
• |
Your operating system requires one or more of the changes to NONMEM source described in Section 2. |
|
• |
The BLKDAT routine was not included in the executable. |
|
• |
The machine-dependent constants in BLKDAT are incorrect. |
|
• |
NONMEM and PRED are not consistent as to precision (single vs. double). |
|
• |
The NONMEM control stream was not keyed in properly. |
|
• |
The number of significant digits requested in the parameter estimates may be more than NONMEM can obtain on your computer, resulting in unsuccessful termination of the Estimation Step due to rounding errors dominating. This is most likely to occur when single-precision NONMEM is installed on a computer other than the large scientific computers described in Section 4.1 of Chapter I. Modify the ESTM record of the NONMEM control stream to request a smaller number of significant digits. In the test case of Section 4.1 (Figure 2 of Users Guide, Part I), for example, the ESTM record appears as follows and requests 4 significant digits: |
ESTM 0 240 4 2 Change it to the following: ESTM 0 240 3 2 |
Problems that can arise during a NONMEM run are also discussed in Chapter XIII of NONMEM Users Guide, Part V. If you cannot locate the source of the error, please call the NONMEM consultant.
If the output report appears correct you can proceed in either of two ways. The simple test case involves only a subset of NONMEM’s features and subroutines. If you are using a computer or compiler which is relatively new, it is possible that problems or errors in machine dependent constants are still present. You should continue entering and running the examples in Users Guide, Parts I and II, which do not involve PREDPP or NM-TRAN, but which do exercise an increasingly complete selection of NONMEM’s features. If you are using a computer and compiler with prior successful NONMEM installations, you might proceed immediately to Chapter IV.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...