WFN and NMQual

Last Updated 13 August 2007

NMQual should be used by all NONMEM users to ensure their source code is up to date and patched correctly.

There are several things to consider when you use NMQual:

1. Installing Perl

NMQual requires you to use Perl. You can download perl from ActivePerl . After installing perl you will need to download and install the XML-Xpath package. You can do this using PPM. The PPM (Perl Package Manager) connects to the internet and searches for the package. If this fails e.g. because of local firewall then it is possible to copy the contents of Perl\site\lib\XML\XPath from an existing installation to the equivalent destination on the target machine.
PPM downloads the Xpath package and installs it. You may need Administrator privileges to get through firewalls.
To run ppm you can open a Windows Command prompt window eg. Click on Start the Run then type 'cmd' in the Run box and press enter.
When you see the command prompt it shows the current drive and directory path and ends in a ">" e.g.
c:\>
At the Windows command prompt type 'ppm' then press enter eg. it might look like this:
c:\>ppm <--- ppm is typed at the command prompt
A PPM window will open (Perl Version 5.8.8)

If you get a file not found error message then this probably means you don't have your perl\bin directory in the search path. You will need to have it in your path if you want to used NMQual. The ActivePerl installer will add it to your path by default.
Wait for the database to finish loading.
Select View All Packages
Scroll down to find the XML-XPath package
Select it and right click and select for Install
Click on green right arrow in toolbar to Install (or click on File Run Marked Actions)

Wait for XML-XPath to download and install.
Quit from PPM.

You should now be able to use NMQual.

2. NMQual Used to Patch and Compile NONMEM

NMQual patches the source code to get a consistent patch level and compiles a new installation of NONMEM. You can run the NMQual installation without using the special NMQual front end that checks the integrity of the installation every time you run it.

Follow the instructions supplied with NMQual to patch and compile NONMEM. After successful compilation you can use WFN with the NMQual compiled NONMEM. Make sure you have changed wfn.bat to set NMHOME to the NMQual target directory.

3. NMQual Used to Run NONMEM

After NMQual has been used to patch and compile NONMEM it is possible to use NMQual to run NONMEM. NMQual checks that the object code has not been changed since the installation and provides an extra level of qualification. Note that this does take a little big longer for each run and the resulting output listing file from NONMEM is bigger.
I have tested NMQual with WFN and updated WFN to be able to work with it. It requires you to use WFN for NONMEM V version 409 (or later) or WFN6 for NONMEM 6. You must make a change to a new version of wfn.bat derived from wfn.txt (supplied with these NMQual enabled versions of WFN) to allow it to run the NMQual version of NONMEM. I have tested NMQual with df, g77, gfortran and ivf compilers.
In wfn.bat you need to specify the name of your NMQual target in wfn.bat. After the 'set F77VER' line in wfn.bat you should insert 'set NMQUALVER' with the name of your NMQual target e.g.
set F77VER=g77
set NMQUALVER=std
The NMQual target is the name of the directory containing NONMEM after you run NMQual. If NMQual installs NONMEM in c:\mynonmem\std then the value of NMQUALVER needed by wfn.bat is std. Note that the target directory is NOT the directory used to install the NMQual files. It is created by NMQual when you run the NMQual.p perl script.

4. WFN Used to Run NONMEM without NMQual that was installed by NMQual

Because of the way that NMQual modifies the NONMEM output file listing not all the information is correctly retrieved by WFN when it finishes and displays the final results. This is one of the reasons I do not like to have NMQual involved in actually running NONMEM.

WFN will run NONMEM normally and will not invoke the NMQUAL std.pl script to do all the extra work if you unset NMQUALVER in wfn.bat ie.

set nmqualver=

Setting NMQUALVER is only needed when you use nmqinstall.bat to install NONMEM with NMQual.

5. Multiple Compiled Versions of NONMEM

It is possible to use WFN to make NMQual install multiple compiled versions of NONMEM for use with Wings for NONMEM.

Several things are required:
1. Working installation of WFN with NONMEM and associated Fortran compiler
2. Files in NMQ4WFN.exe extracted into a directory such as wfn6\NMQ4WFN
3. Before using the nmqinstall.bat file (e.g. extracted to wfn6\NMQ4WFN) it is necessary to change wfn.bat to support multiple compiled versions and compilers.

Older WFN Versions

If you using a version of WFN before WFN601 then find the lines in wfn.bat.

rem *******************************
rem Wings for NONMEM Initialization
rem *******************************

Below these lines insert two lines with variables to specify the NONMEM version and patch date e.g. use this for NONMEM VI and a patch date of 14 June 2007.

rem *******************************
rem Wings for NONMEM Initialization
rem *******************************

set NMVER=6

set NMVERDATE=20070614

If you want to use NMQual with NONMEM V then set NMVER=5.

The NMVERDATE is not critical but can be useful if it is set to the date of the last patch for NONMEM used by NMQual.

All WFN Versions - IMPORTANT

For all versions of WFN find the following line in your wfn.bat:

rem * Uncomment for Multiple Compiled Versions and Compilers *

Replace the existing NMBINHOME line as follows:

rem * Uncomment for Multiple Compiled Versions and Compilers *
set NMBINHOME=%NMHOME%\ver%NMVER%_%NMVERDATE%\%F77VER%\%NMOBJ%

Save wfn.bat.

After changing wfn.bat you must check and change nmqinstall.bat so that NMQual can find its files and the NONMEM source files and perl can be run.
NMQSRCHOME path must indicate the directory containing the NMQual files (e.g. config.template.xml).
NMDISTHOME path must indicate the directory containing the NONMEM source files either on a CD-ROM drive or other disk drive. Note that this NMQual must have access to the original files or an exact copy. It will not work with the source files from a standard NONMEM installation created with setup.bat. You can select distribution source directories for NONMEM V (NMVER=5) and NONMEM VI (NMVER=6). The choice of NONMEM version will be made based on the setting of NMVER in wfn.bat.
PERLHOME path must indicate the directory containing your perl installation with a 'bin' sub-directory.

rem ******** Check Paths *************
set NMQSRCHOME=C:\nmvi\wfn6\NMQ4WFN\nmqual-6.2.0
if '%NMVER%=='5 set NMDISTHOME=D:\NONMEM_V.1.1
if '%NMVER%=='6 set NMDISTHOME=D:\NONMEM_6.1.0
set PERLHOME=C:\perl
rem ******** End Check Paths *************
You can selectively install different compiled versions of NONMEM by changing the list of versions in the set VERSIONS line in nmqinstall.bat
rem ******** Check Versions *************
set VERSIONS=std s70 500 570
rem ******** End Check Versions *************

Save nmqinstall.bat after making changes.

In order to select the desired NONMEM compilation version it is necessary to change the WFN shortcut target so that the specific compiler and compilation version are selected e.g. to use the g77 compiler with the std compilation version the shortcut target should look like this:

%SystemRoot%\system32\cmd.exe /k c:\nmvi\wfn6\bin\wfn.bat g77 std

You can choose to start with a different NONMEM compilation version by changing 'std' to one of the other version types (s70, 500 and 570).

After making changes to wfn.bat and nmqinstall.bat you should then open a new WFN window with your WFN shortcut, change to the nmqinstall.bat directory
cd C:\nmvi\wfn6\NMQ4WFN
Then run nmqinstall.bat
nmqinstall
This will create the compiled versions of NONMEM identified by set VERSIONS in nmqinstall.bat. A destination for the compiled NONMEM files will be created automatically using the value of NMBINHOME defined in wfn.bat.
See wfnnmver.htm for details of these versions and how to switch between them.

6. Additional Changes to NONMEM

Some additional modifications to the NONMEM code are provided in changes.nick.nm5.xml and changes.nick.nm6.xml. These changes do not affect the performance of NONMEM but add some helpful functionality e.g. displaying the objective function value after ever iteration in a human readable numeric format and making it easier for WFN to read and display the standard NONMEM output listing.

7. Installing Updates to NMQual

Metrum Institute issues updates to NMQual shortly after bug fixes are announced by Globomax. To install the NMQual update go to the NMQ4WFN link and download the latest zip file to your WFN for NMqual directory e.g. C:\nmvi\wfn6\NMQ4WFN. Extract the contents of the NMQual file (e.g. nmqual-6.2.0.exe) to this directory. This will create a new NMqual version sub-directory e.g. C:\nmvi\wfn6\NMQ4WFN\nmqual-6.2.0.

Change the value of NMQSRCHOME in your nmqinstall.bat file to reflect the new NMQual version e.g. set NMQSRCHOME=C:\nmvi\wfn6\NMQ4WFN\nmqual-6.2.0. Save nmqinstall.bat.

Change your wfn.bat file to show the version date e.g. set NMVERDATE=20070614. Save wfn.bat.

Open a new WFN shortcut window so that WFN will look for the updated NONMEM versions.

Re-run nmqinstall.bat to create the updated NONMEM versions.

8. How to set the NMQUALVER variable for using NMQUAL Runtime Qualification

