ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'develop' into collected-small-changes

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-05-17 22:10:15 -04:00
parent a5171beacd 935c9a02d7
commit e94275391c
58 changed files with 16188 additions and 13002 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
doc/src/Tools.rst
View File

@ -56,6 +56,7 @@ Pre-processing tools
* :ref:`moltemplate <moltemplate>`
* :ref:`msi2lmp <msi>`
* :ref:`polybond <polybond>`
* :ref:`stl_bin2txt <stlconvert>`
Post-processing tools
@ -1017,6 +1018,28 @@ For more details please see the README.md file in that folder.
----------
.. _stlconvert:
stl_bin2txt tool
----------------
The file stl_bin2txt.cpp converts binary STL files - like they are
frequently offered for download on the web - into ASCII format STL files
that LAMMPS can read with the :doc:`create_atoms mesh <create_atoms>` or
the :doc:`fix smd/wall_surface <fix_smd_wall_surface>` commands. The syntax
for running the tool is
.. code-block:: bash
stl_bin2txt infile.stl outfile.stl
which creates outfile.stl from infile.stl. This tool must be compiled
on a platform compatible with the byte-ordering that was used to create
the binary file. This usually is a so-called little endian hardware
(like x86).
----------
.. _swig:
SWIG interface

117
doc/src/create_atoms.rst
View File

