<p><aclass="reference internal"href="Section_accelerate.html"><em>Return to Section accelerate overview</em></a></p>
<divclass="section"id="user-intel-package">
<h1>5.USER-INTEL package<aclass="headerlink"href="#user-intel-package"title="Permalink to this headline">¶</a></h1>
<p>The USER-INTEL package was developed by Mike Brown at Intel
Corporation. It provides a capability to accelerate simulations by
offloading neighbor list and non-bonded force calculations to Intel(R)
Xeon Phi(TM) coprocessors (not native mode like the KOKKOS package).
Additionally, it supports running simulations in single, mixed, or
double precision with vectorization, even if a coprocessor is not
present, i.e. on an Intel(R) CPU. The same C++ code is used for both
cases. When offloading to a coprocessor, the routine is run twice,
once with an offload flag.</p>
<p>The USER-INTEL package can be used in tandem with the USER-OMP
package. This is useful when offloading pair style computations to
coprocessors, so that other styles not supported by the USER-INTEL
package, e.g. bond, angle, dihedral, improper, and long-range
electrostatics, can run simultaneously in threaded mode on the CPU
cores. Since less MPI tasks than CPU cores will typically be invoked
when running with coprocessors, this enables the extra CPU cores to be
used for useful computation.</p>
<p>If LAMMPS is built with both the USER-INTEL and USER-OMP packages
intsalled, this mode of operation is made easier to use, because the
“-suffix intel”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switch</span></a> or
the <aclass="reference internal"href="suffix.html"><em>suffix intel</em></a> command will both set a second-choice
suffix to “omp” so that styles from the USER-OMP package will be used
if available, after first testing if a style from the USER-INTEL
package is available.</p>
<p>When using the USER-INTEL package, you must choose at build time
whether you are building for CPU-only acceleration or for using the
Xeon Phi in offload mode.</p>
<p>Here is a quick overview of how to use the USER-INTEL package
for CPU-only acceleration:</p>
<ulclass="simple">
<li>specify these CCFLAGS in your src/MAKE/Makefile.machine: -openmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost</li>
<li>specify -openmp with LINKFLAGS in your Makefile.machine</li>
<li>include the USER-INTEL package and (optionally) USER-OMP package and build LAMMPS</li>
<li>specify how many OpenMP threads per MPI task to use</li>
<li>use USER-INTEL and (optionally) USER-OMP styles in your input script</li>
</ul>
<p>Note that many of these settings can only be used with the Intel
compiler, as discussed below.</p>
<p>Using the USER-INTEL package to offload work to the Intel(R)
Xeon Phi(TM) coprocessor is the same except for these additional
steps:</p>
<ulclass="simple">
<li>add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in your Makefile.machine</li>
<li>add the flag -offload to LINKFLAGS in your Makefile.machine</li>
</ul>
<p>The latter two steps in the first case and the last step in the
coprocessor case can be done using the “-pk intel” and “-sf intel”
<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switches</span></a> respectively. Or
the effect of the “-pk” or “-sf” switches can be duplicated by adding
the <aclass="reference internal"href="package.html"><em>package intel</em></a> or <aclass="reference internal"href="suffix.html"><em>suffix intel</em></a>
<p>Note that if the USER-OMP package is also installed, you can use
styles from both packages, as described below.</p>
<p>The Makefile.machine needs a “-fopenmp” flag for OpenMP support in
both the CCFLAGS and LINKFLAGS variables. You also need to add
-DLAMMPS_MEMALIGN=64 and -restrict to CCFLAGS.</p>
<p>If you are compiling on the same architecture that will be used for
the runs, adding the flag <em>-xHost</em> to CCFLAGS will enable
vectorization with the Intel(R) compiler. Otherwise, you must
provide the correct compute node architecture to the -x option
(e.g. -xAVX).</p>
<p>In order to build with support for an Intel(R) Xeon Phi(TM)
coprocessor, the flag <em>-offload</em> should be added to the LINKFLAGS line
and the flag -DLMP_INTEL_OFFLOAD should be added to the CCFLAGS line.</p>
<p>Example makefiles Makefile.intel_cpu and Makefile.intel_phi are
included in the src/MAKE/OPTIONS directory with settings that perform
well with the Intel(R) compiler. The latter file has support for
offload to coprocessors; the former does not.</p>
<p><strong>Notes on CPU and core affinity:</strong></p>
<p>Setting core affinity is often used to pin MPI tasks and OpenMP
threads to a core or group of cores so that memory access can be
uniform. Unless disabled at build time, affinity for MPI tasks and
OpenMP threads on the host will be set by default on the host
when using offload to a coprocessor. In this case, it is unnecessary
to use other methods to control affinity (e.g. taskset, numactl,
I_MPI_PIN_DOMAIN, etc.). This can be disabled in an input script
with the <em>no_affinity</em> option to the <aclass="reference internal"href="package.html"><em>package intel</em></a>
command or by disabling the option at build time (by adding
-DINTEL_OFFLOAD_NOAFFINITY to the CCFLAGS line of your Makefile).
Disabling this option is not recommended, especially when running
on a machine with hyperthreading disabled.</p>
<p><strong>Running with the USER-INTEL package from the command line:</strong></p>
<p>The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.</p>
<p>If you plan to compute (any portion of) pairwise interactions using
USER-INTEL pair styles on the CPU, or use USER-OMP styles on the CPU,
you need to choose how many OpenMP threads per MPI task to use. Note
that the product of MPI tasks * OpenMP threads/task should not exceed
the physical number of cores (on a node), otherwise performance will
suffer.</p>
<p>If LAMMPS was built with coprocessor support for the USER-INTEL
package, you also need to specify the number of coprocessor/node and
the number of coprocessor threads per MPI task to use. Note that
coprocessor threads (which run on the coprocessor) are totally
independent from OpenMP threads (which run on the CPU). The default
values for the settings that affect coprocessor threads are typically
fine, as discussed below.</p>
<p>Use the “-sf intel”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switch</span></a>,
which will automatically append “intel” to styles that support it. If
a style does not support it, an “omp” suffix is tried next. OpenMP
threads per MPI task can be set via the “-pk intel Nphi omp Nt” or
“-pk omp Nt”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switches</span></a>, which
set Nt = # of OpenMP threads per MPI task to use. The “-pk omp” form
is only allowed if LAMMPS was also built with the USER-OMP package.</p>
<p>Use the “-pk intel Nphi”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switch</span></a> to set Nphi = # of Xeon Phi(TM)
coprocessors/node, if LAMMPS was built with coprocessor support. All
the available coprocessor threads on each Phi will be divided among
MPI tasks, unless the <em>tptask</em> option of the “-pk intel”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switch</span></a> is used to limit the coprocessor
threads per MPI task. See the <aclass="reference internal"href="package.html"><em>package intel</em></a> command
for details.</p>
<divclass="highlight-python"><divclass="highlight"><pre>CPU-only without USER-OMP (but using Intel vectorization on CPU):
lmp_machine -sf intel -in in.script # 1 MPI task
mpirun -np 32 lmp_machine -sf intel -in in.script # 32 MPI tasks on as many nodes as needed (e.g. 2 16-core nodes)
</pre></div>
</div>
<divclass="highlight-python"><divclass="highlight"><pre>CPU-only with USER-OMP (and Intel vectorization on CPU):
lmp_machine -sf intel -pk intel 16 0 -in in.script # 1 MPI task on a 16-core node
mpirun -np 4 lmp_machine -sf intel -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node
<p>Note that if the “-sf intel” switch is used, it also invokes two
default commands: <aclass="reference internal"href="package.html"><em>package intel 1</em></a>, followed by <aclass="reference internal"href="package.html"><em>package omp 0</em></a>. These both set the number of OpenMP threads per
MPI task via the OMP_NUM_THREADS environment variable. The first
command sets the number of Xeon Phi(TM) coprocessors/node to 1 (and
the precision mode to “mixed”, as one of its option defaults). The
latter command is not invoked if LAMMPS was not built with the
USER-OMP package. The Nphi = 1 value for the first command is ignored
if LAMMPS was not built with coprocessor support.</p>
<p>Using the “-pk intel” or “-pk omp” switches explicitly allows for
direct setting of the number of OpenMP threads per MPI task, and
additional options for either of the USER-INTEL or USER-OMP packages.
In particular, the “-pk intel” switch sets the number of
coprocessors/node and can limit the number of coprocessor threads per
MPI task. The syntax for these two switches is the same as the
<aclass="reference internal"href="package.html"><em>package omp</em></a> and <aclass="reference internal"href="package.html"><em>package intel</em></a> commands.
See the <aclass="reference internal"href="package.html"><em>package</em></a> command doc page for details, including
the default values used for all its options if these switches are not
specified, and how to set the number of OpenMP threads via the
OMP_NUM_THREADS environment variable if desired.</p>
<p><strong>Or run with the USER-INTEL package by editing an input script:</strong></p>
<p>The discussion above for the mpirun/mpiexec command, MPI tasks/node,
OpenMP threads per MPI task, and coprocessor threads per MPI task is
the same.</p>
<p>Use the <aclass="reference internal"href="suffix.html"><em>suffix intel</em></a> command, or you can explicitly add an
“intel” suffix to individual styles in your input script, e.g.</p>
<p>You must also use the <aclass="reference internal"href="package.html"><em>package intel</em></a> command, unless the
“-sf intel” or “-pk intel”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switches</span></a> were used. It specifies how many
coprocessors/node to use, as well as other OpenMP threading and
coprocessor options. Its doc page explains how to set the number of
OpenMP threads via an environment variable if desired.</p>
<p>If LAMMPS was also built with the USER-OMP package, you must also use
the <aclass="reference internal"href="package.html"><em>package omp</em></a> command to enable that package, unless
the “-sf intel” or “-pk omp”<aclass="reference internal"href="Section_start.html#start-7"><span>command-line switches</span></a> were used. It specifies how many
OpenMP threads per MPI task to use, as well as other options. Its doc
page explains how to set the number of OpenMP threads via an
environment variable if desired.</p>
<p><strong>Speed-ups to expect:</strong></p>
<p>If LAMMPS was not built with coprocessor support when including the
USER-INTEL package, then acclerated styles will run on the CPU using
vectorization optimizations and the specified precision. This may
give a substantial speed-up for a pair style, particularly if mixed or
single precision is used.</p>
<p>If LAMMPS was built with coproccesor support, the pair styles will run
on one or more Intel(R) Xeon Phi(TM) coprocessors (per node). The
performance of a Xeon Phi versus a multi-core CPU is a function of
your hardware, which pair style is used, the number of
atoms/coprocessor, and the precision used on the coprocessor (double,
single, mixed).</p>
<p>See the <aclass="reference external"href="http://lammps.sandia.gov/bench.html">Benchmark page</a> of the
LAMMPS web site for performance of the USER-INTEL package on different
hardware.</p>
<p><strong>Guidelines for best performance on an Intel(R) Xeon Phi(TM)
coprocessor:</strong></p>
<ulclass="simple">
<li>The default for the <aclass="reference internal"href="package.html"><em>package intel</em></a> command is to have
all the MPI tasks on a given compute node use a single Xeon Phi(TM)
coprocessor. In general, running with a large number of MPI tasks on
each node will perform best with offload. Each MPI task will
automatically get affinity to a subset of the hardware threads
available on the coprocessor. For example, if your card has 61 cores,
with 60 cores available for offload and 4 hardware threads per core
(240 total threads), running with 24 MPI tasks per node will cause
each MPI task to use a subset of 10 threads on the coprocessor. Fine
tuning of the number of threads to use per MPI task or the number of
threads to use per core can be accomplished with keyword settings of
the <aclass="reference internal"href="package.html"><em>package intel</em></a> command.</li>
<li>If desired, only a fraction of the pair style computation can be
offloaded to the coprocessors. This is accomplished by using the
<em>balance</em> keyword in the <aclass="reference internal"href="package.html"><em>package intel</em></a> command. A
balance of 0 runs all calculations on the CPU. A balance of 1 runs
all calculations on the coprocessor. A balance of 0.5 runs half of
the calculations on the coprocessor. Setting the balance to -1 (the
default) will enable dynamic load balancing that continously adjusts
the fraction of offloaded work throughout the simulation. This option
typically produces results within 5 to 10 percent of the optimal fixed
balance.</li>
<li>When using offload with CPU hyperthreading disabled, it may help
performance to use fewer MPI tasks and OpenMP threads than available
cores. This is due to the fact that additional threads are generated
internally to handle the asynchronous offload tasks.</li>
<li>If running short benchmark runs with dynamic load balancing, adding a
short warm-up run (10-20 steps) will allow the load-balancer to find a
near-optimal setting that will carry over to additional runs.</li>
<li>If pair computations are being offloaded to an Intel(R) Xeon Phi(TM)
coprocessor, a diagnostic line is printed to the screen (not to the
log file), during the setup phase of a run, indicating that offload
mode is being used and indicating the number of coprocessor threads
per MPI task. Additionally, an offload timing summary is printed at
the end of each run. When offloading, the frequency for <aclass="reference internal"href="atom_modify.html"><em>atom sorting</em></a> is changed to 1 so that the per-atom data is
effectively sorted at every rebuild of the neighbor lists.</li>
<li>For simulations with long-range electrostatics or bond, angle,
dihedral, improper calculations, computation and data transfer to the
coprocessor will run concurrently with computations and MPI
communications for these calculations on the host CPU. The USER-INTEL
package has two modes for deciding which atoms will be handled by the
coprocessor. This choice is controlled with the <em>ghost</em> keyword of
the <aclass="reference internal"href="package.html"><em>package intel</em></a> command. When set to 0, ghost atoms
(atoms at the borders between MPI tasks) are not offloaded to the
card. This allows for overlap of MPI communication of forces with
computation on the coprocessor when the <aclass="reference internal"href="newton.html"><em>newton</em></a> setting
is “on”. The default is dependent on the style being used, however,
better performance may be achieved by setting this option
explictly.</li>
</ul>
<divclass="section"id="restrictions">
<h2>Restrictions<aclass="headerlink"href="#restrictions"title="Permalink to this headline">¶</a></h2>
<p>When offloading to a coprocessor, <aclass="reference internal"href="pair_hybrid.html"><em>hybrid</em></a> styles
that require skip lists for neighbor builds cannot be offloaded.
Using <aclass="reference internal"href="pair_hybrid.html"><em>hybrid/overlay</em></a> is allowed. Only one intel
accelerated style may be used with hybrid styles.
<aclass="reference internal"href="special_bonds.html"><em>Special_bonds</em></a> exclusion lists are not currently
supported with offload, however, the same effect can often be
accomplished by setting cutoffs for excluded atom types to 0. None of
the pair styles in the USER-INTEL package currently support the
“inner”, “middle”, “outer” options for rRESPA integration via the
<aclass="reference internal"href="run_style.html"><em>run_style respa</em></a> command; only the “pair” option is
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.