jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14131 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2015-10-21 18:52:59 +00:00
parent c4af165bba
commit cd078405e0
25 changed files with 1858 additions and 1547 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

900
doc/Manual.html
View File

@ -1,478 +1,454 @@
<HTML>
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="5 Oct 2015 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
<BODY>
<!-- END_HTML_ONLY -->
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>LAMMPS Documentation &mdash; LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<link rel="next" title="1. Introduction" href="Section_intro.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="#" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="#">LAMMPS</a>
</nav>
<HR>
<H1></H1>
<CENTER><H3>LAMMPS Documentation
</H3></CENTER>
<CENTER><H4>5 Oct 2015 version
</H4></CENTER>
<H4>Version info:
</H4>
<P>The LAMMPS "version" is the date when it was released, such as 1 May
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="#">Docs</a> &raquo;</li>
<li>LAMMPS Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
<div class="rst-footer-buttons" style="margin-bottom: 1em" role="navigation" aria-label="footer navigation">
<a href="Section_intro.html" class="btn btn-neutral float-right" title="1. Introduction" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<H1></H1><div class="section" id="lammps-documentation">
<h1>LAMMPS Documentation<a class="headerlink" href="#lammps-documentation" title="Permalink to this headline"></a></h1>
<div class="section" id="aug-2015-version">
<h2>10 Aug 2015 version<a class="headerlink" href="#aug-2015-version" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="version-info">
<h2>Version info:<a class="headerlink" href="#version-info" title="Permalink to this headline"></a></h2>
<p>The LAMMPS &#8220;version&#8221; is the date when it was released, such as 1 May
2010. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it immediately, and post a notice on <A HREF = "http://lammps.sandia.gov/bug.html">this page of
the WWW site</A>. Each dated copy of LAMMPS contains all the
feature, we release it immediately, and post a notice on <a class="reference external" href="http://lammps.sandia.gov/bug.html">this page of the WWW site</a>. Each dated copy of LAMMPS contains all the
features and bug-fixes up to and including that version date. The
version date is printed to the screen and logfile every time you run
LAMMPS. It is also in the file src/version.h and in the LAMMPS
directory name created when you unpack a tarball, and at the top of
the first page of the manual (this page).
</P>
<UL><LI>If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.
<LI>If you browse the HTML doc pages included in your tarball, they
describe the version you have.
<LI>The <A HREF = "Manual.pdf">PDF file</A> on the WWW site or in the tarball is updated
about once per month. This is because it is large, and we don't want
it to be part of every patch.
<LI>There is also a <A HREF = "Developer.pdf">Developer.pdf</A> file in the doc
the first page of the manual (this page).</p>
<ul class="simple">
<li>If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.</li>
<li>If you browse the HTML doc pages included in your tarball, they
describe the version you have.</li>
<li>The <a class="reference external" href="Manual.pdf">PDF file</a> on the WWW site or in the tarball is updated
about once per month. This is because it is large, and we don&#8217;t want
it to be part of every patch.</li>
<li>There is also a <a class="reference external" href="Developer.pdf">Developer.pdf</a> file in the doc
directory, which describes the internal structure and algorithms of
LAMMPS.
</UL>
<P>LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.
</P>
<P>LAMMPS is a classical molecular dynamics simulation code designed to
LAMMPS.</li>
</ul>
<p>LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.</p>
<p>LAMMPS is a classical molecular dynamics simulation code designed to
run efficiently on parallel computers. It was developed at Sandia
National Laboratories, a US Department of Energy facility, with
funding from the DOE. It is an open-source code, distributed freely
under the terms of the GNU Public License (GPL).
</P>
<P>The primary developers of LAMMPS are <A HREF = "http://www.sandia.gov/~sjplimp">Steve Plimpton</A>, Aidan
under the terms of the GNU Public License (GPL).</p>
<p>The primary developers of LAMMPS are <a class="reference external" href="http://www.sandia.gov/~sjplimp">Steve Plimpton</a>, Aidan
Thompson, and Paul Crozier who can be contacted at
sjplimp,athomps,pscrozi at sandia.gov. The <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> at
http://lammps.sandia.gov has more information about the code and its
uses.
</P>
<HR>
<P>The LAMMPS documentation is organized into the following sections. If
sjplimp,athomps,pscrozi at sandia.gov. The <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a> at
<a class="reference external" href="http://lammps.sandia.gov">http://lammps.sandia.gov</a> has more information about the code and its
uses.</p>
<hr class="docutils" />
<p>The LAMMPS documentation is organized into the following sections. If
you find errors or omissions in this manual or have suggestions for
useful information to add, please send an email to the developers so
we can improve the LAMMPS documentation.
</P>
<P>Once you are familiar with LAMMPS, you may want to bookmark <A HREF = "Section_commands.html#comm">this
page</A> at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.
</P>
<P><A HREF = "Manual.pdf">PDF file</A> of the entire manual, generated by
<A HREF = "http://freecode.com/projects/htmldoc">htmldoc</A>
</P>
<P><!-- RST
</P>
<P>.. toctree::
:maxdepth: 2
:numbered: // comment
</P>
<P> Section_intro
Section_start
Section_commands
Section_packages
Section_accelerate
Section_howto
Section_example
Section_perf
Section_tools
Section_modify
Section_python
Section_errors
Section_history
</P>
<P>Indices and tables
==================
</P>
<P>* :ref:`genindex` // comment
* :ref:`search` // comment
</P>
<P>END_RST -->
</P>
<OL><LI><!-- HTML_ONLY -->
<A HREF = "Section_intro.html">Introduction</A>
<UL> 1.1 <A HREF = "Section_intro.html#intro_1">What is LAMMPS</A>
<BR>
1.2 <A HREF = "Section_intro.html#intro_2">LAMMPS features</A>
<BR>
1.3 <A HREF = "Section_intro.html#intro_3">LAMMPS non-features</A>
<BR>
1.4 <A HREF = "Section_intro.html#intro_4">Open source distribution</A>
<BR>
1.5 <A HREF = "Section_intro.html#intro_5">Acknowledgments and citations</A>
<BR></UL>
<LI><A HREF = "Section_start.html">Getting started</A>
<UL> 2.1 <A HREF = "Section_start.html#start_1">What's in the LAMMPS distribution</A>
<BR>
2.2 <A HREF = "Section_start.html#start_2">Making LAMMPS</A>
<BR>
2.3 <A HREF = "Section_start.html#start_3">Making LAMMPS with optional packages</A>
<BR>
2.4 <A HREF = "Section_start.html#start_4">Building LAMMPS via the Make.py script</A>
<BR>
2.5 <A HREF = "Section_start.html#start_5">Building LAMMPS as a library</A>
<BR>
2.6 <A HREF = "Section_start.html#start_6">Running LAMMPS</A>
<BR>
2.7 <A HREF = "Section_start.html#start_7">Command-line options</A>
<BR>
2.8 <A HREF = "Section_start.html#start_8">Screen output</A>
<BR>
2.9 <A HREF = "Section_start.html#start_9">Tips for users of previous versions</A>
<BR></UL>
<LI><A HREF = "Section_commands.html">Commands</A>
<UL> 3.1 <A HREF = "Section_commands.html#cmd_1">LAMMPS input script</A>
<BR>
3.2 <A HREF = "Section_commands.html#cmd_2">Parsing rules</A>
<BR>
3.3 <A HREF = "Section_commands.html#cmd_3">Input script structure</A>
<BR>
3.4 <A HREF = "Section_commands.html#cmd_4">Commands listed by category</A>
<BR>
3.5 <A HREF = "Section_commands.html#cmd_5">Commands listed alphabetically</A>
<BR></UL>
<LI><A HREF = "Section_packages.html">Packages</A>
<UL> 4.1 <A HREF = "Section_packages.html#pkg_1">Standard packages</A>
<BR>
4.2 <A HREF = "Section_packages.html#pkg_2">User packages</A>
<BR></UL>
<LI><A HREF = "Section_accelerate.html">Accelerating LAMMPS performance</A>
<UL> 5.1 <A HREF = "Section_accelerate.html#acc_1">Measuring performance</A>
<BR>
5.2 <A HREF = "Section_accelerate.html#acc_2">Algorithms and code options to boost performace</A>
<BR>
5.3 <A HREF = "Section_accelerate.html#acc_3">Accelerator packages with optimized styles</A>
<BR>
<UL> 5.3.1 <A HREF = "accelerate_cuda.html">USER-CUDA package</A>
<BR>
5.3.2 <A HREF = "accelerate_gpu.html">GPU package</A>
<BR>
5.3.3 <A HREF = "accelerate_intel.html">USER-INTEL package</A>
<BR>
5.3.4 <A HREF = "accelerate_kokkos.html">KOKKOS package</A>
<BR>
5.3.5 <A HREF = "accelerate_omp.html">USER-OMP package</A>
<BR>
5.3.6 <A HREF = "accelerate_opt.html">OPT package</A>
<BR></UL>
5.4 <A HREF = "Section_accelerate.html#acc_4">Comparison of various accelerator packages</A>
<BR></UL>
<LI><A HREF = "Section_howto.html">How-to discussions</A>
<UL> 6.1 <A HREF = "Section_howto.html#howto_1">Restarting a simulation</A>
<BR>
6.2 <A HREF = "Section_howto.html#howto_2">2d simulations</A>
<BR>
6.3 <A HREF = "Section_howto.html#howto_3">CHARMM and AMBER force fields</A>
<BR>
6.4 <A HREF = "Section_howto.html#howto_4">Running multiple simulations from one input script</A>
<BR>
6.5 <A HREF = "Section_howto.html#howto_5">Multi-replica simulations</A>
<BR>
6.6 <A HREF = "Section_howto.html#howto_6">Granular models</A>
<BR>
6.7 <A HREF = "Section_howto.html#howto_7">TIP3P water model</A>
<BR>
6.8 <A HREF = "Section_howto.html#howto_8">TIP4P water model</A>
<BR>
6.9 <A HREF = "Section_howto.html#howto_9">SPC water model</A>
<BR>
6.10 <A HREF = "Section_howto.html#howto_10">Coupling LAMMPS to other codes</A>
<BR>
6.11 <A HREF = "Section_howto.html#howto_11">Visualizing LAMMPS snapshots</A>
<BR>
6.12 <A HREF = "Section_howto.html#howto_12">Triclinic (non-orthogonal) simulation boxes</A>
<BR>
6.13 <A HREF = "Section_howto.html#howto_13">NEMD simulations</A>
<BR>
6.14 <A HREF = "Section_howto.html#howto_14">Finite-size spherical and aspherical particles</A>
<BR>
6.15 <A HREF = "Section_howto.html#howto_15">Output from LAMMPS (thermo, dumps, computes, fixes, variables)</A>
<BR>
6.16 <A HREF = "Section_howto.html#howto_16">Thermostatting, barostatting, and compute temperature</A>
<BR>
6.17 <A HREF = "Section_howto.html#howto_17">Walls</A>
<BR>
6.18 <A HREF = "Section_howto.html#howto_18">Elastic constants</A>
<BR>
6.19 <A HREF = "Section_howto.html#howto_19">Library interface to LAMMPS</A>
<BR>
6.20 <A HREF = "Section_howto.html#howto_20">Calculating thermal conductivity</A>
<BR>
6.21 <A HREF = "Section_howto.html#howto_21">Calculating viscosity</A>
<BR>
6.22 <A HREF = "Section_howto.html#howto_22">Calculating a diffusion coefficient</A>
<BR>
6.23 <A HREF = "Section_howto.html#howto_23">Using chunks to calculate system properties</A>
<BR>
6.24 <A HREF = "Section_howto.html#howto_24">Setting parameters for pppm/disp</A>
<BR>
6.25 <A HREF = "Section_howto.html#howto_25">Polarizable models</A>
<BR>
6.26 <A HREF = "Section_howto.html#howto_26">Adiabatic core/shell model</A>
<BR>
6.27 <A HREF = "Section_howto.html#howto_27">Drude induced dipoles</A>
<BR></UL>
<LI><A HREF = "Section_example.html">Example problems</A>
<LI><A HREF = "Section_perf.html">Performance & scalability</A>
<LI><A HREF = "Section_tools.html">Additional tools</A>
<LI><A HREF = "Section_modify.html">Modifying & extending LAMMPS</A>
<UL> 10.1 <A HREF = "Section_modify.html#mod_1">Atom styles</A>
<BR>
10.2 <A HREF = "Section_modify.html#mod_2">Bond, angle, dihedral, improper potentials</A>
<BR>
10.3 <A HREF = "Section_modify.html#mod_3">Compute styles</A>
<BR>
10.4 <A HREF = "Section_modify.html#mod_4">Dump styles</A>
<BR>
10.5 <A HREF = "Section_modify.html#mod_5">Dump custom output options</A>
<BR>
10.6 <A HREF = "Section_modify.html#mod_6">Fix styles</A>
<BR>
10.7 <A HREF = "Section_modify.html#mod_7">Input script commands</A>
<BR>
10.8 <A HREF = "Section_modify.html#mod_8">Kspace computations</A>
<BR>
10.9 <A HREF = "Section_modify.html#mod_9">Minimization styles</A>
<BR>
10.10 <A HREF = "Section_modify.html#mod_10">Pairwise potentials</A>
<BR>
10.11 <A HREF = "Section_modify.html#mod_11">Region styles</A>
<BR>
10.12 <A HREF = "Section_modify.html#mod_12">Body styles</A>
<BR>
10.13 <A HREF = "Section_modify.html#mod_13">Thermodynamic output options</A>
<BR>
10.14 <A HREF = "Section_modify.html#mod_14">Variable options</A>
<BR>
10.15 <A HREF = "Section_modify.html#mod_15">Submitting new features for inclusion in LAMMPS</A>
<BR></UL>
<LI><A HREF = "Section_python.html">Python interface</A>
<UL> 11.1 <A HREF = "Section_python.html#py_1">Overview of running LAMMPS from Python</A>
<BR>
11.2 <A HREF = "Section_python.html#py_2">Overview of using Python from a LAMMPS script</A>
<BR>
11.3 <A HREF = "Section_python.html#py_3">Building LAMMPS as a shared library</A>
<BR>
11.4 <A HREF = "Section_python.html#py_4">Installing the Python wrapper into Python</A>
<BR>
11.5 <A HREF = "Section_python.html#py_5">Extending Python with MPI to run in parallel</A>
<BR>
11.6 <A HREF = "Section_python.html#py_6">Testing the Python-LAMMPS interface</A>
<BR>
11.7 <A HREF = "py_7">Using LAMMPS from Python</A>
<BR>
11.8 <A HREF = "py_8">Example Python scripts that use LAMMPS</A>
<BR></UL>
<LI><A HREF = "Section_errors.html">Errors</A>
<UL> 12.1 <A HREF = "Section_errors.html#err_1">Common problems</A>
<BR>
12.2 <A HREF = "Section_errors.html#err_2">Reporting bugs</A>
<BR>
12.3 <A HREF = "Section_errors.html#err_3">Error & warning messages</A>
<BR></UL>
<LI><A HREF = "Section_history.html">Future and history</A>
<UL> 13.1 <A HREF = "Section_history.html#hist_1">Coming attractions</A>
<BR>
13.2 <A HREF = "Section_history.html#hist_2">Past versions</A>
<BR></UL>
</OL>
<!-- END_HTML_ONLY -->
</BODY>
</HTML>
we can improve the LAMMPS documentation.</p>
<p>Once you are familiar with LAMMPS, you may want to bookmark <a class="reference internal" href="Section_commands.html#comm"><span>this page</span></a> at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.</p>
<p><a class="reference external" href="Manual.pdf">PDF file</a> of the entire manual, generated by
<a class="reference external" href="http://freecode.com/projects/htmldoc">htmldoc</a></p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_intro.html#what-is-lammps">1.1. What is LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_intro.html#lammps-features">1.2. LAMMPS features</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_intro.html#lammps-non-features">1.3. LAMMPS non-features</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_intro.html#open-source-distribution">1.4. Open source distribution</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_intro.html#acknowledgments-and-citations">1.5. Acknowledgments and citations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#what-s-in-the-lammps-distribution">2.1. What&#8217;s in the LAMMPS distribution</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#making-lammps">2.2. Making LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#making-lammps-with-optional-packages">2.3. Making LAMMPS with optional packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#building-lammps-via-the-make-py-tool">2.4. Building LAMMPS via the Make.py tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#building-lammps-as-a-library">2.5. Building LAMMPS as a library</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#running-lammps">2.6. Running LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#command-line-options">2.7. Command-line options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#lammps-screen-output">2.8. LAMMPS screen output</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#tips-for-users-of-previous-lammps-versions">2.9. Tips for users of previous LAMMPS versions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#lammps-input-script">3.1. LAMMPS input script</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#parsing-rules">3.2. Parsing rules</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#input-script-structure">3.3. Input script structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#commands-listed-by-category">3.4. Commands listed by category</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#individual-commands">3.5. Individual commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#fix-styles">3.6. Fix styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#compute-styles">3.7. Compute styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#pair-style-potentials">3.8. Pair_style potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#bond-style-potentials">3.9. Bond_style potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#angle-style-potentials">3.10. Angle_style potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#dihedral-style-potentials">3.11. Dihedral_style potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#improper-style-potentials">3.12. Improper_style potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_commands.html#kspace-solvers">3.13. Kspace solvers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#standard-packages">4.1. Standard packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-compress-package">4.2. Build instructions for COMPRESS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-gpu-package">4.3. Build instructions for GPU package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-kim-package">4.4. Build instructions for KIM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-kokkos-package">4.5. Build instructions for KOKKOS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-kspace-package">4.6. Build instructions for KSPACE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-meam-package">4.7. Build instructions for MEAM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-poems-package">4.8. Build instructions for POEMS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-python-package">4.9. Build instructions for PYTHON package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-reax-package">4.10. Build instructions for REAX package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-voronoi-package">4.11. Build instructions for VORONOI package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#build-instructions-for-xtc-package">4.12. Build instructions for XTC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-packages">4.13. User packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-atc-package">4.14. USER-ATC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-awpmd-package">4.15. USER-AWPMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-cg-cmm-package">4.16. USER-CG-CMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-colvars-package">4.17. USER-COLVARS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-cuda-package">4.18. USER-CUDA package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-diffraction-package">4.19. USER-DIFFRACTION package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-drude-package">4.20. USER-DRUDE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-eff-package">4.21. USER-EFF package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-fep-package">4.22. USER-FEP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-h5md-package">4.23. USER-H5MD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-intel-package">4.24. USER-INTEL package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-lb-package">4.25. USER-LB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-misc-package">4.26. USER-MISC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-molfile-package">4.27. USER-MOLFILE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-omp-package">4.28. USER-OMP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-phonon-package">4.29. USER-PHONON package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-qmmm-package">4.30. USER-QMMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-qtb-package">4.31. USER-QTB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-reaxc-package">4.32. USER-REAXC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-smd-package">4.33. USER-SMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_packages.html#user-sph-package">4.34. USER-SPH package</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#measuring-performance">5.1. Measuring performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#general-strategies">5.2. General strategies</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#packages-with-optimized-styles">5.3. Packages with optimized styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#restarting-a-simulation">6.1. Restarting a simulation</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#d-simulations">6.2. 2d simulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#charmm-amber-and-dreiding-force-fields">6.3. CHARMM, AMBER, and DREIDING force fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#running-multiple-simulations-from-one-input-script">6.4. Running multiple simulations from one input script</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#multi-replica-simulations">6.5. Multi-replica simulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#granular-models">6.6. Granular models</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#tip3p-water-model">6.7. TIP3P water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#tip4p-water-model">6.8. TIP4P water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#spc-water-model">6.9. SPC water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#coupling-lammps-to-other-codes">6.10. Coupling LAMMPS to other codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#visualizing-lammps-snapshots">6.11. Visualizing LAMMPS snapshots</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#triclinic-non-orthogonal-simulation-boxes">6.12. Triclinic (non-orthogonal) simulation boxes</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#nemd-simulations">6.13. NEMD simulations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#finite-size-spherical-and-aspherical-particles">6.14. Finite-size spherical and aspherical particles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#output-from-lammps-thermo-dumps-computes-fixes-variables">6.15. Output from LAMMPS (thermo, dumps, computes, fixes, variables)</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#thermostatting-barostatting-and-computing-temperature">6.16. Thermostatting, barostatting, and computing temperature</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#walls">6.17. Walls</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#elastic-constants">6.18. Elastic constants</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#library-interface-to-lammps">6.19. Library interface to LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#calculating-thermal-conductivity">6.20. Calculating thermal conductivity</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#calculating-viscosity">6.21. Calculating viscosity</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#calculating-a-diffusion-coefficient">6.22. Calculating a diffusion coefficient</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#using-chunks-to-calculate-system-properties">6.23. Using chunks to calculate system properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#setting-parameters-for-the-kspace-style-pppm-disp-command">6.24. Setting parameters for the <code class="docutils literal"><span class="pre">kspace_style</span> <span class="pre">pppm/disp</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#polarizable-models">6.25. Polarizable models</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#adiabatic-core-shell-model">6.26. Adiabatic core/shell model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#drude-induced-dipoles">6.27. Drude induced dipoles</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#amber2lmp-tool">9.1. amber2lmp tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#binary2txt-tool">9.2. binary2txt tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#ch2lmp-tool">9.3. ch2lmp tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#chain-tool">9.4. chain tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#colvars-tools">9.5. colvars tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#createatoms-tool">9.6. createatoms tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#data2xmovie-tool">9.7. data2xmovie tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#eam-database-tool">9.8. eam database tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#eam-generate-tool">9.9. eam generate tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#eff-tool">9.10. eff tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#emacs-tool">9.11. emacs tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#fep-tool">9.12. fep tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#i-pi-tool">9.13. i-pi tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#ipp-tool">9.14. ipp tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#kate-tool">9.15. kate tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#lmp2arc-tool">9.16. lmp2arc tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#lmp2cfg-tool">9.17. lmp2cfg tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#lmp2vmd-tool">9.18. lmp2vmd tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#matlab-tool">9.19. matlab tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#micelle2d-tool">9.20. micelle2d tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#moltemplate-tool">9.21. moltemplate tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#msi2lmp-tool">9.22. msi2lmp tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#phonon-tool">9.23. phonon tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#polymer-bonding-tool">9.24. polymer bonding tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#pymol-asphere-tool">9.25. pymol_asphere tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#python-tool">9.26. python tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#reax-tool">9.27. reax tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#restart2data-tool">9.28. restart2data tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#vim-tool">9.29. vim tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#xmgrace-tool">9.30. xmgrace tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_tools.html#xmovie-tool">9.31. xmovie tool</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#atom-styles">10.1. Atom styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#bond-angle-dihedral-improper-potentials">10.2. Bond, angle, dihedral, improper potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#compute-styles">10.3. Compute styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#dump-styles">10.4. Dump styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#dump-custom-output-options">10.5. Dump custom output options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#fix-styles">10.6. Fix styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#input-script-commands">10.7. Input script commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#kspace-computations">10.8. Kspace computations</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#minimization-styles">10.9. Minimization styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#pairwise-potentials">10.10. Pairwise potentials</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#region-styles">10.11. Region styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#body-styles">10.12. Body styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#thermodynamic-output-options">10.13. Thermodynamic output options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#variable-options">10.14. Variable options</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#submitting-new-features-for-inclusion-in-lammps">10.15. Submitting new features for inclusion in LAMMPS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#overview-of-running-lammps-from-python">11.1. Overview of running LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#overview-of-using-python-from-a-lammps-script">11.2. Overview of using Python from a LAMMPS script</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#building-lammps-as-a-shared-library">11.3. Building LAMMPS as a shared library</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#installing-the-python-wrapper-into-python">11.4. Installing the Python wrapper into Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#extending-python-with-mpi-to-run-in-parallel">11.5. Extending Python with MPI to run in parallel</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#testing-the-python-lammps-interface">11.6. Testing the Python-LAMMPS interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#using-lammps-from-python">11.7. Using LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#example-python-scripts-that-use-lammps">11.8. Example Python scripts that use LAMMPS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_errors.html#common-problems">12.1. Common problems</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_errors.html#reporting-bugs">12.2. Reporting bugs</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_errors.html#error-warning-messages">12.3. Error &amp; warning messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_errors.html#error">12.4. Errors:</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_errors.html#warnings">12.5. Warnings:</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_history.html#coming-attractions">13.1. Coming attractions</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_history.html#past-versions">13.2. Past versions</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="indices-and-tables">
<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline"></a></h1>
<ul class="simple">
<li><a class="reference internal" href="genindex.html"><span>Index</span></a></li>
<li><a class="reference internal" href="search.html"><span>Search Page</span></a></li>
</ul>
</BODY></div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="Section_intro.html" class="btn btn-neutral float-right" title="1. Introduction" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>