@ -11,7 +11,7 @@ Syntax
create_atoms type style args keyword values ...
* type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)
* style = *box* or *region* or *single* or *random*
* style = *box* or *region* or *single* or *mesh* or *random*
.. parsed-literal::
@ -20,6 +20,8 @@ Syntax
region-ID = particles will only be created if contained in the region
*single* args = x y z
x,y,z = coordinates of a single particle (distance units)
*mesh* args = STL-file
STL-file = file with triangle mesh in STL format
*random* args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
@ -47,6 +49,14 @@ Syntax
*set* values = dim name
dim = *x* or *y* or *z*
name = name of variable to set with x, y, or z atom position
*radscale* value = factor
factor = scale factor for setting atom radius
*meshmode* values = mode arg
mode = *bisect* or *qrand*
*bisect* arg = radthresh
radthresh = threshold value for *mesh* to determine when to split triangles (distance units)
*qrand* arg = density
density = minimum number density for atoms place on *mesh* triangles (inverse distance squared units)
*rotate* values = theta Rx Ry Rz
theta = rotation angle for single molecule (degrees)
Rx,Ry,Rz = rotation vector for single molecule
@ -69,21 +79,23 @@ Examples
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos
create_atoms 2 random 50 12345 NULL overlap 2.0 maxtry 50
create_atoms 1 mesh open_box.stl meshmode qrand 0.1 units box
create_atoms 1 mesh funnel.stl meshmode bisect 4.0 units box radscale 0.9
Description
"""""""""""
This command creates atoms (or molecules) within the simulation box,
either on a lattice, or a single atom (or molecule), or a random
collection of atoms (or molecules). It is an alternative to reading
in atom coordinates explicitly via a :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command. A simulation box must
already exist, which is typically created via the :doc:`create_box
<create_box>` command. Before using this command, a lattice must also
be defined using the :doc:`lattice <lattice>` command, unless you
specify the *single* style with units = box or the *random* style.
For the remainder of this doc page, a created atom or molecule is
referred to as a "particle".
either on a lattice, or a single atom (or molecule), or on a surface
defined by a triangulated mesh, or a random collection of atoms (or
molecules). It is an alternative to reading in atom coordinates
explicitly via a :doc:`read_data <read_data>` or :doc:`read_restart
<read_restart>` command. A simulation box must already exist, which is
typically created via the :doc:`create_box <create_box>` command.
Before using this command, a lattice must also be defined using the
:doc:`lattice <lattice>` command, unless you specify the *single* style
with units = box or the *random* style. For the remainder of this doc
page, a created atom or molecule is referred to as a "particle".
If created particles are individual atoms, they are assigned the
specified atom *type*, though this can be altered via the *basis*
@ -119,6 +131,62 @@ the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.
.. figure:: img/marble_race.jpg
:figwidth: 33%
:align: right
:target: _images/marble_race.jpg
For the *mesh* style, a file with a triangle mesh in `STL format
<https://en.wikipedia.org/wiki/STL_(file_format)>`_ is read and one or
more particles are placed into the area of each triangle. The reader
supports both ASCII and binary files conforming to the format on the
Wikipedia page. Binary STL files (e.g. as frequently offered for
3d-printing) can also be first converted to ASCII for editing with the
:ref:`stl_bin2txt tool <stlconvert>`. The use of the *units box* option
is required. There are two algorithms available for placing atoms:
*bisect* and *qrand*. They can be selected via the *meshmode* option;
*bisect* is the default. If the atom style allows it, the radius will
be set to a value depending on the algorithm and the value of the
*radscale* parameter (see below), and the atoms created from the mesh
are assigned a new molecule ID.
In *bisect* mode a particle is created at the center of each triangle
unless the average distance of the triangle vertices from its center is
larger than the *radthresh* value (default is lattice spacing in
x-direction). In case the average distance is over the threshold, the
triangle is recursively split into two halves along the the longest side
until the threshold is reached. There will be at least one sphere per
triangle. The value of *radthresh* is set as an argument to *meshmode
bisect*. The average distance of the vertices from the center is also
used to set the radius.
In *qrand* mode a quasi-random sequence is used to distribute particles
on mesh triangles using an approach by :ref:`(Roberts) <Roberts2019>`.
Particles are added to the triangle until the minimum number density is
met or exceeded such that every triangle will have at least one
particle. The minimum number density is set as an argument to the
*qrand* option. The radius will be set so that the sum of the area of
the radius of the particles created in place of a triangle will be equal
to the area of that triangle.
.. note::
The atom placement algorithms in the *mesh* style benefit from meshes
where triangles are close to equilateral. It is therefore
recommended to pre-process STL files to optimize the mesh
accordingly. There are multiple open source and commercial software
tools available with the capability to generate optimized meshes.
.. note::
In most cases the atoms created in *mesh* style will become an
immobile or rigid object that would not be time integrated or moved
by :doc:`fix move <fix_move>` or :doc:`fix rigid <fix_rigid>`. For
computational efficiency *and* to avoid undesired contributions to
pressure and potential energy due to close contacts, it is usually
beneficial to exclude computing interactions between the created
particles using :doc:`neigh_modify exclude <neigh_modify>`.
For the *random* 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
@ -316,6 +384,13 @@ the atoms around the rotation axis is consistent with the right-hand
rule: if your right-hand's thumb points along *R*, then your fingers
wrap around the axis in the direction of rotation.
The *radscale* keyword only applies to the *mesh* style and adjusts the
radius of created particles (see above), provided this is supported by
the atom style. Its value is a prefactor (must be > 0.0, default is
1.0) that is applied to the atom radius inferred from the size of the
individual triangles in the triangle mesh that the particle corresponds
to.
The *overlap* keyword only applies to the *random* style. It prevents
newly created particles from being created closer than the specified
*Doverlap* distance from any other particle. When the particles being
@ -424,9 +499,11 @@ values specified in the file read by the :doc:`molecule <molecule>`
command. E.g. the file typically defines bonds (angles,etc) between
atoms in the molecule, and can optionally define charges on each atom.
Note that the *sphere* 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.
Note that the *sphere* 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. When using the *mesh* style,
the particle diameter is adjusted from the size of the individual
triangles in the triangle mesh.
Note that the *ellipsoid* 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
@ -460,5 +537,13 @@ Default
The default for the *basis* keyword is that all created atoms are
assigned the argument *type* as their atom type (when single atoms are
being created). The other defaults are *remap* = no, *rotate* =
random, *overlap* not checked, *maxtry* = 10, and *units* = lattice.
being created). The other defaults are *remap* = no, *rotate* = random,
*radscale* = 1.0, *radthresh* = x-lattice spacing, *overlap* not
checked, *maxtry* = 10, and *units* = lattice.
----------
.. _Roberts2019:
**(Roberts)** R. Roberts (2019) "Evenly Distributing Points in a Triangle." Extreme Learning.
`<http://extremelearning.com.au/evenly-distributing-points-in-a-triangle/>`_

63
doc/src/delete_atoms.rst
View File

@ -10,7 +10,7 @@ Syntax
delete_atoms style args keyword value ...
* style = *group* or *region* or *overlap* or *porosity* or *variable*
* style = *group* or *region* or *overlap* or *random* or *variable*
.. parsed-literal::
@ -20,11 +20,17 @@ Syntax
cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
group1-ID = one atom in pair must be in this group
group2-ID = other atom in pair must be in this group
*porosity* args = group-ID region-ID fraction seed
*random* args = ranstyle value eflag group-ID region-ID seed
ranstyle = *fraction* or *count*
for *fraction*:
value = fraction (0.0 to 1.0) of eligible atoms to delete
eflag = *no* for fast approximate deletion, *yes* for exact deletion
for *count*:
value = number of atoms to delete
eflag = *no* for warning if count > eligible atoms, *yes* for error
group-ID = group within which to perform deletions
region-ID = region within which to perform deletions
or NULL to only impose the group criterion
fraction = delete this fraction of atoms
seed = random number seed (positive integer)
*variable* args = variable-name
@ -46,16 +52,17 @@ Examples
delete_atoms region sphere compress no
delete_atoms overlap 0.3 all all
delete_atoms overlap 0.5 solvent colloid
delete_atoms porosity all cube 0.1 482793 bond yes
delete_atoms porosity polymer cube 0.1 482793 bond yes
delete_atoms random fraction 0.1 yes all cube 482793 bond yes
delete_atoms random fraction 0.3 no polymer NULL 482793 bond yes
delete_atoms random count 500 no ions NULL 482793
detele_atoms variable checkers
Description
"""""""""""
Delete the specified atoms. This command can be used to carve out
voids from a block of material or to delete created atoms that are too
close to each other (e.g. at a grain boundary).
Delete the specified atoms. This command can be used, for example, to
carve out voids from a block of material or to delete created atoms
that are too close to each other (e.g. at a grain boundary).
For style *group*, all atoms belonging to the group are deleted.
@ -81,17 +88,33 @@ have occurred that no atom pairs within the cutoff will remain
minimum number of atoms will be deleted, or that the same atoms will
be deleted when running on different numbers of processors.
For style *porosity* a specified *fraction* of atoms are deleted which
are both in the specified group and within the specified region. The
region-ID can be specified as NULL to only impose the group criterion.
Likewise, specifying the group-ID as *all* will only impose the region
criterion.
For style *random* a subset of eligible atoms are deleted. Which
atoms to delete are chosen randomly using the specified random number
*seed*. Which atoms are deleted may vary when running on different
numbers of processors.
For example, if fraction is 0.1, then 10% of the eligible atoms will
be deleted. The atoms to delete are chosen randomly. There is no
guarantee that the exact fraction of atoms will be deleted, or that
the same atoms will be deleted when running on different numbers of
processors.
For *ranstyle* = *fraction*, the specified fractional *value* (0.0 to
1.0) of eligible atoms are deleted. If *eflag* is set to *no*, then
the number of deleted atoms will be approximate, but the operation
will be fast. If *eflag* is set to *yes*, then the number deleted
will match the requested fraction, but for large systems the selection
of deleted atoms may take additional time to determine.
For *ranstyle* = *count*, the specified integer *value* is the number
of eligible atoms are deleted. If *eflag* is set to *no*, then if the
requested number is larger then the number of eligible atoms, a
warning is issued and only the eligible atoms are deleted instead of
the requested *value*. If *eflag* is set to *yes*, an error is
triggered instead and LAMMPS will exit. For large systems the
selection of atoms to delete may take additional time to determine,
the same as for requesting an exact fraction with *pstyle* =
*fraction*.
Which atoms are eligible for deletion for style *random* is determined
by the specified *group-ID* and *region-ID*. To be eligible, an atom
must be in both the specified group and region. If *group-ID* = all,
there is effectively no group criterion. If *region-ID* is specified
as NULL, no region criterion is imposed.
For style *variable*, all atoms for which the atom-style variable with
the given name evaluates to non-zero will be deleted. Additional atoms
@ -100,6 +123,10 @@ were deleted within the region; see the *mol* keyword discussion below.
This option allows complex selections of atoms not covered by the
other options listed above.
----------
Here is the meaning of the optional keywords.
If the *compress* keyword is set to *yes*, then after atoms are
deleted, then atom IDs are re-assigned so that they run from 1 to the
number of atoms in the system. Note that this is not done for

BIN
doc/src/img/marble_race.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB