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@13789 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2015-07-29 23:55:00 +00:00
parent 0bc9643615
commit 5c85ecd413
956 changed files with 1510 additions and 114990 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/Manual.html
View File

@ -114,12 +114,20 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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">
@ -408,6 +416,7 @@ it gives quick access to documentation for all LAMMPS commands.</p>
<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>

6
doc/Manual.txt
View File

@ -85,7 +85,7 @@ it gives quick access to documentation for all LAMMPS commands.
.. toctree::
:maxdepth: 2
:numbered:
:numbered: // comment
Section_intro
Section_start
@ -105,8 +105,8 @@ it gives quick access to documentation for all LAMMPS commands.
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
* :ref:`genindex` // comment
* :ref:`search` // comment
END_RST -->

13
doc/Section_accelerate.html
View File

@ -124,12 +124,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_howto.html" class="btn btn-neutral float-right" title="6. How-to discussions" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_packages.html" class="btn btn-neutral" title="4. Packages" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -582,6 +592,7 @@ to benchmark the performance of both packages on your system.</p>
<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>

13
doc/Section_commands.html
View File

@ -130,12 +130,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_packages.html" class="btn btn-neutral float-right" title="4. Packages" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_start.html" class="btn btn-neutral" title="2. Getting Started" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -1442,6 +1452,7 @@ KOKKOS, o = USER-OMP, t = OPT.</p>
<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>

13
doc/Section_errors.html
View File

@ -122,12 +122,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_history.html" class="btn btn-neutral float-right" title="13. Future and history" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_python.html" class="btn btn-neutral" title="11. Python interface to LAMMPS" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -6343,6 +6353,7 @@ infinity.</dd>
<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>

13
doc/Section_example.html
View File

@ -115,12 +115,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_perf.html" class="btn btn-neutral float-right" title="8. Performance &amp; scalability" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_howto.html" class="btn btn-neutral" title="6. How-to discussions" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -362,6 +372,7 @@ packages.</p>
<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>

11
doc/Section_history.html
View File

@ -118,12 +118,20 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_errors.html" class="btn btn-neutral" title="12. Errors" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -280,6 +288,7 @@ internally. A brief listing of their features is given here.</p>
<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>

13
doc/Section_howto.html
View File

@ -170,12 +170,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_example.html" class="btn btn-neutral float-right" title="7. Example problems" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_accelerate.html" class="btn btn-neutral" title="5. Accelerating LAMMPS performance" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -2821,6 +2831,7 @@ Phys, 79, 926 (1983).</p>
<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>

13
doc/Section_intro.html
View File

@ -135,12 +135,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_start.html" class="btn btn-neutral float-right" title="2. Getting Started" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Manual.html" class="btn btn-neutral" title="LAMMPS Documentation" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -660,6 +670,7 @@ version of LAMMPS were the following:</p>
<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>

13
doc/Section_modify.html
View File

@ -132,12 +132,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_python.html" class="btn btn-neutral float-right" title="11. Python interface to LAMMPS" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_tools.html" class="btn btn-neutral" title="9. Additional tools" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -1209,6 +1219,7 @@ feature.</p>
<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>

13
doc/Section_packages.html
View File

@ -138,12 +138,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_accelerate.html" class="btn btn-neutral float-right" title="5. Accelerating LAMMPS performance" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_commands.html" class="btn btn-neutral" title="3. Commands" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -1299,6 +1309,7 @@ you have questions.</p>
<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>

13
doc/Section_perf.html
View File

@ -115,12 +115,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_tools.html" class="btn btn-neutral float-right" title="9. Additional tools" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_example.html" class="btn btn-neutral" title="7. Example problems" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -269,6 +279,7 @@ on 1500 processors that ran at 85% parallel efficiency.</p>
<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>

21
doc/Section_python.html
View File

@ -130,12 +130,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_errors.html" class="btn btn-neutral float-right" title="12. Errors" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_modify.html" class="btn btn-neutral" title="10. Modifying &amp; extending LAMMPS" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -850,7 +860,7 @@ variables that have to match the VMD installation on your system.</p>
source code for individual scripts for comments about what they do.</p>
<p>Here are screenshots of the vizplotgui_tool.py script in action for
different visualization package options. Click to see larger images:</p>
<a data-lightbox="group-a9e7c403-7974-4d0b-8735-23c81e15c71a"
<a data-lightbox="group-a67dcb54-45e3-4f9a-8419-cc49899f7dae"
href="_images/screenshot_gl.jpg"
class=""
title=""
@ -860,7 +870,7 @@ different visualization package options. Click to see larger images:</p>
width="25%"
height="auto"
alt=""/>
</a><a data-lightbox="group-ea8c6846-25f4-406a-b892-e93ba3c4c47d"
</a><a data-lightbox="group-87dc8228-44a3-43a0-b863-b23a8578b25d"
href="_images/screenshot_atomeye.jpg"
class=""
title=""
@ -870,7 +880,7 @@ different visualization package options. Click to see larger images:</p>
width="25%"
height="auto"
alt=""/>
</a><a data-lightbox="group-8ca30431-95a2-4503-b487-ec804cd6bc64"
</a><a data-lightbox="group-ff85a8ae-f8ee-48ad-a62c-3ece7d383afa"
href="_images/screenshot_pymol.jpg"
class=""
title=""
@ -880,7 +890,7 @@ different visualization package options. Click to see larger images:</p>
width="25%"
height="auto"
alt=""/>
</a><a data-lightbox="group-5dc72449-ae6a-4097-b7d7-8345723ca951"
</a><a data-lightbox="group-c5001468-50f3-4dc4-8a87-c316d0e65ce3"
href="_images/screenshot_vmd.jpg"
class=""
title=""
@ -942,6 +952,7 @@ different visualization package options. Click to see larger images:</p>
<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>

13
doc/Section_start.html
View File

@ -132,12 +132,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_commands.html" class="btn btn-neutral float-right" title="3. Commands" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_intro.html" class="btn btn-neutral" title="1. Introduction" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -1878,6 +1888,7 @@ close if you have setup the problem for both codes the same.</p>
<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>

13
doc/Section_tools.html
View File

@ -148,12 +148,22 @@
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<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_modify.html" class="btn btn-neutral float-right" title="10. Modifying &amp; extending LAMMPS" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_perf.html" class="btn btn-neutral" title="8. Performance &amp; scalability" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
@ -672,6 +682,7 @@ distributing his great tool!</p>
<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>

104
doc/_sources/Manual.txt
View File

@ -1,104 +0,0 @@
.. raw:: html
<H1></H1>
LAMMPS Documentation
====================
27 Jul 2015 version
-------------------
Version info:
-------------
The LAMMPS "version" 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 `this page of the WWW site <bug_>`_. 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).
* If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.
* If you browse the HTML doc pages included in your tarball, they
describe the version you have.
* The `PDF file <Manual.pdf>`_ 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.
* There is also a `Developer.pdf <Developer.pdf>`_ file in the doc
directory, which describes the internal structure and algorithms of
LAMMPS.
LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.
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).
The primary developers of LAMMPS are `Steve Plimpton <sjp_>`_, Aidan
Thompson, and Paul Crozier who can be contacted at
sjplimp,athomps,pscrozi at sandia.gov. The `LAMMPS WWW Site <lws_>`_ at
http://lammps.sandia.gov has more information about the code and its
uses.
.. _bug: http://lammps.sandia.gov/bug.html
.. _sjp: http://www.sandia.gov/~sjplimp
----------
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.
Once you are familiar with LAMMPS, you may want to bookmark :ref:`this page <comm>` at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.
`PDF file <Manual.pdf>`_ of the entire manual, generated by
`htmldoc <http://freecode.com/projects/htmldoc>`_
.. toctree::
:maxdepth: 2
:numbered:
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
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
.. raw:: html
</BODY>
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

408
doc/_sources/Section_accelerate.txt
View File

@ -1,408 +0,0 @@
Accelerating LAMMPS performance
===============================
This section describes various methods for improving LAMMPS
performance for different classes of problems running on different
kinds of machines.
There are two thrusts to the discussion that follows. The
first is using code options that implement alternate algorithms
that can speed-up a simulation. The second is to use one
of the several accelerator packages provided with LAMMPS that
contain code optimized for certain kinds of hardware, including
multi-core CPUs, GPUs, and Intel Xeon Phi coprocessors.
* 5.1 :ref:`Measuring performance <acc_1>`
* 5.2 :ref:`Algorithms and code options to boost performace <acc_2>`
* 5.3 :ref:`Accelerator packages with optimized styles <acc_3>`
* 5.3.1 :doc:`USER-CUDA package <accelerate_cuda>`
* 5.3.2 :doc:`GPU package <accelerate_gpu>`
* 5.3.3 :doc:`USER-INTEL package <accelerate_intel>`
* 5.3.4 :doc:`KOKKOS package <accelerate_kokkos>`
* 5.3.5 :doc:`USER-OMP package <accelerate_omp>`
* 5.3.6 :doc:`OPT package <accelerate_opt>`
* 5.4 :ref:`Comparison of various accelerator packages <acc_4>`
The `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the LAMMPS
web site gives performance results for the various accelerator
packages discussed in Section 5.2, for several of the standard LAMMPS
benchmark problems, as a function of problem size and number of
compute nodes, on different hardware platforms.
.. _acc_1:
Measuring performance
---------------------------------
Before trying to make your simulation run faster, you should
understand how it currently performs and where the bottlenecks are.
The best way to do this is run the your system (actual number of
atoms) for a modest number of timesteps (say 100 steps) on several
different processor counts, including a single processor if possible.
Do this for an equilibrium version of your system, so that the
100-step timings are representative of a much longer run. There is
typically no need to run for 1000s of timesteps to get accurate
timings; you can simply extrapolate from short runs.
For the set of runs, look at the timing data printed to the screen and
log file at the end of each LAMMPS run. :ref:`This section <start_8>` of the manual has an overview.
Running on one (or a few processors) should give a good estimate of
the serial performance and what portions of the timestep are taking
the most time. Running the same problem on a few different processor
counts should give an estimate of parallel scalability. I.e. if the
simulation runs 16x faster on 16 processors, its 100% parallel
efficient; if it runs 8x faster on 16 processors, it's 50% efficient.
The most important data to look at in the timing info is the timing
breakdown and relative percentages. For example, trying different
options for speeding up the long-range solvers will have little impact
if they only consume 10% of the run time. If the pairwise time is
dominating, you may want to look at GPU or OMP versions of the pair
style, as discussed below. Comparing how the percentages change as
you increase the processor count gives you a sense of how different
operations within the timestep are scaling. Note that if you are
running with a Kspace solver, there is additional output on the
breakdown of the Kspace time. For PPPM, this includes the fraction
spent on FFTs, which can be communication intensive.
Another important detail in the timing info are the histograms of
atoms counts and neighbor counts. If these vary widely across
processors, you have a load-imbalance issue. This often results in
inaccurate relative timing data, because processors have to wait when
communication occurs for other processors to catch up. Thus the
reported times for "Communication" or "Other" may be higher than they
really are, due to load-imbalance. If this is an issue, you can
uncomment the MPI_Barrier() lines in src/timer.cpp, and recompile
LAMMPS, to obtain synchronized timings.
----------
.. _acc_2:
General strategies
------------------------------
.. note::
this section 5.2 is still a work in progress
Here is a list of general ideas for improving simulation performance.
Most of them are only applicable to certain models and certain
bottlenecks in the current performance, so let the timing data you
generate be your guide. It is hard, if not impossible, to predict how
much difference these options will make, since it is a function of
problem size, number of processors used, and your machine. There is
no substitute for identifying performance bottlenecks, and trying out
various options.
* rRESPA
* 2-FFT PPPM
* Staggered PPPM
* single vs double PPPM
* partial charge PPPM
* verlet/split run style
* processor command for proc layout and numa layout
* load-balancing: balance and fix balance
2-FFT PPPM, also called *analytic differentiation* or *ad* PPPM, uses
2 FFTs instead of the 4 FFTs used by the default *ik differentiation*
PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to
achieve the same accuracy as 4-FFT PPPM. For problems where the FFT
cost is the performance bottleneck (typically large problems running
on many processors), 2-FFT PPPM may be faster than 4-FFT PPPM.
Staggered PPPM performs calculations using two different meshes, one
shifted slightly with respect to the other. This can reduce force
aliasing errors and increase the accuracy of the method, but also
doubles the amount of work required. For high relative accuracy, using
staggered PPPM allows one to half the mesh size in each dimension as
compared to regular PPPM, which can give around a 4x speedup in the
kspace time. However, for low relative accuracy, using staggered PPPM
gives little benefit and can be up to 2x slower in the kspace
time. For example, the rhodopsin benchmark was run on a single
processor, and results for kspace time vs. relative accuracy for the
different methods are shown in the figure below. For this system,
staggered PPPM (using ik differentiation) becomes useful when using a
relative accuracy of slightly greater than 1e-5 and above.
.. image:: JPG/rhodo_staggered.jpg
:align: center
.. warning::
Using staggered PPPM may not give the same increase in
accuracy of energy and pressure as it does in forces, so some caution
must be used if energy and/or pressure are quantities of interest,
such as when using a barostat.
----------
.. _acc_3:
Packages with optimized styles
------------------------------------------
Accelerated versions of various :doc:`pair_style <pair_style>`,
:doc:`fixes <fix>`, :doc:`computes <compute>`, and other commands have
been added to LAMMPS, which will typically run faster than the
standard non-accelerated versions. Some require appropriate hardware
to be present on your system, e.g. GPUs or Intel Xeon Phi
coprocessors.
All of these commands are in packages provided with LAMMPS. An
overview of packages is give in :doc:`Section packages <Section_packages>`. These are the accelerator packages
currently in LAMMPS, either as standard or user packages:
+--------------------------------------+------------------------------------------------+
| :doc:`USER-CUDA <accelerate_cuda>` | for NVIDIA GPUs |
+--------------------------------------+------------------------------------------------+
| :doc:`GPU <accelerate_gpu>` | for NVIDIA GPUs as well as OpenCL support |
+--------------------------------------+------------------------------------------------+
| :doc:`USER-INTEL <accelerate_intel>` | for Intel CPUs and Intel Xeon Phi |
+--------------------------------------+------------------------------------------------+
| :doc:`KOKKOS <accelerate_kokkos>` | for GPUs, Intel Xeon Phi, and OpenMP threading |
+--------------------------------------+------------------------------------------------+
| :doc:`USER-OMP <accelerate_omp>` | for OpenMP threading |
+--------------------------------------+------------------------------------------------+
| :doc:`OPT <accelerate_opt>` | generic CPU optimizations |
+--------------------------------------+------------------------------------------------+
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
the same, and the numerical results it produces should also be the
same, except for precision and round-off effects.
For example, all of these styles are accelerated variants of the
Lennard-Jones :doc:`pair_style lj/cut <pair_lj>`:
* :doc:`pair_style lj/cut/cuda <pair_lj>`
* :doc:`pair_style lj/cut/gpu <pair_lj>`
* :doc:`pair_style lj/cut/intel <pair_lj>`
* :doc:`pair_style lj/cut/kk <pair_lj>`
* :doc:`pair_style lj/cut/omp <pair_lj>`
* :doc:`pair_style lj/cut/opt <pair_lj>`
To see what accelerate styles are currently available, see
:ref:`Section_commands 5 <cmd_5>` of the manual. The
doc pages for individual commands (e.g. :doc:`pair lj/cut <pair_lj>` or
:doc:`fix nve <fix_nve>`) also list any accelerated variants available
for that style.
To use an accelerator package in LAMMPS, and one or more of the styles
it provides, follow these general steps. Details vary from package to
package and are explained in the individual accelerator doc pages,
listed above:
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| build the accelerator library | only for USER-CUDA and GPU packages |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| 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 |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| re-build LAMMPS | make machine |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| run a LAMMPS simulation | lmp_machine < in.script |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| enable the accelerator package | via "-c on" and "-k on" :ref:`command-line switches <start_7>`, <br>
only for USER-CUDA and KOKKOS packages |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| set any needed options for the package | via "-pk" :ref:`command-line switch <start_7>` or
:doc:`package <package>` command, <br>
only if defaults need to be changed |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
| use accelerated styles in your input script | via "-sf" :ref:`command-line switch <start_7>` or
:doc:`suffix <suffix>` command |
+---------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------+
The first 4 steps can be done as a single command, using the
src/Make.py tool. The Make.py tool is discussed in :ref:`Section 2.4 <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
or more accelerator packages.
The last 4 steps can all be done from the command-line when LAMMPS is
launched, without changing your input script, as illustrated in the
individual accelerator sections. Or you can add
:doc:`package <package>` and :doc:`suffix <suffix>` commands to your input
script.
.. warning::
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:
* 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
See the examples/accelerate/README and make.list files for sample
Make.py commands that build LAMMPS with any or all of the accelerator
packages. As an example, here is a command that builds with all the
GPU related packages installed (USER-CUDA, GPU, KOKKOS with Cuda),
including settings to build the needed auxiliary USER-CUDA and GPU
libraries for Kepler GPUs:
.. parsed-literal::
Make.py -j 16 -p omp gpu cuda kokkos -cc nvcc wrap=mpi -cuda mode=double arch=35 -gpu mode=double arch=35 \ -kokkos cuda arch=35 lib-all file mpi
The examples/accelerate directory also has input scripts that can be
used with all of the accelerator packages. See its README file for
details.
Likewise, the bench directory has FERMI and KEPLER and PHI
sub-directories with Make.py commands and input scripts for using all
the accelerator packages on various machines. See the README files in
those dirs.
As mentioned above, the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the LAMMPS web site gives
performance results for the various accelerator packages for several
of the standard LAMMPS benchmark problems, as a function of problem
size and number of compute nodes, on different hardware platforms.
Here is a brief summary of what the various packages provide. Details
are in the individual accelerator sections.
* Styles with a "cuda" or "gpu" suffix are part of the USER-CUDA or GPU
packages, and can be run on NVIDIA GPUs. The speed-up on a GPU
depends on a variety of factors, discussed in the accelerator
sections.
* Styles with an "intel" suffix are part of the USER-INTEL
package. These styles support vectorized single and mixed precision
calculations, in addition to full double precision. In extreme cases,
this can provide speedups over 3.5x on CPUs. The package also
supports acceleration in "offload" mode to Intel(R) Xeon Phi(TM)
coprocessors. This can result in additional speedup over 2x depending
on the hardware configuration.
* Styles with a "kk" suffix are part of the KOKKOS package, and can be
run using OpenMP on multicore CPUs, on an NVIDIA GPU, or on an Intel
Xeon Phi in "native" mode. The speed-up depends on a variety of
factors, as discussed on the KOKKOS accelerator page.
* Styles with an "omp" suffix are part of the USER-OMP package and allow
a pair-style to be run in multi-threaded mode using OpenMP. This can
be useful on nodes with high-core counts when using less MPI processes
than cores is advantageous, e.g. when running with PPPM so that FFTs
are run on fewer MPI processors or when the many MPI tasks would
overload the available bandwidth for communication.
* Styles with an "opt" suffix are part of the OPT package and typically
speed-up the pairwise calculations of your simulation by 5-25% on a
CPU.
The individual accelerator package doc pages explain:
* what hardware and software the accelerated package requires
* how to build LAMMPS with the accelerated package
* how to run with the accelerated package either via command-line switches or modifying the input script
* speed-ups to expect
* guidelines for best performance
* restrictions
----------
.. _acc_4:
Comparison of various accelerator packages
------------------------------------------------------
.. note::
this section still needs to be re-worked with additional KOKKOS
and USER-INTEL information.
The next section compares and contrasts the various accelerator
options, since there are multiple ways to perform OpenMP threading,
run on GPUs, and run on Intel Xeon Phi coprocessors.
All 3 of these packages accelerate a LAMMPS calculation using NVIDIA
hardware, but they do it in different ways.
As a consequence, for a particular simulation on specific hardware,
one package may be faster than the other. We give guidelines below,
but the best way to determine which package is faster for your input
script is to try both of them on your machine. See the benchmarking
section below for examples where this has been done.
**Guidelines for using each package optimally:**
* The GPU package allows you to assign multiple CPUs (cores) to a single
GPU (a common configuration for "hybrid" nodes that contain multicore
CPU(s) and GPU(s)) and works effectively in this mode. The USER-CUDA
package does not allow this; you can only use one CPU per GPU.
* The GPU package moves per-atom data (coordinates, forces)
back-and-forth between the CPU and GPU every timestep. The USER-CUDA
package only does this on timesteps when a CPU calculation is required
(e.g. to invoke a fix or compute that is non-GPU-ized). Hence, if you
can formulate your input script to only use GPU-ized fixes and
computes, and avoid doing I/O too often (thermo output, dump file
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.
* 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
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
atoms per GPU. When performing double precision calculations the
crossover point can be significantly smaller.
* Both packages compute bonded interactions (bonds, angles, etc) on the
CPU. This means a model with bonds will force the USER-CUDA package
to transfer per-atom data back-and-forth between the CPU and GPU every
timestep. If the GPU package is running with several MPI processes
assigned to one GPU, the cost of computing the bonded interactions is
spread across more CPUs and hence the GPU package can run faster.
* When using the GPU package with multiple CPUs assigned to one GPU, its
performance depends to some extent on high bandwidth between the CPUs
and the GPU. Hence its performance is affected if full 16 PCIe lanes
are not available for each GPU. In HPC environments this can be the
case if S2050/70 servers are used, where two devices generally share
one PCIe 2.0 16x slot. Also many multi-GPU mainboards do not provide
full 16 lanes to each of the PCIe 2.0 16x slots.
**Differences between the two packages:**
* The GPU package accelerates only pair force, neighbor list, and PPPM
calculations. The USER-CUDA package currently supports a wider range
of pair styles and can also accelerate many fix styles and some
compute styles, as well as neighbor list and PPPM calculations.
* The USER-CUDA package does not support acceleration for minimization.
* The USER-CUDA package does not support hybrid pair styles.
* The USER-CUDA package can order atoms in the neighbor list differently
from run to run resulting in a different order for force accumulation.
* The USER-CUDA package has a limit on the number of atom types that can be
used in a simulation.
* The GPU package requires neighbor lists to be built on the CPU when using
exclusion lists or a triclinic simulation box.
* The GPU package uses more GPU memory than the USER-CUDA package. This
is generally not a problem since typical runs are computation-limited
rather than memory-limited.
Examples
""""""""
The LAMMPS distribution has two directories with sample input scripts
for the GPU and USER-CUDA packages.
* lammps/examples/gpu = GPU package files
* lammps/examples/USER/cuda = USER-CUDA package files
These contain input scripts for identical systems, so they can be used
to benchmark the performance of both packages on your system.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

792
doc/_sources/Section_commands.txt
View File

@ -1,792 +0,0 @@
Commands
========
This section describes how a LAMMPS input script is formatted and the
input script commands used to define a LAMMPS simulation.
| 3.1 :ref:`LAMMPS input script <cmd_1>`
| 3.2 :ref:`Parsing rules <cmd_2>`
| 3.3 :ref:`Input script structure <cmd_3>`
| 3.4 :ref:`Commands listed by category <cmd_4>`
| 3.5 :ref:`Commands listed alphabetically <cmd_5>`
|
.. _cmd_1:
LAMMPS input script
-------------------
LAMMPS executes by reading commands from a input script (text file),
one line at a time. When the input script ends, LAMMPS exits. Each
command causes LAMMPS to take some action. It may set an internal
variable, read in a file, or run a simulation. Most commands have
default settings, which means you only need to use the command if you
wish to change the default.
In many cases, the ordering of commands in an input script is not
important. However the following rules apply:
(1) LAMMPS does not read your entire input script and then perform a
simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
.. parsed-literal::
timestep 0.5
run 100
run 100
does something different than this sequence:
.. parsed-literal::
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 fmsec) is used for two
simulations of 100 timesteps each. In the 2nd case, the default
timestep (1.0 fmsec) is used for the 1st 100 step simulation and a 0.5
fmsec timestep is used for the 2nd one.
(2) Some commands are only valid when they follow other commands. For
example you cannot set the temperature of a group of atoms until atoms
have been defined and a group command is used to define which atoms
belong to the group.
(3) Sometimes command B will use values that can be set by command A.
This means command A must precede command B in the input script if it
is to have the desired effect. For example, the
:doc:`read_data <read_data>` command initializes the system by setting
up the simulation box and assigning atoms to processors. If default
values are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read_data to
tell LAMMPS how to map processors to the simulation box.
Many input script errors are detected by LAMMPS and an ERROR or
WARNING message is printed. :doc:`This section <Section_errors>` gives
more information on what errors mean. The documentation for each
command lists restrictions on how the command can be used.
----------
.. _cmd_2:
Parsing rules
-------------
Each non-blank line in the input script is treated as a command.
LAMMPS commands are case sensitive. Command names are lower-case, as
are specified command arguments. Upper case letters may be used in
file names or user-chosen ID strings.
Here is how each line in the input script is parsed by LAMMPS:
(1) If the last printable character on the line is a "&" character,
the command is assumed to continue on the next line. The next line is
concatenated to the previous line by removing the "&" character and
line break. This allows long commands to be continued across two or
more lines. See the discussion of triple quotes in (6) for how to
continue a command across multiple line without using "&" characters.
(2) All characters from the first "#" character onward are treated as
comment and discarded. See an exception in (6). Note that a
comment after a trailing "&" character will prevent the command from
continuing on the next line. Also note that for multi-line commands a
single leading "#" will comment out the entire command.
(3) The line is searched repeatedly for $ characters, which indicate
variables that are replaced with a text string. See an exception in
(6).
If the $ is followed by curly brackets, then the variable name is the
text inside the curly brackets. If no curly brackets follow the $,
then the variable name is the single character immediately following
the $. Thus ${myTemp} and $x refer to variable names "myTemp" and
"x".
How the variable is converted to a text string depends on what style
of variable it is; see the `variable <variable>`_ doc page for details.
It can be a variable that stores multiple text strings, and return one
of them. The returned text string can be multiple "words" (space
separated) which will then be interpreted as multiple arguments in the
input command. The variable can also store a numeric formula which
will be evaluated and its numeric result returned as a string.
As a special case, if the $ is followed by parenthesis, then the text
inside the parenthesis is treated as an "immediate" variable and
evaluated as an :doc:`equal-style variable <variable>`. This is a way
to use numeric formulas in an input script without having to assign
them to variable names. For example, these 3 input script lines:
.. parsed-literal::
variable X equal (xlo+xhi)/2+sqrt(v_area)
region 1 block $X 2 INF INF EDGE EDGE
variable X delete
can be replaced by
.. parsed-literal::
region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE
so that you do not have to define (or discard) a temporary variable X.
Note that neither the curly-bracket or immediate form of variables can
contain nested $ characters for other variables to substitute for.
Thus you cannot do this:
.. parsed-literal::
variable a equal 2
variable b2 equal 4
print "B2 = ${b$a}"
Nor can you specify this $($x-1.0) for an immediate variable, but
you could use $(v_x-1.0), since the latter is valid syntax for an
:doc:`equal-style variable <variable>`.
See the :doc:`variable <variable>` command for more details of how
strings are assigned to variables and evaluated, and how they can be
used in input script commands.
(4) The line is broken into "words" separated by whitespace (tabs,
spaces). Note that words can thus contain letters, digits,
underscores, or punctuation characters.
(5) The first word is the command name. All successive words in the
line are arguments.
(6) If you want text with spaces to be treated as a single argument,
it can be enclosed in either single or double or triple quotes. A
long single argument enclosed in single or double quotes can span
multiple lines if the "&" character is used, as described above. When
the lines are concatenated together (and the "&" characters and line
breaks removed), the text will become a single line. If you want
multiple lines of an argument to retain their line breaks, the text
can be enclosed in triple quotes, in which case "&" characters are not
needed. For example:
.. parsed-literal::
print "Volume = $v"
print 'Volume = $v'
if "$*steps* > 1000" then quit
variable a string "red green blue &
purple orange cyan"
print """
System volume = $v
System temperature = $t
"""
In each case, the single, double, or triple quotes are removed when
the single argument they enclose is stored internally.
See the :doc:`dump modify format <dump_modify>`, :doc:`print <print>`,
:doc:`if <if>`, and :doc:`python <python>` commands for examples.
A "#" or "$" character that is between quotes will not be treated as a
comment indicator in (2) or substituted for as a variable in (3).
.. warning::
If the argument is itself a command that requires a
quoted argument (e.g. using a :doc:`print <print>` command as part of an
:doc:`if <if>` or :doc:`run every <run>` command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.
----------
.. _cmd_3:
Input script structure
----------------------------------
This section describes the structure of a typical LAMMPS input script.
The "examples" directory in the LAMMPS distribution contains many
sample input scripts; the corresponding problems are discussed in
:doc:`Section_example <Section_example>`, and animated on the `LAMMPS WWW Site <lws_>`_.
A LAMMPS input script typically has 4 parts:
1. Initialization
2. Atom definition
3. Settings
4. Run a simulation
The last 2 parts can be repeated as many times as desired. I.e. run a
simulation, change some settings, run some more, etc. Each of the 4
parts is now described in more detail. Remember that almost all the
commands need only be used if a non-default value is desired.
(1) Initialization
Set parameters that need to be defined before atoms are created or
read-in from a file.
The relevant commands are :doc:`units <units>`,
:doc:`dimension <dimension>`, :doc:`newton <newton>`,
:doc:`processors <processors>`, :doc:`boundary <boundary>`,
:doc:`atom_style <atom_style>`, :doc:`atom_modify <atom_modify>`.
If force-field parameters appear in the files that will be read, these
commands tell LAMMPS what kinds of force fields are being used:
:doc:`pair_style <pair_style>`, :doc:`bond_style <bond_style>`,
:doc:`angle_style <angle_style>`, :doc:`dihedral_style <dihedral_style>`,
:doc:`improper_style <improper_style>`.
(2) Atom definition
There are 3 ways to define atoms in LAMMPS. Read them in from a data
or restart file via the :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` commands. These files can contain
molecular topology information. Or create atoms on a lattice (with no
molecular topology), using these commands: :doc:`lattice <lattice>`,
:doc:`region <region>`, :doc:`create_box <create_box>`,
:doc:`create_atoms <create_atoms>`. The entire set of atoms can be
duplicated to make a larger simulation using the
:doc:`replicate <replicate>` command.
(3) Settings
Once atoms and molecular topology are defined, a variety of settings
can be specified: force field coefficients, simulation parameters,
output options, etc.
Force field coefficients are set by these commands (they can also be
set in the read-in files): :doc:`pair_coeff <pair_coeff>`,
:doc:`bond_coeff <bond_coeff>`, :doc:`angle_coeff <angle_coeff>`,
:doc:`dihedral_coeff <dihedral_coeff>`,
:doc:`improper_coeff <improper_coeff>`,
:doc:`kspace_style <kspace_style>`, :doc:`dielectric <dielectric>`,
:doc:`special_bonds <special_bonds>`.
Various simulation parameters are set by these commands:
:doc:`neighbor <neighbor>`, :doc:`neigh_modify <neigh_modify>`,
:doc:`group <group>`, :doc:`timestep <timestep>`,
:doc:`reset_timestep <reset_timestep>`, :doc:`run_style <run_style>`,
:doc:`min_style <min_style>`, :doc:`min_modify <min_modify>`.
Fixes impose a variety of boundary conditions, time integration, and
diagnostic options. The :doc:`fix <fix>` command comes in many flavors.
Various computations can be specified for execution during a
simulation using the :doc:`compute <compute>`,
:doc:`compute_modify <compute_modify>`, and :doc:`variable <variable>`
commands.
Output options are set by the :doc:`thermo <thermo>`, :doc:`dump <dump>`,
and :doc:`restart <restart>` commands.
(4) Run a simulation
A molecular dynamics simulation is run using the :doc:`run <run>`
command. Energy minimization (molecular statics) is performed using
the :doc:`minimize <minimize>` command. A parallel tempering
(replica-exchange) simulation can be run using the
:doc:`temper <temper>` command.
----------
.. _cmd_4:
Commands listed by category
---------------------------
This section lists all LAMMPS commands, grouped by category. The
:ref:`next section <cmd_5>` lists the same commands alphabetically. Note
that some style options for some commands are part of specific LAMMPS
packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a
default LAMMPS build. These dependencies are listed as Restrictions
in the command's documentation.
Initialization:
:doc:`atom_modify <atom_modify>`, :doc:`atom_style <atom_style>`,
:doc:`boundary <boundary>`, :doc:`dimension <dimension>`,
:doc:`newton <newton>`, :doc:`processors <processors>`, :doc:`units <units>`
Atom definition:
:doc:`create_atoms <create_atoms>`, :doc:`create_box <create_box>`,
:doc:`lattice <lattice>`, :doc:`read_data <read_data>`,
:doc:`read_dump <read_dump>`, :doc:`read_restart <read_restart>`,
:doc:`region <region>`, :doc:`replicate <replicate>`
Force fields:
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style <angle_style>`,
:doc:`bond_coeff <bond_coeff>`, :doc:`bond_style <bond_style>`,
:doc:`dielectric <dielectric>`, :doc:`dihedral_coeff <dihedral_coeff>`,
:doc:`dihedral_style <dihedral_style>`,
:doc:`improper_coeff <improper_coeff>`,
:doc:`improper_style <improper_style>`,
:doc:`kspace_modify <kspace_modify>`, :doc:`kspace_style <kspace_style>`,
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_modify <pair_modify>`,
:doc:`pair_style <pair_style>`, :doc:`pair_write <pair_write>`,
:doc:`special_bonds <special_bonds>`
Settings:
:doc:`comm_style <comm_style>`, :doc:`group <group>`, :doc:`mass <mass>`,
:doc:`min_modify <min_modify>`, :doc:`min_style <min_style>`,
:doc:`neigh_modify <neigh_modify>`, :doc:`neighbor <neighbor>`,
:doc:`reset_timestep <reset_timestep>`, :doc:`run_style <run_style>`,
:doc:`set <set>`, :doc:`timestep <timestep>`, :doc:`velocity <velocity>`
Fixes:
:doc:`fix <fix>`, :doc:`fix_modify <fix_modify>`, :doc:`unfix <unfix>`
Computes:
:doc:`compute <compute>`, :doc:`compute_modify <compute_modify>`,
:doc:`uncompute <uncompute>`
Output:
:doc:`dump <dump>`, :doc:`dump image <dump_image>`,
:doc:`dump_modify <dump_modify>`, :doc:`dump movie <dump_image>`,
:doc:`restart <restart>`, :doc:`thermo <thermo>`,
:doc:`thermo_modify <thermo_modify>`, :doc:`thermo_style <thermo_style>`,
:doc:`undump <undump>`, :doc:`write_data <write_data>`,
:doc:`write_dump <write_dump>`, :doc:`write_restart <write_restart>`
Actions:
:doc:`delete_atoms <delete_atoms>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`displace_atoms <displace_atoms>`, :doc:`change_box <change_box>`,
:doc:`minimize <minimize>`, :doc:`neb <neb>` :doc:`prd <prd>`,
:doc:`rerun <rerun>`, :doc:`run <run>`, :doc:`temper <temper>`
Miscellaneous:
:doc:`clear <clear>`, :doc:`echo <echo>`, :doc:`if <if>`,
:doc:`include <include>`, :doc:`jump <jump>`, :doc:`label <label>`,
:doc:`log <log>`, :doc:`next <next>`, :doc:`print <print>`,
:doc:`shell <shell>`, :doc:`variable <variable>`
----------
.. _cmd_5:
.. _comm:
Individual commands
------------------------------------------
This section lists all LAMMPS commands alphabetically, with a separate
listing below of styles within certain commands. The :ref:`previous section <cmd_4>` lists the same commands, grouped by category. Note
that some style options for some commands are part of specific LAMMPS
packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a
default LAMMPS build. These dependencies are listed as Restrictions
in the command's documentation.
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`angle_coeff <angle_coeff>` | :doc:`angle_style <angle_style>` | :doc:`atom_modify <atom_modify>` | :doc:`atom_style <atom_style>` | :doc:`balance <balance>` | :doc:`bond_coeff <bond_coeff>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`bond_style <bond_style>` | :doc:`boundary <boundary>` | :doc:`box <box>` | :doc:`change_box <change_box>` | :doc:`clear <clear>` | :doc:`comm_modify <comm_modify>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`comm_style <comm_style>` | :doc:`compute <compute>` | :doc:`compute_modify <compute_modify>` | :doc:`create_atoms <create_atoms>` | :doc:`create_bonds <create_bonds>` | :doc:`create_box <create_box>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`delete_atoms <delete_atoms>` | :doc:`delete_bonds <delete_bonds>` | :doc:`dielectric <dielectric>` | :doc:`dihedral_coeff <dihedral_coeff>` | :doc:`dihedral_style <dihedral_style>` | :doc:`dimension <dimension>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`displace_atoms <displace_atoms>` | :doc:`dump <dump>` | :doc:`dump image <dump_image>` | :doc:`dump_modify <dump_modify>` | :doc:`dump movie <dump_image>` | :doc:`echo <echo>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`fix <fix>` | :doc:`fix_modify <fix_modify>` | :doc:`group <group>` | :doc:`if <if>` | :doc:`info <info>` | :doc:`improper_coeff <improper_coeff>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`improper_style <improper_style>` | :doc:`include <include>` | :doc:`jump <jump>` | :doc:`kspace_modify <kspace_modify>` | :doc:`kspace_style <kspace_style>` | :doc:`label <label>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`lattice <lattice>` | :doc:`log <log>` | :doc:`mass <mass>` | :doc:`minimize <minimize>` | :doc:`min_modify <min_modify>` | :doc:`min_style <min_style>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`molecule <molecule>` | :doc:`neb <neb>` | :doc:`neigh_modify <neigh_modify>` | :doc:`neighbor <neighbor>` | :doc:`newton <newton>` | :doc:`next <next>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`package <package>` | :doc:`pair_coeff <pair_coeff>` | :doc:`pair_modify <pair_modify>` | :doc:`pair_style <pair_style>` | :doc:`pair_write <pair_write>` | :doc:`partition <partition>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`prd <prd>` | :doc:`print <print>` | :doc:`processors <processors>` | :doc:`python <python>` | :doc:`quit <quit>` | :doc:`read_data <read_data>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`read_dump <read_dump>` | :doc:`read_restart <read_restart>` | :doc:`region <region>` | :doc:`replicate <replicate>` | :doc:`rerun <rerun>` | :doc:`reset_timestep <reset_timestep>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`restart <restart>` | :doc:`run <run>` | :doc:`run_style <run_style>` | :doc:`set <set>` | :doc:`shell <shell>` | :doc:`special_bonds <special_bonds>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`suffix <suffix>` | :doc:`tad <tad>` | :doc:`temper <temper>` | :doc:`thermo <thermo>` | :doc:`thermo_modify <thermo_modify>` | :doc:`thermo_style <thermo_style>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`timestep <timestep>` | :doc:`uncompute <uncompute>` | :doc:`undump <undump>` | :doc:`unfix <unfix>` | :doc:`units <units>` | :doc:`variable <variable>` |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
| :doc:`velocity <velocity>` | :doc:`write_data <write_data>` | :doc:`write_dump <write_dump>` | :doc:`write_restart <write_restart>` | | |
+----------------------------------------+------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+----------------------------------------+
These are additional commands in USER packages, which can be used if
:ref:`LAMMPS is built with the appropriate package <start_3>`.
+------------------------------+
| :doc:`group2ndx <group2ndx>` |
+------------------------------+
----------
Fix styles
----------
See the :doc:`fix <fix>` command for one-line descriptions of each style
or click on the style itself for a full description. Some of the
styles have accelerated versions, which can be used if LAMMPS is built
with the :doc:`appropriate accelerated package <Section_accelerate>`.
This is indicated by additional letters in parenthesis: c = USER-CUDA,
g = GPU, i = USER-INTEL, k = KOKKOS, o = USER-OMP, t = OPT.
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`adapt <fix_adapt>` | :doc:`addforce (c) <fix_addforce>` | :doc:`append/atoms <fix_append_atoms>` | :doc:`atom/swap <fix_atom_swap>` | :doc:`aveforce (c) <fix_aveforce>` | :doc:`ave/atom <fix_ave_atom>` | :doc:`ave/chunk <fix_ave_chunk>` | :doc:`ave/correlate <fix_ave_correlate>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`ave/histo <fix_ave_histo>` | :doc:`ave/histo/weight <fix_ave_histo>` | :doc:`ave/spatial <fix_ave_spatial>` | :doc:`ave/time <fix_ave_time>` | :doc:`balance <fix_balance>` | :doc:`bond/break <fix_bond_break>` | :doc:`bond/create <fix_bond_create>` | :doc:`bond/swap <fix_bond_swap>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`box/relax <fix_box_relax>` | :doc:`deform <fix_deform>` | :doc:`deposit <fix_deposit>` | :doc:`drag <fix_drag>` | :doc:`dt/reset <fix_dt_reset>` | :doc:`efield <fix_efield>` | :doc:`enforce2d (c) <fix_enforce2d>` | :doc:`evaporate <fix_evaporate>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`external <fix_external>` | :doc:`freeze (c) <fix_freeze>` | :doc:`gcmc <fix_gcmc>` | :doc:`gld <fix_gld>` | :doc:`gravity (co) <fix_gravity>` | :doc:`heat <fix_heat>` | :doc:`indent <fix_indent>` | :doc:`langevin (k) <fix_langevin>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`lineforce <fix_lineforce>` | :doc:`momentum <fix_momentum>` | :doc:`move <fix_move>` | :doc:`msst <fix_msst>` | :doc:`neb <fix_neb>` | :doc:`nph (o) <fix_nh>` | :doc:`nphug (o) <fix_nphug>` | :doc:`nph/asphere (o) <fix_nph_asphere>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`nph/sphere (o) <fix_nph_sphere>` | :doc:`npt (co) <fix_nh>` | :doc:`npt/asphere (o) <fix_npt_asphere>` | :doc:`npt/sphere (o) <fix_npt_sphere>` | :doc:`nve (cko) <fix_nve>` | :doc:`nve/asphere <fix_nve_asphere>` | :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>` | :doc:`nve/body <fix_nve_body>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`nve/limit <fix_nve_limit>` | :doc:`nve/line <fix_nve_line>` | :doc:`nve/noforce <fix_nve_noforce>` | :doc:`nve/sphere (o) <fix_nve_sphere>` | :doc:`nve/tri <fix_nve_tri>` | :doc:`nvt (co) <fix_nh>` | :doc:`nvt/asphere (o) <fix_nvt_asphere>` | :doc:`nvt/sllod (o) <fix_nvt_sllod>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`nvt/sphere (o) <fix_nvt_sphere>` | :doc:`oneway <fix_oneway>` | :doc:`orient/fcc <fix_orient_fcc>` | :doc:`planeforce <fix_planeforce>` | :doc:`poems <fix_poems>` | :doc:`pour <fix_pour>` | :doc:`press/berendsen <fix_press_berendsen>` | :doc:`print <fix_print>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`property/atom <fix_property_atom>` | :doc:`qeq/comb (o) <fix_qeq_comb>` | :doc:`qeq/dynamic <fix_qeq>` | :doc:`qeq/point <fix_qeq>` | :doc:`qeq/shielded <fix_qeq>` | :doc:`qeq/slater <fix_qeq>` | :doc:`reax/bonds <fix_reax_bonds>` | :doc:`recenter <fix_recenter>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`restrain <fix_restrain>` | :doc:`rigid (o) <fix_rigid>` | :doc:`rigid/nph (o) <fix_rigid>` | :doc:`rigid/npt (o) <fix_rigid>` | :doc:`rigid/nve (o) <fix_rigid>` | :doc:`rigid/nvt (o) <fix_rigid>` | :doc:`rigid/small (o) <fix_rigid>` | :doc:`rigid/small/nph <fix_rigid>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`rigid/small/npt <fix_rigid>` | :doc:`rigid/small/nve <fix_rigid>` | :doc:`rigid/small/nvt <fix_rigid>` | :doc:`setforce (c) <fix_setforce>` | :doc:`shake (c) <fix_shake>` | :doc:`spring <fix_spring>` | :doc:`spring/rg <fix_spring_rg>` | :doc:`spring/self <fix_spring_self>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`srd <fix_srd>` | :doc:`store/force <fix_store_force>` | :doc:`store/state <fix_store_state>` | :doc:`temp/berendsen (c) <fix_temp_berendsen>` | :doc:`temp/csld <fix_temp_csvr>` | :doc:`temp/csvr <fix_temp_csvr>` | :doc:`temp/rescale (c) <fix_temp_rescale>` | :doc:`tfmc <fix_tfmc>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`thermal/conductivity <fix_thermal_conductivity>` | :doc:`tmd <fix_tmd>` | :doc:`ttm <fix_ttm>` | :doc:`tune/kspace <fix_tune_kspace>` | :doc:`vector <fix_vector>` | :doc:`viscosity <fix_viscosity>` | :doc:`viscous (c) <fix_viscous>` | :doc:`wall/colloid <fix_wall>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`wall/gran <fix_wall_gran>` | :doc:`wall/harmonic <fix_wall>` | :doc:`wall/lj1043 <fix_wall>` | :doc:`wall/lj126 <fix_wall>` | :doc:`wall/lj93 <fix_wall>` | :doc:`wall/piston <fix_wall_piston>` | :doc:`wall/reflect <fix_wall_reflect>` | :doc:`wall/region <fix_wall_region>` |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
| :doc:`wall/srd <fix_wall_srd>` | | | | | | | |
+--------------------------------------------------------+-----------------------------------------+------------------------------------------+------------------------------------------------+------------------------------------+--------------------------------------+------------------------------------------------------+------------------------------------------+
These are additional fix styles in USER packages, which can be used if
:ref:`LAMMPS is built with the appropriate package <start_3>`.
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`adapt/fep <fix_adapt_fep>` | :doc:`addtorque <fix_addtorque>` | :doc:`atc <fix_atc>` | :doc:`ave/spatial/sphere <fix_ave_spatial_sphere>` | :doc:`drude <fix_drude>` | :doc:`drude/transform/direct <fix_drude_transform>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`drude/transform/reverse <fix_drude_transform>` | :doc:`colvars <fix_colvars>` | :doc:`gle <fix_gle>` | :doc:`imd <fix_imd>` | :doc:`ipi <fix_ipi>` | :doc:`langevin/drude <fix_langevin_drude>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`langevin/eff <fix_langevin_eff>` | :doc:`lb/fluid <fix_lb_fluid>` | :doc:`lb/momentum <fix_lb_momentum>` | :doc:`lb/pc <fix_lb_pc>` | :doc:`lb/rigid/pc/sphere <fix_lb_rigid_pc_sphere>` | :doc:`lb/viscous <fix_lb_viscous>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`meso <fix_meso>` | :doc:`meso/stationary <fix_meso_stationary>` | :doc:`nph/eff <fix_nh_eff>` | :doc:`npt/eff <fix_nh_eff>` | :doc:`nve/eff <fix_nve_eff>` | :doc:`nvt/eff <fix_nh_eff>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`nvt/sllod/eff <fix_nvt_sllod_eff>` | :doc:`phonon <fix_phonon>` | :doc:`pimd <fix_pimd>` | :doc:`qbmsst <fix_qbmsst>` | :doc:`qeq/reax <fix_qeq_reax>` | :doc:`qmmm <fix_qmmm>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`qtb <fix_qtb>` | :doc:`reax/c/bonds <fix_reax_bonds>` | :doc:`reax/c/species <fix_reaxc_species>` | :doc:`saed/vtk <fix_saed_vtk>` | :doc:`smd <fix_smd>` | :doc:`temp/rescale/eff <fix_temp_rescale_eff>` |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
| :doc:`ti/rs <fix_ti_rs>` | :doc:`ti/spring <fix_ti_spring>` | :doc:`ttm/mod <fix_ttm>` | | | |
+------------------------------------------------------+----------------------------------------------+-------------------------------------------+----------------------------------------------------+----------------------------------------------------+-----------------------------------------------------+
----------
Compute styles
--------------
See the :doc:`compute <compute>` command for one-line descriptions of
each style or click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`angle/local <compute_angle_local>` | :doc:`angmom/chunk <compute_angmom_chunk>` | :doc:`body/local <compute_body_local>` | :doc:`bond/local <compute_bond_local>` | :doc:`centro/atom <compute_centro_atom>` | :doc:`chunk/atom <compute_chunk_atom>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`cluster/atom <compute_cluster_atom>` | :doc:`cna/atom <compute_cna_atom>` | :doc:`com <compute_com>` | :doc:`com/chunk <compute_com_chunk>` | :doc:`contact/atom <compute_contact_atom>` | :doc:`coord/atom <compute_coord_atom>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`damage/atom <compute_damage_atom>` | :doc:`dihedral/local <compute_dihedral_local>` | :doc:`dilatation/atom <compute_dilatation_atom>` | :doc:`displace/atom <compute_displace_atom>` | :doc:`erotate/asphere <compute_erotate_asphere>` | :doc:`erotate/rigid <compute_erotate_rigid>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`erotate/sphere <compute_erotate_sphere>` | :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>` | :doc:`event/displace <compute_event_displace>` | :doc:`group/group <compute_group_group>` | :doc:`gyration <compute_gyration>` | :doc:`gyration/chunk <compute_gyration_chunk>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`heat/flux <compute_heat_flux>` | :doc:`improper/local <compute_improper_local>` | :doc:`inertia/chunk <compute_inertia_chunk>` | :doc:`ke <compute_ke>` | :doc:`ke/atom <compute_ke_atom>` | :doc:`ke/rigid <compute_ke_rigid>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`msd <compute_msd>` | :doc:`msd/chunk <compute_msd_chunk>` | :doc:`msd/nongauss <compute_msd_nongauss>` | :doc:`omega/chunk <compute_omega_chunk>` | :doc:`pair <compute_pair>` | :doc:`pair/local <compute_pair_local>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`pe (c) <compute_pe>` | :doc:`pe/atom <compute_pe_atom>` | :doc:`plasticity/atom <compute_plasticity_atom>` | :doc:`pressure (c) <compute_pressure>` | :doc:`property/atom <compute_property_atom>` | :doc:`property/local <compute_property_local>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`property/chunk <compute_property_chunk>` | :doc:`rdf <compute_rdf>` | :doc:`reduce <compute_reduce>` | :doc:`reduce/region <compute_reduce>` | :doc:`slice <compute_slice>` | :doc:`sna/atom <compute_sna>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`snad/atom <compute_sna>` | :doc:`snav/atom <compute_sna>` | :doc:`stress/atom <compute_stress_atom>` | :doc:`temp (c) <compute_temp>` | :doc:`temp/asphere <compute_temp_asphere>` | :doc:`temp/com <compute_temp_com>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`temp/chunk <compute_temp_chunk>` | :doc:`temp/deform <compute_temp_deform>` | :doc:`temp/partial (c) <compute_temp_partial>` | :doc:`temp/profile <compute_temp_profile>` | :doc:`temp/ramp <compute_temp_ramp>` | :doc:`temp/region <compute_temp_region>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
| :doc:`temp/sphere <compute_temp_sphere>` | :doc:`ti <compute_ti>` | :doc:`torque/chunk <compute_torque_chunk>` | :doc:`vacf <compute_vacf>` | :doc:`vcm/chunk <compute_vcm_chunk>` | :doc:`voronoi/atom <compute_voronoi_atom>` |
+------------------------------------------------+----------------------------------------------------------+--------------------------------------------------+----------------------------------------------+--------------------------------------------------+------------------------------------------------+
These are additional compute styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+--------------------------------------------------+------------------------------------------+----------------------------+----------------------------------------+------------------------------------------+--------------------------------------------------+
| :doc:`ackland/atom <compute_ackland_atom>` | :doc:`basal/atom <compute_basal_atom>` | :doc:`fep <compute_fep>` | :doc:`ke/eff <compute_ke_eff>` | :doc:`ke/atom/eff <compute_ke_atom_eff>` | :doc:`meso_e/atom <compute_meso_e_atom>` |
+--------------------------------------------------+------------------------------------------+----------------------------+----------------------------------------+------------------------------------------+--------------------------------------------------+
| :doc:`meso_rho/atom <compute_meso_rho_atom>` | :doc:`meso_t/atom <compute_meso_t_atom>` | :doc:`saed <compute_saed>` | :doc:`temp/drude <compute_temp_drude>` | :doc:`temp/eff <compute_temp_eff>` | :doc:`temp/deform/eff <compute_temp_deform_eff>` |
+--------------------------------------------------+------------------------------------------+----------------------------+----------------------------------------+------------------------------------------+--------------------------------------------------+
| :doc:`temp/region/eff <compute_temp_region_eff>` | :doc:`temp/rotate <compute_temp_rotate>` | :doc:`xrd <compute_xrd>` | | | |
+--------------------------------------------------+------------------------------------------+----------------------------+----------------------------------------+------------------------------------------+--------------------------------------------------+
----------
Pair_style potentials
---------------------
See the :doc:`pair_style <pair_style>` command for an overview of pair
potentials. Click on the style itself for a full description. Many
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`none <pair_none>` | :doc:`hybrid <pair_hybrid>` | :doc:`hybrid/overlay <pair_hybrid>` | :doc:`adp (o) <pair_adp>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`airebo (o) <pair_airebo>` | :doc:`beck (go) <pair_beck>` | :doc:`body <pair_body>` | :doc:`bop <pair_bop>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`born (go) <pair_born>` | :doc:`born/coul/long (cgo) <pair_born>` | :doc:`born/coul/long/cs <pair_born>` | :doc:`born/coul/msm (o) <pair_born>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`born/coul/wolf (go) <pair_born>` | :doc:`brownian (o) <pair_brownian>` | :doc:`brownian/poly (o) <pair_brownian>` | :doc:`buck (cgko) <pair_buck>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`buck/coul/cut (cgko) <pair_buck>` | :doc:`buck/coul/long (cgko) <pair_buck>` | :doc:`buck/coul/long/cs <pair_buck>` | :doc:`buck/coul/msm (o) <pair_buck>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`buck/long/coul/long (o) <pair_buck_long>` | :doc:`colloid (go) <pair_colloid>` | :doc:`comb (o) <pair_comb>` | :doc:`comb3 <pair_comb>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`coul/cut (gko) <pair_coul>` | :doc:`coul/debye (gko) <pair_coul>` | :doc:`coul/dsf (gko) <pair_coul>` | :doc:`coul/long (gko) <pair_coul>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`coul/long/cs <pair_coul>` | :doc:`coul/msm <pair_coul>` | :doc:`coul/streitz <pair_coul>` | :doc:`coul/wolf (ko) <pair_coul>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`dpd (o) <pair_dpd>` | :doc:`dpd/tstat (o) <pair_dpd>` | :doc:`dsmc <pair_dsmc>` | :doc:`eam (cgkot) <pair_eam>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`eam/alloy (cgkot) <pair_eam>` | :doc:`eam/fs (cgkot) <pair_eam>` | :doc:`eim (o) <pair_eim>` | :doc:`gauss (go) <pair_gauss>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`gayberne (gio) <pair_gayberne>` | :doc:`gran/hertz/history (o) <pair_gran>` | :doc:`gran/hooke (co) <pair_gran>` | :doc:`gran/hooke/history (o) <pair_gran>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>` | :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>` | :doc:`kim <pair_kim>` | :doc:`lcbop <pair_lcbop>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`line/lj (o) <pair_line_lj>` | :doc:`lj/charmm/coul/charmm (cko) <pair_charmm>` | :doc:`lj/charmm/coul/charmm/implicit (cko) <pair_charmm>` | :doc:`lj/charmm/coul/long (cgiko) <pair_charmm>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/charmm/coul/msm <pair_charmm>` | :doc:`lj/class2 (cgko) <pair_class2>` | :doc:`lj/class2/coul/cut (cko) <pair_class2>` | :doc:`lj/class2/coul/long (cgko) <pair_class2>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/cut (cgikot) <pair_lj>` | :doc:`lj/cut/coul/cut (cgko) <pair_lj>` | :doc:`lj/cut/coul/debye (cgko) <pair_lj>` | :doc:`lj/cut/coul/dsf (gko) <pair_lj>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/cut/coul/long (cgikot) <pair_lj>` | :doc:`lj/cut/coul/msm (go) <pair_lj>` | :doc:`lj/cut/dipole/cut (go) <pair_dipole>` | :doc:`lj/cut/dipole/long <pair_dipole>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/cut/tip4p/cut (o) <pair_lj>` | :doc:`lj/cut/tip4p/long (ot) <pair_lj>` | :doc:`lj/expand (cgko) <pair_lj_expand>` | :doc:`lj/gromacs (cgko) <pair_gromacs>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/gromacs/coul/gromacs (cko) <pair_gromacs>` | :doc:`lj/long/coul/long (o) <pair_lj_long>` | :doc:`lj/long/dipole/long <pair_dipole>` | :doc:`lj/long/tip4p/long <pair_lj_long>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lj/smooth (co) <pair_lj_smooth>` | :doc:`lj/smooth/linear (o) <pair_lj_smooth_linear>` | :doc:`lj96/cut (cgo) <pair_lj96>` | :doc:`lubricate (o) <pair_lubricate>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`lubricate/poly (o) <pair_lubricate>` | :doc:`lubricateU <pair_lubricateU>` | :doc:`lubricateU/poly <pair_lubricateU>` | :doc:`meam (o) <pair_meam>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`mie/cut (o) <pair_mie>` | :doc:`morse (cgot) <pair_morse>` | :doc:`nb3b/harmonic (o) <pair_nb3b_harmonic>` | :doc:`nm/cut (o) <pair_nm>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`nm/cut/coul/cut (o) <pair_nm>` | :doc:`nm/cut/coul/long (o) <pair_nm>` | :doc:`peri/eps <pair_peri>` | :doc:`peri/lps (o) <pair_peri>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`peri/pmb (o) <pair_peri>` | :doc:`peri/ves <pair_peri>` | :doc:`polymorphic <pair_polymorphic>` | :doc:`reax <pair_reax>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`rebo (o) <pair_airebo>` | :doc:`resquared (go) <pair_resquared>` | :doc:`snap <pair_snap>` | :doc:`soft (go) <pair_soft>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`sw (cgkio) <pair_sw>` | :doc:`table (gko) <pair_table>` | :doc:`tersoff (cko) <pair_tersoff>` | :doc:`tersoff/mod (ko) <pair_tersoff_mod>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`tersoff/zbl (ko) <pair_tersoff_zbl>` | :doc:`tip4p/cut (o) <pair_coul>` | :doc:`tip4p/long (o) <pair_coul>` | :doc:`tri/lj (o) <pair_tri_lj>` |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
| :doc:`yukawa (go) <pair_yukawa>` | :doc:`yukawa/colloid (go) <pair_yukawa_colloid>` | :doc:`zbl (o) <pair_zbl>` | |
+-----------------------------------------------------+-------------------------------------------------------+-----------------------------------------------------------+--------------------------------------------------+
These are additional pair styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`awpmd/cut <pair_awpmd>` | :doc:`coul/cut/soft (o) <pair_lj_soft>` | :doc:`coul/diel (o) <pair_coul_diel>` | :doc:`coul/long/soft (o) <pair_lj_soft>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`eam/cd (o) <pair_eam>` | :doc:`edip (o) <pair_edip>` | :doc:`eff/cut <pair_eff>` | :doc:`gauss/cut <pair_gauss>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`list <pair_list>` | :doc:`lj/charmm/coul/long/soft (o) <pair_charmm>` | :doc:`lj/cut/coul/cut/soft (o) <pair_lj_soft>` | :doc:`lj/cut/coul/long/soft (o) <pair_lj_soft>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/cut/dipole/sf (go) <pair_dipole>` | :doc:`lj/cut/soft (o) <pair_lj_soft>` | :doc:`lj/cut/tip4p/long/soft (o) <pair_lj_soft>` | :doc:`lj/sdk (gko) <pair_sdk>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`lj/sdk/coul/long (go) <pair_sdk>` | :doc:`lj/sdk/coul/msm (o) <pair_sdk>` | :doc:`lj/sf (o) <pair_lj_sf>` | :doc:`meam/spline <pair_meam_spline>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`meam/sw/spline <pair_meam_sw_spline>` | :doc:`quip <pair_quip>` | :doc:`reax/c <pair_reax_c>` | :doc:`sph/heatconduction <pair_sph_heatconduction>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`sph/idealgas <pair_sph_idealgas>` | :doc:`sph/lj <pair_sph_lj>` | :doc:`sph/rhosum <pair_sph_rhosum>` | :doc:`sph/taitwater <pair_sph_taitwater>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`sph/taitwater/morris <pair_sph_taitwater_morris>` | :doc:`srp <pair_srp>` | :doc:`tersoff/table (o) <pair_tersoff>` | :doc:`thole <pair_thole>` |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
| :doc:`tip4p/long/soft (o) <pair_lj_soft>` | | | |
+---------------------------------------------------------+---------------------------------------------------+--------------------------------------------------+-----------------------------------------------------+
----------
Bond_style potentials
---------------------
See the :doc:`bond_style <bond_style>` command for an overview of bond
potentials. Click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`none <bond_none>` | :doc:`hybrid <bond_hybrid>` | :doc:`class2 (o) <bond_class2>` | :doc:`fene (ko) <bond_fene>` |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`fene/expand (o) <bond_fene_expand>` | :doc:`harmonic (ko) <bond_harmonic>` | :doc:`morse (o) <bond_morse>` | :doc:`nonlinear (o) <bond_nonlinear>` |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
| :doc:`quartic (o) <bond_quartic>` | :doc:`table (o) <bond_table>` | | |
+-------------------------------------------+--------------------------------------+---------------------------------+---------------------------------------+
These are additional bond styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+-------------------------------------------------+---------------------------------------------------------+
| :doc:`harmonic/shift (o) <bond_harmonic_shift>` | :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>` |
+-------------------------------------------------+---------------------------------------------------------+
----------
Angle_style potentials
----------------------
See the :doc:`angle_style <angle_style>` command for an overview of
angle potentials. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`none <angle_none>` | :doc:`hybrid <angle_hybrid>` | :doc:`charmm (ko) <angle_charmm>` | :doc:`class2 (o) <angle_class2>` |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`cosine (o) <angle_cosine>` | :doc:`cosine/delta (o) <angle_cosine_delta>` | :doc:`cosine/periodic (o) <angle_cosine_periodic>` | :doc:`cosine/squared (o) <angle_cosine_squared>` |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
| :doc:`harmonic (ko) <angle_harmonic>` | :doc:`table (o) <angle_table>` | | |
+---------------------------------------+----------------------------------------------+----------------------------------------------------+--------------------------------------------------+
These are additional angle styles in USER packages, which can be used
if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
| :doc:`cosine/shift (o) <angle_cosine_shift>` | :doc:`cosine/shift/exp (o) <angle_cosine_shift_exp>` | :doc:`dipole (o) <angle_dipole>` | :doc:`fourier (o) <angle_fourier>` |
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
| :doc:`fourier/simple (o) <angle_fourier_simple>` | :doc:`quartic (o) <angle_quartic>` | :doc:`sdk <angle_sdk>` | |
+--------------------------------------------------+------------------------------------------------------+----------------------------------+------------------------------------+
----------
Dihedral_style potentials
-------------------------
See the :doc:`dihedral_style <dihedral_style>` command for an overview
of dihedral potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
| :doc:`none <dihedral_none>` | :doc:`hybrid <dihedral_hybrid>` | :doc:`charmm (ko) <dihedral_charmm>` | :doc:`class2 (o) <dihedral_class2>` |
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
| :doc:`harmonic (o) <dihedral_harmonic>` | :doc:`helix (o) <dihedral_helix>` | :doc:`multi/harmonic (o) <dihedral_multi_harmonic>` | :doc:`opls (ko) <dihedral_opls>` |
+-----------------------------------------+-----------------------------------+-----------------------------------------------------+-------------------------------------+
These are additional dihedral styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
| :doc:`cosine/shift/exp (o) <dihedral_cosine_shift_exp>` | :doc:`fourier (o) <dihedral_fourier>` | :doc:`nharmonic (o) <dihedral_nharmonic>` | :doc:`quadratic (o) <dihedral_quadratic>` |
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
| :doc:`table (o) <dihedral_table>` | | | |
+---------------------------------------------------------+---------------------------------------+-------------------------------------------+-------------------------------------------+
----------
Improper_style potentials
-------------------------
See the :doc:`improper_style <improper_style>` command for an overview
of improper potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
| :doc:`none <improper_none>` | :doc:`hybrid <improper_hybrid>` | :doc:`class2 (o) <improper_class2>` | :doc:`cvff (o) <improper_cvff>` |
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
| :doc:`harmonic (ko) <improper_harmonic>` | :doc:`umbrella (o) <improper_umbrella>` | | |
+------------------------------------------+-----------------------------------------+-------------------------------------+---------------------------------+
These are additional improper styles in USER packages, which can be
used if :ref:`LAMMPS is built with the appropriate package <start_3>`.
+-----------------------------------+---------------------------------------+---------------------------------+
| :doc:`cossq (o) <improper_cossq>` | :doc:`fourier (o) <improper_fourier>` | :doc:`ring (o) <improper_ring>` |
+-----------------------------------+---------------------------------------+---------------------------------+
----------
Kspace solvers
--------------
See the :doc:`kspace_style <kspace_style>` command for an overview of
Kspace solvers. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the :doc:`appropriate accelerated package <Section_accelerate>`. This is indicated by additional
letters in parenthesis: c = USER-CUDA, g = GPU, i = USER-INTEL, k =
KOKKOS, o = USER-OMP, t = OPT.
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
| :doc:`ewald (o) <kspace_style>` | :doc:`ewald/disp <kspace_style>` | :doc:`msm (o) <kspace_style>` | :doc:`msm/cg (o) <kspace_style>` |
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
| :doc:`pppm (cgo) <kspace_style>` | :doc:`pppm/cg (o) <kspace_style>` | :doc:`pppm/disp <kspace_style>` | :doc:`pppm/disp/tip4p <kspace_style>` |
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
| :doc:`pppm/tip4p (o) <kspace_style>` | | | |
+--------------------------------------+-----------------------------------+---------------------------------+---------------------------------------+
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

8692
doc/_sources/Section_errors.txt
View File

File diff suppressed because it is too large Load Diff

164
doc/_sources/Section_example.txt
View File

@ -1,164 +0,0 @@
Example problems
================
The LAMMPS distribution includes an examples sub-directory with
several sample problems. Each problem is in a sub-directory of its
own. Most are 2d models so that they run quickly, requiring at most a
couple of minutes to run on a desktop machine. Each problem has an
input script (in.*) and produces a log file (log.*) and dump file
(dump.*) when it runs. Some use a data file (data.*) of initial
coordinates as additional input. A few sample log file outputs on
different machines and different numbers of processors are included in
the directories to compare your answers to. E.g. a log file like
log.crack.foo.P means it ran on P processors of machine "foo".
For examples that use input data files, many of them were produced by
`Pizza.py <http://pizza.sandia.gov>`_ or setup tools described in the
:doc:`Additional Tools <Section_tools>` section of the LAMMPS
documentation and provided with the LAMMPS distribution.
If you uncomment the :doc:`dump <dump>` command in the input script, a
text dump file will be produced, which can be animated by various
`visualization programs <http://lammps.sandia.gov/viz.html>`_. It can
also be animated using the xmovie tool described in the :doc:`Additional Tools <Section_tools>` section of the LAMMPS documentation.
If you uncomment the :doc:`dump image <dump>` command in the input
script, and assuming you have built LAMMPS with a JPG library, JPG
snapshot images will be produced when the simulation runs. They can
be quickly post-processed into a movie using commands described on the
:doc:`dump image <dump_image>` doc page.
Animations of many of these examples can be viewed on the Movies
section of the `LAMMPS WWW Site <lws_>`_.
These are the sample problems in the examples sub-directories:
+-------------+----------------------------------------------------------------------------+
| balance | dynamic load balancing, 2d system |
+-------------+----------------------------------------------------------------------------+
| body | body particles, 2d system |
+-------------+----------------------------------------------------------------------------+
| colloid | big colloid particles in a small particle solvent, 2d system |
+-------------+----------------------------------------------------------------------------+
| comb | models using the COMB potential |
+-------------+----------------------------------------------------------------------------+
| crack | crack propagation in a 2d solid |
+-------------+----------------------------------------------------------------------------+
| cuda | use of the USER-CUDA package for GPU acceleration |
+-------------+----------------------------------------------------------------------------+
| dipole | point dipolar particles, 2d system |
+-------------+----------------------------------------------------------------------------+
| dreiding | methanol via Dreiding FF |
+-------------+----------------------------------------------------------------------------+
| eim | NaCl using the EIM potential |
+-------------+----------------------------------------------------------------------------+
| ellipse | ellipsoidal particles in spherical solvent, 2d system |
+-------------+----------------------------------------------------------------------------+
| flow | Couette and Poiseuille flow in a 2d channel |
+-------------+----------------------------------------------------------------------------+
| friction | frictional contact of spherical asperities between 2d surfaces |
+-------------+----------------------------------------------------------------------------+
| gpu | use of the GPU package for GPU acceleration |
+-------------+----------------------------------------------------------------------------+
| hugoniostat | Hugoniostat shock dynamics |
+-------------+----------------------------------------------------------------------------+
| indent | spherical indenter into a 2d solid |
+-------------+----------------------------------------------------------------------------+
| intel | use of the USER-INTEL package for CPU or Intel(R) Xeon Phi(TM) coprocessor |
+-------------+----------------------------------------------------------------------------+
| kim | use of potentials in Knowledge Base for Interatomic Models (KIM) |
+-------------+----------------------------------------------------------------------------+
| line | line segment particles in 2d rigid bodies |
+-------------+----------------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |
+-------------+----------------------------------------------------------------------------+
| melt | rapid melt of 3d LJ system |
+-------------+----------------------------------------------------------------------------+
| micelle | self-assembly of small lipid-like molecules into 2d bilayers |
+-------------+----------------------------------------------------------------------------+
| min | energy minimization of 2d LJ melt |
+-------------+----------------------------------------------------------------------------+
| msst | MSST shock dynamics |
+-------------+----------------------------------------------------------------------------+
| nb3b | use of nonbonded 3-body harmonic pair style |
+-------------+----------------------------------------------------------------------------+
| neb | nudged elastic band (NEB) calculation for barrier finding |
+-------------+----------------------------------------------------------------------------+
| nemd | non-equilibrium MD of 2d sheared system |
+-------------+----------------------------------------------------------------------------+
| obstacle | flow around two voids in a 2d channel |
+-------------+----------------------------------------------------------------------------+
| peptide | dynamics of a small solvated peptide chain (5-mer) |
+-------------+----------------------------------------------------------------------------+
| peri | Peridynamic model of cylinder impacted by indenter |
+-------------+----------------------------------------------------------------------------+
| pour | pouring of granular particles into a 3d box, then chute flow |
+-------------+----------------------------------------------------------------------------+
| prd | parallel replica dynamics of vacancy diffusion in bulk Si |
+-------------+----------------------------------------------------------------------------+
| qeq | use of the QEQ pacakge for charge equilibration |
+-------------+----------------------------------------------------------------------------+
| reax | RDX and TATB models using the ReaxFF |
+-------------+----------------------------------------------------------------------------+
| rigid | rigid bodies modeled as independent or coupled |
+-------------+----------------------------------------------------------------------------+
| shear | sideways shear applied to 2d solid, with and without a void |
+-------------+----------------------------------------------------------------------------+
| snap | NVE dynamics for BCC tantalum crystal using SNAP potential |
+-------------+----------------------------------------------------------------------------+
| srd | stochastic rotation dynamics (SRD) particles as solvent |
+-------------+----------------------------------------------------------------------------+
| tad | temperature-accelerated dynamics of vacancy diffusion in bulk Si |
+-------------+----------------------------------------------------------------------------+
| tri | triangular particles in rigid bodies |
+-------------+----------------------------------------------------------------------------+
Here is how you might run and visualize one of the sample problems:
.. parsed-literal::
cd indent
cp ../../src/lmp_linux . # copy LAMMPS executable to this dir
lmp_linux < in.indent # run the problem
Running the simulation produces the files *dump.indent* and
*log.lammps*. You can visualize the dump file as follows:
.. parsed-literal::
../../tools/xmovie/xmovie -scale dump.indent
If you uncomment the :doc:`dump image <dump_image>` line(s) in the input
script a series of JPG images will be produced by the run. These can
be viewed individually or turned into a movie or animated by tools
like ImageMagick or QuickTime or various Windows-based tools. See the
:doc:`dump image <dump_image>` doc page for more details. E.g. this
Imagemagick command would create a GIF file suitable for viewing in a
browser.
.. parsed-literal::
% convert -loop 1 *.jpg foo.gif
----------
There is also a COUPLE directory with examples of how to use LAMMPS as
a library, either by itself or in tandem with another code or library.
See the COUPLE/README file to get started.
There is also an ELASTIC directory with an example script for
computing elastic constants, using a zero temperature Si example. See
the in.elastic file for more info.
There is also a USER directory which contains subdirectories of
user-provided examples for user packages. See the README files in
those directories for more info. See the
:doc:`Section_start.html <Section_start>` file for more info about user
packages.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

127
doc/_sources/Section_history.txt
View File

@ -1,127 +0,0 @@
Future and history
==================
This section lists features we plan to add to LAMMPS, features of
previous versions of LAMMPS, and features of other parallel molecular
dynamics codes our group has distributed.
| 13.1 :ref:`Coming attractions <hist_1>`
| 13.2 :ref:`Past versions <hist_2>`
|
.. _hist_1:
Coming attractions
-------------------------------
The `Wish list link <http://lammps.sandia.gov/future.html>`_ on the
LAMMPS WWW page gives a list of features we are hoping to add to
LAMMPS in the future, including contact names of individuals you can
email if you are interested in contributing to the developement or
would be a future user of that feature.
You can also send `email to the developers <http://lammps.sandia.gov/authors.html>`_ if you want to add
your wish to the list.
----------
.. _hist_2:
Past versions
--------------------------
LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)
and 3 companies (Cray, Bristol Myers Squibb, and Dupont). The goal was
to develop a large-scale parallel classical MD code; the coding effort
was led by Steve Plimpton at Sandia.
After the CRADA ended, a final F77 version, LAMMPS 99, was
released. As development of LAMMPS continued at Sandia, its memory
management was converted to F90; a final F90 version was released as
LAMMPS 2001.
The current LAMMPS is a rewrite in C++ and was first publicly released
as an open source code in 2004. It includes many new features beyond
those in LAMMPS 99 or 2001. It also includes features from older
parallel MD codes written at Sandia, namely ParaDyn, Warp, and
GranFlow (see below).
In late 2006 we began merging new capabilities into LAMMPS that were
developed by Aidan Thompson at Sandia for his MD code GRASP, which has
a parallel framework similar to LAMMPS. Most notably, these have
included many-body potentials - Stillinger-Weber, Tersoff, ReaxFF -
and the associated charge-equilibration routines needed for ReaxFF.
The `History link <http://lammps.sandia.gov/history.html>`_ on the
LAMMPS WWW page gives a timeline of features added to the
C++ open-source version of LAMMPS over the last several years.
These older codes are available for download from the `LAMMPS WWW site <lws_>`_, except for Warp & GranFlow which were primarily used
internally. A brief listing of their features is given here.
LAMMPS 2001
* F90 + MPI
* dynamic memory
* spatial-decomposition parallelism
* NVE, NVT, NPT, NPH, rRESPA integrators
* LJ and Coulombic pairwise force fields
* all-atom, united-atom, bead-spring polymer force fields
* CHARMM-compatible force fields
* class 2 force fields
* 3d/2d Ewald & PPPM
* various force and temperature constraints
* SHAKE
* Hessian-free truncated-Newton minimizer
* user-defined diagnostics
LAMMPS 99
* F77 + MPI
* static memory allocation
* spatial-decomposition parallelism
* most of the LAMMPS 2001 features with a few exceptions
* no 2d Ewald & PPPM
* molecular force fields are missing a few CHARMM terms
* no SHAKE
Warp
* F90 + MPI
* spatial-decomposition parallelism
* embedded atom method (EAM) metal potentials + LJ
* lattice and grain-boundary atom creation
* NVE, NVT integrators
* boundary conditions for applying shear stresses
* temperature controls for actively sheared systems
* per-atom energy and centro-symmetry computation and output
ParaDyn
* F77 + MPI
* atom- and force-decomposition parallelism
* embedded atom method (EAM) metal potentials
* lattice atom creation
* NVE, NVT, NPT integrators
* all serial DYNAMO features for controls and constraints
GranFlow
* F90 + MPI
* spatial-decomposition parallelism
* frictional granular potentials
* NVE integrator
* boundary conditions for granular flow and packing and walls
* particle insertion
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

3065
doc/_sources/Section_howto.txt
View File

File diff suppressed because it is too large Load Diff

593
doc/_sources/Section_intro.txt
View File

@ -1,593 +0,0 @@
Introduction
============
This section provides an overview of what LAMMPS can and can't do,
describes what it means for LAMMPS to be an open-source code, and
acknowledges the funding and people who have contributed to LAMMPS
over the years.
| 1.1 :ref:`What is LAMMPS <intro_1>`
| 1.2 :ref:`LAMMPS features <intro_2>`
| 1.3 :ref:`LAMMPS non-features <intro_3>`
| 1.4 :ref:`Open source distribution <intro_4>`
| 1.5 :ref:`Acknowledgments and citations <intro_5>`
|
.. _intro_1:
What is LAMMPS
--------------
LAMMPS is a classical molecular dynamics code that models an ensemble
of particles in a liquid, solid, or gaseous state. It can model
atomic, polymeric, biological, metallic, granular, and coarse-grained
systems using a variety of force fields and boundary conditions.
For examples of LAMMPS simulations, see the Publications page of the
`LAMMPS WWW Site <lws_>`_.
LAMMPS runs efficiently on single-processor desktop or laptop
machines, but is designed for parallel computers. It will run on any
parallel machine that compiles C++ and supports the `MPI <mpi_>`_
message-passing library. This includes distributed- or shared-memory
parallel machines and Beowulf-style clusters.
.. _mpi: http://www-unix.mcs.anl.gov/mpi
LAMMPS can model systems with only a few particles up to millions or
billions. See :doc:`Section_perf <Section_perf>` for information on
LAMMPS performance and scalability, or the Benchmarks section of the
`LAMMPS WWW Site <lws_>`_.
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License <gnu_>`_, which means you can use or
modify the code however you wish. See :ref:`this section <intro_4>` for a
brief discussion of the open-source philosophy.
.. _gnu: http://www.gnu.org/copyleft/gpl.html
LAMMPS is designed to be easy to modify or extend with new
capabilities, such as new force fields, atom types, boundary
conditions, or diagnostics. See :doc:`Section_modify <Section_modify>`
for more details.
The current version of LAMMPS is written in C++. Earlier versions
were written in F77 and F90. See
:doc:`Section_history <Section_history>` for more information on
different versions. All versions can be downloaded from the `LAMMPS WWW Site <lws_>`_.
LAMMPS was originally developed under a US Department of Energy CRADA
(Cooperative Research and Development Agreement) between two DOE labs
and 3 companies. It is distributed by `Sandia National Labs <snl_>`_.
See :ref:`this section <intro_5>` for more information on LAMMPS funding and
individuals who have contributed to LAMMPS.
.. _snl: http://www.sandia.gov
In the most general sense, LAMMPS integrates Newton's equations of
motion for collections of atoms, molecules, or macroscopic particles
that interact via short- or long-range forces with a variety of
initial and/or boundary conditions. For computational efficiency
LAMMPS uses neighbor lists to keep track of nearby particles. The
lists are optimized for systems with particles that are repulsive at
short distances, so that the local density of particles never becomes
too large. On parallel machines, LAMMPS uses spatial-decomposition
techniques to partition the simulation domain into small 3d
sub-domains, one of which is assigned to each processor. Processors
communicate and store "ghost" atom information for atoms that border
their sub-domain. LAMMPS is most efficient (in a parallel sense) for
systems whose particles fill a 3d rectangular box with roughly uniform
density. Papers with technical details of the algorithms used in
LAMMPS are listed in :ref:`this section <intro_5>`.
----------
.. _intro_2:
LAMMPS features
---------------
This section highlights LAMMPS features, with pointers to specific
commands which give more details. If LAMMPS doesn't have your
favorite interatomic potential, boundary condition, or atom type, see
:doc:`Section_modify <Section_modify>`, which describes how you can add
it to LAMMPS.
General features
^^^^^^^^^^^^^^^^
* runs on a single processor or in parallel
* distributed-memory message-passing parallelism (MPI)
* spatial-decomposition of simulation domain for parallelism
* open-source distribution
* highly portable C++
* optional libraries used: MPI and single-processor FFT
* GPU (CUDA and OpenCL), Intel(R) Xeon Phi(TM) coprocessors, and OpenMP support for many code features
* easy to extend with new features and functionality
* runs from an input script
* syntax for defining and using variables and formulas
* syntax for looping over runs and breaking out of loops
* run one or multiple simulations simultaneously (in parallel) from one script
* build as library, invoke LAMMPS thru library interface or provided Python wrapper
* couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both
Particle and model types
^^^^^^^^^^^^^^^^^^^^^^^^
(:doc:`atom style <atom_style>` command)
* atoms
* coarse-grained particles (e.g. bead-spring polymers)
* united-atom polymers or organic molecules
* all-atom polymers, organic molecules, proteins, DNA
* metals
* granular materials
* coarse-grained mesoscale models
* finite-size spherical and ellipsoidal particles
* finite-size line segment (2d) and triangle (3d) particles
* point dipole particles
* rigid collections of particles
* hybrid combinations of these
Force fields
^^^^^^^^^^^^
(:doc:`pair style <pair_style>`, :doc:`bond style <bond_style>`,
:doc:`angle style <angle_style>`, :doc:`dihedral style <dihedral_style>`,
:doc:`improper style <improper_style>`, :doc:`kspace style <kspace_style>`
commands)
* pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, class 2 (COMPASS), hydrogen bond, tabulated
* charged pairwise potentials: Coulombic, point-dipole
* manybody potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, SNAP, Streitz-Mintmire, 3-body polymorphic
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald)
* polarization models: :doc:`QEq <fix_qeq>`, :ref:`core/shell model <howto_26>`, :ref:`Drude dipole model <howto_27>`
* charge equilibration (QEq via dynamic, point, shielded, Slater methods)
* coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO
* mesoscopic potentials: granular, Peridynamics, SPH
* electron force field (eFF, AWPMD)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable)
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS)
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS)
* polymer potentials: all-atom, united-atom, bead-spring, breakable
* water potentials: TIP3P, TIP4P, SPC
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
* access to `KIM archive <http://openkim.org>`_ of potentials via :doc:`pair kim <pair_kim>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials
Atom creation
^^^^^^^^^^^^^
(:doc:`read_data <read_data>`, :doc:`lattice <lattice>`,
:doc:`create_atoms <create_atoms>`, :doc:`delete_atoms <delete_atoms>`,
:doc:`displace_atoms <displace_atoms>`, :doc:`replicate <replicate>` commands)
* read in atom coords from files
* create atoms on one or more lattices (e.g. grain boundaries)
* delete geometric or logical groups of atoms (e.g. voids)
* replicate existing atoms multiple times
* displace atoms
Ensembles, constraints, and boundary conditions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(:doc:`fix <fix>` command)
* 2d or 3d systems
* orthogonal or non-orthogonal (triclinic symmetry) simulation domains
* constant NVE, NVT, NPT, NPH, Parinello/Rahman integrators
* thermostatting options for groups and geometric regions of atoms
* pressure control via Nose/Hoover or Berendsen barostatting in 1 to 3 dimensions
* simulation box deformation (tensile and shear)
* harmonic (umbrella) constraint forces
* rigid body constraints
* SHAKE bond and angle constraints
* Monte Carlo bond breaking, formation, swapping
* atom/molecule insertion and deletion
* walls of various kinds
* non-equilibrium molecular dynamics (NEMD)
* variety of additional boundary conditions and constraints
Integrators
^^^^^^^^^^^
(:doc:`run <run>`, :doc:`run_style <run_style>`, :doc:`minimize <minimize>` commands)
* velocity-Verlet integrator
* Brownian dynamics
* rigid body integration
* energy minimization via conjugate gradient or steepest descent relaxation
* rRESPA hierarchical timestepping
* rerun command for post-processing of dump files
Diagnostics
^^^^^^^^^^^
* see the various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
Output
^^^^^^
(:doc:`dump <dump>`, :doc:`restart <restart>` commands)
* log file of thermodynamic info
* text dump files of atom coords, velocities, other per-atom quantities
* binary restart files
* parallel I/O of dump and restart files
* per-atom quantities (energy, stress, centro-symmetry parameter, CNA, etc)
* user-defined system-wide (log file) or per-atom (dump file) calculations
* spatial and time averaging of per-atom quantities
* time averaging of system-wide quantities
* atom snapshots in native, XYZ, XTC, DCD, CFG formats
Multi-replica models
^^^^^^^^^^^^^^^^^^^^
:doc:`nudged elastic band <neb>`
:doc:`parallel replica dynamics <prd>`
:doc:`temperature accelerated dynamics <tad>`
:doc:`parallel tempering <temper>`
Pre- and post-processing
^^^^^^^^^^^^^^^^^^^^^^^^
* Various pre- and post-processing serial tools are packaged
with LAMMPS; see these :doc:`doc pages <Section_tools>`.
* Our group has also written and released a separate toolkit called
`Pizza.py <pizza_>`_ which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in `Python <python_>`_ and is available for download from `the Pizza.py WWW site <pizza_>`_.
.. _pizza: http://www.sandia.gov/~sjplimp/pizza.html
.. _python: http://www.python.org
Specialized features
^^^^^^^^^^^^^^^^^^^^
These are LAMMPS capabilities which you may not think of as typical
molecular dynamics options:
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`
* :doc:`generalized aspherical particles <body>`
* :doc:`stochastic rotation dynamics (SRD) <fix_srd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`
* calculate :doc:`virtual diffraction patterns <compute_xrd>`
* :doc:`atom-to-continuum coupling <fix_atc>` with finite elements
* coupled rigid body integration via the :doc:`POEMS <fix_poems>` library
* :doc:`QM/MM coupling <fix_qmmm>`
* :doc:`path-integral molecular dynamics (PIMD) <fix_ipi>` and :doc:`this as well <fix_pimd>`
* Monte Carlo via :doc:`GCMC <fix_gcmc>` and :doc:`tfMC <fix_tfmc>` and :doc:`atom swapping <fix_swap>`
* :doc:`Direct Simulation Monte Carlo <pair_dsmc>` for low-density fluids
* :doc:`Peridynamics mesoscale modeling <pair_peri>`
* :doc:`Lattice Boltzmann fluid <fix_lb_fluid>`
* :doc:`targeted <fix_tmd>` and :doc:`steered <fix_smd>` molecular dynamics
* :doc:`two-temperature electron model <fix_ttm>`
----------
.. _intro_3:
LAMMPS non-features
-------------------
LAMMPS is designed to efficiently compute Newton's equations of motion
for a system of interacting particles. Many of the tools needed to
pre- and post-process the data for such simulations are not included
in the LAMMPS kernel for several reasons:
* the desire to keep LAMMPS simple
* they are not parallel operations
* other codes already do them
* limited development resources
Specifically, LAMMPS itself does not:
* run thru a GUI
* build molecular systems
* assign force-field coefficients automagically
* perform sophisticated analyses of your MD simulation
* visualize your MD simulation
* plot your output data
A few tools for pre- and post-processing tasks are provided as part of
the LAMMPS package; they are described in :doc:`this section <Section_tools>`. However, many people use other codes or
write their own tools for these tasks.
As noted above, our group has also written and released a separate
toolkit called `Pizza.py <pizza_>`_ which addresses some of the listed
bullets. It provides tools for doing setup, analysis, plotting, and
visualization for LAMMPS simulations. Pizza.py is written in
`Python <python_>`_ and is available for download from `the Pizza.py WWW site <pizza_>`_.
LAMMPS requires as input a list of initial atom coordinates and types,
molecular topology information, and force-field coefficients assigned
to all atoms and bonds. LAMMPS will not build molecular systems and
assign force-field parameters for you.
For atomic systems LAMMPS provides a :doc:`create_atoms <create_atoms>`
command which places atoms on solid-state lattices (fcc, bcc,
user-defined, etc). Assigning small numbers of force field
coefficients can be done via the :doc:`pair coeff <pair_coeff>`, :doc:`bond coeff <bond_coeff>`, :doc:`angle coeff <angle_coeff>`, etc commands.
For molecular systems or more complicated simulation geometries, users
typically use another code as a builder and convert its output to
LAMMPS input format, or write their own code to generate atom
coordinate and molecular topology for LAMMPS to read in.
For complicated molecular systems (e.g. a protein), a multitude of
topology information and hundreds of force-field coefficients must
typically be specified. We suggest you use a program like
`CHARMM <charmm_>`_ or `AMBER <amber_>`_ or other molecular builders to setup
such problems and dump its information to a file. You can then
reformat the file as LAMMPS input. Some of the tools in :doc:`this section <Section_tools>` can assist in this process.
Similarly, LAMMPS creates output files in a simple format. Most users
post-process these files with their own analysis tools or re-format
them for input into other programs, including visualization packages.
If you are convinced you need to compute something on-the-fly as
LAMMPS runs, see :doc:`Section_modify <Section_modify>` for a discussion
of how you can use the :doc:`dump <dump>` and :doc:`compute <compute>` and
:doc:`fix <fix>` commands to print out data of your choosing. Keep in
mind that complicated computations can slow down the molecular
dynamics timestepping, particularly if the computations are not
parallel, so it is often better to leave such analysis to
post-processing codes.
A very simple (yet fast) visualizer is provided with the LAMMPS
package - see the :ref:`xmovie <xmovie>` tool in :doc:`this section <Section_tools>`. It creates xyz projection views of
atomic coordinates and animates them. We find it very useful for
debugging purposes. For high-quality visualization we recommend the
following packages:
* `VMD <http://www.ks.uiuc.edu/Research/vmd>`_
* `AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_
* `PyMol <http://pymol.sourceforge.net>`_
* `Raster3d <http://www.bmsc.washington.edu/raster3d/raster3d.html>`_
* `RasMol <http://www.openrasmol.org>`_
Other features that LAMMPS does not yet (and may never) support are
discussed in :doc:`Section_history <Section_history>`.
Finally, these are freely-available molecular dynamics codes, most of
them parallel, which may be well-suited to the problems you want to
model. They can also be used in conjunction with LAMMPS to perform
complementary modeling tasks.
* `CHARMM <charmm_>`_
* `AMBER <amber_>`_
* `NAMD <namd_>`_
* `NWCHEM <nwchem_>`_
* `DL_POLY <dlpoly_>`_
* `Tinker <tinker_>`_
.. _charmm: http://www.scripps.edu/brooks
.. _amber: http://amber.scripps.edu
.. _namd: http://www.ks.uiuc.edu/Research/namd/
.. _nwchem: http://www.emsl.pnl.gov/docs/nwchem/nwchem.html
.. _dlpoly: http://www.cse.clrc.ac.uk/msi/software/DL_POLY
.. _tinker: http://dasher.wustl.edu/tinker
CHARMM, AMBER, NAMD, NWCHEM, and Tinker are designed primarily for
modeling biological molecules. CHARMM and AMBER use
atom-decomposition (replicated-data) strategies for parallelism; NAMD
and NWCHEM use spatial-decomposition approaches, similar to LAMMPS.
Tinker is a serial code. DL_POLY includes potentials for a variety of
biological and non-biological materials; both a replicated-data and
spatial-decomposition version exist.
----------
.. _intro_4:
Open source distribution
------------------------
LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the `GNU Public License <gnu_>`_ (GPL). This
is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_ for more
details. The legal text of the GPL is in the LICENSE file that is
included in the LAMMPS distribution.
.. _gnuorg: http://www.gnu.org
.. _opensource: http://www.opensource.org
Here is a summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.
(2) If you distribute a modified version of LAMMPS, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
LAMMPS.
(3) If you release any code that includes LAMMPS source code, then it
must also be open-sourced, meaning you distribute it under the terms
of the GPL.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.
In the spirit of an open-source code, these are various ways you can
contribute to making LAMMPS better. You can send email to the
`developers <http://lammps.sandia.gov/authors.html>`_ on any of these
items.
* Point prospective users to the `LAMMPS WWW Site <lws_>`_. Mention it in
talks or link to it from your WWW site.
* If you find an error or omission in this manual or on the `LAMMPS WWW Site <lws_>`_, or have a suggestion for something to clarify or include,
send an email to the
`developers <http://lammps.sandia.gov/authors.html>`_.
* If you find a bug, :ref:`Section_errors 2 <err_2>`
describes how to report it.
* If you publish a paper using LAMMPS results, send the citation (and
any cool pictures or movies if you like) to add to the Publications,
Pictures, and Movies pages of the `LAMMPS WWW Site <lws_>`_, with links
and attributions back to you.
* Create a new Makefile.machine that can be added to the src/MAKE
directory.
* The tools sub-directory of the LAMMPS distribution has various
stand-alone codes for pre- and post-processing of LAMMPS data. More
details are given in :doc:`Section_tools <Section_tools>`. If you write
a new tool that users will find useful, it can be added to the LAMMPS
distribution.
* LAMMPS is designed to be easy to extend with new code for features
like potentials, boundary conditions, diagnostic computations, etc.
:doc:`This section <Section_modify>` gives details. If you add a
feature of general interest, it can be added to the LAMMPS
distribution.
* The Benchmark page of the `LAMMPS WWW Site <lws_>`_ lists LAMMPS
performance on various platforms. The files needed to run the
benchmarks are part of the LAMMPS distribution. If your machine is
sufficiently different from those listed, your timing data can be
added to the page.
* You can send feedback for the User Comments page of the `LAMMPS WWW Site <lws_>`_. It might be added to the page. No promises.
* Cash. Small denominations, unmarked bills preferred. Paper sack OK.
Leave on desk. VISA also accepted. Chocolate chip cookies
encouraged.
----------
.. _intro_5:
Acknowledgments and citations
-------------------------------------------
LAMMPS development has been funded by the `US Department of Energy <doe_>`_ (DOE), through its CRADA, LDRD, ASCI, and Genomes-to-Life
programs and its `OASCR <oascr_>`_ and `OBER <ober_>`_ offices.
Specifically, work on the latest version was funded in part by the US
Department of Energy's Genomics:GTL program
(`www.doegenomestolife.org <gtl_>`_) under the `project <ourgtl_>`_, "Carbon
Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling".
.. _doe: http://www.doe.gov
.. _gtl: http://www.doegenomestolife.org
.. _ourgtl: http://www.genomes2life.org
.. _oascr: http://www.sc.doe.gov/ascr/home.html
.. _ober: http://www.er.doe.gov/production/ober/ober_top.html
The following paper describe the basic parallel algorithms used in
LAMMPS. If you use LAMMPS results in your published work, please cite
this paper and include a pointer to the `LAMMPS WWW Site <lws_>`_
(http://lammps.sandia.gov):
S. J. Plimpton, **Fast Parallel Algorithms for Short-Range Molecular
Dynamics**, J Comp Phys, 117, 1-19 (1995).
Other papers describing specific algorithms used in LAMMPS are listed
under the `Citing LAMMPS link <http://lammps.sandia.gov/cite.html>`_ of
the LAMMPS WWW page.
The `Publications link <http://lammps.sandia.gov/papers.html>`_ on the
LAMMPS WWW page lists papers that have cited LAMMPS. If your paper is
not listed there for some reason, feel free to send us the info. If
the simulations in your paper produced cool pictures or animations,
we'll be pleased to add them to the
`Pictures <http://lammps.sandia.gov/pictures.html>`_ or
`Movies <http://lammps.sandia.gov/movies.html>`_ pages of the LAMMPS WWW
site.
The core group of LAMMPS developers is at Sandia National Labs:
* Steve Plimpton, sjplimp at sandia.gov
* Aidan Thompson, athomps at sandia.gov
* Paul Crozier, pscrozi at sandia.gov
The following folks are responsible for significant contributions to
the code, or other aspects of the LAMMPS development effort. Many of
the packages they have written are somewhat unique to LAMMPS and the
code would not be as general-purpose as it is without their expertise
and efforts.
* Axel Kohlmeyer (Temple U), akohlmey at gmail.com, SVN and Git repositories, indefatigable mail list responder, USER-CG-CMM and USER-OMP packages
* Roy Pollock (LLNL), Ewald and PPPM solvers
* Mike Brown (ORNL), brownw at ornl.gov, GPU package
* Greg Wagner (Sandia), gjwagne at sandia.gov, MEAM package for MEAM potential
* Mike Parks (Sandia), mlparks at sandia.gov, PERI package for Peridynamics
* Rudra Mukherjee (JPL), Rudranarayan.M.Mukherjee at jpl.nasa.gov, POEMS package for articulated rigid body motion
* Reese Jones (Sandia) and collaborators, rjones at sandia.gov, USER-ATC package for atom/continuum coupling
* Ilya Valuev (JIHT), valuev at physik.hu-berlin.de, USER-AWPMD package for wave-packet MD
* Christian Trott (U Tech Ilmenau), christian.trott at tu-ilmenau.de, USER-CUDA package
* Andres Jaramillo-Botero (Caltech), ajaramil at wag.caltech.edu, USER-EFF package for electron force field
* Christoph Kloss (JKU), Christoph.Kloss at jku.at, USER-LIGGGHTS package for granular models and granular/fluid coupling
* Metin Aktulga (LBL), hmaktulga at lbl.gov, USER-REAXC package for C version of ReaxFF
* Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SPH package
As discussed in :doc:`Section_history <Section_history>`, LAMMPS
originated as a cooperative project between DOE labs and industrial
partners. Folks involved in the design and testing of the original
version of LAMMPS were the following:
* John Carpenter (Mayo Clinic, formerly at Cray Research)
* Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)
* Steve Lustig (Dupont)
* Jim Belak (LLNL)
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

974
doc/_sources/Section_modify.txt
View File

@ -1,974 +0,0 @@
Modifying & extending LAMMPS
============================
This section describes how to customize LAMMPS by modifying
and extending its source code.
| 10.1 :ref:`Atom styles <mod_1>`
| 10.2 :ref:`Bond, angle, dihedral, improper potentials <mod_2>`
| 10.3 :ref:`Compute styles <mod_3>`
| 10.4 :ref:`Dump styles <mod_4>`
| 10.5 :ref:`Dump custom output options <mod_5>`
| 10.6 :ref:`Fix styles <mod_6>` which include integrators, temperature and pressure control, force constraints, boundary conditions, diagnostic output, etc
| 10.7 :ref:`Input script commands <mod_7>`
| 10.8 :ref:`Kspace computations <mod_8>`
| 10.9 :ref:`Minimization styles <mod_9>`
| 10.10 :ref:`Pairwise potentials <mod_10>`
| 10.11 :ref:`Region styles <mod_11>`
| 10.12 :ref:`Body styles <mod_12>`
| 10.13 :ref:`Thermodynamic output options <mod_13>`
| 10.14 :ref:`Variable options <mod_14>`
| 10.15 :ref:`Submitting new features for inclusion in LAMMPS <mod_15>`
|
LAMMPS is designed in a modular fashion so as to be easy to modify and
extend with new functionality. In fact, about 75% of its source code
is files added in this fashion.
In this section, changes and additions users can make are listed along
with minimal instructions. If you add a new feature to LAMMPS and
think it will be of interest to general users, we encourage you to
submit it to the developers for inclusion in the released version of
LAMMPS. Information about how to do this is provided
:ref:`below <mod_14>`.
The best way to add a new feature is to find a similar feature in
LAMMPS and look at the corresponding source and header files to figure
out what it does. You will need some knowledge of C++ to be able to
understand the hi-level structure of LAMMPS and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).
Most of the new features described in this section require you to
write a new C++ derived class (except for exceptions described below,
where you can make small edits to existing files). Creating a new
class requires 2 files, a source code file (*.cpp) and a header file
(*.h). The derived class must provide certain methods to work as a
new option. Depending on how different your new feature is compared
to existing features, you can either derive from the base class
itself, or from a derived class that already exists. Enabling LAMMPS
to invoke the new class is as simple as putting the two source
files in the src dir and re-building LAMMPS.
The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write, and thus shouldn't make the rest of LAMMPS more complex or
cause side-effect bugs.
Here is a concrete example. Suppose you write 2 files pair_foo.cpp
and pair_foo.h that define a new class PairFoo that computes pairwise
potentials described in the classic 1997 :ref:`paper <Foo>` by Foo, et al.
If you wish to invoke those potentials in a LAMMPS input script with a
command like
.. parsed-literal::
pair_style foo 0.1 3.5
then your pair_foo.h file should be structured as follows:
.. parsed-literal::
#ifdef PAIR_CLASS
PairStyle(foo,PairFoo)
#else
...
(class definition for PairFoo)
...
#endif
where "foo" is the style keyword in the pair_style command, and
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
files.
When you re-build LAMMPS, your new pairwise potential becomes part of
the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class.
As illustrated by this pairwise example, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.
The instructions below give the header file for the base class that
these styles are derived from. Public variables in that file are ones
used and set by the derived classes which are also used by the base
class. Sometimes they are also used by the rest of LAMMPS. Virtual
functions in the base class header file which are set = 0 are ones you
must define in your new derived class to give it the functionality
LAMMPS expects. Virtual functions that are not set to 0 are functions
you can optionally define.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files as explained
below.
Here are additional guidelines for modifying LAMMPS and adding new
functionality:
* Think about whether what you want to do would be better as a pre- or
post-processing step. Many computations are more easily and more
quickly done that way.
* Don't do anything within the timestepping of a run that isn't
parallel. E.g. don't accumulate a bunch of data on a single processor
and analyze it. You run the risk of seriously degrading the parallel
efficiency.
* If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units <units>`
command.
* If you add something you think is truly useful and doesn't impact
LAMMPS performance when it isn't used, send an email to the
`developers <http://lammps.sandia.gov/authors.html>`_. We might be
interested in adding it to the LAMMPS distribution. See further
details on this at the bottom of this page.
.. _mod_1:
Atom styles
-----------
Classes that define an :doc:`atom style <atom_style>` are derived from
the AtomVec class and managed by the Atom class. The atom style
determines what attributes are associated with an atom. A new atom
style can be created if one of the existing atom styles does not
define all the attributes you need to store and communicate with
atoms.
Atom_vec_atomic.cpp is a simple example of an atom style.
Here is a brief description of methods you define in your new derived
class. See atom_vec.h for details.
+-----------------------+--------------------------------------------------------------------------------+
| init | one time setup (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| grow | re-allocate atom arrays to longer lengths (required) |
+-----------------------+--------------------------------------------------------------------------------+
| grow_reset | make array pointers in Atom and AtomVec classes consistent (required) |
+-----------------------+--------------------------------------------------------------------------------+
| copy | copy info for one atom to another atom's array locations (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_comm | store an atom's info in a buffer communicated every timestep (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_comm_vel | add velocity info to communication buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_comm_hybrid | store extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_comm | retrieve an atom's info from the buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_comm_vel | also retrieve velocity info (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_comm_hybrid | retreive extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_reverse | store an atom's info in a buffer communicating partial forces (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_reverse_hybrid | store extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_reverse | retrieve an atom's info from the buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_reverse_hybrid | retreive extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_border | store an atom's info in a buffer communicated on neighbor re-builds (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_border_vel | add velocity info to buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_border_hybrid | store extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_border | retrieve an atom's info from the buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_border_vel | also retrieve velocity info (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_border_hybrid | retreive extra info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_exchange | store all an atom's info to migrate to another processor (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_exchange | retrieve an atom's info from the buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| size_restart | number of restart quantities associated with proc's atoms (required) |
+-----------------------+--------------------------------------------------------------------------------+
| pack_restart | pack atom quantities into a buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| unpack_restart | unpack atom quantities from a buffer (required) |
+-----------------------+--------------------------------------------------------------------------------+
| create_atom | create an individual atom of this style (required) |
+-----------------------+--------------------------------------------------------------------------------+
| data_atom | parse an atom line from the data file (required) |
+-----------------------+--------------------------------------------------------------------------------+
| data_atom_hybrid | parse additional atom info unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| data_vel | parse one line of velocity information from data file (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| data_vel_hybrid | parse additional velocity data unique to this atom style (optional) |
+-----------------------+--------------------------------------------------------------------------------+
| memory_usage | tally memory allocated by atom arrays (required) |
+-----------------------+--------------------------------------------------------------------------------+
The constructor of the derived class sets values for several variables
that you must set when defining a new atom style, which are documented
in atom_vec.h. New atom arrays are defined in atom.cpp. Search for
the word "customize" and you will find locations you will need to
modify.
.. warning::
It is possible to add some attributes, such as a
molecule ID, to atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.
New :doc:`pair styles <pair_style>`, :doc:`fixes <fix>`, or
:doc:`computes <compute>` can be added to LAMMPS, as discussed below.
The code for these classes can use the per-atom properties defined by
fix property/atom. The Atom class has a find_custom() method that is
useful in this context:
.. parsed-literal::
int index = atom->find_custom(char *name, int &flag);
The "name" of a custom attribute, as specified in the :doc:`fix property/atom <fix_property_atom>` command, is checked to verify
that it exists and its index is returned. The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute.
The vector of values associated with the attribute can then be
accessed using the returned index as
.. parsed-literal::
int *ivector = atom->ivector[index];
double *dvector = atom->dvector[index];
Ivector or dvector are vectors of length Nlocal = # of owned atoms,
which store the attributes of individual atoms.
----------
.. _mod_2:
Bond, angle, dihedral, improper potentials
------------------------------------------
Classes that compute molecular interactions are derived from the Bond,
Angle, Dihedral, and Improper classes. New styles can be created to
add new potentials to LAMMPS.
Bond_harmonic.cpp is the simplest example of a bond style. Ditto for
the harmonic forms of the angle, dihedral, and improper style
commands.
Here is a brief description of common methods you define in your
new derived class. See bond.h, angle.h, dihedral.h, and improper.h
for details and specific additional methods.
+----------------------+---------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init_style* (optional) |
+----------------------+---------------------------------------------------------------------------+
| init_style | check if style specific conditions are met (optional) |
+----------------------+---------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+----------------------+---------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+----------------------+---------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+----------------------+---------------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (required, bond only) |
+----------------------+---------------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (required, angle only) |
+----------------------+---------------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files (required) |
+----------------------+---------------------------------------------------------------------------+
| single | force and energy of a single bond or angle (required, bond or angle only) |
+----------------------+---------------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style (optional) |
+----------------------+---------------------------------------------------------------------------+
----------
.. _mod_3:
Compute styles
--------------
Classes that compute scalar and vector quantities like temperature
and the pressure tensor, as well as classes that compute per-atom
quantities like kinetic energy and the centro-symmetry parameter
are derived from the Compute class. New styles can be created
to add new calculations to LAMMPS.
Compute_temp.cpp is a simple example of computing a scalar
temperature. Compute_ke_atom.cpp is a simple example of computing
per-atom kinetic energy.
Here is a brief description of methods you define in your new derived
class. See compute.h for details.
+------------------+-----------------------------------------------------------------+
| init | perform one time setup (required) |
+------------------+-----------------------------------------------------------------+
| init_list | neighbor list setup, if needed (optional) |
+------------------+-----------------------------------------------------------------+
| compute_scalar | compute a scalar quantity (optional) |
+------------------+-----------------------------------------------------------------+
| compute_vector | compute a vector of quantities (optional) |
+------------------+-----------------------------------------------------------------+
| compute_peratom | compute one or more quantities per atom (optional) |
+------------------+-----------------------------------------------------------------+
| compute_local | compute one or more quantities per processor (optional) |
+------------------+-----------------------------------------------------------------+
| pack_comm | pack a buffer with items to communicate (optional) |
+------------------+-----------------------------------------------------------------+
| unpack_comm | unpack the buffer (optional) |
+------------------+-----------------------------------------------------------------+
| pack_reverse | pack a buffer with items to reverse communicate (optional) |
+------------------+-----------------------------------------------------------------+
| unpack_reverse | unpack the buffer (optional) |
+------------------+-----------------------------------------------------------------+
| remove_bias | remove velocity bias from one atom (optional) |
+------------------+-----------------------------------------------------------------+
| remove_bias_all | remove velocity bias from all atoms in group (optional) |
+------------------+-----------------------------------------------------------------+
| restore_bias | restore velocity bias for one atom after remove_bias (optional) |
+------------------+-----------------------------------------------------------------+
| restore_bias_all | same as before, but for all atoms in group (optional) |
+------------------+-----------------------------------------------------------------+
| memory_usage | tally memory usage (optional) |
+------------------+-----------------------------------------------------------------+
----------
.. _mod_4:
Dump styles
-----------
.. _mod_5:
Dump custom output options
--------------------------
Classes that dump per-atom info to files are derived from the Dump
class. To dump new quantities or in a new format, a new derived dump
class can be added, but it is typically simpler to modify the
DumpCustom class contained in the dump_custom.cpp file.
Dump_atom.cpp is a simple example of a derived dump class.
Here is a brief description of methods you define in your new derived
class. See dump.h for details.
+--------------+---------------------------------------------------+
| write_header | write the header section of a snapshot of atoms |
+--------------+---------------------------------------------------+
| count | count the number of lines a processor will output |
+--------------+---------------------------------------------------+
| pack | pack a proc's output data into a buffer |
+--------------+---------------------------------------------------+
| write_data | write a proc's data to a file |
+--------------+---------------------------------------------------+
See the :doc:`dump <dump>` command and its *custom* style for a list of
keywords for atom information that can already be dumped by
DumpCustom. It includes options to dump per-atom info from Compute
classes, so adding a new derived Compute class is one way to calculate
new quantities to dump.
Alternatively, you can add new keywords to the dump custom command.
Search for the word "customize" in dump_custom.cpp to see the
half-dozen or so locations where code will need to be added.
----------
.. _mod_6:
Fix styles
----------
In LAMMPS, a "fix" is any operation that is computed during
timestepping that alters some property of the system. Essentially
everything that happens during a simulation besides force computation,
neighbor list construction, and output, is a "fix". This includes
time integration (update of coordinates and velocities), force
constraints or boundary conditions (SHAKE or walls), and diagnostics
(compute a diffusion coefficient). New styles can be created to add
new options to LAMMPS.
Fix_setforce.cpp is a simple example of setting forces on atoms to
prescribed values. There are dozens of fix options already in LAMMPS;
choose one as a template that is similar to what you want to
implement.
Here is a brief description of methods you can define in your new
derived class. See fix.h for details.
+-------------------------+-------------------------------------------------------------------------------------------+
| setmask | determines when the fix is called during the timestep (required) |
+-------------------------+-------------------------------------------------------------------------------------------+
| init | initialization before a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_exchange | called before atom exchange in setup (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_force | called before force computation in setup (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup | called immediately before the 1st timestep and after forces are computed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_setup_pre_force | like setup_pre_force, but for minimizations instead of MD runs (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_setup | like setup, but for minimizations instead of MD runs (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| initial_integrate | called at very beginning of each timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_exchange | called before atom exchange on re-neighboring steps (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_neighbor | called before neighbor list build (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_force | called before pair & molecular forces are computed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_force | called after pair & molecular forces are computed and communicated (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| final_integrate | called at end of each timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| end_of_step | called at very end of timestep (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| write_restart | dumps fix info to restart file (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| restart | uses info from restart file to re-initialize the fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| grow_arrays | allocate memory for atom-based arrays used by fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| copy_arrays | copy atom info when an atom migrates to a new processor (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_exchange | store atom's data in a buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_exchange | retrieve atom's data from a buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_restart | store atom's data for writing to restart file (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_restart | retrieve atom's data from a restart file buffer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| size_restart | size of atom's data (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| maxsize_restart | max size of atom's data (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| setup_pre_force_respa | same as setup_pre_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| initial_integrate_respa | same as initial_integrate, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_integrate_respa | called after the first half integration step is done in rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pre_force_respa | same as pre_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| post_force_respa | same as post_force, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| final_integrate_respa | same as final_integrate, but for rRESPA (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_pre_force | called after pair & molecular forces are computed in minimizer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_post_force | called after pair & molecular forces are computed and communicated in minmizer (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_store | store extra data for linesearch based minimization on a LIFO stack (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_pushstore | push the minimization LIFO stack one element down (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_popstore | pop the minimization LIFO stack one element up (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_clearstore | clear minimization LIFO stack (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_step | reset or move forward on line search minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| min_dof | report number of degrees of freedom *added* by this fix in minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| max_alpha | report maximum allowed step size during linesearch minimization (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_comm | pack a buffer to communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_comm | unpack a buffer to communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| pack_reverse_comm | pack a buffer to reverse communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| unpack_reverse_comm | unpack a buffer to reverse communicate a per-atom quantity (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| dof | report number of degrees of freedom *removed* by this fix during MD (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_scalar | return a global scalar property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_vector | return a component of a vector property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| compute_array | return a component of an array property that the fix computes (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| deform | called when the box size is changed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| reset_target | called when a change of the target temperature is requested during a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| reset_dt | is called when a change of the time step is requested during a run (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| modify_param | called when a fix_modify request is executed (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| memory_usage | report memory used by fix (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
| thermo | compute quantities for thermodynamic output (optional) |
+-------------------------+-------------------------------------------------------------------------------------------+
Typically, only a small fraction of these methods are defined for a
particular fix. Setmask is mandatory, as it determines when the fix
will be invoked during the timestep. Fixes that perform time
integration (*nve*, *nvt*, *npt*) implement initial_integrate() and
final_integrate() to perform velocity Verlet updates. Fixes that
constrain forces implement post_force().
Fixes that perform diagnostics typically implement end_of_step(). For
an end_of_step fix, one of your fix arguments must be the variable
"nevery" which is used to determine when to call the fix and you must
set this variable in the constructor of your fix. By convention, this
is the first argument the fix defines (after the ID, group-ID, style).
If the fix needs to store information for each atom that persists from
timestep to timestep, it can manage that memory and migrate the info
with the atoms as they move from processors to processor by
implementing the grow_arrays, copy_arrays, pack_exchange, and
unpack_exchange methods. Similarly, the pack_restart and
unpack_restart methods can be implemented to store information about
the fix in restart files. If you wish an integrator or force
constraint fix to work with rRESPA (see the :doc:`run_style <run_style>`
command), the initial_integrate, post_force_integrate, and
final_integrate_respa methods can be implemented. The thermo method
enables a fix to contribute values to thermodynamic output, as printed
quantities and/or to be summed to the potential energy of the system.
----------
.. _mod_7:
Input script commands
---------------------
New commands can be added to LAMMPS input scripts by adding new
classes that have a "command" method. For example, the create_atoms,
read_data, velocity, and run commands are all implemented in this
fashion. When such a command is encountered in the LAMMPS input
script, LAMMPS simply creates a class with the corresponding name,
invokes the "command" method of the class, and passes it the arguments
from the input script. The command method can perform whatever
operations it wishes on LAMMPS data structures.
The single method your new class must define is as follows:
+---------+-----------------------------------------+
| command | operations performed by the new command |
+---------+-----------------------------------------+
Of course, the new class can define other methods and variables as
needed.
----------
.. _mod_8:
Kspace computations
-------------------
Classes that compute long-range Coulombic interactions via K-space
representations (Ewald, PPPM) are derived from the KSpace class. New
styles can be created to add new K-space options to LAMMPS.
Ewald.cpp is an example of computing K-space interactions.
Here is a brief description of methods you define in your new derived
class. See kspace.h for details.
+--------------+----------------------------------------------+
| init | initialize the calculation before a run |
+--------------+----------------------------------------------+
| setup | computation before the 1st timestep of a run |
+--------------+----------------------------------------------+
| compute | every-timestep computation |
+--------------+----------------------------------------------+
| memory_usage | tally of memory usage |
+--------------+----------------------------------------------+
----------
.. _mod_9:
Minimization styles
-------------------
Classes that perform energy minimization derived from the Min class.
New styles can be created to add new minimization algorithms to
LAMMPS.
Min_cg.cpp is an example of conjugate gradient minimization.
Here is a brief description of methods you define in your new derived
class. See min.h for details.
+--------------+------------------------------------------+
| init | initialize the minimization before a run |
+--------------+------------------------------------------+
| run | perform the minimization |
+--------------+------------------------------------------+
| memory_usage | tally of memory usage |
+--------------+------------------------------------------+
----------
.. _mod_10:
Pairwise potentials
-------------------
Classes that compute pairwise interactions are derived from the Pair
class. In LAMMPS, pairwise calculation include manybody potentials
such as EAM or Tersoff where particles interact without a static bond
topology. New styles can be created to add new pair potentials to
LAMMPS.
Pair_lj_cut.cpp is a simple example of a Pair class, though it
includes some optional methods to enable its use with rRESPA.
Here is a brief description of the class methods in pair.h:
+-------------------------------+-------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+-------------------------------+-------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+-------------------------------+-------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+-------------------------------+-------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+-------------------------------+-------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+-------------------------------+-------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+-------------------------------+-------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+-------------------------------+-------------------------------------------------------------------+
| single | force and energy of a single pairwise interaction between 2 atoms |
+-------------------------------+-------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+-------------------------------+-------------------------------------------------------------------+
The inner/middle/outer routines are optional.
----------
.. _mod_11:
Region styles
-------------
Classes that define geometric regions are derived from the Region
class. Regions are used elsewhere in LAMMPS to group atoms, delete
atoms to create a void, insert atoms in a specified region, etc. New
styles can be created to add new region shapes to LAMMPS.
Region_sphere.cpp is an example of a spherical region.
Here is a brief description of methods you define in your new derived
class. See region.h for details.
+-------+--------------------------------------------+
| match | determine whether a point is in the region |
+-------+--------------------------------------------+
----------
.. _mod_12:
Body styles
-----------
Classes that define body particles are derived from the Body class.
Body particles can represent complex entities, such as surface meshes
of discrete points, collections of sub-particles, deformable objects,
etc.
See :ref:`Section_howto 14 <howto_14>` of the manual for
an overview of using body particles and the :doc:`body <body>` doc page
for details on the various body styles LAMMPS supports. New styles
can be created to add new kinds of body particles to LAMMPS.
Body_nparticle.cpp is an example of a body particle that is treated as
a rigid body containing N sub-particles.
Here is a brief description of methods you define in your new derived
class. See body.h for details.
+--------------------+-----------------------------------------------------------+
| data_body | process a line from the Bodies section of a data file |
+--------------------+-----------------------------------------------------------+
| noutrow | number of sub-particles output is generated for |
+--------------------+-----------------------------------------------------------+
| noutcol | number of values per-sub-particle output is generated for |
+--------------------+-----------------------------------------------------------+
| output | output values for the Mth sub-particle |
+--------------------+-----------------------------------------------------------+
| pack_comm_body | body attributes to communicate every timestep |
+--------------------+-----------------------------------------------------------+
| unpack_comm_body | unpacking of those attributes |
+--------------------+-----------------------------------------------------------+
| pack_border_body | body attributes to communicate when reneighboring is done |
+--------------------+-----------------------------------------------------------+
| unpack_border_body | unpacking of those attributes |
+--------------------+-----------------------------------------------------------+
----------
.. _mod_13:
Thermodynamic output options
----------------------------
There is one class that computes and prints thermodynamic information
to the screen and log file; see the file thermo.cpp.
There are two styles defined in thermo.cpp: "one" and "multi". There
is also a flexible "custom" style which allows the user to explicitly
list keywords for quantities to print when thermodynamic info is
output. See the :doc:`thermo_style <thermo_style>` command for a list
of defined quantities.
The thermo styles (one, multi, etc) are simply lists of keywords.
Adding a new style thus only requires defining a new list of keywords.
Search for the word "customize" with references to "thermo style" in
thermo.cpp to see the two locations where code will need to be added.
New keywords can also be added to thermo.cpp to compute new quantities
for output. Search for the word "customize" with references to
"keyword" in thermo.cpp to see the several locations where code will
need to be added.
Note that the :doc:`thermo_style custom <thermo>` command already allows
for thermo output of quantities calculated by :doc:`fixes <fix>`,
:doc:`computes <compute>`, and :doc:`variables <variable>`. Thus, it may
be simpler to compute what you wish via one of those constructs, than
by adding a new keyword to the thermo command.
----------
.. _mod_14:
Variable options
----------------
There is one class that computes and stores :doc:`variable <variable>`
information in LAMMPS; see the file variable.cpp. The value
associated with a variable can be periodically printed to the screen
via the :doc:`print <print>`, :doc:`fix print <fix_print>`, or
:doc:`thermo_style custom <thermo_style>` commands. Variables of style
"equal" can compute complex equations that involve the following types
of arguments:
.. parsed-literal::
thermo keywords = ke, vol, atoms, ...
other variables = v_a, v_myvar, ...
math functions = div(x,y), mult(x,y), add(x,y), ...
group functions = mass(group), xcm(group,x), ...
atom values = x[123], y[3], vx[34], ...
compute values = c_mytemp[0], c_thermo_press[3], ...
Adding keywords for the :doc:`thermo_style custom <thermo_style>` command
(which can then be accessed by variables) was discussed
:ref:`here <thermo>` on this page.
Adding a new math function of one or two arguments can be done by
editing one section of the Variable::evaulate() method. Search for
the word "customize" to find the appropriate location.
Adding a new group function can be done by editing one section of the
Variable::evaulate() method. Search for the word "customize" to find
the appropriate location. You may need to add a new method to the
Group class as well (see the group.cpp file).
Accessing a new atom-based vector can be done by editing one section
of the Variable::evaulate() method. Search for the word "customize"
to find the appropriate location.
Adding new :doc:`compute styles <compute>` (whose calculated values can
then be accessed by variables) was discussed
:ref:`here <compute>` on this page.
.. _mod_15:
Submitting new features for inclusion in LAMMPS
-----------------------------------------------
We encourage users to submit new features to `the developers <http://lammps.sandia.gov/authors.html>`_ that they add to
LAMMPS, especially if you think they will be of interest to other
users. If they are broadly useful we may add them as core files to
LAMMPS or as part of a :ref:`standard package <start_3>`.
Else we will add them as a user-contributed file or package. Examples
of user packages are in src sub-directories that start with USER. The
USER-MISC package is simply a collection of (mostly) unrelated single
files, which is the simplest way to have your contribution quickly
added to the LAMMPS distribution. You can see a list of the both
standard and user packages by typing "make package" in the LAMMPS src
directory.
Note that by providing us the files to release, you are agreeing to
make them open-source, i.e. we can release them under the terms of the
GPL, used as a license for the rest of LAMMPS. See :ref:`Section 1.4 <intro_4>` for details.
With user packages and files, all we are really providing (aside from
the fame and fortune that accompanies having your name in the source
code and on the `Authors page <http://lammps.sandia.gov/authors.html>`_
of the `LAMMPS WWW site <lws_>`_), is a means for you to distribute your
work to the LAMMPS user community, and a mechanism for others to
easily try out your new feature. This may help you find bugs or make
contact with new collaborators. Note that you're also implicitly
agreeing to support your code which means answer questions, fix bugs,
and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).
.. note::
If you prefer to actively develop and support your add-on
feature yourself, then you may wish to make it available for download
from your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools <http://lammps.sandia.gov/offsite.html>`_ page of the LAMMPS web
site for examples of groups that do this. We are happy to advertise
your package and web site from that page. Simply email the
`developers <http://lammps.sandia.gov/authors.html>`_ with info about
your package and we will post it there.
The previous sections of this doc page describe how to add new "style"
files of various kinds to LAMMPS. Packages are simply collections of
one or more new class files which are invoked as a new style within a
LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you'll need to `communicate with the developers <http://lammps.sandia.gov/authors.html>`_, since we may or may
not want to make those changes. An example of a trivial change is
making a parent-class method "virtual" when you derive a new child
class from it.
Here are the steps you need to follow to submit a single file or user
package for our consideration. Following these steps will save both
you and us time. See existing files in packages in the src dir for
examples.
* All source files you provide must compile with the most current
version of LAMMPS.
* If you want your file(s) to be added to main LAMMPS or one of its
standard packages, then it needs to be written in a style compatible
with other LAMMPS source files. This is so the developers can
understand it and hopefully maintain it. This basically means that
the code accesses data structures, performs its operations, and is
formatted similar to other LAMMPS source files, including the use of
the error class for error and warning messages.
* If you want your contribution to be added as a user-contributed
feature, and it's a single file (actually a *.cpp and *.h file) it can
rapidly be added to the USER-MISC directory. Send us the one-line
entry to add to the USER-MISC/README file in that dir, along with the
2 source files. You can do this multiple times if you wish to
contribute several individual features.
* If you want your contribution to be added as a user-contribution and
it is several related featues, it is probably best to make it a user
package directory with a name like USER-FOO. In addition to your new
files, the directory should contain a README text file. The README
should contain your name and contact information and a brief
description of what your new package does. If your files depend on
other LAMMPS style files also being installed (e.g. because your file
is a derived class from the other LAMMPS class), then an Install.sh
file is also needed to check for those dependencies. See other README
and Install.sh files in other USER directories as examples. Send us a
tarball of this USER-FOO directory.
* Your new source files need to have the LAMMPS copyright, GPL notice,
and your name and email address at the top, like other
user-contributed LAMMPS source files. They need to create a class
that is inside the LAMMPS namespace. If the file is for one of the
USER packages, including USER-MISC, then we are not as picky about the
coding style (see above). I.e. the files do not need to be in the
same stylistic format and syntax as other LAMMPS files, though that
would be nice for developers as well as users who try to read your
code.
* You must also create a documentation file for each new command or
style you are adding to LAMMPS. This will be one file for a
single-file feature. For a package, it might be several files. These
are simple text files which we auto-convert to HTML. Thus they must
be in the same format as other *.txt files in the lammps/doc directory
for similar commands and styles; use one or more of them as a starting
point. As appropriate, the text files can include links to equations
(see doc/Eqs/*.tex for examples, we auto-create the associated JPG
files), or figures (see doc/JPG for examples), or even additional PDF
files with further details (see doc/PDF for examples). The doc page
should also include literature citations as appropriate; see the
bottom of doc/fix_nh.txt for examples and the earlier part of the same
file for how to format the cite itself. The "Restrictions" section of
the doc page should indicate that your command is only available if
LAMMPS is built with the appropriate USER-MISC or USER-FOO package.
See other user package doc files for examples of how to do this. The
txt2html tool we use to convert to HTML can be downloaded from `this site <http://www.sandia.gov/~sjplimp/download.html>`_, so you can perform
the HTML conversion yourself to proofread your doc page.
* For a new package (or even a single command) you can include one or
more example scripts. These should run in no more than 1 minute, even
on a single processor, and not require large data files as input. See
directories under examples/USER for examples of input scripts other
users provided for their packages.
* If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the *.cpp
source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and a
single line of code that references the variable is added to the
constructor of the class. Whenever a user invokes your feature from
their input script, this will cause LAMMPS to output the citation to a
log.cite file and prompt the user to examine the file. Note that you
should only use this for a paper you or your group authored.
E.g. adding a cite in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended
usage. That kind of citation should just be in the doc page you
provide.
Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your doc and README files, and the easier
you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try out your new
feature.
.. _Foo:
**(Foo)** Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

781
doc/_sources/Section_packages.txt
View File

@ -1,781 +0,0 @@
Packages
========
This section gives a quick overview of the add-on packages that extend
LAMMPS functionality.
| 4.1 :ref:`Standard packages <pkg_1>`
| 4.2 :ref:`User packages <pkg_2>`
|
LAMMPS includes many optional packages, which are groups of files that
enable a specific set of features. For example, force fields for
molecular systems or granular systems are in packages. You can see
the list of all packages by typing "make package" from within the src
directory of the LAMMPS distribution.
See :ref:`Section_start 3 <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.
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.
.. _pkg_1:
Standard packages
-----------------------------
The current list of standard packages is as follows:
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| Package | Description | Author(s) | Doc page | Example | Library |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| ASPHERE | aspherical particles | - | :ref:`Section_howto 6.14 <howto_14>` | ellipse | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| BODY | body-style particles | - | :doc:`body <body>` | body | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| CLASS2 | class 2 force fields | - | :doc:`pair_style lj/class2 <pair_class2>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| COLLOID | colloidal particles | - | :doc:`atom_style colloid <atom_style>` | colloid | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| CORESHELL | adiabatic core/shell model | Hendrik Heenen (Technical U of Munich) | :ref:`Section_howto 6.25 <howto_25>` | coreshell | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| DIPOLE | point dipole particles | - | :doc:`pair_style dipole/cut <pair_dipole>` | dipole | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| FLD | Fast Lubrication Dynamics | Kumar & Bybee & Higdon (1) | :doc:`pair_style lubricateU <pair_lubricateU>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| GPU | GPU-enabled styles | Mike Brown (ORNL) | :doc:`Section accelerate <accelerate_gpu>` | gpu | lib/gpu |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| GRANULAR | granular systems | - | :ref:`Section_howto 6.6 <howto_6>` | pour | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| KIM | openKIM potentials | Smirichinski & Elliot & Tadmor (3) | :doc:`pair_style kim <pair_kim>` | kim | KIM |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| KOKKOS | Kokkos-enabled styles | Trott & Edwards (4) | :doc:`Section_accelerate <accelerate_kokkos>` | kokkos | lib/kokkos |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| KSPACE | long-range Coulombic solvers | - | :doc:`kspace_style <kspace_style>` | peptide | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| MANYBODY | many-body potentials | - | :doc:`pair_style tersoff <pair_tersoff>` | shear | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| MEAM | modified EAM potential | Greg Wagner (Sandia) | :doc:`pair_style meam <pair_meam>` | meam | lib/meam |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| MC | Monte Carlo options | - | :doc:`fix gcmc <fix_gcmc>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| MOLECULE | molecular system force fields | - | :ref:`Section_howto 6.3 <howto_3>` | peptide | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| OPT | optimized pair styles | Fischer & Richie & Natoli (2) | :doc:`Section accelerate <accelerate_opt>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| PERI | Peridynamics models | Mike Parks (Sandia) | :doc:`pair_style peri <pair_peri>` | peri | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| POEMS | coupled rigid body motion | Rudra Mukherjee (JPL) | :doc:`fix poems <fix_poems>` | rigid | lib/poems |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| PYTHON | embed Python code in an input script | - | :doc:`python <python>` | python | lib/python |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| REAX | ReaxFF potential | Aidan Thompson (Sandia) | :doc:`pair_style reax <pair_reax>` | reax | lib/reax |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| REPLICA | multi-replica methods | - | :ref:`Section_howto 6.5 <howto_5>` | tad | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| RIGID | rigid bodies | - | :doc:`fix rigid <fix_rigid>` | rigid | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| SHOCK | shock loading methods | - | :doc:`fix msst <fix_msst>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| SNAP | quantum-fit potential | Aidan Thompson (Sandia) | :doc:`pair snap <pair_snap>` | snap | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| SRD | stochastic rotation dynamics | - | :doc:`fix srd <fix_srd>` | srd | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| VORONOI | Voronoi tesselations | Daniel Schwen (LANL) | :doc:`compute voronoi/atom <compute_voronoi_atom>` | - | Voro++ |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| XTC | dumps in XTC format | - | :doc:`dump <dump>` | - | - |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
| | | | | | |
+-----------+--------------------------------------+----------------------------------------+----------------------------------------------------+-----------+------------+
The "Authors" column lists a name(s) if a specific person is
responible for creating and maintaining the package.
(1) The FLD package was created by Amit Kumar and Michael Bybee from
Jonathan Higdon's group at UIUC.
(2) The OPT package was created by James Fischer (High Performance
Technologies), David Richie, and Vincent Natoli (Stone Ridge
Technolgy).
(3) The KIM package was created by Valeriu Smirichinski, Ryan Elliott,
and Ellad Tadmor (U Minn).
(4) The KOKKOS package was created primarily by Christian Trott
(Sandia). It uses the Kokkos library which was developed by Carter
Edwards, Christian, and collaborators at Sandia.
The "Doc page" column links to either a portion of the
:doc:`Section_howto <Section_howto>` of the manual, or an input script
command implemented as part of 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.
E.g. "peptide" refers to the examples/peptide directory.
The "Library" column lists an external library which must be built
first and which LAMMPS links to when it is built. If it is listed as
lib/package, then the code for the library is under the lib directory
of the LAMMPS distribution. See the lib/package/README file for info
on how to build the library. If it is not listed as lib/package, then
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. :ref:`Section start <start_3_3>` of the manual also gives details
on how to build LAMMPS with both kinds of auxiliary libraries.
.. _pkg_2:
User packages
-------------------------
The current list of user-contributed packages is as follows:
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| Package | Description | Author(s) | Doc page | Example | Pic/movie | Library |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-ATC | atom-to-continuum coupling | Jones & Templeton & Zimmerman (1) | :doc:`fix atc <fix_atc>` | USER/atc | `atc <atc_>`_ | lib/atc |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-AWPMD | wave-packet MD | Ilya Valuev (JIHT) | :doc:`pair_style awpmd/cut <pair_awpmd>` | USER/awpmd | - | lib/awpmd |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-CG-CMM | coarse-graining model | Axel Kohlmeyer (Temple U) | :doc:`pair_style lj/sdk <pair_sdk>` | USER/cg-cmm | `cg <cg_>`_ | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-COLVARS | collective variables | Fiorin & Henin & Kohlmeyer (2) | :doc:`fix colvars <fix_colvars>` | USER/colvars | `colvars <colvars>`_ | lib/colvars |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-CUDA | NVIDIA GPU styles | Christian Trott (U Tech Ilmenau) | :doc:`Section accelerate <accelerate_cuda>` | USER/cuda | - | lib/cuda |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-DIFFRACTION | virutal x-ray and electron diffraction | Shawn Coleman (ARL) | :doc:`compute xrd <compute_xrd>` | USER/diffraction | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-DRUDE | Drude oscillators | Dequidt & Devemy & Padua (3) | :doc:`tutorial <tutorial_drude>` | USER/drude | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-EFF | electron force field | Andres Jaramillo-Botero (Caltech) | :doc:`pair_style eff/cut <pair_eff>` | USER/eff | `eff <eff_>`_ | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-FEP | free energy perturbation | Agilio Padua (U Blaise Pascal Clermont-Ferrand) | :doc:`compute fep <compute_fep>` | USER/fep | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-INTEL | Vectorized CPU and Intel(R) coprocessor styles | W. Michael Brown (Intel) | :doc:`Section accelerate <accelerate_intel>` | examples/intel | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-LB | Lattice Boltzmann fluid | Colin Denniston (U Western Ontario) | :doc:`fix lb/fluid <fix_lb_fluid>` | USER/lb | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-MISC | single-file contributions | USER-MISC/README | USER-MISC/README | - | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-MOLFILE | `VMD <VMD_>`_ molfile plug-ins | Axel Kohlmeyer (Temple U) | :doc:`dump molfile <dump_molfile>` | - | - | VMD-MOLFILE |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-OMP | OpenMP threaded styles | Axel Kohlmeyer (Temple U) | :doc:`Section accelerate <accelerate_omp>` | - | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-PHONON | phonon dynamical matrix | Ling-Ti Kong (Shanghai Jiao Tong U) | :doc:`fix phonon <fix_phonon>` | USER/phonon | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-QMMM | QM/MM coupling | Axel Kohlmeyer (Temple U) | :doc:`fix qmmm <fix_qmmm>` | USER/qmmm | - | lib/qmmm |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-QTB | quantum nuclear effects | Yuan Shen (Stanford) | :doc:`fix qtb <fix_qtb>` :doc:`fix_qbmsst <fix_qbmsst>` | qtb | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-QUIP | QUIP/libatoms interface | Albert Bartok-Partay (U Cambridge) | :doc:`pair_style quip <pair_quip>` | USER/quip | - | lib/quip |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-REAXC | C version of ReaxFF | Metin Aktulga (LBNL) | :doc:`pair_style reaxc <pair_reax_c>` | reax | - | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| USER-SPH | smoothed particle hydrodynamics | Georg Ganzenmuller (EMI) | `userguide.pdf <USER/sph/SPH_LAMMPS_userguide.pdf>`_ | USER/sph | `sph <sph_>`_ | - |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
| | | | | | | |
+------------------+------------------------------------------------+-------------------------------------------------+---------------------------------------------------------+------------------+----------------------+-------------+
.. _atc: http://lammps.sandia.gov/pictures.html#atc
.. _cg: http://lammps.sandia.gov/pictures.html#cg
.. _eff: http://lammps.sandia.gov/movies.html#eff
.. _sph: http://lammps.sandia.gov/movies.html#sph
.. _VMD: http://www.ks.uiuc.edu/Research/vmd
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
Jon Zimmerman (Sandia).
(2) The COLVARS package was created by Axel Kohlmeyer (Temple U) using
the colvars module library written by Giacomo Fiorin (Temple U) and
Jerome Henin (LISM, Marseille, France).
(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).
The "Doc page" column links to either a portion of the
:doc:`Section_howto <Section_howto>` of the manual, or an input script
command implemented as part of the package, or to additional
documentation provided witht he package.
The "Example" column is a sub-directory in the examples directory of
the distribution which has an input script that uses the package.
E.g. "peptide" refers to the examples/peptide directory. USER/cuda
refers to the examples/USER/cuda directory.
The "Library" column lists an external library which must be built
first and which LAMMPS links to when it is built. If it is listed as
lib/package, then the code for the library is under the lib directory
of the LAMMPS distribution. See the lib/package/README file for info
on how to build the library. If it 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. :ref:`Section start <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.
----------
USER-ATC package
----------------
This package implements a "fix atc" 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
post-processing of atomic information to continuum fields.
See the doc page for the fix atc command to get started. At the
bottom of the doc page are many links to additional documentation
contained in the doc/USER/atc directory.
There are example scripts for using this package in examples/USER/atc.
This package uses an external library in lib/atc which must be
compiled before making LAMMPS. See the lib/atc/README file and the
LAMMPS manual for information on building LAMMPS with external
libraries.
The primary people who created this package are Reese Jones (rjones at
sandia.gov), Jeremy Templeton (jatempl at sandia.gov) and Jon
Zimmerman (jzimmer at sandia.gov) at Sandia. Contact them directly if
you have questions.
----------
USER-AWPMD package
------------------
This package contains a LAMMPS implementation of the Antisymmetrized
Wave Packet Molecular Dynamics (AWPMD) method.
See the doc page for the pair_style awpmd/cut command to get started.
There are example scripts for using this package in examples/USER/awpmd.
This package uses an external library in lib/awpmd which must be
compiled before making LAMMPS. See the lib/awpmd/README file and the
LAMMPS manual for information on building LAMMPS with external
libraries.
The person who created this package is Ilya Valuev at the JIHT in
Russia (valuev at physik.hu-berlin.de). Contact him directly if you
have questions.
----------
USER-CG-CMM package
-------------------
This package implements 3 commands which can be used in a LAMMPS input
script:
* pair_style lj/sdk
* pair_style lj/sdk/coul/long
* angle_style sdk
These styles allow coarse grained MD simulations with the
parametrization of Shinoda, DeVane, Klein, Mol Sim, 33, 27 (2007)
(SDK), with extensions to simulate ionic liquids, electrolytes, lipids
and charged amino acids.
See the doc pages for these commands for details.
There are example scripts for using this package in
examples/USER/cg-cmm.
This is the second generation implementation reducing the the clutter
of the previous version. For many systems with electrostatics, it will
be faster to use pair_style hybrid/overlay with lj/sdk and coul/long
instead of the combined lj/sdk/coul/long style. since the number of
charged atom types is usually small. For any other coulomb
interactions this is now required. To exploit this property, the use
of the kspace_style pppm/cg is recommended over regular pppm. For all
new styles, input file backward compatibility is provided. The old
implementation is still available through appending the /old
suffix. These will be discontinued and removed after the new
implementation has been fully validated.
The current version of this package should be considered beta
quality. The CG potentials work correctly for "normal" situations, but
have not been testing with all kinds of potential parameters and
simulation systems.
The person who created this package is Axel Kohlmeyer at Temple U
(akohlmey at gmail.com). Contact him directly if you have questions.
----------
USER-COLVARS package
--------------------
This package implements the "fix colvars" command which can be
used in a LAMMPS input script.
This fix allows to use "collective variables" to implement
Adaptive Biasing Force, Metadynamics, Steered MD, Umbrella
Sampling and Restraints. This code consists of two parts:
* A portable collective variable module library written and maintained
* by Giacomo Fiorin (ICMS, Temple University, Philadelphia, PA, USA) and
* Jerome Henin (LISM, CNRS, Marseille, France). This code is located in
* the directory lib/colvars and needs to be compiled first. The colvars
* fix and an interface layer, exchanges information between LAMMPS and
* the collective variable module.
See the doc page of :doc:`fix colvars <fix_colvars>` for more details.
There are example scripts for using this package in
examples/USER/colvars
This is a very new interface that does not yet support all
features in the module and will see future optimizations
and improvements. The colvars module library is also available
in NAMD has been thoroughly used and tested there. Bugs and
problems are likely due to the interface layers code.
Thus the current version of this package should be considered
beta quality.
The person who created this package is Axel Kohlmeyer at Temple U
(akohlmey at gmail.com). Contact him directly if you have questions.
----------
USER-CUDA package
-----------------
This package provides acceleration of various LAMMPS pair styles, fix
styles, compute styles, and long-range Coulombics via PPPM for NVIDIA
GPUs.
See this section of the manual to get started:
:ref:`Section_accelerate <acc_7>`
There are example scripts for using this package in
examples/USER/cuda.
This package uses an external library in lib/cuda which must be
compiled before making LAMMPS. See the lib/cuda/README file and the
LAMMPS manual for information on building LAMMPS with external
libraries.
The person who created this package is Christian Trott at the
University of Technology Ilmenau, Germany (christian.trott at
tu-ilmenau.de). Contact him directly if you have questions.
----------
USER-DIFFRACTION package
------------------------
This package contains the commands neeed to calculate x-ray and
electron diffraction intensities based on kinematic diffraction
theory.
See these doc pages and their related commands to get started:
* :doc:`compute xrd <compute_xrd>`
* :doc:`compute saed <compute_saed>`
* :doc:`fix saed/vtk <fix_saed_vtk>`
The person who created this package is Shawn P. Coleman
(shawn.p.coleman8.ctr at mail.mil) while at the University of
Arkansas. Contact him directly if you have questions.
----------
USER-DRUDE package
------------------
This package implements methods for simulating polarizable systems
in LAMMPS using thermalized Drude oscillators.
See these doc pages and their related commands to get started:
* :doc:`Drude tutorial <tutorial_drude>`
* :doc:`fix drude <fix_drude>`
* :doc:`compute temp/drude <compute_temp_drude>`
* :doc:`fix langevin/drude <fix_langevin_drude>`
* :doc:`fix drude/transform/... <fix_drude_transform>`
* :doc:`pair thole <pair_thole>`
There are auxiliary tools for using this package in tools/drude.
The person who created this package is Alain Dequidt at Universite
Blaise Pascal Clermont-Ferrand (alain.dequidt at univ-bpclermont.fr)
Contact him directly if you have questions. Co-authors: Julien Devemy,
Agilio Padua.
----------
USER-EFF package
----------------
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,
2010. The eFF potential was first introduced by Su and Goddard, in
2007.
eFF can be viewed as an approximation to QM wave packet dynamics and
Fermionic molecular dynamics, combining the ability of electronic
structure methods to describe atomic structure, bonding, and chemistry
in materials, and of plasma methods to describe nonequilibrium
dynamics of large systems with a large number of highly excited
electrons. We classify it as a mixed QM-classical approach rather than
a conventional force field method, which introduces QM-based terms (a
spin-dependent repulsion term to account for the Pauli exclusion
principle and the electron wavefunction kinetic energy associated with
the Heisenberg principle) that reduce, along with classical
electrostatic terms between nuclei and electrons, to the sum of a set
of effective pairwise potentials. This makes eFF uniquely suited to
simulate materials over a wide range of temperatures and pressures
where electronically excited and ionized states of matter can occur
and coexist.
The necessary customizations to the LAMMPS core are in place to
enable the correct handling of explicit electron properties during
minimization and dynamics.
See the doc page for the pair_style eff/cut command to get started.
There are example scripts for using this package in
examples/USER/eff.
There are auxiliary tools for using this package in tools/eff.
The person who created this package is Andres Jaramillo-Botero at
CalTech (ajaramil at wag.caltech.edu). Contact him directly if you
have questions.
----------
USER-FEP package
----------------
This package provides methods for performing free energy perturbation
simulations with soft-core pair potentials in LAMMPS.
See these doc pages and their related commands to get started:
* :doc:`fix adapt/fep <fix_adapt_fep>`
* :doc:`compute fep <compute_fep>`
* :doc:`soft pair styles <pair_lj_soft>`
The person who created this package is Agilio Padua at Universite
Blaise Pascal Clermont-Ferrand (agilio.padua at univ-bpclermont.fr)
Contact him directly if you have questions.
----------
USER-INTEL package
------------------
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
Intel(R) Xeon Phi(TM) coprocessor.
See this section of the manual to get started:
:ref:`Section_accelerate <acc_9>`
The person who created this package is W. Michael Brown at Intel
(michael.w.brown at intel.com). Contact him directly if you have questions.
----------
USER-LB package
---------------
This package contains a LAMMPS implementation of a background
Lattice-Boltzmann fluid, which can be used to model MD particles
influenced by hydrodynamic forces.
See this doc page and its related commands to get started:
:doc:`fix lb/fluid <fix_lb_fluid>`
The people who created this package are Frances Mackay (fmackay at
uwo.ca) and Colin (cdennist at uwo.ca) Denniston, University of
Western Ontario. Contact them directly if you have questions.
----------
USER-MISC package
-----------------
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 (*.cpp and *.h).
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:
:ref:`Section_commands <cmd_5>`
User-contributed features are listed at the bottom of the fix,
compute, pair, etc sections.
The list of features and author of each is given in the
src/USER-MISC/README file.
You should contact the author directly if you have specific questions
about the feature or its coding.
----------
USER-MOLFILE package
--------------------
This package contains a dump molfile command which uses molfile
plugins that are bundled with the
`VMD <http://www.ks.uiuc.edu/Research/vmd>`_ molecular visualization and
analysis program, to enable LAMMPS to dump its information in formats
compatible with various molecular simulation tools.
The package only provides the interface code, not the plugins. These
can be obtained from a VMD installation which has to match the
platform that you are using to compile LAMMPS for. By adding plugins
to VMD, support for new file formats can be added to LAMMPS (or VMD or
other programs that use them) without having to recompile the
application itself.
See this doc page to get started:
:ref:`dump molfile <acc_5>`
The person who created this package is Axel Kohlmeyer at Temple U
(akohlmey at gmail.com). Contact him directly if you have questions.
----------
USER-OMP package
----------------
This package provides OpenMP multi-threading support and
other optimizations of various LAMMPS pair styles, dihedral
styles, and fix styles.
See this section of the manual to get started:
:ref:`Section_accelerate <acc_5>`
The person who created this package is Axel Kohlmeyer at Temple U
(akohlmey at gmail.com). Contact him directly if you have questions.
----------
USER-PHONON package
-------------------
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.
See this doc page to get started:
:doc:`fix phonon <fix_phonon>`
The person who created this package is Ling-Ti Kong (konglt at
sjtu.edu.cn) at Shanghai Jiao Tong University. Contact him directly
if you have questions.
----------
USER-QMMM package
-----------------
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 `Quantum ESPRESSO <espresso_>`_ package.
.. _espresso: http://www.quantum-espresso.org
The current implementation only supports an ONIOM style mechanical
coupling to the Quantum ESPRESSO plane wave DFT package.
Electrostatic coupling is in preparation and the interface has been
written in a manner that coupling to other QM codes should be possible
without changes to LAMMPS itself.
See this doc page to get started:
:doc:`fix qmmm <fix_qmmm>`
as well as the lib/qmmm/README file.
The person who created this package is Axel Kohlmeyer at Temple U
(akohlmey at gmail.com). Contact him directly if you have questions.
----------
USER-QTB package
----------------
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
point energy into the system, alter the energy power spectrum and the
heat capacity towards their quantum nature. This package could be of
interest if one wants to model systems at temperatures lower than
their classical limits or when temperatures ramp up across the
classical limits in the simulation.
See these two doc pages to get started:
:doc:`fix qtb <fix_qtb>` provides quantum nulcear correction through a
colored thermostat and can be used with other time integration schemes
like :doc:`fix nve <fix_nve>` or :doc:`fix nph <fix_nh>`.
:doc:`fix qbmsst <fix_qbmsst>` enables quantum nuclear correction of a
multi-scale shock technique simulation by coupling the quantum thermal
bath with the shocked system.
The person who created this package is Yuan Shen (sy0302 at
stanford.edu) at Stanford University. Contact him directly if you
have questions.
----------
USER-REAXC package
------------------
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
energy. It was originally developed by Adri van Duin and the Goddard
group at CalTech.
The USER-REAXC version of ReaxFF (pair_style reax/c), implemented in
C, should give identical or very similar results to pair_style reax,
which is a ReaxFF implementation on top of a Fortran library, a
version of which library was originally authored by Adri van Duin.
The reax/c version should be somewhat faster and more scalable,
particularly with respect to the charge equilibration calculation. It
should also be easier to build and use since there are no complicating
issues with Fortran memory allocation or linking to a Fortran library.
For technical details about this implemention of ReaxFF, see
this paper:
Parallel and Scalable Reactive Molecular Dynamics: Numerical Methods
and Algorithmic Techniques, H. M. Aktulga, J. C. Fogarty,
S. A. Pandit, A. Y. Grama, Parallel Computing, in press (2011).
See the doc page for the pair_style reax/c command for details
of how to use it in LAMMPS.
The person who created this package is Hasan Metin Aktulga (hmaktulga
at lbl.gov), while at Purdue University. Contact him directly, or
Aidan Thompson at Sandia (athomps at sandia.gov), if you have
questions.
----------
USER-SPH package
----------------
This package implements smoothed particle hydrodynamics (SPH) in
LAMMPS. Currently, the package has the following features:
* Tait, ideal gas, Lennard-Jones equation of states, full support for
complete (i.e. internal-energy dependent) equations of state
* plain or Monaghans XSPH integration of the equations of motion
* density continuity or density summation to propagate the density field
* commands to set internal energy and density of particles from the
input script
* output commands to access internal energy and density for dumping and
thermo output
See the file doc/USER/sph/SPH_LAMMPS_userguide.pdf to get started.
There are example scripts for using this package in examples/USER/sph.
The person who created this package is Georg Ganzenmuller at the
Fraunhofer-Institute for High-Speed Dynamics, Ernst Mach Institute in
Germany (georg.ganzenmueller at emi.fhg.de). Contact him directly if
you have questions.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

74
doc/_sources/Section_perf.txt
View File

@ -1,74 +0,0 @@
Performance & scalability
=========================
LAMMPS performance on several prototypical benchmarks and machines is
discussed on the Benchmarks page of the `LAMMPS WWW Site <lws_>`_ where
CPU timings and parallel efficiencies are listed. Here, the
benchmarks are described briefly and some useful rules of thumb about
their performance are highlighted.
These are the 5 benchmark problems:
#. LJ = atomic fluid, Lennard-Jones potential with 2.5 sigma cutoff (55
neighbors per atom), NVE integration
#. Chain = bead-spring polymer melt of 100-mer chains, FENE bonds and LJ
pairwise interactions with a 2^(1/6) sigma cutoff (5 neighbors per
atom), NVE integration
#. EAM = metallic solid, Cu EAM potential with 4.95 Angstrom cutoff (45
neighbors per atom), NVE integration
#. Chute = granular chute flow, frictional history potential with 1.1
sigma cutoff (7 neighbors per atom), NVE integration
#. Rhodo = rhodopsin protein in solvated lipid bilayer, CHARMM force
field with a 10 Angstrom LJ cutoff (440 neighbors per atom),
particle-particle particle-mesh (PPPM) for long-range Coulombics, NPT
integration
The input files for running the benchmarks are included in the LAMMPS
distribution, as are sample output files. Each of the 5 problems has
32,000 atoms and runs for 100 timesteps. Each can be run as a serial
benchmarks (on one processor) or in parallel. In parallel, each
benchmark can be run as a fixed-size or scaled-size problem. For
fixed-size benchmarking, the same 32K atom problem is run on various
numbers of processors. For scaled-size benchmarking, the model size
is increased with the number of processors. E.g. on 8 processors, a
256K-atom problem is run; on 1024 processors, a 32-million atom
problem is run, etc.
A useful metric from the benchmarks is the CPU cost per atom per
timestep. Since LAMMPS performance scales roughly linearly with
problem size and timesteps, the run time of any problem using the same
model (atom style, force field, cutoff, etc) can then be estimated.
For example, on a 1.7 GHz Pentium desktop machine (Intel icc compiler
under Red Hat Linux), the CPU run-time in seconds/atom/timestep for
the 5 problems is
+----------------+---------+---------+---------+---------+-----------+
| Problem: | LJ | Chain | EAM | Chute | Rhodopsin |
+----------------+---------+---------+---------+---------+-----------+
| CPU/atom/step: | 4.55E-6 | 2.18E-6 | 9.38E-6 | 2.18E-6 | 1.11E-4 |
+----------------+---------+---------+---------+---------+-----------+
| Ratio to LJ: | 1.0 | 0.48 | 2.06 | 0.48 | 24.5 |
+----------------+---------+---------+---------+---------+-----------+
The ratios mean that if the atomic LJ system has a normalized cost of
1.0, the bead-spring chains and granular systems run 2x faster, while
the EAM metal and solvated protein models run 2x and 25x slower
respectively. The bulk of these cost differences is due to the
expense of computing a particular pairwise force field for a given
number of neighbors per atom.
Performance on a parallel machine can also be predicted from the
one-processor timings if the parallel efficiency can be estimated.
The communication bandwidth and latency of a particular parallel
machine affects the efficiency. On most machines LAMMPS will give
fixed-size parallel efficiencies on these benchmarks above 50% so long
as the atoms/processor count is a few 100 or greater - i.e. on 64 to
128 processors. Likewise, scaled-size parallel efficiencies will
typically be 80% or greater up to very large processor counts. The
benchmark data on the `LAMMPS WWW Site <lws_>`_ gives specific examples on
some different machines, including a run of 3/4 of a billion LJ atoms
on 1500 processors that ran at 85% parallel efficiency.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

917
doc/_sources/Section_python.txt
View File

@ -1,917 +0,0 @@
Python interface to LAMMPS
==========================
LAMMPS can work together with Python in two ways. First, Python can
wrap LAMMPS through the :ref:`LAMMPS library interface <howto_19>`, so that a Python script can
create one or more instances of LAMMPS and launch one or more
simulations. In Python lingo, this is "extending" Python with LAMMPS.
Second, LAMMPS can use the Python interpreter, so that a LAMMPS input
script can invoke Python code, and pass information back-and-forth
between the input script and Python functions you write. The Python
code can also callback to LAMMPS to query or change its attributes.
In Python lingo, this is "embedding" Python in LAMMPS.
This section describes how to do both.
* 11.1 :ref:`Overview of running LAMMPS from Python <py_1>`
* 11.2 :ref:`Overview of using Python from a LAMMPS script <py_2>`
* 11.3 :ref:`Building LAMMPS as a shared library <py_3>`
* 11.4 :ref:`Installing the Python wrapper into Python <py_4>`
* 11.5 :ref:`Extending Python with MPI to run in parallel <py_5>`
* 11.6 :ref:`Testing the Python-LAMMPS interface <py_6>`
* 11.7 :ref:`Using LAMMPS from Python <py_7>`
* 11.8 :ref:`Example Python scripts that use LAMMPS <py_8>`
If you are not familiar with it, `Python <http://www.python.org>`_ is a
powerful scripting and programming language which can essentially do
anything that faster, lower-level languages like C or C++ can do, but
typically with much fewer lines of code. When used in embedded mode,
Python can perform operations that the simplistic LAMMPS input script
syntax cannot. Python can be also be used as a "glue" language to
drive a program through its library interface, or to hook multiple
pieces of software together, such as a simulation package plus a
visualization package, or to run a coupled multiscale or multiphysics
model.
See :ref:`Section_howto 10 <howto_10>` of the manual and
the couple directory of the distribution for more ideas about coupling
LAMMPS to other codes. See :ref:`Section_howto 19 <howto_19>` for a description of the LAMMPS
library interface provided in src/library.cpp and src/library.h, and
how to extend it for your needs. As described below, that interface
is what is exposed to Python either when calling LAMMPS from Python or
when calling Python from a LAMMPS input script and then calling back
to LAMMPS from Python code. The library interface is designed to be
easy to add functions to. Thus the Python interface to LAMMPS is also
easy to extend as well.
If you create interesting Python scripts that run LAMMPS or
interesting Python functions that can be called from a LAMMPS input
script, that you think would be useful to other users, please `email them to the developers <http://lammps.sandia.gov/authors.html>`_. We can
include them in the LAMMPS distribution.
.. _py_1:
Overview of running LAMMPS from Python
--------------------------------------
The LAMMPS distribution includes a python directory with all you need
to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS
library interface, with one wrapper function per LAMMPS library
function. This file makes it is possible to do the following either
from a Python script, or interactively from a Python prompt: create
one or more instances of LAMMPS, invoke LAMMPS commands or give it an
input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do
this in serial or parallel. Running Python interactively in parallel
does not generally work, unless you have a version of Python that
extends standard Python to enable multiple instances of Python to read
what you type.
To do all of this, you must first build LAMMPS as a shared library,
then insure that your Python can find the python/lammps.py file and
the shared library. These steps are explained in subsequent sections
11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a
parallel Python program and how to test that you are ready to use
LAMMPS from Python. Section 11.7 lists all the functions in the
current LAMMPS library interface and how to call them from Python.
Section 11.8 gives some examples of coupling LAMMPS to other tools via
Python. For example, LAMMPS can easily be coupled to a GUI or other
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.
Two advantages of using Python to run LAMMPS are how concise the
language is, and that it can be run interactively, enabling rapid
development and debugging of programs. If you use it to mostly invoke
costly operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.
The Python wrapper for LAMMPS uses the amazing and magical (to me)
"ctypes" package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
Ctypes is part of standard Python for versions 2.5 and later. You can
check which version of Python you have installed, by simply typing
"python" at a shell prompt.
----------
.. _py_2:
Overview of using Python from a LAMMPS script
---------------------------------------------
.. warning::
It is not currently possible to use the
:doc:`python <python>` command described in this section with Python 3,
only with Python 2. The C API changed from Python 2 to 3 and the
LAMMPS code is not compatible with both.
LAMMPS has a :doc:`python <python>` command which can be used in an
input script to define and execute a Python function that you write
the code for. The Python function can also be assigned to a LAMMPS
python-style variable via the :doc:`variable <variable>` command. Each
time the variable is evaluated, either in the LAMMPS input script
itself, or by another LAMMPS command that uses the variable, this will
trigger the Python function to be invoked.
The Python code for the function can be included directly in the input
script or in an auxiliary file. The function can have arguments which
are mapped to LAMMPS variables (also defined in the input script) and
it can return a value to a LAMMPS variable. This is thus a mechanism
for your input script to pass information to a piece of Python code,
ask Python to execute the code, and return information to your input
script.
Note that a Python function can be arbitrarily complex. It can import
other Python modules, instantiate Python classes, call other Python
functions, etc. The Python code that you provide can contain more
code than the single function. It can contain other functions or
Python classes, as well as global variables or other mechanisms for
storing state between calls from LAMMPS to the function.
The Python function you provide can consist of "pure" Python code that
only performs operations provided by standard Python. However, the
Python function can also "call back" to LAMMPS through its
Python-wrapped library interface, in the manner described in the
previous section 11.1. This means it can issue LAMMPS input script
commands or query and set internal LAMMPS state. As an example, this
can be useful in an input script to create a more complex loop with
branching logic, than can be created using the simple looping and
brancing logic enabled by the :doc:`next <next>` and :doc:`if <if>`
commands.
See the :doc:`python <python>` doc page and the :doc:`variable <variable>`
doc page for its python-style variables for more info, including
examples of Python code you can write for both pure Python operations
and callbacks to LAMMPS.
To run pure Python code from LAMMPS, you only need to build LAMMPS
with the PYTHON package installed:
make yes-python
make machine
Note that this will link LAMMPS with the Python library on your
system, which typically requires several auxiliary system libraries to
also be linked. The list of these libraries and the paths to find
them are specified in the lib/python/Makefile.lammps file. You need
to insure that file contains the correct information for your version
of Python and your machine to successfully build LAMMPS. See the
lib/python/README file for more info.
If you want to write Python code with callbacks to LAMMPS, then you
must also follow the steps overviewed in the preceeding section (11.1)
for running LAMMPS from Python. I.e. you must build LAMMPS as a
shared library and insure that Python can find the python/lammps.py
file and the shared library.
----------
.. _py_3:
Building LAMMPS as a shared library
-----------------------------------
Instructions on how to build LAMMPS as a shared library are given in
:ref:`Section_start 5 <start_5>`. A shared library is one
that is dynamically loadable, which is what Python requires to wrap
LAMMPS. On Linux this is a library file that ends in ".so", not ".a".
>From the src directory, type
.. parsed-literal::
make foo mode=shlib
where foo is the machine target name, such as linux or g++ or serial.
This should create the file liblammps_foo.so in the src directory, as
well as a soft link liblammps.so, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.
If this fails, see :ref:`Section_start 5 <start_5>` for
more details, especially if your LAMMPS build uses auxiliary libraries
like MPI or FFTW which may not be built as shared libraries on your
system.
----------
.. _py_4:
Installing the Python wrapper into Python
-----------------------------------------
For Python to invoke LAMMPS, there are 2 files it needs to know about:
* python/lammps.py
* src/liblammps.so
Lammps.py is the Python wrapper on the LAMMPS library interface.
Liblammps.so is the shared LAMMPS library that Python loads, as
described above.
You can insure Python can find these files in one of two ways:
* set two environment variables
* run the python/install.py script
If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:
.. parsed-literal::
setenv PYTHONPATH $*PYTHONPATH*:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH $*LD_LIBRARY_PATH*:/home/sjplimp/lammps/src
If you use the python/install.py script, you need to invoke it every
time you rebuild LAMMPS (as a shared library) or make changes to the
python/lammps.py file.
You can invoke install.py from the python directory as
.. parsed-literal::
% python install.py [libdir] [pydir]
The optional libdir is where to copy the LAMMPS shared library to; the
default is /usr/local/lib. The optional pydir is where to copy the
lammps.py file to; the default is the site-packages directory of the
version of Python that is running the install script.
Note that libdir must be a location that is in your default
LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a
location that Python looks in by default for imported modules, like
its site-packages dir. If you want to copy these files to
non-standard locations, such as within your own user space, you will
need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables
accordingly, as above.
If the install.py script does not allow you to copy files into system
directories, prefix the python command with "sudo". If you do this,
make sure that the Python that root runs is the same as the Python you
run. E.g. you may need to do something like
.. parsed-literal::
% sudo /usr/local/bin/python install.py [libdir] [pydir]
You can also invoke install.py from the make command in the src
directory as
.. parsed-literal::
% make install-python
In this mode you cannot append optional arguments. Again, you may
need to prefix this with "sudo". In this mode you cannot control
which Python is invoked by root.
Note that if you want Python to be able to load different versions of
the LAMMPS shared library (see :ref:`this section <py_5>` below), you will
need to manually copy files like liblammps_g++.so into the appropriate
system directory. This is not needed if you set the LD_LIBRARY_PATH
environment variable as described above.
----------
.. _py_5:
Extending Python with MPI to run in parallel
--------------------------------------------
If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
make MPI calls directly from Python in your script, if you desire.
There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.
These include
* `pyMPI <http://pympi.sourceforge.net/>`_
* `maroonmpi <http://code.google.com/p/maroonmpi/>`_
* `mpi4py <http://code.google.com/p/mpi4py/>`_
* `myMPI <http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16>`_
* `Pypar <http://code.google.com/p/pypar>`_
All of these except pyMPI work by wrapping the MPI library and
exposing (some portion of) its interface to your Python script. This
means Python cannot be used interactively in parallel, since they do
not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of "python"
itself) as a result.
In principle any of these Python/MPI packages should work to invoke
LAMMPS in parallel and to make MPI calls themselves from a Python
script which is itself running in parallel. However, when I
downloaded and looked at a few of them, their documentation was
incomplete and I had trouble with their installation. It's not clear
if some of the packages are still being actively developed and
supported.
The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous `Numpy package <http://numpy.scipy.org>`_ be installed in your Python. After
launching python, type
.. parsed-literal::
import numpy
to see if it is installed. If not, here is how to install it (version
1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
top-level directory, type
.. parsed-literal::
python setup.py build
sudo python setup.py install
The "sudo" is only needed if required to copy Numpy files into your
Python distribution's site-packages directory.
To install Pypar (version pypar-2.1.4_94 as of Aug 2012), unpack it
and from its "source" directory, type
.. parsed-literal::
python setup.py build
sudo python setup.py install
Again, the "sudo" is only needed if required to copy Pypar files into
your Python distribution's site-packages directory.
If you have successully installed Pypar, you should be able to run
Python and type
.. parsed-literal::
import pypar
without error. You should also be able to run python in parallel
on a simple test script
.. parsed-literal::
% mpirun -np 4 python test.py
where test.py contains the lines
.. parsed-literal::
import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())
and see one line of output for each processor you run on.
.. warning::
To use Pypar and LAMMPS in parallel from Python, you
must insure both are using the same version of MPI. If you only have
one MPI installed on your system, this is not an issue, but it can be
if you have multiple MPIs. Your LAMMPS build is explicit about which
MPI it is using, since you specify the details in your lo-level
src/MAKE/Makefile.foo file. Pypar uses the "mpicc" command to find
information about the MPI it uses to build against. And it tries to
load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find
the MPI library that LAMMPS is using. If you have problems running
both Pypar and LAMMPS together, this is an issue you may need to
address, e.g. by moving other MPI installations so that Pypar finds
the right one.
----------
.. _py_6:
Testing the Python-LAMMPS interface
-----------------------------------
To test if LAMMPS is callable from Python, launch Python interactively
and type:
.. parsed-literal::
>>> from lammps import lammps
>>> lmp = lammps()
If you get no errors, you're ready to use LAMMPS from Python. If the
2nd command fails, the most common error to see is
.. parsed-literal::
OSError: Could not load LAMMPS dynamic library
which means Python was unable to load the LAMMPS shared library. This
typically occurs if the system can't find the LAMMPS shared library or
one of the auxiliary shared libraries it depends on, or if something
about the library is incompatible with your Python. The error message
should give you an indication of what went wrong.
You can also test the load directly in Python as follows, without
first importing from the lammps.py file:
.. parsed-literal::
>>> from ctypes import CDLL
>>> CDLL("liblammps.so")
If an error occurs, carefully go thru the steps in :ref:`Section_start 5 <start_5>` and above about building a shared
library and about insuring Python can find the necessary two files
it needs.
**Test LAMMPS and Python in serial:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run a LAMMPS test in serial, type these lines into Python
interactively from the bench directory:
.. parsed-literal::
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
Or put the same lines in the file test.py and run it as
.. parsed-literal::
% python test.py
Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:
.. parsed-literal::
lmp_g++ < in.lj
**Test LAMMPS and Python in parallel:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To run LAMMPS in parallel, assuming you have installed the
`Pypar <http://datamining.anu.edu.au/~ole/pypar>`_ package as discussed
above, create a test.py file containing these lines:
.. parsed-literal::
import pypar
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
pypar.finalize()
You can then run it in parallel as:
.. parsed-literal::
% mpirun -np 4 python test.py
and you should see the same output as if you had typed
.. parsed-literal::
% mpirun -np 4 lmp_g++ < in.lj
Note that if you leave out the 3 lines from test.py that specify Pypar
commands you will instantiate and run LAMMPS independently on each of
the P processors specified in the mpirun command. In this case you
should get 4 sets of output, each showing that a LAMMPS run was made
on a single processor, instead of one set of output showing that
LAMMPS ran on 4 processors. If the 1-processor outputs occur, it
means that Pypar is not working correctly.
Also note that once you import the PyPar module, Pypar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the Pypar documentation. The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.
**Running Python scripts:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
.. parsed-literal::
% python foo.script
% python -i foo.script
% foo.script
The last command requires that the first line of the script be
something like this:
.. parsed-literal::
#!/usr/local/bin/python
#!/usr/local/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
.. parsed-literal::
% chmod +x foo.script
Without the "-i" flag, Python will exit when the script finishes.
With the "-i" flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.
.. _py_7:
Using LAMMPS from Python
------------------------
As described above, the Python interface to LAMMPS consists of a
Python "lammps" module, the source code for which is in
python/lammps.py, which creates a "lammps" object, with a set of
methods that can be invoked on that object. The sample Python code
below assumes you have first imported the "lammps" module in your
Python script, as follows:
.. parsed-literal::
from lammps import lammps
These are the methods defined by the lammps module. If you look at
the files src/library.cpp and src/library.h you will see that they
correspond one-to-one with calls you can make to the LAMMPS library
from a C++ or C or Fortran program.
.. parsed-literal::
lmp = lammps() # create a LAMMPS object using the default liblammps.so library
lmp = lammps(ptr=lmpptr) # ditto, but use lmpptr as previously created LAMMPS object
lmp = lammps("g++") # create a LAMMPS object using the liblammps_g++.so library
lmp = lammps("",list) # ditto, with command-line args, e.g. list = ["-echo","screen"]
lmp = lammps("g++",list)
.. parsed-literal::
lmp.close() # destroy a LAMMPS object
.. parsed-literal::
lmp.file(file) # run an entire input script, file = "in.lj"
lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100"
.. parsed-literal::
xlo = lmp.extract_global(name,type) # extract a global quantity
# name = "boxxlo", "nlocal", etc
# type = 0 = int
# 1 = double
.. parsed-literal::
coords = lmp.extract_atom(name,type) # extract a per-atom quantity
# name = "x", "type", etc
# type = 0 = vector of ints
# 1 = array of ints
# 2 = vector of doubles
# 3 = array of doubles
.. parsed-literal::
eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute
v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix
# id = ID of compute or fix
# style = 0 = global data
# 1 = per-atom data
# 2 = local data
# type = 0 = scalar
# 1 = vector
# 2 = array
# i,j = indices of value in global vector or array
.. parsed-literal::
var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable
# name = name of variable
# group = group ID (ignored for equal-style variables)
# flag = 0 = equal-style variable
# 1 = atom-style variable
.. parsed-literal::
flag = lmp.set_variable(name,value) # set existing named string-style variable to value, flag = 0 if successful
natoms = lmp.get_natoms() # total # of atoms as int
data = lmp.gather_atoms(name,type,count) # return atom attribute of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms(name,type,count,data) # scatter atom attribute of all atoms from data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
----------
.. warning::
Currently, the creation of a LAMMPS object from within
lammps.py does not take an MPI communicator as an argument. There
should be a way to do this, so that the LAMMPS instance runs on a
subset of processors if desired, but I don't know how to do it from
Pypar. So for now, it runs with MPI_COMM_WORLD, which is all the
processors. If someone figures out how to do this with one or more of
the Python wrappers for MPI, like Pypar, please let us know and we
will amend these doc pages.
The lines
.. parsed-literal::
from lammps import lammps
lmp = lammps()
create an instance of LAMMPS, wrapped in a Python class by the lammps
Python module, and return an instance of the Python class as lmp. It
is used to make all subequent calls to the LAMMPS library.
Additional arguments can be used to tell Python the name of the shared
library to load or to pass arguments to the LAMMPS instance, the same
as if LAMMPS were launched from a command-line prompt.
If the ptr argument is set like this:
.. parsed-literal::
lmp = lammps(ptr=lmpptr)
then lmpptr must be an argument passed to Python via the LAMMPS
:doc:`python <python>` command, when it is used to define a Python
function that is invoked by the LAMMPS input script. This mode of
using Python with LAMMPS is described above in 11.2. The variable
lmpptr refers to the instance of LAMMPS that called the embedded
Python interpreter. Using it as an argument to lammps() allows the
returned Python class instance "lmp" to make calls to that instance of
LAMMPS. See the :doc:`python <python>` command doc page for examples
using this syntax.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
.. parsed-literal::
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")
The file() and command() methods allow an input script or single
commands to be invoked.
The extract_global(), extract_atom(), extract_compute(),
extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LAMMPS.
For extract_global() see the src/library.cpp file for the list of
valid names. New names could easily be added. A double or integer is
returned. You need to specify the appropriate data type via the type
argument.
For extract_atom(), a pointer to internal LAMMPS atom-based data is
returned, which you can use via normal Python subscripting. See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added. A pointer to a vector of
doubles or integers, or a pointer to an array of doubles (double **)
or integers (int **) is returned. You need to specify the appropriate
data type via the type argument.
For extract_compute() and extract_fix(), the global, per-atom, or
local data calulated by the compute or fix can be accessed. What is
returned depends on whether the compute or fix calculates a scalar or
vector or array. For a scalar, a single double value is returned. If
the compute or fix calculates a vector or array, a pointer to the
internal LAMMPS data is returned, which you can use via normal Python
subscripting. The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices. The I,J arguments can be left out if not needed.
See :ref:`Section_howto 15 <howto_15>` of the manual for a
discussion of global, per-atom, and local data, and of scalar, vector,
and array data types. See the doc pages for individual
:doc:`computes <compute>` and :doc:`fixes <fix>` for a description of what
they calculate and store.
For extract_variable(), an :doc:`equal-style or atom-style variable <variable>` is evaluated and its result returned.
For equal-style variables a single double value is returned and the
group argument is ignored. For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
The get_natoms() method returns the total number of atoms in the
simulation, as an int.
The gather_atoms() method returns a ctypes vector of ints or doubles
as specified by type, of length count*natoms, for the property of all
the atoms in the simulation specified by name, ordered by count and
then by atom ID. The vector can be used via normal Python
subscripting. If atom IDs are not consecutively ordered within
LAMMPS, a None is returned as indication of an error.
Note that the data structure gather_atoms("x") returns is different
from the data structure returned by extract_atom("x") in four ways.
(1) Gather_atoms() returns a vector which you index as x[i];
extract_atom() returns an array which you index as x[i][j]. (2)
Gather_atoms() orders the atoms by atom ID while extract_atom() does
not. (3) Gathert_atoms() returns a list of all atoms in the
simulation; extract_atoms() returns just the atoms local to each
processor. (4) Finally, the gather_atoms() data structure is a copy
of the atom coords stored internally in LAMMPS, whereas extract_atom()
returns an array that effectively points directly to the internal
data. This means you can change values inside LAMMPS from Python by
assigning a new values to the extract_atom() array. To do this with
the gather_atoms() vector, you need to change values in the vector,
then invoke the scatter_atoms() method.
The scatter_atoms() method takes a vector of ints or doubles as
specified by type, of length count*natoms, for the property of all the
atoms in the simulation specified by name, ordered by bount and then
by atom ID. It uses the vector of data to overwrite the corresponding
properties for each atom inside LAMMPS. This requires LAMMPS to have
its "map" option enabled; see the :doc:`atom_modify <atom_modify>`
command for details. If it is not, or if atom IDs are not
consecutively ordered, no coordinates are reset.
The array of coordinates passed to scatter_atoms() must be a ctypes
vector of ints or doubles, allocated and initialized something like
this:
.. parsed-literal::
from ctypes import *
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_coords("x",1,3,x)
Alternatively, you can just change values in the vector returned by
gather_atoms("x",1,3), since it is a ctypes vector of doubles.
----------
As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in src/library.cpp and
library.h. This means you can extend the Python wrapper via the
following steps:
* Add a new interface function to src/library.cpp and
src/library.h.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to python/lammps.py for this interface
function.
* You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing?
.. _py_8:
Example Python scripts that use LAMMPS
--------------------------------------
These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of
things that are possible when Python wraps LAMMPS. If you create your
own scripts, send them to us and we can include them in the LAMMPS
distribution.
+--------------------+-------------------------------------------------------+
| trivial.py | read/run a LAMMPS input script thru Python |
+--------------------+-------------------------------------------------------+
| demo.py | invoke various LAMMPS library interface routines |
+--------------------+-------------------------------------------------------+
| simple.py | mimic operation of couple/simple/simple.cpp in Python |
+--------------------+-------------------------------------------------------+
| gui.py | GUI go/stop/temperature-slider to control LAMMPS |
+--------------------+-------------------------------------------------------+
| plot.py | real-time temeperature plot with GnuPlot via Pizza.py |
+--------------------+-------------------------------------------------------+
| viz_tool.py | real-time viz via some viz package |
+--------------------+-------------------------------------------------------+
| vizplotgui_tool.py | combination of viz_tool.py and plot.py and gui.py |
+--------------------+-------------------------------------------------------+
----------
For the viz_tool.py and vizplotgui_tool.py commands, replace "tool"
with "gl" or "atomeye" or "pymol" or "vmd", depending on what
visualization package you have installed.
Note that for GL, you need to be able to run the Pizza.py GL tool,
which is included in the pizza sub-directory. See the `Pizza.py doc pages <pizza_>`_ for more info:
.. _pizza: http://www.sandia.gov/~sjplimp/pizza.html
Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye WWW pages `here <atomeye_>`_ or `here <atomeye3_>`_ for more details:
.. parsed-literal::
http://mt.seas.upenn.edu/Archive/Graphics/A
http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html
.. _atomeye: http://mt.seas.upenn.edu/Archive/Graphics/A
.. _atomeye3: http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html
The latter link is to AtomEye 3 which has the scriping
capability needed by these Python scripts.
Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script. See the PyMol WWW pages `here <pymol_>`_ or
`here <pymolopen_>`_ for more details:
.. parsed-literal::
http://www.pymol.org
http://sourceforge.net/scm/?type=svn&group_id=4546
.. _pymol: http://www.pymol.org
.. _pymolopen: http://sourceforge.net/scm/?type=svn&group_id=4546
The latter link is to the open-source version.
Note that for VMD, you need a fairly current version (1.8.7 works for
me) and there are some lines in the pizza/vmd.py script for 4 PIZZA
variables that have to match the VMD installation on your system.
----------
See the python/README file for instructions on how to run them and the
source code for individual scripts for comments about what they do.
Here are screenshots of the vizplotgui_tool.py script in action for
different visualization package options. Click to see larger images:
.. thumbnail:: JPG/screenshot_gl.jpg
.. thumbnail:: JPG/screenshot_atomeye.jpg
.. thumbnail:: JPG/screenshot_pymol.jpg
.. thumbnail:: JPG/screenshot_vmd.jpg
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

2070
doc/_sources/Section_start.txt
View File

File diff suppressed because it is too large Load Diff

737
doc/_sources/Section_tools.txt
View File

@ -1,737 +0,0 @@
Additional tools
================
LAMMPS is designed to be a computational kernel for performing
molecular dynamics computations. Additional pre- and post-processing
steps are often necessary to setup and analyze a simulation. A few
additional tools are provided with the LAMMPS distribution and are
described in this section.
Our group has also written and released a separate toolkit called
`Pizza.py <pizza_>`_ which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in `Python <python_>`_ and is available for download from `the Pizza.py WWW site <pizza_>`_.
.. _pizza: http://www.sandia.gov/~sjplimp/pizza.html
.. _python: http://www.python.org
Note that many users write their own setup or analysis tools or use
other existing codes and convert their output to a LAMMPS input format
or vice versa. The tools listed here are included in the LAMMPS
distribution as examples of auxiliary tools. Some of them are not
actively supported by Sandia, as they were contributed by LAMMPS
users. If you have problems using them, we can direct you to the
authors.
The source code for each of these codes is in the tools sub-directory
of the LAMMPS distribution. There is a Makefile (which you may need
to edit for your platform) which will build several of the tools which
reside in that directory. Some of them are larger packages in their
own sub-directories with their own Makefiles.
* :ref:`amber2lmp <amber>`
* :ref:`binary2txt <binary>`
* :ref:`ch2lmp <charmm>`
* :ref:`chain <chain>`
* :ref:`colvars <colvars>`
* :ref:`createatoms <create>`
* :ref:`data2xmovie <data>`
* :ref:`eam database <eamdb>`
* :ref:`eam generate <eamgn>`
* :ref:`eff <eff>`
* :ref:`emacs <emacs>`
* :ref:`fep <fep>`
* :ref:`i-pi <ipi>`
* :ref:`ipp <ipp>`
* :ref:`kate <kate>`
* :ref:`lmp2arc <arc>`
* :ref:`lmp2cfg <cfg>`
* :ref:`lmp2vmd <vmd>`
* :ref:`matlab <matlab>`
* :ref:`micelle2d <micelle>`
* :ref:`moltemplate <moltemplate>`
* :ref:`msi2lmp <msi>`
* :ref:`phonon <phonon>`
* :ref:`polymer bonding <polybond>`
* :ref:`pymol_asphere <pymol>`
* :ref:`python <pythontools>`
* :ref:`reax <reax>`
* :ref:`restart2data <restart>`
* :ref:`vim <vim>`
* :ref:`xmgrace <xmgrace>`
* :ref:`xmovie <xmovie>`
----------
.. _amber:
amber2lmp tool
--------------------------
The amber2lmp sub-directory contains two Python scripts for converting
files back-and-forth between the AMBER MD code and LAMMPS. See the
README file in amber2lmp for more information.
These tools were written by Keir Novik while he was at Queen Mary
University of London. Keir is no longer there and cannot support
these tools which are out-of-date with respect to the current LAMMPS
version (and maybe with respect to AMBER as well). Since we don't use
these tools at Sandia, you'll need to experiment with them and make
necessary modifications yourself.
----------
.. _binary:
binary2txt tool
----------------------------
The file binary2txt.cpp converts one or more binary LAMMPS dump file
into ASCII text files. The syntax for running the tool is
.. parsed-literal::
binary2txt file1 file2 ...
which creates file1.txt, file2.txt, etc. This tool must be compiled
on a platform that can read the binary file created by a LAMMPS run,
since binary files are not compatible across all platforms.
----------
.. _charmm:
ch2lmp tool
------------------------
The ch2lmp sub-directory contains tools for converting files
back-and-forth between the CHARMM MD code and LAMMPS.
They are intended to make it easy to use CHARMM as a builder and as a
post-processor for LAMMPS. Using charmm2lammps.pl, you can convert an
ensemble built in CHARMM into its LAMMPS equivalent. Using
lammps2pdb.pl you can convert LAMMPS atom dumps into pdb files.
See the README file in the ch2lmp sub-directory for more information.
These tools were created by Pieter in't Veld (pjintve at sandia.gov)
and Paul Crozier (pscrozi at sandia.gov) at Sandia.
----------
.. _chain:
chain tool
----------------------
The file chain.f creates a LAMMPS data file containing bead-spring
polymer chains and/or monomer solvent atoms. It uses a text file
containing chain definition parameters as an input. The created
chains and solvent atoms can strongly overlap, so LAMMPS needs to run
the system initially with a "soft" pair potential to un-overlap it.
The syntax for running the tool is
.. parsed-literal::
chain < def.chain > data.file
See the def.chain or def.chain.ab files in the tools directory for
examples of definition files. This tool was used to create the
system for the :doc:`chain benchmark <Section_perf>`.
----------
.. _colvars:
colvars tools
---------------------------
The colvars directory contains a collection of tools for postprocessing
data produced by the colvars collective variable library.
To compile the tools, edit the makefile for your system and run "make".
Please report problems and issues the colvars library and its tools
at: https://github.com/colvars/colvars/issues
abf_integrate:
MC-based integration of multidimensional free energy gradient
Version 20110511
.. parsed-literal::
Syntax: ./abf_integrate < filename > [-n < nsteps >] [-t < temp >] [-m [0|1] (metadynamics)] [-h < hill_height >] [-f < variable_hill_factor >]
The LAMMPS interface to the colvars collective variable library, as
well as these tools, were created by Axel Kohlmeyer (akohlmey at
gmail.com) at ICTP, Italy.
----------
.. _create:
createatoms tool
-----------------------------
The tools/createatoms directory contains a Fortran program called
createAtoms.f which can generate a variety of interesting crystal
structures and geometries and output the resulting list of atom
coordinates in LAMMPS or other formats.
See the included Manual.pdf for details.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.
----------
.. _data:
data2xmovie tool
---------------------------
The file data2xmovie.c converts a LAMMPS data file into a snapshot
suitable for visualizing with the :ref:`xmovie <xmovie>` tool, as if it had
been output with a dump command from LAMMPS itself. The syntax for
running the tool is
.. parsed-literal::
data2xmovie [options] < infile > outfile
See the top of the data2xmovie.c file for a discussion of the options.
----------
.. _eamdb:
eam database tool
-----------------------------
The tools/eam_database directory contains a Fortran program that will
generate EAM alloy setfl potential files for any combination of 16
elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
Zr. The files can then be used with the :doc:`pair_style eam/alloy <pair_eam>` command.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
and is based on his paper:
X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
144113 (2004).
----------
.. _eamgn:
eam generate tool
-----------------------------
The tools/eam_generate directory contains several one-file C programs
that convert an analytic formula into a tabulated :doc:`embedded atom method (EAM) <pair_eam>` setfl potential file. The potentials they
produce are in the potentials directory, and can be used with the
:doc:`pair_style eam/alloy <pair_eam>` command.
The source files and potentials were provided by Gerolf Ziegenhain
(gerolf at ziegenhain.com).
----------
.. _eff:
eff tool
------------------
The tools/eff directory contains various scripts for generating
structures and post-processing output for simulations using the
electron force field (eFF).
These tools were provided by Andres Jaramillo-Botero at CalTech
(ajaramil at wag.caltech.edu).
----------
.. _emacs:
emacs tool
----------------------
The tools/emacs directory contains a Lips add-on file for Emacs that
enables a lammps-mode for editing of input scripts when using Emacs,
with various highlighting options setup.
These tools were provided by Aidan Thompson at Sandia
(athomps at sandia.gov).
----------
.. _fep:
fep tool
------------------
The tools/fep directory contains Python scripts useful for
post-processing results from performing free-energy perturbation
simulations using the USER-FEP package.
The scripts were contributed by Agilio Padua (Universite Blaise
Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
See README file in the tools/fep directory.
----------
.. _ipi:
i-pi tool
-------------------
The tools/i-pi directory contains a version of the i-PI package, with
all the LAMMPS-unrelated files removed. It is provided so that it can
be used with the :doc:`fix ipi <fix_ipi>` command to perform
path-integral molecular dynamics (PIMD).
The i-PI package was created and is maintained by Michele Ceriotti,
michele.ceriotti at gmail.com, to interface to a variety of molecular
dynamics codes.
See the tools/i-pi/manual.pdf file for an overview of i-PI, and the
:doc:`fix ipi <fix_ipi>` doc page for further details on running PIMD
calculations with LAMMPS.
----------
.. _ipp:
ipp tool
------------------
The tools/ipp directory contains a Perl script ipp which can be used
to facilitate the creation of a complicated file (say, a lammps input
script or tools/createatoms input file) using a template file.
ipp was created and is maintained by Reese Jones (Sandia), rjones at
sandia.gov.
See two examples in the tools/ipp directory. One of them is for the
tools/createatoms tool's input file.
----------
.. _kate:
kate tool
--------------------
The file in the tools/kate directory is an add-on to the Kate editor
in the KDE suite that allow syntax highlighting of LAMMPS input
scripts. See the README.txt file for details.
The file was provided by Alessandro Luigi Sellerio
(alessandro.sellerio at ieni.cnr.it).
----------
.. _arc:
lmp2arc tool
----------------------
The lmp2arc sub-directory contains a tool for converting LAMMPS output
files to the format for Accelrys' Insight MD code (formerly
MSI/Biosym and its Discover MD code). See the README file for more
information.
This tool was written by John Carpenter (Cray), Michael Peachey
(Cray), and Steve Lustig (Dupont). John is now at the Mayo Clinic
(jec at mayo.edu), but still fields questions about the tool.
This tool was updated for the current LAMMPS C++ version by Jeff
Greathouse at Sandia (jagreat at sandia.gov).
----------
.. _cfg:
lmp2cfg tool
----------------------
The lmp2cfg sub-directory contains a tool for converting LAMMPS output
files into a series of *.cfg files which can be read into the
`AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_ visualizer. See
the README file for more information.
This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).
----------
.. _vmd:
lmp2vmd tool
----------------------
The lmp2vmd sub-directory contains a README.txt file that describes
details of scripts and plugin support within the `VMD package <http://www.ks.uiuc.edu/Research/vmd>`_ for visualizing LAMMPS
dump files.
The VMD plugins and other supporting scripts were written by Axel
Kohlmeyer (akohlmey at cmm.chem.upenn.edu) at U Penn.
----------
.. _matlab:
matlab tool
------------------------
The matlab sub-directory contains several :ref:`MATLAB <matlab>` scripts for
post-processing LAMMPS output. The scripts include readers for log
and dump files, a reader for EAM potential files, and a converter that
reads LAMMPS dump files and produces CFG files that can be visualized
with the `AtomEye <http://mt.seas.upenn.edu/Archive/Graphics/A>`_
visualizer.
See the README.pdf file for more information.
These scripts were written by Arun Subramaniyan at Purdue Univ
(asubrama at purdue.edu).
.. _matlab: http://www.mathworks.com
----------
.. _micelle:
micelle2d tool
----------------------------
The file micelle2d.f creates a LAMMPS data file containing short lipid
chains in a monomer solution. It uses a text file containing lipid
definition parameters as an input. The created molecules and solvent
atoms can strongly overlap, so LAMMPS needs to run the system
initially with a "soft" pair potential to un-overlap it. The syntax
for running the tool is
.. parsed-literal::
micelle2d < def.micelle2d > data.file
See the def.micelle2d file in the tools directory for an example of a
definition file. This tool was used to create the system for the
:doc:`micelle example <Section_example>`.
----------
.. _moltemplate:
moltemplate tool
----------------------------------
The moltemplate sub-directory contains a Python-based tool for
building molecular systems based on a text-file description, and
creating LAMMPS data files that encode their molecular topology as
lists of bonds, angles, dihedrals, etc. See the README.TXT file for
more information.
This tool was written by Andrew Jewett (jewett.aij at gmail.com), who
supports it. It has its own WWW page at
`http://moltemplate.org <http://moltemplate.org>`_.
----------
.. _msi:
msi2lmp tool
----------------------
The msi2lmp sub-directory contains a tool for creating LAMMPS input
data files from Accelrys' Insight MD code (formerly MSI/Biosym and
its Discover MD code). See the README file for more information.
This tool was written by John Carpenter (Cray), Michael Peachey
(Cray), and Steve Lustig (Dupont). John is now at the Mayo Clinic
(jec at mayo.edu), but still fields questions about the tool.
This tool may be out-of-date with respect to the current LAMMPS and
Insight versions. Since we don't use it at Sandia, you'll need to
experiment with it yourself.
----------
.. _phonon:
phonon tool
------------------------
The phonon sub-directory contains a post-processing tool useful for
analyzing the output of the :doc:`fix phonon <fix_phonon>` command in
the USER-PHONON package.
See the README file for instruction on building the tool and what
library it needs. And see the examples/USER/phonon directory
for example problems that can be post-processed with this tool.
This tool was written by Ling-Ti Kong at Shanghai Jiao Tong
University.
----------
.. _polybond:
polymer bonding tool
-----------------------------------
The polybond sub-directory contains a Python-based tool useful for
performing "programmable polymer bonding". The Python file
lmpsdata.py provides a "Lmpsdata" class with various methods which can
be invoked by a user-written Python script to create data files with
complex bonding topologies.
See the Manual.pdf for details and example scripts.
This tool was written by Zachary Kraus at Georgia Tech.
----------
.. _pymol:
pymol_asphere tool
------------------------------
The pymol_asphere sub-directory contains a tool for converting a
LAMMPS dump file that contains orientation info for ellipsoidal
particles into an input file for the :ref:`PyMol visualization package <pymol>`.
.. _pymol: http://pymol.sourceforge.net
Specifically, the tool triangulates the ellipsoids so they can be
viewed as true ellipsoidal particles within PyMol. See the README and
examples directory within pymol_asphere for more information.
This tool was written by Mike Brown at Sandia.
----------
.. _pythontools:
python tool
-----------------------------
The python sub-directory contains several Python scripts
that perform common LAMMPS post-processing tasks, such as:
* extract thermodynamic info from a log file as columns of numbers
* plot two columns of thermodynamic info from a log file using GnuPlot
* sort the snapshots in a dump file by atom ID
* convert multiple :doc:`NEB <neb>` dump files into one dump file for viz
* convert dump files into XYZ, CFG, or PDB format for viz by other packages
These are simple scripts built on `Pizza.py <pizza_>`_ modules. See the
README for more info on Pizza.py and how to use these scripts.
----------
.. _reax:
reax tool
--------------------
The reax sub-directory contains stand-alond codes that can
post-process the output of the :doc:`fix reax/bonds <fix_reax_bonds>`
command from a LAMMPS simulation using :doc:`ReaxFF <pair_reax>`. See
the README.txt file for more info.
These tools were written by Aidan Thompson at Sandia.
----------
.. _restart:
restart2data tool
-------------------------------
.. warning::
This tool is now obsolete and is not included in the
current LAMMPS distribution. This is becaues there is now a
:doc:`write_data <write_data>` command, which can create a data file
from within an input script. Running LAMMPS with the "-r"
:ref:`command-line switch <start_7>` as follows:
lmp_g++ -r restartfile datafile
is the same as running a 2-line input script:
read_restart restartfile
write_data datafile
which will produce the same data file that the restart2data tool used
to create. The following information is included in case you have an
older version of LAMMPS which still includes the restart2data tool.
The file restart2data.cpp converts a binary LAMMPS restart file into
an ASCII data file. The syntax for running the tool is
.. parsed-literal::
restart2data restart-file data-file (input-file)
Input-file is optional and if specified will contain LAMMPS input
commands for the masses and force field parameters, instead of putting
those in the data-file. Only a few force field styles currently
support this option.
This tool must be compiled on a platform that can read the binary file
created by a LAMMPS run, since binary files are not compatible across
all platforms.
Note that a text data file has less precision than a binary restart
file. Hence, continuing a run from a converted data file will
typically not conform as closely to a previous run as will restarting
from a binary restart file.
If a "%" appears in the specified restart-file, the tool expects a set
of multiple files to exist. See the :doc:`restart <restart>` and
:doc:`write_restart <write_restart>` commands for info on how such sets
of files are written by LAMMPS, and how the files are named.
----------
.. _vim:
vim tool
------------------
The files in the tools/vim directory are add-ons to the VIM editor
that allow easier editing of LAMMPS input scripts. See the README.txt
file for details.
These files were provided by Gerolf Ziegenhain (gerolf at
ziegenhain.com)
----------
.. _xmgrace:
xmgrace tool
--------------------------
The files in the tools/xmgrace directory can be used to plot the
thermodynamic data in LAMMPS log files via the xmgrace plotting
package. There are several tools in the directory that can be used in
post-processing mode. The lammpsplot.cpp file can be compiled and
used to create plots from the current state of a running LAMMPS
simulation.
See the README file for details.
These files were provided by Vikas Varshney (vv0210 at gmail.com)
----------
.. _xmovie:
xmovie tool
------------------------
The xmovie tool is an X-based visualization package that can read
LAMMPS dump files and animate them. It is in its own sub-directory
with the tools directory. You may need to modify its Makefile so that
it can find the appropriate X libraries to link against.
The syntax for running xmovie is
.. parsed-literal::
xmovie [options] dump.file1 dump.file2 ...
If you just type "xmovie" you will see a list of options. Note that
by default, LAMMPS dump files are in scaled coordinates, so you
typically need to use the -scale option with xmovie. When xmovie runs
it opens a visualization window and a control window. The control
options are straightforward to use.
Xmovie was mostly written by Mike Uttormark (U Wisconsin) while he
spent a summer at Sandia. It displays 2d projections of a 3d domain.
While simple in design, it is an amazingly fast program that can
render large numbers of atoms very quickly. It's a useful tool for
debugging LAMMPS input and output and making sure your simulation is
doing what you think it should. The animations on the Examples page
of the `LAMMPS WWW site <lws_>`_ were created with xmovie.
I've lost contact with Mike, so I hope he's comfortable with us
distributing his great tool!
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

223
doc/_sources/accelerate_cuda.txt
View File

@ -1,223 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-CUDA package
-------------------
The USER-CUDA package was developed by Christian Trott (Sandia) while
at U Technology Ilmenau in Germany. It provides NVIDIA GPU versions
of many pair styles, many fixes, a few computes, and for long-range
Coulombics via the PPPM command. It has the following general
features:
* The package is designed to allow an entire LAMMPS calculation, for
many timesteps, to run entirely on the GPU (except for inter-processor
MPI communication), so that atom-based data (e.g. coordinates, forces)
do not have to move back-and-forth between the CPU and GPU.
* The speed-up advantage of this approach is typically better when the
number of atoms per GPU is large
* Data will stay on the GPU until a timestep where a non-USER-CUDA fix
or compute is invoked. Whenever a non-GPU operation occurs (fix,
compute, output), data automatically moves back to the CPU as needed.
This may incur a performance penalty, but should otherwise work
transparently.
* Neighbor lists are constructed on the GPU.
* The package only supports use of a single MPI task, running on a
single CPU (core), assigned to each GPU.
Here is a quick overview of how to use the USER-CUDA package:
* build the library in lib/cuda for your GPU hardware with desired precision
* include the USER-CUDA package and build LAMMPS
* use the mpirun command to specify 1 MPI task per GPU (on each node)
* enable the USER-CUDA package via the "-c on" command-line switch
* specify the # of GPUs per node
* use USER-CUDA styles in your input script
The latter two steps can be done using the "-pk cuda" and "-sf cuda"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package cuda <package>` or :doc:`suffix cuda <suffix>` commands
respectively to your input script.
**Required hardware/software:**
To use this package, you need to have one or more NVIDIA GPUs and
install the NVIDIA Cuda software on your system:
Your NVIDIA GPU needs to support Compute Capability 1.3. This list may
help you to find out the Compute Capability of your card:
http://en.wikipedia.org/wiki/Comparison_of_Nvidia_graphics_processing_units
Install the Nvidia Cuda Toolkit (version 3.2 or higher) and the
corresponding GPU drivers. The Nvidia Cuda SDK is not required, but
we recommend it also be installed. You can then make sure its sample
projects can be compiled without problems.
**Building LAMMPS with the USER-CUDA package:**
This requires two steps (a,b): build the USER-CUDA library, then build
LAMMPS with the USER-CUDA package.
You can do both these steps in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, this
command will create src/lmp_cuda using src/MAKE/Makefile.mpi as the
starting Makefile.machine:
.. parsed-literal::
Make.py -p cuda -cuda mode=single arch=20 -o cuda lib-cuda file mpi
Or you can follow these two (a,b) steps:
(a) Build the USER-CUDA library
The USER-CUDA library is in lammps/lib/cuda. If your *CUDA* toolkit
is not installed in the default system directoy */usr/local/cuda* edit
the file *lib/cuda/Makefile.common* accordingly.
To build the library with the settings in lib/cuda/Makefile.default,
simply type:
.. parsed-literal::
make
To set options when the library is built, type "make OPTIONS", where
*OPTIONS* are one or more of the following. The settings will be
written to the *lib/cuda/Makefile.defaults* before the build.
.. parsed-literal::
*precision=N* to set the precision level
N = 1 for single precision (default)
N = 2 for double precision
N = 3 for positions in double precision
N = 4 for positions and velocities in double precision
*arch=M* to set GPU compute capability
M = 35 for Kepler GPUs
M = 20 for CC2.0 (GF100/110, e.g. C2050,GTX580,GTX470) (default)
M = 21 for CC2.1 (GF104/114, e.g. GTX560, GTX460, GTX450)
M = 13 for CC1.3 (GF200, e.g. C1060, GTX285)
*prec_timer=0/1* to use hi-precision timers
0 = do not use them (default)
1 = use them
this is usually only useful for Mac machines
*dbg=0/1* to activate debug mode
0 = no debug mode (default)
1 = yes debug mode
this is only useful for developers
*cufft=1* for use of the CUDA FFT library
0 = no CUFFT support (default)
in the future other CUDA-enabled FFT libraries might be supported
If the build is successful, it will produce the files liblammpscuda.a and
Makefile.lammps.
Note that if you change any of the options (like precision), you need
to re-build the entire library. Do a "make clean" first, followed by
"make".
(b) Build LAMMPS with the USER-CUDA package
.. parsed-literal::
cd lammps/src
make yes-user-cuda
make machine
No additional compile/link flags are needed in Makefile.machine.
Note that if you change the USER-CUDA library precision (discussed
above) and rebuild the USER-CUDA library, then you also need to
re-install the USER-CUDA package and re-build LAMMPS, so that all
affected files are re-compiled and linked to the new USER-CUDA
library.
**Run with the USER-CUDA 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.
When using the USER-CUDA package, you must use exactly one MPI task
per physical GPU.
You must use the "-c on" :ref:`command-line switch <start_7>` to enable the USER-CUDA package.
The "-c on" switch also issues a default :doc:`package cuda 1 <package>`
command which sets various USER-CUDA options to default values, as
discussed on the :doc:`package <package>` command doc page.
Use the "-sf cuda" :ref:`command-line switch <start_7>`,
which will automatically append "cuda" to styles that support it. Use
the "-pk cuda Ng" :ref:`command-line switch <start_7>` to
set Ng = # of GPUs per node to a different value than the default set
by the "-c on" switch (1 GPU) or change other :doc:`package cuda <package>` options.
.. parsed-literal::
lmp_machine -c on -sf cuda -pk cuda 1 -in in.script # 1 MPI task uses 1 GPU
mpirun -np 2 lmp_machine -c on -sf cuda -pk cuda 2 -in in.script # 2 MPI tasks use 2 GPUs on a single 16-core (or whatever) node
mpirun -np 24 -ppn 2 lmp_machine -c on -sf cuda -pk cuda 2 -in in.script # ditto on 12 16-core nodes
The syntax for the "-pk" switch is the same as same as the "package
cuda" command. See the :doc:`package <package>` command doc page for
details, including the default values used for all its options if it
is not specified.
Note that the default for the :doc:`package cuda <package>` command is
to set the Newton flag to "off" for both pairwise and bonded
interactions. This typically gives fastest performance. If the
:doc:`newton <newton>` command is used in the input script, it can
override these defaults.
**Or run with the USER-CUDA package by editing an input script:**
The discussion above for the mpirun/mpiexec command and the requirement
of one MPI task per GPU is the same.
You must still use the "-c on" :ref:`command-line switch <start_7>` to enable the USER-CUDA package.
Use the :doc:`suffix cuda <suffix>` command, or you can explicitly add a
"cuda" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/cuda 2.5
You only need to use the :doc:`package cuda <package>` command if you
wish to change any of its option defaults, including the number of
GPUs/node (default = 1), as set by the "-c on" :ref:`command-line switch <start_7>`.
**Speed-ups to expect:**
The performance of a GPU versus a multi-core CPU is a function of your
hardware, which pair style is used, the number of atoms/GPU, and the
precision used on the GPU (double, single, mixed).
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the USER-CUDA package on different
hardware.
**Guidelines for best performance:**
* The USER-CUDA package offers more speed-up relative to CPU performance
when the number of atoms per GPU is large, e.g. on the order of tens
or hundreds of 1000s.
* As noted above, this package will continue to run a simulation
entirely on the GPU(s) (except for inter-processor MPI communication),
for multiple timesteps, until a CPU calculation is required, either by
a fix or compute that is non-GPU-ized, or until output is performed
(thermo or dump snapshot or restart file). The less often this
occurs, the faster your simulation will run.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

249
doc/_sources/accelerate_gpu.txt
View File

@ -1,249 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.GPU package
-------------
The GPU package was developed by Mike Brown at ORNL and his
collaborators, particularly Trung Nguyen (ORNL). It provides GPU
versions of many pair styles, including the 3-body Stillinger-Weber
pair style, and for :doc:`kspace_style pppm <kspace_style>` for
long-range Coulombics. It has the following general features:
* It is designed to exploit common GPU hardware configurations where one
or more GPUs are coupled to many cores of one or more multi-core CPUs,
e.g. within a node of a parallel machine.
* Atom-based data (e.g. coordinates, forces) moves back-and-forth
between the CPU(s) and GPU every timestep.
* Neighbor lists can be built on the CPU or on the GPU
* The charge assignement and force interpolation portions of PPPM can be
run on the GPU. The FFT portion, which requires MPI communication
between processors, runs on the CPU.
* Asynchronous force computations can be performed simultaneously on the
CPU(s) and GPU.
* It allows for GPU computations to be performed in single or double
precision, or in mixed-mode precision, where pairwise forces are
computed in single precision, but accumulated into double-precision
force vectors.
* LAMMPS-specific code is in the GPU package. It makes calls to a
generic GPU library in the lib/gpu directory. This library provides
NVIDIA support as well as more general OpenCL support, so that the
same functionality can eventually be supported on a variety of GPU
hardware.
Here is a quick overview of how to use the GPU package:
* build the library in lib/gpu for your GPU hardware wity desired precision
* include the GPU package and build LAMMPS
* use the mpirun command to set the number of MPI tasks/node which determines the number of MPI tasks/GPU
* specify the # of GPUs per node
* use GPU styles in your input script
The latter two steps can be done using the "-pk gpu" and "-sf gpu"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package gpu <package>` or :doc:`suffix gpu <suffix>` commands
respectively to your input script.
**Required hardware/software:**
To use this package, you currently need to have an NVIDIA GPU and
install the NVIDIA Cuda software on your system:
* Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/0/information
* Go to http://www.nvidia.com/object/cuda_get.html
* Install a driver and toolkit appropriate for your system (SDK is not necessary)
* Run lammps/lib/gpu/nvc_get_devices (after building the GPU library, see below) to list supported devices and properties
**Building LAMMPS with the GPU package:**
This requires two steps (a,b): build the GPU library, then build
LAMMPS with the GPU package.
You can do both these steps in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, this
command will create src/lmp_gpu using src/MAKE/Makefile.mpi as the
starting Makefile.machine:
.. parsed-literal::
Make.py -p gpu -gpu mode=single arch=31 -o gpu lib-gpu file mpi
Or you can follow these two (a,b) steps:
(a) Build the GPU library
The GPU library is in lammps/lib/gpu. Select a Makefile.machine (in
lib/gpu) appropriate for your system. You should pay special
attention to 3 settings in this makefile.
* CUDA_HOME = needs to be where NVIDIA Cuda software is installed on your system
* CUDA_ARCH = needs to be appropriate to your GPUs
* CUDA_PREC = precision (double, mixed, single) you desire
See lib/gpu/Makefile.linux.double for examples of the ARCH settings
for different GPU choices, e.g. Fermi vs Kepler. It also lists the
possible precision settings:
.. parsed-literal::
CUDA_PREC = -D_SINGLE_SINGLE # single precision for all calculations
CUDA_PREC = -D_DOUBLE_DOUBLE # double precision for all calculations
CUDA_PREC = -D_SINGLE_DOUBLE # accumulation of forces, etc, in double
The last setting is the mixed mode referred to above. Note that your
GPU must support double precision to use either the 2nd or 3rd of
these settings.
To build the library, type:
.. parsed-literal::
make -f Makefile.machine
If successful, it will produce the files libgpu.a and Makefile.lammps.
The latter file has 3 settings that need to be appropriate for the
paths and settings for the CUDA system software on your machine.
Makefile.lammps is a copy of the file specified by the EXTRAMAKE
setting in Makefile.machine. You can change EXTRAMAKE or create your
own Makefile.lammps.machine if needed.
Note that to change the precision of the GPU library, you need to
re-build the entire library. Do a "clean" first, e.g. "make -f
Makefile.linux clean", followed by the make command above.
(b) Build LAMMPS with the GPU package
.. parsed-literal::
cd lammps/src
make yes-gpu
make machine
No additional compile/link flags are needed in Makefile.machine.
Note that if you change the GPU library precision (discussed above)
and rebuild the GPU library, then you also need to re-install the GPU
package and re-build LAMMPS, so that all affected files are
re-compiled and linked to the new GPU library.
**Run with the GPU 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.
When using the GPU package, you cannot assign more than one GPU to a
single MPI task. However multiple MPI tasks can share the same GPU,
and in many cases it will be more efficient to run this way. Likewise
it may be more efficient to use less MPI tasks/node than the available
# of CPU cores. Assignment of multiple MPI tasks to a GPU will happen
automatically if you create more MPI tasks/node than there are
GPUs/mode. E.g. with 8 MPI tasks/node and 2 GPUs, each GPU will be
shared by 4 MPI tasks.
Use the "-sf gpu" :ref:`command-line switch <start_7>`,
which will automatically append "gpu" to styles that support it. Use
the "-pk gpu Ng" :ref:`command-line switch <start_7>` to
set Ng = # of GPUs/node to use.
.. parsed-literal::
lmp_machine -sf gpu -pk gpu 1 -in in.script # 1 MPI task uses 1 GPU
mpirun -np 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # 12 MPI tasks share 2 GPUs on a single 16-core (or whatever) node
mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script # ditto on 4 16-core nodes
Note that if the "-sf gpu" switch is used, it also issues a default
:doc:`package gpu 1 <package>` command, which sets the number of
GPUs/node to 1.
Using the "-pk" switch explicitly allows for setting of the number of
GPUs/node to use and additional options. Its syntax is the same as
same as the "package gpu" command. See the :doc:`package <package>`
command doc page for details, including the default values used for
all its options if it is not specified.
Note that the default for the :doc:`package gpu <package>` command is to
set the Newton flag to "off" pairwise interactions. It does not
affect the setting for bonded interactions (LAMMPS default is "on").
The "off" setting for pairwise interaction is currently required for
GPU package pair styles.
**Or run with the GPU package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and use of multiple MPI tasks/GPU is the same.
Use the :doc:`suffix gpu <suffix>` command, or you can explicitly add an
"gpu" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/gpu 2.5
You must also use the :doc:`package gpu <package>` command to enable the
GPU package, unless the "-sf gpu" or "-pk gpu" :ref:`command-line switches <start_7>` were used. It specifies the
number of GPUs/node to use, as well as other options.
**Speed-ups to expect:**
The performance of a GPU versus a multi-core CPU is a function of your
hardware, which pair style is used, the number of atoms/GPU, and the
precision used on the GPU (double, single, mixed).
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.
You should also experiment with how many MPI tasks per GPU to use to
give the best performance for your problem and machine. This is also
a function of the problem size and the pair style being using.
Likewise, you should experiment with the precision setting for the GPU
library to see if single or mixed precision will give accurate
results, since they will typically be faster.
**Guidelines for best performance:**
* Using multiple MPI tasks per GPU will often give the best performance,
as allowed my most multi-core CPU/GPU configurations.
* If the number of particles per MPI task is small (e.g. 100s of
particles), it can be more efficient to run with fewer MPI tasks per
GPU, even if you do not use all the cores on the compute node.
* The :doc:`package gpu <package>` command has several options for tuning
performance. Neighbor lists can be built on the GPU or CPU. Force
calculations can be dynamically balanced across the CPU cores and
GPUs. GPU-specific settings can be made which can be optimized
for different hardware. See the :doc:`packakge <package>` command
doc page for details.
* As described by the :doc:`package gpu <package>` command, GPU
accelerated pair styles can perform computations asynchronously with
CPU computations. The "Pair" time reported by LAMMPS will be the
maximum of the time required to complete the CPU pair style
computations and the time required to complete the GPU pair style
computations. Any time spent for GPU-enabled pair styles for
computations that run simultaneously with :doc:`bond <bond_style>`,
:doc:`angle <angle_style>`, :doc:`dihedral <dihedral_style>`,
:doc:`improper <improper_style>`, and :doc:`long-range <kspace_style>`
calculations will not be included in the "Pair" time.
* When the *mode* setting for the package gpu command is force/neigh,
the time for neighbor list calculations on the GPU will be added into
the "Pair" time, not the "Neigh" time. An additional breakdown of the
times required for various tasks on the GPU (data copy, neighbor
calculations, force computations, etc) are output only with the LAMMPS
screen output (not in the log file) at the end of each run. These
timings represent total time spent on the GPU for each routine,
regardless of asynchronous CPU calculations.
* The output section "GPU Time Info (average)" reports "Max Mem / Proc".
This is the maximum memory used at one time on the GPU for data
storage by a single MPI process.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

346
doc/_sources/accelerate_intel.txt
View File

@ -1,346 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-INTEL package
--------------------
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.
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.
If LAMMPS is built with both the USER-INTEL and USER-OMP packages
intsalled, this mode of operation is made easier to use, because the
"-suffix intel" :ref:`command-line switch <start_7>` or
the :doc:`suffix intel <suffix>` 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.
When using the USER-INTEL package, you must choose at build time
whether you are building for CPU-only acceleration or for using the
Xeon Phi in offload mode.
Here is a quick overview of how to use the USER-INTEL package
for CPU-only acceleration:
* 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
Note that many of these settings can only be used with the Intel
compiler, as discussed below.
Using the USER-INTEL package to offload work to the Intel(R)
Xeon Phi(TM) coprocessor is the same except for these additional
steps:
* add the flag -DLMP_INTEL_OFFLOAD to CCFLAGS in your Makefile.machine
* add the flag -offload to LINKFLAGS in your Makefile.machine
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"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package intel <package>` or :doc:`suffix intel <suffix>`
commands respectively to your input script.
**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.
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.
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.
**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.
You can do either in one line, using the src/Make.py script, described
in :ref:`Section 2.4 <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:
.. parsed-literal::
Make.py -p intel omp -intel cpu -o intel_cpu -cc icc file mpi
Make.py -p intel omp -intel phi -o intel_phi -cc icc file mpi
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:
.. parsed-literal::
cd lammps/src
make yes-user-intel
make yes-user-omp (if desired)
make machine
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.
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).
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 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 :doc:`package intel <package>`
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:**
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 LAMMPS was built with coprocessor support for the USER-INTEL
package, you also need to specify the number of coprocessor/node and
the number of coprocessor threads per MPI task to use. Note that
coprocessor threads (which run on the coprocessor) are totally
independent from OpenMP threads (which run on the CPU). The default
values for the settings that affect coprocessor threads are typically
fine, as discussed below.
Use the "-sf intel" :ref:`command-line switch <start_7>`,
which will automatically append "intel" to styles that support it. If
a style does not support it, an "omp" suffix is tried next. OpenMP
threads per MPI task can be set via the "-pk intel Nphi omp Nt" or
"-pk omp Nt" :ref:`command-line switches <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.
Use the "-pk intel Nphi" :ref:`command-line switch <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" :ref:`command-line switch <start_7>` is used to limit the coprocessor
threads per MPI task. See the :doc:`package intel <package>` command
for details.
.. parsed-literal::
CPU-only without USER-OMP (but using Intel vectorization on CPU):
lmp_machine -sf intel -in in.script # 1 MPI task
mpirun -np 32 lmp_machine -sf intel -in in.script # 32 MPI tasks on as many nodes as needed (e.g. 2 16-core nodes)
.. parsed-literal::
CPU-only with USER-OMP (and Intel vectorization on CPU):
lmp_machine -sf intel -pk intel 16 0 -in in.script # 1 MPI task on a 16-core node
mpirun -np 4 lmp_machine -sf intel -pk omp 4 -in in.script # 4 MPI tasks each with 4 threads on a single 16-core node
mpirun -np 32 lmp_machine -sf intel -pk omp 4 -in in.script # ditto on 8 16-core nodes
.. parsed-literal::
CPUs + Xeon Phi(TM) coprocessors with or without USER-OMP:
lmp_machine -sf intel -pk intel 1 omp 16 -in in.script # 1 MPI task, 16 OpenMP threads on CPU, 1 coprocessor, all 240 coprocessor threads
lmp_machine -sf intel -pk intel 1 omp 16 tptask 32 -in in.script # 1 MPI task, 16 OpenMP threads on CPU, 1 coprocessor, only 32 coprocessor threads
mpirun -np 4 lmp_machine -sf intel -pk intel 1 omp 4 -in in.script # 4 MPI tasks, 4 OpenMP threads/task, 1 coprocessor, 60 coprocessor threads/task
mpirun -np 32 -ppn 4 lmp_machine -sf intel -pk intel 1 omp 4 -in in.script # ditto on 8 16-core nodes
mpirun -np 8 lmp_machine -sf intel -pk intel 4 omp 2 -in in.script # 8 MPI tasks, 2 OpenMP threads/task, 4 coprocessors, 120 coprocessor threads/task
Note that if the "-sf intel" switch is used, it also invokes two
default commands: :doc:`package intel 1 <package>`, followed by :doc:`package omp 0 <package>`. These both set the number of OpenMP threads per
MPI task via the OMP_NUM_THREADS environment variable. The first
command sets the number of Xeon Phi(TM) coprocessors/node to 1 (and
the precision mode to "mixed", as one of its option defaults). The
latter command is not invoked if LAMMPS was not built with the
USER-OMP package. The Nphi = 1 value for the first command is ignored
if LAMMPS was not built with coprocessor support.
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
:doc:`package omp <package>` and :doc:`package intel <package>` commands.
See the :doc:`package <package>` command doc page for details, including
the default values used for all its options if these switches are not
specified, and how to set the number of OpenMP threads via the
OMP_NUM_THREADS environment variable if desired.
**Or run with the USER-INTEL package by editing an input script:**
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 :doc:`suffix intel <suffix>` command, or you can explicitly add an
"intel" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/intel 2.5
You must also use the :doc:`package intel <package>` command, unless the
"-sf intel" or "-pk intel" :ref:`command-line switches <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.
If LAMMPS was also built with the USER-OMP package, you must also use
the :doc:`package omp <package>` command to enable that package, unless
the "-sf intel" or "-pk omp" :ref:`command-line switches <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.
**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 built with coproccesor support, the pair styles will run
on one or more Intel(R) Xeon Phi(TM) coprocessors (per node). The
performance of a Xeon Phi versus a multi-core CPU is a function of
your hardware, which pair style is used, the number of
atoms/coprocessor, and the precision used on the coprocessor (double,
single, mixed).
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.
**Guidelines for best performance on an Intel(R) Xeon Phi(TM)
coprocessor:**
* The default for the :doc:`package intel <package>` command is to have
all the MPI tasks on a given compute node use a single Xeon Phi(TM)
coprocessor. In general, running with a large number of MPI tasks on
each node will perform best with offload. Each MPI task will
automatically get affinity to a subset of the hardware threads
available on the coprocessor. For example, if your card has 61 cores,
with 60 cores available for offload and 4 hardware threads per core
(240 total threads), running with 24 MPI tasks per node will cause
each MPI task to use a subset of 10 threads on the coprocessor. Fine
tuning of the number of threads to use per MPI task or the number of
threads to use per core can be accomplished with keyword settings of
the :doc:`package intel <package>` command.
* If desired, only a fraction of the pair style computation can be
offloaded to the coprocessors. This is accomplished by using the
*balance* keyword in the :doc:`package intel <package>` command. A
balance of 0 runs all calculations on the CPU. A balance of 1 runs
all calculations on the coprocessor. A balance of 0.5 runs half of
the calculations on the coprocessor. Setting the balance to -1 (the
default) will enable dynamic load balancing that continously adjusts
the fraction of offloaded work throughout the simulation. This option
typically produces results within 5 to 10 percent of the optimal fixed
balance.
* When using offload with CPU hyperthreading disabled, it may help
performance to use fewer MPI tasks and OpenMP threads than available
cores. This is due to the fact that additional threads are generated
internally to handle the asynchronous offload tasks.
* If running short benchmark runs with dynamic load balancing, adding a
short warm-up run (10-20 steps) will allow the load-balancer to find a
near-optimal setting that will carry over to additional runs.
* If pair computations are being offloaded to an Intel(R) Xeon Phi(TM)
coprocessor, a diagnostic line is printed to the screen (not to the
log file), during the setup phase of a run, indicating that offload
mode is being used and indicating the number of coprocessor threads
per MPI task. Additionally, an offload timing summary is printed at
the end of each run. When offloading, the frequency for :doc:`atom sorting <atom_modify>` is changed to 1 so that the per-atom data is
effectively sorted at every rebuild of the neighbor lists.
* For simulations with long-range electrostatics or bond, angle,
dihedral, improper calculations, computation and data transfer to the
coprocessor will run concurrently with computations and MPI
communications for these calculations on the host CPU. The USER-INTEL
package has two modes for deciding which atoms will be handled by the
coprocessor. This choice is controlled with the *ghost* keyword of
the :doc:`package intel <package>` command. When set to 0, ghost atoms
(atoms at the borders between MPI tasks) are not offloaded to the
card. This allows for overlap of MPI communication of forces with
computation on the coprocessor when the :doc:`newton <newton>` setting
is "on". The default is dependent on the style being used, however,
better performance may be achieved by setting this option
explictly.
Restrictions
""""""""""""
When offloading to a coprocessor, :doc:`hybrid <pair_hybrid>` styles
that require skip lists for neighbor builds cannot be offloaded.
Using :doc:`hybrid/overlay <pair_hybrid>` is allowed. Only one intel
accelerated style may be used with hybrid styles.
:doc:`Special_bonds <special_bonds>` exclusion lists are not currently
supported with offload, however, the same effect can often be
accomplished by setting cutoffs for excluded atom types to 0. None of
the pair styles in the USER-INTEL package currently support the
"inner", "middle", "outer" options for rRESPA integration via the
:doc:`run_style respa <run_style>` command; only the "pair" option is
supported.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

524
doc/_sources/accelerate_kokkos.txt
View File

@ -1,524 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.KOKKOS package
----------------
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 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
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.
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
load and store operations. Such data structures are used in LAMMPS to
store atom coordinates or forces or neighbor lists. The layout is
chosen to optimize performance on different platforms. Again this
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).
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 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
The latter two steps can be done using the "-k on", "-pk kokkos" and
"-sf kk" :ref:`command-line switches <start_7>`
respectively. Or the effect of the "-pk" or "-sf" switches can be
duplicated by adding the :doc:`package kokkos <package>` or :doc:`suffix kk <suffix>` commands respectively to your input script.
**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
Kokkos support within LAMMPS must be built with a C++11 compatible
compiler. For example, gcc 4.7.2 or later.
Note that Intel Xeon Phi coprocessors are supported in "native" mode,
not "offload" mode like the USER-INTEL package supports.
Only NVIDIA GPUs are currently supported.
.. warning::
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 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.
**Building LAMMPS with the KOKKOS package:**
You must choose at build time whether to build for OpenMP, Cuda, or
Phi.
You can do any of these in one line, using the src/Make.py script,
described in :ref:`Section 2.4 <start_4>` of the manual.
Type "Make.py -h" for help. If run from the src directory, these
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.
.. parsed-literal::
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
Or you can follow these steps:
CPU-only (run all-MPI or with OpenMP threading):
.. parsed-literal::
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP
Intel Xeon Phi:
.. parsed-literal::
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP KOKKOS_ARCH=KNC
CPUs and GPUs:
.. parsed-literal::
cd lammps/src
make yes-kokkos
make cuda KOKKOS_DEVICES=Cuda
These examples set the KOKKOS-specific OMP, MIC, CUDA variables on the
make command line which requires a GNU-compatible make command. Try
"gmake" if your system's standard make complains.
.. warning::
If you build using make line variables and re-build
LAMMPS twice with different KOKKOS options and the *same* target,
e.g. g++ in the first two examples above, then you *must* perform a
"make clean-all" or "make clean-machine" before each build. This is
to force all the KOKKOS-dependent files to be re-compiled with the new
options.
You can also hardwire these make variables in the specified machine
makefile, e.g. src/MAKE/Makefile.g++ in the first two examples above,
with a line like:
.. parsed-literal::
KOKKOS_ARCH = KNC
Note that if you build LAMMPS multiple times in this manner, using
different KOKKOS options (defined in different machine makefiles), you
do not have to worry about doing a "clean" in between. This is
because the targets will be different.
.. warning::
The 3rd example above for a GPU, uses a different
machine makefile, in this case src/MAKE/Makefile.cuda, which is
included in the LAMMPS distribution. To build the KOKKOS package for
a GPU, this makefile must use the NVIDA "nvcc" compiler. And it must
have a KOKKOS_ARCH setting that is appropriate for your NVIDIA
hardware and installed software. Typical values for KOKKOS_ARCH are given
below, as well
as other settings that must be included in the machine makefile, if
you create your own.
.. warning::
Currently, there are no precision options with the
KOKKOS package. All compilation and computation is performed in
double precision.
There are other allowed options when building with the KOKKOS package.
As above, they can be set either as variables on the make command line
or in Makefile.machine. This is the full list of options, including
those discussed above, Each takes a value shown below. The
default value is listed, which is set in the
lib/kokkos/Makefile.kokkos file.
#Default settings specific options
#Options: force_uvm,use_ldg,rdc
* KOKKOS_DEVICES, values = *OpenMP*, *Serial*, *Pthreads*, *Cuda*, default = *OpenMP*
* KOKKOS_ARCH, values = *KNC*, *SNB*, *HSW*, *Kepler*, *Kepler30*, *Kepler32*, *Kepler35*, *Kepler37*, *Maxwell*, *Maxwell50*, *Maxwell52*, *Maxwell53*, *ARMv8*, *BGQ*, *Power7*, *Power8*, default = *none*
* KOKKOS_DEBUG, values = *yes*, *no*, default = *no*
* KOKKOS_USE_TPLS, values = *hwloc*, *librt*, default = *none*
* KOKKOS_CUDA_OPTIONS, values = *force_uvm*, *use_ldg*, *rdc*
KOKKOS_DEVICE sets the parallelization method used for Kokkos code
(within LAMMPS). KOKKOS_DEVICES=OpenMP means that OpenMP will be
used. KOKKOS_DEVICES=Pthreads means that pthreads will be used.
KOKKOS_DEVICES=Cuda means an NVIDIA GPU running CUDA will be used.
If KOKKOS_DEVICES=Cuda, then the lo-level Makefile in the src/MAKE
directory must use "nvcc" as its compiler, via its CC setting. For
best performance its CCFLAGS setting should use -O3 and have a
KOKKOS_ARCH setting that matches the compute capability of your NVIDIA
hardware and software installation, e.g. KOKKOS_ARCH=Kepler30. Note
the minimal required compute capability is 2.0, but this will give
signicantly reduced performance compared to Kepler generation GPUs
with compute capability 3.x. For the LINK setting, "nvcc" should not
be used; instead use g++ or another compiler suitable for linking C++
applications. Often you will want to use your MPI compiler wrapper
for this setting (i.e. mpicxx). Finally, the lo-level Makefile must
also have a "Compilation rule" for creating *.o files from *.cu files.
See src/Makefile.cuda for an example of a lo-level Makefile with all
of these settings.
KOKKOS_USE_TPLS=hwloc binds threads to hardware cores, so they do not
migrate during a simulation. KOKKOS_USE_TPLS=hwloc should always be
used if running with KOKKOS_DEVICES=Pthreads for pthreads. It is not
necessary for KOKKOS_DEVICES=OpenMP for OpenMP, because OpenMP
provides alternative methods via environment variables for binding
threads to hardware cores. More info on binding threads to cores is
given in :ref:`this section <acc_8>`.
KOKKOS_ARCH=KNC enables compiler switches needed when compling for an
Intel Phi processor.
KOKKOS_USE_TPLS=librt enables use of a more accurate timer mechanism
on most Unix platforms. This library is not available on all
platforms.
KOKKOS_DEBUG is only useful when developing a Kokkos-enabled style
within LAMMPS. KOKKOS_DEBUG=yes enables printing of run-time
debugging information that can be useful. It also enables runtime
bounds checking on Kokkos data structures.
KOKKOS_CUDA_OPTIONS are additional options for CUDA.
For more information on Kokkos see the Kokkos programmers' guide here:
/lib/kokkos/doc/Kokkos_PG.pdf.
**Run with the KOKKOS 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.
When using KOKKOS built with host=OMP, you need to choose how many
OpenMP threads per MPI task will be used (via the "-k" command-line
switch discussed below). 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.
When using the KOKKOS package built with device=CUDA, you must use
exactly one MPI task per physical GPU.
When using the KOKKOS package built with host=MIC for Intel Xeon Phi
coprocessor support you need to insure there are one or more MPI tasks
per coprocessor, and choose the number of coprocessor threads to use
per MPI task (via the "-k" command-line switch discussed below). The
product of MPI tasks * coprocessor threads/task should not exceed the
maximum number of threads the coproprocessor is designed to run,
otherwise performance will suffer. This value is 240 for current
generation Xeon Phi(TM) chips, which is 60 physical cores * 4
threads/core. Note that with the KOKKOS package you do not need to
specify how many Phi coprocessors there are per node; each
coprocessors is simply treated as running some number of MPI tasks.
You must use the "-k on" :ref:`command-line switch <start_7>` to enable the KOKKOS package. It
takes additional arguments for hardware settings appropriate to your
system. Those arguments are :ref:`documented here <start_7>`. The two most commonly used
options are:
.. parsed-literal::
-k on t Nt g Ng
The "t Nt" option applies to host=OMP (even if device=CUDA) and
host=MIC. For host=OMP, it specifies how many OpenMP threads per MPI
task to use with a node. For host=MIC, it specifies how many Xeon Phi
threads per MPI task to use within a node. The default is Nt = 1.
Note that for host=OMP this is effectively MPI-only mode which may be
fine. But for host=MIC you will typically end up using far less than
all the 240 available threads, which could give very poor performance.
The "g Ng" option applies to device=CUDA. It specifies how many GPUs
per compute node to use. The default is 1, so this only needs to be
specified is you have 2 or more GPUs per compute node.
The "-k on" switch also issues a "package kokkos" command (with no
additional arguments) which sets various KOKKOS options to default
values, as discussed on the :doc:`package <package>` command doc page.
Use the "-sf kk" :ref:`command-line switch <start_7>`,
which will automatically append "kk" to styles that support it. Use
the "-pk kokkos" :ref:`command-line switch <start_7>` if
you wish to change any of the default :doc:`package kokkos <package>`
optionns set by the "-k on" :ref:`command-line switch <start_7>`.
.. parsed-literal::
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
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
.. parsed-literal::
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
.. parsed-literal::
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
Note that the default for the :doc:`package kokkos <package>` command is
to use "full" neighbor lists and set the Newton flag to "off" for both
pairwise and bonded interactions. This typically gives fastest
performance. If the :doc:`newton <newton>` command is used in the input
script, it can override the Newton flag defaults.
However, when running in MPI-only mode with 1 thread per MPI task, it
will typically be faster to use "half" neighbor lists and set the
Newton flag to "on", just as is the case for non-accelerated pair
styles. You can do this with the "-pk" :ref:`command-line switch <start_7>`.
**Or run with the KOKKOS package by editing an input script:**
The discussion above for the mpirun/mpiexec command and setting
appropriate thread and GPU values for host=OMP or host=MIC or
device=CUDA are the same.
You must still use the "-k on" :ref:`command-line switch <start_7>` to enable the KOKKOS package, and
specify its additional arguments for hardware options appopriate to
your system, as documented above.
Use the :doc:`suffix kk <suffix>` command, or you can explicitly add a
"kk" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/kk 2.5
You only need to use the :doc:`package kokkos <package>` command if you
wish to change any of its option defaults, as set by the "-k on"
:ref:`command-line switch <start_7>`.
**Speed-ups to expect:**
The performance of KOKKOS running in different modes is a function of
your hardware, which KOKKOS-enable styles are used, and the problem
size.
Generally speaking, the following rules of thumb apply:
* When running on CPUs only, with a single thread per MPI task,
performance of a KOKKOS style is somewhere between the standard
(un-accelerated) styles (MPI-only mode), and those provided by the
USER-OMP package. However the difference between all 3 is small (less
than 20%).
* When running on CPUs only, with multiple threads per MPI task,
performance of a KOKKOS style is a bit slower than the USER-OMP
package.
* When running on GPUs, KOKKOS is typically faster than the USER-CUDA
and GPU packages.
* When running on Intel Xeon Phi, KOKKOS is not as fast as
the USER-INTEL package, which is optimized for that hardware.
See the `Benchmark page <http://lammps.sandia.gov/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
hardware.
**Guidelines for best performance:**
Here are guidline for using the KOKKOS package on the different
hardware configurations listed above.
Many of the guidelines use the :doc:`package kokkos <package>` command
See its doc page for details and default settings. Experimenting with
its options can provide a speed-up for specific calculations.
**Running on a multi-core CPU:**
If N is the number of physical cores/node, then the number of MPI
tasks/node * number of threads/task should not exceed N, and should
typically equal N. Note that the default threads/task is 1, as set by
the "t" keyword of the "-k" :ref:`command-line switch <start_7>`. If you do not change this, no
additional parallelism (beyond MPI) will be invoked on the host
CPU(s).
You can compare the performance running in different modes:
* run with 1 MPI task/node and N threads/task
* run with N MPI tasks/node and 1 thread/task
* run with settings in between these extremes
Examples of mpirun commands in these modes are shown above.
When using KOKKOS to perform multi-threading, it is important for
performance to bind both MPI tasks to physical cores, and threads to
physical cores, so they do not migrate during a simulation.
If you are not certain MPI tasks are being bound (check the defaults
for your MPI installation), binding can be forced with these flags:
.. parsed-literal::
OpenMPI 1.8: mpirun -np 2 -bind-to socket -map-by socket ./lmp_openmpi ...
Mvapich2 2.0: mpiexec -np 2 -bind-to socket -map-by socket ./lmp_mvapich ...
For binding threads with the KOKKOS OMP option, use thread affinity
environment variables to force binding. With OpenMP 3.1 (gcc 4.7 or
later, intel 12 or later) setting the environment variable
OMP_PROC_BIND=true should be sufficient. For binding threads with the
KOKKOS pthreads option, compile LAMMPS the KOKKOS HWLOC=yes option, as
discussed in :ref:`Section 2.3.4 <start_3_4>` of the
manual.
**Running on GPUs:**
Insure the -arch setting in the machine makefile you are using,
e.g. src/MAKE/Makefile.cuda, is correct for your GPU hardware/software
(see :ref:`this section <start_3_4>` of the manual for
details).
The -np setting of the mpirun command should set the number of MPI
tasks/node to be equal to the # of physical GPUs on the node.
Use the "-k" :ref:`command-line switch <start_7>` to
specify the number of GPUs per node, and the number of threads per MPI
task. As above for multi-core CPUs (and no GPU), if N is the number
of physical cores/node, then the number of MPI tasks/node * number of
threads/task should not exceed N. With one GPU (and one MPI task) it
may be faster to use less than all the available cores, by setting
threads/task to a smaller value. This is because using all the cores
on a dual-socket node will incur extra cost to copy memory from the
2nd socket to the GPU.
Examples of mpirun commands that follow these rules are shown above.
.. warning::
When using a GPU, you will achieve the best
performance if your input script does not use any fix or compute
styles which are not yet Kokkos-enabled. This allows data to stay on
the GPU for multiple timesteps, without being copied back to the host
CPU. Invoking a non-Kokkos fix or compute, or performing I/O for
:doc:`thermo <thermo_style>` or :doc:`dump <dump>` output will cause data
to be copied back to the CPU.
You cannot yet assign multiple MPI tasks to the same GPU with the
KOKKOS package. We plan to support this in the future, similar to the
GPU package in LAMMPS.
You cannot yet use both the host (multi-threaded) and device (GPU)
together to compute pairwise interactions with the KOKKOS package. We
hope to support this in the future, similar to the GPU package in
LAMMPS.
**Running on an Intel Phi:**
Kokkos only uses Intel Phi processors in their "native" mode, i.e.
not hosted by a CPU.
As illustrated above, build LAMMPS with OMP=yes (the default) and
MIC=yes. The latter insures code is correctly compiled for the Intel
Phi. The OMP setting means OpenMP will be used for parallelization on
the Phi, which is currently the best option within Kokkos. In the
future, other options may be added.
Current-generation Intel Phi chips have either 61 or 57 cores. One
core should be excluded for running the OS, leaving 60 or 56 cores.
Each core is hyperthreaded, so there are effectively N = 240 (4*60) or
N = 224 (4*56) cores to run on.
The -np setting of the mpirun command sets the number of MPI
tasks/node. The "-k on t Nt" command-line switch sets the number of
threads/task as Nt. The product of these 2 values should be N, i.e.
240 or 224. Also, the number of threads/task should be a multiple of
4 so that logical threads from more than one MPI task do not run on
the same physical core.
Examples of mpirun commands that follow these rules are shown above.
Restrictions
""""""""""""
As noted above, if using GPUs, the number of MPI tasks per compute
node should equal to the number of GPUs per compute node. In the
future Kokkos will support assigning multiple MPI tasks to a single
GPU.
Currently Kokkos does not support AMD GPUs due to limits in the
available backend programming models. Specifically, Kokkos requires
extensive C++ support from the Kernel language. This is expected to
change in the future.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

199
doc/_sources/accelerate_omp.txt
View File

@ -1,199 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.USER-OMP package
------------------
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.
Here is a quick overview of how to use the USER-OMP package:
* 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
The latter two steps can be done using the "-pk omp" and "-sf omp"
:ref:`command-line switches <start_7>` respectively. Or
the effect of the "-pk" or "-sf" switches can be duplicated by adding
the :doc:`package omp <package>` or :doc:`suffix omp <suffix>` commands
respectively to your input script.
**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.
**Building LAMMPS with the USER-OMP package:**
To do this in one line, use the src/Make.py script, described in
:ref:`Section 2.4 <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:
.. parsed-literal::
Make.py -p omp -o omp file mpi
Or you can follow these steps:
.. parsed-literal::
cd lammps/src
make yes-user-omp
make machine
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".
**Run with the USER-OMP 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.
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.
Use the "-sf omp" :ref:`command-line switch <start_7>`,
which will automatically append "omp" to styles that support it. Use
the "-pk omp Nt" :ref:`command-line switch <start_7>`, to
set Nt = # of OpenMP threads per MPI task to use.
.. parsed-literal::
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
Note that if the "-sf omp" switch is used, it also issues a default
:doc:`package omp 0 <package>` 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 :doc:`package <package>` 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.
**Or run with the USER-OMP package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.
Use the :doc:`suffix omp <suffix>` command, or you can explicitly add an
"omp" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/omp 2.5
You must also use the :doc:`package omp <package>` command to enable the
USER-OMP package, unless the "-sf omp" or "-pk omp" :ref:`command-line switches <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.
**Speed-ups to expect:**
Depending on which styles are accelerated, you should look for a
reduction in the "Pair time", "Bond time", "KSpace time", and "Loop
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.
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
sub-section.
A description of the multi-threading strategy used in the USER-OMP
package and some performance examples are `presented here <http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1>`_
**Guidelines for best performance:**
For many problems on current generation CPUs, running the USER-OMP
package with a single thread/task is faster than running with multiple
threads/task. This is because the MPI parallelization in LAMMPS is
often more efficient than multi-threading as implemented in the
USER-OMP package. The parallel efficiency (in a threaded sense) also
varies for different USER-OMP styles.
Using multiple threads/task can be more effective under the following
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
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
inter-node communication bandwidth contention in the same way, but
offers an additional speedup by utilizing the otherwise idle CPU
cores.
* The interconnect used for MPI communication does not provide
sufficient bandwidth for a large number of MPI tasks per node. For
example, this applies to running over gigabit ethernet or on Cray XT4
or XT5 series supercomputers. As in the aforementioned case, this
effect worsens when using an increasing number of nodes.
* The system has a spatially inhomogeneous particle density which does
not map well to the :doc:`domain decomposition scheme <processors>` or
:doc:`load-balancing <balance>` options that LAMMPS provides. This is
because multi-threading achives parallelism over the number of
particles, not via their distribution in space.
* A machine is being used in "capability mode", i.e. near the point
where MPI parallelism is maxed out. For example, this can happen when
using the :doc:`PPPM solver <kspace_style>` for long-range
electrostatics on large numbers of nodes. The scaling of the KSpace
calculation (see the :doc:`kspace_style <kspace_style>` command) becomes
the performance-limiting factor. Using multi-threading allows less
MPI tasks to be invoked and can speed-up the long-range solver, while
increasing overall performance by parallelizing the pairwise and
bonded calculations via OpenMP. Likewise additional speedup can be
sometimes be achived by increasing the length of the Coulombic cutoff
and thus reducing the work done by the long-range solver. Using the
:doc:`run_style verlet/split <run_style>` command, which is compatible
with the USER-OMP package, is an alternative way to reduce the number
of MPI tasks assigned to the KSpace calculation.
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.
* It is usually most efficient to restrict threading to a single
socket, i.e. use one or more MPI task per socket.
* 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.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/accelerate_opt.txt
View File

@ -1,88 +0,0 @@
:doc:`Return to Section accelerate overview <Section_accelerate>`
5.OPT package
-------------
The OPT package was developed by James Fischer (High Performance
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.
Here is a quick overview of how to use the OPT package:
* include the OPT package and build LAMMPS
* use OPT pair styles in your input script
The last step can be done using the "-sf opt" :ref:`command-line switch <start_7>`. Or the effect of the "-sf" switch
can be duplicated by adding a :doc:`suffix opt <suffix>` command to your
input script.
**Required hardware/software:**
None.
**Building LAMMPS with the OPT package:**
Include the package and build LAMMPS:
To do this in one line, use the src/Make.py script, described in
:ref:`Section 2.4 <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:
.. parsed-literal::
Make.py -p opt -o opt file mpi
Or you can follow these steps:
.. parsed-literal::
cd lammps/src
make yes-opt
make machine
If you are using Intel compilers, then the CCFLAGS setting in
Makefile.machine needs to include "-restrict".
**Run with the OPT package from the command line:**
Use the "-sf opt" :ref:`command-line switch <start_7>`,
which will automatically append "opt" to styles that support it.
.. parsed-literal::
lmp_machine -sf opt -in in.script
mpirun -np 4 lmp_machine -sf opt -in in.script
**Or run with the OPT package by editing an input script:**
Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
"opt" suffix to individual styles in your input script, e.g.
.. parsed-literal::
pair_style lj/cut/opt 2.5
**Speed-ups to expect:**
You should see a reduction in the "Pair time" value printed at the end
of a run. On most machines for reasonable problem sizes, it will be a
5 to 20% savings.
**Guidelines for best performance:**
None. Just try out an OPT pair style to see how it performs.
Restrictions
""""""""""""
None.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

110
doc/_sources/angle_charmm.txt
View File

@ -1,110 +0,0 @@
.. index:: angle_style charmm
angle_style charmm command
==========================
angle_style charmm/kk command
=============================
angle_style charmm/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style charmm
Examples
""""""""
.. parsed-literal::
angle_style charmm
angle_coeff 1 300.0 107.0 50.0 3.0
Description
"""""""""""
The *charmm* angle style uses the potential
.. image:: Eqs/angle_charmm.jpg
:align: center
with an additional Urey_Bradley term based on the distance *r* between
the 1st and 3rd atoms in the angle. K, theta0, Kub, and Rub are
coefficients defined for each angle type.
See :ref:`(MacKerell) <MacKerell>` for a description of the CHARMM force
field.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/radian^2)
* theta0 (degrees)
* K_ub (energy/distance^2)
* r_ub (distance)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _MacKerell:
**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field,
Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

139
doc/_sources/angle_class2.txt
View File

@ -1,139 +0,0 @@
.. index:: angle_style class2
angle_style class2 command
==========================
angle_style class2/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style class2
Examples
""""""""
.. parsed-literal::
angle_style class2
angle_coeff * 75.0
angle_coeff 1 bb 10.5872 1.0119 1.5228
angle_coeff * ba 3.6551 24.895 1.0119 1.5228
Description
"""""""""""
The *class2* angle style uses the potential
.. image:: Eqs/angle_class2.jpg
:align: center
where Ea is the angle term, Ebb is a bond-bond term, and Eba is a
bond-angle term. Theta0 is the equilibrium angle and r1 and r2 are
the equilibrium bond lengths.
See :ref:`(Sun) <Sun>` for a description of the COMPASS class2 force field.
Coefficients for the Ea, Ebb, and Eba formulas must be defined for
each angle type via the :doc:`angle_coeff <angle_coeff>` command as in
the example above, or in the data file or restart files read by the
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands.
These are the 4 coefficients for the Ea formula:
* theta0 (degrees)
* K2 (energy/radian^2)
* K3 (energy/radian^3)
* K4 (energy/radian^4)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of the various K are in per-radian.
For the Ebb formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 4 coefficients, the first of which
is "bb" to indicate they are BondBond coefficients. In a data file,
these coefficients should be listed under a "BondBond Coeffs" heading
and you must leave out the "bb", i.e. only list 3 coefficients after
the angle type.
* bb
* M (energy/distance^2)
* r1 (distance)
* r2 (distance)
For the Eba formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 5 coefficients, the first of which
is "ba" to indicate they are BondAngle coefficients. In a data file,
these coefficients should be listed under a "BondAngle Coeffs" heading
and you must leave out the "ba", i.e. only list 4 coefficients after
the angle type.
* ba
* N1 (energy/distance^2)
* N2 (energy/distance^2)
* r1 (distance)
* r2 (distance)
The theta0 value in the Eba formula is not specified, since it is the
same value from the Ea formula.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the CLASS2
package. See the :ref:`Making LAMMPS <start_3>` section
for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _Sun:
**(Sun)** Sun, J Phys Chem B 102, 7338-7364 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

116
doc/_sources/angle_coeff.txt
View File

@ -1,116 +0,0 @@
.. index:: angle_coeff
angle_coeff command
===================
Syntax
""""""
.. parsed-literal::
angle_coeff N args
* N = angle type (see asterisk form below)
* args = coefficients for one or more angle types
Examples
""""""""
.. parsed-literal::
angle_coeff 1 300.0 107.0
angle_coeff * 5.0
angle_coeff 2*10 5.0
Description
"""""""""""
Specify the angle force field coefficients for one or more angle types.
The number and meaning of the coefficients depends on the angle style.
Angle coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the 1st example above. Or a wild-card asterisk can be
used to set the coefficients for multiple angle types. This takes the
form "*" or "*n" or "n*" or "m*n". If N = the number of angle types,
then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
Note that using an angle_coeff command can override a previous setting
for the same angle type. For example, these commands set the coeffs
for all angle types, then overwrite the coeffs for just angle type 2:
.. parsed-literal::
angle_coeff * 200.0 107.0 1.2
angle_coeff 2 50.0 107.0
A line in a data file that specifies angle coefficients uses the exact
same format as the arguments of the angle_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Angle Coeffs" section of a data file, the line that
corresponds to the 1st example above would be listed as
.. parsed-literal::
1 300.0 107.0
The :doc:`angle_style class2 <angle_class2>` is an exception to this
rule, in that an additional argument is used in the input script to
allow specification of the cross-term coefficients. See its
doc page for details.
----------
Here is an alphabetic list of angle styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`angle_coeff <angle_coeff>` command.
Note that there are also additional angle styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the angle section of :ref:`this page <cmd_5>`.
* :doc:`angle_style none <angle_none>` - turn off angle interactions
* :doc:`angle_style hybrid <angle_hybrid>` - define multiple styles of angle interactions
* :doc:`angle_style charmm <angle_charmm>` - CHARMM angle
* :doc:`angle_style class2 <angle_class2>` - COMPASS (class 2) angle
* :doc:`angle_style cosine <angle_cosine>` - cosine angle potential
* :doc:`angle_style cosine/delta <angle_cosine_delta>` - difference of cosines angle potential
* :doc:`angle_style cosine/periodic <angle_cosine_periodic>` - DREIDING angle
* :doc:`angle_style cosine/squared <angle_cosine_squared>` - cosine squared angle potential
* :doc:`angle_style harmonic <angle_harmonic>` - harmonic angle
* :doc:`angle_style table <angle_table>` - tabulated by angle
----------
Restrictions
""""""""""""
This command must come after the simulation box is defined by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
An angle style must be defined before any angle coefficients are
set, either in the input script or in a data file.
Related commands
""""""""""""""""
:doc:`angle_style <angle_style>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

85
doc/_sources/angle_cosine.txt
View File

@ -1,85 +0,0 @@
.. index:: angle_style cosine
angle_style cosine command
==========================
angle_style cosine/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style cosine
Examples
""""""""
.. parsed-literal::
angle_style cosine
angle_coeff * 75.0
Description
"""""""""""
The *cosine* angle style uses the potential
.. image:: Eqs/angle_cosine.jpg
:align: center
where K is defined for each angle type.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_delta.txt
View File

@ -1,90 +0,0 @@
.. index:: angle_style cosine/delta
angle_style cosine/delta command
================================
angle_style cosine/delta/omp command
====================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/delta
Examples
""""""""
.. parsed-literal::
angle_style cosine/delta
angle_coeff 2*4 75.0 100.0
Description
"""""""""""
The *cosine/delta* angle style uses the potential
.. image:: Eqs/angle_cosine_delta.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style cosine/squared <angle_cosine_squared>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/angle_cosine_periodic.txt
View File

@ -1,109 +0,0 @@
.. index:: angle_style cosine/periodic
angle_style cosine/periodic command
===================================
angle_style cosine/periodic/omp command
=======================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/periodic
Examples
""""""""
.. parsed-literal::
angle_style cosine/periodic
angle_coeff * 75.0 1 6
Description
"""""""""""
The *cosine/periodic* angle style uses the following potential, which
is commonly used in the :ref:`DREIDING <howto_4>` force
field, particularly for organometallic systems where *n* = 4 might be
used for an octahedral complex and *n* = 3 might be used for a
trigonal center:
.. image:: Eqs/angle_cosine_periodic.jpg
:align: center
where C, B and n are coefficients defined for each angle type.
See :ref:`(Mayo) <Mayo>` for a description of the DREIDING force field
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* C (energy)
* B = 1 or -1
* n = 1, 2, 3, 4, 5 or 6 for periodicity
Note that the prefactor C is specified and not the overall force
constant K = C / n^2. When B = 1, it leads to a minimum for the
linear geometry. When B = -1, it leads to a maximum for the linear
geometry.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
----------
.. _Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_shift.txt
View File

@ -1,90 +0,0 @@
.. index:: angle_style cosine/shift
angle_style cosine/shift command
================================
angle_style cosine/shift/omp command
====================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/shift
Examples
""""""""
.. parsed-literal::
angle_style cosine/shift
angle_coeff * 10.0 45.0
Description
"""""""""""
The *cosine/shift* angle style uses the potential
.. image:: Eqs/angle_cosine_shift.jpg
:align: center
where theta0 is the equilibrium angle. The potential is bounded
between -Umin and zero. In the neighborhood of the minimum E=- Umin +
Umin/4(theta-theta0)^2 hence the spring constant is umin/2.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* umin (energy)
* theta (angle)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`,
:doc:`angle_cosineshiftexp <angle_cosineshiftexp>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

103
doc/_sources/angle_cosine_shift_exp.txt
View File

@ -1,103 +0,0 @@
.. index:: angle_style cosine/shift/exp
angle_style cosine/shift/exp command
====================================
angle_style cosine/shift/exp/omp command
========================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/shift/exp
Examples
""""""""
.. parsed-literal::
angle_style cosine/shift/exp
angle_coeff * 10.0 45.0 2.0
Description
"""""""""""
The *cosine/shift/exp* angle style uses the potential
.. image:: Eqs/angle_cosine_shift_exp.jpg
:align: center
where Umin, theta, and a are defined for each angle type.
The potential is bounded between [-Umin:0] and the minimum is
located at the angle theta0. The a parameter can be both positive or
negative and is used to control the spring constant at the
equilibrium.
The spring constant is given by k = A exp(A) Umin / [2 (Exp(a)-1)].
For a > 3, k/Umin = a/2 to better than 5% relative error. For negative
values of the a parameter, the spring constant is essentially zero,
and anharmonic terms takes over. The potential is furthermore well
behaved in the limit a -> 0, where it has been implemented to linear
order in a for a < 0.001. In this limit the potential reduces to the
cosineshifted potential.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* umin (energy)
* theta (angle)
* A (real number)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`,
:doc:`angle_cosineshift <angle_cosineshift>`,
:doc:`dihedral_cosineshift <dihedral_cosineshift>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/angle_cosine_squared.txt
View File

@ -1,90 +0,0 @@
.. index:: angle_style cosine/squared
angle_style cosine/squared command
==================================
angle_style cosine/squared/omp command
======================================
Syntax
""""""
.. parsed-literal::
angle_style cosine/squared
Examples
""""""""
.. parsed-literal::
angle_style cosine/squared
angle_coeff 2*4 75.0 100.0
Description
"""""""""""
The *cosine/squared* angle style uses the potential
.. image:: Eqs/angle_cosine_squared.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

147
doc/_sources/angle_dipole.txt
View File

@ -1,147 +0,0 @@
.. index:: angle_style dipole
angle_style dipole command
==========================
angle_style dipole/omp command
==============================
Syntax
""""""
.. parsed-literal::
angle_style dipole
Examples
""""""""
.. parsed-literal::
angle_style dipole
angle_coeff 6 2.1 180.0
Description
"""""""""""
The *dipole* angle style is used to control the orientation of a dipolar
atom within a molecule :ref:`(Orsi) <Orsi>`. Specifically, the *dipole* angle
style restrains the orientation of a point dipole mu_j (embedded in atom
'j') with respect to a reference (bond) vector r_ij = r_i - r_j, where 'i'
is another atom of the same molecule (typically, 'i' and 'j' are also
covalently bonded).
It is convenient to define an angle gamma between the 'free' vector mu_j
and the reference (bond) vector r_ij:
.. image:: Eqs/angle_dipole_gamma.jpg
:align: center
The *dipole* angle style uses the potential:
.. image:: Eqs/angle_dipole_potential.jpg
:align: center
where K is a rigidity constant and gamma0 is an equilibrium (reference)
angle.
The torque on the dipole can be obtained by differentiating the
potential using the 'chain rule' as in appendix C.3 of
:ref:`(Allen) <Allen>`:
.. image:: Eqs/angle_dipole_torque.jpg
:align: center
Example: if gamma0 is set to 0 degrees, the torque generated by
the potential will tend to align the dipole along the reference
direction defined by the (bond) vector r_ij (in other words, mu_j is
restrained to point towards atom 'i').
Note that the angle dipole potential does not give rise to any force,
because it does not depend on the distance between i and j (it only
depends on the angle between mu_j and r_ij).
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* gamma0 (degrees)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_6>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <2_3>`
section for more info on packages.
.. warning::
In the "Angles" section of the data file, the atom ID
'j' corresponding to the dipole to restrain must come before the atom
ID of the reference atom 'i'. A third atom ID 'k' must also be
provided, although 'k' is just a 'dummy' atom which can be any atom;
it may be useful to choose a convention (e.g., 'k'='i') and adhere to
it. For example, if ID=1 for the dipolar atom to restrain, and ID=2
for the reference atom, the corresponding line in the "Angles" section
of the data file would read: X X 1 2 2
The "newton" command for intramolecular interactions must be "on"
(which is the default).
This angle style should not be used with SHAKE.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_hybrid <angle_hybrid>`
**Default:** none
----------
.. _Orsi:
**(Orsi)** Orsi & Essex, The ELBA force field for coarse-grain modeling of
lipid membranes, PloS ONE 6(12): e28637, 2011.
.. _Allen:
**(Allen)** Allen & Tildesley, Computer Simulation of Liquids,
Clarendon Press, Oxford, 1987.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

85
doc/_sources/angle_fourier.txt
View File

@ -1,85 +0,0 @@
.. index:: angle_style fourier
angle_style fourier command
===========================
angle_style fourier/omp command
===============================
Syntax
""""""
.. parsed-literal::
angle_style fourier
Examples
""""""""
angle_style fourier
angle_coeff 75.0 1.0 1.0 1.0
Description
"""""""""""
The *fourier* angle style uses the potential
.. image:: Eqs/angle_fourier.jpg
:align: center
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* C0 (real)
* C1 (real)
* C2 (real)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

84
doc/_sources/angle_fourier_simple.txt
View File

@ -1,84 +0,0 @@
.. index:: angle_style fourier/simple
angle_style fourier/simple command
==================================
angle_style fourier/simple/omp command
======================================
Syntax
""""""
.. parsed-literal::
angle_style fourier/simple
Examples
""""""""
angle_style fourier/simple
angle_coeff 100.0 -1.0 1.0
Description
"""""""""""
The *fourier/simple* angle style uses the potential
.. image:: Eqs/angle_fourier_simple.jpg
:align: center
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy)
* c (real)
* n (real)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/angle_harmonic.txt
View File

@ -1,93 +0,0 @@
.. index:: angle_style harmonic
angle_style harmonic command
============================
angle_style harmonic/kk command
===============================
angle_style harmonic/omp command
================================
Syntax
""""""
.. parsed-literal::
angle_style harmonic
Examples
""""""""
.. parsed-literal::
angle_style harmonic
angle_coeff 1 300.0 107.0
Description
"""""""""""
The *harmonic* angle style uses the potential
.. image:: Eqs/angle_harmonic.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/radian^2)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
none
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/angle_hybrid.txt
View File

@ -1,109 +0,0 @@
.. index:: angle_style hybrid
angle_style hybrid command
==========================
Syntax
""""""
.. parsed-literal::
angle_style hybrid style1 style2 ...
* style1,style2 = list of one or more angle styles
Examples
""""""""
.. parsed-literal::
angle_style hybrid harmonic cosine
angle_coeff 1 harmonic 80.0 30.0
angle_coeff 2* cosine 50.0
Description
"""""""""""
The *hybrid* style enables the use of multiple angle styles in one
simulation. An angle style is assigned to each angle type. For
example, angles in a polymer flow (of angle type 1) could be computed
with a *harmonic* potential and angles in the wall boundary (of angle
type 2) could be computed with a *cosine* potential. The assignment
of angle type to style is made via the :doc:`angle_coeff <angle_coeff>`
command or in the data file.
In the angle_coeff commands, the name of an angle style must be added
after the angle type, with the remaining coefficients being those
appropriate to that style. In the example above, the 2 angle_coeff
commands set angles of angle type 1 to be computed with a *harmonic*
potential with coefficients 80.0, 30.0 for K, theta0. All other angle
types (2-N) are computed with a *cosine* potential with coefficient
50.0 for K.
If angle coefficients are specified in the data file read via the
:doc:`read_data <read_data>` command, then the same rule applies.
E.g. "harmonic" or "cosine", must be added after the angle type, for each
line in the "Angle Coeffs" section, e.g.
.. parsed-literal::
Angle Coeffs
.. parsed-literal::
1 harmonic 80.0 30.0
2 cosine 50.0
...
If *class2* is one of the angle hybrid styles, the same rule holds for
specifying additional BondBond (and BondAngle) coefficients either via
the input script or in the data file. I.e. *class2* must be added to
each line after the angle type. For lines in the BondBond (or
BondAngle) section of the data file for angle types that are not
*class2*, you must use an angle style of *skip* as a placeholder, e.g.
.. parsed-literal::
BondBond Coeffs
.. parsed-literal::
1 skip
2 class2 3.6512 1.0119 1.0119
...
Note that it is not necessary to use the angle style *skip* in the
input script, since BondBond (or BondAngle) coefficients need not be
specified at all for angle types that are not *class2*.
An angle style of *none* with no additional coefficients can be used
in place of an angle style, either in a input script angle_coeff
command or in the data file, if you desire to turn off interactions
for specific angle types.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Unlike other angle styles, the hybrid angle style does not store angle
coefficient info for individual sub-styles in a :doc:`binary restart files <restart>`. Thus when retarting a simulation from a restart
file, you need to re-specify angle_coeff commands.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

38
doc/_sources/angle_none.txt
View File

@ -1,38 +0,0 @@
.. index:: angle_style none
angle_style none command
========================
Syntax
""""""
.. parsed-literal::
angle_style none
Examples
""""""""
.. parsed-literal::
angle_style none
Description
"""""""""""
Using an angle style of none means angle forces are not computed, even
if triplets of angle atoms were listed in the data file read by the
:doc:`read_data <read_data>` command.
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/angle_quartic.txt
View File

@ -1,93 +0,0 @@
.. index:: angle_style quartic
angle_style quartic command
===========================
angle_style quartic/omp command
===============================
Syntax
""""""
.. parsed-literal::
angle_style quartic
Examples
""""""""
.. parsed-literal::
angle_style quartic
angle_coeff 1 129.1948 56.8726 -25.9442 -14.2221
Description
"""""""""""
The *quartic* angle style uses the potential
.. image:: Eqs/angle_quartic.jpg
:align: center
where theta0 is the equilibrium value of the angle, and K is a
prefactor. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* theta0 (degrees)
* K2 (energy/radian^2)
* K3 (energy/radian^3)
* K4 (energy/radian^4)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER_MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

70
doc/_sources/angle_sdk.txt
View File

@ -1,70 +0,0 @@
.. index:: angle_style sdk
angle_style sdk command
=======================
Syntax
""""""
.. parsed-literal::
angle_style sdk
.. parsed-literal::
angle_style sdk/omp
Examples
""""""""
.. parsed-literal::
angle_style sdk
angle_coeff 1 300.0 107.0
Description
"""""""""""
The *sdk* angle style is a combination of the harmonic angle potential,
.. image:: Eqs/angle_harmonic.jpg
:align: center
where theta0 is the equilibrium value of the angle and K a prefactor,
with the *repulsive* part of the non-bonded *lj/sdk* pair style
between the atoms 1 and 3. This angle potential is intended for
coarse grained MD simulations with the CMM parametrization using the
:doc:`pair_style lj/sdk <pair_sdk>`. Relative to the pair_style
*lj/sdk*, however, the energy is shifted by *epsilon*, to avoid sudden
jumps. Note that the usual 1/2 factor is included in K.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above:
* K (energy/radian^2)
* theta0 (degrees)
Theta0 is specified in degrees, but LAMMPS converts it to radians
internally; hence the units of K are in energy/radian^2.
The also required *lj/sdk* parameters will be extracted automatically
from the pair_style.
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
USER-CG-CMM package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style harmonic <angle_harmonic>`, :doc:`pair_style lj/sdk <pair_sdk>`,
:doc:`pair_style lj/sdk/coul/long <pair_sdk>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

112
doc/_sources/angle_style.txt
View File

@ -1,112 +0,0 @@
.. index:: angle_style
angle_style command
===================
Syntax
""""""
.. parsed-literal::
angle_style style
* style = *none* or *hybrid* or *charmm* or *class2* or *cosine* or *cosine/squared* or *harmonic*
Examples
""""""""
.. parsed-literal::
angle_style harmonic
angle_style charmm
angle_style hybrid harmonic cosine
Description
"""""""""""
Set the formula(s) LAMMPS uses to compute angle interactions between
triplets of atoms, which remain in force for the duration of the
simulation. The list of angle triplets is read in by a
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>` command
from a data or restart file.
Hybrid models where angles are computed using different angle
potentials can be setup using the *hybrid* angle style.
The coefficients associated with a angle style can be specified in a
data or restart file or via the :doc:`angle_coeff <angle_coeff>` command.
All angle potentials store their coefficient data in binary restart
files which means angle_style and :doc:`angle_coeff <angle_coeff>`
commands do not need to be re-specified in an input script that
restarts a simulation. See the :doc:`read_restart <read_restart>`
command for details on how to do this. The one exception is that
angle_style *hybrid* only stores the list of sub-styles in the restart
file; angle coefficients need to be re-specified.
.. warning::
When both an angle and pair style is defined, the
:doc:`special_bonds <special_bonds>` command often needs to be used to
turn off (or weight) the pairwise interaction that would otherwise
exist between 3 bonded atoms.
In the formulas listed for each angle style, *theta* is the angle
between the 3 atoms in the angle.
----------
Here is an alphabetic list of angle styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`angle_coeff <angle_coeff>` command.
Note that there are also additional angle styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the angle section of :ref:`this page <cmd_5>`.
* :doc:`angle_style none <angle_none>` - turn off angle interactions
* :doc:`angle_style hybrid <angle_hybrid>` - define multiple styles of angle interactions
* :doc:`angle_style charmm <angle_charmm>` - CHARMM angle
* :doc:`angle_style class2 <angle_class2>` - COMPASS (class 2) angle
* :doc:`angle_style cosine <angle_cosine>` - cosine angle potential
* :doc:`angle_style cosine/delta <angle_cosine_delta>` - difference of cosines angle potential
* :doc:`angle_style cosine/periodic <angle_cosine_periodic>` - DREIDING angle
* :doc:`angle_style cosine/squared <angle_cosine_squared>` - cosine squared angle potential
* :doc:`angle_style harmonic <angle_harmonic>` - harmonic angle
* :doc:`angle_style table <angle_table>` - tabulated by angle
----------
Restrictions
""""""""""""
Angle styles can only be set for atom_styles that allow angles to be
defined.
Most angle styles are part of the MOLECULE package. They are only
enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The doc pages for individual bond potentials tell if it is part of a
package.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
Default
"""""""
.. parsed-literal::
angle_style none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

175
doc/_sources/angle_table.txt
View File

@ -1,175 +0,0 @@
.. index:: angle_style table
angle_style table command
=========================
angle_style table/omp command
=============================
Syntax
""""""
.. parsed-literal::
angle_style table style N
* style = *linear* or *spline* = method of interpolation
* N = use N values in table
Examples
""""""""
.. parsed-literal::
angle_style table linear 1000
angle_coeff 3 file.table ENTRY1
Description
"""""""""""
Style *table* creates interpolation tables of length *N* from angle
potential and derivative values listed in a file(s) as a function of
angle The files are read by the :doc:`angle_coeff <angle_coeff>`
command.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and derivative values at each of
*N* angles. During a simulation, these tables are used to interpolate
energy and force values on individual atoms as needed. The
interpolation is done in one of 2 styles: *linear* or *spline*.
For the *linear* style, the angle is used to find 2 surrounding table
values from which an energy or its derivative is computed by linear
interpolation.
For the *spline* style, a cubic spline coefficients are computed and
stored at each of the *N* values in the table. The angle is used to
find the appropriate set of coefficients which are used to evaluate a
cubic polynomial which computes the energy or derivative.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above.
* filename
* keyword
The filename specifies a file containing tabulated energy and
derivative values. The keyword specifies a section of the file. The
format of this file is described below.
----------
The format of a tabulated file is as follows (without the
parenthesized comments):
.. parsed-literal::
# Angle potential for harmonic (one or more comment or blank lines)
.. parsed-literal::
HAM (keyword is the first text on line)
N 181 FP 0 0 EQ 90.0 (N, FP, EQ parameters)
(blank line)
N 181 FP 0 0 (N, FP parameters)
1 0.0 200.5 2.5 (index, angle, energy, derivative)
2 1.0 198.0 2.5
...
181 180.0 0.0 0.0
A section begins with a non-blank line whose 1st character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
:doc:`angle_coeff <angle_coeff>` command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
The parameter "N" is required and its value is the number of table
entries that follow. Note that this may be different than the *N*
specified in the :doc:`angle_style table <angle_style>` command. Let
Ntable = *N* in the angle_style command, and Nfile = "N" in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and derivative
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual angles and their atoms. This means that if you
want the interpolation tables of length Ntable to match exactly what
is in the tabulated file (with effectively no preliminary
interpolation), you should set Ntable = Nfile.
The "FP" parameter is optional. If used, it is followed by two values
fplo and fphi, which are the 2nd derivatives at the innermost and
outermost angle settings. These values are needed by the spline
construction routines. If not specified by the "FP" parameter, they
are estimated (less accurately) by the first two and last two
derivative values in the table.
The "EQ" parameter is also optional. If used, it is followed by a the
equilibrium angle value, which is used, for example, by the :doc:`fix shake <fix_shake>` command. If not used, the equilibrium angle is
set to 180.0.
Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the angle value (in degrees), the 3rd value is the energy (in energy
units), and the 4th is -dE/d(theta) (also in energy units). The 3rd
term is the energy of the 3-atom configuration for the specified
angle. The last term is the derivative of the energy with respect to
the angle (in degrees, not radians). Thus the units of the last term
are still energy, not force. The angle values must increase from one
line to the next. The angle values must also begin with 0.0 and end
with 180.0, i.e. span the full range of possible angles.
Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

186
doc/_sources/atom_modify.txt
View File

@ -1,186 +0,0 @@
.. index:: atom_modify
atom_modify command
===================
Syntax
""""""
.. parsed-literal::
atom_modify keyword values ...
* one or more keyword/value pairs may be appended
* keyword = *id* or *map* or *first* or *sort*
.. parsed-literal::
*id* value = *yes* or *no*
*map* value = *array* or *hash*
*first* value = group-ID = group whose atoms will appear first in internal atom lists
*sort* values = Nfreq binsize
Nfreq = sort atoms spatially every this many time steps
binsize = bin size for spatial sorting (distance units)
Examples
""""""""
.. parsed-literal::
atom_modify map hash
atom_modify map array sort 10000 2.0
atom_modify first colloid
Description
"""""""""""
Modify certain attributes of atoms defined and stored within LAMMPS,
in addition to what is specified by the :doc:`atom_style <atom_style>`
command. The *id* and *map* keywords must be specified before a
simulation box is defined; other keywords can be specified any time.
The *id* keyword determines whether non-zero atom IDs can be assigned
to each atom. If the value is *yes*, which is the default, IDs are
assigned, whether you use the :doc:`create atoms <create_atoms>` or
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands to initialize atoms. If the value is *no* the IDs for all
atoms are assumed to be 0.
If atom IDs are used, they must all be positive integers. They should
also be unique, though LAMMPS does not check for this. Typically they
should also be consecutively numbered (from 1 to Natoms), though this
is not required. Molecular :doc:`atom styles <atom_style>` are those
that store bond topology information (styles bond, angle, molecular,
full). These styles require atom IDs since the IDs are used to encode
the topology. Some other LAMMPS commands also require the use of atom
IDs. E.g. some many-body pair styles use them to avoid double
computation of the I-J interaction between two atoms.
The only reason not to use atom IDs is if you are running an atomic
simulation so large that IDs cannot be uniquely assigned. For a
default LAMMPS build this limit is 2^31 or about 2 billion atoms.
However, even in this case, you can use 64-bit atom IDs, allowing 2^63
or about 9e18 atoms, if you build LAMMPS with the - DLAMMPS_BIGBIG
switch. This is described in :ref:`Section 2.2 <start_2>`
of the manual. If atom IDs are not used, they must be specified as 0
for all atoms, e.g. in a data or restart file.
The *map* keyword determines how atom ID lookup is done for molecular
atom styles. Lookups are performed by bond (angle, etc) routines in
LAMMPS to find the local atom index associated with a global atom ID.
When the *array* value is used, each processor stores a lookup table
of length N, where N is the largest atom ID in the system. This is a
fast, simple method for many simulations, but requires too much memory
for large simulations. The *hash* value uses a hash table to perform
the lookups. This can be slightly slower than the *array* method, but
its memory cost is proportional to the number of atoms owned by a
processor, i.e. N/P when N is the total number of atoms in the system
and P is the number of processors.
When this setting is not specified in your input script, LAMMPS
creates a map, if one is needed, as an array or hash. See the
discussion of default values below for how LAMMPS chooses which kind
of map to build. Note that atomic systems do not normally need to
create a map. However, even in this case some LAMMPS commands will
create a map to find atoms (and then destroy it), or require a
permanent map. An example of the former is the :doc:`velocity loop all <velocity>` command, which uses a map when looping over all
atoms and insuring the same velocity values are assigned to an atom
ID, no matter which processor owns it.
The *first* keyword allows a :doc:`group <group>` to be specified whose
atoms will be maintained as the first atoms in each processor's list
of owned atoms. This in only useful when the specified group is a
small fraction of all the atoms, and there are other operations LAMMPS
is performing that will be sped-up significantly by being able to loop
over the smaller set of atoms. Otherwise the reordering required by
this option will be a net slow-down. The :doc:`neigh_modify include <neigh_modify>` and :doc:`comm_modify group <comm_modify>`
commands are two examples of commands that require this setting to
work efficiently. Several :doc:`fixes <fix>`, most notably time
integration fixes like :doc:`fix nve <fix_nve>`, also take advantage of
this setting if the group they operate on is the group specified by
this command. Note that specifying "all" as the group-ID effectively
turns off the *first* option.
It is OK to use the *first* keyword with a group that has not yet been
defined, e.g. to use the atom_modify first command at the beginning of
your input script. LAMMPS does not use the group until a simullation
is run.
The *sort* keyword turns on a spatial sorting or reordering of atoms
within each processor's sub-domain every *Nfreq* timesteps. If
*Nfreq* is set to 0, then sorting is turned off. Sorting can improve
cache performance and thus speed-up a LAMMPS simulation, as discussed
in a paper by :ref:`(Meloni) <Meloni>`. Its efficacy depends on the problem
size (atoms/processor), how quickly the system becomes disordered, and
various other factors. As a general rule, sorting is typically more
effective at speeding up simulations of liquids as opposed to solids.
In tests we have done, the speed-up can range from zero to 3-4x.
Reordering is peformed every *Nfreq* timesteps during a dynamics run
or iterations during a minimization. More precisely, reordering
occurs at the first reneighboring that occurs after the target
timestep. The reordering is performed locally by each processor,
using bins of the specified *binsize*. If *binsize* is set to 0.0,
then a binsize equal to half the :doc:`neighbor <neighbor>` cutoff
distance (force cutoff plus skin distance) is used, which is a
reasonable value. After the atoms have been binned, they are
reordered so that atoms in the same bin are adjacent to each other in
the processor's 1d list of atoms.
The goal of this procedure is for atoms to put atoms close to each
other in the processor's one-dimensional list of atoms that are also
near to each other spatially. This can improve cache performance when
pairwise intereractions and neighbor lists are computed. Note that if
bins are too small, there will be few atoms/bin. Likewise if bins are
too large, there will be many atoms/bin. In both cases, the goal of
cache locality will be undermined.
.. warning::
Running a simulation with sorting on versus off should
not change the simulation results in a statistical sense. However, a
different ordering will induce round-off differences, which will lead
to diverging trajectories over time when comparing two simluations.
Various commands, particularly those which use random numbers
(e.g. :doc:`velocity create <velocity>`, and :doc:`fix langevin <fix_langevin>`), may generate (statistically identical)
results which depend on the order in which atoms are processed. The
order of atoms in a :doc:`dump <dump>` file will also typically change
if sorting is enabled.
Restrictions
""""""""""""
The *first* and *sort* options cannot be used together. Since sorting
is on by default, it will be turned off if the *first* keyword is
used with a group-ID that is not "all".
**Related commands:** none
Default
"""""""
By default, *id* is yes. By default, atomic systems (no bond topology
info) do not use a map. For molecular systems (with bond topology
info), a map is used. The default map style is array if no atom ID is
larger than 1 million, otherwise the default is hash. By default, a
"first" group is not defined. By default, sorting is enabled with a
frequency of 1000 and a binsize of 0.0, which means the neighbor
cutoff will be used to set the bin size.
----------
.. _Meloni:
**(Meloni)** Meloni, Rosati and Colombo, J Chem Phys, 126, 121102 (2007).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

294
doc/_sources/atom_style.txt
View File

@ -1,294 +0,0 @@
.. index:: atom_style
atom_style command
==================
Syntax
""""""
.. parsed-literal::
atom_style style args
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *electron* or *ellipsoid* or *full* or *line* or *meso* or *molecular* or *peri* or *sphere* or *tri* or *template* or *hybrid*
.. parsed-literal::
args = none for any style except *body* and *hybrid*
*body* args = bstyle bstyle-args
bstyle = style of body particles
bstyle-args = additional arguments specific to the bstyle
see the :doc:`body <body>` doc page for details
*template* args = template-ID
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
*hybrid* args = list of one or more sub-styles, each with their args
* accelerated styles (with same args) = *angle/cuda* or *angle/kk* or *atomic/cuda* or *atomic/kk* or *bond/kk* or *charge/cuda* or *charge/kk* or *full/cuda* or *full/kk* or *molecular/kk*
Examples
""""""""
.. parsed-literal::
atom_style atomic
atom_style bond
atom_style full
atom_style full/cuda
atom_style body nparticle 2 10
atom_style hybrid charge bond
atom_style hybrid charge body nparticle 2 5
atom_style template myMols
Description
"""""""""""
Define what style of atoms to use in a simulation. This determines
what attributes are associated with the atoms. This command must be
used before a simulation is setup via a :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`, or :doc:`create_box <create_box>`
command.
Once a style is assigned, it cannot be changed, so use a style general
enough to encompass all attributes. E.g. with style *bond*, angular
terms cannot be used or added later to the model. It is OK to use a
style more general than needed, though it may be slightly inefficient.
The choice of style affects what quantities are stored by each atom,
what quantities are communicated between processors to enable forces
to be computed, and what quantities are listed in the data file read
by the :doc:`read_data <read_data>` command.
These are the additional attributes of each style and the typical
kinds of physical systems they are used to model. All styles store
coordinates, velocities, atom IDs and types. See the
:doc:`read_data <read_data>`, :doc:`create_atoms <create_atoms>`, and
:doc:`set <set>` commands for info on how to set these various
quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *angle* | bonds and angles | bead-spring polymers with stiffness |
+--------------+-----------------------------------------------------+--------------------------------------+
| *atomic* | only the default values | coarse-grain liquids, solids, metals |
+--------------+-----------------------------------------------------+--------------------------------------+
| *body* | mass, inertia moments, quaternion, angular momentum | arbitrary bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *bond* | bonds | bead-spring polymers |
+--------------+-----------------------------------------------------+--------------------------------------+
| *charge* | charge | atomic system with charges |
+--------------+-----------------------------------------------------+--------------------------------------+
| *dipole* | charge and dipole moment | system with dipolar particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *electron* | charge and spin and eradius | electronic force field |
+--------------+-----------------------------------------------------+--------------------------------------+
| *ellipsoid* | shape, quaternion, angular momentum | aspherical particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *full* | molecular + charge | bio-molecules |
+--------------+-----------------------------------------------------+--------------------------------------+
| *line* | end points, angular velocity | rigid bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *meso* | rho, e, cv | SPH particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *molecular* | bonds, angles, dihedrals, impropers | uncharged molecules |
+--------------+-----------------------------------------------------+--------------------------------------+
| *peri* | mass, volume | mesocopic Peridynamic models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *sphere* | diameter, mass, angular velocity | granular models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *template* | template index, template atom | small molecules with fixed topology |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tri* | corner points, angular momentum | rigid bodies |
+--------------+-----------------------------------------------------+--------------------------------------+
| *wavepacket* | charge, spin, eradius, etag, cs_re, cs_im | AWPMD |
+--------------+-----------------------------------------------------+--------------------------------------+
.. warning::
It is possible to add some attributes, such as a
molecule ID, to atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.
All of the above styles define point particles, except the *sphere*,
*ellipsoid*, *electron*, *peri*, *wavepacket*, *line*, *tri*, and
*body* styles, which define finite-size particles. See :ref:`Section_howto 14 <howto_14>` for an overview of using finite-size
particle models with LAMMPS.
All of the point-particle styles assign mass to particles on a
per-type basis, using the :doc:`mass <mass>` command, The finite-size
particle styles assign mass to individual particles on a per-particle
basis.
For the *sphere* style, the particles are spheres and each stores a
per-particle diameter and mass. If the diameter > 0.0, the particle
is a finite-size sphere. If the diameter = 0.0, it is a point
particle.
For the *ellipsoid* style, the particles are ellipsoids and each
stores a flag which indicates whether it is a finite-size ellipsoid or
a point particle. If it is an ellipsoid, it also stores a shape
vector with the 3 diamters of the ellipsoid and a quaternion 4-vector
with its orientation.
For the *electron* style, the particles representing electrons are 3d
Gaussians with a specified position and bandwidth or uncertainty in
position, which is represented by the eradius = electron size.
For the *peri* style, the particles are spherical and each stores a
per-particle mass and volume.
The *meso* style is for smoothed particle hydrodynamics (SPH)
particles which store a density (rho), energy (e), and heat capacity
(cv).
The *wavepacket* style is similar to *electron*, but the electrons may
consist of several Gaussian wave packets, summed up with coefficients
cs= (cs_re,cs_im). Each of the wave packets is treated as a separate
particle in LAMMPS, wave packets belonging to the same electron must
have identical *etag* values.
For the *line* style, the particles are idealized line segments and
each stores a per-particle mass and length and orientation (i.e. the
end points of the line segment).
For the *tri* style, the particles are planar triangles and each
stores a per-particle mass and size and orientation (i.e. the corner
points of the triangle).
The *template* style allows molecular topolgy (bonds,angles,etc) to be
defined via a molecule template using the `molecule <molecule.txt>`_
command. The template stores one or more molecules with a single copy
of the topology info (bonds,angles,etc) of each. Individual atoms
only store a template index and template atom to identify which
molecule and which atom-within-the-molecule they represent. Using the
*template* style instead of the *bond*, *angle*, *molecular* styles
can save memory for systems comprised of a large number of small
molecules, all of a single type (or small number of types). See the
paper by Grime and Voth, in :ref:`(Grime) <Grime>`, for examples of how this
can be advantageous for large-scale coarse-grained systems.
.. warning::
When using the *template* style with a :doc:`molecule template <molecule>` that contains multiple molecules, you should
insure the atom types, bond types, angle_types, etc in all the
molecules are consistent. E.g. if one molecule represents H2O and
another CO2, then you probably do not want each molecule file to
define 2 atom types and a single bond type, because they will conflict
with each other when a mixture system of H2O and CO2 molecules is
defined, e.g. by the :doc:`read_data <read_data>` command. Rather the
H2O molecule should define atom types 1 and 2, and bond type 1. And
the CO2 molecule should define atom types 3 and 4 (or atom types 3 and
2 if a single oxygen type is desired), and bond type 2.
For the *body* style, the particles are arbitrary bodies with internal
attributes defined by the "style" of the bodies, which is specified by
the *bstyle* argument. Body particles can represent complex entities,
such as surface meshes of discrete points, collections of
sub-particles, deformable objects, etc.
The :doc:`body <body>` doc page descibes the body styles LAMMPS
currently supports, and provides more details as to the kind of body
particles they represent. For all styles, each body particle stores
moments of inertia and a quaternion 4-vector, so that its orientation
and position can be time integrated due to forces and torques.
Note that there may be additional arguments required along with the
*bstyle* specification, in the atom_style body command. These
arguments are described in the :doc:`body <body>` doc page.
----------
Typically, simulations require only a single (non-hybrid) atom style.
If some atoms in the simulation do not have all the properties defined
by a particular style, use the simplest style that defines all the
needed properties by any atom. For example, if some atoms in a
simulation are charged, but others are not, use the *charge* style.
If some atoms have bonds, but others do not, use the *bond* style.
The only scenario where the *hybrid* style is needed is if there is no
single style which defines all needed properties of all atoms. For
example, if you want dipolar particles which will rotate due to
torque, you would need to use "atom_style hybrid sphere dipole". When
a hybrid style is used, atoms store and communicate the union of all
quantities implied by the individual styles.
When using the *hybrid* style, you cannot combine the *template* style
with another molecular style that stores bond,angle,etc info on a
per-atom basis.
LAMMPS can be extended with new atom styles as well as new body
styles; see :doc:`this section <Section_modify>`.
----------
Styles with a *cuda* or *kk* 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
:doc:`Section_accelerate <Section_accelerate>` of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.
Note that other acceleration packages in LAMMPS, specifically the GPU,
USER-INTEL, USER-OMP, and OPT packages do not use accelerated atom
styles.
The accelerated styles are part of the USER-CUDA and KOKKOS packages
respectively. They are only enabled if LAMMPS was built with those
packages. See the :ref:`Making LAMMPS <start_3>` section
for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command.
The *angle*, *bond*, *full*, *molecular*, and *template* styles are
part of the MOLECULE package. The *line* and *tri* styles are part
of the ASPHERE pacakge. The *body* style is part of the BODY package.
The *dipole* style is part of the DIPOLE package. The *peri* style is
part of the PERI package for Peridynamics. The *electron* style is
part of the USER-EFF package for :doc:`electronic force fields <pair_eff>`. The *meso* style is part of the USER-SPH
package for smoothed particle hydrodyanmics (SPH). See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS. The
*wavepacket* style is part of the USER-AWPMD package for the
:doc:`antisymmetrized wave packet MD method <pair_awpmd>`. They are
only enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`read_data <read_data>`, :doc:`pair_style <pair_style>`
Default
"""""""
atom_style atomic
----------
.. _Grime:
**(Grime)** Grime and Voth, to appear in J Chem Theory & Computation
(2014).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

387
doc/_sources/balance.txt
View File

@ -1,387 +0,0 @@
.. index:: balance
balance command
===============
Syntax
""""""
.. parsed-literal::
balance thresh style args ... keyword value ...
* thresh = imbalance threshhold that must be exceeded to perform a re-balance
* one style/arg pair can be used (or multiple for *x*,*y*,*z*)
* style = *x* or *y* or *z* or *shift* or *rcb*
.. parsed-literal::
*x* args = *uniform* or Px-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in x dimension
numbers = Px-1 ascending values between 0 and 1, Px - # of processors in x dimension
*x* can be specified together with *y* or *z*
*y* args = *uniform* or Py-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in y dimension
numbers = Py-1 ascending values between 0 and 1, Py - # of processors in y dimension
*y* can be specified together with *x* or *z*
*z* args = *uniform* or Pz-1 numbers between 0 and 1
*uniform* = evenly spaced cuts between processors in z dimension
numbers = Pz-1 ascending values between 0 and 1, Pz - # of processors in z dimension
*z* can be specified together with *x* or *y*
*shift* args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshhold is reached
*rcb* args = none
* zero or more keyword/value pairs may be appended
* keyword = *out*
.. parsed-literal::
*out* value = filename
filename = write each processor's sub-domain to a file
Examples
""""""""
.. parsed-literal::
balance 0.9 x uniform y 0.4 0.5 0.6
balance 1.2 shift xz 5 1.1
balance 1.0 shift xz 5 1.1
balance 1.1 rcb
balance 1.0 shift x 20 1.0 out tmp.balance
Description
"""""""""""
This command adjusts the size and shape of processor sub-domains
within the simulation box, to attempt to balance the number of
particles and thus the computational cost (load) evenly across
processors. The load balancing is "static" in the sense that this
command performs the balancing once, before or between simulations.
The processor sub-domains will then remain static during the
subsequent run. To perform "dynamic" balancing, see the :doc:`fix balance <fix_balance>` command, which can adjust processor
sub-domain sizes and shapes on-the-fly during a :doc:`run <run>`.
Load-balancing is typically only useful if the particles in the
simulation box have a spatially-varying density distribution. E.g. a
model of a vapor/liquid interface, or a solid with an irregular-shaped
geometry containing void regions. In this case, the LAMMPS default of
dividing the simulation box volume into a regular-spaced grid of 3d
bricks, with one equal-volume sub-domain per procesor, may assign very
different numbers of particles per processor. This can lead to poor
performance when the simulation is run in parallel.
Note that the :doc:`processors <processors>` command allows some control
over how the box volume is split across processors. Specifically, for
a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
Pz, subject to the constraint that Px * Py * Pz = P, the total number
of processors. This is sufficient to achieve good load-balance for
some problems on some processor counts. However, all the processor
sub-domains will still have the same shape and same volume.
The requested load-balancing operation is only performed if the
current "imbalance factor" in particles owned by each processor
exceeds the specified *thresh* parameter. The imbalance factor is
defined as the maximum number of particles owned by any processor,
divided by the average number of particles per processor. Thus an
imbalance factor of 1.0 is perfect balance.
As an example, for 10000 particles running on 10 processors, if the
most heavily loaded processor has 1200 particles, then the factor is
1.2, meaning there is a 20% imbalance. Note that a re-balance can be
forced even if the current balance is perfect (1.0) be specifying a
*thresh* < 1.0.
.. warning::
Balancing is performed even if the imbalance factor
does not exceed the *thresh* parameter if a "grid" style is specified
when the current partitioning is "tiled". The meaning of "grid" vs
"tiled" is explained below. This is to allow forcing of the
partitioning to "grid" so that the :doc:`comm_style brick <comm_style>`
command can then be used to replace a current :doc:`comm_style tiled <comm_style>` setting.
When the balance command completes, it prints statistics about the
result, including the change in the imbalance factor and the change in
the maximum number of particles on any processor. For "grid" methods
(defined below) that create a logical 3d grid of processors, the
positions of all cutting planes in each of the 3 dimensions (as
fractions of the box length) are also printed.
.. warning::
This command attempts to minimize the imbalance
factor, as defined above. But depending on the method a perfect
balance (1.0) may not be achieved. For example, "grid" methods
(defined below) that create a logical 3d grid cannot achieve perfect
balance for many irregular distributions of particles. Likewise, if a
portion of the system is a perfect lattice, e.g. the intiial system is
generated by the :doc:`create_atoms <create_atoms>` command, then "grid"
methods may be unable to achieve exact balance. This is because
entire lattice planes will be owned or not owned by a single
processor.
.. warning::
The imbalance factor is also an estimate of the
maximum speed-up you can hope to achieve by running a perfectly
balanced simulation versus an imbalanced one. In the example above,
the 10000 particle simulation could run up to 20% faster if it were
perfectly balanced, versus when imbalanced. However, computational
cost is not strictly proportional to particle count, and changing the
relative size and shape of processor sub-domains may lead to
additional computational and communication overheads, e.g. in the PPPM
solver used via the :doc:`kspace_style <kspace_style>` command. Thus
you should benchmark the run times of a simulation before and after
balancing.
----------
The method used to perform a load balance is specified by one of the
listed styles (or more in the case of *x*,*y*,*z*), which are
described in detail below. There are 2 kinds of styles.
The *x*, *y*, *z*, and *shift* styles are "grid" methods which produce
a logical 3d grid of processors. They operate by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the
volume (area in 2d) assigned to each processor, as in the following 2d
diagram where processor sub-domains are shown and atoms are colored by
the processor that owns them. The leftmost diagram is the default
partitioning of the simulation box across processors (one sub-box for
each of 16 processors); the middle diagram is after a "grid" method
has been applied.
.. thumbnail:: JPG/balance_uniform.jpg
:align: center
.. thumbnail:: JPG/balance_nonuniform.jpg
:align: center
.. thumbnail:: JPG/balance_rcb.jpg
:align: center
The *rcb* style is a "tiling" method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles in each sub-box, as
in the rightmost diagram above.
The "grid" methods can be used with either of the
:doc:`comm_style <comm_style>` command options, *brick* or *tiled*. The
"tiling" methods can only be used with :doc:`comm_style tiled <comm_style>`. Note that it can be useful to use a "grid"
method with :doc:`comm_style tiled <comm_style>` to return the domain
partitioning to a logical 3d grid of processors so that "comm_style
brick" can afterwords be specified for subsequent :doc:`run <run>`
commands.
When a "grid" method is specified, the current domain partitioning can
be either a logical 3d grid or a tiled partitioning. In the former
case, the current logical 3d grid is used as a starting point and
changes are made to improve the imbalance factor. In the latter case,
the tiled partitioning is discarded and a logical 3d grid is created
with uniform spacing in all dimensions. This becomes the starting
point for the balancing operation.
When a "tiling" method is specified, the current domain partitioning
("grid" or "tiled") is ignored, and a new partitioning is computed
from scratch.
----------
The *x*, *y*, and *z* styles invoke a "grid" method for balancing, as
described above. Note that any or all of these 3 styles can be
specified together, one after the other, but they cannot be used with
any other style. This style adjusts the position of cutting planes
between processor sub-domains in specific dimensions. Only the
specified dimensions are altered.
The *uniform* argument spaces the planes evenly, as in the left
diagrams above. The *numeric* argument requires listing Ps-1 numbers
that specify the position of the cutting planes. This requires
knowing Ps = Px or Py or Pz = the number of processors assigned by
LAMMPS to the relevant dimension. This assignment is made (and the
Px, Py, Pz values printed out) when the simulation box is created by
the "create_box" or "read_data" or "read_restart" command and is
influenced by the settings of the :doc:`processors <processors>`
command.
Each of the numeric values must be between 0 and 1, and they must be
listed in ascending order. They represent the fractional position of
the cutting place. The left (or lower) edge of the box is 0.0, and
the right (or upper) edge is 1.0. Neither of these values is
specified. Only the interior Ps-1 positions are specified. Thus is
there are 2 procesors in the x dimension, you specify a single value
such as 0.75, which would make the left processor's sub-domain 3x
larger than the right processor's sub-domain.
----------
The *shift* style invokes a "grid" method for balancing, as
described above. It changes the positions of cutting planes between
processors in an iterative fashion, seeking to reduce the imbalance
factor, similar to how the :doc:`fix balance shift <fix_balance>`
command operates.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.
Balancing proceeds by adjusting the cutting planes in each of the
dimensions listed in *dimstr*, one dimension at a time. For a single
dimension, the balancing operation (described below) is iterated on up
to *Niter* times. After each dimension finishes, the imbalance factor
is re-computed, and the balancing operation halts if the *stopthresh*
criterion is met.
A rebalance operation in a single dimension is performed using a
recursive multisectioning algorithm, where the position of each
cutting plane (line in 2d) in the dimension is adjusted independently.
This is similar to a recursive bisectioning for a single value, except
that the bounds used for each bisectioning take advantage of
information from neighboring cuts if possible. At each iteration, the
count of particles on either side of each plane is tallied. If the
counts do not match the target value for the plane, the position of
the cut is adjusted to be halfway between a low and high bound. The
low and high bounds are adjusted on each iteration, using new count
information, so that they become closer together over time. Thus as
the recustion progresses, the count of particles on either side of the
plane gets closer to the target value.
Once the rebalancing is complete and final processor sub-domains
assigned, particles are migrated to their new owning processor, and
the balance procedure ends.
.. warning::
At each rebalance operation, the bisectioning for each
cutting plane (line in 2d) typcially starts with low and high bounds
separated by the extent of a processor's sub-domain in one dimension.
The size of this bracketing region shrinks by 1/2 every iteration.
Thus if *Niter* is specified as 10, the cutting plane will typically
be positioned to 1 part in 1000 accuracy (relative to the perfect
target position). For *Niter* = 20, it will be accurate to 1 part in
a million. Thus there is no need ot set *Niter* to a large value.
LAMMPS will check if the threshold accuracy is reached (in a
dimension) is less iterations than *Niter* and exit early. However,
*Niter* should also not be set too small, since it will take roughly
the same number of iterations to converge even if the cutting plane is
initially close to the target value.
----------
The *rcb* style invokes a "tiled" method for balancing, as described
above. It performs a recursive coordinate bisectioning (RCB) of the
simulation domain. The basic idea is as follows.
The simulation domain is cut into 2 boxes by an axis-aligned cut in
the longest dimension, leaving one new box on either side of the cut.
All the processors are also partitioned into 2 groups, half assigned
to the box on the lower side of the cut, and half to the box on the
upper side. (If the processor count is odd, one side gets an extra
processor.) The cut is positioned so that the number of atoms in the
lower box is exactly the number that the processors assigned to that
box should own for load balance to be perfect. This also makes load
balance for the upper box perfect. The positioning is done
iteratively, by a bisectioning method. Note that counting atoms on
either side of the cut requires communication between all processors
at each iteration.
That is the procedure for the first cut. Subsequent cuts are made
recursively, in exactly the same manner. The subset of processors
assigned to each box make a new cut in the longest dimension of that
box, splitting the box, the subset of processsors, and the atoms in
the box in two. The recursion continues until every processor is
assigned a sub-box of the entire simulation domain, and owns the atoms
in that sub-box.
----------
The *out* keyword writes a text file to the specified *filename* with
the results of the balancing operation. The file contains the bounds
of the sub-domain for each processor after the balancing operation
completes. The format of the file is compatible with the
`Pizza.py <pizza>`_ *mdump* tool which has support for manipulating and
visualizing mesh files. An example is shown here for a balancing by 4
processors for a 2d problem:
.. parsed-literal::
ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16
The coordinates of all the vertices are listed in the NODES section, 5
per processor. Note that the 4 sub-domains share vertices, so there
will be duplicate nodes in the list.
The "SQUARES" section lists the node IDs of the 4 vertices in a
rectangle for each processor (1 to 4).
For a 3d problem, the syntax is similar with 8 vertices listed for
each processor, instead of 4, and "SQUARES" replaced by "CUBES".
----------
Restrictions
""""""""""""
For 2d simulations, the *z* style cannot be used. Nor can a "z"
appear in *dimstr* for the *shift* style.
Related commands
""""""""""""""""
:doc:`processors <processors>`, :doc:`fix balance <fix_balance>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

164
doc/_sources/body.txt
View File

@ -1,164 +0,0 @@
Body particles
==============
**Overview:**
This doc page is not about a LAMMPS input script command, but about
body particles, which are generalized finite-size particles.
Individual body particles can represent complex entities, such as
surface meshes of discrete points, collections of sub-particles,
deformable objects, etc. Note that other kinds of finite-size
spherical and aspherical particles are also supported by LAMMPS, such
as spheres, ellipsoids, line segments, and triangles, but they are
simpler entities that body particles. See :ref:`Section_howto 14 <howto_14>` for a general overview of all these
particle types.
Body particles are used via the :doc:`atom_style body <atom_style>`
command. It takes a body style as an argument. The current body
styles supported by LAMMPS are as follows. The name in the first
column is used as the *bstyle* argument for the :doc:`atom_style body <atom_style>` command.
+-------------+---------------------------------+
| *nparticle* | rigid body with N sub-particles |
+-------------+---------------------------------+
The body style determines what attributes are stored for each body and
thus how they can be used to compute pairwise body/body or
bond/non-body (point particle) interactions. More details of each
style are described below.
We hope to add more styles in the future. See :ref:`Section_modify 12 <mod_12>` for details on how to add a new body
style to the code.
----------
**When to use body particles:**
You should not use body particles to model a rigid body made of
simpler particles (e.g. point, sphere, ellipsoid, line segment,
triangular particles), if the interaction between pairs of rigid
bodies is just the summation of pairwise interactions between the
simpler particles. LAMMPS already supports this kind of model via the
:doc:`fix rigid <fix_rigid>` command. Any of the numerous pair styles
that compute interactions between simpler particles can be used. The
:doc:`fix rigid <fix_rigid>` command time integrates the motion of the
rigid bodies. All of the standard LAMMPS commands for thermostatting,
adding constraints, performing output, etc will operate as expected on
the simple particles.
By contrast, when body particles are used, LAMMPS treats an entire
body as a single particle for purposes of computing pairwise
interactions, building neighbor lists, migrating particles between
processors, outputting particles to a dump file, etc. This means that
interactions between pairs of bodies or between a body and non-body
(point) particle need to be encoded in an appropriate pair style. If
such a pair style were to mimic the :doc:`fix rigid <fix_rigid>` model,
it would need to loop over the entire collection of interactions
between pairs of simple particles within the two bodies, each time a
single body/body interaction was computed.
Thus it only makes sense to use body particles and develop such a pair
style, when particle/particle interactions are more complex than what
the :doc:`fix rigid <fix_rigid>` command can already calculate. For
example, if particles have one or more of the following attributes:
* represented by a surface mesh
* represented by a collection of geometric entities (e.g. planes + spheres)
* deformable
* internal stress that induces fragmentation
then the interaction between pairs of particles is likely to be more
complex than the summation of simple sub-particle interactions. An
example is contact or frictional forces between particles with planar
sufaces that inter-penetrate.
These are additional LAMMPS commands that can be used with body
particles of different styles
+------------------------------------------------+---------------------------------------------------+
| :doc:`fix nve/body <fix_nve_body>` | integrate motion of a body particle |
+------------------------------------------------+---------------------------------------------------+
| :doc:`compute body/local <compute_body_local>` | store sub-particle attributes of a body particle |
+------------------------------------------------+---------------------------------------------------+
| :doc:`dump local <dump>` | output sub-particle attributes of a body particle |
+------------------------------------------------+---------------------------------------------------+
The pair styles defined for use with specific body styles are listed
in the sections below.
----------
**Specifics of body style nparticle:**
The *nparticle* body style represents body particles as a rigid body
with a variable number N of sub-particles. It is provided as a
vanillia, prototypical example of a body particle, although as
mentioned above, the :doc:`fix rigid <fix_rigid>` command already
duplicates its functionality.
The atom_style body command for this body style takes two additional
arguments:
.. parsed-literal::
atom_style body nparticle Nmin Nmax
Nmin = minimum # of sub-particles in any body in the system
Nmax = maximum # of sub-particles in any body in the system
The Nmin and Nmax arguments are used to bound the size of data
structures used internally by each particle.
When the :doc:`read_data <read_data>` command reads a data file for this
body style, the following information must be provided for each entry
in the *Bodies* section of the data file:
.. parsed-literal::
atom-ID 1 M
N
ixx iyy izz ixy ixz iyz x1 y1 z1 ...
...
... xN yN zN
N is the number of sub-particles in the body particle. M = 6 + 3*N.
The integer line has a single value N. The floating point line(s)
list 6 moments of inertia followed by the coordinates of the N
sub-particles (x1 to zN) as 3N values on as many lines as required.
Note that this in not N lines, but 10 values per line; see the
:doc:`read_data <read_data>` command for details. The 6 moments of
inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the values consistent with
the current orientation of the rigid body around its center of mass.
The values are with respect to the simulation box XYZ axes, not with
respect to the prinicpal axes of the rigid body itself. LAMMPS
performs the latter calculation internally. The coordinates of each
sub-particle are specified as its x,y,z displacement from the
center-of-mass of the body particle. The center-of-mass position of
the particle is specified by the x,y,z values in the *Atoms* section
of the data file.
The :doc:`pair_style body <pair_body>` command can be used with this
body style to compute body/body and body/non-body interactions.
For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
commands, this body style produces one datum for each of the N
sub-particles in a body particle. The datum has 3 values:
.. parsed-literal::
1 = x position of sub-particle
2 = y position of sub-particle
3 = z position of sub-particle
These values are the current position of the sub-particle within the
simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientiation of the body particle.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

101
doc/_sources/bond_class2.txt
View File

@ -1,101 +0,0 @@
.. index:: bond_style class2
bond_style class2 command
=========================
bond_style class2/omp command
=============================
Syntax
""""""
.. parsed-literal::
bond_style class2
Examples
""""""""
.. parsed-literal::
bond_style class2
bond_coeff 1 1.0 100.0 80.0 80.0
Description
"""""""""""
The *class2* bond style uses the potential
.. image:: Eqs/bond_class2.jpg
:align: center
where r0 is the equilibrium bond distance.
See :ref:`(Sun) <Sun>` for a description of the COMPASS class2 force field.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* R0 (distance)
* K2 (energy/distance^2)
* K3 (energy/distance^3)
* K4 (energy/distance^4)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the CLASS2
package. See the :ref:`Making LAMMPS <start_3>` section
for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Sun:
**(Sun)** Sun, J Phys Chem B 102, 7338-7364 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

112
doc/_sources/bond_coeff.txt
View File

@ -1,112 +0,0 @@
.. index:: bond_coeff
bond_coeff command
==================
Syntax
""""""
.. parsed-literal::
bond_coeff N args
* N = bond type (see asterisk form below)
* args = coefficients for one or more bond types
Examples
""""""""
.. parsed-literal::
bond_coeff 5 80.0 1.2
bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
bond_coeff 1 harmonic 200.0 1.0
Description
"""""""""""
Specify the bond force field coefficients for one or more bond types.
The number and meaning of the coefficients depends on the bond style.
Bond coefficients can also be set in the data file read by the
:doc:`read_data <read_data>` command or in a restart file.
N can be specified in one of two ways. An explicit numeric value can
be used, as in the 1st example above. Or a wild-card asterisk can be
used to set the coefficients for multiple bond types. This takes the
form "*" or "*n" or "n*" or "m*n". If N = the number of bond types,
then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
Note that using a bond_coeff command can override a previous setting
for the same bond type. For example, these commands set the coeffs
for all bond types, then overwrite the coeffs for just bond type 2:
.. parsed-literal::
bond_coeff * 100.0 1.2
bond_coeff 2 200.0 1.2
A line in a data file that specifies bond coefficients uses the exact
same format as the arguments of the bond_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
under the "Bond Coeffs" section of a data file, the line that
corresponds to the 1st example above would be listed as
.. parsed-literal::
5 80.0 1.2
----------
Here is an alphabetic list of bond styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`bond_coeff <bond_coeff>` command.
Note that here are also additional bond styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the bond section of :ref:`this page <cmd_5>`.
* :doc:`bond_style none <bond_none>` - turn off bonded interactions
* :doc:`bond_style hybrid <bond_hybrid>` - define multiple styles of bond interactions
* :doc:`bond_style class2 <bond_class2>` - COMPASS (class 2) bond
* :doc:`bond_style fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
* :doc:`bond_style fene/expand <bond_fene_expand>` - FENE bonds with variable size particles
* :doc:`bond_style harmonic <bond_harmonic>` - harmonic bond
* :doc:`bond_style morse <bond_morse>` - Morse bond
* :doc:`bond_style nonlinear <bond_nonlinear>` - nonlinear bond
* :doc:`bond_style quartic <bond_quartic>` - breakable quartic bond
* :doc:`bond_style table <bond_table>` - tabulated by bond length
----------
Restrictions
""""""""""""
This command must come after the simulation box is defined by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
A bond style must be defined before any bond coefficients are set,
either in the input script or in a data file.
Related commands
""""""""""""""""
:doc:`bond_style <bond_style>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

109
doc/_sources/bond_fene.txt
View File

@ -1,109 +0,0 @@
.. index:: bond_style fene
bond_style fene command
=======================
bond_style fene/kk command
==========================
bond_style fene/omp command
===========================
Syntax
""""""
.. parsed-literal::
bond_style fene
Examples
""""""""
.. parsed-literal::
bond_style fene
bond_coeff 1 30.0 1.5 1.0 1.0
Description
"""""""""""
The *fene* bond style uses the potential
.. image:: Eqs/bond_fene.jpg
:align: center
to define a finite extensible nonlinear elastic (FENE) potential
:ref:`(Kremer) <Kremer>`, used for bead-spring polymer models. The first
term is attractive, the 2nd Lennard-Jones term is repulsive. The
first term extends to R0, the maximum extent of the bond. The 2nd
term is cutoff at 2^(1/6) sigma, the minimum of the LJ potential.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* R0 (distance)
* epsilon (energy)
* sigma (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
You typically should specify `special_bonds fene <special_bonds.html">`_
or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
style. LAMMPS will issue a warning it that's not the case.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Kremer:
**(Kremer)** Kremer, Grest, J Chem Phys, 92, 5057 (1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

111
doc/_sources/bond_fene_expand.txt
View File

@ -1,111 +0,0 @@
.. index:: bond_style fene/expand
bond_style fene/expand command
==============================
bond_style fene/expand/omp command
==================================
Syntax
""""""
.. parsed-literal::
bond_style fene/expand
Examples
""""""""
.. parsed-literal::
bond_style fene/expand
bond_coeff 1 30.0 1.5 1.0 1.0 0.5
Description
"""""""""""
The *fene/expand* bond style uses the potential
.. image:: Eqs/bond_fene_expand.jpg
:align: center
to define a finite extensible nonlinear elastic (FENE) potential
:ref:`(Kremer) <Kremer>`, used for bead-spring polymer models. The first
term is attractive, the 2nd Lennard-Jones term is repulsive.
The *fene/expand* bond style is similar to *fene* except that an extra
shift factor of delta (positive or negative) is added to *r* to
effectively change the bead size of the bonded atoms. The first term
now extends to R0 + delta and the 2nd term is cutoff at 2^(1/6) sigma
+ delta.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* R0 (distance)
* epsilon (energy)
* sigma (distance)
* delta (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
You typically should specify `special_bonds fene <special_bonds.html">`_
or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
style. LAMMPS will issue a warning it that's not the case.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Kremer:
**(Kremer)** Kremer, Grest, J Chem Phys, 92, 5057 (1990).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

90
doc/_sources/bond_harmonic.txt
View File

@ -1,90 +0,0 @@
.. index:: bond_style harmonic
bond_style harmonic command
===========================
bond_style harmonic/kk command
==============================
bond_style harmonic/omp command
===============================
Syntax
""""""
.. parsed-literal::
bond_style harmonic
Examples
""""""""
.. parsed-literal::
bond_style harmonic
bond_coeff 5 80.0 1.2
Description
"""""""""""
The *harmonic* bond style uses the potential
.. image:: Eqs/bond_harmonic.jpg
:align: center
where r0 is the equilibrium bond distance. Note that the usual 1/2
factor is included in K.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^2)
* r0 (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

94
doc/_sources/bond_harmonic_shift.txt
View File

@ -1,94 +0,0 @@
.. index:: bond_style harmonic/shift
bond_style harmonic/shift command
=================================
bond_style harmonic/shift/omp command
=====================================
Syntax
""""""
.. parsed-literal::
bond_style harmonic/shift
Examples
""""""""
.. parsed-literal::
bond_style harmonic/shift
bond_coeff 5 10.0 0.5 1.0
Description
"""""""""""
The *harmonic/shift* bond style is a shifted harmonic bond that uses
the potential
.. image:: Eqs/bond_harmonic_shift.jpg
:align: center
where r0 is the equilibrium bond distance, and rc the critical distance.
The potential is -Umin at r0 and zero at rc. The spring constant is
k = Umin / [ 2 (r0-rc)^2].
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Umin (energy)
* r0 (distance)
* rc (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_harmonic <bond_harmonic>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

93
doc/_sources/bond_harmonic_shift_cut.txt
View File

@ -1,93 +0,0 @@
.. index:: bond_style harmonic/shift/cut
bond_style harmonic/shift/cut command
=====================================
bond_style harmonic/shift/cut/omp command
=========================================
Syntax
""""""
.. parsed-literal::
bond_style harmonic/shift/cut
Examples
""""""""
.. parsed-literal::
bond_style harmonic/shift/cut
bond_coeff 5 10.0 0.5 1.0
Description
"""""""""""
The *harmonic/shift/cut* bond style is a shifted harmonic bond that
uses the potential
.. image:: Eqs/bond_harmonic_shift_cut.jpg
:align: center
where r0 is the equilibrium bond distance, and rc the critical distance.
The bond potential is zero for distances r > rc. The potential is -Umin
at r0 and zero at rc. The spring constant is k = Umin / [ 2 (r0-rc)^2].
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Umin (energy)
* r0 (distance)
* rc (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
USER-MISC package. See the :ref:`Making LAMMPS <start_3>`
section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_harmonic <bond_harmonic>`,
:doc:`bond_harmonicshift <bond_harmonicshift>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/bond_hybrid.txt
View File

@ -1,88 +0,0 @@
.. index:: bond_style hybrid
bond_style hybrid command
=========================
Syntax
""""""
.. parsed-literal::
bond_style hybrid style1 style2 ...
* style1,style2 = list of one or more bond styles
Examples
""""""""
.. parsed-literal::
bond_style hybrid harmonic fene
bond_coeff 1 harmonic 80.0 1.2
bond_coeff 2* fene 30.0 1.5 1.0 1.0
Description
"""""""""""
The *hybrid* style enables the use of multiple bond styles in one
simulation. A bond style is assigned to each bond type. For example,
bonds in a polymer flow (of bond type 1) could be computed with a
*fene* potential and bonds in the wall boundary (of bond type 2) could
be computed with a *harmonic* potential. The assignment of bond type
to style is made via the :doc:`bond_coeff <bond_coeff>` command or in
the data file.
In the bond_coeff commands, the name of a bond style must be added
after the bond type, with the remaining coefficients being those
appropriate to that style. In the example above, the 2 bond_coeff
commands set bonds of bond type 1 to be computed with a *harmonic*
potential with coefficients 80.0, 1.2 for K, r0. All other bond types
(2-N) are computed with a *fene* potential with coefficients 30.0,
1.5, 1.0, 1.0 for K, R0, epsilon, sigma.
If bond coefficients are specified in the data file read via the
:doc:`read_data <read_data>` command, then the same rule applies.
E.g. "harmonic" or "fene" must be added after the bond type, for each
line in the "Bond Coeffs" section, e.g.
.. parsed-literal::
Bond Coeffs
.. parsed-literal::
1 harmonic 80.0 1.2
2 fene 30.0 1.5 1.0 1.0
...
A bond style of *none* with no additional coefficients can be used in
place of a bond style, either in a input script bond_coeff command or
in the data file, if you desire to turn off interactions for specific
bond types.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Unlike other bond styles, the hybrid bond style does not store bond
coefficient info for individual sub-styles in a :doc:`binary restart files <restart>`. Thus when retarting a simulation from a restart
file, you need to re-specify bond_coeff commands.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/bond_morse.txt
View File

@ -1,88 +0,0 @@
.. index:: bond_style morse
bond_style morse command
========================
bond_style morse/omp command
============================
Syntax
""""""
.. parsed-literal::
bond_style morse
Examples
""""""""
.. parsed-literal::
bond_style morse
bond_coeff 5 1.0 2.0 1.2
Description
"""""""""""
The *morse* bond style uses the potential
.. image:: Eqs/bond_morse.jpg
:align: center
where r0 is the equilibrium bond distance, alpha is a stiffness
parameter, and D determines the depth of the potential well.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* D (energy)
* alpha (inverse distance)
* r0 (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

38
doc/_sources/bond_none.txt
View File

@ -1,38 +0,0 @@
.. index:: bond_style none
bond_style none command
=======================
Syntax
""""""
.. parsed-literal::
bond_style none
Examples
""""""""
.. parsed-literal::
bond_style none
Description
"""""""""""
Using a bond style of none means bond forces are not computed, even if
pairs of bonded atoms were listed in the data file read by the
:doc:`read_data <read_data>` command.
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

98
doc/_sources/bond_nonlinear.txt
View File

@ -1,98 +0,0 @@
.. index:: bond_style nonlinear
bond_style nonlinear command
============================
bond_style nonlinear/omp command
================================
Syntax
""""""
.. parsed-literal::
bond_style nonlinear
Examples
""""""""
.. parsed-literal::
bond_style nonlinear
bond_coeff 2 100.0 1.1 1.4
Description
"""""""""""
The *nonlinear* bond style uses the potential
.. image:: Eqs/bond_nonlinear.jpg
:align: center
to define an anharmonic spring :ref:`(Rector) <Rector>` of equilibrium
length r0 and maximum extension lamda.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* epsilon (energy)
* r0 (distance)
* lamda (distance)
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
----------
.. _Rector:
**(Rector)** Rector, Van Swol, Henderson, Molecular Physics, 82, 1009 (1994).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

128
doc/_sources/bond_quartic.txt
View File

@ -1,128 +0,0 @@
.. index:: bond_style quartic
bond_style quartic command
==========================
bond_style quartic/omp command
==============================
Syntax
""""""
.. parsed-literal::
bond_style quartic
Examples
""""""""
.. parsed-literal::
bond_style quartic
bond_coeff 2 1200 -0.55 0.25 1.3 34.6878
Description
"""""""""""
The *quartic* bond style uses the potential
.. image:: Eqs/bond_quartic.jpg
:align: center
to define a bond that can be broken as the simulation proceeds (e.g.
due to a polymer being stretched). The sigma and epsilon used in the
LJ portion of the formula are both set equal to 1.0 by LAMMPS.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* K (energy/distance^4)
* B1 (distance)
* B2 (distance)
* Rc (distance)
* U0 (energy)
This potential was constructed to mimic the FENE bond potential for
coarse-grained polymer chains. When monomers with sigma = epsilon =
1.0 are used, the following choice of parameters gives a quartic
potential that looks nearly like the FENE potential: K = 1200, B1 =
-0.55, B2 = 0.25, Rc = 1.3, and U0 = 34.6878. Different parameters
can be specified using the :doc:`bond_coeff <bond_coeff>` command, but
you will need to choose them carefully so they form a suitable bond
potential.
Rc is the cutoff length at which the bond potential goes smoothly to a
local maximum. If a bond length ever becomes > Rc, LAMMPS "breaks"
the bond, which means two things. First, the bond potential is turned
off by setting its type to 0, and is no longer computed. Second, a
pairwise interaction between the two atoms is turned on, since they
are no longer bonded.
LAMMPS does the second task via a computational sleight-of-hand. It
subtracts the pairwise interaction as part of the bond computation.
When the bond breaks, the subtraction stops. For this to work, the
pairwise interaction must always be computed by the
:doc:`pair_style <pair_style>` command, whether the bond is broken or
not. This means that :doc:`special_bonds <special_bonds>` must be set
to 1,1,1, as indicated as a restriction below.
Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 are not included. The
:doc:`delete_bonds <delete_bonds>` command can also be used to query the
status of broken bonds or permanently delete them, e.g.:
.. parsed-literal::
delete_bonds all stats
delete_bonds all bond 0 remove
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The *quartic* style requires that :doc:`special_bonds <special_bonds>`
parameters be set to 1,1,1. Three- and four-body interactions (angle,
dihedral, etc) cannot be used with *quartic* bonds.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

121
doc/_sources/bond_style.txt
View File

@ -1,121 +0,0 @@
.. index:: bond_style
bond_style command
==================
Syntax
""""""
.. parsed-literal::
bond_style style args
* style = *none* or *hybrid* or *class2* or *fene* or *fene/expand* or *harmonic* or *morse* or *nonlinear* or *quartic*
.. parsed-literal::
args = none for any style except *hybrid*
*hybrid* args = list of one or more styles
Examples
""""""""
.. parsed-literal::
bond_style harmonic
bond_style fene
bond_style hybrid harmonic fene
Description
"""""""""""
Set the formula(s) LAMMPS uses to compute bond interactions between
pairs of atoms. In LAMMPS, a bond differs from a pairwise
interaction, which are set via the :doc:`pair_style <pair_style>`
command. Bonds are defined between specified pairs of atoms and
remain in force for the duration of the simulation (unless the bond
breaks which is possible in some bond potentials). The list of bonded
atoms is read in by a :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command from a data or restart file.
By contrast, pair potentials are typically defined between all pairs
of atoms within a cutoff distance and the set of active interactions
changes over time.
Hybrid models where bonds are computed using different bond potentials
can be setup using the *hybrid* bond style.
The coefficients associated with a bond style can be specified in a
data or restart file or via the :doc:`bond_coeff <bond_coeff>` command.
All bond potentials store their coefficient data in binary restart
files which means bond_style and :doc:`bond_coeff <bond_coeff>` commands
do not need to be re-specified in an input script that restarts a
simulation. See the :doc:`read_restart <read_restart>` command for
details on how to do this. The one exception is that bond_style
*hybrid* only stores the list of sub-styles in the restart file; bond
coefficients need to be re-specified.
.. warning::
When both a bond and pair style is defined, the
:doc:`special_bonds <special_bonds>` command often needs to be used to
turn off (or weight) the pairwise interaction that would otherwise
exist between 2 bonded atoms.
In the formulas listed for each bond style, *r* is the distance
between the 2 atoms in the bond.
----------
Here is an alphabetic list of bond styles defined in LAMMPS. Click on
the style to display the formula it computes and coefficients
specified by the associated :doc:`bond_coeff <bond_coeff>` command.
Note that there are also additional bond styles submitted by users
which are included in the LAMMPS distribution. The list of these with
links to the individual styles are given in the bond section of :ref:`this page <cmd_5>`.
* :doc:`bond_style none <bond_none>` - turn off bonded interactions
* :doc:`bond_style hybrid <bond_hybrid>` - define multiple styles of bond interactions
* :doc:`bond_style class2 <bond_class2>` - COMPASS (class 2) bond
* :doc:`bond_style fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
* :doc:`bond_style fene/expand <bond_fene_expand>` - FENE bonds with variable size particles
* :doc:`bond_style harmonic <bond_harmonic>` - harmonic bond
* :doc:`bond_style morse <bond_morse>` - Morse bond
* :doc:`bond_style nonlinear <bond_nonlinear>` - nonlinear bond
* :doc:`bond_style quartic <bond_quartic>` - breakable quartic bond
* :doc:`bond_style table <bond_table>` - tabulated by bond length
----------
Restrictions
""""""""""""
Bond styles can only be set for atom styles that allow bonds to be
defined.
Most bond styles are part of the MOLECULE package. They are only
enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
The doc pages for individual bond potentials tell if it is part of a
package.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
Default
"""""""
bond_style none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

172
doc/_sources/bond_table.txt
View File

@ -1,172 +0,0 @@
.. index:: bond_style table
bond_style table command
========================
bond_style table/omp command
============================
Syntax
""""""
.. parsed-literal::
bond_style table style N
* style = *linear* or *spline* = method of interpolation
* N = use N values in table
Examples
""""""""
.. parsed-literal::
bond_style table linear 1000
bond_coeff 1 file.table ENTRY1
Description
"""""""""""
Style *table* creates interpolation tables of length *N* from bond
potential and force values listed in a file(s) as a function of bond
length. The files are read by the :doc:`bond_coeff <bond_coeff>`
command.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and force values at each of *N*
distances. During a simulation, these tables are used to interpolate
energy and force values as needed. The interpolation is done in one
of 2 styles: *linear* or *spline*.
For the *linear* style, the bond length is used to find 2 surrounding
table values from which an energy or force is computed by linear
interpolation.
For the *spline* style, a cubic spline coefficients are computed and
stored at each of the *N* values in the table. The bond length is
used to find the appropriate set of coefficients which are used to
evaluate a cubic polynomial which computes the energy or force.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above.
* filename
* keyword
The filename specifies a file containing tabulated energy and force
values. The keyword specifies a section of the file. The format of
this file is described below.
----------
The format of a tabulated file is as follows (without the
parenthesized comments):
.. parsed-literal::
# Bond potential for harmonic (one or more comment or blank lines)
.. parsed-literal::
HAM (keyword is the first text on line)
N 101 FP 0 0 EQ 0.5 (N, FP, EQ parameters)
(blank line)
1 0.00 338.0000 1352.0000 (index, bond-length, energy, force)
2 0.01 324.6152 1324.9600
...
101 1.00 338.0000 -1352.0000
A section begins with a non-blank line whose 1st character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
:doc:`bond_coeff <bond_coeff>` command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
The parameter "N" is required and its value is the number of table
entries that follow. Note that this may be different than the *N*
specified in the :doc:`bond_style table <bond_style>` command. Let
Ntable = *N* in the bond_style command, and Nfile = "N" in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and force
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual bond lengths. This means that if you want the
interpolation tables of length Ntable to match exactly what is in the
tabulated file (with effectively no preliminary interpolation), you
should set Ntable = Nfile.
The "FP" parameter is optional. If used, it is followed by two values
fplo and fphi, which are the derivatives of the force at the innermost
and outermost bond lengths. These values are needed by the spline
construction routines. If not specified by the "FP" parameter, they
are estimated (less accurately) by the first two and last two force
values in the table.
The "EQ" parameter is also optional. If used, it is followed by a the
equilibrium bond length, which is used, for example, by the :doc:`fix shake <fix_shake>` command. If not used, the equilibrium bond
length is set to 0.0.
Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the bond length r (in distance units), the 3rd value is the energy (in
energy units), and the 4th is the force (in force units). The bond
lengths must range from a LO value to a HI value, and increase from
one line to the next. If the actual bond length is ever smaller than
the LO value or larger than the HI value, then the bond energy and
force is evaluated as if the bond were the LO or HI length.
Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.
----------
Styles with a *cuda*, *gpu*, *intel*, *kk*, *omp*, or *opt* 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 :doc:`Section_accelerate <Section_accelerate>`
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.
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 :ref:`Making LAMMPS <start_3>` section for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :ref:`-suffix command-line switch <start_7>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See :doc:`Section_accelerate <Section_accelerate>` of the manual for
more instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the :ref:`Making LAMMPS <start_3>` section for more info on packages.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

114
doc/_sources/boundary.txt
View File

@ -1,114 +0,0 @@
.. index:: boundary
boundary command
================
Syntax
""""""
.. parsed-literal::
boundary x y z
* x,y,z = *p* or *s* or *f* or *m*, one or two letters
.. parsed-literal::
*p* is periodic
*f* is non-periodic and fixed
*s* is non-periodic and shrink-wrapped
*m* is non-periodic and shrink-wrapped with a minimum value
Examples
""""""""
.. parsed-literal::
boundary p p f
boundary p fs p
boundary s f fm
Description
"""""""""""
Set the style of boundaries for the global simulation box in each
dimension. A single letter assigns the same style to both the lower
and upper face of the box. Two letters assigns the first style to the
lower face and the second style to the upper face. The initial size
of the simulation box is set by the :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`, or :doc:`create_box <create_box>`
commands.
The style *p* means the box is periodic, so that particles interact
across the boundary, and they can exit one end of the box and re-enter
the other end. A periodic dimension can change in size due to
constant pressure boundary conditions or box deformation (see the :doc:`fix npt <fix_nh>` and :doc:`fix deform <fix_deform>` commands). The *p*
style must be applied to both faces of a dimension.
The styles *f*, *s*, and *m* mean the box is non-periodic, so that
particles do not interact across the boundary and do not move from one
side of the box to the other.
For style *f*, the position of the face is fixed. If an atom moves
outside the face it will be deleted on the next timestep that
reneighboring occurs. This will typically generate an error unless
you have set the :doc:`thermo_modify lost <thermo_modify>` option to
allow for lost atoms.
For style *s*, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move.
For style *m*, shrink-wrapping occurs, but is bounded by the value
specified in the data or restart file or set by the
:doc:`create_box <create_box>` command. For example, if the upper z
face has a value of 50.0 in the data file, the face will always be
positioned at 50.0 or above, even if the maximum z-extent of all the
atoms becomes less than 50.0. This can be useful if you start a
simulation with an empty box or if you wish to leave room on one side
of the box, e.g. for atoms to evaporate from a surface.
For triclinic (non-orthogonal) simulation boxes, if the 2nd dimension
of a tilt factor (e.g. y for xy) is periodic, then the periodicity is
enforced with the tilt factor offset. If the 1st dimension is
shrink-wrapped, then the shrink wrapping is applied to the tilted box
face, to encompass the atoms. E.g. for a positive xy tilt, the xlo
and xhi faces of the box are planes tilting in the +y direction as y
increases. These tilted planes are shrink-wrapped around the atoms to
determine the x extent of the box.
See :ref:`Section_howto 12 <howto_12>` of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
:doc:`read_restart <read_restart>` command. See the
:doc:`change_box <change_box>` command for how to change the simulation
box boundaries after it has been defined.
For 2d simulations, the z dimension must be periodic.
Related commands
""""""""""""""""
See the :doc:`thermo_modify <thermo_modify>` command for a discussion
of lost atoms.
Default
"""""""
.. parsed-literal::
boundary p p p
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

73
doc/_sources/box.txt
View File

@ -1,73 +0,0 @@
.. index:: box
box command
===========
Syntax
""""""
.. parsed-literal::
box keyword value ...
* one or more keyword/value pairs may be appended
* keyword = *tilt*
.. parsed-literal::
*tilt* value = *small* or *large*
Examples
""""""""
.. parsed-literal::
box tilt large
box tilt small
Description
"""""""""""
Set attributes of the simulation box.
For triclinic (non-orthogonal) simulation boxes, the *tilt* keyword
allows simulation domains to be created with arbitrary tilt factors,
e.g. via the :doc:`create_box <create_box>` or
:doc:`read_data <read_data>` commands. Tilt factors determine how
skewed the triclinic box is; see :ref:`this section <howto_12>` of the manual for a discussion of
triclinic boxes in LAMMPS.
LAMMPS normally requires that no tilt factor can skew the box more
than half the distance of the parallel box length, which is the 1st
dimension in the tilt factor (x for xz). If *tilt* is set to
*small*, which is the default, then an error will be
generated if a box is created which exceeds this limit. If *tilt*
is set to *large*, then no limit is enforced. You can create
a box with any tilt factors you wish.
Note that if a simulation box has a large tilt factor, LAMMPS will run
less efficiently, due to the large volume of communication needed to
acquire ghost atoms around a processor's irregular-shaped sub-domain.
For extreme values of tilt, LAMMPS may also lose atoms and generate an
error.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
:doc:`read_restart <read_restart>` command.
**Related commands:** none
Default
"""""""
The default value is tilt = small.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

380
doc/_sources/change_box.txt
View File

@ -1,380 +0,0 @@
.. index:: change_box
change_box command
==================
Syntax
""""""
.. parsed-literal::
change_box group-ID parameter args ... keyword args ...
* group-ID = ID of group of atoms to (optionally) displace
* one or more parameter/arg pairs may be appended
.. parsed-literal::
parameter = *x* or *y* or *z* or *xy* or *xz* or *yz* or *boundary* or *ortho* or *triclinic* or *set* or *remap*
*x*, *y*, *z* args = style value(s)
style = *final* or *delta* or *scale* or *volume*
*final* values = lo hi
lo hi = box boundaries after displacement (distance units)
*delta* values = dlo dhi
dlo dhi = change in box boundaries after displacement (distance units)
*scale* values = factor
factor = multiplicative factor for change in box length after displacement
*volume* value = none = adjust this dim to preserve volume of system
*xy*, *xz*, *yz* args = style value
style = *final* or *delta*
*final* value = tilt
tilt = tilt factor after displacement (distance units)
*delta* value = dtilt
dtilt = change in tilt factor after displacement (distance units)
*boundary* args = x y z
x,y,z = *p* or *s* or *f* or *m*, one or two letters
*p* is periodic
*f* is non-periodic and fixed
*s* is non-periodic and shrink-wrapped
*m* is non-periodic and shrink-wrapped with a minimum value
*ortho* args = none = change box to orthogonal
*triclinic* args = none = change box to triclinic
*set* args = none = store state of current box
*remap* args = none = remap atom coords from last saved state to current box
* zero or more keyword/value pairs may be appended
* keyword = *units*
.. parsed-literal::
*units* value = *lattice* or *box*
lattice = distances are defined in lattice units
box = distances are defined in simulation box units
Examples
""""""""
.. parsed-literal::
change_box all xy final -2.0 z final 0.0 5.0 boundary p p f remap units box
change_box all x scale 1.1 y volume z volume remap
Description
"""""""""""
Change the volume and/or shape and/or boundary conditions for the
simulation box. Orthogonal simulation boxes have 3 adjustable size
parameters (x,y,z). Triclinic (non-orthogonal) simulation boxes have
6 adjustable size/shape parameters (x,y,z,xy,xz,yz). Any or all of
them can be adjusted independently by this command. Thus it can be
used to expand or contract a box, or to apply a shear strain to a
non-orthogonal box. It can also be used to change the boundary
conditions for the simulation box, similar to the
:doc:`boundary <boundary>` command.
The size and shape of the initial simulation box are specified by the
:doc:`create_box <create_box>` or :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command used to setup the simulation.
The size and shape may be altered by subsequent runs, e.g. by use of
the :doc:`fix npt <fix_nh>` or :doc:`fix deform <fix_deform>` commands.
The :doc:`create_box <create_box>`, :doc:`read data <read_data>`, and
:doc:`read_restart <read_restart>` commands also determine whether the
simulation box is orthogonal or triclinic and their doc pages explain
the meaning of the xy,xz,yz tilt factors.
See :ref:`Section_howto 12 <howto_12>` of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.
The keywords used in this command are applied sequentially to the
simulation box and the atoms in it, in the order specified.
Before the sequence of keywords are invoked, the current box
size/shape is stored, in case a *remap* keyword is used to map the
atom coordinates from a previously stored box size/shape to the
current one.
After all the keywords have been processed, any shrink-wrap boundary
conditions are invoked (see the :doc:`boundary <boundary>` command)
which may change simulation box boundaries, and atoms are migrated to
new owning processors.
IMPORTANT_NOTE: This means that you cannot use the change_box command
to enlarge a shrink-wrapped box, e.g. to make room to insert more
atoms via the :doc:`create_atoms <create_atoms>` command, because the
simulation box will be re-shrink-wrapped before the change_box command
completes. Instead you could do something like this, assuming the
simulation box is non-periodic and atoms extend from 0 to 20 in all
dimensions:
.. parsed-literal::
change_box all x final -10 20
create_atoms 1 single -5 5 5 # this will fail to insert an atom
.. parsed-literal::
change_box all x final -10 20 boundary f s s
create_atoms 1 single -5 5 5
change_box boundary s s s # this will work
.. warning::
Unlike the earlier "displace_box" version of this
command, atom remapping is NOT performed by default. This command
allows remapping to be done in a more general way, exactly when you
specify it (zero or more times) in the sequence of transformations.
Thus if you do not use the *remap* keyword, atom coordinates will not
be changed even if the box size/shape changes. If a uniformly
strained state is desired, the *remap* keyword should be specified.
.. warning::
It is possible to lose atoms with this command.
E.g. by changing the box without remapping the atoms, and having atoms
end up outside of non-periodic boundaries. It is also possible to
alter bonds between atoms straddling a boundary in bad ways. E.g. by
converting a boundary from periodic to non-periodic. It is also
possible when remapping atoms to put them (nearly) on top of each
other. E.g. by converting a boundary from non-periodic to periodic.
All of these will typically lead to bad dynamics and/or generate error
messages.
.. warning::
The simulation box size/shape can be changed by
arbitrarily large amounts by this command. This is not a problem,
except that the mapping of processors to the simulation box is not
changed from its initial 3d configuration; see the
:doc:`processors <processors>` command. Thus, if the box size/shape
changes dramatically, the mapping of processors to the simulation box
may not end up as optimal as the initial mapping attempted to be.
.. warning::
Because the keywords used in this command are applied
one at a time to the simulation box and the atoms in it, care must be
taken with triclinic cells to avoid exceeding the limits on skew after
each transformation in the sequence. If skew is exceeded before the
final transformation this can be avoided by changing the order of the
sequence, or breaking the transformation into two or more smaller
transformations. For more information on the allowed limits for box
skew see the discussion on triclinic boxes on :ref:`this page <howto_12>`.
----------
For the *x*, *y*, and *z* parameters, this is the meaning of their
styles and values.
For style *final*, the final lo and hi box boundaries of a dimension
are specified. The values can be in lattice or box distance units.
See the discussion of the units keyword below.
For style *delta*, plus or minus changes in the lo/hi box boundaries
of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.
For style *scale*, a multiplicative factor to apply to the box length
of a dimension is specified. For example, if the initial box length
is 10, and the factor is 1.1, then the final box length will be 11. A
factor less than 1.0 means compression.
The *volume* style changes the specified dimension in such a way that
the overall box volume remains constant with respect to the operation
performed by the preceding keyword. The *volume* style can only be
used following a keyword that changed the volume, which is any of the
*x*, *y*, *z* keywords. If the preceding keyword "key" had a *volume*
style, then both it and the current keyword apply to the keyword
preceding "key". I.e. this sequence of keywords is allowed:
.. parsed-literal::
change_box all x scale 1.1 y volume z volume
The *volume* style changes the associated dimension so that the
overall box volume is unchanged relative to its value before the
preceding keyword was invoked.
If the following command is used, then the z box length will shrink by
the same 1.1 factor the x box length was increased by:
.. parsed-literal::
change_box all x scale 1.1 z volume
If the following command is used, then the y,z box lengths will each
shrink by sqrt(1.1) to keep the volume constant. In this case, the
y,z box lengths shrink so as to keep their relative aspect ratio
constant:
.. parsed-literal::
change_box all"x scale 1.1 y volume z volume
If the following command is used, then the final box will be a factor
of 10% larger in x and y, and a factor of 21% smaller in z, so as to
keep the volume constant:
.. parsed-literal::
change_box all x scale 1.1 z volume y scale 1.1 z volume
.. warning::
For solids or liquids, when one dimension of the box
is expanded, it may be physically undesirable to hold the other 2 box
lengths constant since that implies a density change. For solids,
adjusting the other dimensions via the *volume* style may make
physical sense (just as for a liquid), but may not be correct for
materials and potentials whose Poisson ratio is not 0.5.
For the *scale* and *volume* styles, the box length is expanded or
compressed around its mid point.
----------
For the *xy*, *xz*, and *yz* parameters, this is the meaning of their
styles and values. Note that changing the tilt factors of a triclinic
box does not change its volume.
For style *final*, the final tilt factor is specified. The value
can be in lattice or box distance units. See the discussion of the
units keyword below.
For style *delta*, a plus or minus change in the tilt factor is
specified. The value can be in lattice or box distance units. See
the discussion of the units keyword below.
All of these styles change the xy, xz, yz tilt factors. In LAMMPS,
tilt factors (xy,xz,yz) for triclinic boxes are required to be no more
than half the distance of the parallel box length. For example, if
xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt
factor must be between -5 and 5. Similarly, both xz and yz must be
between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a
limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are all equivalent. Any tilt factor specified by this command
must be within these limits.
----------
The *boundary* keyword takes arguments that have exactly the same
meaning as they do for the :doc:`boundary <boundary>` command. In each
dimension, a single letter assigns the same style to both the lower
and upper face of the box. Two letters assigns the first style to the
lower face and the second style to the upper face.
The style *p* means the box is periodic; the other styles mean
non-periodic. For style *f*, the position of the face is fixed. For
style *s*, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move. For style *m*, shrink-wrapping occurs, but is bounded by the
current box edge in that dimension, so that the box will become no
smaller. See the :doc:`boundary <boundary>` command for more
explanation of these style options.
Note that the "boundary" command itself can only be used before the
simulation box is defined via a :doc:`read_data <read_data>` or
:doc:`create_box <create_box>` or :doc:`read_restart <read_restart>`
command. This command allows the boundary conditions to be changed
later in your input script. Also note that the
:doc:`read_restart <read_restart>` will change boundary conditions to
match what is stored in the restart file. So if you wish to change
them, you should use the change_box command after the read_restart
command.
----------
The *ortho* and *triclinic* keywords convert the simulation box to be
orthogonal or triclinic (non-orthongonal). See :ref:`this section <howto_13>` for a discussion of how non-orthongal
boxes are represented in LAMMPS.
The simulation box is defined as either orthogonal or triclinic when
it is created via the :doc:`create_box <create_box>`,
:doc:`read_data <read_data>`, or :doc:`read_restart <read_restart>`
commands.
These keywords allow you to toggle the existing simulation box from
orthogonal to triclinic and vice versa. For example, an initial
equilibration simulation can be run in an orthogonal box, the box can
be toggled to triclinic, and then a :ref:`non-equilibrium MD (NEMD) simulation <howto_13>` can be run with deformation
via the :doc:`fix deform <fix_deform>` command.
If the simulation box is currently triclinic and has non-zero tilt in
xy, yz, or xz, then it cannot be converted to an orthogonal box.
----------
The *set* keyword saves the current box size/shape. This can be
useful if you wish to use the *remap* keyword more than once or if you
wish it to be applied to an intermediate box size/shape in a sequence
of keyword operations. Note that the box size/shape is saved before
any of the keywords are processed, i.e. the box size/shape at the time
the create_box command is encountered in the input script.
The *remap* keyword remaps atom coordinates from the last saved box
size/shape to the current box state. For example, if you stretch the
box in the x dimension or tilt it in the xy plane via the *x* and *xy*
keywords, then the *remap* commmand will dilate or tilt the atoms to
conform to the new box size/shape, as if the atoms moved with the box
as it deformed.
Note that this operation is performed without regard to periodic
boundaries. Also, any shrink-wrapping of non-periodic boundaries (see
the :doc:`boundary <boundary>` command) occurs after all keywords,
including this one, have been processed.
Only atoms in the specified group are remapped.
----------
The *units* keyword determines the meaning of the distance units used
to define various arguments. A *box* value selects standard distance
units as defined by the :doc:`units <units>` command, e.g. Angstroms for
units = real or metal. A *lattice* value means the distance units are
in lattice spacings. The :doc:`lattice <lattice>` command must have
been previously used to define the lattice spacing.
----------
Restrictions
""""""""""""
If you use the *ortho* or *triclinic* keywords, then at the point in
the input script when this command is issued, no :doc:`dumps <dump>` can
be active, nor can a :doc:`fix ave/spatial <fix_ave_spatial>` or :doc:`fix deform <fix_deform>` be active. This is because these commands
test whether the simulation box is orthogonal when they are first
issued. Note that these commands can be used in your script before a
change_box command is issued, so long as an :doc:`undump <undump>` or
:doc:`unfix <unfix>` command is also used to turn them off.
Related commands
""""""""""""""""
:doc:`fix deform <fix_deform>`, :doc:`boundary <boundary>`
Default
"""""""
The option default is units = lattice.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

47
doc/_sources/clear.txt
View File

@ -1,47 +0,0 @@
.. index:: clear
clear command
=============
Syntax
""""""
.. parsed-literal::
clear
Examples
""""""""
.. parsed-literal::
(commands for 1st simulation)
clear
(commands for 2nd simulation)
Description
"""""""""""
This command deletes all atoms, restores all settings to their default
values, and frees all memory allocated by LAMMPS. Once a clear
command has been executed, it is almost as if LAMMPS were starting
over, with only the exceptions noted below. This command enables
multiple jobs to be run sequentially from one input script.
These settings are not affected by a clear command: the working
directory (:doc:`shell <shell>` command), log file status
(:doc:`log <log>` command), echo status (:doc:`echo <echo>` command), and
input script variables (:doc:`variable <variable>` command).
Restrictions
""""""""""""
none
**Related commands:** none
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

161
doc/_sources/comm_modify.txt
View File

@ -1,161 +0,0 @@
.. index:: comm_modify
comm_modify command
===================
Syntax
""""""
.. parsed-literal::
comm_modify keyword value ...
* zero or more keyword/value pairs may be appended
* keyword = *mode* or *cutoff* or *group* or *vel*
.. parsed-literal::
*mode* value = *single* or *multi* = communicate atoms within a single or multiple distances
*cutoff* value = Rcut (distance units) = communicate atoms from this far away
*group* value = group-ID = only communicate atoms in the group
*vel* value = *yes* or *no* = do or do not communicate velocity info with ghost atoms
Examples
""""""""
.. parsed-literal::
comm_modify mode multi
comm_modify mode multi group solvent
comm_modify vel yes
comm_modify cutoff 5.0 vel yes
Description
"""""""""""
This command sets parameters that affect the inter-processor
communication of atom information that occurs each timestep as
coordinates and other properties are exchanged between neighboring
processors and stored as properties of ghost atoms.
.. warning::
These options apply to the currently defined comm
style. When you specify a :doc:`comm_style <comm_style>` command, all
communication settings are restored to their default values, including
those previously reset by a comm_modify command. Thus if your input
script specifies a comm_style command, you should use the comm_modify
command after it.
The *mode* keyword determines whether a single or multiple cutoff
distances are used to determine which atoms to communicate.
The default mode is *single* which means each processor acquires
information for ghost atoms that are within a single distance from its
sub-domain. The distance is the maximum of the neighbor cutoff for
all atom type pairs.
For many systems this is an efficient algorithm, but for systems with
widely varying cutoffs for different type pairs, the *multi* mode can
be faster. In this case, each atom type is assigned its own distance
cutoff for communication purposes, and fewer atoms will be
communicated. See the :doc:`neighbor multi <neighbor>` command for a
neighbor list construction option that may also be beneficial for
simulations of this kind.
The *cutoff* keyword allows you to set a ghost cutoff distance, which
is the distance from the borders of a processor's sub-domain at which
ghost atoms are acquired from other processors. By default the ghost
cutoff = neighbor cutoff = pairwise force cutoff + neighbor skin. See
the :doc:`neighbor <neighbor>` command for more information about the
skin distance. If the specified Rcut is greater than the neighbor
cutoff, then extra ghost atoms will be acquired. If it is smaller,
the ghost cutoff is set to the neighbor cutoff.
These are simulation scenarios in which it may be useful or even
necessary to set a ghost cutoff > neighbor cutoff:
* a single polymer chain with bond interactions, but no pairwise interactions
* bonded interactions (e.g. dihedrals) extend further than the pairwise cutoff
* ghost atoms beyond the pairwise cutoff are needed for some computation
In the first scenario, a pairwise potential is not defined. Thus the
pairwise neighbor cutoff will be 0.0. But ghost atoms are still
needed for computing bond, angle, etc interactions between atoms on
different processors, or when the interaction straddles a periodic
boundary.
The appropriate ghost cutoff depends on the :doc:`newton bond <newton>`
setting. For newton bond *off*, the distance needs to be the furthest
distance between any two atoms in the bond, angle, etc. E.g. the
distance between 1-4 atoms in a dihedral. For newton bond *on*, the
distance between the central atom in the bond, angle, etc and any
other atom is sufficient. E.g. the distance between 2-4 atoms in a
dihedral.
In the second scenario, a pairwise potential is defined, but its
neighbor cutoff is not sufficiently long enough to enable bond, angle,
etc terms to be computed. As in the previous scenario, an appropriate
ghost cutoff should be set.
In the last scenario, a :doc:`fix <fix>` or :doc:`compute <compute>` or
:doc:`pairwise potential <pair_style>` needs to calculate with ghost
atoms beyond the normal pairwise cutoff for some computation it
performs (e.g. locate neighbors of ghost atoms in a multibody pair
potential). Setting the ghost cutoff appropriately can insure it will
find the needed atoms.
.. warning::
In these scenarios, if you do not set the ghost cutoff
long enough, and if there is only one processor in a periodic
dimension (e.g. you are running in serial), then LAMMPS may "find" the
atom it is looking for (e.g. the partner atom in a bond), that is on
the far side of the simulation box, across a periodic boundary. This
will typically lead to bad dynamics (i.e. the bond length is now the
simulation box length). To detect if this is happening, see the
:doc:`neigh_modify cluster <neigh_modify>` command.
The *group* keyword will limit communication to atoms in the specified
group. This can be useful for models where no ghost atoms are needed
for some kinds of particles. All atoms (not just those in the
specified group) will still migrate to new processors as they move.
The group specified with this option must also be specified via the
:doc:`atom_modify first <atom_modify>` command.
The *vel* keyword enables velocity information to be communicated with
ghost particles. Depending on the :doc:`atom_style <atom_style>`,
velocity info includes the translational velocity, angular velocity,
and angular momentum of a particle. If the *vel* option is set to
*yes*, then ghost atoms store these quantities; if *no* then they do
not. The *yes* setting is needed by some pair styles which require
the velocity state of both the I and J particles to compute a pairwise
I,J interaction.
Note that if the :doc:`fix deform <fix_deform>` command is being used
with its "remap v" option enabled, then the velocities for ghost atoms
(in the fix deform group) mirrored across a periodic boundary will
also include components due to any velocity shift that occurs across
that boundary (e.g. due to dilation or shear).
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`comm_style <comm_style>`, :doc:`neighbor <neighbor>`
Default
"""""""
The option defauls are mode = single, group = all, cutoff = 0.0, vel =
no. The cutoff default of 0.0 means that ghost cutoff = neighbor
cutoff = pairwise force cutoff + neighbor skin.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

73
doc/_sources/comm_style.txt
View File

@ -1,73 +0,0 @@
.. index:: comm_style
comm_style command
==================
Syntax
""""""
.. parsed-literal::
comm_style style
* style = *brick* or *tiled*
Examples
""""""""
.. parsed-literal::
comm_style brick
comm_style tiled
Description
"""""""""""
This command sets the style of inter-processor communication of atom
information that occurs each timestep as coordinates and other
properties are exchanged between neighboring processors and stored as
properties of ghost atoms.
For the default *brick* style, the domain decomposition used by LAMMPS
to partition the simulation box must be a regular 3d grid of bricks,
one per processor. Each processor communicates with its 6 Cartesian
neighbors in the grid to acquire information for nearby atoms.
For the *tiled* style, a more general domain decomposition can be
used, as triggered by the :doc:`balance <balance>` or :doc:`fix balance <fix_balance>` commands. The simulation box can be
partitioned into non-overlapping rectangular-shaped "tiles" or varying
sizes and shapes. Again there is one tile per processor. To acquire
information for nearby atoms, communication must now be done with a
more complex pattern of neighboring processors.
Note that this command does not actually define a partitoining of the
simulation box (a domain decomposition), rather it determines what
kinds of decompositions are allowed and the pattern of communication
used to enable the decomposition. A decomposition is created when the
simulation box is first created, via the :doc:`create_box <create_box>`
or :doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands. For both the *brick* and *tiled* styles, the initial
decomposition will be the same, as described by
:doc:`create_box <create_box>` and :doc:`processors <processors>`
commands. The decomposition can be changed via the
:doc:`balance <balance>` or :doc:`fix_balance <fix_balance>` commands.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`comm_modify <comm_modify>`, :doc:`processors <processors>`,
:doc:`balance <balance>`, :doc:`fix balance <fix_balance>`
Default
"""""""
The default style is brick.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

269
doc/_sources/compute.txt
View File

@ -1,269 +0,0 @@
.. index:: compute
compute command
===============
Syntax
""""""
.. parsed-literal::
compute ID group-ID style args
* ID = user-assigned name for the computation
* group-ID = ID of the group of atoms to perform the computation on
* style = one of a list of possible style names (see below)
* args = arguments used by a particular style
Examples
""""""""
.. parsed-literal::
compute 1 all temp
compute newtemp flow temp/partial 1 1 0
compute 3 all ke/atom
Description
"""""""""""
Define a computation that will be performed on a group of atoms.
Quantities calculated by a compute are instantaneous values, meaning
they are calculated from information about atoms on the current
timestep or iteration, though a compute may internally store some
information about a previous state of the system. Defining a compute
does not perform a computation. Instead computes are invoked by other
LAMMPS commands as needed, e.g. to calculate a temperature needed for
a thermostat fix or to generate thermodynamic or dump file output.
See this :ref:`howto section <howto_15>` for a summary of
various LAMMPS output options, many of which involve computes.
The ID of a compute can only contain alphanumeric characters and
underscores.
----------
Computes calculate one of three styles of quantities: global,
per-atom, or local. A global quantity is one or more system-wide
values, e.g. the temperature of the system. A per-atom quantity is
one or more values per atom, e.g. the kinetic energy of each atom.
Per-atom values are set to 0.0 for atoms not in the specified compute
group. Local quantities are calculated by each processor based on the
atoms it owns, but there may be zero or more per atom, e.g. a list of
bond distances. Computes that produce per-atom quantities have the
word "atom" in their style, e.g. *ke/atom*. Computes that produce
local quantities have the word "local" in their style,
e.g. *bond/local*. Styles with neither "atom" or "local" in their
style produce global quantities.
Note that a single compute produces either global or per-atom or local
quantities, but never more than one of these.
Global, per-atom, and local quantities each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
doc page for each compute describes the style and kind of values it
produces, e.g. a per-atom vector. Some computes produce more than one
kind of a single style, e.g. a global scalar and a global vector.
When a compute quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
notation, where ID is the ID of the compute:
+------------+--------------------------------------------+
| c_ID | entire scalar, vector, or array |
+------------+--------------------------------------------+
| c_ID[I] | one element of vector, one column of array |
+------------+--------------------------------------------+
| c_ID[I][J] | one element of array |
+------------+--------------------------------------------+
In other words, using one bracket reduces the dimension of the
quantity once (vector -> scalar, array -> vector). Using two brackets
reduces the dimension twice (array -> scalar). Thus a command that
uses scalar compute values as input can also process elements of a
vector or array.
Note that commands and :doc:`variables <variable>` which use compute
quantities typically do not allow for all kinds, e.g. a command may
require a vector of values, not a scalar. This means there is no
ambiguity about referring to a compute quantity as c_ID even if it
produces, for example, both a scalar and vector. The doc pages for
various commands explain the details.
----------
In LAMMPS, the values generated by a compute can be used in several
ways:
* The results of computes that calculate a global temperature or
pressure can be used by fixes that do thermostatting or barostatting
or when atom velocities are created.
* Global values can be output via the :doc:`thermo_style custom <thermo_style>` or :doc:`fix ave/time <fix_ave_time>` command.
Or the values can be referenced in a :doc:`variable equal <variable>` or
:doc:`variable atom <variable>` command.
* Per-atom values can be output via the :doc:`dump custom <dump>` command
or the :doc:`fix ave/spatial <fix_ave_spatial>` command. Or they can be
time-averaged via the :doc:`fix ave/atom <fix_ave_atom>` command or
reduced by the :doc:`compute reduce <compute_reduce>` command. Or the
per-atom values can be referenced in an :doc:`atom-style variable <variable>`.
* Local values can be reduced by the :doc:`compute reduce <compute_reduce>` command, or histogrammed by the :doc:`fix ave/histo <fix_ave_histo>` command, or output by the :doc:`dump local <dump>` command.
The results of computes that calculate global quantities can be either
"intensive" or "extensive" values. Intensive means the value is
independent of the number of atoms in the simulation,
e.g. temperature. Extensive means the value scales with the number of
atoms in the simulation, e.g. total rotational kinetic energy.
:doc:`Thermodynamic output <thermo_style>` will normalize extensive
values by the number of atoms in the system, depending on the
"thermo_modify norm" setting. It will not normalize intensive values.
If a compute value is accessed in another way, e.g. by a
:doc:`variable <variable>`, you may want to know whether it is an
intensive or extensive value. See the doc page for individual
computes for further info.
----------
LAMMPS creates its own computes internally for thermodynamic output.
Three computes are always created, named "thermo_temp",
"thermo_press", and "thermo_pe", as if these commands had been invoked
in the input script:
.. parsed-literal::
compute thermo_temp all temp
compute thermo_press all pressure thermo_temp
compute thermo_pe all pe
Additional computes for other quantities are created if the thermo
style requires it. See the documentation for the
:doc:`thermo_style <thermo_style>` command.
Fixes that calculate temperature or pressure, i.e. for thermostatting
or barostatting, may also create computes. These are discussed in the
documentation for specific :doc:`fix <fix>` commands.
In all these cases, the default computes LAMMPS creates can be
replaced by computes defined by the user in the input script, as
described by the :doc:`thermo_modify <thermo_modify>` and :doc:`fix modify <fix_modify>` commands.
Properties of either a default or user-defined compute can be modified
via the :doc:`compute_modify <compute_modify>` command.
Computes can be deleted with the :doc:`uncompute <uncompute>` command.
Code for new computes can be added to LAMMPS (see :doc:`this section <Section_modify>` of the manual) and the results of their
calculations accessed in the various ways described above.
----------
Each compute style has its own doc page which describes its arguments
and what it does. Here is an alphabetic list of compute styles
available in LAMMPS. They are also given in more compact form in the
compute section of :ref:`this page <cmd_5>`.
There are also additional compute styles (not listed here) submitted
by users which are included in the LAMMPS distribution. The list of
these with links to the individual styles are given in the compute
section of :ref:`this page <cmd_5>`.
There are also additional accelerated compute styles (note listed
here) included in the LAMMPS distribution for faster performance on
CPUs and GPUs. The list of these with links to the individual styles
are given in the compute section of :ref:`this page <cmd_5>`.
* :doc:`angle/local <compute_bond_local>` - theta and energy of each angle
* :doc:`body/local <compute_body_local>` - attributes of body sub-particles
* :doc:`bond/local <compute_bond_local>` - distance and energy of each bond
* :doc:`centro/atom <compute_centro_atom>` - centro-symmetry parameter for each atom
* :doc:`cluster/atom <compute_cluster_atom>` - cluster ID for each atom
* :doc:`cna/atom <compute_cna_atom>` - common neighbor analysis (CNA) for each atom
* :doc:`com <compute_com>` - center-of-mass of group of atoms
* :doc:`com/chunk <compute_com_chunk>` - center-of-mass for each chunk
* :doc:`contact/atom <compute_contact_atom>` - contact count for each spherical particle
* :doc:`coord/atom <compute_coord_atom>` - coordination number for each atom
* :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
* :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral
* :doc:`dilatation/atom <compute_dilatation_atom>` - Peridynamic dilatation for each atom
* :doc:`displace/atom <compute_displace_atom>` - displacement of each atom
* :doc:`erotate/asphere <compute_erotate_asphere>` - rotational energy of aspherical particles
* :doc:`erotate/rigid <compute_erotate_rigid>` - rotational energy of rigid bodies
* :doc:`erotate/sphere <compute_erotate_sphere>` - rotational energy of spherical particles
* :doc:`erotate/sphere/atom <compute_erotate_sphere>` - rotational energy for each spherical particle
* :doc:`event/displace <compute_event_displace>` - detect event on atom displacement
* :doc:`group/group <compute_group_group>` - energy/force between two groups of atoms
* :doc:`gyration <compute_gyration>` - radius of gyration of group of atoms
* :doc:`gyration/chunk <compute_gyration_chunk>` - radius of gyration for each chunk
* :doc:`heat/flux <compute_heat_flux>` - heat flux through a group of atoms
* :doc:`improper/local <compute_improper_local>` - angle of each improper
* :doc:`inertia/chunk <compute_inertia_chunk>` - inertia tensor for each chunk
* :doc:`ke <compute_ke>` - translational kinetic energy
* :doc:`ke/atom <compute_ke_atom>` - kinetic energy for each atom
* :doc:`ke/rigid <compute_ke_rigid>` - translational kinetic energy of rigid bodies
* :doc:`msd <compute_msd>` - mean-squared displacement of group of atoms
* :doc:`msd/chunk <compute_msd_chunk>` - mean-squared displacement for each chunk
* :doc:`msd/nongauss <compute_msd_nongauss>` - MSD and non-Gaussian parameter of group of atoms
* :doc:`pair <compute_pair>` - values computed by a pair style
* :doc:`pair/local <compute_pair_local>` - distance/energy/force of each pairwise interaction
* :doc:`pe <compute_pe>` - potential energy
* :doc:`pe/atom <compute_pe_atom>` - potential energy for each atom
* :doc:`plasticity/atom <compute_plasticity_atom>` - Peridynamic plasticity for each atom
* :doc:`pressure <compute_pressure>` - total pressure and pressure tensor
* :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
* :doc:`property/local <compute_property_local>` - convert local attributes to localvectors/arrays
* :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes
* :doc:`rdf <compute_rdf>` - radial distribution function g(r) histogram of group of atoms
* :doc:`reduce <compute_reduce>` - combine per-atom quantities into a single global value
* :doc:`reduce/region <compute_reduce>` - same as compute reduce, within a region
* :doc:`slice <compute_slice>` - extract values from global vector or array
* :doc:`sna/atom <compute_sna>` - calculate bispectrum coefficients for each atom
* :doc:`snad/atom <compute_sna>` - derivative of bispectrum coefficients for each atom
* :doc:`snav/atom <compute_sna>` - virial contribution from bispectrum coefficients for each atom
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`temp <compute_temp>` - temperature of group of atoms
* :doc:`temp/asphere <compute_temp_asphere>` - temperature of aspherical particles
* :doc:`temp/chunk <compute_temp_chunk>` - temperature of each chunk
* :doc:`temp/com <compute_temp_com>` - temperature after subtracting center-of-mass velocity
* :doc:`temp/deform <compute_temp_deform>` - temperature excluding box deformation velocity
* :doc:`temp/partial <compute_temp_partial>` - temperature excluding one or more dimensions of velocity
* :doc:`temp/profile <compute_temp_profile>` - temperature excluding a binned velocity profile
* :doc:`temp/ramp <compute_temp_ramp>` - temperature excluding ramped velocity component
* :doc:`temp/region <compute_temp_region>` - temperature of a region of atoms
* :doc:`temp/sphere <compute_temp_sphere>` - temperature of spherical particles
* :doc:`ti <compute_ti>` - thermodyanmic integration free energy values
* :doc:`torque/chunk <compute_torque_chunk>` - torque applied on each chunk
* :doc:`vacf <compute_vacf>` - velocity-autocorrelation function of group of atoms
* :doc:`vcm/chunk <compute_vcm_chunk>` - velocity of center-of-mass for each chunk
* :doc:`voronoi/atom <compute_voronoi_atom>` - Voronoi volume and neighbors for each atom
There are also additional compute styles submitted by users which are
included in the LAMMPS distribution. The list of these with links to
the individual styles are given in the compute section of :ref:`this page <cmd_5>`.
There are also additional accelerated compute styles included in the
LAMMPS distribution for faster performance on CPUs and GPUs. The list
of these with links to the individual styles are given in the pair
section of :ref:`this page <cmd_5>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`uncompute <uncompute>`, :doc:`compute_modify <compute_modify>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/spatial <fix_ave_spatial>`,
:doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/histo <fix_ave_histo>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

87
doc/_sources/compute_ackland_atom.txt
View File

@ -1,87 +0,0 @@
.. index:: compute ackland/atom
compute ackland/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID ackland/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* ackland/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all ackland/atom
Description
"""""""""""
Defines a computation that calculates the local lattice structure
according to the formulation given in :ref:`(Ackland) <Ackland>`.
In contrast to the :doc:`centro-symmetry parameter <compute_centro_atom>` this method is stable against
temperature boost, because it is based not on the distance between
particles but the angles. Therefore statistical fluctuations are
averaged out a little more. A comparison with the Common Neighbor
Analysis metric is made in the paper.
The result is a number which is mapped to the following different
lattice structures:
* 0 = UNKNOWN
* 1 = BCC
* 2 = FCC
* 3 = HCP
* 4 = ICO
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.-
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
Restrictions
""""""""""""
This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
The per-atom vector values will be unitless since they are the
integers defined above.
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`
**Default:** none
----------
.. _Ackland:
**(Ackland)** Ackland, Jones, Phys Rev B, 73, 054104 (2006).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

86
doc/_sources/compute_angle_local.txt
View File

@ -1,86 +0,0 @@
.. index:: compute angle/local
compute angle/local command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID angle/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* angle/local = style name of this compute command
* one or more keywords may be appended
* keyword = *theta* or *eng*
.. parsed-literal::
*theta* = tabulate angles
*eng* = tabulate angle energies
Examples
""""""""
.. parsed-literal::
compute 1 all angle/local theta
compute 1 all angle/local eng theta
Description
"""""""""""
Define a computation that calculates properties of individual angle
interactions. The number of datums generated, aggregated across all
processors, equals the number of angles in the system, modified by the
group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their angles. An angle will only
be included if all 3 atoms in the angle are in the specified compute
group. Any angles that have been broken (see the
:doc:`angle_style <angle_style>` command) by setting their angle type to
0 are not included. Angles that have been turned off (see the :doc:`fix shake <fix_shake>` or :doc:`delete_bonds <delete_bonds>` commands) by
setting their angle type negative are written into the file, but their
energy will be 0.0.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, angle output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of angles. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *theta* will be in degrees. The output for *eng* will
be in energy :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

97
doc/_sources/compute_angmom_chunk.txt
View File

@ -1,97 +0,0 @@
.. index:: compute angmom/chunk
compute angmom/chunk command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID angmom/chunk chunkID
* ID, group-ID are documented in :doc:`compute <compute>` command
* angmom/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
Examples
""""""""
.. parsed-literal::
compute 1 fluid angmom/chunk molchunk
Description
"""""""""""
Define a computation that calculates the angular momemtum of multiple
chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the 3 components of the angular momentum
vector for each chunk, due to the velocity/momentum of the individual
atoms in the chunk around the center-of-mass of the chunk. The
calculation includes all effects due to atoms passing thru periodic
boundaries.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
.. warning::
The coordinates of an atom contribute to the chunk's
angular momentum in "unwrapped" form, by using the image flags
associated with each atom. See the :doc:`dump custom <dump>` command
for a discussion of "unwrapped" coordinates. See the Atoms section of
the :doc:`read_data <read_data>` command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
The simplest way to output the results of the compute angmom/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all angmom/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
**Output info:**
This compute calculates a global array where the number of rows = the
number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The number of columns =
3 for the 3 xyz components of the angular momentum for each chunk.
These values can be accessed by any command that uses global array
values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The array values are "intensive". The array values will be in
mass-velocity-distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`variable angmom() function <variable>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

88
doc/_sources/compute_basal_atom.txt
View File

@ -1,88 +0,0 @@
.. index:: compute basal/atom
compute basal/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID basal/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* basal/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all basal/atom
Description
"""""""""""
Defines a computation that calculates the hexagonal close-packed "c"
lattice vector for each atom in the group. It does this by
calculating the normal unit vector to the basal plane for each atom.
The results enable efficient identification and characterization of
twins and grains in hexagonal close-packed structures.
The output of the compute is thus the 3 components of a unit vector
associdate with each atom. The components are set to 0.0 for
atoms not in the group.
Details of the calculation are given in :ref:`(Barrett) <Barrett>`.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.
An example input script that uses this compute is provided
in examples/USER/misc/basal.
**Output info:**
This compute calculates a per-atom array with 3 columns, which can be
accessed by indices 1-3 by any command that uses per-atom values from
a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom vector values are unitless since the 3 columns represent
components of a unit vector.
Restrictions
""""""""""""
This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
The output of this compute will be meaningless unless the atoms are on
(or near) hcp lattice sites, since the calculation assumes a
well-defined basal plane.
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`, :doc:`compute ackland/atom <compute_ackland_atom>`
**Default:** none
----------
.. _Barrett:
**(Barrett)** Barrett, Tschopp, El Kadiri, Scripta Mat. 66, p.666 (2012).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

102
doc/_sources/compute_body_local.txt
View File

@ -1,102 +0,0 @@
.. index:: compute body/local
compute body/local command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID body/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* body/local = style name of this compute command
* one or more keywords may be appended
* keyword = *type* or *integer*
.. parsed-literal::
*type* = atom type of the body particle
*integer* = 1,2,3,etc = index of fields defined by body style
Examples
""""""""
.. parsed-literal::
compute 1 all body/local type 1 2 3
compute 1 all body/local 3 6
Description
"""""""""""
Define a computation that calculates properties of individual body
sub-particles. The number of datums generated, aggregated across all
processors, equals the number of body sub-particles plus the number of
non-body particles in the system, modified by the group parameter as
explained below. See :ref:`Section_howto 14 <howto_14>`
of the manual and the :doc:`body <body>` doc page for more details on
using body particles.
The local data stored by this command is generated by looping over all
the atoms. An atom will only be included if it is in the group. If
the atom is a body particle, then its N sub-particles will be looped
over, and it will contribute N datums to the count of datums. If it
is not a body particle, it will contribute 1 datum.
For both body particles and non-body particles, the *type* keyword
will store the type of the atom.
The *integer* keywords mean different things for body and non-body
particles. If the atom is not a body particle, only its *x*, *y*, *z*
coordinates can be referenced, using the *integer* keywords 1,2,3.
Note that this means that if you want to access more fields than this
for body particles, then you cannot include non-body particles in the
group.
For a body particle, the *integer* keywords refer to fields calculated
by the body style for each sub-particle. The body style, as specified
by the :doc:`atom_style body <atom_style>`, determines how many fields
exist and what they are. See the :doc:`body <body>` doc page for
details of the different styles.
Here is an example of how to output body information using the :doc:`dump local <dump>` command with this compute. If fields 1,2,3 for the
body sub-particles are x,y,z coordinates, then the dump file will be
formatted similar to the output of a :doc:`dump atom or custom <dump>`
command.
.. parsed-literal::
compute 1 all body/local type 1 2 3
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_1[4]
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of datums as described above. If a single keyword
is specified, a local vector is produced. If two or more keywords are
specified, a local array is produced where the number of columns = the
number of keywords. The vector or array can be accessed by any
command that uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The :doc:`units <units>` for output values depend on the body style.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

96
doc/_sources/compute_bond_local.txt
View File

@ -1,96 +0,0 @@
.. index:: compute bond/local
compute bond/local command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID bond/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* bond/local = style name of this compute command
* one or more keywords may be appended
* keyword = *dist* or *eng*
.. parsed-literal::
*dist* = bond distance
*eng* = bond energy
*force* = bond force
Examples
""""""""
.. parsed-literal::
compute 1 all bond/local eng
compute 1 all bond/local dist eng force
Description
"""""""""""
Define a computation that calculates properties of individual bond
interactions. The number of datums generated, aggregated across all
processors, equals the number of bonds in the system, modified
by the group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their bonds. A bond will only be
included if both atoms in the bond are in the specified compute group.
Any bonds that have been broken (see the :doc:`bond_style <bond_style>`
command) by setting their bond type to 0 are not included. Bonds that
have been turned off (see the :doc:`fix shake <fix_shake>` or
:doc:`delete_bonds <delete_bonds>` commands) by setting their bond type
negative are written into the file, but their energy will be 0.0.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, bond output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
Here is an example of how to do this:
.. parsed-literal::
compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of bonds. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *dist* will be in distance :doc:`units <units>`. The
output for *eng* will be in energy :doc:`units <units>`. The output for
*force* will be in force :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

142
doc/_sources/compute_centro_atom.txt
View File

@ -1,142 +0,0 @@
.. index:: compute centro/atom
compute centro/atom command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID centro/atom lattice
* ID, group-ID are documented in :doc:`compute <compute>` command
* centro/atom = style name of this compute command
* lattice = *fcc* or *bcc* or N = # of neighbors per atom to include
Examples
""""""""
.. parsed-literal::
compute 1 all centro/atom fcc
.. parsed-literal::
compute 1 all centro/atom 8
Description
"""""""""""
Define a computation that calculates the centro-symmetry parameter for
each atom in the group. In solid-state systems the centro-symmetry
parameter is a useful measure of the local lattice disorder around an
atom and can be used to characterize whether the atom is part of a
perfect lattice, a local defect (e.g. a dislocation or stacking
fault), or at a surface.
The value of the centro-symmetry parameter will be 0.0 for atoms not
in the specified compute group.
This parameter is computed using the following formula from
:ref:`(Kelchner) <Kelchner>`
.. image:: Eqs/centro_symmetry.jpg
:align: center
where the *N* nearest neighbors or each atom are identified and Ri and
Ri+N/2 are vectors from the central atom to a particular pair of
nearest neighbors. There are N*(N-1)/2 possible neighbor pairs that
can contribute to this formula. The quantity in the sum is computed
for each, and the N/2 smallest are used. This will typically be for
pairs of atoms in symmetrically opposite positions with respect to the
central atom; hence the i+N/2 notation.
*N* is an input parameter, which should be set to correspond to the
number of nearest neighbors in the underlying lattice of atoms. If
the keyword *fcc* or *bcc* is used, *N* is set to 12 and 8
respectively. More generally, *N* can be set to a positive, even
integer.
For an atom on a lattice site, surrounded by atoms on a perfect
lattice, the centro-symmetry parameter will be 0. It will be near 0
for small thermal perturbations of a perfect lattice. If a point
defect exists, the symmetry is broken, and the parameter will be a
larger positive value. An atom at a surface will have a large
positive parameter. If the atom does not have *N* neighbors (within
the potential cutoff), then its centro-symmetry parameter is set to
0.0.
Only atoms within the cutoff of the pairwise neighbor list are
considered as possible neighbors. Atoms not in the compute group are
included in the *N* neighbors used in this calculation.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (e.g. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each with a
*centro/atom* style.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitless values >= 0.0. Their
magnitude depends on the lattice style due to the number of
contibuting neighbor pairs in the summation in the formula above. And
it depends on the local defects surrounding the central atom, as
described above.
Here are typical centro-symmetry values, from a a nanoindentation
simulation into gold (FCC). These were provided by Jon Zimmerman
(Sandia):
.. parsed-literal::
Bulk lattice = 0
Dislocation core ~ 1.0 (0.5 to 1.25)
Stacking faults ~ 5.0 (4.0 to 6.0)
Free surface ~ 23.0
These values are *not* normalized by the square of the lattice
parameter. If they were, normalized values would be:
.. parsed-literal::
Bulk lattice = 0
Dislocation core ~ 0.06 (0.03 to 0.075)
Stacking faults ~ 0.3 (0.24 to 0.36)
Free surface ~ 1.38
For BCC materials, the values for dislocation cores and free surfaces
would be somewhat different, due to their being only 8 neighbors instead
of 12.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute cna/atom <compute_cna_atom>`
**Default:** none
----------
.. _Kelchner:
**(Kelchner)** Kelchner, Plimpton, Hamilton, Phys Rev B, 58, 11085 (1998).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

586
doc/_sources/compute_chunk_atom.txt
View File

@ -1,586 +0,0 @@
.. index:: compute chunk/atom
compute chunk/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID chunk/atom style args keyword values ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* chunk/atom = style name of this compute command
.. parsed-literal::
style = *bin/1d* or *bin/2d* or *bin/3d* or *type* or *molecule* or *compute/fix/variable*
*bin/1d* args = dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*bin/2d* args = dim origin delta dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*bin/3d* args = dim origin delta dim origin delta dim origin delta
dim = *x* or *y* or *z*
origin = *lower* or *center* or *upper* or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
*type* args = none
*molecule* args = none
*compute/fix/variable* = c_ID, c_ID[I], f_ID, f_ID[I], v_name with no args
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
* zero or more keyword/values pairs may be appended
* keyword = *region* or *nchunk* or *static* or *compress* or *bound* or *discard* or *units*
.. parsed-literal::
*region* value = region-ID
region-ID = ID of region atoms must be in to be part of a chunk
*nchunk* value = *once* or *every*
once = only compute the number of chunks once
every = re-compute the number of chunks whenever invoked
*limit* values = 0 or Nc max or Nc exact
0 = no limit on the number of chunks
Nc max = limit number of chunks to be <= Nc
Nc exact = set number of chunks to exactly Nc
*ids* value = *once* or *nfreq* or *every*
once = assign chunk IDs to atoms only once, they persist thereafter
nfreq = assign chunk IDs to atoms only once every Nfreq steps (if invoked by :doc:`fix ave/chunk <fix_ave_chunk>` which sets Nfreq)
every = assign chunk IDs to atoms whenever invoked
*compress* value = *yes* or *no*
yes = compress chunk IDs to eliminate IDs with no atoms
no = do not compress chunk IDs even if some IDs have no atoms
*discard* value = *yes* or *no* or *mixed*
yes = discard atoms with out-of-range chunk IDs by assigning a chunk ID = 0
no = keep atoms with out-of-range chunk IDs by assigning a valid chunk ID
mixed = keep or discard such atoms according to spatial binning rule
*bound* values = x/y/z lo hi
x/y/z = *x* or *y* or *z* to bound sptial bins in this dimension
lo = *lower* or coordinate value (distance units)
hi = *upper* or coordinate value (distance units)
*units* value = *box* or *lattice* or *reduced*
Examples
""""""""
.. parsed-literal::
compute 1 all chunk/atom type
compute 1 all chunk/atom bin/1d z lower 0.02 units reduced
compute 1 all chunk/atom bin/2d z lower 1.0 y 0.0 2.5
compute 1 all chunk/atom molecule region sphere nchunk once ids once compress yes
Description
"""""""""""
Define a computation that calculates an integer chunk ID from 1 to
Nchunk for each atom in the group. Values of chunk IDs are determined
by the *style* of chunk, which can be based on atom type or molecule
ID or spatial binning or a per-atom property or value calculated by
another :doc:`compute <compute>`, :doc:`fix <fix>`, or :doc:`atom-style variable <variable>`. Per-atom chunk IDs can be used by other
computes with "chunk" in their style name, such as :doc:`compute com/chunk <compute_com_chunk>` or :doc:`compute msd/chunk <compute_msd_chunk>`. Or they can be used by the :doc:`fix ave/chunk <fix_ave_chunk>` command to sum and time average a
variety of per-atom properties over the atoms in each chunk. Or they
can simply be accessed by any command that uses per-atom values from a
compute as input, as discussed in :ref:`Section_howto 15 <howto_15>`.
See :ref:`Section_howto 23 <howto_23>` for an overview of
how this compute can be used with a variety of other commands to
tabulate properties of a simulation. The howto section gives several
examples of input script commands that can be used to calculate
interesting properties.
Conceptually it is important to realize that this compute does two
simple things. First, it sets the value of *Nchunk* = the number of
chunks, which can be a constant value or change over time. Second, it
assigns each atom to a chunk via a chunk ID. Chunk IDs range from 1
to *Nchunk* inclusive; some chunks may have no atoms assigned to them.
Atoms that do not belong to any chunk are assigned a value of 0. Note
that the two operations are not always performed together. For
example, spatial bins can be setup once (which sets *Nchunk*), and
atoms assigned to those bins many times thereafter (setting their
chunk IDs).
All other commands in LAMMPS that use chunk IDs assume there are
*Nchunk* number of chunks, and that every atom is assigned to one of
those chunks, or not assigned to any chunk.
There are many options for specifying for how and when *Nchunk* is
calculated, and how and when chunk IDs are assigned to atoms. The
details depend on the chunk *style* and its *args*, as well as
optional keyword settings. They can also depend on whether a :doc:`fix ave/chunk <fix_ave_chunk>` command is using this compute, since
that command requires *Nchunk* to remain static across windows of
timesteps it specifies, while it accumulates per-chunk averages.
The details are described below.
The different chunk styles operate as follows. For each style, how it
calculates *Nchunk* and assigns chunk IDs to atoms is explained. Note
that using the optional keywords can change both of those actions, as
described further below where the keywords are discussed.
----------
The *binning* styles perform a spatial binning of atoms, and assign an
atom the chunk ID corresponding to the bin number it is in. *Nchunk*
is set to the number of bins, which can change if the simulation box
size changes.
The *bin/1d*, *bin/2d*, and *bin/3d* styles define bins as 1d layers
(slabs), 2d pencils, or 3d boxes. The *dim*, *origin*, and *delta*
settings are specified 1, 2, or 3 times. For 2d or 3d bins, there is
no restriction on specifying dim = x before dim = y or z, or dim = y
before dim = z. Bins in a particular *dim* have a bin size in that
dimension given by *delta*. In each dimension, bins are defined
relative to a specified *origin*, which may be the lower/upper edge of
the simulation box (in that dimension), or its center point, or a
specified coordinate value. Starting at the origin, sufficient bins
are created in both directions to completely span the simulation box
or the bounds specified by the optional *bounds* keyword.
For orthogonal simulation boxes, the bins are layers, pencils, or
boxes aligned with the xyz coordinate axes. For triclinic
(non-orthogonal) simulation boxes, the bin faces are parallel to the
tilted faces of the simulation box. See :ref:`this section <howto_12>` of the manual for a discussion of
the geometry of triclinic boxes in LAMMPS. As described there, a
tilted simulation box has edge vectors a,b,c. In that nomenclature,
bins in the x dimension have faces with normals in the "b" cross "c"
direction. Bins in y have faces normal to the "a" cross "c"
direction. And bins in z have faces normal to the "a" cross "b"
direction. Note that in order to define the size and position of
these bins in an unambiguous fashion, the *units* option must be set
to *reduced* when using a triclinic simulation box, as noted below.
The meaning of *origin* and *delta* for triclinic boxes is as follows.
Consider a triclinic box with bins that are 1d layers or slabs in the
x dimension. No matter how the box is tilted, an *origin* of 0.0
means start layers at the lower "b" cross "c" plane of the simulation
box and an *origin* of 1.0 means to start layers at the upper "b"
cross "c" face of the box. A *delta* value of 0.1 in *reduced* units
means there will be 10 layers from 0.0 to 1.0, regardless of the
current size or shape of the simulation box.
The created bins (and hence the chunk IDs) are numbered consecutively
from 1 to the number of bins = *Nchunk*. For 2d and 3d bins, the
numbering varies most rapidly in the first dimension (which could be
x, y, or z), next rapidly in the 2nd dimension, and most slowly in the
3rd dimension.
Each time this compute is invoked, each atom is mapped to a bin based
on its current position. Note that between reneighboring timesteps,
atoms can move outside the current simulation box. If the box is
periodic (in that dimension) the atom is remapping into the periodic
box for purposes of binning. If the box in not periodic, the atom may
have moved outside the bounds of all bins. If an atom is not inside
any bin, the *discard* keyword is used to determine how a chunk ID is
assigned to the atom.
----------
The *type* style uses the atom type as the chunk ID. *Nchunk* is set
to the number of atom types defined for the simulation, e.g. via the
:doc:`create_box <create_box>` or :doc:`read_data <read_data>` commands.
----------
The *molecule* style uses the molecule ID of each atom as its chunk
ID. *Nchunk* is set to the largest chunk ID. Note that this excludes
molecule IDs for atoms which are not in the specified group or
optional region.
There is no requirement that all atoms in a particular molecule are
assigned the same chunk ID (zero or non-zero), though you probably
want that to be the case, if you wish to compute a per-molecule
property. LAMMPS will issue a warning if that is not the case, but
only the first time that *Nchunk* is calculated.
Note that atoms with a molecule ID = 0, which may be non-molecular
solvent atoms, have an out-of-range chunk ID. These atoms are
discarded (not assigned to any chunk) or assigned to *Nchunk*,
depending on the value of the *discard* keyword.
----------
The *compute/fix/variable* styles set the chunk ID of each atom based
on a quantity calculated and stored by a compute, fix, or variable.
In each case, it must be a per-atom quantity. In each case the
referenced floating point values are converted to an integer chunk ID
as follows. The floating point value is truncated (rounded down) to
an integer value. If the integer value is <= 0, then a chunk ID of 0
is assigned to the atom. If the integer value is > 0, it becomes the
chunk ID to the atom. *Nchunk* is set to the largest chunk ID. Note
that this excludes atoms which are not in the specified group or
optional region.
If the style begins with "c_", a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and :doc:`add them to LAMMPS <Section_modify>`.
If the style begins with "f_", a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with the
timestep on which this compute accesses the fix, else an error
results. Users can also write code for their own fix styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "v_", a variable name for an *atom* or
*atomfile* style :doc:`variable <variable>` must follow which has been
previously defined in the input script. Variables of style *atom* can
reference thermodynamic keywords and various per-atom attributes, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of generating per-atom quantities to
treat as a chunk ID.
Normally, *Nchunk* = the number of chunks, is re-calculated every time
this fix is invoked, though the value may or may not change. As
explained below, the *nchunk* keyword can be set to *once* which means
*Nchunk* will never change.
If a :doc:`fix ave/chunk <fix_ave_chunk>` command uses this compute, it
can also turn off the re-calculation of *Nchunk* for one or more
windows of timesteps. The extent of the windows, during which Nchunk
is held constant, are determined by the *Nevery*, *Nrepeat*, *Nfreq*
values and the *ave* keyword setting that are used by the :doc:`fix ave/chunk <fix_ave_chunk>` command.
Specifically, if *ave* = *one*, then for each span of *Nfreq*
timesteps, *Nchunk* is held constant between the first timestep when
averaging is done (within the Nfreq-length window), and the last
timestep when averaging is done (multiple of Nfreq). If *ave* =
*running* or *window*, then *Nchunk* is held constant forever,
starting on the first timestep when the :doc:`fix ave/chunk <fix_ave_chunk>` command invokes this compute.
Note that multiple :doc:`fix ave/chunk <fix_ave_chunk>` commands can use
the same compute chunk/atom compute. However, the time windows they
induce for holding *Nchunk* constant must be identical, else an error
will be generated.
The various optional keywords operate as follows. Note that some of
them function differently or are ignored by different chunk styles.
Some of them also have different default values, depending on
the chunk style, as listed below.
The *region* keyword applies to all chunk styles. If used, an atom
must be in both the specified group and the specified geometric
:doc:`region <region>` to be assigned to a chunk.
----------
The *nchunk* keyword applies to all chunk styles. It specifies how
often *Nchunk* is recalculated, which in turn can affect the chunk IDs
assigned to individual atoms.
If *nchunk* is set to *once*, then *Nchunk* is only calculated once,
the first time this compute is invoked. If *nchunk* is set to
*every*, then *Nchunk* is re-calculated every time the compute is
invoked. Note that, as described above, the use of this compute
by the :doc:`fix ave/chunk <fix_ave_chunk>` command can override
the *every* setting.
The default values for *nchunk* are listed below and depend on the
chunk style and other system and keyword settings. They attempt to
represent typical use cases for the various chunk styles. The
*nchunk* value can always be set explicitly if desired.
----------
The *limit* keyword can be used to limit the calculated value of
*Nchunk* = the number of chunks. The limit is applied each time
*Nchunk* is calculated, which also limits the chunk IDs assigned to
any atom. The *limit* keyword is used by all chunk styles except the
*binning* styles, which ignore it. This is because the number of bins
can be tailored using the *bound* keyword (described below) which
effectively limits the size of *Nchunk*.
If *limit* is set to *Nc* = 0, then no limit is imposed on *Nchunk*,
though the *compress* keyword can still be used to reduce *Nchunk*, as
described below.
If *Nc* > 0, then the effect of the *limit* keyword depends on whether
the *compress* keyword is also used with a setting of *yes*, and
whether the *compress* keyword is specified before the *limit* keyword
or after.
In all cases, *Nchunk* is first calculated in the usual way for each
chunk style, as described above.
First, here is what occurs if *compress yes* is not set. If *limit*
is set to *Nc max*, then *Nchunk* is reset to the smaller of *Nchunk*
and *Nc*. If *limit* is set to *Nc exact*, then *Nchunk* is reset to
*Nc*, whether the original *Nchunk* was larger or smaller than *Nc*.
If *Nchunk* shrank due to the *limit* setting, then atom chunk IDs >
*Nchunk* will be reset to 0 or *Nchunk*, depending on the setting of
the *discard* keyword. If *Nchunk* grew, there will simply be some
chunks with no atoms assigned to them.
If *compress yes* is set, and the *compress* keyword comes before the
*limit* keyword, the compression operation is performed first, as
described below, which resets *Nchunk*. The *limit* keyword is then
applied to the new *Nchunk* value, exactly as described in the
preceeding paragraph. Note that in this case, all atoms will end up
with chunk IDs <= *Nc*, but their original values (e.g. molecule ID or
compute/fix/variable value) may have been > *Nc*, because of the
compression operation.
If *compress yes* is set, and the *compress* keyword comes after the
*limit* keyword, then the *limit* value of *Nc* is applied first to
the uncompressed value of *Nchunk*, but only if *Nc* < *Nchunk*
(whether *Nc max* or *Nc exact* is used). This effectively means all
atoms with chunk IDs > *Nc* have their chunk IDs reset to 0 or *Nc*,
depending on the setting of the *discard* keyword. The compression
operation is then performed, which may shrink *Nchunk* further. If
the new *Nchunk* < *Nc* and *limit* = *Nc exact* is specified, then
*Nchunk* is reset to *Nc*, which results in extra chunks with no atoms
assigned to them. Note that in this case, all atoms will end up with
chunk IDs <= *Nc*, and their original values (e.g. molecule ID or
compute/fix/variable value) will also have been <= *Nc*.
----------
The *ids* keyword applies to all chunk styles. If the setting is
*once* then the chunk IDs assigned to atoms the first time this
compute is invoked will be permanent, and never be re-computed.
If the setting is *nfreq* and if a :doc:`fix ave/chunk <fix_ave_chunk>`
command is using this compute, then in each of the *Nchunk* = constant
time windows (discussed above), the chunk ID's assigned to atoms on
the first step of the time window will persist until the end of the
time window.
If the setting is *every*, which is the default, then chunk IDs are
re-calculated on any timestep this compute is invoked.
.. warning::
If you want the persistent chunk-IDs calculated by
this compute to be continuous when running from a :doc:`restart file <read_restart>`, then you should use the same ID for this
compute, as in the original run. This is so that the fix this compute
creates to store per-atom quantities will also have the same ID, and
thus be initialized correctly with chunk IDs from the restart file.
----------
The *compress* keyword applies to all chunk styles and affects how
*Nchunk* is calculated, which in turn affects the chunk IDs assigned
to each atom. It is useful for converting a "sparse" set of chunk IDs
(with many IDs that have no atoms assigned to them), into a "dense"
set of IDs, where every chunk has one or more atoms assigned to it.
Two possible use cases are as follows. If a large simulation box is
mostly empty space, then the *binning* style may produce many bins
with no atoms. If *compress* is set to *yes*, only bins with atoms
will be contribute to *Nchunk*. Likewise, the *molecule* or
*compute/fix/variable* styles may produce large *Nchunk* values. For
example, the :doc:`compute cluster/atom <compute_cluster_atom>` command
assigns every atom an atom ID for one of the atoms it is clustered
with. For a million-atom system with 5 clusters, there would only be
5 unique chunk IDs, but the largest chunk ID might be 1 million,
resulting in *Nchunk* = 1 million. If *compress* is set to *yes*,
*Nchunk* will be reset to 5.
If *compress* is set to *no*, which is the default, no compression is
done. If it is set to *yes*, all chunk IDs with no atoms are removed
from the list of chunk IDs, and the list is sorted. The remaining
chunk IDs are renumbered from 1 to *Nchunk* where *Nchunk* is the new
length of the list. The chunk IDs assigned to each atom reflect
the new renumbering from 1 to *Nchunk*.
The original chunk IDs (before renumbering) can be accessed by the
:doc:`compute property/chunk <compute_property_chunk>` command and its
*id* keyword, or by the :doc:`fix ave/chunk <fix_ave_chunk>` command
which outputs the original IDs as one of the columns in its global
output array. For example, using the "compute cluster/atom" command
discussed above, the original 5 unique chunk IDs might be atom IDs
(27,4982,58374,857838,1000000). After compresion, these will be
renumbered to (1,2,3,4,5). The original values (27,...,1000000) can
be output to a file by the :doc:`fix ave/chunk <fix_ave_chunk>` command,
or by using the :doc:`fix ave/time <fix_ave_time>` command in
conjunction with the :doc:`compute property/chunk <compute_property_chunk>` command.
.. warning::
The compression operation requires global
communication across all processors to share their chunk ID values.
It can require large memory on every processor to store them, even
after they are compressed, if there are are a large number of unique
chunk IDs with atoms assigned to them. It uses a STL map to find
unique chunk IDs and store them in sorted order. Each time an atom is
assigned a compressed chunk ID, it must access the STL map. All of
this means that compression can be expensive, both in memory and CPU
time. The use of the *limit* keyword in conjunction with the
*compress* keyword can affect these costs, depending on which keyword
is used first. So use this option with care.
----------
The *discard* keyword applies to all chunk styles. It affects what
chunk IDs are assigned to atoms that do not match one of the valid
chunk IDs from 1 to *Nchunk*. Note that it does not apply to atoms
that are not in the specified group or optionally specified region.
Those atoms are always assigned a chunk ID = 0.
If the calculated chunk ID for an atom is not within the range 1 to
*Nchunk* then it is a "discard" atom. Note that *Nchunk* may have
been shrunk by the *limit* keyword. Or the *compress* keyword may
have eliminated chunk IDs that were valid before the compression took
place, and are now not in the compressed list. Also note that for the
*molecule* chunk style, if new molecules are added to the system,
their chunk IDs may exceed a previously calculated *Nchunk*.
Likewise, evaluation of a compute/fix/variable on a later timestep may
return chunk IDs that are invalid for the previously calculated
*Nchunk*.
All the chunk styles except the *binning* styles, must use *discard*
set to either *yes* or *no*. If *discard* is set to *yes*, which is
the default, then every "discard" atom has its chunk ID set to 0. If
*discard* is set to *no*, every "discard" atom has its chunk ID set to
*Nchunk*. I.e. it becomes part of the last chunk.
The *binning* styles use the *discard* keyword to decide whether to
discard atoms outside the spatial domain covered by bins, or to assign
them to the bin they are nearest to. Details are as follows.
If *discard* is set to *yes*, an out-of-domain atom will have its
chunk ID set to 0. If *discard* is set to *no*, the atom will have
its chunk ID set to the first or last bin in that dimension. If
(discard* is set to *mixed*, which is the default, it will only have
its chunk ID set to the first or last bin if bins extend to the
simulation box boundary in that dimension. This is the case if the
*bound* keyword settings are *lower* and *upper*, which is the
default. If the *bound* keyword settings are numeric values, then the
atom will have its chunk ID set to 0 if it is outside the bounds of
any bin. Note that in this case, it is possible that the first or
last bin extends beyond the numeric *bounds* settings, depending on
the specified *origin*. If this is the case, the chunk ID of the atom
is only set to 0 if it is outside the first or last bin, not if it is
simply outside the numeric *bounds* setting.
----------
The *bound* keyword only applies to the *binning* styles; otherwise it
is ignored. It can be used one or more times to limit the extent of
bin coverage in a specified dimension, i.e. to only bin a portion of
the box. If the *lo* setting is *lower* or the *hi* setting is
*upper*, the bin extent in that direction extends to the box boundary.
If a numeric value is used for *lo* and/or *hi*, then the bin extent
in the *lo* or *hi* direction extends only to that value, which is
assumed to be inside (or at least near) the simulation box boundaries,
though LAMMPS does not check for this. Note that using the *bound*
keyword typically reduces the total number of bins and thus the number
of chunks *Nchunk*.
The *units* keyword only applies to the *binning* styles; otherwise it
is ignored. It determines the meaning of the distance units used for
the bin sizes *delta* and for *origin* and *bounds* values if they are
coordinate values. For orthogonal simulation boxes, any of the 3
options may be used. For non-orthogonal (triclinic) simulation boxes,
only the *reduced* option may be used.
A *box* value selects standard distance units as defined by the
:doc:`units <units>` command, e.g. Angstroms for units = real or metal.
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` command must have been previously used to
define the lattice spacing. A *reduced* value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an *origin* value of
0.5 means the center of the box in any dimension. A *delta* value of
0.1 means 10 bins span the box in that dimension.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitless chunk IDs, ranging from 1 to
*Nchunk* (inclusive) for atoms assigned to chunks, and 0 for atoms not
belonging to a chunk.
Restrictions
""""""""""""
Even if the *nchunk* keyword is set to *once*, the chunk IDs assigned
to each atom are not stored in a restart files. This means you cannot
expect those assignments to persist in a restarted simulation.
Instead you must re-specify this command and assign atoms to chunks when
the restarted simulation begins.
Related commands
""""""""""""""""
:doc:`fix ave/chunk <fix_ave_chunk>`
Default
"""""""
The option defaults are as follows:
* region = none
* nchunk = every if compress is yes, overriding other defaults listed here
* nchunk = once for type style
* nchunk = once for mol style if region is none
* nchunk = every for mol style if region is set
* nchunk = once for binning style if the simulation box size is static or units = reduced
* nchunk = every for binning style if the simulation box size is dynamic and units is lattice or box
* nchunk = every for compute/fix/variable style
* limit = 0
* ids = every
* compress = no
* discard = yes for all styles except binning
* discard = mixed for binning styles
* bound = lower and upper in all dimensions
* units = lattice
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

67
doc/_sources/compute_cluster_atom.txt
View File

@ -1,67 +0,0 @@
.. index:: compute cluster/atom
compute cluster/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID cluster/atom cutoff
* ID, group-ID are documented in :doc:`compute <compute>` command
* cluster/atom = style name of this compute command
* cutoff = distance within which to label atoms as part of same cluster (distance units)
Examples
""""""""
.. parsed-literal::
compute 1 all cluster/atom 1.0
Description
"""""""""""
Define a computation that assigns each atom a cluster ID.
A cluster is defined as a set of atoms, each of which is within the
cutoff distance from one or more other atoms in the cluster. If an
atom has no neighbors within the cutoff distance, then it is a 1-atom
cluster. The ID of every atom in the cluster will be the smallest
atom ID of any atom in the cluster.
Only atoms in the compute group are clustered and assigned cluster
IDs. Atoms not in the compute group are assigned a cluster ID = 0.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of a
*clsuter/atom* style.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be an ID > 0, as explained above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute coord/atom <compute_coord_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

117
doc/_sources/compute_cna_atom.txt
View File

@ -1,117 +0,0 @@
.. index:: compute cna/atom
compute cna/atom command
========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID cna/atom cutoff
* ID, group-ID are documented in :doc:`compute <compute>` command
* cna/atom = style name of this compute command
* cutoff = cutoff distance for nearest neighbors (distance units)
Examples
""""""""
.. parsed-literal::
compute 1 all cna/atom 3.08
Description
"""""""""""
Define a computation that calculates the CNA (Common Neighbor
Analysis) pattern for each atom in the group. In solid-state systems
the CNA pattern is a useful measure of the local crystal structure
around an atom. The CNA methodology is described in :ref:`(Faken) <Faken>`
and :ref:`(Tsuzuki) <Tsuzuki>`.
Currently, there are five kinds of CNA patterns LAMMPS recognizes:
* fcc = 1
* hcp = 2
* bcc = 3
* icosohedral = 4
* unknown = 5
The value of the CNA pattern will be 0 for atoms not in the specified
compute group. Note that normally a CNA calculation should only be
performed on mono-component systems.
The CNA calculation can be sensitive to the specified cutoff value.
You should insure the appropriate nearest neighbors of an atom are
found within the cutoff distance for the presumed crystal strucure.
E.g. 12 nearest neighbor for perfect FCC and HCP crystals, 14 nearest
neighbors for perfect BCC crystals. These formulas can be used to
obtain a good cutoff distance:
.. image:: Eqs/cna_cutoff1.jpg
:align: center
where a is the lattice constant for the crystal structure concerned
and in the HCP case, x = (c/a) / 1.633, where 1.633 is the ideal c/a
for HCP crystals.
Also note that since the CNA calculation in LAMMPS uses the neighbors
of an owned atom to find the nearest neighbors of a ghost atom, the
following relation should also be satisfied:
.. image:: Eqs/cna_cutoff2.jpg
:align: center
where Rc is the cutoff distance of the potential, Rs is the skin
distance as specified by the :doc:`neighbor <neighbor>` command, and
cutoff is the argument used with the compute cna/atom command. LAMMPS
will issue a warning if this is not the case.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (e.g. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each with a
*cna/atom* style.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values will be a number from 0 to 5, as explained
above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute centro/atom <compute_centro_atom>`
**Default:** none
----------
.. _Faken:
**(Faken)** Faken, Jonsson, Comput Mater Sci, 2, 279 (1994).
.. _Tsuzuki:
**(Tsuzuki)** Tsuzuki, Branicio, Rino, Comput Phys Comm, 177, 518 (2007).
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

67
doc/_sources/compute_com.txt
View File

@ -1,67 +0,0 @@
.. index:: compute com
compute com command
===================
Syntax
""""""
.. parsed-literal::
compute ID group-ID com
* ID, group-ID are documented in :doc:`compute <compute>` command
* com = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all com
Description
"""""""""""
Define a computation that calculates the center-of-mass of the group
of atoms, including all effects due to atoms passing thru periodic
boundaries.
A vector of three quantites is calculated by this compute, which
are the x,y,z coordinates of the center of mass.
.. warning::
The coordinates of an atom contribute to the
center-of-mass in "unwrapped" form, by using the image flags
associated with each atom. See the :doc:`dump custom <dump>` command
for a discussion of "unwrapped" coordinates. See the Atoms section of
the :doc:`read_data <read_data>` command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
**Output info:**
This compute calculates a global vector of length 3, which can be
accessed by indices 1-3 by any command that uses global vector values
from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The vector values are "intensive". The vector values will be in
distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute com/chunk <compute_com_chunk>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

95
doc/_sources/compute_com_chunk.txt
View File

@ -1,95 +0,0 @@
.. index:: compute com/chunk
compute com/chunk command
=========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID com/chunk chunkID
* ID, group-ID are documented in :doc:`compute <compute>` command
* com/chunk = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
Examples
""""""""
.. parsed-literal::
compute 1 fluid com/chunk molchunk
Description
"""""""""""
Define a computation that calculates the center-of-mass for multiple
chunks of atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` doc page and ":ref:`Section_howto 23 <howto_23>` for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.
This compute calculates the x,y,z coordinates of the center-of-mass
for each chunk, which includes all effects due to atoms passing thru
periodic boundaries.
Note that only atoms in the specified group contribute to the
calculation. The :doc:`compute chunk/atom <compute_chunk_atom>` command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
"all" group for this command if you simply want to include atoms with
non-zero chunk IDs.
.. warning::
The coordinates of an atom contribute to the chunk's
center-of-mass in "unwrapped" form, by using the image flags
associated with each atom. See the :doc:`dump custom <dump>` command
for a discussion of "unwrapped" coordinates. See the Atoms section of
the :doc:`read_data <read_data>` command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the :doc:`set image <set>` command.
The simplest way to output the results of the compute com/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`
command, for example:
.. parsed-literal::
compute cc1 all chunk/atom molecule
compute myChunk all com/chunk cc1
fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
**Output info:**
This compute calculates a global array where the number of rows = the
number of chunks *Nchunk* as calculated by the specified :doc:`compute chunk/atom <compute_chunk_atom>` command. The number of columns =
3 for the x,y,z center-of-mass coordinates of each chunk. These
values can be accessed by any command that uses global array values
from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The array values are "intensive". The array values will be in
distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute com <compute_com>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

64
doc/_sources/compute_contact_atom.txt
View File

@ -1,64 +0,0 @@
.. index:: compute contact/atom
compute contact/atom command
============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID contact/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* contact/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all contact/atom
Description
"""""""""""
Define a computation that calculates the number of contacts
for each atom in a group.
The contact number is defined for finite-size spherical particles as
the number of neighbor atoms which overlap the central particle,
meaning that their distance of separation is less than or equal to the
sum of the radii of the two particles.
The value of the contact number will be 0.0 for atoms not in the
specified compute group.
**Output info:**
This compute calculates a per-atom vector, whose values can be
accessed by any command that uses per-atom values from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The per-atom vector values will be a number >= 0.0, as explained
above.
Restrictions
""""""""""""
This compute requires that atoms store a radius as defined by the
:doc:`atom_style sphere <atom_style>` command.
Related commands
""""""""""""""""
:doc:`compute coord/atom <compute_coord_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

103
doc/_sources/compute_coord_atom.txt
View File

@ -1,103 +0,0 @@
.. index:: compute coord/atom
compute coord/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID coord/atom cutoff type1 type2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* coord/atom = style name of this compute command
* cutoff = distance within which to count coordination neighbors (distance units)
* typeN = atom type for Nth coordination count (see asterisk form below)
Examples
""""""""
.. parsed-literal::
compute 1 all coord/atom 2.0
compute 1 all coord/atom 6.0 1 2
compute 1 all coord/atom 6.0 2*4 5*8 *
Description
"""""""""""
Define a computation that calculates one or more coordination numbers
for each atom in a group.
A coordination number is defined as the number of neighbor atoms with
specified atom type(s) that are within the specified cutoff distance
from the central atom. Atoms not in the group are included in a
coordination number of atoms in the group.
The *typeN* keywords allow you to specify which atom types contribute
to each coordination number. One coordination number is computed for
each of the *typeN* keywords listed. If no *typeN* keywords are
listed, a single coordination number is calculated, which includes
atoms of all types (same as the "*" format, see below).
The *typeN* keywords can be specified in one of two ways. An explicit
numeric value can be used, as in the 2nd example above. Or a
wild-card asterisk can be used to specify a range of atom types. This
takes the form "*" or "*n" or "n*" or "m*n". If N = the number of
atom types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
The value of all coordination numbers will be 0.0 for atoms not in the
specified compute group.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently.
.. warning::
If you have a bonded system, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the coordination count. One way
to get around this, is to write a dump file, and use the
:doc:`rerun <rerun>` command to compute the coordination for snapshots
in the dump file. The rerun script can use a
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
**Output info:**
If single *type1* keyword is specified (or if none are specified),
this compute calculates a per-atom vector. If multiple *typeN*
keywords are specified, this compute calculates a per-atom array, with
N columns. These values can be accessed by any command that uses
per-atom values from a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom vector or array values will be a number >= 0.0, as
explained above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute cluster/atom <compute_cluster_atom>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_damage_atom.txt
View File

@ -1,69 +0,0 @@
.. index:: compute damage/atom
compute damage/atom command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID damage/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* damage/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all damage/atom
Description
"""""""""""
Define a computation that calculates the per-atom damage for each atom
in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
The "damage" of a Peridymaics particles is based on the bond breakage
between the particle and its neighbors. If all the bonds are broken
the particle is considered to be fully damaged.
See the `PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for a formal
definition of "damage" and more details about Peridynamics as it is
implemented in LAMMPS.
This command can be used with all the Peridynamic pair styles.
The damage value will be 0.0 for atoms not in the specified compute
group.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The per-atom vector values are unitlesss numbers (damage) >= 0.0.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute dilatation <compute_dilatation>`, :doc:`compute plasticity <compute_plasticity>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

79
doc/_sources/compute_dihedral_local.txt
View File

@ -1,79 +0,0 @@
.. index:: compute dihedral/local
compute dihedral/local command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID dihedral/local input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* dihedral/local = style name of this compute command
* one or more keywords may be appended
* keyword = *phi*
.. parsed-literal::
*phi* = tabulate dihedral angles
Examples
""""""""
.. parsed-literal::
compute 1 all dihedral/local phi
Description
"""""""""""
Define a computation that calculates properties of individual dihedral
interactions. The number of datums generated, aggregated across all
processors, equals the number of angles in the system, modified by the
group parameter as explained below.
The local data stored by this command is generated by looping over all
the atoms owned on a processor and their dihedrals. A dihedral will
only be included if all 4 atoms in the dihedral are in the specified
compute group.
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, dihedral output from the :doc:`compute property/local <compute_property_local>` command can be combined
with data from this command and output by the :doc:`dump local <dump>`
command in a consistent way.
**Output info:**
This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of dihedrals. If a single keyword is specified, a
local vector is produced. If two or more keywords are specified, a
local array is produced where the number of columns = the number of
keywords. The vector or array can be accessed by any command that
uses local values from a compute as input. See :ref:`this section <howto_15>` for an overview of LAMMPS output
options.
The output for *phi* will be in degrees.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`dump local <dump>`, :doc:`compute property/local <compute_property_local>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

71
doc/_sources/compute_dilatation_atom.txt
View File

@ -1,71 +0,0 @@
.. index:: compute dilatation/atom
compute dilatation/atom command
===============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID dilatation/atom
* ID, group-ID are documented in compute command
* dilation/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all dilatation/atom
Description
"""""""""""
Define a computation that calculates the per-atom dilatation for each
atom in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
For small deformation, dilatation of is the measure of the volumetric
strain.
The dilatation "theta" for each peridynamic particle I is calculated
as a sum over its neighbors with unbroken bonds, where the
contribution of the IJ pair is a function of the change in bond length
(versus the initial length in the reference state), the volume
fraction of the particles and an influence function. See the
`PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for a formal
definition of dilatation.
This command can only be used with a subset of the Peridynamic :doc:`pair styles <pair_peri>`: peri/lps, peri/ves and peri/eps.
The dilatation value will be 0.0 for atoms not in the specified
compute group.
**Output info:**
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
Section_howto 15 for an overview of LAMMPS output options.
The per-atom vector values are unitlesss numbers (theta) >= 0.0.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute damage <compute_damage>`, :doc:`compute plasticity <compute_plasticity>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

80
doc/_sources/compute_displace_atom.txt
View File

@ -1,80 +0,0 @@
.. index:: compute displace/atom
compute displace/atom command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID displace/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* displace/atom = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all displace/atom
Description
"""""""""""
Define a computation that calculates the current displacement of each
atom in the group from its original coordinates, including all effects
due to atoms passing thru periodic boundaries.
A vector of four quantites per atom is calculated by this compute.
The first 3 elements of the vector are the dx,dy,dz displacements.
The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +
dz*dz).
The displacement of an atom is from its original position at the time
the compute command was issued. The value of the displacement will be
0.0 for atoms not in the specified compute group.
.. warning::
Initial coordinates are stored in "unwrapped" form, by
using the image flags associated with each atom. See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
See the Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the :doc:`set image <set>` command.
.. warning::
If you want the quantities calculated by this compute
to be continuous when running from a :doc:`restart file <read_restart>`,
then you should use the same ID for this compute, as in the original
run. This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with time=0 atom coordinates from the restart file.
**Output info:**
This compute calculates a per-atom array with 4 columns, which can be
accessed by indices 1-4 by any command that uses per-atom values from
a compute as input. See :ref:`Section_howto 15 <howto_15>` for an overview of LAMMPS output
options.
The per-atom array values will be in distance :doc:`units <units>`.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`compute msd <compute_msd>`, :doc:`dump custom <dump>`, :doc:`fix store/state <fix_store_state>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

80
doc/_sources/compute_erotate_asphere.txt
View File

@ -1,80 +0,0 @@
.. index:: compute erotate/asphere
compute erotate/asphere command
===============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/asphere
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/asphere = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/asphere
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a group of aspherical particles. The aspherical particles can be
ellipsoids, or line segments, or triangles. See the
:doc:`atom_style <atom_style>` and :doc:`read_data <read_data>` commands
for descriptions of these options.
For all 3 types of particles, the rotational kinetic energy is
computed as 1/2 I w^2, where I is the inertia tensor for the
aspherical particle and w is its angular velocity, which is computed
from its angular momentum if needed.
.. warning::
For :doc:`2d models <dimension>`, ellipsoidal particles
are treated as ellipsoids, not ellipses, meaning their moments of
inertia will be the same as in 3d.
**Output info:**
This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute requires that ellipsoidal particles atoms store a shape
and quaternion orientation and angular momentum as defined by the
:doc:`atom_style ellipsoid <atom_style>` command.
This compute requires that line segment particles atoms store a length
and orientation and angular velocity as defined by the :doc:`atom_style line <atom_style>` command.
This compute requires that triangular particles atoms store a size and
shape and quaternion orientation and angular momentum as defined by
the :doc:`atom_style tri <atom_style>` command.
All particles in the group must be finite-size. They cannot be point
particles.
**Related commands:** none
:doc:`compute erotate/sphere <compute_erotate_sphere>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_erotate_rigid.txt
View File

@ -1,69 +0,0 @@
.. index:: compute erotate/rigid
compute erotate/rigid command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/rigid fix-ID
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/rigid = style name of this compute command
* fix-ID = ID of rigid body fix
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/rigid myRigid
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a collection of rigid bodies, as defined by one of the :doc:`fix rigid <fix_rigid>` command variants.
The rotational energy of each rigid body is computed as 1/2 I Wbody^2,
where I is the inertia tensor for the rigid body, and Wbody is its
angular velocity vector. Both I and Wbody are in the frame of
reference of the rigid body, i.e. I is diagonalized.
The *fix-ID* should be the ID of one of the :doc:`fix rigid <fix_rigid>`
commands which defines the rigid bodies. The group specified in the
compute command is ignored. The rotational energy of all the rigid
bodies defined by the fix rigid command in included in the
calculation.
**Output info:**
This compute calculates a global scalar (the summed rotational energy
of all the rigid bodies). This value can be used by any command that
uses a global scalar value from a compute as input. See
:ref:`Section_howto 15 <howto_15>` for an overview of
LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute is part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute ke/rigid <compute_erotate_ke_rigid>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

69
doc/_sources/compute_erotate_sphere.txt
View File

@ -1,69 +0,0 @@
.. index:: compute erotate/sphere
compute erotate/sphere command
==============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID erotate/sphere
* ID, group-ID are documented in :doc:`compute <compute>` command
* erotate/sphere = style name of this compute command
Examples
""""""""
.. parsed-literal::
compute 1 all erotate/sphere
Description
"""""""""""
Define a computation that calculates the rotational kinetic energy of
a group of spherical particles.
The rotational energy is computed as 1/2 I w^2, where I is the moment
of inertia for a sphere and w is the particle's angular velocity.
.. warning::
For :doc:`2d models <dimension>`, particles are treated
as spheres, not disks, meaning their moment of inertia will be the
same as in 3d.
**Output info:**
This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See :ref:`Section_howto 15 <howto_15>` for an
overview of LAMMPS output options.
The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units <units>`.
Restrictions
""""""""""""
This compute requires that atoms store a radius and angular velocity
(omega) as defined by the :doc:`atom_style sphere <atom_style>` command.
All particles in the group must be finite-size spheres or point
particles. They cannot be aspherical. Point particles will not
contribute to the rotational energy.
Related commands
""""""""""""""""
:doc:`compute erotate/asphere <compute_erotate_asphere>`
**Default:** none
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

Some files were not shown because too many files have changed in this diff Show More