4
doc/Manual.html.html
View File

@ -3,7 +3,7 @@
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="25 Sep 2015 version">
<META NAME="docnumber" CONTENT="5 Oct 2015 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
@ -21,7 +21,7 @@
<P><CENTER><H3>LAMMPS Documentation
</H3></CENTER>
<CENTER><H4>25 Sep 2015 version
<CENTER><H4>5 Oct 2015 version
</H4></CENTER>
<H4>Version info:
</H4>

4
doc/Manual.txt
View File

@ -1,7 +1,7 @@
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="5 Oct 2015 version">
<META NAME="docnumber" CONTENT="10 Aug 2015 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation. This software and manual is distributed under the GNU General Public License.">
</HEAD>
@ -21,7 +21,7 @@
<H1></H1>
LAMMPS Documentation :c,h3
5 Oct 2015 version :c,h4
10 Aug 2015 version :c,h4
Version info: :h4

53
doc/Section_accelerate.html
View File

@ -275,7 +275,8 @@ standard non-accelerated versions. Some require appropriate hardware
to be present on your system, e.g. GPUs or Intel Xeon Phi
coprocessors.</p>
<p>All of these commands are in packages provided with LAMMPS. An
overview of packages is give in <a class="reference internal" href="Section_packages.html"><em>Section packages</em></a>. These are the accelerator packages
overview of packages is give in <a class="reference internal" href="Section_packages.html"><em>Section packages</em></a>.</p>
<p>These are the accelerator packages
currently in LAMMPS, either as standard or user packages:</p>
<table border="1" class="docutils">
<colgroup>
@ -303,6 +304,30 @@ currently in LAMMPS, either as standard or user packages:</p>
</tr>
</tbody>
</table>
<p>Inverting this list, LAMMPS currently has acceleration support for
three kinds of hardware, via the listed packages:</p>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="90%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Many-core CPUs</td>
<td><a class="reference internal" href="accelerate_intel.html"><em>USER-INTEL</em></a>, <a class="reference internal" href="accelerate_kokkos.html"><em>KOKKOS</em></a>, <a class="reference internal" href="accelerate_omp.html"><em>USER-OMP</em></a>, <a class="reference internal" href="accelerate_opt.html"><em>OPT</em></a> packages</td>
</tr>
<tr class="row-even"><td>NVIDIA GPUs</td>
<td><a class="reference internal" href="accelerate_cuda.html"><em>USER-CUDA</em></a>, <a class="reference internal" href="accelerate_gpu.html"><em>GPU</em></a>, <a class="reference internal" href="accelerate_kokkos.html"><em>KOKKOS</em></a> packages</td>
</tr>
<tr class="row-odd"><td>Intel Phi</td>
<td><a class="reference internal" href="accelerate_intel.html"><em>USER-INTEL</em></a>, <a class="reference internal" href="accelerate_kokkos.html"><em>KOKKOS</em></a> packages</td>
</tr>
</tbody>
</table>
<p>Which package is fastest for your hardware may depend on the size
problem you are running and what commands (accelerated and
non-accelerated) are invoked by your input script. While these doc
pages include performance guidelines, there is no substitute for
trying out the different packages appropriate to your hardware.</p>
<p>Any accelerated style has the same name as the corresponding standard
style, except that a suffix is appended. Otherwise, the syntax for
the command that uses the style is identical, their functionality is
@ -345,7 +370,7 @@ listed above:</p>
<div class="line">install the accelerator package | make yes-opt, make yes-user-intel, etc |</div>
</div>
<blockquote>
<div>only for USER-INTEL, KOKKOS, USER-OMP packages |</div></blockquote>
<div>only for USER-INTEL, KOKKOS, USER-OMP, OPT packages |</div></blockquote>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
@ -355,15 +380,14 @@ listed above:</p>
<tr class="row-odd"><td>re-build LAMMPS</td>
<td>make machine</td>
</tr>
<tr class="row-even"><td>run a LAMMPS simulation</td>
<td>lmp_machine &lt; in.script</td>
</tr>
</tbody>
</table>
<div class="line-block">
<div class="line">run a LAMMPS simulation | lmp_machine &lt; in.script |</div>
<div class="line">re-build LAMMPS | make machine |</div>
</div>
<blockquote>
<div>mpirun -np 32 lmp_machine -in in.script |</div></blockquote>
<blockquote>
<div>only for USER-CUDA and KOKKOS packages |</div></blockquote>
<blockquote>
<div><a class="reference internal" href="package.html"><em>package</em></a> command, &lt;br&gt;
@ -376,8 +400,8 @@ only if defaults need to be changed |</div></blockquote>
<tbody valign="top">
</tbody>
</table>
<p>The first 4 steps can be done as a single command, using the
src/Make.py tool. The Make.py tool is discussed in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual, and its use is
<p>Note that the first 4 steps can be done as a single command, using the
src/Make.py tool. This tool is discussed in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual, and its use is
illustrated in the individual accelerator sections. Typically these
steps only need to be done once, to create an executable that uses one
or more accelerator packages.</p>
@ -389,12 +413,13 @@ script.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">With a few exceptions, you can build a single LAMMPS
executable with all its accelerator packages installed. Note that the
USER-INTEL and KOKKOS packages require you to choose one of their
options when building. I.e. CPU or Phi for USER-INTEL. OpenMP, Cuda,
or Phi for KOKKOS. Here are the exceptions; you cannot build a single
executable with:</p>
executable with all its accelerator packages installed. Note however
that the USER-INTEL and KOKKOS packages require you to choose one of
their hardware options when building for a specific platform.
I.e. CPU or Phi option for the USER-INTEL package. Or the OpenMP,
Cuda, or Phi option for the KOKKOS package.</p>
</div>
<p>These are the exceptions. You cannot build a single executable with:</p>
<ul class="simple">
<li>both the USER-INTEL Phi and KOKKOS Phi options</li>
<li>the USER-INTEL Phi or Kokkos Phi option, and either the USER-CUDA or GPU packages</li>
@ -491,7 +516,7 @@ snapshots, restart files), then the data transfer cost of the
USER-CUDA package can be very low, causing it to run faster than the
GPU package.</li>
<li>The GPU package is often faster than the USER-CUDA package, if the
number of atoms per GPU is &#8220;small&#8221;. The crossover point, in terms of
number of atoms per GPU is smaller. The crossover point, in terms of
atoms/GPU at which the USER-CUDA package becomes faster depends
strongly on the pair style. For example, for a simple Lennard Jones
system the crossover (in single precision) is often about 50K-100K

40
doc/Section_accelerate.txt
View File

@ -152,7 +152,9 @@ coprocessors.
All of these commands are in packages provided with LAMMPS. An
overview of packages is give in "Section
packages"_Section_packages.html. These are the accelerator packages
packages"_Section_packages.html.
These are the accelerator packages
currently in LAMMPS, either as standard or user packages:
"USER-CUDA"_accelerate_cuda.html : for NVIDIA GPUs
@ -162,6 +164,19 @@ currently in LAMMPS, either as standard or user packages:
"USER-OMP"_accelerate_omp.html : for OpenMP threading
"OPT"_accelerate_opt.html : generic CPU optimizations :tb(s=:)
Inverting this list, LAMMPS currently has acceleration support for
three kinds of hardware, via the listed packages:
Many-core CPUs : "USER-INTEL"_accelerate_intel.html, "KOKKOS"_accelerate_kokkos.html, "USER-OMP"_accelerate_omp.html, "OPT"_accelerate_opt.html packages
NVIDIA GPUs : "USER-CUDA"_accelerate_cuda.html, "GPU"_accelerate_gpu.html, "KOKKOS"_accelerate_kokkos.html packages
Intel Phi : "USER-INTEL"_accelerate_intel.html, "KOKKOS"_accelerate_kokkos.html packages :tb(s=:)
Which package is fastest for your hardware may depend on the size
problem you are running and what commands (accelerated and
non-accelerated) are invoked by your input script. While these doc
pages include performance guidelines, there is no substitute for
trying out the different packages appropriate to your hardware.
Any accelerated style has the same name as the corresponding standard
style, except that a suffix is appended. Otherwise, the syntax for
the command that uses the style is identical, their functionality is
@ -195,11 +210,12 @@ install the accelerator package |
make yes-opt, make yes-user-intel, etc |
add compile/link flags to Makefile.machine |
in src/MAKE, <br>
only for USER-INTEL, KOKKOS, USER-OMP packages |
only for USER-INTEL, KOKKOS, USER-OMP, OPT packages |
re-build LAMMPS |
make machine |
run a LAMMPS simulation |
lmp_machine < in.script |
lmp_machine < in.script <br>
mpirun -np 32 lmp_machine -in in.script |
enable the accelerator package |
via "-c on" and "-k on" "command-line switches"_Section_start.html#start_7, <br>
only for USER-CUDA and KOKKOS packages |
@ -211,8 +227,8 @@ use accelerated styles in your input script |
via "-sf" "command-line switch"_Section_start.html#start_7 or
"suffix"_suffix.html command :tb(c=2,s=|)
The first 4 steps can be done as a single command, using the
src/Make.py tool. The Make.py tool is discussed in "Section
Note that the first 4 steps can be done as a single command, using the
src/Make.py tool. This tool is discussed in "Section
2.4"_Section_start.html#start_4 of the manual, and its use is
illustrated in the individual accelerator sections. Typically these
steps only need to be done once, to create an executable that uses one
@ -225,11 +241,13 @@ individual accelerator sections. Or you can add
script.
IMPORTANT NOTE: With a few exceptions, you can build a single LAMMPS
executable with all its accelerator packages installed. Note that the
USER-INTEL and KOKKOS packages require you to choose one of their
options when building. I.e. CPU or Phi for USER-INTEL. OpenMP, Cuda,
or Phi for KOKKOS. Here are the exceptions; you cannot build a single
executable with:
executable with all its accelerator packages installed. Note however
that the USER-INTEL and KOKKOS packages require you to choose one of
their hardware options when building for a specific platform.
I.e. CPU or Phi option for the USER-INTEL package. Or the OpenMP,
Cuda, or Phi option for the KOKKOS package.
These are the exceptions. You cannot build a single executable with:
both the USER-INTEL Phi and KOKKOS Phi options
the USER-INTEL Phi or Kokkos Phi option, and either the USER-CUDA or GPU packages :ul
@ -339,7 +357,7 @@ USER-CUDA package can be very low, causing it to run faster than the
GPU package. :l
The GPU package is often faster than the USER-CUDA package, if the
number of atoms per GPU is "small". The crossover point, in terms of
number of atoms per GPU is smaller. The crossover point, in terms of
atoms/GPU at which the USER-CUDA package becomes faster depends
strongly on the pair style. For example, for a simple Lennard Jones
system the crossover (in single precision) is often about 50K-100K

6
doc/Section_commands.html
View File

@ -1136,11 +1136,11 @@ KOKKOS, o = USER-OMP, t = OPT.</p>
</tr>
<tr class="row-odd"><td><a class="reference internal" href="pair_coul.html"><em>tip4p/long (o)</em></a></td>
<td><a class="reference internal" href="pair_tri_lj.html"><em>tri/lj (o)</em></a></td>
<td><a class="reference internal" href="pair_vashishta.html"><em>vashishta (o)</em></a></td>
<td><a class="reference internal" href="pair_yukawa.html"><em>yukawa (go)</em></a></td>
<td><a class="reference internal" href="pair_yukawa_colloid.html"><em>yukawa/colloid (go)</em></a></td>
</tr>
<tr class="row-even"><td><a class="reference internal" href="pair_zbl.html"><em>zbl (go)</em></a></td>
<td>&nbsp;</td>
<tr class="row-even"><td><a class="reference internal" href="pair_yukawa_colloid.html"><em>yukawa/colloid (go)</em></a></td>
<td><a class="reference internal" href="pair_zbl.html"><em>zbl (go)</em></a></td>
<td>&nbsp;</td>
<td>&nbsp;</td>
</tr>

2
doc/Section_commands.txt
View File

@ -887,7 +887,7 @@ KOKKOS, o = USER-OMP, t = OPT.
"tip4p/cut (o)"_pair_coul.html,
"tip4p/long (o)"_pair_coul.html,
"tri/lj (o)"_pair_tri_lj.html,
"vashishta"_pair_vashishta.html,
"vashishta (o)"_pair_vashishta.html,
"yukawa (go)"_pair_yukawa.html,
"yukawa/colloid (go)"_pair_yukawa_colloid.html,
"zbl (go)"_pair_zbl.html :tb(c=4,ea=c)

215
doc/Section_packages.html
View File