For the purposes of using WFN with NMQUAL so that runtime qualification happens with NMQUAL then it is necessary to set an environment variable in wfn.bat so indicate the name of the .pl file that will do the work. In this example the .pl file is std.pl and it is found in the test subdirectory of the NONMEM installation.
This appears in the NMQUAL config*.xml script I use to make a version of NONMEM in the target directory 'std'.


<directory id='target'>c:\users\nick\NONMEM\ver6_20070614\g77\std</directory>

NMQUAL will create in the c:\users\nick\NONMEM\ver6_20070614\g77\std directory the usual NONMEM sub-directories (nm,pr,tl,tr,etc) plus a special NMQUAL directory called 'test'. NMQUAL puts several files in here including a file called std.pl. This is the full path to the test directory.
c:\users\nick\NONMEM\ver6_20070614\g77\std\test.

NMQUAL knows this default location for 'test' but for some reason not clear to me it doesn't know the name of the .pl file it needs to call. So in WFN you would do this in wfn.bat so that 1) WFN know to invoke NMQUAL and 2) knows the name that should be used for the .pl file which will do the work:

set NMQUALVER=std

If I do this and run WFN with the theopd example I get the following output.

C:\users\nick\NMQ4WFN>set nmqualver ; this line confirms that the value of NMQUALVER is std
NMQUALVER=std

C:\users\nick\NMQ4WFN>cd \users\nick\wfn6\run ; this is where theopd.ctl is located

C:\Users\Nick\wfn6\run>nmgo theopd ; ask WFN to run NONMEM with the nmgo command

this is c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl
c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl is confirming checksums
checking 8 items
C:\users\nick\NONMEM\ver6_20070614\g77\std\test\checksum.2007.04.08.2135.xml

c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl is testing environment variables
'OS' exists
'USERNAME' exists
'PATH' exists
'LIBRARY_PATH' exists
'PATH' contains 'G77\bin;' at position 113

c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl is testing system commands
'g77 -v' was executed
'g77 -v' was executed
c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl: home directory is C:\us
ers\nick\NONMEM\ver6_20070614\g77\std\test
c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl: default in/out director
y is C:\Users\Nick\wfn6\run\theopd.std
c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl: execution directory is
C:\Users\Nick\wfn6\run\theopd.std

WARNINGS AND ERRORS (IF ANY) FOR PROBLEM 1

(WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.

(WARNING 13) WITH USER-WRITTEN PRED OR $PRED, NM-TRAN CANNOT APPEND THE
MDV DATA ITEM.

c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl is starting C:\Users\Nick
\wfn6\run\theopd.std\nonmem.exe

MONITORING OF SEARCH:

0ITERATION NO.: 0 OBJECTIVE VALUE: 23534.627 NO. OF FUNC. EVALS.: 6
CUMULATIVE NO. OF FUNC. EVALS.: 6
PARAMETER: 0.1000E+00 0.1000E+00 0.1000E+00 0.1000E+00 0.1000E+00 0.1000E
+00 0.1000E+00
GRADIENT: -0.4964E+03 -0.2730E+04 0.1722E+03 -0.5644E+03 -0.1429E+04 -0.1318E
+04 -0.3477E+05
0ITERATION NO.: 41 OBJECTIVE VALUE: 5802.086 NO. OF FUNC. EVALS.: 0
CUMULATIVE NO. OF FUNC. EVALS.: 324
PARAMETER: 0.7493E-01 -0.9455E-01 -0.3196E+00 -0.2739E+01 -0.2722E+00 0.6359E
+00 0.2194E+01
GRADIENT: -0.7424E-04 -0.4129E-04 0.6728E-04 0.1152E-05 -0.1674E-04 0.4773E
-04 -0.3970E-03
c:\users\nick\NONMEM\ver6_20070614\g77\std\test/std.pl is complete

THETA: POPE0 POPEMAX POPEC50
ETA: ETAE0 ETAEMAX ETAEC50
ERR: ERRSD
theopd.lst . eval=324 sig=+4.5 sub=153 obs=NO.',I5,</to> CCIL=NNNN NV
I1.1
THETA = 146 165 6.57
ETASD = 0.0413521 0.487852 1.2083
ERRSD = 81.1788
THETA:se% = 7.6 12.5 30.0
OMEGA:se% = 4350.9 42.9 78.8
SIGMA:se% = 10.6

MINIMIZATION SUCCESSFUL

user 0.0 real 0.0 tcl 0.0

If you have used the WFN nmqinstall.bat method AND you have set VERSIONS=std in nmqinstall.bat THEN the correct value for NMQUALVER in wfn.bat is std. i.e. set NMQUALVER=std.