Chapter I - Introduction
This guide describes how to install and test the NONMEM system, which consists of NONMEM Version VI, PREDPP Version V, and NM-TRAN Version IV. They are referred to collectively as NONMEM VI. The NONMEM system is distributed as FORTRAN 77 source code. There is only one version of NONMEM VI; this guide tells how to modify the source code in order to customize it for your computer and your operating system.
The first chapter describes system and compiler requirements and discusses certain decisions that must be made before installation begins. Later chapters give step by step instructions for installing the major components of the system, testing them, and running them.
For certain commonly used platforms, short-cut installation procedures described in Appendices 3-5 may be followed rather than the step by step procedure outlined in the remaining chapters of this guide. Please first examine these appendices and determine whether they apply to your system and compiler.
If the short-cuts cannot be used on your system, or if modifications are required to adapt the short-cuts to your system, it is best to review the step by step procedure outlined below and in the remaining chapters of this guide.
Please follow these steps when installing the NONMEM system:
|
1. |
Read Chapter I of Users Guide, Part V. It describes the various components of the NONMEM system and how they are used. Please familiarize yourself with the components of the NONMEM system and how they relate to each other. (Alternately, read Appendix 1 of the document you are reading now, in which the relevant material is reproduced.) |
|
2. |
Review the remainder of this chapter. Be sure that your system has sufficient memory and disk space before you start, and that you have all the necessary documents. |
|
3. |
Review decisions described in this chapter. The people who will use NONMEM should be consulted on these decisions. |
|
4. |
Follow the instructions in the remaining chapters of this guide. Be sure to test each component of NONMEM immediately after you install it. If you put testing off until the end, it will be very hard to track down the cause of errors. |
|
5. |
If any questions or persistent problems arise regarding installation, please phone the NONMEM consultant at (410) 696-3098 between the hours of 8:00AM and 5:00PM EDT, or preferably send electronic mail to: |
|
6. |
You may also ask questions of other NONMEM users by way of the NONMEM Users Network, described in Section 6. |
Please do not make ANY changes to the source code other than the ones described in this guide without first talking to the NONMEM consultant. Unless such changes are approved, the NONMEM consultant cannot help you with problems which may arise. The NONMEM consultant is familiar with the problems you will encounter during the installation, and will be able to suggest the best fix for your situation.
The size of a NONMEM executable ("load module") varies considerably, depending on which optional routines are included. However, all modern computers can run NONMEM VI easily.
For more detailed information regarding the memory requirements for NONMEM V-PREDPP IV see NONMEM Users Guide, Part VI Appendix II, but be aware that the requirements for NONMEM VI are greater.
The compiler must implement the ANSI FORTRAN 77 standard. Most FORTRAN 90 compilers implement this standard because FORTRAN 77 is a subset of FORTRAN 90. If a FORTRAN 90 compiler is used, references to FORTRAN 77 in this guide should be understood as references to FORTRAN 90. The Essential Lahey Fortran 90 Compiler does not support the complete Fortran 90 standard and is not suitable for use with NONMEM, although other Lahey Fortran compilers can be used. In addition the compiler must implement certain other features:
|
1. |
It must allow the default length of integer variables to be 4 bytes. All subroutines must be compiled with the default length of integer variables as 4 bytes. |
|
2. |
It must support hollerith constants and hollerith format specifications. |
|
3. |
It must allow the assignment of hollerith constants to integer variables in DATA statements. |
|
4. |
It must allow variables of different types to share the same storage area using the EQUIVALENCE statement. |
|
5. |
It is desirable that floating point underflow be permitted to occur silently, but only if the resulting value is set to zero; this is the default action specified by the IEEE 754 standard for floating point arithmetic. See also Chapter III Sections 2.1.3 and 2.10.† |
|
---------- |
|
6. |
It must allow the FORTRAN INCLUDE statement. It is an extension to many FORTRAN 77 systems, and is part of the FORTRAN 90 language. If your system does not permit INCLUDE statements, please contact the NONMEM consultant. |
|
7. |
The loader must set uninitialized data to zeros. (This is the default on most systems.) |
NONMEM run-times vary greatly, depending on the amount of data and the complexity of the model. Extensive use is made of floating point arithmetic, so it is necessary to have a floating point (math) processor. With most modern machines, simple problems with moderate size population data sets, such as are used in the various examples in the Users Guide, will run in a reasonable amount of time (no more than an hour, often much less). With more complicated problems, run times can be as much as 10 hours or more. Machines with speeds of 1 GHz or more are preferred.
See the readme file on the distribution medium for advice on problems that are due to an incorrect Fortran installation or configuration. Prior to installing NONMEM a test of your compiler is appropriate to assure that your compiler is properly configured. An example of such a test is given in the readme file.
The NONMEM system is read from the NONMEM distribution medium in the form of FORTRAN 77 source code. Chapter II describes the number of bytes of storage required for each file on the medium. After compilation, the source code can be deleted from disk and only read back when necessary, e.g., when bug fixes are to be applied. On most systems, the compiled object code (binary code) occupies more disk space than does the original source code. In general, at least 40 megabytes of disk storage are desirable during the installation of NONMEM. Additional storage will be needed for the user files: input data files, output reports, etc.
As an illustration, consider an example
using a theophylline data set which is presented in Users
Guide IV. The data are from 12 subjects, with 11 plasma
concentrations per subject. The example uses the one
compartment model with first-order absorption. For purposes
of comparison, the problem was run using a user-supplied
PRED code, PREDPP with ADVAN2, PREDPP with ADVAN7, and
PREDPP with ADVAN6. NM-TRAN and double-precision NONMEM were
used for all runs. The control and data files are present on
the distribution medium as files THEO, THEOPP, CONTROL4,
CONTROL5, CONTROL6, CONTROL7. and are discussed in Chapter
X, Sections 4 and 5.
NONMEM V was used for all runs.
A Sun Microsystems SS/ELC (4/25FM) with 16MB memory and SunOS 4.1.4 (Solaris 1.1.2) was used. The manufacturer’s rating for this machine is 33-MHz, 20.3 SPECmarks, 23.7 MIPS, 3.4 MFLOPS. In these runs, we used Sun FORTRAN 1.4 with options requesting static libraries and full optimization (-Bstatic -cg89 -O4 -dalign -libmil).
This table shows the CPU time required (in seconds), the size of the executable program as stored on disk (in kilobytes), and the run-time memory requirement, including text, constants, and arrays (in kilobytes):
A Sun Microsystems Ultra 2 model 1300 with 132MB memory and SunOS 5.5.1 (Solaris 2.5.1) was used. The manufacturers rating for this machine is 300-MHz, 12.1 SPECint95, 1.5 SPECfp95. In these runs, we used Sun FORTRAN 4.0 with options requesting static libraries and full optimization (-Bstatic -fast -xO4 -xtarget=ultra -xarch=v8plus -xdepend -lmopt -lm).
A Dell 5100/GMT PC with 16MB memory and Microsoft Windows 95 was used. The manufacturers rating for this machine is 100-MHz. In these runs, we used DIGITAL Visual Fortran 5.0 with options /optimize:1 /fpe:0 The run-time memory requirement is not available. (The same problems were run with DIGITAL Visual Fortran 5.0 and Microsoft Windows NT, and the performance is almost identical.)
Run times on other computers should in general be approximately inversely proportional to MHz (Megaherz). That is, a computer with half the MHz rating should take roughly twice as long.
All other volumes of the NONMEM Users Guide should be available for reference as needed during the installation process. In particular, examples of input and output to be used as test cases during the installation are found in NONMEM Users Guide, Parts I and VI. The inputs are recorded on the distribution medium. The results files can be found at
ftp://ftp.globomaxnm.com/Public/nonmem/output
The additional documentation is:
Part I - Users Basic Guide A step by step discussion of various NONMEM features and statistical concepts involved in using NONMEM, including examples of data analyses.
Part II - Users Supplemental Guide A continuation of Part I which includes some special features of NONMEM.
Part IV - NM-TRAN Guide A complete reference guide to NM-TRAN (which includes the Data Preprocessor).
Part V - NONMEM-PREDPP Introductory Guide A guide for beginning users of NONMEM-PREDPP. A NONMEM user should read the Introductory Guide first.
Part VI - PREDPP Guide A complete reference guide to PREDPP.
Part VII - Conditional Estimation Methods A description of these methods and some guidelines for their use.
Part VIII - Help Guide A fast way to locate information on a given word or topic. The content of the Help Guide is also supplied on the NONMEM distribution medium for on-line use.
NONMEM V Supplemental Guide Describes changes found with NONMEM V of which the user should be aware, especially if he used earlier versions of NONMEM.
Introduction to Version VI Describes changes and new features found with NONMEM VI of which the user should be aware, especially if he used earlier versions of NONMEM. The NONMEM Distribution medium contains files readme_6.1.0.doc and readme_6.1.txt (Unix: readme~1.doc and readme~1.txt). (The names may change with future releases.) The ".doc" file may be viewed with Microsoft Word; the ".txt" may be viewed with a text editor. You may print them. Their content is identical. The "readme" contains important information that was developed too late for inclusion in this guide, and also contains instructions on the shortcut method of installing NONMEM. Be sure to read it.
Emails and Technical Newsletters From time to time, emails and technical newsletters are sent to all current NONMEM licensees. These describe how to fix bugs discovered in the code and may give hints and suggestions on the installation and use of the system. Please be sure to review all emails and technical newsletters, if any, that accompany the NONMEM distribution medium. If you think you may be missing relevant newsletters, please call the NONMEM consultant.
See also Section 7 of this chapter for a list of internet sites from which bug memos and fixes may be obtained.
With NONMEM VI, NONMEM and PREDPP exist on the distribution medium in only one version: double precision (DP).
Some scientific workstations are described as having "64 bit architecture". This typically describes the width of the data bus, not the size of the floating point word, which is 32 bits. Double precision is recommended for such machines.
On some large scientific computers (e.g., CRAY X-MP, Cyber 205), however, single precision affords precision comparable to double precision on general-purpose computers; double precision arithmetic is generally not used or recommended for these machines. If you have such a computer, please contact the NONMEM consultant.
Some users may choose to write their own PRED subroutines. A user-supplied PRED subroutine can be tailored to the specific prediction model of interest, which may not involve pharmacokinetics at all. Even if it does implement a pharmacokinetic model, it can be tailored to the specific kinds of dosing and modeling required for the problem, and in general will require less storage and run faster than will PREDPP. Most users, however, will use NONMEM for pharmacokinetic data analysis and will want to use PREDPP. Such users will need to install PREDPP.
Users are not required to install or use NM-TRAN. However, we recommend the use of NM-TRAN. It facilitates the use of NONMEM for both new and experienced users. It obviates the need for the user to develop code for partial derivatives. It provides extensive error checking.
NONMEM input may be prepared using NM-TRAN on an interactive system for later execution in a batch or background environment. NM-TRAN (which is itself a batch program) runs quickly and, on an interactive system, errors can be corrected quickly.
In the following chapters, complete examples of operating system commands and features are given for three commonly-used operating systems: IBM CMS (specifically, IBM VM/XA2.1 VM/CMS 5.6, using VS FORTRAN Level 2.5.0), UNIX (specifically, SunOS 4.1.4, a variant of 4.2BSD, using Sun FORTRAN 3.0.1), and MS-DOS (specifically, an MS-DOS window running under Microsoft Windows 95 or NT, using Microsoft PowerStation Fortran and DIGITAL Visual Fortran 5.0). MS-DOS examples can also be used with Microsoft Windows XP and Vista.
The UNIX examples all use commands common to both the C-shell and Bourne shell, except where indicated. These examples appear in boxes. Text not boxed generally applies to any operating system environment.
Only UNIX, CMS and MS-DOS examples are included because these are the only operating systems with which we have first hand experience. NONMEM has been installed under a variety of other operating systems.
The examples, suitably modified for local differences, may suffice for many users. For other operating systems, they may be helpful as samples of what can be done. For example, NONMEM VI has been installed on a MacBook Pro running OS X using the UNIX/Linux installation instructions.
People who are proficient in the use of their local operating system may well choose to do things differently.
Some special help is given occasionally for users with operating systems other than CMS, UNIX, and MS-DOS, and compilers other than the ones mentioned above. In particular, VAX/VMS and OPEN/VMS users, and users of Watcom FORTRAN 77, should look in the index at the back of this document. Entries for "VAX VMS" and "Watcom" will help you find suggestions sent to us by other users of these products. We cannot guarantee their accuracy or applicability to your particular situation.
Some operating systems allow a collection of compiled subroutines to be stored in a single file or repository called a "subroutine library", or "binary library." Typically, the system loader can automatically select from such a library only those subroutines needed to satisfy the external references encountered during the construction of a given executable. It is very convenient to use such libraries because they simplify the commands needed to build NONMEM-PREDPP executables. If your operating system includes a means of storing programs in a binary library, we suggest that you take advantage of the feature.
In CMS, subroutine libraries are called TXTLIBs and all CMS examples in this guide depend on their use. Some versions of UNIX allow users to store binaries in library archives (".a" files) using UNIX commands ar, ranlib, etc. The examples in this guide depend on their use.
You and the NONMEM users at your site are invited to participate in the NONMEM Users Network. It is an electronic mailing list, not a news group. A user with a question, remark, or discussion which he believes might interest or help other NONMEM users sends the item to a single e-mail address. The item is automatically broadcast to every e-mail address on the network. The mail is not reviewed by anyone before it is broadcast. The NONMEM Users Network helps users worldwide communicate with each other, share information, and solve problems. In addition, technical newsletters describing bug fixes may be sent via e-mail to the network, as well as by ordinary (paper) mail to all licensees.
To be added to the mailing list (or to be removed from it), please send a request containing your e-mail address to: nmusers-request@globomaxnm.com.
Thereafter, to send an item to the network, send it to: nmusers@globomaxnm.com.
You may send questions to the network even if you are not actually on the mailing list, but be sure to include your e-mail address for replies.
Bug lists may be found at the following sites:
http://www.globomax.com/nonmem.htm ftp://ftp.globomaxnm.com/Public/nonmem/NONMEM_V_buglist ftp://ftp.globomaxnm.com/Public/nonmem/NONMEM_VI_buglist
Licensed NONMEM users may obtain copies of fixed routines in the following password-protected ftp site:
ftp://ftp.globomaxnm.com/Public/nonmem/NONMEM_VI_fixed_routines
With NONMEM VI 1.1 (Feb 2007) the login and password are as follows:
login: nonmemvi password: updates
These may be changed. If you cannot login, please contact the NONMEM consultant.
TOP TABLE OF CONTENTS NEXT CHAPTER ...