@ -79,28 +79,39 @@
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">4. Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#standard-packages">4.1. Standard packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-packages">4.2. User packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-atc-package">4.3. USER-ATC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-awpmd-package">4.4. USER-AWPMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-cg-cmm-package">4.5. USER-CG-CMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-colvars-package">4.6. USER-COLVARS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-cuda-package">4.7. USER-CUDA package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-diffraction-package">4.8. USER-DIFFRACTION package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-drude-package">4.9. USER-DRUDE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-eff-package">4.10. USER-EFF package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-fep-package">4.11. USER-FEP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-h5md-package">4.12. USER-H5MD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-intel-package">4.13. USER-INTEL package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-lb-package">4.14. USER-LB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-misc-package">4.15. USER-MISC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-molfile-package">4.16. USER-MOLFILE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-omp-package">4.17. USER-OMP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-phonon-package">4.18. USER-PHONON package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-qmmm-package">4.19. USER-QMMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-qtb-package">4.20. USER-QTB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-reaxc-package">4.21. USER-REAXC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-smd-package">4.22. USER-SMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-sph-package">4.23. USER-SPH package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-compress-package">4.2. Build instructions for COMPRESS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-gpu-package">4.3. Build instructions for GPU package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-kim-package">4.4. Build instructions for KIM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-kokkos-package">4.5. Build instructions for KOKKOS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-kspace-package">4.6. Build instructions for KSPACE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-meam-package">4.7. Build instructions for MEAM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-poems-package">4.8. Build instructions for POEMS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-python-package">4.9. Build instructions for PYTHON package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-reax-package">4.10. Build instructions for REAX package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-voronoi-package">4.11. Build instructions for VORONOI package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-instructions-for-xtc-package">4.12. Build instructions for XTC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-packages">4.13. User packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-atc-package">4.14. USER-ATC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-awpmd-package">4.15. USER-AWPMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-cg-cmm-package">4.16. USER-CG-CMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-colvars-package">4.17. USER-COLVARS package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-cuda-package">4.18. USER-CUDA package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-diffraction-package">4.19. USER-DIFFRACTION package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-drude-package">4.20. USER-DRUDE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-eff-package">4.21. USER-EFF package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-fep-package">4.22. USER-FEP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-h5md-package">4.23. USER-H5MD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-intel-package">4.24. USER-INTEL package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-lb-package">4.25. USER-LB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-misc-package">4.26. USER-MISC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-molfile-package">4.27. USER-MOLFILE package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-omp-package">4.28. USER-OMP package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-phonon-package">4.29. USER-PHONON package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-qmmm-package">4.30. USER-QMMM package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-qtb-package">4.31. USER-QTB package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-reaxc-package">4.32. USER-REAXC package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-smd-package">4.33. USER-SMD package</a></li>
<li class="toctree-l2"><a class="reference internal" href="#user-sph-package">4.34. USER-SPH package</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
@ -177,13 +188,26 @@ directory of the LAMMPS distribution.</p>
<p>See <a class="reference internal" href="Section_start.html#start-3"><span>Section_start 3</span></a> of the manual for
details on how to include/exclude specific packages as part of the
LAMMPS build process, and for more details about the differences
between standard packages and user packages in LAMMPS.</p>
<p>Below, the packages currently availabe in LAMMPS are listed. For
standard packages, just a one-line description is given. For user
packages, more details are provided.</p>
between standard packages and user packages.</p>
<p>Unless otherwise noted below, every package is independent of all the
others. I.e. any package can be included or excluded in a LAMMPS
build, independent of all other packages. However, note that some
packages include commands derived from commands in other packages. If
the other package is not installed, the derived command from the new
package will also not be installed when you include the new one.
E.g. the pair lj/cut/coul/long/omp command from the USER-OMP package
will not be installed as part of the USER-OMP package if the KSPACE
package is not also installed, since it contains the pair
lj/cut/coul/long command. If you later install the KSPACE pacakge and
the USER-OMP package is already installed, both the pair
lj/cut/coul/long and lj/cut/coul/long/omp commands will be installed.</p>
<p>The two tables below list currently available packages in LAMMPS, with
a one-line descriptions of each. The sections below give a few more
details, including instructions for building LAMMPS with the package,
either via the make command or the Make.py tool described in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a>.</p>
<div class="section" id="standard-packages">
<span id="pkg-1"></span><h2>4.1. Standard packages<a class="headerlink" href="#standard-packages" title="Permalink to this headline"></a></h2>
<p>The current list of standard packages is as follows:</p>
<p>The current list of standard packages is as follows.</p>
<table border="1" class="docutils">
<colgroup>
<col width="7%" />
@ -549,7 +573,9 @@ packages, more details are provided.</p>
</tbody>
</table>
<p>The &#8220;Authors&#8221; column lists a name(s) if a specific person is
responible for creating and maintaining the package.</p>
responible for creating and maintaining the package.
More details on
multiple authors are give below.</p>
<p>(1) The FLD package was created by Amit Kumar and Michael Bybee from
Jonathan Higdon&#8217;s group at UIUC.</p>
<p>(2) The OPT package was created by James Fischer (High Performance
@ -575,9 +601,61 @@ it is a third-party library not included in the LAMMPS distribution.
See the src/package/README or src/package/Makefile.lammps file for
info on where to download the library. <a class="reference internal" href="Section_start.html#start-3-3"><span>Section start</span></a> of the manual also gives details
on how to build LAMMPS with both kinds of auxiliary libraries.</p>
<p>Except where explained below, all of these packages can be installed,
and LAMMPS re-built, by issuing these commands from the src dir.</p>
<div class="highlight-python"><div class="highlight"><pre>make yes-package
make machine
or
Make.py -p package -a machine
</pre></div>
</div>
<p>To un-install the package and re-build LAMMPS without it:</p>
<div class="highlight-python"><div class="highlight"><pre>make no-package
make machine
or
Make.py -p ^package -a machine
</pre></div>
</div>
<p>&#8220;Package&#8221; is the name of the package in lower-case letters,
e.g. asphere or rigid, and &#8220;machine&#8221; is the build target, e.g. mpi or
serial.</p>
</div>
<div class="section" id="build-instructions-for-compress-package">
<h2>4.2. Build instructions for COMPRESS package<a class="headerlink" href="#build-instructions-for-compress-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-gpu-package">
<h2>4.3. Build instructions for GPU package<a class="headerlink" href="#build-instructions-for-gpu-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-kim-package">
<h2>4.4. Build instructions for KIM package<a class="headerlink" href="#build-instructions-for-kim-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-kokkos-package">
<h2>4.5. Build instructions for KOKKOS package<a class="headerlink" href="#build-instructions-for-kokkos-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-kspace-package">
<h2>4.6. Build instructions for KSPACE package<a class="headerlink" href="#build-instructions-for-kspace-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-meam-package">
<h2>4.7. Build instructions for MEAM package<a class="headerlink" href="#build-instructions-for-meam-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-poems-package">
<h2>4.8. Build instructions for POEMS package<a class="headerlink" href="#build-instructions-for-poems-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-python-package">
<h2>4.9. Build instructions for PYTHON package<a class="headerlink" href="#build-instructions-for-python-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-reax-package">
<h2>4.10. Build instructions for REAX package<a class="headerlink" href="#build-instructions-for-reax-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-voronoi-package">
<h2>4.11. Build instructions for VORONOI package<a class="headerlink" href="#build-instructions-for-voronoi-package" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="build-instructions-for-xtc-package">
<h2>4.12. Build instructions for XTC package<a class="headerlink" href="#build-instructions-for-xtc-package" title="Permalink to this headline"></a></h2>
<hr class="docutils" />
</div>
<div class="section" id="user-packages">
<span id="pkg-2"></span><h2>4.2. User packages<a class="headerlink" href="#user-packages" title="Permalink to this headline"></a></h2>
<span id="pkg-2"></span><h2>4.13. User packages<a class="headerlink" href="#user-packages" title="Permalink to this headline"></a></h2>
<p>The current list of user-contributed packages is as follows:</p>
<table border="1" class="docutils">
<colgroup>
@ -908,11 +986,7 @@ on how to build LAMMPS with both kinds of auxiliary libraries.</p>
</table>
<p>The &#8220;Authors&#8221; column lists a name(s) if a specific person is
responible for creating and maintaining the package.</p>
<p>If the Library is not listed as lib/package, then it is a third-party
library not included in the LAMMPS distribution. See the
src/package/Makefile.lammps file for info on where to download the
library from.</p>
<p>(2) The ATC package was created by Reese Jones, Jeremy Templeton, and
<p>(1) The ATC package was created by Reese Jones, Jeremy Templeton, and
Jon Zimmerman (Sandia).</p>
<p>(2) The COLVARS package was created by Axel Kohlmeyer (Temple U) using
the colvars module library written by Giacomo Fiorin (Temple U) and
@ -920,10 +994,14 @@ Jerome Henin (LISM, Marseille, France).</p>
<p>(3) The DRUDE package was created by Alain Dequidt (U Blaise Pascal
Clermont-Ferrand) and co-authors Julien Devemy (CNRS) and Agilio Padua
(U Blaise Pascal).</p>
<p>If the Library is not listed as lib/package, then it is a third-party
library not included in the LAMMPS distribution. See the
src/package/Makefile.lammps file for info on where to download the
library from.</p>
<p>The &#8220;Doc page&#8221; column links to either a portion of the
<a class="reference internal" href="Section_howto.html"><em>Section_howto</em></a> of the manual, or an input script
command implemented as part of the package, or to additional
documentation provided witht he package.</p>
documentation provided within the package.</p>
<p>The &#8220;Example&#8221; column is a sub-directory in the examples directory of
the distribution which has an input script that uses the package.
E.g. &#8220;peptide&#8221; refers to the examples/peptide directory. USER/cuda
@ -938,12 +1016,27 @@ See the src/package/Makefile.lammps file for info on where to download
the library. <a class="reference internal" href="Section_start.html#start-3-3"><span>Section start</span></a> of the
manual also gives details on how to build LAMMPS with both kinds of
auxiliary libraries.</p>
<p>More details on each package, from the USER-<a href="#id2"><span class="problematic" id="id3">*</span></a>/README file is given
below.</p>
<p>Except where explained below, all of these packages can be installed,
and LAMMPS re-built, by issuing these commands from the src dir.</p>
<div class="highlight-python"><div class="highlight"><pre>make yes-user-package
make machine
or
Make.py -p package -a machine
</pre></div>
</div>
<p>To un-install the package and re-build LAMMPS without it:</p>
<div class="highlight-python"><div class="highlight"><pre>make no-user-package
make machine
or
Make.py -p ^package -a machine
</pre></div>
</div>
<p>&#8220;Package&#8221; is the name of the package (in this case without the user
prefix) in lower-case letters, e.g. drude or phonon, and &#8220;machine&#8221; is
the build target, e.g. mpi or serial.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-atc-package">
<h2>4.3. USER-ATC package<a class="headerlink" href="#user-atc-package" title="Permalink to this headline"></a></h2>
<h2>4.14. USER-ATC package<a class="headerlink" href="#user-atc-package" title="Permalink to this headline"></a></h2>
<p>This package implements a &#8220;fix atc&#8221; command which can be used in a
LAMMPS input script. This fix can be employed to either do concurrent
coupling of MD with FE-based physics surrogates or on-the-fly
@ -963,7 +1056,7 @@ you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-awpmd-package">
<h2>4.4. USER-AWPMD package<a class="headerlink" href="#user-awpmd-package" title="Permalink to this headline"></a></h2>
<h2>4.15. USER-AWPMD package<a class="headerlink" href="#user-awpmd-package" title="Permalink to this headline"></a></h2>
<p>This package contains a LAMMPS implementation of the Antisymmetrized
Wave Packet Molecular Dynamics (AWPMD) method.</p>
<p>See the doc page for the pair_style awpmd/cut command to get started.</p>
@ -978,7 +1071,7 @@ have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-cg-cmm-package">
<h2>4.5. USER-CG-CMM package<a class="headerlink" href="#user-cg-cmm-package" title="Permalink to this headline"></a></h2>
<h2>4.16. USER-CG-CMM package<a class="headerlink" href="#user-cg-cmm-package" title="Permalink to this headline"></a></h2>
<p>This package implements 3 commands which can be used in a LAMMPS input
script:</p>
<ul class="simple">
@ -1013,7 +1106,7 @@ simulation systems.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-colvars-package">
<h2>4.6. USER-COLVARS package<a class="headerlink" href="#user-colvars-package" title="Permalink to this headline"></a></h2>
<h2>4.17. USER-COLVARS package<a class="headerlink" href="#user-colvars-package" title="Permalink to this headline"></a></h2>
<p>This package implements the &#8220;fix colvars&#8221; command which can be
used in a LAMMPS input script.</p>
<p>This fix allows to use &#8220;collective variables&#8221; to implement
@ -1042,7 +1135,7 @@ beta quality.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-cuda-package">
<h2>4.7. USER-CUDA package<a class="headerlink" href="#user-cuda-package" title="Permalink to this headline"></a></h2>
<h2>4.18. USER-CUDA package<a class="headerlink" href="#user-cuda-package" title="Permalink to this headline"></a></h2>
<p>This package provides acceleration of various LAMMPS pair styles, fix
styles, compute styles, and long-range Coulombics via PPPM for NVIDIA
GPUs.</p>
@ -1060,7 +1153,7 @@ tu-ilmenau.de). Contact him directly if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-diffraction-package">
<h2>4.8. USER-DIFFRACTION package<a class="headerlink" href="#user-diffraction-package" title="Permalink to this headline"></a></h2>
<h2>4.19. USER-DIFFRACTION package<a class="headerlink" href="#user-diffraction-package" title="Permalink to this headline"></a></h2>
<p>This package contains the commands neeed to calculate x-ray and
electron diffraction intensities based on kinematic diffraction
theory.</p>
@ -1076,7 +1169,7 @@ Arkansas. Contact him directly if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-drude-package">
<h2>4.9. USER-DRUDE package<a class="headerlink" href="#user-drude-package" title="Permalink to this headline"></a></h2>
<h2>4.20. USER-DRUDE package<a class="headerlink" href="#user-drude-package" title="Permalink to this headline"></a></h2>
<p>This package implements methods for simulating polarizable systems
in LAMMPS using thermalized Drude oscillators.</p>
<p>See these doc pages and their related commands to get started:</p>
@ -1096,7 +1189,7 @@ Agilio Padua.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-eff-package">
<h2>4.10. USER-EFF package<a class="headerlink" href="#user-eff-package" title="Permalink to this headline"></a></h2>
<h2>4.21. USER-EFF package<a class="headerlink" href="#user-eff-package" title="Permalink to this headline"></a></h2>
<p>This package contains a LAMMPS implementation of the electron Force
Field (eFF) currently under development at Caltech, as described in
A. Jaramillo-Botero, J. Su, Q. An, and W.A. Goddard III, JCC,
@ -1130,7 +1223,7 @@ have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-fep-package">
<h2>4.11. USER-FEP package<a class="headerlink" href="#user-fep-package" title="Permalink to this headline"></a></h2>
<h2>4.22. USER-FEP package<a class="headerlink" href="#user-fep-package" title="Permalink to this headline"></a></h2>
<p>This package provides methods for performing free energy perturbation
simulations with soft-core pair potentials in LAMMPS.</p>
<p>See these doc pages and their related commands to get started:</p>
@ -1145,7 +1238,7 @@ Contact him directly if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-h5md-package">
<h2>4.12. USER-H5MD package<a class="headerlink" href="#user-h5md-package" title="Permalink to this headline"></a></h2>
<h2>4.23. USER-H5MD package<a class="headerlink" href="#user-h5md-package" title="Permalink to this headline"></a></h2>
<p>This package contains a <a class="reference internal" href="dump_h5md.html"><em>dump h5md</em></a> command for
performing a dump of atom properties in HDF5 format. <a class="reference external" href="http://www.hdfgroup.org/HDF5/">HDF5 files</a> are binary, portable and self-describing and can be
examined and used by a variety of auxiliary tools. The output HDF5
@ -1159,7 +1252,7 @@ directly if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-intel-package">
<h2>4.13. USER-INTEL package<a class="headerlink" href="#user-intel-package" title="Permalink to this headline"></a></h2>
<h2>4.24. USER-INTEL package<a class="headerlink" href="#user-intel-package" title="Permalink to this headline"></a></h2>
<p>This package provides options for performing neighbor list and
non-bonded force calculations in single, mixed, or double precision
and also a capability for accelerating calculations with an
@ -1171,7 +1264,7 @@ Intel(R) Xeon Phi(TM) coprocessor.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-lb-package">
<h2>4.14. USER-LB package<a class="headerlink" href="#user-lb-package" title="Permalink to this headline"></a></h2>
<h2>4.25. USER-LB package<a class="headerlink" href="#user-lb-package" title="Permalink to this headline"></a></h2>
<p>This package contains a LAMMPS implementation of a background
Lattice-Boltzmann fluid, which can be used to model MD particles
influenced by hydrodynamic forces.</p>
@ -1183,10 +1276,10 @@ Western Ontario. Contact them directly if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-misc-package">
<h2>4.15. USER-MISC package<a class="headerlink" href="#user-misc-package" title="Permalink to this headline"></a></h2>
<h2>4.26. USER-MISC package<a class="headerlink" href="#user-misc-package" title="Permalink to this headline"></a></h2>
<p>The files in this package are a potpourri of (mostly) unrelated
features contributed to LAMMPS by users. Each feature is a single
pair of files (<a href="#id4"><span class="problematic" id="id5">*</span></a>.cpp and <a href="#id6"><span class="problematic" id="id7">*</span></a>.h).</p>
pair of files (<a href="#id2"><span class="problematic" id="id3">*</span></a>.cpp and <a href="#id4"><span class="problematic" id="id5">*</span></a>.h).</p>
<p>More information about each feature can be found by reading its doc
page in the LAMMPS doc directory. The doc page which lists all LAMMPS
input script commands is as follows:</p>
@ -1200,7 +1293,7 @@ about the feature or its coding.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-molfile-package">
<h2>4.16. USER-MOLFILE package<a class="headerlink" href="#user-molfile-package" title="Permalink to this headline"></a></h2>
<h2>4.27. USER-MOLFILE package<a class="headerlink" href="#user-molfile-package" title="Permalink to this headline"></a></h2>
<p>This package contains a dump molfile command which uses molfile
plugins that are bundled with the
<a class="reference external" href="http://www.ks.uiuc.edu/Research/vmd">VMD</a> molecular visualization and
@ -1219,7 +1312,7 @@ application itself.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-omp-package">
<h2>4.17. USER-OMP package<a class="headerlink" href="#user-omp-package" title="Permalink to this headline"></a></h2>
<h2>4.28. USER-OMP package<a class="headerlink" href="#user-omp-package" title="Permalink to this headline"></a></h2>
<p>This package provides OpenMP multi-threading support and
other optimizations of various LAMMPS pair styles, dihedral
styles, and fix styles.</p>
@ -1230,7 +1323,7 @@ styles, and fix styles.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-phonon-package">
<h2>4.18. USER-PHONON package<a class="headerlink" href="#user-phonon-package" title="Permalink to this headline"></a></h2>
<h2>4.29. USER-PHONON package<a class="headerlink" href="#user-phonon-package" title="Permalink to this headline"></a></h2>
<p>This package contains a fix phonon command that calculates dynamical
matrices, which can then be used to compute phonon dispersion
relations, directly from molecular dynamics simulations.</p>
@ -1242,7 +1335,7 @@ if you have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-qmmm-package">
<h2>4.19. USER-QMMM package<a class="headerlink" href="#user-qmmm-package" title="Permalink to this headline"></a></h2>
<h2>4.30. USER-QMMM package<a class="headerlink" href="#user-qmmm-package" title="Permalink to this headline"></a></h2>
<p>This package provides a fix qmmm command which allows LAMMPS to be
used in a QM/MM simulation, currently only in combination with pw.x
code from the <a class="reference external" href="http://www.quantum-espresso.org">Quantum ESPRESSO</a> package.</p>
@ -1259,7 +1352,7 @@ without changes to LAMMPS itself.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-qtb-package">
<h2>4.20. USER-QTB package<a class="headerlink" href="#user-qtb-package" title="Permalink to this headline"></a></h2>
<h2>4.31. USER-QTB package<a class="headerlink" href="#user-qtb-package" title="Permalink to this headline"></a></h2>
<p>This package provides a self-consistent quantum treatment of the
vibrational modes in a classical molecular dynamics simulation. By
coupling the MD simulation to a colored thermostat, it introduces zero
@ -1281,7 +1374,7 @@ have questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-reaxc-package">
<h2>4.21. USER-REAXC package<a class="headerlink" href="#user-reaxc-package" title="Permalink to this headline"></a></h2>
<h2>4.32. USER-REAXC package<a class="headerlink" href="#user-reaxc-package" title="Permalink to this headline"></a></h2>
<p>This package contains a implementation for LAMMPS of the ReaxFF force
field. ReaxFF uses distance-dependent bond-order functions to
represent the contributions of chemical bonding to the potential
@ -1309,7 +1402,7 @@ questions.</p>
</div>
<hr class="docutils" />
<div class="section" id="user-smd-package">
<h2>4.22. USER-SMD package<a class="headerlink" href="#user-smd-package" title="Permalink to this headline"></a></h2>
<h2>4.33. USER-SMD package<a class="headerlink" href="#user-smd-package" title="Permalink to this headline"></a></h2>
<p>This package implements smoothed Mach dynamics (SMD) in
LAMMPS. Currently, the package has the following features:</p>
<ul class="simple">
@ -1322,7 +1415,7 @@ strength models, i.e. pressure and deviatoric stresses are separated.</li>
hardening, Mie-Grueneisen, Polynomial EOS). Easy to add new
material models.</li>
<li>Rigid boundary conditions (walls) can be loaded as surface geometries
from <a href="#id9"><span class="problematic" id="id10">*</span></a>.STL files.</li>
from <a href="#id7"><span class="problematic" id="id8">*</span></a>.STL files.</li>
</ul>
<p>See the file doc/PDF/SMD_LAMMPS_userguide.pdf to get started.</p>
<p>There are example scripts for using this package in examples/USER/smd.</p>
@ -1332,7 +1425,7 @@ Germany (georg.ganzenmueller at emi.fhg.de). Contact him directly if
you have questions.</p>
</div>
<div class="section" id="user-sph-package">
<h2>4.23. USER-SPH package<a class="headerlink" href="#user-sph-package" title="Permalink to this headline"></a></h2>
<h2>4.34. USER-SPH package<a class="headerlink" href="#user-sph-package" title="Permalink to this headline"></a></h2>
<p>This package implements smoothed particle hydrodynamics (SPH) in
LAMMPS. Currently, the package has the following features:</p>
<ul class="simple">

126
doc/Section_packages.txt
View File

@ -25,18 +25,33 @@ directory of the LAMMPS distribution.
See "Section_start 3"_Section_start.html#start_3 of the manual for
details on how to include/exclude specific packages as part of the
LAMMPS build process, and for more details about the differences
between standard packages and user packages in LAMMPS.
between standard packages and user packages.
Below, the packages currently availabe in LAMMPS are listed. For
standard packages, just a one-line description is given. For user
packages, more details are provided.
Unless otherwise noted below, every package is independent of all the
others. I.e. any package can be included or excluded in a LAMMPS
build, independent of all other packages. However, note that some
packages include commands derived from commands in other packages. If
the other package is not installed, the derived command from the new
package will also not be installed when you include the new one.
E.g. the pair lj/cut/coul/long/omp command from the USER-OMP package
will not be installed as part of the USER-OMP package if the KSPACE
package is not also installed, since it contains the pair
lj/cut/coul/long command. If you later install the KSPACE pacakge and
the USER-OMP package is already installed, both the pair
lj/cut/coul/long and lj/cut/coul/long/omp commands will be installed.
The two tables below list currently available packages in LAMMPS, with
a one-line descriptions of each. The sections below give a few more
details, including instructions for building LAMMPS with the package,
either via the make command or the Make.py tool described in "Section
2.4"_Section_start.html#start_4.
:line
:line
4.1 Standard packages :h4,link(pkg_1)
The current list of standard packages is as follows:
The current list of standard packages is as follows.
Package, Description, Author(s), Doc page, Example, Library
ASPHERE, aspherical particles, -, "Section_howto 6.14"_Section_howto.html#howto_14, ellipse, -
@ -72,6 +87,8 @@ XTC, dumps in XTC format, -, "dump"_dump.html, -, -
The "Authors" column lists a name(s) if a specific person is
responible for creating and maintaining the package.
More details on
multiple authors are give below.
(1) The FLD package was created by Amit Kumar and Michael Bybee from
Jonathan Higdon's group at UIUC.
@ -106,6 +123,70 @@ info on where to download the library. "Section
start"_Section_start.html#start_3_3 of the manual also gives details
on how to build LAMMPS with both kinds of auxiliary libraries.
Except where explained below, all of these packages can be installed,
and LAMMPS re-built, by issuing these commands from the src dir.
make yes-package
make machine
or
Make.py -p package -a machine :pre
To un-install the package and re-build LAMMPS without it:
make no-package
make machine
or
Make.py -p ^package -a machine :pre
"Package" is the name of the package in lower-case letters,
e.g. asphere or rigid, and "machine" is the build target, e.g. mpi or
serial.
:line
:line
Build instructions for COMPRESS package :h4
:line
Build instructions for GPU package :h4
:line
Build instructions for KIM package :h4
:line
Build instructions for KOKKOS package :h4
:line
Build instructions for KSPACE package :h4
:line
Build instructions for MEAM package :h4
:line
Build instructions for POEMS package :h4
:line
Build instructions for PYTHON package :h4
:line
Build instructions for REAX package :h4
:line
Build instructions for VORONOI package :h4
:line
Build instructions for XTC package :h4
:line
:line
@ -148,12 +229,7 @@ USER-TALLY, Pairwise tallied computes, Axel Kohlmeyer (Temple U), "compute <...>
The "Authors" column lists a name(s) if a specific person is
responible for creating and maintaining the package.
If the Library is not listed as lib/package, then it is a third-party
library not included in the LAMMPS distribution. See the
src/package/Makefile.lammps file for info on where to download the
library from.
(2) The ATC package was created by Reese Jones, Jeremy Templeton, and
(1) The ATC package was created by Reese Jones, Jeremy Templeton, and
Jon Zimmerman (Sandia).
(2) The COLVARS package was created by Axel Kohlmeyer (Temple U) using
@ -164,10 +240,15 @@ Jerome Henin (LISM, Marseille, France).
Clermont-Ferrand) and co-authors Julien Devemy (CNRS) and Agilio Padua
(U Blaise Pascal).
If the Library is not listed as lib/package, then it is a third-party
library not included in the LAMMPS distribution. See the
src/package/Makefile.lammps file for info on where to download the
library from.
The "Doc page" column links to either a portion of the
"Section_howto"_Section_howto.html of the manual, or an input script
command implemented as part of the package, or to additional
documentation provided witht he package.
documentation provided within the package.
The "Example" column is a sub-directory in the examples directory of
the distribution which has an input script that uses the package.
@ -185,9 +266,26 @@ the library. "Section start"_Section_start.html#start_3_3 of the
manual also gives details on how to build LAMMPS with both kinds of
auxiliary libraries.
More details on each package, from the USER-*/README file is given
below.
Except where explained below, all of these packages can be installed,
and LAMMPS re-built, by issuing these commands from the src dir.
make yes-user-package
make machine
or
Make.py -p package -a machine :pre
To un-install the package and re-build LAMMPS without it:
make no-user-package
make machine
or
Make.py -p ^package -a machine :pre
"Package" is the name of the package (in this case without the user
prefix) in lower-case letters, e.g. drude or phonon, and "machine" is
the build target, e.g. mpi or serial.
:line
:line
USER-ATC package :h4

78
doc/Section_start.html
View File

