Chapter VI - How to Install the NM-TRAN Library Subroutines (Optional)
NM-TRAN users can choose how abbreviated code is implemented. Generated FORTRAN subroutines which must be compiled and linked with NONMEM before the actual NONMEM run can be used, or subroutines from the NM-TRAN Library that read a file of instructions generated by NM-TRAN can be used.
An advantage of using library subroutines is that a pre-existing executable can be used. The computer time spent compiling and linking can be avoided. However, the resulting executable will be larger and slower to execute than when generated code is used.
Another advantage to using library subroutines is that, in a multi-problem run, different abbreviated code may be used in different problems. With generated code, all problems subsequent to the first must implement the identical abbreviated code (although such code can test the problem number in conditional statements and can implement different models depending on the problem number).
Examples are given in Chapter VII of the use of NONMEM-PREDPP with both generated and library subroutines.
It is not necessary that both choices be available. You may, for example, choose to save the disk space required for the library subroutines and for pre-existing executables and skip this chapter entirely.
If NM-TRAN library routines are to be installed, file "TRLD" version is assumed to have been read from the distribution medium. UNIX users might work in a dedicated directory, called (say) /export/home/nmvi/tl. MS-DOS users might work in a dedicated directory, called (say) c:\nmvi\tl. CMS users can safely work in the same disk area as in Chapter III, PROVIDED they take care not to replace the PREDPP PRED subroutine; see Section 1 below.
It is also assumed that you have already read the file SIZES from the NONMEM distribution medium into the directory above the TRLD directory, as discussed in chapters 2 and 3
This chapter guides you through the following steps.
|
1. |
Separate the file into smaller files. |
|
2. |
Make any required changes to the source code. |
|
3. |
Compile the subroutines. |
Note that a test of the library subroutines is deferred to Chapter VII, in which NM-TRAN and NONMEM-PREDPP are run in sequence.
There are 9 library subroutines: PRED, PK, ERROR, DES, AES, MODEL, TOL, MIX and INFN. (INFN is new to NONMEM VI.) The subroutines should be separated, either using an editor or using the program SEP. It makes no difference if SEP or SEPG77 is used. It is easiest to use whichever was used for NONMEM. Be sure to first save the source code for PREDPP’s PRED subroutine temporarily under a different name or in a different directory so that it is not replaced by the PRED subroutine from the NM-TRAN Library.
UNIX:
sep < TRLD
|
MS-DOS: |
sep < trld
|
CMS: |
FILEDEF 5 DISK TRLD DATA A LOAD SEP ( START RENAME FILE PRED A FILE PRDLIB A LIST FILE ( EXEC RENAME CMS EXEC A TRLD EXEC A TRLD EXEC REN
Because FILE PRED A was renamed FILE PRDLIB A, the file PRDLIB FORTRAN A is created. This contains the NM-TRAN Library PRED subroutine.
Certain constants are used by the NM-TRAN Library subroutines to control array sizes, and may be changed by the user. These constants are set by PARAMETER statements in the include file SIZES. Constants that are changed in SIZES take effect only after all of the NM-TRAN Library subroutines have been recompiled.
Note that NONMEM and PREDPP and NM-TRAN also share the include file. Certain constants are common to more than one of these components. 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.
Parameters LTH and LVR appear in the include file SIZES. They are discussed in Chapter III, Section 2.9, and in Appendix 2.
NM-TRAN error message 288 described in Chapter V requires changes to the parameter LNP4.
Failure to change LNP4 to correspond with the value in NM-TRAN and NONMEM will cause the NONMEM run to fail with messages such as:
LIBRARY PRED SUBROUTINE: LNP4 IS TOO SMALL
After changing the value of LNP4 in SIZES, recompile the library subroutines and rebuild the NONMEM executable.
Parameter NO appears in the include file SIZES. It is discussed in Chapter III, Section 2.9, and in Appendix 2.
Parameter PC appears in the include file SIZES. It is discussed in Chapter IV, Section 1.3, and in Appendix 2.
Library subroutines use certain fixed-length arrays as internal tables. These arrays are large enough for typical use of NM-TRAN. However, if the amount or complexity of the abbreviated code is large, error messages may occur either during the NM-TRAN step or from a library subroutine itself at the start of the actual NONMEM run. The following parameters in include file SIZES define the sizes of the arrays:
PARAMETER (DIMTMP=150) PARAMETER (DIMCNS=50) PARAMETER (DIMNEW=600) PARAMETER (DIMRV=350*LVR) PARAMETER (DIMQ=400)
NM-TRAN error messages 198, 199, 212, 226, 294 and 393, described in Chapter V, require changes to parameters DIMTMP, DIMCNS, DIMNEW, DIMRV, and DIMQ in the include file SIZES. It is best to change these parameters immediately in SIZES and recompile the library subroutines whenever they are changed in SIZES.
However, it is possible that a given control stream may still work with the unmodified library subroutines because, with this control stream, NM-TRAN uses fewer positions in an array than it might. If there is a genuine problem, the NONMEM run will fail with error messages such as:
LIBRARY PRED SUBROUTINE: DIMTMP IS TOO SMALL LIBRARY PRED SUBROUTINE: DIMCNS IS TOO SMALL LIBRARY PRED SUBROUTINE: DIMNEW IS TOO SMALL LIBRARY PRED SUBROUTINE: DIMRV IS TOO SMALL LIBRARY PRED SUBROUTINE: DIMQ IS TOO SMALL
Modify SIZES. Change the values of the parameter in question to the value used in NM-TRAN. Recompile all NM-TRAN library subroutines and rebuild the NONMEM executable.
The NONMEM run may fail with error messages such as:
LIBRARY PRED SUBROUTINE: DIMTOK IS TOO SMALL LIBRARY PK SUBROUTINE: DIMTOK IS TOO SMALL LIBRARY ERROR SUBROUTINE: DIMTOK IS TOO SMALL LIBRARY DES SUBROUTINE: DIMTOK IS TOO SMALL LIBRARY AES SUBROUTINE: DIMTOK IS TOO SMALL
If such a message occurs, locate the following statement in SIZES:
PARAMETER (DIMTOK=7000)
Change the value 7000 to some larger value. Recompile all NM-TRAN library subroutines and rebuild the NONMEM executable.
NM-TRAN creates a file of instructions with default file name FLIB, which is read by the library subroutines at the start of the NONMEM run. The FORTRAN unit number used by the library subroutines for this file is 41. To change the unit number, locate this line of code in SIZES and change 41 to the desired value:
PARAMETER (FL=41)
Recompile all the library subroutines and rebuild the NONMEM executable.
If the name of the control file for the library subroutines is changed in NM-TRAN’s block data routine ABLOCK (see Chapter V, Section 2.1), the name must also be changed in SIZES. Locate this line of code in SIZES and change constant ’FLIB’ to the same name as in NM-TRAN’s ABLOCK:
PARAMETER (FLIB=’FLIB’)
When bugs are found in NM-TRAN library subroutines, the fixes are described in emails and technical newsletters. Please check any emails or newsletters that may have been sent with the NONMEM distribution medium or that are received afterwards. You will have to modify the source code and recompile the library subroutines.
See also Chapter 1, Section 7, for internet sites of interest.
You should now compile the library subroutines using a FORTRAN 77 compiler. Compile each subroutine separately and save the resulting object code for later use. No warning or error messages are expected. If error messages are produced, please phone the NONMEM consultant before you attempt to fix the source code yourself. The object modules can be saved in a binary library. In CMS, say, use TRLD TXTLIB A. (You must keep the NM-TRAN library PRED subroutine separate from PREDPP’s PRED subroutine.)
|
UNIX: |
f77 -O -c *.f >& emsgs.txt
|
MS-DOS: |
Using PowerStation Fortran:
fl32 /c /G4 /Ox /Op *.for > emsgs.txt
Using DIGITAL Visual Fortran:
df /c /optimize:1 /fpe:0 *.for >
emsgs.txt
|
CMS: |
Make a file called ADDTRLD EXEC A containing the statement:
TXTLIB ADD TRLD &2
Input the following commands:
TRLD EXEC COMPILE TXTLIB GEN TRLD AES TRLD EXEC ADDTRLD TRLD EXEC ERASE2 ERASE * LISTING
Note that the PRED subroutine was saved in TRLD TXTLIB A under the name PRDLIB. However, the entry name is PRED and it can be retrieved from the library by the loader as needed.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...