doc/user/command_line_options.doc

   1 /*
   2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
   3 (HOOMD-blue) Open Source Software License Copyright 2008-2011 Ames Laboratory
   4 Iowa State University and The Regents of the University of Michigan All rights
   5 reserved.
   6
   7 HOOMD-blue may contain modifications ("Contributions") provided, and to which
   8 copyright is held, by various Contributors who have granted The Regents of the
   9 University of Michigan the right to modify and/or distribute such Contributions.
  10
  11 You may redistribute, use, and create derivate works of HOOMD-blue, in source
  12 and binary forms, provided you abide by the following conditions:
  13
  14 * Redistributions of source code must retain the above copyright notice, this
  15 list of conditions, and the following disclaimer both in the code and
  16 prominently in any materials provided with the distribution.
  17
  18 * Redistributions in binary form must reproduce the above copyright notice, this
  19 list of conditions, and the following disclaimer in the documentation and/or
  20 other materials provided with the distribution.
  21
  22 * All publications and presentations based on HOOMD-blue, including any reports
  23 or published results obtained, in whole or in part, with HOOMD-blue, will
  24 acknowledge its use according to the terms posted at the time of submission on:
  25 http://codeblue.umich.edu/hoomd-blue/citations.html
  26
  27 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  28 http://codeblue.umich.edu/hoomd-blue/
  29
  30 * Apart from the above required attributions, neither the name of the copyright
  31 holder nor the names of HOOMD-blue's contributors may be used to endorse or
  32 promote products derived from this software without specific prior written
  33 permission.
  34
  35 Disclaimer
  36
  37 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
  38 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  39 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
  40 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
  41
  42 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  43 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  44 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  45 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  46 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  47 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  48 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  49 */
  50
  51 /*! \page page_command_line_options Command line options
  52
  53 <h2>Overview</h2>
  54 \b hoomd [script_file] [options]
  55
  56 <h3>Options</h3>
  57 <i>no options given</i>
  58 \par
  59 hoomd will run on an automatically determined GPU, or on the CPUs if no capable GPUs are found.
  60
  61 <b>-h, --help</b>
  62 \par
  63 print a description of all the command line options
  64
  65 <b>--mode</b>={\a cpu | \a gpu}<br>
  66 \par
  67 force hoomd to run either on the \a cpu or \a gpu
  68
  69 <b>--gpu</b>={#}
  70 \par
  71 specify explicitly the GPU on which hoomd will execute. Implies --mode=gpu.
  72
  73 <b>--ncpu</b>={#}
  74 \par
  75 specify the number of CPU cores on which hoomd will execute. <i>Does not</i> imply --mode=cpu.
  76
  77 <b>--ignore-display-gpu</b>
  78 \par
  79 prevent hoomd from running on the GPU that is attached to the display
  80
  81 <b>--minimize-cpu-usage</b>
  82 \par
  83 minimize the CPU usage of hoomd when it runs on a GPU
  84
  85 <b>--gpu_error_checking</b>
  86 \par
  87 enable error checks after every GPU kernel call
  88 <hr>
  89
  90 <h2>Detailed description</h2>
  91
  92 <h3>Control where a simulation is executed</h3>
  93 Any simulation in HOOMD-blue can be run on a number of CPUs or a GPU.  To control which,
  94 set the \c --mode option on the script command line. Valid settings are \c cpu
  95 and \c gpu.
  96 \code
  97 hoomd some_script.hoomd --mode=cpu
  98 \endcode
  99 When \c --mode is set to \c gpu and no other options are specified, hoomd will
 100 choose a GPU automatically. It will prioritize the GPU choice based on speed and
 101 whether it is attached to a display. Unless you take steps to configure your system
 102 (see below), then running a second instance of HOOMD-blue will place it on the same GPU
 103 as the first. HOOMD-blue will run correctly with more than one simulation on a GPU as
 104 long as there is enough memory, but the performance penalty is severe.
 105
 106 You can select the GPU on which to run using the \c --gpu command line option.
 107 \code
 108 hoomd some_script.hoomd --gpu=1
 109 \endcode
 110 Note that specifying \c --gpu implies \c --mode=gpu. To find out which id
 111 is assigned to each GPU in your system, download the CUDA SDK for your system
 112 from http://www.nvidia.com/object/cuda_get.html and run the \c deviceQuery sample.
 113
 114 If you run a script without any options
 115 \code
 116 hoomd some_script.hoomd
 117 \endcode
 118 hoomd first checks if there are any GPUs in the system. If it finds one or more,
 119 it makes the same automatic choice described previously. If none are found, it runs on the CPU.
 120
 121 <hr>
 122 <h3>Automatic determination of the GPU on which to run</h3>
 123 If CUDA 2.2 or newer is installed on a Linux OS, free GPUs can be determined automatically. To utilize this
 124 capability, the system administrator (root) must first use the \c nvidia-smi utility to enable
 125 the compute-exclusive mode on all GPUs in the system (for an example, see http://forums.nvidia.com/index.php?showtopic=96638&hl=nvidia-smi).
 126 With this mode enabled, running hoomd with no options or with the \c --mode=gpu option will result in an automatic
 127 choice of the first free GPU from the prioritized list.
 128
 129 Furthermore, the compute-exclusive mode <em>only allows a</em> \b single CUDA application to run on each GPU. If you have
 130 4 compute-exclusive GPUs available in the system, executing a fifth instance of hoomd with "hoomd some_script.hoomd"
 131 will result in the error: ***Error! no CUDA-capable device is available.
 132 <hr>
 133
 134 <h3>Minimizing the CPU usage of HOOMD-blue</h3>
 135 When hoomd is running on a GPU, it still uses 100% of one CPU core by default. This CPU usage can be
 136 decreased significantly by specifying the \c --minimize-cpu-usage command line option:
 137 \code
 138 hoomd some_script.hoomd --minimize-cpu-usage
 139 \endcode
 140 Tests performed indicate that enabling this option incurs a 10% overall performance reduction,
 141 but the CPU usage of hoomd is reduced to only 10% of a single CPU core.
 142
 143 \note For the --minimize-cpu-usage option to work, hoomd must be compiled and used on a system with CUDA
 144 version 2.2 or newer.
 145
 146 <hr>
 147
 148 <h3>Preventing HOOMD-blue from running on the display GPU</h3>
 149
 150 While running hoomd on the display GPU works just fine, it does moderately slow the simulation and causes the display
 151 to lag. If you wish to prevent hoomd from running on the display, add the \c --ignore-display-gpu command line:
 152 \code
 153 hoomd some_script.hoomd --ignore-display-gpu
 154 \endcode
 155
 156 <hr>
 157
 158 <h3>Controlling error checking on the GPU</h3>
 159 Detailed error checking is off by default to enable the best performance. If you have trouble
 160 that appears to be caused by the failure of a calculation to run on the GPU, you
 161 can run with GPU error checking enabled to check for any errors returned by the GPU.
 162
 163 To do this, run the script with the \c --gpu_error_checking command line option:
 164 \code
 165 hoomd some_script.hoomd --gpu_error_checking
 166 \endcode
 167
 168 <hr>
 169
 170 <h3>Controlling the number of CPU cores on which HOOMD-blue executes</h3>
 171 HOOMD-blue runs in parallel on any number of local CPU cores using OpenMP. The number of CPU cores
 172 used is determined by the OpenMP runtime, which usually defaults to all CPU cores in the system. Limit the number of
 173 CPU cores used by setting the environment variable OMP_NUM_THREADS before executing hoomd or by using the --ncpu
 174 command line option.
 175
 176 <hr>
 177
 178 You can always run
 179 \code
 180 hoomd some_script.hoomd --help
 181 \endcode
 182 to get a full list of the available command line options some of which
 183 may not be listed here.
 184 */