@ -79,7 +79,7 @@
<li class="toctree-l2"><a class="reference internal" href="#what-s-in-the-lammps-distribution">2.1. What&#8217;s in the LAMMPS distribution</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-lammps">2.2. Making LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-lammps-with-optional-packages">2.3. Making LAMMPS with optional packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-via-the-make-py-script">2.4. Building LAMMPS via the Make.py script</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-via-the-make-py-tool">2.4. Building LAMMPS via the Make.py tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-as-a-library">2.5. Building LAMMPS as a library</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#static-library">2.5.1. <strong>Static library:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#shared-library">2.5.2. <strong>Shared library:</strong></a></li>
@ -699,9 +699,6 @@ excluded, you can build it yourself.</p>
<p>One way to do this is install and use cygwin to build LAMMPS with a
standard unix style make program, just as you would on a Linux box;
see src/MAKE/MACHINES/Makefile.cygwin.</p>
<p>The other way to do this is using Visual Studio and project files.
See the src/WINDOWS directory and its README.txt file for instructions
on both a basic build and a customized build with pacakges you select.</p>
<hr class="docutils" />
</div>
<div class="section" id="making-lammps-with-optional-packages">
@ -734,32 +731,35 @@ package. You can also type</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lmp_machine</span> <span class="o">-</span><span class="n">h</span>
</pre></div>
</div>
<p>to run your executable with the optional <a class="reference internal" href="#start-7"><span>-h command-line switch</span></a> for &#8220;help&#8221;, which will list the styles and commands
known to your executable.</p>
<p>to run your executable with the optional <a class="reference internal" href="#start-7"><span>-h command-line switch</span></a> for &#8220;help&#8221;, which will simply list the styles and
commands known to your executable, and immediately exit.</p>
<p>There are two kinds of packages in LAMMPS, standard and user packages.
More information about the contents of standard and user packages is
given in <a class="reference internal" href="Section_packages.html"><em>Section_packages</em></a> of the manual. The
difference between standard and user packages is as follows:</p>
<p>Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.</p>
<p>User packages have been contributed by users, and always begin with
the user prefix. If they are a single command (single file), they are
typically in the user-misc package. Otherwise, they are a a set of
files grouped together which add a specific functionality to the code.</p>
<p>Standard packages, such as molecule or kspace, are supported by the
LAMMPS developers and are written in a syntax and style consistent
with the rest of LAMMPS. This means we will answer questions about
them, debug and fix them if necessary, and keep them compatible with
future changes to LAMMPS.</p>
<p>User packages, such as user-atc or user-omp, have been contributed by
users, and always begin with the user prefix. If they are a single
command (single file), they are typically in the user-misc package.
Otherwise, they are a a set of files grouped together which add a
specific functionality to the code.</p>
<p>User packages don&#8217;t necessarily meet the requirements of the standard
packages. If you have problems using a feature provided in a user
package, you will likely need to contact the contributor directly to
get help. Information on how to submit additions you make to LAMMPS
as a user-contributed package is given in <a class="reference internal" href="Section_modify.html#mod-15"><span>this section</span></a> of the documentation.</p>
<p>Some packages (both standard and user) require additional libraries.
See more details below.</p>
package, you may need to contact the contributor directly to get help.
Information on how to submit additions you make to LAMMPS as single
files or either a standard or user-contributed package are given in
<a class="reference internal" href="Section_modify.html#mod-15"><span>this section</span></a> of the documentation.</p>
<p>Some packages (both standard and user) require additional auxiliary
libraries when building LAMMPS. See more details below.</p>
<hr class="docutils" />
<p id="start-3-2"><strong>*Including/excluding packages:*</strong></p>
<p>To use or not use a package you must include or exclude it before
building LAMMPS. From the src directory, this is typically as simple
as:</p>
<p>To use (or not use) a package you must include it (or exclude it)
before building LAMMPS. From the src directory, this is typically as
simple as:</p>
<div class="highlight-python"><div class="highlight"><pre>make yes-colloid
make g++
</pre></div>
@ -772,10 +772,10 @@ make g++
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">You should NOT include/exclude packages and build
LAMMPS in a single make command by using multiple targets, e.g. make
LAMMPS in a single make command using multiple targets, e.g. make
yes-colloid g++. This is because the make procedure creates a list of
source files that will be out-of-date for the build if the package
configuration changes during the same command.</p>
configuration changes within the same command.</p>
</div>
<p>Some packages have individual files that depend on other packages
being included. LAMMPS checks for this and does the right thing.
@ -827,30 +827,30 @@ options.</p>
<hr class="docutils" />
<p id="start-3-3"><strong>*Packages that require extra libraries:*</strong></p>
<p>A few of the standard and user packages require additional auxiliary
libraries. Most of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built if you wish to include
libraries. Many of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built, if you wish to include
that package. If you get a LAMMPS build error about a missing
library, this is likely the reason. See the
<a class="reference internal" href="Section_packages.html"><em>Section_packages</em></a> doc page for a list of
packages that have these kinds of auxiliary libraries.</p>
<p>The lib directory in the distribution has sub-directories with package
names that correspond to the needed auxiliary libs, e.g. lib/reax.
names that correspond to the needed auxiliary libs, e.g. lib/gpu.
Each sub-directory has a README file that gives more details. Code
for most of the auxiliary libraries is included in that directory.
Examples are the USER-ATC and MEAM packages.</p>
<p>A few of the lib sub-directories do not include code, but do include
instructions and sometimes scripts that automate the process of
instructions (and sometimes scripts) that automate the process of
downloading the auxiliary library and installing it so LAMMPS can link
to it. Examples are the KIM and VORONOI and USER-MOLFILE and USER-SMD
to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD
packages.</p>
<p>The lib/python directory (for the PYTHON package) contains only a
choice of Makefile.lammps.* files. This is because no auxiliary code
or libraries are needed, only the Python library and other system libs
that already available on your system. However, the Makefile.lammps
file is needed to tell the LAMMPS build which libs to use and where to
find them.</p>
that should already available on your system. However, the
Makefile.lammps file is needed to tell LAMMPS which libs to use and
where to find them.</p>
<p>For libraries with provided code, the sub-directory README file
(e.g. lib/reax/README) has instructions on how to build that library.
(e.g. lib/atc/README) has instructions on how to build that library.
Typically this is done by typing something like:</p>
<div class="highlight-python"><div class="highlight"><pre>make -f Makefile.g++
</pre></div>
@ -873,10 +873,10 @@ fail.</p>
<p>As explained in the lib/package/README files, the settings in
Makefile.lammps are used to specify additional system libraries and
their locations so that LAMMPS can build with the auxiliary library.
For example, if the MEAM or REAX packages are used, the auxiliary
libraries consist of F90 code, built with a Fortran complier. To link
that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS
is built with, typically requires additional Fortran-to-C libraries be
For example, if the MEAM package is used, the auxiliary library
consists of F90 code, built with a Fortran complier. To link that
library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is
built with, typically requires additional Fortran-to-C libraries be
included in the link. Another example are the BLAS and LAPACK
libraries needed to use the USER-ATC or USER-AWPMD packages.</p>
<p>For libraries without provided code, the sub-directory README file has
@ -969,8 +969,8 @@ settings for CCFLAGS.</p>
</ul>
<hr class="docutils" />
</div>
<div class="section" id="building-lammps-via-the-make-py-script">
<span id="start-4"></span><h2>2.4. Building LAMMPS via the Make.py script<a class="headerlink" href="#building-lammps-via-the-make-py-script" title="Permalink to this headline"></a></h2>
<div class="section" id="building-lammps-via-the-make-py-tool">
<span id="start-4"></span><h2>2.4. Building LAMMPS via the Make.py tool<a class="headerlink" href="#building-lammps-via-the-make-py-tool" title="Permalink to this headline"></a></h2>
<p>The src directory includes a Make.py script, written in Python, which
can be used to automate various steps of the build process. It is
particularly useful for working with the accelerator packages, as well

76
doc/Section_start.txt
View File

@ -628,10 +628,6 @@ One way to do this is install and use cygwin to build LAMMPS with a
standard unix style make program, just as you would on a Linux box;
see src/MAKE/MACHINES/Makefile.cygwin.
The other way to do this is using Visual Studio and project files.
See the src/WINDOWS directory and its README.txt file for instructions
on both a basic build and a customized build with pacakges you select.
:line
2.3 Making LAMMPS with optional packages :h4,link(start_3)
@ -670,41 +666,43 @@ package. You can also type
lmp_machine -h :pre
to run your executable with the optional "-h command-line
switch"_#start_7 for "help", which will list the styles and commands
known to your executable.
switch"_#start_7 for "help", which will simply list the styles and
commands known to your executable, and immediately exit.
There are two kinds of packages in LAMMPS, standard and user packages.
More information about the contents of standard and user packages is
given in "Section_packages"_Section_packages.html of the manual. The
difference between standard and user packages is as follows:
Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.
Standard packages, such as molecule or kspace, are supported by the
LAMMPS developers and are written in a syntax and style consistent
with the rest of LAMMPS. This means we will answer questions about
them, debug and fix them if necessary, and keep them compatible with
future changes to LAMMPS.
User packages have been contributed by users, and always begin with
the user prefix. If they are a single command (single file), they are
typically in the user-misc package. Otherwise, they are a a set of
files grouped together which add a specific functionality to the code.
User packages, such as user-atc or user-omp, have been contributed by
users, and always begin with the user prefix. If they are a single
command (single file), they are typically in the user-misc package.
Otherwise, they are a a set of files grouped together which add a
specific functionality to the code.
User packages don't necessarily meet the requirements of the standard
packages. If you have problems using a feature provided in a user
package, you will likely need to contact the contributor directly to
get help. Information on how to submit additions you make to LAMMPS
as a user-contributed package is given in "this
section"_Section_modify.html#mod_15 of the documentation.
package, you may need to contact the contributor directly to get help.
Information on how to submit additions you make to LAMMPS as single
files or either a standard or user-contributed package are given in
"this section"_Section_modify.html#mod_15 of the documentation.
Some packages (both standard and user) require additional libraries.
See more details below.
Some packages (both standard and user) require additional auxiliary
libraries when building LAMMPS. See more details below.
:line
[{Including/excluding packages:}] :link(start_3_2)
To use or not use a package you must include or exclude it before
building LAMMPS. From the src directory, this is typically as simple
as:
To use (or not use) a package you must include it (or exclude it)
before building LAMMPS. From the src directory, this is typically as
simple as:
make yes-colloid
make g++ :pre
@ -715,10 +713,10 @@ make no-manybody
make g++ :pre
IMPORTANT NOTE: You should NOT include/exclude packages and build
LAMMPS in a single make command by using multiple targets, e.g. make
LAMMPS in a single make command using multiple targets, e.g. make
yes-colloid g++. This is because the make procedure creates a list of
source files that will be out-of-date for the build if the package
configuration changes during the same command.
configuration changes within the same command.
Some packages have individual files that depend on other packages
being included. LAMMPS checks for this and does the right thing.
@ -777,34 +775,34 @@ options.
[{Packages that require extra libraries:}] :link(start_3_3)
A few of the standard and user packages require additional auxiliary
libraries. Most of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built if you wish to include
libraries. Many of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built, if you wish to include
that package. If you get a LAMMPS build error about a missing
library, this is likely the reason. See the
"Section_packages"_Section_packages.html doc page for a list of
packages that have these kinds of auxiliary libraries.
The lib directory in the distribution has sub-directories with package
names that correspond to the needed auxiliary libs, e.g. lib/reax.
names that correspond to the needed auxiliary libs, e.g. lib/gpu.
Each sub-directory has a README file that gives more details. Code
for most of the auxiliary libraries is included in that directory.
Examples are the USER-ATC and MEAM packages.
A few of the lib sub-directories do not include code, but do include
instructions and sometimes scripts that automate the process of
instructions (and sometimes scripts) that automate the process of
downloading the auxiliary library and installing it so LAMMPS can link
to it. Examples are the KIM and VORONOI and USER-MOLFILE and USER-SMD
to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD
packages.
The lib/python directory (for the PYTHON package) contains only a
choice of Makefile.lammps.* files. This is because no auxiliary code
or libraries are needed, only the Python library and other system libs
that already available on your system. However, the Makefile.lammps
file is needed to tell the LAMMPS build which libs to use and where to
find them.
that should already available on your system. However, the
Makefile.lammps file is needed to tell LAMMPS which libs to use and
where to find them.
For libraries with provided code, the sub-directory README file
(e.g. lib/reax/README) has instructions on how to build that library.
(e.g. lib/atc/README) has instructions on how to build that library.
Typically this is done by typing something like:
make -f Makefile.g++ :pre
@ -830,10 +828,10 @@ fail.
As explained in the lib/package/README files, the settings in
Makefile.lammps are used to specify additional system libraries and
their locations so that LAMMPS can build with the auxiliary library.
For example, if the MEAM or REAX packages are used, the auxiliary
libraries consist of F90 code, built with a Fortran complier. To link
that library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS
is built with, typically requires additional Fortran-to-C libraries be
For example, if the MEAM package is used, the auxiliary library
consists of F90 code, built with a Fortran complier. To link that
library with LAMMPS (a C++ code) via whatever C++ compiler LAMMPS is
built with, typically requires additional Fortran-to-C libraries be
included in the link. Another example are the BLAS and LAPACK
libraries needed to use the USER-ATC or USER-AWPMD packages.
@ -936,7 +934,7 @@ CCFLAGS: add -restrict :ul
:line
2.4 Building LAMMPS via the Make.py script :h4,link(start_4)
2.4 Building LAMMPS via the Make.py tool :h4,link(start_4)
The src directory includes a Make.py script, written in Python, which
can be used to automate various steps of the build process. It is

350
doc/accelerate_intel.html
View File

@ -128,216 +128,182 @@
<div class="section" id="user-intel-package">
<h1>5.USER-INTEL package<a class="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
installed, this mode of operation is made easier to use, with the
&#8220;-suffix hybrid intel omp&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>
or the <a class="reference internal" href="suffix.html"><em>suffix hybrid intel omp</em></a> command will both set a
second-choice suffix to &#8220;omp&#8221; 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 the
binary will support offload to Xeon Phi coprocessors. Binaries supporting
offload can still be run in CPU-only (host-only) mode.</p>
<p>Here is a quick overview of how to use the USER-INTEL package
for CPU-only acceleration:</p>
<ul class="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>
<ul class="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 &#8220;-pk intel&#8221; and &#8220;-sf intel&#8221;
<a class="reference internal" href="Section_start.html#start-7"><span>command-line switches</span></a> respectively. Or
the effect of the &#8220;-pk&#8221; or &#8220;-sf&#8221; switches can be duplicated by adding
the <a class="reference internal" href="package.html"><em>package intel</em></a> or <a class="reference internal" href="suffix.html"><em>suffix intel</em></a>
commands respectively to your input script.</p>
Corporation. It provides two methods for accelerating simulations,
depending on the hardware you have. The first is acceleration on
Intel(R) CPUs by running in single, mixed, or double precision with
vectorization. The second is acceleration on Intel(R) Xeon Phi(TM)
coprocessors via offloading neighbor list and non-bonded force
calculations to the Phi. The same C++ code is used in both cases.
When offloading to a coprocessor from a CPU, the same routine is run
twice, once on the CPU and once with an offload flag.</p>
<p>Note that the USER-INTEL package supports use of the Phi in &#8220;offload&#8221;
mode, not &#8220;native&#8221; mode like the <a class="reference internal" href="accelerate_kokkos.html"><em>KOKKOS package</em></a>.</p>
<p>Also note that the USER-INTEL package can be used in tandem with the
<a class="reference internal" href="accelerate_omp.html"><em>USER-OMP package</em></a>. This is useful when
offloading pair style computations to the Phi, 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>As illustrated below, if LAMMPS is built with both the USER-INTEL and
USER-OMP packages, this dual mode of operation is made easier to use,
via the &#8220;-suffix hybrid intel omp&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a> or the <a class="reference internal" href="suffix.html"><em>suffix hybrid intel omp</em></a> command. Both set a second-choice suffix to &#8220;omp&#8221; so
that styles from the USER-INTEL package will be used if available,
with styles from the USER-OMP package as a second choice.</p>
<p>Here is a quick overview of how to use the USER-INTEL package for CPU
acceleration, assuming one or more 16-core nodes. More details
follow.</p>
<div class="highlight-python"><div class="highlight"><pre>use an Intel compiler
use these CCFLAGS settings in Makefile.machine: -fopenmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost, -fno-alias, -ansi-alias, -override-limits
use these LINKFLAGS settings in Makefile.machine: -fopenmp, -xHost
make yes-user-intel yes-user-omp # including user-omp is optional
make mpi # build with the USER-INTEL package, if settings (including compiler) added to Makefile.mpi
make intel_cpu # or Makefile.intel_cpu already has settings, uses Intel MPI wrapper
Make.py -v -p intel omp -intel cpu -a file mpich_icc # or one-line build via Make.py for MPICH
Make.py -v -p intel omp -intel cpu -a file ompi_icc # or for OpenMPI
Make.py -v -p intel omp -intel cpu -a file intel_cpu # or for Intel MPI wrapper
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>lmp_machine -sf intel -pk intel 0 omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, no USER-OMP
mpirun -np 32 lmp_machine -sf intel -in in.script # 2 nodess, 16 MPI tasks/node, no threads, no USER-OMP
lmp_machine -sf hybrid intel omp -pk intel 0 omp 16 -pk omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, with USER-OMP
mpirun -np 32 -ppn 4 lmp_machine -sf hybrid intel omp -pk omp 4 -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task, with USER-OMP
</pre></div>
</div>
<p>Here is a quick overview of how to use the USER-INTEL package for the
same CPUs as above (16 cores/node), with an additional Xeon Phi(TM)
coprocessor per node. More details follow.</p>
<div class="highlight-python"><div class="highlight"><pre>Same as above for building, with these additions/changes:
add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in Makefile.machine
add the flag -offload to LINKFLAGS in Makefile.machine
for Make.py change &quot;-intel cpu&quot; to &quot;-intel phi&quot;, and &quot;file intel_cpu&quot; to &quot;file intel_phi&quot;
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>mpirun -np 32 lmp_machine -sf intel -pk intel 1 -in in.script # 2 nodes, 16 MPI tasks/node, 240 total threads on coprocessor, no USER-OMP
mpirun -np 16 -ppn 8 lmp_machine -sf intel -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, no USER-OMP
mpirun -np 32 -ppn 8 lmp_machine -sf hybrid intel omp -pk intel 1 omp 2 -pk omp 2 -in in.script # 4 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, with USER-OMP
</pre></div>
</div>
<p><strong>Required hardware/software:</strong></p>
<p>Your compiler must support the OpenMP interface. Use of an Intel(R)
C++ compiler is recommended, but not required. However, g++ will not
recognize some of the settings listed above, so they cannot be used.
Optimizations for vectorization have only been tested with the
Intel(R) compiler. Use of other compilers may not result in
vectorization, or give poor performance.</p>
<p>The recommended version of the Intel(R) compiler is 14.0.1.106.
Versions 15.0.1.133 and later are also supported. If using Intel(R)
MPI, versions 15.0.2.044 and later are recommended.</p>
<p>To use the offload option, you must have one or more Intel(R) Xeon
Phi(TM) coprocessors and use an Intel(R) C++ compiler.</p>
<p>Optimizations for vectorization have only been tested with the
Intel(R) compiler. Use of other compilers may not result in
vectorization or give poor performance.</p>
<p>Use of an Intel C++ compiler is recommended, but not required (though
g++ will not recognize some of the settings, so they cannot be used).
The compiler must support the OpenMP interface.</p>
<p>The recommended version of the Intel(R) compiler is 14.0.1.106.
Versions 15.0.1.133 and later are also supported. If using Intel(R)
MPI, versions 15.0.2.044 and later are recommended.</p>
<p><strong>Building LAMMPS with the USER-INTEL package:</strong></p>
<p>You can choose to build with or without support for offload to a
Intel(R) Xeon Phi(TM) coprocessor. If you build with support for a
coprocessor, the same binary can be used on nodes with and without
coprocessors installed. However, if you do not have coprocessors
on your system, building without offload support will produce a
smaller binary.</p>
<p>You can do either in one line, using the src/Make.py script, described
in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual. Type
&#8220;Make.py -h&#8221; for help. If run from the src directory, these commands
will create src/lmp_intel_cpu and lmp_intel_phi using
src/MAKE/Makefile.mpi as the starting Makefile.machine:</p>
<div class="highlight-python"><div class="highlight"><pre>Make.py -p intel omp -intel cpu -o intel_cpu -cc icc -a file mpi
Make.py -p intel omp -intel phi -o intel_phi -cc icc -a file mpi
</pre></div>
</div>
<p>Note that this assumes that your MPI and its mpicxx wrapper
is using the Intel compiler. If it is not, you should
leave off the &#8220;-cc icc&#8221; switch.</p>
<p>Or you can follow these steps:</p>
<div class="highlight-python"><div class="highlight"><pre>cd lammps/src
make yes-user-intel
make yes-user-omp (if desired)
make machine
</pre></div>
</div>
<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 &#8220;-fopenmp&#8221; 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>The lines above illustrate how to include/build with the USER-INTEL
package, for either CPU or Phi support, in two steps, using the &#8220;make&#8221;
command. Or how to do it with one command via the src/Make.py script,
described in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual.
Type &#8220;Make.py -h&#8221; for help. Because the mechanism for specifing what
compiler to use (Intel in this case) is different for different MPI
wrappers, 3 versions of the Make.py command are shown.</p>
<p>Note that if you build with support for a Phi coprocessor, the same
binary can be used on nodes with or without coprocessors installed.
However, if you do not have coprocessors on your system, building
without offload support will produce a smaller binary.</p>
<p>If you also build with the USER-OMP package, you can use styles from
both packages, as described below.</p>
<p>Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include &#8220;-fopenmp&#8221;. Likewise, if you use an Intel compiler, the
CCFLAGS setting must include &#8220;-restrict&#8221;. For Phi support, the
&#8220;-DLMP_INTEL_OFFLOAD&#8221; (CCFLAGS) and &#8220;-offload&#8221; (LINKFLAGS) settings
are required. The other settings listed above are optional, but will
typically improve performance. The Make.py command will add all of
these automatically.</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 <a class="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>
the runs, adding the flag <em>-xHost</em> to CCFLAGS enables vectorization
with the Intel(R) compiler. Otherwise, you must provide the correct
compute node architecture to the -x option (e.g. -xAVX).</p>
<p>Example machines 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 has support for
offload to Phi coprocessors; the former does not.</p>
<p><strong>Run 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
optionally 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 &#8220;-sf intel&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>,
which will automatically append &#8220;intel&#8221; to styles that support it.
OpenMP threads per MPI task can be set via the &#8220;-pk intel Nphi omp Nt&#8221; or
&#8220;-pk omp Nt&#8221; <a class="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 &#8220;-pk omp&#8221; form
is only allowed if LAMMPS was also built with the USER-OMP package.</p>
<p>Use the &#8220;-pk intel Nphi&#8221; <a class="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 &#8220;-pk intel&#8221; <a class="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 <a class="reference internal" href="package.html"><em>package intel</em></a> command
for details.</p>
<div class="highlight-python"><div class="highlight"><pre>CPU-only without USER-OMP (but using Intel vectorization on CPU):
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)
lmp_machine -sf intel -pk intel 0 omp 16 -in in.script # 1 MPI task and 16 threads
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>CPU-only with USER-OMP (and Intel vectorization on CPU):
lmp_machine -sf hybrid intel omp -pk intel 0 omp 16 -in in.script # 1 MPI task on a 16-core node with 16 threads
mpirun -np 4 lmp_machine -sf hybrid intel omp -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>CPUs + Xeon Phi(TM) coprocessors with or without USER-OMP:
mpirun -np 32 -ppn 16 lmp_machine -sf intel -pk intel 1 -in in.script # 2 nodes with 16 MPI tasks on each, 240 total threads on coprocessor
mpirun -np 16 -ppn 8 lmp_machine -sf intel -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks on each node, 2 threads for each task, 240 total threads on coprocessor
mpirun -np 16 -ppn 8 lmp_machine -sf hybrid intel omp -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks on each node, 2 threads for each task, 240 total threads on coprocessor, USER-OMP package for some styles
</pre></div>
</div>
<p>Note that if the &#8220;-sf intel&#8221; switch is used, it also invokes a
default command: <a class="reference internal" href="package.html"><em>package intel 1</em></a>. If the &#8220;-sf hybrid intel omp&#8221;
switch is used, the default USER-OMP command <a class="reference internal" href="package.html"><em>package omp 0</em></a> is
also invoked. 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 &#8220;mixed&#8221;, 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 &#8220;-pk intel&#8221; or &#8220;-pk omp&#8221; 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 &#8220;-pk intel&#8221; 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
<a class="reference internal" href="package.html"><em>package omp</em></a> and <a class="reference internal" href="package.html"><em>package intel</em></a> commands.
See the <a class="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
<p>If you 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. If both packages
are used, it must be done for both packages, and the same thread count
value should be used for both. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.</p>
<p>When using the USER-INTEL package for the Phi, you also need to
specify the number of coprocessor/node and optionally 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>As in the lines above, use the &#8220;-sf intel&#8221; or &#8220;-sf hybrid intel omp&#8221;
<a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>, which will
automatically append &#8220;intel&#8221; to styles that support it. In the second
case, &#8220;omp&#8221; will be appended if an &#8220;intel&#8221; style does not exist.</p>
<p>Note that if either switch is used, it also invokes a default command:
<a class="reference internal" href="package.html"><em>package intel 1</em></a>. If the &#8220;-sf hybrid intel omp&#8221; switch
is used, the default USER-OMP command <a class="reference internal" href="package.html"><em>package omp 0</em></a> is
also invoked (if LAMMPS was built with USER-OMP). 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 (ignored if USER-INTEL is built for CPU-only),
and the precision mode to &#8220;mixed&#8221; (default value).</p>
<p>You can also use the &#8220;-pk intel Nphi&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a> to explicitly set Nphi = # of Xeon
Phi(TM) coprocessors/node, as well as additional options. Nphi should
be &gt;= 1 if LAMMPS was built with coprocessor support, otherswise Nphi
= 0 for a CPU-only build. All the available coprocessor threads on
each Phi will be divided among MPI tasks, unless the <em>tptask</em> option
of the &#8220;-pk intel&#8221; <a class="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 <a class="reference internal" href="package.html"><em>package intel</em></a> command for details, including the default values
used for all its options if not specified, and how to set the number
of OpenMP threads via the OMP_NUM_THREADS environment variable if
desired.</p>
<p>If LAMMPS was built with the USER-OMP package, you can also use the
&#8220;-pk omp Nt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a> to
explicitly set Nt = # of OpenMP threads per MPI task to use, as well
as additional options. Nt should be the same threads per MPI task as
set for the USER-INTEL package, e.g. via the &#8220;-pk intel Nphi omp Nt&#8221;
command. Again, see the <a class="reference internal" href="package.html"><em>package omp</em></a> command for
details, including the default values used for all its options if 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 <a class="reference internal" href="suffix.html"><em>suffix intel</em></a> command, or you can explicitly add an
&#8220;intel&#8221; suffix to individual styles in your input script, e.g.</p>
<p>Use the <a class="reference internal" href="suffix.html"><em>suffix intel</em></a> or <a class="reference internal" href="suffix.html"><em>suffix hybrid intel omp</em></a> commands, or you can explicitly add an &#8220;intel&#8221; or
&#8220;omp&#8221; suffix to individual styles in your input script, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre>pair_style lj/cut/intel 2.5
</pre></div>
</div>
<p>You must also use the <a class="reference internal" href="package.html"><em>package intel</em></a> command, unless the
&#8220;-sf intel&#8221; or &#8220;-pk intel&#8221; <a class="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>
coprocessor options. The <a class="reference internal" href="package.html"><em>package</em></a> 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 <a class="reference internal" href="package.html"><em>package omp</em></a> command to enable that package, unless
the &#8220;-sf hybrid intel omp&#8221; or &#8220;-pk omp&#8221; <a class="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>
OpenMP threads per MPI task to use (should be same as the setting for
the USER-INTEL package), 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 not built with coprocessor support (CPU only) 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
@ -347,6 +313,20 @@ single, mixed).</p>
<p>See the <a class="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>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">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 (CPU) 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 <a class="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>
</div>
<p><strong>Guidelines for best performance on an Intel(R) Xeon Phi(TM)
coprocessor:</strong></p>
<ul class="simple">

