html/execute_docs.php

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>PsN :: Documentation :: execute</title>
   5 <!--Adobe(R) LiveMotion(TM) 1.0 Generated JavaScript. Please do not edit. -->
   6   <script>
   7
   8 <!--
   9
  10 function newImage(arg) {
  11
  12 if (document.images) {
  13
  14 rslt = new Image();
  15
  16 rslt.src = arg;
  17
  18 return rslt;
  19
  20 }
  21
  22 }
  23
  24 ImageArray = new Array;
  25
  26 var preloadFlag = false;
  27
  28 function preloadImages() {
  29
  30 if (document.images) {
  31
  32 ImageArray[ImageArray.length++] = newImage(/* OWNER('object', 'dflt') *//*URL*/'images/indexhome.jpg');
  33 ImageArray[ImageArray.length++] = newImage(/* OWNER('object', 'movr') *//*URL*/'images/indexhomeov.jpg');
  34 ImageArray[ImageArray.length++] = newImage(/* OWNER('object1', 'dflt') *//*URL*/'images/indexdocumentation.jpg');
  35 ImageArray[ImageArray.length++] = newImage(/* OWNER('object1', 'movr') *//*URL*/'images/indexdocumentationov.jpg');
  36 ImageArray[ImageArray.length++] = newImage(/* OWNER('object2', 'dflt') *//*URL*/'images/indexdownload.jpg');
  37 ImageArray[ImageArray.length++] = newImage(/* OWNER('object2', 'movr') *//*URL*/'images/indexdownloadov.jpg');
  38 ImageArray[ImageArray.length++] = newImage(/* OWNER('object3', 'dflt') *//*URL*/'images/indexbuglist.jpg');
  39 ImageArray[ImageArray.length++] = newImage(/* OWNER('object3', 'movr') *//*URL*/'images/indexbuglistov.jpg');
  40 ImageArray[ImageArray.length++] = newImage(/* OWNER('object4', 'dflt') *//*URL*/'images/indexmailing_list.jpg');
  41 ImageArray[ImageArray.length++] = newImage(/* OWNER('object4', 'movr') *//*URL*/'images/indexmailing_listov.jpg');
  42 preloadFlag = true;
  43 }
  44 }
  45 function changeImages() {
  46 if (document.images && (preloadFlag == true)) {
  47 for (var i=0; i<changeImages.arguments.length; i+=2) {
  48 document[changeImages.arguments[i]].src = changeImages.arguments[i+1];
  49 }
  50 }
  51 }
  52 // -->
  53   </script><!-- End generated JavaScript. -->
  54   <meta http-equiv="Content-Type"
  55  content="text/html; charset=ISO-8859-1">
  56   <style type="text/css">
  57 <!--
  58 body,td,th {
  59 font-family: Helvetica, Arial, serif;
  60 font-size: 12px;
  61 color: #000000;
  62 }
  63 body {
  64 margin-left: 6px;
  65 margin-top: 0px;
  66 margin-right: 0px;
  67 margin-bottom: 0px;
  68 background-image: url(gfx/bg.jpg);
  69 }
  70 .style1 {
  71 font-size: 36px;
  72 font-weight: bold;
  73 }
  74 .heading1 {
  75 font-size: 16px;
  76 font-weight: bold;
  77 color: #333399;
  78 margin-left: 40px;
  79 }
  80 a:link {
  81 color: #656D9C;
  82 text-decoration: none;
  83 }
  84 a:visited {
  85 color: #656D9C;
  86 text-decoration: none;
  87 }
  88 a:hover {
  89 color: #AF9D49;
  90 text-decoration: none;
  91 }
  92 a:active {
  93 color: #656D9C;
  94 text-decoration: none;
  95 }
  96 .style2 {font-family: "Courier New", Courier, mono}
  97 -->
  98   </style>
  99   <script language="JavaScript" type="text/JavaScript">
 100 <!--
 101 function MM_reloadPage(init) { //reloads the window if Nav4 resized
 102 if (init==true) with (navigator) {if ((appName=="Netscape")&&(parseInt(appVersion)==4)) {
 103 document.MM_pgW=innerWidth; document.MM_pgH=innerHeight; onresize=MM_reloadPage; }}
 104 else if (innerWidth!=document.MM_pgW || innerHeight!=document.MM_pgH) location.reload();
 105 }
 106 MM_reloadPage(true);
 107 //-->
 108   </script>
 109   <meta content="Pntus Pihlgren" name="author">
 110 </head>
 111 <body onload="preloadImages();"
 112  style="background-color: rgb(255, 255, 255);">
 113 <!-- The table is not formatted nicely because some browsers cannot join images in table cells if there are any hard carriage returns in a TD. -->
 114 <div id="Layer1"
 115  style="position: absolute; left: 335px; top: 42px; width: 388px; height: 43px; z-index: 1; font-size: x-small;">
 116 <div class="style1" align="right">Execute<br>
 117 </div>
 118 </div>
 119 <div id="Layer2"
 120  style="position: absolute; left: 226px; top: 188px; width: 497px; height: 431px; z-index: 2;">
 121 <div align="justify">
 122
 123 <?php
 124 include("execute_synopsis.php");
 125 include("execute_description.php");
 126 include("execute_options.php");
 127 include("execute_examples.php");
 128 php?>
 129 <!--
 130 <h3 class="heading1">Synopsis</h3>
 131 <span class="style2">$ execute [ -h | -? ] [ --help ]<br>
 132 [ --abort_on_fail ]<br>
 133 [ --clean ]<br>
 134 [ --compress ]<br>
 135 [ --cpu_time='integer' ]<br>
 136 [ --debug=0 ]<br>
 137 [ --debug_package='string' ]<br>
 138 [ --debug_subroutine='string' ]<br>
 139 [ --directory='string' ]<br>
 140 [ --extra_data_file='string' ]<br>
 141 [ --extra_files='string' ]<br>
 142 [ --grid_batch_size='integer' ]<br>
 143 [ --missing_data_token='string' ]<br>
 144 [ --nm_directory='string' ]<br>
 145 [ --nm_version='string' ]<br>
 146 [ --outputfile='string' ]<br>
 147 [ --picky ]<br>
 148 [ --remove_temp_files ]<br>
 149 [ --results_file='string' ]<br>
 150 [ --retries='integer' ]<br>
 151 [ --run_on_nordugrid ]<br>
 152 [ --seed='string' ]<br>
 153 [ --threads='integer' ]<br>
 154 [ --tweak_inits ]</span><br>
 155 <h3 class="heading1">Description</h3>
 156 <p>The execute utility is a Perl script that allows you to run multiple model files
 157     either sequentially or in parallel. It is more or less an nmfe replacement.</p>
 158 <p> The execute utility creates sub directories where it puts NONMEM's input-
 159       and output files, to make sure that parallel NONMEM runs do not interfere with each other. The top directory is by default named
 160       'modelfit_dirX', where 'X' is a number that starts at 1 and is
 161       increased by one each time the execute utility is run.</p>
 162 <p> When the NONMEM runs are finished, the output- and table files will be copied
 163       to the directory where execute started. This means that you can normally ignore
 164       the 'modelfit_dirX' directory. If you need to access any
 165       special files these can be found inside the 'modelfit_dirX'. Inside the 'modelfit_dirX' a few
 166       sub directories named 'NM_runY' and 'mZ' will also be found.  For each model file
 167       specified on the command line there will be one 'NM_runY' directory in which the actual NONMEM execution takes place. The order
 168       of the 'NM_runY' directories corresponds to the order of the
 169       model files given on the command line. The first run will take place inside 'NM_run1', the second in 'NM_run2' and
 170       so on. The 'mZ' directories are only used internally by execute so you can safely ignore them.</p>
 171 <h3 class="heading1">Options</h3>
 172
 173 <p class="style2">-h | -?</p>
 174 <p> With -h or -? excute.pl will print the list of options and then exit.</p>
 175
 176 <p class="style2"> -help</p>
 177 <p> With -help execute will print a longer, more detailed message.</p>
 178
 179 <p class="style2"> -nm_version='integer'</p>
 180
 181 <p> If you have more than one installation of NONMEM you can choose
 182 between them using the <span class="style2">-nm_version</span>
 183 option. The installations must be specified in the psn.conf file. The
 184 default value is 5. </p>
 185
 186 <p class="style2"> -threads='integer'</p>
 187
 188 <p> The <span class="style2">-threads</span>
 189
 190 option enables parallel execution of multiple NONMEM runs. On a
 191 desktop computer it is recommended to set <span
 192 class="style2">-threads</span> to the number of CPUs in the system
 193 plus one. It is possible to specify more threads, but that will
 194 probably not increase the performance. If you are running on a
 195 computer cluster, you should consult your systems administrator to
 196 find out how many threads to specify. The <span
 197 class="style2">-threads</span> option will be ignored if you run on a
 198 grid system, since grids have their own scheduling algorithms. The
 199 default value for the <span class="style2">-threads</span>option is
 200 1.</p>
 201
 202 <p class="style2"> -directory='string'</p>
 203
 204 <p> The directory option defines the directory in which execute will
 205 run NONMEM. The default name is 'modelfit_dirX' where X will be
 206 increased by one each time you run the execute utility. You do not
 207     have to create the directory since it will be done automatically.</p>
 208
 209 <p> If you abort execute or if your system crashes you can use the
 210   '-directory' option set to the directory of the execute run that
 211   crashed. Execute will then not run the model files that had finished
 212   before the crash, thereby saving some time. Note that is
 213   important to give exactly the same options as was given the first
 214   time.</p>
 215
 216 <p class="style2"> -seed='string'</p>
 217
 218 <p> If you use the -retries='integer' option, execute will
 219   use a random number to create new initial estimates for the model
 220 parameters. To make sure that
 221   the same result is produced if  the same model is rerun, you can set
 222     your own random seed with the <span class="style2">-seed</span> option.</p>
 223
 224 <p class="style2"> -remove_temp_files</p> <p> If the <span
 225 class="style2">-remove_temp_files</span> option is used, execute will
 226 remove the 'FCON', 'FDATA', 'FREPORT', 'FSUBS', 'FSUBS.f', 'LINK.LNK',
 227 'FSTREAM', 'PRDERR' and 'nonmem' files from the 'NM_runY'
 228 directory. The default value is 0. </p>
 229
 230 <p class="style2"> -clean</p>
 231
 232 <p> The <span class="style2">-clean</span> option is a more thorough
 233 version of '-remove_temp_files'. If the <span
 234 class="style2">-clean</span> option is used, execute will remove the
 235 entire 'NM_runY'
 236   directory after the NONMEM run is finished.</p>
 237
 238 <p class="style2"> -compress</p>
 239
 240 <p> The execute utility will compress the contents of 'NM_runY' to the
 241 file 'nonmem_files.tgz' if the <span class="style2">-compress</span>
 242 option is used and if you have the archive and compress programs
 243 <strong>tar</strong> and <strong>gzip</strong> installed. If you use
 244 the <span class="style2">-remove_temp_files </span>options,
 245   temporary files will be removed before the compression. The <span
 246 class="style2">-compress</span> option obviously has no effect if you
 247 also use the <span class="style2">-clean</span> option. </p>
 248
 249 <p> -tweak_inits</p> <p> If NONMEM terminates nonsuccessfully, PsN can
 250 perturb the initial estimates and run NONMEM again. The generation of
 251 new initial estimates <img src="images/init1.gif"> for the
 252 <em>i</em>:th retry are performed according to</p> <p
 253 align="center"><img src="images/perturb1.gif" width="236"
 254 height="32"></p> <p>where <img src="images/init_orig1.gif" width="29"
 255 height="28"> are the initial estimates of the original run. The
 256 updating procedure makes sure that boundary conditions on the
 257 parameters are still valid. For this option to be valid, the <span
 258 class="style2">-retries</span> option must be set to a number larger
 259 than zero. The default setting uses tweak_inits. </p>
 260
 261 <p class="style2"> -outputfile</p> <p> The <span
 262 class="style2">-outputfile</span> option specifies the output file
 263 name for the NONMEM run. Currently this option is only valid when a
 264 single model is supplied to the execute utility.</p>
 265
 266 <p class="style2">-picky</p>
 267 <p> The <span class="style2">-picky</span> option is only valid together with
 268   <span class="style2">-tweak_inits</span>. Normally PsN only tries new initial estimates if '<span class="style2">MINIMZATION SUCCESSFUL</span>' is not found in the NONMEM output file. With the <span class="style2">-picky</span> option,  PsN
 269   will  regard any of the following messages as a signal for rerunning:</p>
 270 <p class="style2"> 0ESTIMATE OF THETA IS NEAR THE BOUNDARY<br>
 271   0PARAMETER ESTIMATE IS NEAR ITS BOUNDARY<br>
 272   0R MATRIX ALGORITHMICALLY SINGULAR<br>
 273   0S MATRIX ALGORITHMICALLY SINGULAR</p>
 274
 275 <p class="style2"> -retries='integer'</p>
 276
 277 <p>  The <span class="style2">-retries</span> option tells
 278 the execute utility how many times it shall try to rerun a NONMEM job if it gets an error message. In the current version of PsN (2.2), the <span class="style2">-retries</span> option is only valid together with <span class="style2">-tweak_inits</span>. The default value of the <span class="style2">-retries</span> option is 0. </p>
 279
 280 <p class="style2"> -abort_on_fail</p> <p> If the <span
 281 class="style2">-abort_on_fail</span> option is set and one of the
 282 NONMEM runs fails, execute will stop scheduling
 283   more runs and try to stop those that are currently running.</p>
 284
 285 <p class="style2">-run_on_nordugrid</p>
 286 <p>!! Currently only valid for Linux system !!<br>
 287  Using this option, execute will run on the nordugrid clusters listed
 288 in ~/.ng_cluster. If you do not know about Nordugrid, you can safely
 289 ignore this option. You can read more on http://www.nordugrid.org.
 290 </p>
 291
 292 <p class="style2"> -cpu_time='integer'</p>
 293
 294 <p> This option specifies the number of minutes allocated for a
 295   grid job. The default value is 120 minutes. This option is only
 296 valid together with the <span class="style2">-run_on_nordugrid</span>
 297 option.</p>
 298
 299 <p class="style2"> -grid_batch_size='integer'</p>
 300 <p> This option specifies the number of NONMEM runs that will be grouped
 301   together into one grid job. The default number is 5. This option is
 302 only valid together with the '-run_on_nordugrid' option.</p>
 303
 304 <p class="style2"> -debug='integer'</p>
 305
 306 <p> The <span class="style2">-debug </span>option is mainly intended
 307 for developers who wish to debug PsN. By default <span
 308 class="style2">-debug</span> is set to zero but you can try setting it
 309 to '1' to enable warning messages. If you run into problems that
 310 require support, you may have to increase this number to 2 or 3 and
 311 send the output to us.</p>
 312
 313 <p class="style2"> -debug_package='string'</p>
 314
 315 <p> When used together with <span class="style2">-debug</span>, the
 316 <span class="style2">-debug_package</span> option makes is possible to
 317 choose which part of PsN you want to see debug messages for. Again,
 318 this option is mostly useful for developers.</p>
 319
 320 <p class="style2"> -debug_subroutine='string'</p>
 321
 322 <p> With this option it is possible to specify exactly which
 323 subroutines in PsN you want to see debug messages for.</p>
 324 -->
 325 <h3 class="heading1">Output</h3>
 326 <p>The output- and table files of NONMEM will be copied from the temporary run directories to the place specified by the <span class="style2">-outputfile</span> option and the $TABLE record of the model files. </p>
 327 </div>
 328 <!--
 329 <h3 class="heading1">Example</h3>
 330 <p align="justify" class="style2">$ execute pheno.mod </p>
 331 <p align="justify">Runs one model file and accepts all default values.</p>
 332 <p align="justify" class="style2">$ execute -threads=2  -retries=5 phenobarbital.mod pheno_alternate.mod</p>
 333 <p align="justify">Runs two model files in parallel using 5 possible retries.</p>
 334 -->
 335 </div>
 336
 337 <table border="0" cellpadding="0" cellspacing="0" width="780">
 338   <tbody>
 339     <tr>
 340       <td height="600" width="780">
 341       <table border="0" cellpadding="0" cellspacing="0" width="780">
 342         <tbody>
 343           <tr>
 344             <td colspan="7" height="201" width="780"><img
 345  src="images/indexpane1_1_.jpg" name="" alt="" border="0" height="201"
 346  width="780"></td>
 347           </tr>
 348           <tr>
 349             <td height="46" width="26"><img
 350  src="images/indexpane1_2_.jpg" name="" alt="" border="0" height="46"
 351  width="26"></td>
 352             <td height="46" width="73"><a href="index.php"
 353  onmouseover="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhomeov.jpg'); return true;"
 354  onmouseout="changeImages(/*CMP*/ 'object', /*URL*/ 'images/indexhome.jpg'); return true;"><img
 355  src="images/indexhome.jpg" name="object" alt="Home" border="0"
 356  height="46" width="73"></a></td>
 357             <td height="46" width="11"><img
 358  src="images/indexpane3_2_.jpg" name="" alt="" border="0" height="46"
 359  width="11"></td>
 360             <td height="46" width="25"><img
 361  src="images/indexpane4_2_.jpg" name="" alt="" border="0" height="46"
 362  width="25"></td>
 363             <td height="46" width="15"><img
 364  src="images/indexpane5_2_.jpg" name="" alt="" border="0" height="46"
 365  width="15"></td>
 366             <td height="46" width="40"><img
 367  src="images/indexpane6_2_.jpg" name="" alt="" border="0" height="46"
 368  width="40"></td>
 369             <td height="46" width="590"><img
 370  src="images/indexpane7_2_.jpg" name="" alt="" border="0" height="46"
 371  width="590"></td>
 372           </tr>
 373           <tr>
 374             <td colspan="7" height="7" width="780"><img
 375  src="images/indexpane1_3_.jpg" name="" alt="" border="0" height="7"
 376  width="780"></td>
 377           </tr>
 378           <tr>
 379             <td height="46" width="26"><img
 380  src="images/indexpane1_4_.jpg" name="" alt="" border="0" height="46"
 381  width="26"></td>
 382             <td colspan="5" height="46" width="164"><a href="docs.php"
 383  onmouseover="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentationov.jpg'); return true;"
 384  onmouseout="changeImages(/*CMP*/ 'object1', /*URL*/ 'images/indexdocumentation.jpg'); return true;"><img
 385  src="images/indexdocumentation.jpg" name="object1" alt="Documentation"
 386  border="0" height="46" width="164"></a></td>
 387             <td height="46" width="590"><img
 388  src="images/indexpane7_4_.jpg" name="" alt="" border="0" height="46"
 389  width="590"></td>
 390           </tr>
 391           <tr>
 392             <td colspan="7" height="7" width="780"><img
 393  src="images/indexpane1_5_.jpg" name="" alt="" border="0" height="7"
 394  width="780"></td>
 395           </tr>
 396           <tr>
 397             <td height="46" width="26"><img
 398  src="images/indexpane1_6_.jpg" name="" alt="" border="0" height="46"
 399  width="26"></td>
 400             <td colspan="3" height="46" width="109"><a
 401  href="download.php"
 402  onmouseover="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownloadov.jpg'); return true;"
 403  onmouseout="changeImages(/*CMP*/ 'object2', /*URL*/ 'images/indexdownload.jpg'); return true;"><img
 404  src="images/indexdownload.jpg" name="object2" alt="Download" border="0"
 405  height="46" width="109"></a></td>
 406             <td colspan="3" height="46" width="645"><img
 407  src="images/indexpane5_6_.jpg" name="" alt="" border="0" height="46"
 408  width="645"></td>
 409           </tr>
 410           <tr>
 411             <td colspan="7" height="7" width="780"><img
 412  src="images/indexpane1_7_.jpg" name="" alt="" border="0" height="7"
 413  width="780"></td>
 414           </tr>
 415           <tr>
 416             <td height="46" width="26"><img
 417  src="images/indexpane1_8_.jpg" name="" alt="" border="0" height="46"
 418  width="26"></td>
 419             <td colspan="2" height="46" width="84"><a href="buglist.php"
 420  onmouseover="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglistov.jpg'); return true;"
 421  onmouseout="changeImages(/*CMP*/ 'object3', /*URL*/ 'images/indexbuglist.jpg'); return true;"><img
 422  src="images/indexbuglist.jpg" name="object3" alt="Buglist" border="0"
 423  height="46" width="84"></a></td>
 424             <td colspan="4" height="46" width="670"><img
 425  src="images/indexpane4_8_.jpg" name="" alt="" border="0" height="46"
 426  width="670"></td>
 427           </tr>
 428           <tr>
 429             <td colspan="7" height="7" width="780"><img
 430  src="images/indexpane1_9_.jpg" name="" alt="" border="0" height="7"
 431  width="780"></td>
 432           </tr>
 433           <tr>
 434             <td height="46" width="26"><img
 435  src="images/indexpane1_10_.jpg" name="" alt="" border="0" height="46"
 436  width="26"></td>
 437             <td colspan="4" height="46" width="124"><a href="list.php"
 438  onmouseover="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_listov.jpg'); return true;"
 439  onmouseout="changeImages(/*CMP*/ 'object4', /*URL*/ 'images/indexmailing_list.jpg'); return true;"><img
 440  src="images/indexmailing_list.jpg" name="object4" alt="Mailing List"
 441  border="0" height="46" width="124"></a></td>
 442             <td colspan="2" height="46" width="630"><img
 443  src="images/indexpane6_10_.jpg" name="" alt="" border="0" height="46"
 444  width="630"></td>
 445           </tr>
 446           <tr>
 447             <td colspan="7" height="141" width="780"><img
 448  src="images/indexpane1_11_.jpg" name="" alt="" border="0" height="141"
 449  width="780"></td>
 450           </tr>
 451         </tbody>
 452       </table>
 453       </td>
 454     </tr>
 455     <tr>
 456       <td><img src="images/is_single_pixel_gif.gif" alt="" height="1"
 457  width="780"></td>
 458     </tr>
 459   </tbody>
 460 </table>
 461 <!--Adobe(R) LiveMotion(TM) DataMap1.0 DO NOT EDIT
 462 end DataMap -->
 463 </body>
 464 </html>