Chapter VII - How to Run NM-TRAN and NONMEM-PREDPP
Once NONMEM, PREDPP, and NM-TRAN have been installed and tested, you may want to create simple commands that will allow the programs to be easily run together.
Users who are upgrading from NONMEM V to NONMEM VI and who have already developed satisfactory front-end tools for running NM-TRAN and NONMEM can continue to use the same tools, and may prefer to skip this chapter.
Users who are installing for the first time, or who are upgrading from NONMEM V to NONMEM VI and do not already have satisfactory front-end tools, may choose to use the tools presented in this chapter.
The tools are a UNIX C shell script (NMFE6) and MS-DOS batch file (NMFE6.BAT), and a required FORTRAN utility program (NMLINK6). They are provided on the NONMEM distribution medium.
Two special versions of NMLINK6, called makeg77bat and makeg95bat, are provided on the CD. Two special versions of nmfe6.bat, called nmg77.bat and nmg96.bat, are provided on the CD. They handle issues specific to the G77 and G95 compilers in the Windows environment. See Section 2.1.4 for a discussion of these variations.
A version of NMFE6.bat, called nmfe6wfl386.bat, is provided on the CD. It handles issues specific to the Open Watcom 1.3 compiler. See the readme file on the distribution medium for more information about nmfe6wfl386.bat. Other than this file, no support will be offered for the Open Watcom 1.3 compiler in the future.
The tools are installed by the automatic installation utilities SETUP and CDSETUP6.BAT described in Appendix 4 and 5, or can be installed by the user following the instructions in this chapter. The material in this chapter serves as a detailed description of what these utilities do to install the tools, and it contains suggestions for modifications to both the utilities and the tools which may be useful in some environments.
The MS-DOS tools require the use of Microsoft Fortran PowerStation or DIGITAL Visual Fortran 5.0, or a compiler whose linker permits use of linker response files (such as LINK.LNK in the examples).
The tools are general in nature and can be used to run any PREDPP ADVAN/TRANS combination, with abbreviated or user-supplied code for required routines PK, ERROR, etc. They also can be used for runs with abbreviated or user-supplied code for PRED. If abbreviated code is used, it can be implemented with either NM-TRAN Library or generated subroutines.
Use of the tools is illustrated in this chapter with a PREDPP example using ADVAN2 and TRANS1, using both NM-TRAN library subroutines (two-step run) and generated code (three-step run). Examples of CMS EXECs are also given for the same examples. These examples, suitably modified for local differences, should suffice for many CMS users.
For other operating systems, the examples in this chapter may be helpful as samples of what can be done. The final section of this chapter discusses various considerations for modifying these examples.
In the two-step run, illustrated by Figure 7.1, abbreviated codes within the NM-TRAN control file are implemented using NM-TRAN library subroutines. The NONMEM-PREDPP executable is created only once and can be stored for repeated re-use. In the three-step run, illustrated by Figure 7.2, abbreviated codes are implemented using generated subroutines. FORTRAN code for these subroutines is compiled, and the NONMEM-PREDPP executable is created, as part of every run. The two figures are the same except in the shaded areas. All NM-TRAN files are shown (the most important ones in darker boxes), but not all NONMEM files are shown. FORTRAN unit numbers are indicated for every file.
Fig 7.1. Two-step NM-TRAN and NONMEM-PREDPP run using library subroutines.
Fig 7.2. Three-step NM-TRAN and NONMEM-PREDPP run using generated subroutines.
As described in Chapter I, several choices must be made when using the NONMEM system. In these examples, we assume that the following choices have been made.
1. Double-Precision Versions
|
The examples use files containing double-precision subroutines. (See also Chapter I, Section 4.1.) |
2. PREDPP
|
The examples use PREDPP rather than a user-supplied PRED or $PRED abbreviated code. (See also Chapter I, Section 4.2.) |
3. ADVAN2
|
ADVAN2 implements the one-compartment model with first order absorption. |
4. TRANS1
|
The function of a TRANS routine is to re-parameterize the basic pharmacokinetic parameters. |
5. Steady-State Routines
|
The presence of steady-state doses in the data file requires additional subroutines. The steady-state subroutines add to the size of the NONMEM executable, especially so when a general model (ADVAN5-9) is used, but they do not add to the run time unless the data actually includes steady state doses. With the UNIX and MS-DOS tools described in this chapter, steady-state subroutines are included in the NONMEM executable only if the SS data item is defined on the $DATA record or an SS subroutine is listed on the $SUBROUTINES record. |
6. Library Subroutines vs. Generated Code
|
The choice of library vs. generated subroutines was discussed in Chapter VI. Examples are given here of the use of both. |
7. Return Code from NM-TRAN
|
The UNIX and MS-DOS tools described in this chapter test for the non-existence of the NM-TRAN output file FREPORT to stop execution when NM-TRAN detects errors. The CMS example below takes advantage of the NM-TRAN return code to stop execution when NM-TRAN detects errors. (See also Chapter V, Section 2.2.) In the UNIX and MS-DOS examples, on the other hand, it is the absence of NM-TRAN output file FREPORT that causes execution to be stopped when errors are detected. |
CMS users should now skip to Section 3.
Sections 2.1-2.3 concern installation of NMLINK6, NMFE6, and NMFE6.BAT. If SETUP or CDSETUP6.BAT is used, the reader may wish to skip to Section 2.4.
It is suggested that this program be created in a new directory. In UNIX, for example, you might work in a dedicated directory called (say) /export/home/nmvi/util. In MS-DOS, you might work in a dedicated directory called (say) c:\nmvi\util. The program is assumed to have been read from "NMLINK6" on the distribution medium. It should be copied to directory util and given the name nmlink6.for or, if your Fortran compiler requires the extension ".f", nmlink6.f
UNIX and MS-DOS examples depend on the use of the NMLINK6 utility program. Other than the name, the program is unchanged from the NONMEM V version NMLINK5.
The contents of the file are as follows.
PROGRAM NMLINK
CHARACTER*72 TEMP,PREFIX,PATH
CHARACTER*9 A(8),SUF
CHARACTER*1 B,S
INTEGER LP,LSUF
INCLUDE ’path.for’
B=’ ’
LP=INDEX(PATH,B)-1
LSUF=INDEX(SUF,B)-1
OPEN (10,FILE = ’FREPORT’)
OPEN (11,FILE = ’LINK.LNK’)
5 READ (10,101,END=99) TEMP
10 IF (INDEX(TEMP,’PREDPP LIBRARY’).NE.0) THEN
PREFIX=PATH(1:LP)//S//’pr’//S
GO TO 20
ENDIF
IF (INDEX(TEMP,’NM-TRAN LIBRARY’).NE.0) THEN
PREFIX=PATH(1:LP)//S//’tl’//S
GO TO 20
ENDIF
GO TO 5
20 READ (10,101,END=99) TEMP
READ (TEMP,100,END=99) A
DO 30 I=1,8
IF (A(I).EQ.B.OR.A(I)(9:9).NE.B) GO TO 10
TEMP=PREFIX
J=INDEX(TEMP,B)
TEMP(J:)=A(I)(2:)
J=INDEX(TEMP,B)
TEMP(J:)=SUF(1:LSUF)
WRITE (11,*) TEMP
30 CONTINUE
GO TO 20
100 FORMAT (8A9)
101 FORMAT (A72)
99 END
Prior to compilation, a file called path.for must be created in the directory where nmlink6.for exists. It must contain the following three lines. Each line must start with at least six spaces. That is, the first non-blank character of each line must be in column 7 or higher.
|
UNIX: |
PATH=’/export/home/nmvi’
S=’/’
SUF=’.o’
|
MS-DOS: |
PATH=’c:\nmvi’
S=’\’
SUF=’.obj
If the NONMEM VI directory is not /export/home/nmvi or c:\nmvi, supply the correct path.
Changes may be necessary to the source code prior to compilation. If directories have been created as recommended in the previous chapters (pr and tl for PREDPP and NM-TRAN Library routines, respectively), then no changes are needed to the source code. If sub-directories other than pr and tl were used for PREDPP and NM-TRAN library routines respectively, locate these lines of code and replace characters pr and tl with the correct sub-directories:
PREFIX=PATH(1:LP)//S//’pr’//S
PREFIX=PATH(1:LP)//S//’tl’//S
If file name FREPORT was changed in NM-TRAN’s ABLOCK (see Chapter V, Section 1.1.1), the same change must also be changed in nmlink6 source code.
A user with Watcom FORTRAN 77 suggests this change. Locate this line:
WRITE (11,*) TEMP
Replace with:
WRITE (11,*) ’file ’,TEMP
Now the program must be compiled.
|
UNIX: |
f77 -o nmlink6.exe nmlink6.for
This creates nmlink6.exe, the executable module.
|
MS-DOS: |
fl32 nmlink6.for
This creates nmlink6.exe, the executable module.
MAKEG77BAT and MAKEG95BAT are Fortran programs that can be used instead of NMLINK6 with G77 and G95 in the Windows environment. With these compilers, the linker does not permit the use of linker response files (such as LINK.LNK).
When CDSETUP6.BAT is used, then NMFE6.BAT does not use NMLINK6 to create LINK.LNK. Instead, MAKEG77BAT and MAKEG95BAT are used. These generate a file named G77COMPILE.BAT or G95COMPILE.BAT, respectively. G77COMPILE or G95COMPILE contains the complete compiler command, and is invoked by NMFE6.BAT using the MS-DOS "CALL" command. When G77 or G95 is used, CDSETUP6.BAT uses files nmg77.bat and nmg95.bat from the CD as prototypes for NMFE6.BAT.
For example, suppose CONTROL5 is used.
The command in NMFE6.BAT with (e.g.) fl32 that builds the NONMEM executable is:
fl32 /Ox /Op /Fenonmem fsubs.for @link.lnk c:\nmvi\NM\nonmem.obj c:\nmvi\NM\blkdat.obj c:\nmvi\NM\nonmem.lib
The file LINK.LNK contains the following:
c:\nmvi\pr\PRED.o c:\nmvi\pr\PREDI.o c:\nmvi\pr\CHECK.o c:\nmvi\pr\SADVAN.o c:\nmvi\pr\ADVAN2.o c:\nmvi\pr\SSS0.o c:\nmvi\pr\TRANS1.o c:\nmvi\pr\INFN.o
With (e.g.) g95, the command in NMFE6.BAT that builds the NONMEM executable is:
call g95compile.bat
The file G95COMPILE.BAT contains the following:
g95 -O -o nonmem.exe -fno-backslash fsubs.for c:\nmvi\pr\PRED.obj
c:\nmvi\pr\PREDI.obj c:\nmvi\pr\CHECK.obj c:\nmvi\pr\SADVAN.obj
c:\nmvi\pr\ADVAN2.obj c:\nmvi\pr\SSS0.obj c:\nmvi\pr\TRANS1.obj
c:\nmvi\pr\INFN.obj c:\nmvi\NM\nonmem.obj c:\nmvi\NM\blkdat.obj
c:\nmvi\NM\nonmem.lib
The C shell script NMFE6 is assumed to have been read from file "NMFE6" on the distribution medium. It should be copied to directory util and given the name nmfe6. It must be made executable, as follows:
chmod 755 nmfe6
NMFE6 includes the start date and time and the stop date and time in the output file, and also copies the NM-TRAN input file to the output file. The contents of NMFE6 are as follows.
#!/bin/csh # This C shell script runs NM-TRAN and NONMEM VI # written by AJB 3/98 version 1.0 Modified April 2006 # The following lines are inserted by SETUP #set dir=/home/nmvi #set f=f77 #set o=-O set ndir=$dir/nm set n="$ndir/NONMEM.o $ndir/BLKDAT.o $ndir/nonmem.a" # for user library set u= rm -f FSUBS FSUBS.f FLIB FREPORT LINK.LNK nonmem >& /dev/null if ($#argv != 2) then echo Usage: nmfe6 infile outfile exit endif if !(-e $1) then echo File $1 does not exist. exit endif set s= $dir/tr/nmtran.exe < $1 if !(-e FREPORT) exit $dir/util/nmlink6.exe if (-e FSUBS) then cp FSUBS FSUBS.f set s=FSUBS.f endif $f -o nonmem $o $s ‘cat LINK.LNK‘ $n $u if !(-e nonmem) then echo No nonmem execution. exit endif echo Starting nonmem execution ... date >$2 cat $1 >>$2 echo " " >>$2 echo " " >>$2 ./nonmem < FCON >> $2 date >>$2
Changes to nmfe6 must be made. Locate the following three lines of code. First, delete the character "#". Second, change if necessary (e.g., if the NONMEM VI directory is not /export/home/nmvi; if the command for Fortran compiles is not f77; if an option other than -O was used during compiles of NONMEM and PREDPP).
#set dir=/export/home/nmvi #set f=f77 #set o=-O
The UNIX installation utility SETUP makes the above changes automatically.
If any file names were changed in NM-TRAN’s ABLOCK (see Chapter V, Section 1.1.1), the file names must also be changed in nmfe6.
If a binary library nonmem.a was not created for NONMEM (see Chapter V, section 3), locate
set n="$ndir/NONMEM.o $ndir/BLKDAT.o $ndir/nonmem.a"
Change to:
set n="$ndir/*.o"
It is best to copy nmfe6 to a directory in every NONMEM user’s path, such as /usr/local. If you are the only NONMEM user, you may choose to place nmfe6 in your home directory. The nmfe6 command may now be executed from any directory. (You may first need to enter the UNIX command "rehash".)
The SETUP utility does not implement these suggestions.
The MS-DOS batch file nmfe6.bat is assumed to have been read from file "NMFE6.BAT" on the distribution medium. It should be copied to directory util. In the remainder of this chapter, nmfe6.bat denotes the modified version of the file in directory util.
Nmfe6.bat includes the start date and time and the stop date and time in the output file, and also copies the NM-TRAN input file to the output file. The contents of nmfe6.bat follow.
@echo off date /t >%2 time /t >>%2 @echo off rem This MS-DOS batch file runs NM-TRAN and NONMEM V rem written by AJB 3/98 version 1.0 Modified 4/2006 rem set commands are inserted by setup.bat rem set dir=c:\nmv rem for MS Fortran Powerstation ... rem set f=fl32 rem set op=/Ox /Op rem For Digitial Visual Fortran 5.0 ... rem set f=df rem set op=/optimize:1 /fpe:0 set ndir=%dir%\nm set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib set u= if exist FSUBS* del FSUBS* if exist FLIB del FLIB if exist FREPORT del FREPORT if exist LINK.LNK del LINK.LNK if exist %f%.txt del %f%.txt if exist nonmem.exe del nonmem.exe if not "%1" == "" goto checko echo Usage: nmfe6 infile outfile goto exit :checko if not "%2" == "" goto checki echo Usage: nmfe6 infile outfile goto exit :checki if exist %1 goto tran echo %1 does not exist. goto exite :tran set s= %dir%\tr\nmtran.exe < %1 if not exist FREPORT goto exit %dir%\util\nmlink6.exe if not exist fsubs goto compile copy fsubs fsubs.for set s=fsubs.for :compile %f% %op% /Fenonmem %s% @link.lnk %n% %u% > %f%.txt if not exist nonmem.exe goto exite echo Starting nonmem execution ... nonmem.exe copy %2 +%1 +output %2 echo Stop Time: >>%2 date /t >>%2 time /t >>%2 del output goto exit :exite echo No nonmem execution. if exist %f%.txt echo There may be error messages in file %f%.txt. :exit set dir= set ndir= set n= set f= set u=
Changes to nmfe6.bat must be made. First, locate the following line of code and delete the characters "rem". If the NONMEM VI directory is not c:\nmvi, change to the appropriate directory.
rem set dir=c:\nmvi
If you are using MS Fortran Powerstation compiler, locate the following pair of lines, delete the characters "rem", and change the compiler instruction and the compiler options if other commands or options were used during the compile of NONMEM and PREDPP:
rem set f=fl32 rem set op=/Ox /Op
If you are using DIGITAL Visual Fortran compiler, locate the following pair of lines, delete the characters "rem", and change the compiler command and the compiler options if other commands or options were used during the compile of NONMEM and PREDPP:
rem set f=df rem set op=/optimize:1 /fpe:0
The installation utility CDSETUP6.BAT makes the above changes automatically.
If any file names were changed in NM-TRAN’s ABLOCK (see Chapter V, Section 1.1.1), the file names must also be changed in nmfe6.bat.
A user with Watcom FORTRAN 77 suggests this change. Locate this line:
%f% %op% /Fenonmem %s% @link.lnk %n% %u% > %f%.txt
Replace with:
%f% %op% /fe=nonmem %s% /fi=link.lnk %n% %u% > %f%.txt
If a binary library nonmem.lib was not created, as may be the case with Watcom FORTRAN 77, locate this line:
set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib
Replace with:
set n=%ndir%\*.obj
It is best to copy nmfe6.bat to a directory in every NONMEM user’s path. You may instead change system environmental variables to put the directory in your path. One way is to put in c:\nmvi\util and edit your autoexec.bat file to include c:\nmvi\util in the PATH variable. E.g.,
set PATH=C:\nmvi\util;"%PATH%"
Reboot after changing autoexec.bat.
The CDSETUP6.BAT utility does not implement these suggestions.
The following are assumed to exist, and are created by the SETUP utility:
/export/home/nmvi/nm
|
This is a directory containing compiled code for double precision NONMEM. The compiled code is contained in a binary library nonmem.a in this directory. Object files nonmem.o and blkdat.o also exist in this directory. |
/export/home/nmvi/pr
|
This is a directory containing the compiled code for double precision PREDPP. Each routine is in a separate ".o" file. |
/export/home/nmvi/tl
|
This is a directory containing the compiled code for the double precision NM-TRAN library subroutines. Each routine is in a separate ".o" file. |
/export/home/nmvi/tr/tran
|
This is the compiled executable code for NM-TRAN. |
/export/home/nmvi/util/nmlink6
|
This is the compiled utility program NMLINK6. |
/export/home/nmvi/util/nmfe6
|
This is the modified version of C shell script NMFE6. |
control5 and theopp
|
These are the files CONTROL5 and THEOPP that were recommended in Chapter V. |
The following are assumed to exist, and are created by the CDSETUP6.BAT utility:
c:\nmvi\nmd
|
This is a directory containing compiled code for double precision NONMEM. The compiled code is contained in a binary library nonmem.lib in this directory. Object files nonmem.obj and blkdat.obj also exist in this directory. |
c:\nmvi\pr
|
This is a directory containing the compiled code for double precision PREDPP. Each routine is in a separate ".obj" file. |
c:\nmvi\tl
|
This is a directory containing the compiled code for the double precision NM-TRAN library subroutines. Each routine is in a separate ".obj" file. |
c:\nmvi\tr\nmtran
|
This is the compiled executable code for NM-TRAN. |
c:\nmvi\util\nmlink6.exe
|
This is the compiled utility program NMLINK6. |
c:\nmvi\util\nmfe6.bat
|
This is the modified version of NMFE6.BAT. |
control5 and theopp
|
These are the files CONTROL5 and THEOPP that were used in Chapter V. |
It is suggested that NONMEM be run in a new directory. In UNIX, for example, you might work in a dedicated directory called (say) /export/home/nmvi/run. In MS-DOS, you might work in a dedicated directory called (say) c:\nmvi\run. The NM-TRAN control file control5, as read from the distribution medium, can be used for a test run of nmfe6 and nmfe6.bat, using generated PK and ERROR subroutines. Copy the files control5 and theopp to the run directory. If nmfe6 or nmfe6.bat is not in your path, copy it to the run directory.
SETUP (or CDSETUP6.BAT) creates the run directory and copies to it control5, theopp, and nmfe6 (or nmfe6.bat) for test purposes.
File control5 contains this line:
$SUBROUTINES ADVAN2
This directs NM-TRAN to create the file FSUBS
containing generated double precision FORTRAN
subroutines†.
----------
The user types a command such as the following:
|
UNIX and MS-DOS: |
nmfe6 control5 report5
NM-TRAN is executed using control5 as input. Any NM-TRAN error messages appear at the terminal. If errors are found, nmfe6 exits. Otherwise, NM-TRAN creates the file FSUBS containing double precision generated subroutines PK and ERROR. FSUBS is renamed FSUBS.for (because the compiler expects the suffix ".for"). Utility program nmlink6 is executed. This program reads the NM-TRAN output file FREPORT and creates the file LINK.LNK, which lists the object modules from PREDPP that are needed for the run. FSUBS.for is compiled and linked with PREDPP according to the instructions in LINK.LNK, and then linked with NONMEM itself. Finally, the executable, nonmem.exe, runs. The output report appears in file report5, along with any operating system error messages generated during the NONMEM run.
In order to run with NM-TRAN library routines, change the $SUBROUTINES line to:
$SUBROUTINES ADVAN2 LIBRARY
The user types the same command. NM-TRAN creates a file FLIB with instructions for the NM-TRAN library PK and ERROR routines. FSUBS is not created. LINK.LNK now lists the the NM-TRAN library PK and ERROR routines in addition to the PREDPP routines. Otherwise, the run is identical to the first case.
Compare the NONMEM output with that referenced in Chapters III and IV. Remember that slight differences from the published output are expected during the estimation step, but that the final parameter estimates should be the same.
If there are no errors, UNIX and MS-DOS users should now skip to Section 4.
In MS-DOS, the message "Out of environment space" may occur when CDSETUP6.BAT or nmfe6.bat is used. If this happens, append /e:1024 to the shell command in config.sys. E.g.,
shell=c:\windows\command.com c:\windows /p/e:1024
Reboot the system.
A larger value than 1024 may be necessary, e.g., 2048.
Alternately, in Windows 95, make the change in the properties window for the MS-DOS icon, Memory tab, Initial Environment pull-down menu. Start a new MS-DOS window.
In MS-DOS, if the NONMEM run fails because there are too many open files, locate the line starting files= in config.sys and change to:
files=64
Reboot the system.
With Microsoft FORTRAN PowerStation 1.0, the nmfe6 command may fail with the following message:
File Creation error.
If so, edit nmfe6.bat. Locate this line:
%f% %op% /Fenonmem %s% @link.lnk %n% %u% > %f%.txt
Delete the characters "> %f%.txt". The new line is:
%f% %op% /Fenonmem %s% @link.lnk %n% %u%
All compiler messages will be directed to the terminal rather than to the file fl32.txt.
With Microsoft FORTRAN PowerStation 1.0 and Microsoft Windows 3.1, the compile may fail (nonmem.exe is not created) because the command line is too long. If so, edit nmfe6.bat. Locate the line
set n=%ndir%\nonmem.obj %ndir%\blkdat.obj %ndir%\nonmem.lib
Replace with set n=%ndir%\blkdat.obj %ndir%\nonmem.lib
If the compile still fails, please contact the NONMEM consultant.
Certain optional files can be generated by NONMEM at the users request. These files are discussed in Chapter IX, Section 2. No special modification of nmfe6 or nmfe6.bat is needed.
Note that nmfe6 is very general. Any NM-TRAN control and report file names could be specified instead of control5 and report5. These may specify any ADVAN and TRANS routines, or $PRED abbreviated code, or user-supplied PRED routine. With abbreviated code, either NM-TRAN Library routines or generated routines may be used. Thus, other NM-TRAN control streams from the NONMEM distribution medium may be run using nmfe6.
Users may choose to substitute their own subroutines for certain default NONMEM-PREDPP routines. It is assumed in this discussion that CPYUSR is set to its default value, .TRUE., in NM-TRAN’s ABLOCK.
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.
If a binary library is not used, care must be taken to omit the default version from the link-edit command, because duplicate entry names usually cause a fatal error.
E.g., if the NONMEM directory includes the default MIX.o, then a command such as the following will include two modules with entry name mix, which is an error:
f77 mix.o /export/home/nmvi/nm/*.o ...
One solution to the problem is to temporarily remove mix.o from /export/home/nmvi/nm, and replace it after the f77 command has finished executing. A better solution is to list precisely those NONMEM routines that are needed for the executable being built, rather than use the notation "*.o". Because there are many NONMEM routines, one must construct this list cleverly using UNIX or MS-DOS tools.
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=subname
NM-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.
User-supplied routines and NM-TRAN verbatim code may contain calls to other user-supplied subroutines, which are referred to as user utility routines. There are two ways that 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=BSPLINE
NM-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 nmfe6 shell script or nmfe6.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=BSPLINES.o set u="/.../.../mylib.a"
|
MS-DOS: |
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 nmfe6 and nmfe6.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.
The NM-TRAN control file may contain one or more lines of the form
INCLUDE filename
The 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.
UNIX and MS-DOS users should now skip to Section 4.
The following files are assumed to exist:
NMD TXTLIB A
|
This is a CMS text library containing the compiled code for double precision NONMEM. |
PPD TXTLIB A
|
This is a CMS text library containing the compiled code for double precision PREDPP. |
TRLD TXTLIB A
|
This is a CMS text library containing the compiled code for double precision NM-TRAN library subroutines. |
TRAN TXTLIB A
|
This is a CMS text library containing the compiled code for NM-TRAN. |
Other TEXT files
|
Duplicately-named routines must be compiled separately and are assumed to be on the local disk: ADVAN2 TEXT A, TRANS1 TEXT A, SSS TEXT A, SS2 TEXT A. Files BLKDAT TEXT A and ABLOCK TEXT A must exist also. |
CAUTION: Make sure there are no other TEXT files on the local disk with the same names as NONMEM, PREDPP, or NM-TRAN subroutines. Any such TEXT file will take precedence over the one in the TXTLIB. In particular, when using NM-TRAN library subroutines, make sure that files named PK TEXT A and ERROR TEXT A do not exist on the local disk.
To run NM-TRAN and NONMEM, a file named GO2 EXEC A is created, containing the commands:
&ERROR &EXIT FILEDEF 5 DISK &1 DATA A FILEDEF 6 TERMINAL ( LRECL 133 RECFM F FILEDEF &2 DISK &2 DATA A FILEDEF FDATA DISK FDATA DATA A FILEDEF FSTREAM DISK FSTREAM DATA A FILEDEF FLIB DISK FLIB DATA A FILEDEF FCON DISK FCON DATA A FILEDEF FSUBS DISK FSUBS FORTRAN A FILEDEF FREPORT DISK FREPORT DATA A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB TRAN LOAD NMTRAN ABLOCK ( START FILEDEF 5 DISK FCON DATA A FILEDEF 6 DISK &3 LISTING A ( LRECL 133 FILEDEF PRDERR DISK PRDERR LISTING A ( LRECL 133 FILEDEF FILE2 TERMINAL ( LRECL 133 FILEDEF &2 DISK &2 DATA A FILEDEF FDATA DISK FDATA DATA A FILEDEF FSTREAM DISK FSTREAM DATA A FILEDEF FLIB DISK FLIB DATA A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB NMD PPD TRLD LOAD NONMEM BLKDAT ADVAN2 TRANS1 SSS SS2 ( START
The user types a command such as the following:
GO2 CONTROL5 THEOPP REPORT5
(Any NM-TRAN control, data, and report file names could be specified in place of CONTROL5, THEOPP, and REPORT5.)
The NM-TRAN control file must contain the statements:
$DATA THEOPP $SUBROUTINES ADVAN2 LIBRARY
The data file name must be specified twice: as part of the command line and in the NM-TRAN $DATA record. The $SUBROUTINES record directs NM-TRAN to create the file FLIB containing instructions for the NM-TRAN library subroutines.
First, NM-TRAN is executed using CONTROL5 and THEOPP as input. Any NM-TRAN error messages appear at the terminal. If errors are found, the EXEC exits. Otherwise, the NONMEM-PREDPP executable is built and run. The library PK and ERROR subroutines are obtained automatically from TRLD TXTLIB A. Any intermediate output from the estimation step appears at the terminal. The output report appears in file REPORT5 LISTING A, along with any operating system error messages.
Note that two versions of the data file are made available to NONMEM: the original file (&2 DATA A), and a modified version (FDATA DATA A). NM-TRAN contains a data preprocessor which sometimes generates a modified version of the input data file. The commands shown will work equally well in both cases. The file control stream (FSTREAM DATA A) contains the appropriate ddname, FDATA or the name specified on the NM-TRAN $DATA record, for NONMEM’s use. However, if an input data file having a record length larger than 80 bytes is used, LRECL must be specified on both FILEDEF statements (&2 and FDATA).
With CMS, FILEDEF statements are not normally needed for NM-TRAN work file FWORK, or for NONMEM work files FILE07, FILE10-FILE25, and FILE32-FILE33. The files are automatically opened and deleted at the end of the run.
However, with IBM VS FORTRAN Level 2.5.0, a system warning message AFB201I may appear when the data file is large because this release of FORTRAN defines the default maximum unformatted record length to be 796. The default can be changed; e.g., see IBM Manual SC26-4339-4, VS FORTRAN Version 2 Installation and Customization for CMS Release 5, page 36. Alternately, you can include this FILEDEF statement prior to each NM-TRAN run:
FILEDEF FWORK DISK FWORK DATA A ( RECFM U LRECL 13000
You will also need to include FILEDEF statements similar to these prior to each run of NONMEM:
FILEDEF FILE07 DISK FILE07 DATA A ( RECFM U LRECL 13000 FILEDEF FILE10 DISK FILE10 DATA A ( RECFM U LRECL 13000 FILEDEF FILE11 DISK FILE11 DATA A ( RECFM U LRECL 13000 ...
(No harm is done by specifying 13000, which is larger than needed. The precise record lengths are described in Chapter IX.)
To run NM-TRAN, compile the subroutines, build a NONMEM-PREDPP executable, and execute it, a file named CGO2 EXEC A is created, containing the commands:
&ERROR &EXIT FILEDEF 5 DISK &1 DATA A FILEDEF 6 TERMINAL ( LRECL 133 RECFM F FILEDEF &2 DISK &2 DATA A FILEDEF FDATA DISK FDATA DATA A FILEDEF FSTREAM DISK FSTREAM DATA A FILEDEF FLIB DISK FLIB DATA A FILEDEF FCON DISK FCON DATA A FILEDEF FSUBS DISK FSUBS FORTRAN A FILEDEF FREPORT DISK FREPORT DATA A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB TRAN LOAD NMTRAN ABLOCK ( START EXEC FORTVS FSUBS FILEDEF 5 DISK FCON DATA A FILEDEF 6 DISK &3 LISTING A ( LRECL 133 FILEDEF PRDERR DISK PRDERR LISTING A ( LRECL 133 FILEDEF FILE2 TERMINAL ( LRECL 133 FILEDEF &2 DISK &2 DATA A FILEDEF FDATA DISK FDATA DATA A FILEDEF FSTREAM DISK FSTREAM DATA A GLOBAL TXTLIB VSF2LINK VSF2FORT CMSLIB NMD PPD LOAD NONMEM BLKDAT ADVAN2 TRANS1 SSS SS2 FSUBS ( START
The user types a command such as the following:
CGO2 CONTROL5 THEOPP REPORT5
(Any NM-TRAN control, data, and report file names could be specified in place of CONTROL5, THEOPP, and REPORT5.)
The NM-TRAN control file must include one
of these statements, depending on the precision†:
----------
$SUBROUTINES ADVAN2 DOUBLE $SUBROUTINES ADVAN2 SINGLE
This directs NM-TRAN to create the file FSUBS containing FORTRAN subroutines. As before, NM-TRAN is executed using CONTROL5 and THEOPP as input. Any error messages appear at the terminal. If errors are found, the EXEC exits. Otherwise, the file FSUBS FORTRAN A is compiled and linked with NONMEM-PREDPP and the resulting executable is executed. As described for the two-step example, the data file name must be specified on the command line and in the NM-TRAN $DATA record. The output report appears in file REPORT5 LISTING A, along with any operating system error messages. If system warning message AFB201I appears, FILEDEF statements for NM-TRAN work file FWORK and NONMEM work files FILE07, FILE10-FILE25, and FILE32-FILE33 may be needed; see the discussion in the previous example.
The command files should now be tested using the NM-TRAN control stream and data file used in Chapter V, Section 5, which are file "CONTROL5" and file "THEOPP" from the distribution medium. A complete test can be run as shown above. Compare the NONMEM output with that referenced in Chapters III and IV. Remember that slight differences from the published output are expected during the estimation step, but that the final parameter estimates should be the same.
Certain optional files can be generated by NONMEM at the users request. These files are discussed in Chapter IX, Section 2. If optional files are used, the CMS examples should be modified to include appropriate FILEDEF statements unless CMS’s default file names and characteristics are acceptable. Table Files in particular should have FILEDEF statements specifying LRECL 132.
For CMS, a suite of command files should be made available, one for each analytic ADVAN and (if desired) TRANS combination. (The analytic ADVAN routines are ADVAN1-4 and ADVAN10-12). For example, to use ADVAN1 with TRANS2, you could use a different command file named (in UNIX) cgo12 or (in CMS) CGO12 EXEC A. These should be identical to the above examples, except for the substitution of a different name (other than ADVAN2 and TRANS1) for the ADVAN and TRANS subroutine.
In the simple cases illustrated in this chapter, the NONMEM-PREDPP executable always consists of the same set of subroutines (other than different ADVAN, TRANS, and possibly SS routines). This will not always be the case.
First, when general models (ADVAN5-9) are used, additional subroutines must be selected from the PREDPP library. Second, it is sometimes necessary to include steady state routines, though this should be done only when necessary. Finally, user-supplied subroutines may be substituted for NONMEM-PREDPP routines, as described below.
When building a more complicated type of NONMEM-PREDPP executable there are several considerations.
Commands to build the executable can be based on the written documentation in Chapter VII of NONMEM Users Guide, Part VI, which describes the various combinations of PREDPP subroutines that can be used.
Alternately, the information in the FREPORT file can be used. This not only describes choices from the PREDPP library but also substitutions for default NONMEM and/or PREDPP routines. A preliminary run (involving NM-TRAN only) can be performed to obtain the FREPORT file. The information in FREPORT can be used to develop the commands which build the executable.
The most sophisticated approach is to use the FREPORT file directly as input to a command file or program which builds the executable from this input. This provides the maximum flexibility. Coding such a routine is not simple, however. It may be easiest to start with utility program NMLINK6 and make modifications as needed for the local operating system. Note that the format of lines in FREPORT containing 8-character subroutine names is (8(1X,A8)). If any subroutine name exceeds 8 characters, then all subroutine names are on separate lines, each with format (1X,A78).
It may be best if that NM-TRAN not copy user-supplied subroutines to the FSUBS file; see Chapter V, Section 2.1.2. This is especially true when user-supplied subroutines in both object and source form are to be used, and both types of modules are sometimes specified on the $SUBROUTINES record.
Users may choose to substitute their own
subroutines for certain default NONMEM-PREDPP routines, as
follows:
NONMEM routines: CRIT, MIX.
PREDPP routines: INFN and TRANS.
Users may also supply their own complete PK, ERROR, MODEL, DES, and AES subroutines, 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. In CMS, if TXTLIBs are used, it is possible to substitute for any subroutine if the corresponding TEXT file exists on the local disk.
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:
|
1) |
Substitutions are documented in the FREPORT file, which contains a complete description of the composition of the NONMEM-PREDPP executable. If generated subroutines are produced, FREPORT also describes their precision (single or double). |
|
2) |
All user-supplied subroutines are copied to file FSUBS, to help in the construction of the actual executable. In CMS, an appropriate FILEDEF statement must be present to connect the filename given on the $SUBROUTINES record, which is a ddname, to the actual disk file. |
|
CMS: $SUBROUTINES .... PK=PK10 ... CMS command: FILEDEF PK10 DISK PK10 FORTRAN A |
If the FSUBS file is always compiled and the resulting object code is included in the executable, as in Case II, this will automatically include the object code for user-supplied subroutines. In CMS, this code will automatically take precedence over default versions in TXTLIBs.
The NM-TRAN control file may contain one or more lines of the form
INCLUDE filename
The file with name "filename" is an NM-TRAN include file. NMTRAN opens the include file, reads it to end-of-file and includes it 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. With CMS, filename is a DDNAME. A file definition statement is needed to connect it to an actual disk file. If no file definition statement is provided, the file opened defaults to "FILE filename A".
A choice must be made between storing executables on disk for re-use versus recreating them as needed. Various considerations that affect this choice are discussed in this section, to which you may return after a reasonable amount of experience has been obtained with the NONMEM system.
In certain computer systems, the amount of time spent compiling and building a executable may sometimes be very large compared to the actual NONMEM run time (e.g., during preliminary "data check out" runs). Use of pre-existing executables for such runs may be desirable. When, in particular, NM-TRAN library subroutines are used, it is possible to build a general-purpose executable for NONMEM-PREDPP with a given ADVAN and TRANS combination and make repeated use of the executable. This is what is done in the UNIX two-step example in this chapter, for example. (In CMS, the GENMOD command can be used in a similar manner to build a re-usable MODULE file.) However, if there are to be a number of different executables existing simultaneously, corresponding to different ADVAN and TRANS combinations, the amount of disk storage used for such executables may become excessive. (See Table 1.1 in Chapter I.) If disk space is limited, it may better to erase each executable after use and re-create it as needed. (The command files of the examples can be modified to do the erasure automatically.)
Even if disk storage is adequate, and even if pre-existing modules are useful during preliminary stages of a study, it may be preferable to use generated subroutines for lengthier NONMEM runs. The compile and load time may be small compared with the improvement in run time when NM-TRAN library subroutines are not used. It may also happen that NM-TRAN abbreviated code is too restrictive for some studies and user-supplied code is required. Some installations may choose to make both options available: pre-existing general-purpose executables and specially-generated executables.
A version of nmfe6 or nmfe6.bat where the line starting $f (nmfe6) or %f% (nmfe6.bat) is deleted re-uses the existing NONMEM executable module.
When a pre-existing executable is used, the new runs may include different NONMEM initial estimate records, task specification records, or may specify a different data set. If NM-TRAN library subroutines were used in the creation of the pre-existing module, the abbreviated code may change, as may the order of data items listed in the $INPUT record. If generated subroutines were used in its creation, the abbreviated code may not change, nor may the order and position in the $INPUT record of those of data items referenced in the abbreviated code.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...