344
doc/accelerate_intel.txt
View File

@ -12,215 +12,177 @@
5.3.3 USER-INTEL package :h4
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.
Corporation. It provides two methods for accelerating simulations,
depending on the hardware you have. The first is acceleration on
Intel(R) CPUs by running in single, mixed, or double precision with
vectorization. The second is acceleration on Intel(R) Xeon Phi(TM)
coprocessors via offloading neighbor list and non-bonded force
calculations to the Phi. The same C++ code is used in both cases.
When offloading to a coprocessor from a CPU, the same routine is run
twice, once on the CPU and once with an offload flag.
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.
Note that the USER-INTEL package supports use of the Phi in "offload"
mode, not "native" mode like the "KOKKOS
package"_accelerate_kokkos.html.
If LAMMPS is built with both the USER-INTEL and USER-OMP packages
installed, this mode of operation is made easier to use, with the
"-suffix hybrid intel omp" "command-line switch"_Section_start.html#start_7
or the "suffix hybrid intel omp"_suffix.html 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.
Also note that the USER-INTEL package can be used in tandem with the
"USER-OMP package"_accelerate_omp.html. This is useful when
offloading pair style computations to the Phi, 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.
When using the USER-INTEL package, you must choose at build time whether the
binary will support offload to Xeon Phi coprocessors. Binaries supporting
offload can still be run in CPU-only (host-only) mode.
As illustrated below, if LAMMPS is built with both the USER-INTEL and
USER-OMP packages, this dual mode of operation is made easier to use,
via the "-suffix hybrid intel omp" "command-line
switch"_Section_start.html#start_7 or the "suffix hybrid intel
omp"_suffix.html command. Both set a second-choice suffix to "omp" so
that styles from the USER-INTEL package will be used if available,
with styles from the USER-OMP package as a second choice.
Here is a quick overview of how to use the USER-INTEL package
for CPU-only acceleration:
Here is a quick overview of how to use the USER-INTEL package for CPU
acceleration, assuming one or more 16-core nodes. More details
follow.
specify these CCFLAGS in your src/MAKE/Makefile.machine: -openmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost
specify -openmp with LINKFLAGS in your Makefile.machine
include the USER-INTEL package and (optionally) USER-OMP package and build LAMMPS
specify how many OpenMP threads per MPI task to use
use USER-INTEL and (optionally) USER-OMP styles in your input script :ul
use an Intel compiler
use these CCFLAGS settings in Makefile.machine: -fopenmp, -DLAMMPS_MEMALIGN=64, -restrict, -xHost, -fno-alias, -ansi-alias, -override-limits
use these LINKFLAGS settings in Makefile.machine: -fopenmp, -xHost
make yes-user-intel yes-user-omp # including user-omp is optional
make mpi # build with the USER-INTEL package, if settings (including compiler) added to Makefile.mpi
make intel_cpu # or Makefile.intel_cpu already has settings, uses Intel MPI wrapper
Make.py -v -p intel omp -intel cpu -a file mpich_icc # or one-line build via Make.py for MPICH
Make.py -v -p intel omp -intel cpu -a file ompi_icc # or for OpenMPI
Make.py -v -p intel omp -intel cpu -a file intel_cpu # or for Intel MPI wrapper :pre
Note that many of these settings can only be used with the Intel
compiler, as discussed below.
lmp_machine -sf intel -pk intel 0 omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, no USER-OMP
mpirun -np 32 lmp_machine -sf intel -in in.script # 2 nodess, 16 MPI tasks/node, no threads, no USER-OMP
lmp_machine -sf hybrid intel omp -pk intel 0 omp 16 -pk omp 16 -in in.script # 1 node, 1 MPI task/node, 16 threads/task, with USER-OMP
mpirun -np 32 -ppn 4 lmp_machine -sf hybrid intel omp -pk omp 4 -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task, with USER-OMP :pre
Using the USER-INTEL package to offload work to the Intel(R)
Xeon Phi(TM) coprocessor is the same except for these additional
steps:
Here is a quick overview of how to use the USER-INTEL package for the
same CPUs as above (16 cores/node), with an additional Xeon Phi(TM)
coprocessor per node. More details follow.
add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in your Makefile.machine
add the flag -offload to LINKFLAGS in your Makefile.machine :ul
Same as above for building, with these additions/changes:
add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in Makefile.machine
add the flag -offload to LINKFLAGS in Makefile.machine
for Make.py change "-intel cpu" to "-intel phi", and "file intel_cpu" to "file intel_phi" :pre
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"
"command-line switches"_Section_start.html#start_7 respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the "package intel"_package.html or "suffix intel"_suffix.html
commands respectively to your input script.
mpirun -np 32 lmp_machine -sf intel -pk intel 1 -in in.script # 2 nodes, 16 MPI tasks/node, 240 total threads on coprocessor, no USER-OMP
mpirun -np 16 -ppn 8 lmp_machine -sf intel -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, no USER-OMP
mpirun -np 32 -ppn 8 lmp_machine -sf hybrid intel omp -pk intel 1 omp 2 -pk omp 2 -in in.script # 4 nodes, 8 MPI tasks/node, 2 threads/task, 240 total threads on coprocessor, with USER-OMP :pre
[Required hardware/software:]
To use the offload option, you must have one or more Intel(R) Xeon
Phi(TM) coprocessors and use an Intel(R) C++ compiler.
Your compiler must support the OpenMP interface. Use of an Intel(R)
C++ compiler is recommended, but not required. However, g++ will not
recognize some of the settings listed above, so they cannot be used.
Optimizations for vectorization have only been tested with the
Intel(R) compiler. Use of other compilers may not result in
vectorization or give poor performance.
Use of an Intel C++ compiler is recommended, but not required (though
g++ will not recognize some of the settings, so they cannot be used).
The compiler must support the OpenMP interface.
vectorization, or give poor performance.
The recommended version of the Intel(R) compiler is 14.0.1.106.
Versions 15.0.1.133 and later are also supported. If using Intel(R)
Versions 15.0.1.133 and later are also supported. If using Intel(R)
MPI, versions 15.0.2.044 and later are recommended.
To use the offload option, you must have one or more Intel(R) Xeon
Phi(TM) coprocessors and use an Intel(R) C++ compiler.
[Building LAMMPS with the USER-INTEL package:]
You can choose to build with or without support for offload to a
Intel(R) Xeon Phi(TM) coprocessor. If you build with support for a
coprocessor, the same binary can be used on nodes with and without
coprocessors installed. However, if you do not have coprocessors
on your system, building without offload support will produce a
smaller binary.
The lines above illustrate how to include/build with the USER-INTEL
package, for either CPU or Phi support, in two steps, using the "make"
command. Or how to do it with one command via the src/Make.py script,
described in "Section 2.4"_Section_start.html#start_4 of the manual.
Type "Make.py -h" for help. Because the mechanism for specifing what
compiler to use (Intel in this case) is different for different MPI
wrappers, 3 versions of the Make.py command are shown.
You can do either in one line, using the src/Make.py script, described
in "Section 2.4"_Section_start.html#start_4 of the manual. Type
"Make.py -h" for help. If run from the src directory, these commands
will create src/lmp_intel_cpu and lmp_intel_phi using
src/MAKE/Makefile.mpi as the starting Makefile.machine:
Note that if you build with support for a Phi coprocessor, the same
binary can be used on nodes with or without coprocessors installed.
However, if you do not have coprocessors on your system, building
without offload support will produce a smaller binary.
Make.py -p intel omp -intel cpu -o intel_cpu -cc icc -a file mpi
Make.py -p intel omp -intel phi -o intel_phi -cc icc -a file mpi :pre
If you also build with the USER-OMP package, you can use styles from
both packages, as described below.
Note that this assumes that your MPI and its mpicxx wrapper
is using the Intel compiler. If it is not, you should
leave off the "-cc icc" switch.
Or you can follow these steps:
cd lammps/src
make yes-user-intel
make yes-user-omp (if desired)
make machine :pre
Note that if the USER-OMP package is also installed, you can use
styles from both packages, as described below.
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.
Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include "-fopenmp". Likewise, if you use an Intel compiler, the
CCFLAGS setting must include "-restrict". For Phi support, the
"-DLMP_INTEL_OFFLOAD" (CCFLAGS) and "-offload" (LINKFLAGS) settings
are required. The other settings listed above are optional, but will
typically improve performance. The Make.py command will add all of
these automatically.
If you are compiling on the same architecture that will be used for
the runs, adding the flag {-xHost} 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).
the runs, adding the flag {-xHost} to CCFLAGS enables vectorization
with the Intel(R) compiler. Otherwise, you must provide the correct
compute node architecture to the -x option (e.g. -xAVX).
In order to build with support for an Intel(R) Xeon Phi(TM)
coprocessor, the flag {-offload} should be added to the LINKFLAGS line
and the flag -DLMP_INTEL_OFFLOAD should be added to the CCFLAGS line.
Example machines 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 has support for
offload to Phi coprocessors; the former does not.
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.
[Notes on CPU and core affinity:]
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 {no_affinity} option to the "package intel"_package.html
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.
[Running with the USER-INTEL package from the command line:]
[Run with the USER-INTEL package from the command line:]
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.
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.
If you 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. If both packages
are used, it must be done for both packages, and the same thread count
value should be used for both. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.
If LAMMPS was built with coprocessor support for the USER-INTEL
package, you also need to specify the number of coprocessor/node and
optionally 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.
When using the USER-INTEL package for the Phi, you also need to
specify the number of coprocessor/node and optionally 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.
Use the "-sf intel" "command-line switch"_Section_start.html#start_7,
which will automatically append "intel" to styles that support it.
OpenMP threads per MPI task can be set via the "-pk intel Nphi omp Nt" or
"-pk omp Nt" "command-line switches"_Section_start.html#start_7, 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.
As in the lines above, use the "-sf intel" or "-sf hybrid intel omp"
"command-line switch"_Section_start.html#start_7, which will
automatically append "intel" to styles that support it. In the second
case, "omp" will be appended if an "intel" style does not exist.
Use the "-pk intel Nphi" "command-line
switch"_Section_start.html#start_7 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 {tptask} option of the "-pk intel" "command-line
switch"_Section_start.html#start_7 is used to limit the coprocessor
threads per MPI task. See the "package intel"_package.html command
for details.
Note that if either switch is used, it also invokes a default command:
"package intel 1"_package.html. If the "-sf hybrid intel omp" switch
is used, the default USER-OMP command "package omp 0"_package.html is
also invoked (if LAMMPS was built with USER-OMP). 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 (ignored if USER-INTEL is built for CPU-only),
and the precision mode to "mixed" (default value).
CPU-only without USER-OMP (but using Intel vectorization on CPU):
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)
lmp_machine -sf intel -pk intel 0 omp 16 -in in.script # 1 MPI task and 16 threads :pre
You can also use the "-pk intel Nphi" "command-line
switch"_Section_start.html#start_7 to explicitly set Nphi = # of Xeon
Phi(TM) coprocessors/node, as well as additional options. Nphi should
be >= 1 if LAMMPS was built with coprocessor support, otherswise Nphi
= 0 for a CPU-only build. All the available coprocessor threads on
each Phi will be divided among MPI tasks, unless the {tptask} option
of the "-pk intel" "command-line switch"_Section_start.html#start_7 is
used to limit the coprocessor threads per MPI task. See the "package
intel"_package.html command for details, including the default values
used for all its options if not specified, and how to set the number
of OpenMP threads via the OMP_NUM_THREADS environment variable if
desired.
CPU-only with USER-OMP (and Intel vectorization on CPU):
lmp_machine -sf hybrid intel omp -pk intel 0 omp 16 -in in.script # 1 MPI task on a 16-core node with 16 threads
mpirun -np 4 lmp_machine -sf hybrid intel omp -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node :pre
CPUs + Xeon Phi(TM) coprocessors with or without USER-OMP:
mpirun -np 32 -ppn 16 lmp_machine -sf intel -pk intel 1 -in in.script # 2 nodes with 16 MPI tasks on each, 240 total threads on coprocessor
mpirun -np 16 -ppn 8 lmp_machine -sf intel -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks on each node, 2 threads for each task, 240 total threads on coprocessor
mpirun -np 16 -ppn 8 lmp_machine -sf hybrid intel omp -pk intel 1 omp 2 -in in.script # 2 nodes, 8 MPI tasks on each node, 2 threads for each task, 240 total threads on coprocessor, USER-OMP package for some styles :pre
Note that if the "-sf intel" switch is used, it also invokes a
default command: "package intel 1"_package.html. If the "-sf hybrid intel omp"
switch is used, the default USER-OMP command "package omp 0"_package.html is
also invoked. 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.
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
"package omp"_package.html and "package intel"_package.html commands.
See the "package"_package.html command doc page for details, including
the default values used for all its options if these switches are not
If LAMMPS was built with the USER-OMP package, you can also use the
"-pk omp Nt" "command-line switch"_Section_start.html#start_7 to
explicitly set Nt = # of OpenMP threads per MPI task to use, as well
as additional options. Nt should be the same threads per MPI task as
set for the USER-INTEL package, e.g. via the "-pk intel Nphi omp Nt"
command. Again, see the "package omp"_package.html command for
details, including the default values used for all its options if not
specified, and how to set the number of OpenMP threads via the
OMP_NUM_THREADS environment variable if desired.
@ -230,8 +192,9 @@ 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.
Use the "suffix intel"_suffix.html command, or you can explicitly add an
"intel" suffix to individual styles in your input script, e.g.
Use the "suffix intel"_suffix.html or "suffix hybrid intel
omp"_suffix.html commands, or you can explicitly add an "intel" or
"omp" suffix to individual styles in your input script, e.g.
pair_style lj/cut/intel 2.5 :pre
@ -239,24 +202,26 @@ You must also use the "package intel"_package.html command, unless the
"-sf intel" or "-pk intel" "command-line
switches"_Section_start.html#start_7 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.
coprocessor options. The "package"_package.html doc page explains how
to set the number of OpenMP threads via an environment variable if
desired.
If LAMMPS was also built with the USER-OMP package, you must also use
the "package omp"_package.html command to enable that package, unless
the "-sf hybrid intel omp" or "-pk omp" "command-line
switches"_Section_start.html#start_7 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.
OpenMP threads per MPI task to use (should be same as the setting for
the USER-INTEL package), as well as other options. Its doc page
explains how to set the number of OpenMP threads via an environment
variable if desired.
[Speed-ups to expect:]
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.
If LAMMPS was not built with coprocessor support (CPU only) 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.
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
@ -269,6 +234,19 @@ See the "Benchmark page"_http://lammps.sandia.gov/bench.html of the
LAMMPS web site for performance of the USER-INTEL package on different
hardware.
IMPORTANT NOTE: 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 (CPU) 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 {no_affinity} option to the "package
intel"_package.html 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.
[Guidelines for best performance on an Intel(R) Xeon Phi(TM)
coprocessor:]

164
doc/accelerate_kokkos.html
View File

