Homec4science
Diffusion lammps (lammm-devel) Browse

lammps/doc/html/create_atoms.html
db1e17197fcflammm-devel

Last Change
Raw File

create_atoms.html
View Options

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>create_atoms command &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li>create_atoms command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="create-atoms-command">
<span id="index-0"></span><h1>create_atoms command</h1>
<div class="section" id="syntax">
<h2>Syntax</h2>
<pre class="literal-block">
create_atoms type style args keyword values ...
</pre>
<ul class="simple">
<li>type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)</li>
<li>style = <em>box</em> or <em>region</em> or <em>single</em> or <em>random</em></li>
</ul>
<pre class="literal-block">
<em>box</em> args = none
<em>region</em> args = region-ID
region-ID = particles will only be created if contained in the region
<em>single</em> args = x y z
x,y,z = coordinates of a single particle (distance units)
<em>random</em> args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
region-ID = create atoms within this region, use NULL for entire simulation box
</pre>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>mol</em> or <em>basis</em> or <em>remap</em> or <em>var</em> or <em>set</em> or <em>units</em></li>
</ul>
<pre class="literal-block">
<em>mol</em> value = template-ID seed
template-ID = ID of molecule template specified in a separate <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command
seed = random # seed (positive integer)
<em>basis</em> values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
<em>remap</em> value = <em>yes</em> or <em>no</em>
<em>var</em> value = name = variable name to evaluate for test of atom creation
<em>set</em> values = dim name
dim = <em>x</em> or <em>y</em> or <em>z</em>
name = name of variable to set with x, y, or z atom position
<em>rotate</em> values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees)
<em>units</em> value = <em>lattice</em> or <em>box</em>
<em>lattice</em> = the geometry is defined in lattice units
<em>box</em> = the geometry is defined in simulation box units
</pre>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>This command creates atoms (or molecules) on a lattice, or a single
atom (or molecule), or a random collection of atoms (or molecules), as
an alternative to reading in their coordinates explicitly via a
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command. A simulation box must already exist, which is typically
created via the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command. Before using
this command, a lattice must also be defined using the
<a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command, unless you specify the <em>single</em> style
with units = box or the <em>random</em> style. For the remainder of this doc
page, a created atom or molecule is referred to as a &#8220;particle&#8221;.</p>
<p>If created particles are individual atoms, they are assigned the
specified atom <em>type</em>, though this can be altered via the <em>basis</em>
keyword as discussed below. If molecules are being created, the type
of each atom in the created molecule is specified in the file read by
the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command, and those values are added to
the specified atom <em>type</em>. E.g. if <em>type</em> = 2, and the file specifies
atom types 1,2,3, then each created molecule will have atom types
3,4,5.</p>
<p>For the <em>box</em> style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
is periodic, you should insure its size is a multiple of the lattice
spacings, to avoid unwanted atom overlaps at the box boundaries. If
your box is periodic and a multiple of the lattice spacing in a
particular dimension, LAMMPS is careful to put exactly one particle at
the boundary (on either side of the box), not zero or two.</p>
<p>For the <em>region</em> style, a geometric volume is filled with particles on
the lattice. This volume what is inside the simulation box and is
also consistent with the region volume. See the <a class="reference internal" href="region.html"><span class="doc">region</span></a>
command for details. Note that a region can be specified so that its
&#8220;volume&#8221; is either inside or outside a geometric boundary. Also note
that if your region is the same size as a periodic simulation box (in
some dimension), LAMMPS does not implement the same logic described
above as for the <em>box</em> style, to insure exactly one particle at
periodic boundaries. if this is what you desire, you should either
use the <em>box</em> style, or tweak the region size to get precisely the
particles you want.</p>
<p>For the <em>single</em> style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.</p>
<p>For the <em>random</em> style, N particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
speficied random number <em>seed</em>, resulting in the same set of particles
coordinates, independent of how many processors are being used in the
simulation. If the <em>region-ID</em> argument is specified as NULL, then
the created particles will be anywhere in the simulation box. If a
<em>region-ID</em> is specified, a geometric volume is filled which is both
inside the simulation box and is also consistent with the region
volume. See the <a class="reference internal" href="region.html"><span class="doc">region</span></a> command for details. Note that
a region can be specified so that its &#8220;volume&#8221; is either inside or
outside a geometric boundary.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Particles generated by the <em>random</em> style will typically be
highly overlapped which will cause many interatomic potentials to
compute large energies and forces. Thus you should either perform an
<a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a> or run dynamics with <a class="reference internal" href="fix_nve_limit.html"><span class="doc">fix nve/limit</span></a> to equilibrate such a system, before
running normal dynamics.</p>
</div>
<p>Note that this command adds particles to those that already exist.
This means it can be used to add particles to a system previously read
in from a data or restart file. Or the create_atoms command can be
used multiple times, to add multiple sets of particles to the
simulation. For example, grain boundaries can be created, by
interleaving create_atoms with <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> commands
specifying different orientations. By using the create_atoms command
in conjunction with the <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command,
reasonably complex geometries can be created, or a protein can be
solvated with a surrounding box of water molecules.</p>
<p>In all these cases, care should be taken to insure that new atoms do
not overlap existing atoms inappropriately, especially if molecules
are being added. The <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command can be
used to remove overlapping atoms or molecules.</p>
<hr class="docutils" />
<p>Individual atoms are inserted by this command, unless the <em>mol</em>
keyword is used. It specifies a <em>template-ID</em> previously defined
using the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command, which reads a file that
defines the molecule. The coordinates, atom types, charges, etc, as
well as any bond/angle/etc and special neighbor information for the
molecule can be specified in the molecule file. See the
<a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command for details. The only settings
required to be in this file are the coordinates and types of atoms in
the molecule.</p>
<p>Using a lattice to add molecules, e.g. via the <em>box</em> or <em>region</em> or
<em>single</em> styles, is exactly the same as adding atoms on lattice
points, except that entire molecules are added at each point, i.e. on
the point defined by each basis atom in the unit cell as it tiles the
simulation box or region. This is done by placing the geometric
center of the molecule at the lattice point, and giving the molecule a
random orientation about the point. The random <em>seed</em> specified with
the <em>mol</em> keyword is used for this operation, and the random numbers
generated by each processor are different. This means the coordinates
of individual atoms (in the molecules) will be different when running
on different numbers of processors, unlike when atoms are being
created in parallel.</p>
<p>Also note that because of the random rotations, it may be important to
use a lattice with a large enough spacing that adjacent molecules will
not overlap, regardless of their relative orientations.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command is used to create
the simulation box, followed by the create_atoms command with its
<em>mol</em> option for adding molecules, then you typically need to use the
optional keywords allowed by the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command
for extra bonds (angles,etc) or extra special neighbors. This is
because by default, the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command sets up a
non-molecular system which doesn&#8217;t allow molecules to be added.</p>
</div>
<hr class="docutils" />
<p>This is the meaning of the other allowed keywords.</p>
<p>The <em>basis</em> keyword is only used when atoms (not molecules) are being
created. It specifies an atom type that will be assigned to specific
basis atoms as they are created. See the <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a>
command for specifics on how basis atoms are defined for the unit cell
of the lattice. By default, all created atoms are assigned the
argument <em>type</em> as their atom type.</p>
<p>The <em>remap</em> keyword only applies to the <em>single</em> style. If it is set
to <em>yes</em>, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to <em>no</em>, no remapping is done
and no particle is created if its position is outside the box.</p>
<p>The <em>var</em> and <em>set</em> keywords can be used together to provide a
criterion for accepting or rejecting the addition of an individual
atom, based on its coordinates. The <em>name</em> specified for the <em>var</em>
keyword is the name of an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> which
should evaluate to a zero or non-zero value based on one or two or
three variables which will store the x, y, or z coordinates of an atom
(one variable per coordinate). If used, these other variables must be
<a class="reference internal" href="variable.html"><span class="doc">internal-style variables</span></a> defined in the input script;
their initial numeric value can be anything. They must be
internal-style variables, because this command resets their values
directly. The <em>set</em> keyword is used to identify the names of these
other variables, one variable for the x-coordinate of a created atom,
one for y, and one for z.</p>
<p>When an atom is created, its x,y,z coordinates become the values for
any <em>set</em> variable that is defined. The <em>var</em> variable is then
evaluated. If the returned value is 0.0, the atom is not created. If
it is non-zero, the atom is created.</p>
<p>As an example, these commands can be used in a 2d simulation, to
create a sinusoidal surface. Note that the surface is &#8220;rough&#8221; due to
individual lattice points being &#8220;above&#8221; or &#8220;below&#8221; the mathematical
expression for the sinusoidal curve. If a finer lattice were used,
the sinusoid would appear to be &#8220;smoother&#8221;. Also note the use of the
&#8220;xlat&#8221; and &#8220;ylat&#8221; <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> keywords which
converts lattice spacings to distance. Click on the image for a
larger version.</p>
<pre class="literal-block">
variable x equal 100
variable y equal 25
lattice hex 0.8442
region box block 0 $x 0 $y -0.5 0.5
create_box 1 box
</pre>
<pre class="literal-block">
variable xx equal 0.0
variable yy equal 0.0
variable v equal &quot;(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) &gt; 0.0&quot;
create_atoms 1 box var v set x xx set y yy
</pre>
<a class=""
data-lightbox="group-default"
href="_images/sinusoid.jpg"
title=""
data-title=""
><img src="_images/sinusoid.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>The <em>rotate</em> keyword can be used with the <em>single</em> style, when adding
a single molecule to specify the orientation at which the molecule is
inserted. The axis of rotation is determined by the rotation vector
(Rx,Ry,Rz) that goes through the insertion point. The specified
<em>theta</em> determines the angle of rotation around that axis. Note that
the direction of rotation for the atoms around the rotation axis is
consistent with the right-hand rule: if your right-hand&#8217;s thumb points
along <em>R</em>, then your fingers wrap around the axis in the direction of
rotation.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the <em>single</em>
style. A <em>box</em> value selects standard distance units as defined by
the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or
metal. A <em>lattice</em> value means the distance units are in lattice
spacings.</p>
<hr class="docutils" />
<p>Atom IDs are assigned to created atoms in the following way. The
collection of created atoms are assigned consecutive IDs that start
immediately following the largest atom ID existing before the
create_atoms command was invoked. When a simulation is performed on
different numbers of processors, there is no guarantee a particular
created atom will be assigned the same ID. If molecules are being
created, molecule IDs are assigned to created molecules in a similar
fashion.</p>
<p>Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen <a class="reference internal" href="atom_style.html"><span class="doc">atom style</span></a>. See the <a class="reference internal" href="atom_style.html"><span class="doc">atom style</span></a> command for more details. See the
<a class="reference internal" href="set.html"><span class="doc">set</span></a> and <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> commands for info on how
to change these values.</p>
<ul class="simple">
<li>charge = 0.0</li>
<li>dipole moment magnitude = 0.0</li>
<li>diameter = 1.0</li>
<li>shape = 0.0 0.0 0.0</li>
<li>density = 1.0</li>
<li>volume = 1.0</li>
<li>velocity = 0.0 0.0 0.0</li>
<li>angular velocity = 0.0 0.0 0.0</li>
<li>angular momentum = 0.0 0.0 0.0</li>
<li>quaternion = (1,0,0,0)</li>
<li>bonds, angles, dihedrals, impropers = none</li>
</ul>
<p>If molecules are being created, these defaults can be overridden by
values specified in the file read by the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a>
command. E.g. the file typically defines bonds (angles,etc) between
atoms in the molecule, and can optionally define charges on each atom.</p>
<p>Note that the <em>sphere</em> atom style sets the default particle diameter
to 1.0 as well as the density. This means the mass for the particle
is not 1.0, but is PI/6 * diameter^3 = 0.5236.</p>
<p>Note that the <em>ellipsoid</em> atom style sets the default particle shape
to (0.0 0.0 0.0) and the density to 1.0 which means it is a point
particle, not an ellipsoid, and has a mass of 1.0.</p>
<p>Note that the <em>peri</em> style sets the default volume and density to 1.0
and thus also set the mass for the particle to 1.0.</p>
<p>The <a class="reference internal" href="set.html"><span class="doc">set</span></a> command can be used to override many of these
default settings.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>An <a class="reference internal" href="atom_style.html"><span class="doc">atom_style</span></a> must be previously defined to use this
command.</p>
<p>A rotation vector specified for a single molecule must be in
the z-direction for a 2d model.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands</h2>
<p><a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a>, <a class="reference internal" href="region.html"><span class="doc">region</span></a>, <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>,
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a>, <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a></p>
</div>
<div class="section" id="default">
<h2>Default</h2>
<p>The default for the <em>basis</em> keyword is that all created atoms are
assigned the argument <em>type</em> as their atom type (when single atoms are
being created). The other defaults are <em>remap</em> = no, <em>rotate</em> =
random, and <em>units</em> = lattice.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013 Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
c4science · Help