@ -127,23 +127,22 @@
<p><a class="reference internal" href="Section_accelerate.html"><em>Return to Section accelerate overview</em></a></p>
<div class="section" id="kokkos-package">
<h1>5.KOKKOS package<a class="headerlink" href="#kokkos-package" title="Permalink to this headline"></a></h1>
<p>The KOKKOS package was developed primaritly by Christian Trott
(Sandia) with contributions of various styles by others, including
Sikandar Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia).
The underlying Kokkos library was written
primarily by Carter Edwards, Christian Trott, and Dan Sunderland (all
Sandia).</p>
<p>The KOKKOS package was developed primarily by Christian Trott (Sandia)
with contributions of various styles by others, including Sikandar
Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia). The
underlying Kokkos library was written primarily by Carter Edwards,
Christian Trott, and Dan Sunderland (all Sandia).</p>
<p>The KOKKOS package contains versions of pair, fix, and atom styles
that use data structures and macros provided by the Kokkos library,
which is included with LAMMPS in lib/kokkos.</p>
<p>The Kokkos library is part of
<a class="reference external" href="http://trilinos.sandia.gov/packages/kokkos">Trilinos</a> and can also
be downloaded from <a class="reference external" href="https://github.com/kokkos/kokkos">Github</a>. Kokkos is a
<a class="reference external" href="http://trilinos.sandia.gov/packages/kokkos">Trilinos</a> and can also be
downloaded from <a class="reference external" href="https://github.com/kokkos/kokkos">Github</a>. Kokkos is a
templated C++ library that provides two key abstractions for an
application like LAMMPS. First, it allows a single implementation of
an application kernel (e.g. a pair style) to run efficiently on
different kinds of hardware, such as a GPU, Intel Phi, or many-core
chip.</p>
CPU.</p>
<p>The Kokkos library also provides data abstractions to adjust (at
compile time) the memory layout of basic data structures like 2d and
3d arrays and allow the transparent utilization of special hardware
@ -153,53 +152,80 @@ chosen to optimize performance on different platforms. Again this
functionality is hidden from the developer, and does not affect how
the kernel is coded.</p>
<p>These abstractions are set at build time, when LAMMPS is compiled with
the KOKKOS package installed. This is done by selecting a &#8220;host&#8221; and
&#8220;device&#8221; to build for, compatible with the compute nodes in your
machine (one on a desktop machine or 1000s on a supercomputer).</p>
<p>All Kokkos operations occur within the context of an individual MPI
task running on a single node of the machine. The total number of MPI
tasks used by LAMMPS (one or multiple per compute node) is set in the
usual manner via the mpirun or mpiexec commands, and is independent of
Kokkos.</p>
<p>Kokkos provides support for two different modes of execution per MPI
task. This means that computational tasks (pairwise interactions,
neighbor list builds, time integration, etc) can be parallelized for
one or the other of the two modes. The first mode is called the
&#8220;host&#8221; and is one or more threads running on one or more physical CPUs
(within the node). Currently, both multi-core CPUs and an Intel Phi
processor (running in native mode, not offload mode like the
USER-INTEL package) are supported. The second mode is called the
&#8220;device&#8221; and is an accelerator chip of some kind. Currently only an
NVIDIA GPU is supported via Cuda. If your compute node does not have
a GPU, then there is only one mode of execution, i.e. the host and
device are the same.</p>
<p>When using the KOKKOS package, you must choose at build time whether
you are building for OpenMP, GPU, or for using the Xeon Phi in native
mode.</p>
<p>Here is a quick overview of how to use the KOKKOS package:</p>
the KOKKOS package installed. All Kokkos operations occur within the
context of an individual MPI task running on a single node of the
machine. The total number of MPI tasks used by LAMMPS (one or
multiple per compute node) is set in the usual manner via the mpirun
or mpiexec commands, and is independent of Kokkos.</p>
<p>Kokkos currently provides support for 3 modes of execution (per MPI
task). These are OpenMP (for many-core CPUs), Cuda (for NVIDIA GPUs),
and OpenMP (for Intel Phi). Note that the KOKKOS package supports
running on the Phi in native mode, not offload mode like the
USER-INTEL package supports. You choose the mode at build time to
produce an executable compatible with specific hardware.</p>
<p>Here is a quick overview of how to use the KOKKOS package
for CPU acceleration, assuming one or more 16-core nodes.
More details follow.</p>
<p>use a C++11 compatible compiler
make yes-kokkos
make mpi KOKKOS_DEVICES=OpenMP # build with the KOKKOS package
make kokkos_omp # or Makefile.kokkos_omp already has variable set
Make.py -v -p kokkos -kokkos omp -o mpi -a file mpi # or one-line build via Make.py</p>
<div class="highlight-python"><div class="highlight"><pre>mpirun -np 16 lmp_mpi -k on -sf kk -in in.lj # 1 node, 16 MPI tasks/node, no threads
mpirun -np 2 -ppn 1 lmp_mpi -k on t 16 -sf kk -in in.lj # 2 nodes, 1 MPI task/node, 16 threads/task
mpirun -np 2 lmp_mpi -k on t 8 -sf kk -in in.lj # 1 node, 2 MPI tasks/node, 8 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -k on t 4 -sf kk -in in.lj # 8 nodes, 4 MPI tasks/node, 4 threads/task
</pre></div>
</div>
<ul class="simple">
<li>specify variables and settings in your Makefile.machine that enable OpenMP, GPU, or Phi support</li>
<li>include the KOKKOS package and build LAMMPS</li>
<li>enable the KOKKOS package and its hardware options via the &#8220;-k on&#8221; command-line switch use KOKKOS styles in your input script</li>
</ul>
<p>The latter two steps can be done using the &#8220;-k on&#8221;, &#8220;-pk kokkos&#8221; and
&#8220;-sf kk&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switches</span></a>
respectively. Or the effect of the &#8220;-pk&#8221; or &#8220;-sf&#8221; switches can be
duplicated by adding the <a class="reference internal" href="package.html"><em>package kokkos</em></a> or <a class="reference internal" href="suffix.html"><em>suffix kk</em></a> commands respectively to your input script.</p>
<p>Here is a quick overview of how to use the KOKKOS package for GPUs,
assuming one or more nodes, each with 16 cores and a GPU. More
details follow.</p>
<p>discuss use of NVCC, which Makefiles to examine</p>
<p>use a C++11 compatible compiler
KOKKOS_DEVICES = Cuda, OpenMP
KOKKOS_ARCH = Kepler35
make yes-kokkos
make machine
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda</p>
<div class="highlight-python"><div class="highlight"><pre>mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj # one MPI task, 6 threads on CPU
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj # ditto on 4 nodes
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # two MPI tasks, 8 threads per CPU
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # ditto on 16 nodes
</pre></div>
</div>
<p>Here is a quick overview of how to use the KOKKOS package
for the Intel Phi:</p>
<div class="highlight-python"><div class="highlight"><pre>use a C++11 compatible compiler
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNC
make yes-kokkos
make machine
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi
</pre></div>
</div>
<p>host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj # 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj # 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj # 12 MPI tasks on 1 Phi, 12*20 = 240
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj # ditto on 8 Phis</p>
<p><strong>Required hardware/software:</strong></p>
<p>The KOKKOS package can be used to build and run LAMMPS on the
following kinds of hardware:</p>
<ul class="simple">
<li>CPU-only: one MPI task per CPU core (MPI-only, but using KOKKOS styles)</li>
<li>CPU-only: one or a few MPI tasks per node with additional threading via OpenMP</li>
<li>Phi: on one or more Intel Phi coprocessors (per node)</li>
<li>GPU: on the GPUs of a node with additional OpenMP threading on the CPUs</li>
</ul>
<p>Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. If using gcc, version 4.8.1 or later is required.</p>
<p>Note that Intel Xeon Phi coprocessors are supported in &#8220;native&#8221; mode,
not &#8220;offload&#8221; mode like the USER-INTEL package supports.</p>
<p>Only NVIDIA GPUs are currently supported.</p>
<p>To build with Kokkos support for CPUs, your compiler must support the
OpenMP interface. You should have one or more multi-core CPUs so that
multiple threads can be launched by each MPI task running on a CPU.</p>
<p>To build with Kokkos support for NVIDIA GPUs, NVIDIA Cuda software
version 6.5 or later must be installed on your system. See the
discussion for the <a class="reference internal" href="accelerate_cuda.html"><em>USER-CUDA</em></a> and
<a class="reference internal" href="accelerate_gpu.html"><em>GPU</em></a> packages for details of how to check and do
this.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">For good performance of the KOKKOS package on GPUs,
@ -207,12 +233,12 @@ you must have Kepler generation GPUs (or later). The Kokkos library
exploits texture cache options not supported by Telsa generation GPUs
(or older).</p>
</div>
<p>To build the KOKKOS package for GPUs, NVIDIA Cuda software version 6.5 or later must be
installed on your system. See the discussion above for the USER-CUDA
and GPU packages for details of how to check and do this.</p>
<p>To build with Kokkos support for Intel Xeon Phi coprocessors, your
sysmte must be configured to use them in &#8220;native&#8221; mode, not &#8220;offload&#8221;
mode like the USER-INTEL package supports.</p>
<p><strong>Building LAMMPS with the KOKKOS package:</strong></p>
<p>You must choose at build time whether to build for OpenMP, Cuda, or
Phi.</p>
<p>You must choose at build time whether to build for CPUs (OpenMP),
GPUs, or Phi.</p>
<p>You can do any of these in one line, using the src/Make.py script,
described in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual.
Type &#8220;Make.py -h&#8221; for help. If run from the src directory, these
@ -220,11 +246,10 @@ commands will create src/lmp_kokkos_omp, lmp_kokkos_cuda, and
lmp_kokkos_phi. Note that the OMP and PHI options use
src/MAKE/Makefile.mpi as the starting Makefile.machine. The CUDA
option uses src/MAKE/OPTIONS/Makefile.kokkos_cuda.</p>
<div class="highlight-python"><div class="highlight"><pre>Make.py -p kokkos -kokkos omp -o kokkos_omp -a file mpi
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi
</pre></div>
</div>
<p>The latter two steps can be done using the &#8220;-k on&#8221;, &#8220;-pk kokkos&#8221; and
&#8220;-sf kk&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switches</span></a>
respectively. Or the effect of the &#8220;-pk&#8221; or &#8220;-sf&#8221; switches can be
duplicated by adding the <a class="reference internal" href="package.html"><em>package kokkos</em></a> or <a class="reference internal" href="suffix.html"><em>suffix kk</em></a> commands respectively to your input script.</p>
<p>Or you can follow these steps:</p>
<p>CPU-only (run all-MPI or with OpenMP threading):</p>
<div class="highlight-python"><div class="highlight"><pre>cd lammps/src
@ -384,29 +409,6 @@ which will automatically append &#8220;kk&#8221; to styles that support it. Use
the &#8220;-pk kokkos&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a> if
you wish to change any of the default <a class="reference internal" href="package.html"><em>package kokkos</em></a>
optionns set by the &#8220;-k on&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>.</p>
<div class="highlight-python"><div class="highlight"><pre>host=OMP, dual hex-core nodes (12 threads/node):
mpirun -np 12 lmp_g++ -in in.lj # MPI-only mode with no Kokkos
mpirun -np 12 lmp_g++ -k on -sf kk -in in.lj # MPI-only mode with Kokkos
mpirun -np 1 lmp_g++ -k on t 12 -sf kk -in in.lj # one MPI task, 12 threads
mpirun -np 2 lmp_g++ -k on t 6 -sf kk -in in.lj # two MPI tasks, 6 threads/task
mpirun -np 32 -ppn 2 lmp_g++ -k on t 6 -sf kk -in in.lj # ditto on 16 nodes
</pre></div>
</div>
<p>host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj # 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj # 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj # 12 MPI tasks on 1 Phi, 12*20 = 240
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj # ditto on 8 Phis</p>
<div class="highlight-python"><div class="highlight"><pre>host=OMP, device=CUDA, node = dual hex-core CPUs and a single GPU:
mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj # one MPI task, 6 threads on CPU
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj # ditto on 4 nodes
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>host=OMP, device=CUDA, node = dual 8-core CPUs and 2 GPUs:
mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # two MPI tasks, 8 threads per CPU
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # ditto on 16 nodes
</pre></div>
</div>
<p>Note that the default for the <a class="reference internal" href="package.html"><em>package kokkos</em></a> command is
to use &#8220;full&#8221; neighbor lists and set the Newton flag to &#8220;off&#8221; for both
pairwise and bonded interactions. This typically gives fastest

164
doc/accelerate_kokkos.txt
View File

@ -11,25 +11,24 @@
5.3.4 KOKKOS package :h4
The KOKKOS package was developed primaritly by Christian Trott
(Sandia) with contributions of various styles by others, including
Sikandar Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia).
The underlying Kokkos library was written
primarily by Carter Edwards, Christian Trott, and Dan Sunderland (all
Sandia).
The KOKKOS package was developed primarily by Christian Trott (Sandia)
with contributions of various styles by others, including Sikandar
Mashayak (UIUC), Stan Moore (Sandia), and Ray Shan (Sandia). The
underlying Kokkos library was written primarily by Carter Edwards,
Christian Trott, and Dan Sunderland (all Sandia).
The KOKKOS package contains versions of pair, fix, and atom styles
that use data structures and macros provided by the Kokkos library,
which is included with LAMMPS in lib/kokkos.
The Kokkos library is part of
"Trilinos"_http://trilinos.sandia.gov/packages/kokkos and can also
be downloaded from "Github"_https://github.com/kokkos/kokkos. Kokkos is a
"Trilinos"_http://trilinos.sandia.gov/packages/kokkos and can also be
downloaded from "Github"_https://github.com/kokkos/kokkos. Kokkos is a
templated C++ library that provides two key abstractions for an
application like LAMMPS. First, it allows a single implementation of
an application kernel (e.g. a pair style) to run efficiently on
different kinds of hardware, such as a GPU, Intel Phi, or many-core
chip.
CPU.
The Kokkos library also provides data abstractions to adjust (at
compile time) the memory layout of basic data structures like 2d and
@ -41,76 +40,105 @@ functionality is hidden from the developer, and does not affect how
the kernel is coded.
These abstractions are set at build time, when LAMMPS is compiled with
the KOKKOS package installed. This is done by selecting a "host" and
"device" to build for, compatible with the compute nodes in your
machine (one on a desktop machine or 1000s on a supercomputer).
the KOKKOS package installed. All Kokkos operations occur within the
context of an individual MPI task running on a single node of the
machine. The total number of MPI tasks used by LAMMPS (one or
multiple per compute node) is set in the usual manner via the mpirun
or mpiexec commands, and is independent of Kokkos.
All Kokkos operations occur within the context of an individual MPI
task running on a single node of the machine. The total number of MPI
tasks used by LAMMPS (one or multiple per compute node) is set in the
usual manner via the mpirun or mpiexec commands, and is independent of
Kokkos.
Kokkos currently provides support for 3 modes of execution (per MPI
task). These are OpenMP (for many-core CPUs), Cuda (for NVIDIA GPUs),
and OpenMP (for Intel Phi). Note that the KOKKOS package supports
running on the Phi in native mode, not offload mode like the
USER-INTEL package supports. You choose the mode at build time to
produce an executable compatible with specific hardware.
Here is a quick overview of how to use the KOKKOS package
for CPU acceleration, assuming one or more 16-core nodes.
More details follow.
use a C++11 compatible compiler
make yes-kokkos
make mpi KOKKOS_DEVICES=OpenMP # build with the KOKKOS package
make kokkos_omp # or Makefile.kokkos_omp already has variable set
Make.py -v -p kokkos -kokkos omp -o mpi -a file mpi # or one-line build via Make.py
mpirun -np 16 lmp_mpi -k on -sf kk -in in.lj # 1 node, 16 MPI tasks/node, no threads
mpirun -np 2 -ppn 1 lmp_mpi -k on t 16 -sf kk -in in.lj # 2 nodes, 1 MPI task/node, 16 threads/task
mpirun -np 2 lmp_mpi -k on t 8 -sf kk -in in.lj # 1 node, 2 MPI tasks/node, 8 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -k on t 4 -sf kk -in in.lj # 8 nodes, 4 MPI tasks/node, 4 threads/task :pre
Kokkos provides support for two different modes of execution per MPI
task. This means that computational tasks (pairwise interactions,
neighbor list builds, time integration, etc) can be parallelized for
one or the other of the two modes. The first mode is called the
"host" and is one or more threads running on one or more physical CPUs
(within the node). Currently, both multi-core CPUs and an Intel Phi
processor (running in native mode, not offload mode like the
USER-INTEL package) are supported. The second mode is called the
"device" and is an accelerator chip of some kind. Currently only an
NVIDIA GPU is supported via Cuda. If your compute node does not have
a GPU, then there is only one mode of execution, i.e. the host and
device are the same.
When using the KOKKOS package, you must choose at build time whether
you are building for OpenMP, GPU, or for using the Xeon Phi in native
mode.
Here is a quick overview of how to use the KOKKOS package:
specify variables and settings in your Makefile.machine that enable OpenMP, GPU, or Phi support
include the KOKKOS package and build LAMMPS
enable the KOKKOS package and its hardware options via the "-k on" command-line switch use KOKKOS styles in your input script :ul
The latter two steps can be done using the "-k on", "-pk kokkos" and
"-sf kk" "command-line switches"_Section_start.html#start_7
respectively. Or the effect of the "-pk" or "-sf" switches can be
duplicated by adding the "package kokkos"_package.html or "suffix
kk"_suffix.html commands respectively to your input script.
Here is a quick overview of how to use the KOKKOS package for GPUs,
assuming one or more nodes, each with 16 cores and a GPU. More
details follow.
discuss use of NVCC, which Makefiles to examine
use a C++11 compatible compiler
KOKKOS_DEVICES = Cuda, OpenMP
KOKKOS_ARCH = Kepler35
make yes-kokkos
make machine
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda
mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj # one MPI task, 6 threads on CPU
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj # ditto on 4 nodes :pre
mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # two MPI tasks, 8 threads per CPU
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # ditto on 16 nodes :pre
Here is a quick overview of how to use the KOKKOS package
for the Intel Phi:
use a C++11 compatible compiler
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNC
make yes-kokkos
make machine
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi :pre
host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj # 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj # 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj # 12 MPI tasks on 1 Phi, 12*20 = 240
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj # ditto on 8 Phis
[Required hardware/software:]
The KOKKOS package can be used to build and run LAMMPS on the
following kinds of hardware:
CPU-only: one MPI task per CPU core (MPI-only, but using KOKKOS styles)
CPU-only: one or a few MPI tasks per node with additional threading via OpenMP
Phi: on one or more Intel Phi coprocessors (per node)
GPU: on the GPUs of a node with additional OpenMP threading on the CPUs :ul
Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. If using gcc, version 4.8.1 or later is required.
Note that Intel Xeon Phi coprocessors are supported in "native" mode,
not "offload" mode like the USER-INTEL package supports.
To build with Kokkos support for CPUs, your compiler must support the
OpenMP interface. You should have one or more multi-core CPUs so that
multiple threads can be launched by each MPI task running on a CPU.
Only NVIDIA GPUs are currently supported.
To build with Kokkos support for NVIDIA GPUs, NVIDIA Cuda software
version 6.5 or later must be installed on your system. See the
discussion for the "USER-CUDA"_accelerate_cuda.html and
"GPU"_accelerate_gpu.html packages for details of how to check and do
this.
IMPORTANT NOTE: For good performance of the KOKKOS package on GPUs,
you must have Kepler generation GPUs (or later). The Kokkos library
exploits texture cache options not supported by Telsa generation GPUs
(or older).
To build the KOKKOS package for GPUs, NVIDIA Cuda software version 6.5 or later must be
installed on your system. See the discussion above for the USER-CUDA
and GPU packages for details of how to check and do this.
To build with Kokkos support for Intel Xeon Phi coprocessors, your
sysmte must be configured to use them in "native" mode, not "offload"
mode like the USER-INTEL package supports.
[Building LAMMPS with the KOKKOS package:]
You must choose at build time whether to build for OpenMP, Cuda, or
Phi.
You must choose at build time whether to build for CPUs (OpenMP),
GPUs, or Phi.
You can do any of these in one line, using the src/Make.py script,
described in "Section 2.4"_Section_start.html#start_4 of the manual.
@ -120,9 +148,12 @@ lmp_kokkos_phi. Note that the OMP and PHI options use
src/MAKE/Makefile.mpi as the starting Makefile.machine. The CUDA
option uses src/MAKE/OPTIONS/Makefile.kokkos_cuda.
Make.py -p kokkos -kokkos omp -o kokkos_omp -a file mpi
Make.py -p kokkos -kokkos cuda arch=31 -o kokkos_cuda -a file kokkos_cuda
Make.py -p kokkos -kokkos phi -o kokkos_phi -a file mpi :pre
The latter two steps can be done using the "-k on", "-pk kokkos" and
"-sf kk" "command-line switches"_Section_start.html#start_7
respectively. Or the effect of the "-pk" or "-sf" switches can be
duplicated by adding the "package kokkos"_package.html or "suffix
kk"_suffix.html commands respectively to your input script.
Or you can follow these steps:
@ -301,26 +332,7 @@ you wish to change any of the default "package kokkos"_package.html
optionns set by the "-k on" "command-line
switch"_Section_start.html#start_7.
host=OMP, dual hex-core nodes (12 threads/node):
mpirun -np 12 lmp_g++ -in in.lj # MPI-only mode with no Kokkos
mpirun -np 12 lmp_g++ -k on -sf kk -in in.lj # MPI-only mode with Kokkos
mpirun -np 1 lmp_g++ -k on t 12 -sf kk -in in.lj # one MPI task, 12 threads
mpirun -np 2 lmp_g++ -k on t 6 -sf kk -in in.lj # two MPI tasks, 6 threads/task
mpirun -np 32 -ppn 2 lmp_g++ -k on t 6 -sf kk -in in.lj # ditto on 16 nodes :pre
host=MIC, Intel Phi with 61 cores (240 threads/phi via 4x hardware threading):
mpirun -np 1 lmp_g++ -k on t 240 -sf kk -in in.lj # 1 MPI task on 1 Phi, 1*240 = 240
mpirun -np 30 lmp_g++ -k on t 8 -sf kk -in in.lj # 30 MPI tasks on 1 Phi, 30*8 = 240
mpirun -np 12 lmp_g++ -k on t 20 -sf kk -in in.lj # 12 MPI tasks on 1 Phi, 12*20 = 240
mpirun -np 96 -ppn 12 lmp_g++ -k on t 20 -sf kk -in in.lj # ditto on 8 Phis
host=OMP, device=CUDA, node = dual hex-core CPUs and a single GPU:
mpirun -np 1 lmp_cuda -k on t 6 -sf kk -in in.lj # one MPI task, 6 threads on CPU
mpirun -np 4 -ppn 1 lmp_cuda -k on t 6 -sf kk -in in.lj # ditto on 4 nodes :pre
host=OMP, device=CUDA, node = dual 8-core CPUs and 2 GPUs:
mpirun -np 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # two MPI tasks, 8 threads per CPU
mpirun -np 32 -ppn 2 lmp_cuda -k on t 8 g 2 -sf kk -in in.lj # ditto on 16 nodes :pre
Note that the default for the "package kokkos"_package.html command is
to use "full" neighbor lists and set the Newton flag to "off" for both

141
doc/accelerate_omp.html
View File

@ -130,72 +130,55 @@
<p>The USER-OMP package was developed by Axel Kohlmeyer at Temple
University. It provides multi-threaded versions of most pair styles,
nearly all bonded styles (bond, angle, dihedral, improper), several
Kspace styles, and a few fix styles. The package currently
uses the OpenMP interface for multi-threading.</p>
<p>Here is a quick overview of how to use the USER-OMP package:</p>
<ul class="simple">
<li>use the -fopenmp flag for compiling and linking in your Makefile.machine</li>
<li>include the USER-OMP package and build LAMMPS</li>
<li>use the mpirun command to set the number of MPI tasks/node</li>
<li>specify how many threads per MPI task to use</li>
<li>use USER-OMP styles in your input script</li>
</ul>
<p>The latter two steps can be done using the &#8220;-pk omp&#8221; and &#8220;-sf omp&#8221;
<a class="reference internal" href="Section_start.html#start-7"><span>command-line switches</span></a> respectively. Or
the effect of the &#8220;-pk&#8221; or &#8220;-sf&#8221; switches can be duplicated by adding
the <a class="reference internal" href="package.html"><em>package omp</em></a> or <a class="reference internal" href="suffix.html"><em>suffix omp</em></a> commands
respectively to your input script.</p>
Kspace styles, and a few fix styles. The package currently uses the
OpenMP interface for multi-threading.</p>
<p>Here is a quick overview of how to use the USER-OMP package, assuming
one or more 16-core nodes. More details follow.</p>
<div class="highlight-python"><div class="highlight"><pre>use -fopenmp with CCFLAGS and LINKFLAGS in Makefile.machine
make yes-user-omp
make mpi # build with USER-OMP package, if settings added to Makefile.mpi
make omp # or Makefile.omp already has settings
Make.py -v -p omp -o mpi -a file mpi # or one-line build via Make.py
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>lmp_mpi -sf omp -pk omp 16 &lt; in.script # 1 MPI task, 16 threads
mpirun -np 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 4 MPI tasks, 4 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task
</pre></div>
</div>
<p><strong>Required hardware/software:</strong></p>
<p>Your compiler must support the OpenMP interface. You should have one
or more multi-core CPUs so that multiple threads can be launched by an
MPI task running on a CPU.</p>
or more multi-core CPUs so that multiple threads can be launched by
each MPI task running on a CPU.</p>
<p><strong>Building LAMMPS with the USER-OMP package:</strong></p>
<p>To do this in one line, use the src/Make.py script, described in
<a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual. Type &#8220;Make.py
-h&#8221; for help. If run from the src directory, this command will create
src/lmp_omp using src/MAKE/Makefile.mpi as the starting
Makefile.machine:</p>
<div class="highlight-python"><div class="highlight"><pre>Make.py -p omp -o omp -a file mpi
</pre></div>
</div>
<p>Or you can follow these steps:</p>
<div class="highlight-python"><div class="highlight"><pre>cd lammps/src
make yes-user-omp
make machine
</pre></div>
</div>
<p>The CCFLAGS setting in Makefile.machine needs &#8220;-fopenmp&#8221; to add OpenMP
support. This works for both the GNU and Intel compilers. Without
this flag the USER-OMP styles will still be compiled and work, but
will not support multi-threading. For the Intel compilers the CCFLAGS
setting also needs to include &#8220;-restrict&#8221;.</p>
<p>The lines above illustrate how to include/build with the USER-OMP
package in two steps, using the &#8220;make&#8221; command. Or how to do it with
one command via the src/Make.py script, described in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual. Type &#8220;Make.py -h&#8221; for
help.</p>
<p>Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include &#8220;-fopenmp&#8221;. Likewise, if you use an Intel compiler, the
CCFLAGS setting must include &#8220;-restrict&#8221;. The Make.py command will
add these automatically.</p>
<p><strong>Run with the USER-OMP 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>You need to choose how many threads per MPI task will be used by the
USER-OMP package. Note that the product of MPI tasks * threads/task
should not exceed the physical number of cores (on a node), otherwise
performance will suffer.</p>
<p>Use the &#8220;-sf omp&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>,
which will automatically append &#8220;omp&#8221; to styles that support it. Use
the &#8220;-pk omp Nt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>, to
set Nt = # of OpenMP threads per MPI task to use.</p>
<div class="highlight-python"><div class="highlight"><pre>lmp_machine -sf omp -pk omp 16 -in in.script # 1 MPI task on a 16-core node
mpirun -np 4 lmp_machine -sf omp -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node
mpirun -np 32 -ppn 4 lmp_machine -sf omp -pk omp 4 -in in.script # ditto on 8 16-core nodes
</pre></div>
</div>
<p>Note that if the &#8220;-sf omp&#8221; switch is used, it also issues a default
<a class="reference internal" href="package.html"><em>package omp 0</em></a> command, which sets the number of threads
per MPI task via the OMP_NUM_THREADS environment variable.</p>
<p>Using the &#8220;-pk&#8221; switch explicitly allows for direct setting of the
number of threads and additional options. Its syntax is the same as
the &#8220;package omp&#8221; command. See the <a class="reference internal" href="package.html"><em>package</em></a> command doc
page for details, including the default values used for all its
options if it is not specified, and how to set the number of threads
via the OMP_NUM_THREADS environment variable if desired.</p>
<p>You need to choose how many OpenMP threads per MPI task will be used
by the USER-OMP package. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.</p>
<p>As in the lines above, use the &#8220;-sf omp&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>, which will automatically append
&#8220;omp&#8221; to styles that support it. The &#8220;-sf omp&#8221; switch also issues a
default <a class="reference internal" href="package.html"><em>package omp 0</em></a> command, which will set the
number of threads per MPI task via the OMP_NUM_THREADS environment
variable.</p>
<p>You can also use the &#8220;-pk omp Nt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>, to explicitly set Nt = # of OpenMP
threads per MPI task to use, as well as additional options. Its
syntax is the same as the <a class="reference internal" href="package.html"><em>package omp</em></a> command whose doc
page gives details, including the default values used if it is not
specified. It also gives more details on how to set the number of
threads via the OMP_NUM_THREADS environment variable.</p>
<p><strong>Or run with the USER-OMP package by editing an input script:</strong></p>
<p>The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.</p>
@ -205,25 +188,24 @@ and threads/MPI task is the same.</p>
</pre></div>
</div>
<p>You must also use the <a class="reference internal" href="package.html"><em>package omp</em></a> command to enable the
USER-OMP package, unless the &#8220;-sf omp&#8221; or &#8220;-pk omp&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switches</span></a> were used. It specifies how many
threads per MPI task to use, as well as other options. Its doc page
explains how to set the number of threads via an environment variable
if desired.</p>
USER-OMP package. When you do this you also specify how many threads
per MPI task to use. The command doc page explains other options and
how to set the number of threads via the OMP_NUM_THREADS environment
variable.</p>
<p><strong>Speed-ups to expect:</strong></p>
<p>Depending on which styles are accelerated, you should look for a
reduction in the &#8220;Pair time&#8221;, &#8220;Bond time&#8221;, &#8220;KSpace time&#8221;, and &#8220;Loop
time&#8221; values printed at the end of a run.</p>
<p>You may see a small performance advantage (5 to 20%) when running a
USER-OMP style (in serial or parallel) with a single thread per MPI
task, versus running standard LAMMPS with its standard
(un-accelerated) styles (in serial or all-MPI parallelization with 1
task/core). This is because many of the USER-OMP styles contain
similar optimizations to those used in the OPT package, as described
above.</p>
<p>With multiple threads/task, the optimal choice of MPI tasks/node and
OpenMP threads/task can vary a lot and should always be tested via
benchmark runs for a specific simulation running on a specific
machine, paying attention to guidelines discussed in the next
task, versus running standard LAMMPS with its standard un-accelerated
styles (in serial or all-MPI parallelization with 1 task/core). This
is because many of the USER-OMP styles contain similar optimizations
to those used in the OPT package, described in <a class="reference internal" href="accelerate_opt.html"><em>Section accelerate 5.3.6</em></a>.</p>
<p>With multiple threads/task, the optimal choice of number of MPI
tasks/node and OpenMP threads/task can vary a lot and should always be
tested via benchmark runs for a specific simulation running on a
specific machine, paying attention to guidelines discussed in the next
sub-section.</p>
<p>A description of the multi-threading strategy used in the USER-OMP
package and some performance examples are <a class="reference external" href="http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&amp;d=1">presented here</a></p>
@ -239,7 +221,7 @@ circumstances:</p>
<ul class="simple">
<li>Individual compute nodes have a significant number of CPU cores but
the CPU itself has limited memory bandwidth, e.g. for Intel Xeon 53xx
(Clovertown) and 54xx (Harpertown) quad core processors. Running one
(Clovertown) and 54xx (Harpertown) quad-core processors. Running one
MPI task per CPU core will result in significant performance
degradation, so that running with 4 or even only 2 MPI tasks per node
is faster. Running in hybrid MPI+OpenMP mode will reduce the
@ -274,15 +256,16 @@ of MPI tasks assigned to the KSpace calculation.</li>
<p>Additional performance tips are as follows:</p>
<ul class="simple">
<li>The best parallel efficiency from <em>omp</em> styles is typically achieved
when there is at least one MPI task per physical processor,
i.e. socket or die.</li>
when there is at least one MPI task per physical CPU chip, i.e. socket
or die.</li>
<li>It is usually most efficient to restrict threading to a single
socket, i.e. use one or more MPI task per socket.</li>
<li>Several current MPI implementation by default use a processor affinity
setting that restricts each MPI task to a single CPU core. Using
multi-threading in this mode will force the threads to share that core
and thus is likely to be counterproductive. Instead, binding MPI
tasks to a (multi-core) socket, should solve this issue.</li>
<li>IMPORTANT NOTE: By default, several current MPI implementations use a
processor affinity setting that restricts each MPI task to a single
CPU core. Using multi-threading in this mode will force all threads
to share the one core and thus is likely to be counterproductive.
Instead, binding MPI tasks to a (multi-core) socket, should solve this
issue.</li>
</ul>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline"></a></h2>

139
doc/accelerate_omp.txt
View File

@ -14,50 +14,40 @@
The USER-OMP package was developed by Axel Kohlmeyer at Temple
University. It provides multi-threaded versions of most pair styles,
nearly all bonded styles (bond, angle, dihedral, improper), several
Kspace styles, and a few fix styles. The package currently
uses the OpenMP interface for multi-threading.
Kspace styles, and a few fix styles. The package currently uses the
OpenMP interface for multi-threading.
Here is a quick overview of how to use the USER-OMP package:
Here is a quick overview of how to use the USER-OMP package, assuming
one or more 16-core nodes. More details follow.
use the -fopenmp flag for compiling and linking in your Makefile.machine
include the USER-OMP package and build LAMMPS
use the mpirun command to set the number of MPI tasks/node
specify how many threads per MPI task to use
use USER-OMP styles in your input script :ul
use -fopenmp with CCFLAGS and LINKFLAGS in Makefile.machine
make yes-user-omp
make mpi # build with USER-OMP package, if settings added to Makefile.mpi
make omp # or Makefile.omp already has settings
Make.py -v -p omp -o mpi -a file mpi # or one-line build via Make.py :pre
The latter two steps can be done using the "-pk omp" and "-sf omp"
"command-line switches"_Section_start.html#start_7 respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the "package omp"_package.html or "suffix omp"_suffix.html commands
respectively to your input script.
lmp_mpi -sf omp -pk omp 16 < in.script # 1 MPI task, 16 threads
mpirun -np 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 4 MPI tasks, 4 threads/task
mpirun -np 32 -ppn 4 lmp_mpi -sf omp -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task :pre
[Required hardware/software:]
Your compiler must support the OpenMP interface. You should have one
or more multi-core CPUs so that multiple threads can be launched by an
MPI task running on a CPU.
or more multi-core CPUs so that multiple threads can be launched by
each MPI task running on a CPU.
[Building LAMMPS with the USER-OMP package:]
To do this in one line, use the src/Make.py script, described in
"Section 2.4"_Section_start.html#start_4 of the manual. Type "Make.py
-h" for help. If run from the src directory, this command will create
src/lmp_omp using src/MAKE/Makefile.mpi as the starting
Makefile.machine:
The lines above illustrate how to include/build with the USER-OMP
package in two steps, using the "make" command. Or how to do it with
one command via the src/Make.py script, described in "Section
2.4"_Section_start.html#start_4 of the manual. Type "Make.py -h" for
help.
Make.py -p omp -o omp -a file mpi :pre
Or you can follow these steps:
cd lammps/src
make yes-user-omp
make machine :pre
The CCFLAGS setting in Makefile.machine needs "-fopenmp" to add OpenMP
support. This works for both the GNU and Intel compilers. Without
this flag the USER-OMP styles will still be compiled and work, but
will not support multi-threading. For the Intel compilers the CCFLAGS
setting also needs to include "-restrict".
Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include "-fopenmp". Likewise, if you use an Intel compiler, the
CCFLAGS setting must include "-restrict". The Make.py command will
add these automatically.
[Run with the USER-OMP package from the command line:]
@ -66,30 +56,25 @@ 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.
You need to choose how many threads per MPI task will be used by the
USER-OMP package. Note that the product of MPI tasks * threads/task
should not exceed the physical number of cores (on a node), otherwise
performance will suffer.
You need to choose how many OpenMP threads per MPI task will be used
by the USER-OMP package. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.
Use the "-sf omp" "command-line switch"_Section_start.html#start_7,
which will automatically append "omp" to styles that support it. Use
the "-pk omp Nt" "command-line switch"_Section_start.html#start_7, to
set Nt = # of OpenMP threads per MPI task to use.
As in the lines above, use the "-sf omp" "command-line
switch"_Section_start.html#start_7, which will automatically append
"omp" to styles that support it. The "-sf omp" switch also issues a
default "package omp 0"_package.html command, which will set the
number of threads per MPI task via the OMP_NUM_THREADS environment
variable.
lmp_machine -sf omp -pk omp 16 -in in.script # 1 MPI task on a 16-core node
mpirun -np 4 lmp_machine -sf omp -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node
mpirun -np 32 -ppn 4 lmp_machine -sf omp -pk omp 4 -in in.script # ditto on 8 16-core nodes :pre
Note that if the "-sf omp" switch is used, it also issues a default
"package omp 0"_package.html command, which sets the number of threads
per MPI task via the OMP_NUM_THREADS environment variable.
Using the "-pk" switch explicitly allows for direct setting of the
number of threads and additional options. Its syntax is the same as
the "package omp" command. See the "package"_package.html command doc
page for details, including the default values used for all its
options if it is not specified, and how to set the number of threads
via the OMP_NUM_THREADS environment variable if desired.
You can also use the "-pk omp Nt" "command-line
switch"_Section_start.html#start_7, to explicitly set Nt = # of OpenMP
threads per MPI task to use, as well as additional options. Its
syntax is the same as the "package omp"_package.html command whose doc
page gives details, including the default values used if it is not
specified. It also gives more details on how to set the number of
threads via the OMP_NUM_THREADS environment variable.
[Or run with the USER-OMP package by editing an input script:]
@ -102,11 +87,10 @@ Use the "suffix omp"_suffix.html command, or you can explicitly add an
pair_style lj/cut/omp 2.5 :pre
You must also use the "package omp"_package.html command to enable the
USER-OMP package, unless the "-sf omp" or "-pk omp" "command-line
switches"_Section_start.html#start_7 were used. It specifies how many
threads per MPI task to use, as well as other options. Its doc page
explains how to set the number of threads via an environment variable
if desired.
USER-OMP package. When you do this you also specify how many threads
per MPI task to use. The command doc page explains other options and
how to set the number of threads via the OMP_NUM_THREADS environment
variable.
[Speed-ups to expect:]
@ -116,16 +100,16 @@ time" values printed at the end of a run.
You may see a small performance advantage (5 to 20%) when running a
USER-OMP style (in serial or parallel) with a single thread per MPI
task, versus running standard LAMMPS with its standard
(un-accelerated) styles (in serial or all-MPI parallelization with 1
task/core). This is because many of the USER-OMP styles contain
similar optimizations to those used in the OPT package, as described
above.
task, versus running standard LAMMPS with its standard un-accelerated
styles (in serial or all-MPI parallelization with 1 task/core). This
is because many of the USER-OMP styles contain similar optimizations
to those used in the OPT package, described in "Section accelerate
5.3.6"_accelerate_opt.html.
With multiple threads/task, the optimal choice of MPI tasks/node and
OpenMP threads/task can vary a lot and should always be tested via
benchmark runs for a specific simulation running on a specific
machine, paying attention to guidelines discussed in the next
With multiple threads/task, the optimal choice of number of MPI
tasks/node and OpenMP threads/task can vary a lot and should always be
tested via benchmark runs for a specific simulation running on a
specific machine, paying attention to guidelines discussed in the next
sub-section.
A description of the multi-threading strategy used in the USER-OMP
@ -146,7 +130,7 @@ circumstances:
Individual compute nodes have a significant number of CPU cores but
the CPU itself has limited memory bandwidth, e.g. for Intel Xeon 53xx
(Clovertown) and 54xx (Harpertown) quad core processors. Running one
(Clovertown) and 54xx (Harpertown) quad-core processors. Running one
MPI task per CPU core will result in significant performance
degradation, so that running with 4 or even only 2 MPI tasks per node
is faster. Running in hybrid MPI+OpenMP mode will reduce the
@ -184,17 +168,18 @@ of MPI tasks assigned to the KSpace calculation. :l,ule
Additional performance tips are as follows:
The best parallel efficiency from {omp} styles is typically achieved
when there is at least one MPI task per physical processor,
i.e. socket or die. :ulb,l
when there is at least one MPI task per physical CPU chip, i.e. socket
or die. :ulb,l
It is usually most efficient to restrict threading to a single
socket, i.e. use one or more MPI task per socket. :l
Several current MPI implementation by default use a processor affinity
setting that restricts each MPI task to a single CPU core. Using
multi-threading in this mode will force the threads to share that core
and thus is likely to be counterproductive. Instead, binding MPI
tasks to a (multi-core) socket, should solve this issue. :l,ule
IMPORTANT NOTE: By default, several current MPI implementations use a
processor affinity setting that restricts each MPI task to a single
CPU core. Using multi-threading in this mode will force all threads
to share the one core and thus is likely to be counterproductive.
Instead, binding MPI tasks to a (multi-core) socket, should solve this
issue. :l,ule
[Restrictions:]

53
doc/accelerate_opt.html
View File

@ -132,41 +132,30 @@ Technologies), David Richie, and Vincent Natoli (Stone Ridge
Technologies). It contains a handful of pair styles whose compute()
methods were rewritten in C++ templated form to reduce the overhead
due to if tests and other conditional code.</p>
<p>Here is a quick overview of how to use the OPT package:</p>
<ul class="simple">
<li>include the OPT package and build LAMMPS</li>
<li>use OPT pair styles in your input script</li>
</ul>
<p>The last step can be done using the &#8220;-sf opt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>. Or the effect of the &#8220;-sf&#8221; switch
can be duplicated by adding a <a class="reference internal" href="suffix.html"><em>suffix opt</em></a> command to your
input script.</p>
<p>Here is a quick overview of how to use the OPT package. More details
follow.</p>
<div class="highlight-python"><div class="highlight"><pre>make yes-opt
make mpi # build with the OPT pacakge
Make.py -v -p opt -o mpi -a file mpi # or one-line build via Make.py
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>lmp_mpi -sf opt -in in.script # run in serial
mpirun -np 4 lmp_mpi -sf opt -in in.script # run in parallel
</pre></div>
</div>
<p><strong>Required hardware/software:</strong></p>
<p>None.</p>
<p><strong>Building LAMMPS with the OPT package:</strong></p>
<p>Include the package and build LAMMPS:</p>
<p>To do this in one line, use the src/Make.py script, described in
<a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual. Type &#8220;Make.py
-h&#8221; for help. If run from the src directory, this command will create
src/lmp_opt using src/MAKE/Makefile.mpi as the starting
Makefile.machine:</p>
<div class="highlight-python"><div class="highlight"><pre>Make.py -p opt -o opt -a file mpi
</pre></div>
</div>
<p>Or you can follow these steps:</p>
<div class="highlight-python"><div class="highlight"><pre>cd lammps/src
make yes-opt
make machine
</pre></div>
</div>
<p>If you are using Intel compilers, then the CCFLAGS setting in
Makefile.machine needs to include &#8220;-restrict&#8221;.</p>
<p>The lines above illustrate how to build LAMMPS with the OPT package in
two steps, using the &#8220;make&#8221; command. Or how to do it with one command
via the src/Make.py script, described in <a class="reference internal" href="Section_start.html#start-4"><span>Section 2.4</span></a> of the manual. Type &#8220;Make.py -h&#8221; for
help.</p>
<p>Note that if you use an Intel compiler to build with the OPT package,
the CCFLAGS setting in your Makefile.machine must include &#8220;-restrict&#8221;.
The Make.py command will add this automatically.</p>
<p><strong>Run with the OPT package from the command line:</strong></p>
<p>Use the &#8220;-sf opt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>,
which will automatically append &#8220;opt&#8221; to styles that support it.</p>
<div class="highlight-python"><div class="highlight"><pre>lmp_machine -sf opt -in in.script
mpirun -np 4 lmp_machine -sf opt -in in.script
</pre></div>
</div>
<p>As in the lines above, use the &#8220;-sf opt&#8221; <a class="reference internal" href="Section_start.html#start-7"><span>command-line switch</span></a>, which will automatically append
&#8220;opt&#8221; to styles that support it.</p>
<p><strong>Or run with the OPT package by editing an input script:</strong></p>
<p>Use the <a class="reference internal" href="suffix.html"><em>suffix opt</em></a> command, or you can explicitly add an
&#8220;opt&#8221; suffix to individual styles in your input script, e.g.</p>
@ -178,7 +167,7 @@ mpirun -np 4 lmp_machine -sf opt -in in.script
of a run. On most machines for reasonable problem sizes, it will be a
5 to 20% savings.</p>
<p><strong>Guidelines for best performance:</strong></p>
<p>None. Just try out an OPT pair style to see how it performs.</p>
<p>Just try out an OPT pair style to see how it performs.</p>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline"></a></h2>
<p>None.</p>

49
doc/accelerate_opt.txt
View File

@ -17,15 +17,15 @@ Technologies). It contains a handful of pair styles whose compute()
methods were rewritten in C++ templated form to reduce the overhead
due to if tests and other conditional code.
Here is a quick overview of how to use the OPT package:
Here is a quick overview of how to use the OPT package. More details
follow.
include the OPT package and build LAMMPS
use OPT pair styles in your input script :ul
make yes-opt
make mpi # build with the OPT pacakge
Make.py -v -p opt -o mpi -a file mpi # or one-line build via Make.py :pre
The last step can be done using the "-sf opt" "command-line
switch"_Section_start.html#start_7. Or the effect of the "-sf" switch
can be duplicated by adding a "suffix opt"_suffix.html command to your
input script.
lmp_mpi -sf opt -in in.script # run in serial
mpirun -np 4 lmp_mpi -sf opt -in in.script # run in parallel :pre
[Required hardware/software:]
@ -33,32 +33,21 @@ None.
[Building LAMMPS with the OPT package:]
Include the package and build LAMMPS:
The lines above illustrate how to build LAMMPS with the OPT package in
two steps, using the "make" command. Or how to do it with one command
via the src/Make.py script, described in "Section
2.4"_Section_start.html#start_4 of the manual. Type "Make.py -h" for
help.
To do this in one line, use the src/Make.py script, described in
"Section 2.4"_Section_start.html#start_4 of the manual. Type "Make.py
-h" for help. If run from the src directory, this command will create
src/lmp_opt using src/MAKE/Makefile.mpi as the starting
Makefile.machine:
Make.py -p opt -o opt -a file mpi :pre
Or you can follow these steps:
cd lammps/src
make yes-opt
make machine :pre
If you are using Intel compilers, then the CCFLAGS setting in
Makefile.machine needs to include "-restrict".
Note that if you use an Intel compiler to build with the OPT package,
the CCFLAGS setting in your Makefile.machine must include "-restrict".
The Make.py command will add this automatically.
[Run with the OPT package from the command line:]
Use the "-sf opt" "command-line switch"_Section_start.html#start_7,
which will automatically append "opt" to styles that support it.
lmp_machine -sf opt -in in.script
mpirun -np 4 lmp_machine -sf opt -in in.script :pre
As in the lines above, use the "-sf opt" "command-line
switch"_Section_start.html#start_7, which will automatically append
"opt" to styles that support it.
[Or run with the OPT package by editing an input script:]
@ -75,7 +64,7 @@ of a run. On most machines for reasonable problem sizes, it will be a
[Guidelines for best performance:]
None. Just try out an OPT pair style to see how it performs.
Just try out an OPT pair style to see how it performs.
[Restrictions:]

4
doc/genindex.html
View File

@ -1938,6 +1938,10 @@
</dt>
<dt><a href="pair_vashishta.html#index-0">pair_style vashishta</a>
</dt>
<dt><a href="pair_yukawa.html#index-0">pair_style yukawa</a>
</dt>

14
doc/pair_hybrid.html
View File

@ -198,11 +198,15 @@ model, then you should just list the sub-style once and use the
pair_coeff command to assign parameters for the different type pairs.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">An exception to this option to list an individual pair
style multiple times are the pair styles implemented as Fortran
libraries: <a class="reference internal" href="pair_meam.html"><em>pair_style meam</em></a> and <a class="reference internal" href="pair_reax.html"><em>pair_style reax</em></a> (<a class="reference internal" href="pair_reax_c.html"><em>pair_style reax/c</em></a> is OK).
This is because unlike a C++ class, they can not be instantiated
multiple times, due to the manner in which they were coded in Fortran.</p>
<p class="last">There are two exceptions to this option to list an
individual pair style multiple times. The first is for pair styles
implemented as Fortran libraries: <a class="reference internal" href="pair_meam.html"><em>pair_style meam</em></a> and
<a class="reference internal" href="pair_reax.html"><em>pair_style reax</em></a> (<a class="reference internal" href="pair_reax_c.html"><em>pair_style reax/c</em></a>
is OK). This is because unlike a C++ class, they can not be
instantiated multiple times, due to the manner in which they were
coded in Fortran. The second is for GPU-enabled pair styles in the
GPU package. This is b/c the GPU package also currently assumes that
only one instance of a pair style is being used.</p>
</div>
<p>In the pair_coeff commands, the name of a pair style must be added
after the I,J type specification, with the remaining coefficients

15
doc/pair_hybrid.txt
View File

@ -70,12 +70,15 @@ other pairwise potential for several different atom type pairs in your
model, then you should just list the sub-style once and use the
pair_coeff command to assign parameters for the different type pairs.
IMPORTANT NOTE: An exception to this option to list an individual pair
style multiple times are the pair styles implemented as Fortran
libraries: "pair_style meam"_pair_meam.html and "pair_style
reax"_pair_reax.html ("pair_style reax/c"_pair_reax_c.html is OK).
This is because unlike a C++ class, they can not be instantiated
multiple times, due to the manner in which they were coded in Fortran.
IMPORTANT NOTE: There are two exceptions to this option to list an
individual pair style multiple times. The first is for pair styles
implemented as Fortran libraries: "pair_style meam"_pair_meam.html and
"pair_style reax"_pair_reax.html ("pair_style reax/c"_pair_reax_c.html
is OK). This is because unlike a C++ class, they can not be
instantiated multiple times, due to the manner in which they were
coded in Fortran. The second is for GPU-enabled pair styles in the
GPU package. This is b/c the GPU package also currently assumes that
only one instance of a pair style is being used.
In the pair_coeff commands, the name of a pair style must be added
after the I,J type specification, with the remaining coefficients

1
doc/pair_style.html
View File

@ -309,6 +309,7 @@ in the pair section of <a class="reference internal" href="Section_commands.html
<li><a class="reference internal" href="pair_coul.html"><em>pair_style tip4p/cut</em></a> - Coulomb for TIP4P water w/out LJ</li>
<li><a class="reference internal" href="pair_coul.html"><em>pair_style tip4p/long</em></a> - long-range Coulombics for TIP4P water w/out LJ</li>
<li><a class="reference internal" href="pair_tri_lj.html"><em>pair_style tri/lj</em></a> - LJ potential between triangles</li>
<li><code class="xref doc docutils literal"><span class="pre">pair_style</span> <span class="pre">vashishta</span></code> - Vashishta 2-body and 3-body potential</li>
<li><a class="reference internal" href="pair_yukawa.html"><em>pair_style yukawa</em></a> - Yukawa potential</li>
<li><a class="reference internal" href="pair_yukawa_colloid.html"><em>pair_style yukawa/colloid</em></a> - screened Yukawa potential for finite-size particles</li>
<li><a class="reference internal" href="pair_zbl.html"><em>pair_style zbl</em></a> - Ziegler-Biersack-Littmark potential</li>

461
doc/pair_vashishta.html
View File

@ -1,103 +1,219 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>pair_style vashishta command &mdash; LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<HR>
<H3>pair_style vashishta command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>pair_style vashishta
</PRE>
<P><B>Examples:</B>
</P>
<PRE>pair_style vashishta
pair_coeff * * SiC.vashishta Si C
</PRE>
<P><B>Description:</B>
</P>
<P>The <I>vashishta</I> style computes the combined 2-body and 3-body
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li>pair_style vashishta command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="pair-style-vashishta-command">
<span id="index-0"></span><h1>pair_style vashishta command<a class="headerlink" href="#pair-style-vashishta-command" title="Permalink to this headline"></a></h1>
</div>
<div class="section" id="pair-style-vashishta-omp-command">
<h1>pair_style vashishta/omp command<a class="headerlink" href="#pair-style-vashishta-omp-command" title="Permalink to this headline"></a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline"></a></h2>
<div class="highlight-python"><div class="highlight"><pre>pair_style vashishta
</pre></div>
</div>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline"></a></h2>
<div class="highlight-python"><div class="highlight"><pre>pair_style vashishta
pair_coeff * * SiC.vashishta Si C
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline"></a></h2>
<p>The <em>vashishta</em> style computes the combined 2-body and 3-body
family of potentials developed in the group of Vashishta and
co-workers. By combining repulsive, screened Coulombic,
screened charge-dipole, and dispersion interactions with a
bond-angle energy based on the Stillinger-Weber potential,
co-workers. By combining repulsive, screened Coulombic,
screened charge-dipole, and dispersion interactions with a
bond-angle energy based on the Stillinger-Weber potential,
this potential has been used to describe a variety of inorganic
compounds, including SiO2 <A HREF = "#Vashishta1990">Vashishta1990</A>,
SiC <A HREF = "#Vashishta2007">Vashishta2007</A>,
and InP <A HREF = "#Branicio2009">Branicio2009</A>.
</P>
<P>The potential for the energy U of a system of atoms is
</P>
<CENTER><IMG SRC = "Eqs/pair_vashishta.jpg">
</CENTER>
<P>where we follow the notation used in <A HREF = "#Branicio2009">Branicio2009</A>.
compounds, including SiO2 <a class="reference internal" href="#vashishta1990"><span>Vashishta1990</span></a>,
SiC <a class="reference internal" href="#vashishta2007"><span>Vashishta2007</span></a>,
and InP <a class="reference internal" href="#branicio2009"><span>Branicio2009</span></a>.</p>
<p>The potential for the energy U of a system of atoms is</p>
<img alt="_images/pair_vashishta.jpg" class="align-center" src="_images/pair_vashishta.jpg" />
<p>where we follow the notation used in <a class="reference internal" href="#branicio2009"><span>Branicio2009</span></a>.
U2 is a two-body term and U3 is a three-body term. The
summation over two-body terms is over all neighbors J within
a cutoff distance = <I>rc</I>. The twobody terms are shifted and
tilted by a linear function so that the energy and force are
both zero at <I>rc</I>. The summation over three-body terms
is over all neighbors J and K within a cut-off distance = <I>r0</I>,
where the exponential screening function becomes zero.
</P>
<P>Only a single pair_coeff command is used with the <I>vashishta</I> style which
a cutoff distance = <em>rc</em>. The twobody terms are shifted and
tilted by a linear function so that the energy and force are
both zero at <em>rc</em>. The summation over three-body terms
is over all neighbors J and K within a cut-off distance = <em>r0</em>,
where the exponential screening function becomes zero.</p>
<p>Only a single pair_coeff command is used with the <em>vashishta</em> style which
specifies a Vashishta potential file with parameters for all
needed elements. These are mapped to LAMMPS atom types by specifying
N additional arguments after the filename in the pair_coeff command,
where N is the number of LAMMPS atom types:
</P>
<UL><LI>filename
<LI>N element names = mapping of Vashishta elements to atom types
</UL>
<P>See the <A HREF = "pair_coeff.html">pair_coeff</A> doc page for alternate ways
to specify the path for the potential file.
</P>
<P>As an example, imagine a file SiC.vashishta has parameters for
where N is the number of LAMMPS atom types:</p>
<ul class="simple">
<li>filename</li>
<li>N element names = mapping of Vashishta elements to atom types</li>
</ul>
<p>See the <a class="reference internal" href="pair_coeff.html"><em>pair_coeff</em></a> doc page for alternate ways
to specify the path for the potential file.</p>
<p>As an example, imagine a file SiC.vashishta has parameters for
Si and C. If your LAMMPS simulation has 4 atoms types and you want
the 1st 3 to be Si, and the 4th to be C, you would use the following
pair_coeff command:
</P>
<PRE>pair_coeff * * SiC.vashishta Si Si Si C
</PRE>
<P>The 1st 2 arguments must be * * so as to span all LAMMPS atom types.
pair_coeff command:</p>
<div class="highlight-python"><div class="highlight"><pre>pair_coeff * * SiC.vashishta Si Si Si C
</pre></div>
</div>
<p>The 1st 2 arguments must be * * so as to span all LAMMPS atom types.
The first three Si arguments map LAMMPS atom types 1,2,3 to the Si
element in the file. The final C argument maps LAMMPS atom type 4
to the C element in the file. If a mapping value is specified as
NULL, the mapping is not performed. This can be used when a <I>vashishta</I>
potential is used as part of the <I>hybrid</I> pair style. The NULL values
NULL, the mapping is not performed. This can be used when a <em>vashishta</em>
potential is used as part of the <em>hybrid</em> pair style. The NULL values
are placeholders for atom types that will be used with other
potentials.
</P>
<P>Vashishta files in the <I>potentials</I> directory of the LAMMPS
distribution have a ".vashishta" suffix. Lines that are not blank or
potentials.</p>
<p>Vashishta files in the <em>potentials</em> directory of the LAMMPS
distribution have a &#8221;.vashishta&#8221; suffix. Lines that are not blank or
comments (starting with #) define parameters for a triplet of
elements. The parameters in a single entry correspond to the two-body
and three-body coefficients in the formulae above:
</P>
<UL><LI>element 1 (the center atom in a 3-body interaction)
<LI>element 2
<LI>element 3
<LI>H (energy units)
<LI>eta
<LI>Zi (electron charge units)
<LI>Zj (electron charge units)
<LI>lambda1 (distance units)
<LI>D (energy units)
<LI>lambda4 (distance units)
<LI>W (energy units)
<LI>rc (distance units)
<LI>B (energy units)
<LI>gamma
<LI>r0 (distance units)
<LI>C
<LI>costheta0
</UL>
<P>The non-annotated parameters are unitless.
and three-body coefficients in the formulae above:</p>
<ul class="simple">
<li>element 1 (the center atom in a 3-body interaction)</li>
<li>element 2</li>
<li>element 3</li>
<li>H (energy units)</li>
<li>eta</li>
<li>Zi (electron charge units)</li>
<li>Zj (electron charge units)</li>
<li>lambda1 (distance units)</li>
<li>D (energy units)</li>
<li>lambda4 (distance units)</li>
<li>W (energy units)</li>
<li>rc (distance units)</li>
<li>B (energy units)</li>
<li>gamma</li>
<li>r0 (distance units)</li>
<li>C</li>
<li>costheta0</li>
</ul>
<p>The non-annotated parameters are unitless.
The Vashishta potential file must contain entries for all the
elements listed in the pair_coeff command. It can also contain
entries for additional elements not being used in a particular
@ -107,9 +223,8 @@ For a single-element simulation, only a single entry is required
entries (for SiSiSi, SiSiC, SiCSi, SiCC, CSiSi, CSiC, CCSi, CCC), that
specify parameters for all permutations of the two elements
interacting in three-body configurations. Thus for 3 elements, 27
entries would be required, etc.
</P>
<P>Depending on the particular version of the Vashishta potential,
entries would be required, etc.</p>
<p>Depending on the particular version of the Vashishta potential,
the values of these parameters may be keyed to the identities of
zero, one, two, or three elements.
In order to make the input file format unambiguous, general,
@ -125,87 +240,145 @@ even though they only have 1 subscript.
The three-body parameters are B, C, costheta0.
They appear in the above formulae with three subscripts.
Two-body and three-body parameters are handled differently,
as described below.
</P>
<P>The first element in each entry is the center atom
as described below.</p>
<p>The first element in each entry is the center atom
in a three-body interaction, while the second and third elements
are two neighbor atoms. Three-body parameters for a central atom I
and two neighbors J and K are taken from the IJK entry.
Note that even though three-body parameters do not depend on the order of
J and K, LAMMPS stores three-body parameters for both IJK and IKJ.
The user must ensure that these values are equal.
The user must ensure that these values are equal.
Two-body parameters for an atom I interacting with atom J are taken from
the IJJ entry, where the 2nd and 3rd
elements are the same. Thus the two-body parameters
elements are the same. Thus the two-body parameters
for Si interacting with C come from the SiCC entry. Note that even
though two-body parameters (except possibly gamma and r0 in U3)
do not depend on the order of the two elements,
though two-body parameters (except possibly gamma and r0 in U3)
do not depend on the order of the two elements,
LAMMPS will get the Si-C value from the SiCC entry
and the C-Si value from the CSiSi entry. The user must ensure
that these values are equal. Two-body parameters appearing
in entries where the 2nd and 3rd elements are different are
stored but never used. It is good practice to enter zero for
these values. Note that the three-body function U3 above
contains the two-body parameters gamma and r0. So U3 for a
these values. Note that the three-body function U3 above
contains the two-body parameters gamma and r0. So U3 for a
central C atom bonded to an Si atom and a second C atom
will take three-body parameters from the CSiC entry, but
two-body parameters from the CCC and CSiSi entries.
</P>
<HR>
<P><B>Mixing, shift, table, tail correction, restart, rRESPA info</B>:
</P>
<P>For atom type pairs I,J and I != J, where types I and J correspond to
two-body parameters from the CCC and CSiSi entries.</p>
<hr class="docutils" />
<p>Styles with a <em>cuda</em>, <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><em>Section_accelerate</em></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the USER-CUDA, GPU, USER-INTEL,
KOKKOS, USER-OMP and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span>Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span>-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><em>suffix</em></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><em>Section_accelerate</em></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Mixing, shift, table, tail correction, restart, rRESPA info</strong>:</p>
<p>For atom type pairs I,J and I != J, where types I and J correspond to
two different element types, mixing is performed by LAMMPS as
described above from values in the potential file.
</P>
<P>This pair style does not support the <A HREF = "pair_modify.html">pair_modify</A>
shift, table, and tail options.
</P>
<P>This pair style does not write its information to <A HREF = "restart.html">binary restart
files</A>, since it is stored in potential files. Thus, you
described above from values in the potential file.</p>
<p>This pair style does not support the <a class="reference internal" href="pair_modify.html"><em>pair_modify</em></a>
shift, table, and tail options.</p>
<p>This pair style does not write its information to <a class="reference internal" href="restart.html"><em>binary restart files</em></a>, since it is stored in potential files. Thus, you
need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.
</P>
<P>This pair style can only be used via the <I>pair</I> keyword of the
<A HREF = "run_style.html">run_style respa</A> command. It does not support the
<I>inner</I>, <I>middle</I>, <I>outer</I> keywords.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>This pair style is part of the MANYBODY package. It is only enabled
script that reads a restart file.</p>
<p>This pair style can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><em>run_style respa</em></a> command. It does not support the
<em>inner</em>, <em>middle</em>, <em>outer</em> keywords.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline"></a></h2>
<p>This pair style is part of the MANYBODY package. It is only enabled
if LAMMPS was built with that package (which it is by default). See
the <A HREF = "Section_start.html#start_3">Making LAMMPS</A> section for more info.
</P>
<P>This pair style requires the <A HREF = "newton.html">newton</A> setting to be "on"
for pair interactions.
</P>
<P>The Vashishta potential files provided with LAMMPS (see the
potentials directory) are parameterized for metal <A HREF = "units.html">units</A>.
the <a class="reference internal" href="Section_start.html#start-3"><span>Making LAMMPS</span></a> section for more info.</p>
<p>This pair style requires the <a class="reference internal" href="newton.html"><em>newton</em></a> setting to be &#8220;on&#8221;
for pair interactions.</p>
<p>The Vashishta potential files provided with LAMMPS (see the
potentials directory) are parameterized for metal <a class="reference internal" href="units.html"><em>units</em></a>.
You can use the Vashishta potential with any LAMMPS units, but you would need
to create your own Vashishta potential file with coefficients listed in the
appropriate units if your simulation doesn't use "metal" units.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "pair_coeff.html">pair_coeff</A>
</P>
<P><B>Default:</B> none
</P>
<HR>
appropriate units if your simulation doesn&#8217;t use &#8220;metal&#8221; units.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="pair_coeff.html"><em>pair_coeff</em></a></p>
<p><strong>Default:</strong> none</p>
<hr class="docutils" />
<p id="vashishta1990"><strong>(Vashishta1990)</strong> P. Vashishta, R. K. Kalia, J. P. Rino, Phys. Rev. B 41, 12197 (1990).</p>
<p id="vashishta2007"><strong>(Vashishta2007)</strong> P. Vashishta, R. K. Kalia, A. Nakano, J. P. Rino. J. Appl. Phys. 101, 103515 (2007).</p>
<p id="branicio2009"><strong>(Branicio2009)</strong> Branicio, Rino, Gan and Tsuzuki, J. Phys Condensed Matter 21 (2009) 095002</p>
</div>
</div>
<A NAME = "Vashishta1990"></A>
<P><B>(Vashishta1990)</B> P. Vashishta, R. K. Kalia, J. P. Rino, Phys. Rev. B 41, 12197 (1990).
</P>
<A NAME = "Vashishta2007"></A>
</div>
</div>
<footer>
<P><B>(Vashishta2007)</B> P. Vashishta, R. K. Kalia, A. Nakano, J. P. Rino. J. Appl. Phys. 101, 103515 (2007).
</P>
<A NAME = "Branicio2009"></A>
<hr/>
<P><B>(Branicio2009)</B> Branicio, Rino, Gan and Tsuzuki, J. Phys Condensed Matter 21 (2009) 095002
</P>
</HTML>
<div role="contentinfo">
<p>
&copy; Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>

2
doc/searchindex.js
View File

File diff suppressed because one or more lines are too long