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

formatted mesocnt doc files

Browse Source
This commit is contained in:
phankl
2022-08-30 17:53:35 +01:00
parent 8a058ec2a0
commit 1139cb9345
3 changed files with 163 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
doc/src/angle_mesocnt.rst
View File

@ -28,24 +28,36 @@ The *mesocnt* angle style uses the potential
.. math::
E = K_\text{H} \Delta \theta^2 \qquad |\Delta \theta| < \Delta \theta_\text{B} \\
E = K_\text{H} \Delta \theta_\text{B}^2 + K_\text{B} (\Delta \theta - \Delta \theta_\text{B}) \qquad |\Delta \theta| \geq \Delta \theta_\text{B}
E = K_\text{H} \Delta \theta^2, \qquad |\Delta \theta| < \Delta
\theta_\text{B} \\
E = K_\text{H} \Delta \theta_\text{B}^2 +
K_\text{B} (\Delta \theta - \Delta \theta_\text{B}), \qquad |\Delta
\theta| \geq \Delta \theta_\text{B}
where :math:`\Delta \theta = \theta - \pi` is the bending angle of the nanotube, :math:`K_\text{H}` and :math:`K_\text{B}` are prefactors for the harmonic and linear regime respectively and :math:`\Delta \theta_\text{B}` is the buckling angle. Note that the usual 1/2 factor for the harmonic potential is included in :math:`K_\text{H}`.
where :math:`\Delta \theta = \theta - \pi` is the bending angle of the
nanotube, :math:`K_\text{H}` and :math:`K_\text{B}` are prefactors for
the harmonic and linear regime respectively and :math:`\Delta
\theta_\text{B}` is the buckling angle. Note that the usual 1/2 factor
for the harmonic potential is included in :math:`K_\text{H}`.
The style implements parametrisation presets of :math:`K_\text{H}`, :math:`K_\text{B}` and :math:`\Delta \theta_\text{B}` for mesoscopic simulations of
carbon nanotubes based on the atomistic simulations of :ref:`(Srivastava) <Srivastava_2>` and buckling considerations of :ref:`(Zhigilei) <Zhigilei1_1>`.
The style implements parametrisation presets of :math:`K_\text{H}`,
:math:`K_\text{B}` and :math:`\Delta \theta_\text{B}` for mesoscopic
simulations of carbon nanotubes based on the atomistic simulations of
:ref:`(Srivastava) <Srivastava_2>` and buckling considerations of
:ref:`(Zhigilei) <Zhigilei1_1>`.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the examples above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
:doc:`angle_coeff <angle_coeff>` command as in the examples above, or
in the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* mode = *buckling* or *harmonic*
* preset = *C* or *custom*
* additional parameters depending on preset
If mode *harmonic* is chosen, the potential is simply harmonic and does not switch to the linear term when the buckling angle is reached. In *buckling* mode, the full piecewise potential is used.
If mode *harmonic* is chosen, the potential is simply harmonic and
does not switch to the linear term when the buckling angle is
reached. In *buckling* mode, the full piecewise potential is used.
Preset *C* is for carbon nanotubes, and the additional parameters are:
@ -53,13 +65,15 @@ Preset *C* is for carbon nanotubes, and the additional parameters are:
* chiral index :math:`m` (unitless)
* :math:`r_0` (distance)
Here, :math:`r_0` is the equilibrium distance of the bonds included in the angle, see :doc:`bond_style mesocnt <bond_mesocnt>`.
Here, :math:`r_0` is the equilibrium distance of the bonds included in
the angle, see :doc:`bond_style mesocnt <bond_mesocnt>`.
In harmonic mode with preset *custom*, the additional paramter is:
* :math:`K_\text{H}` (energy)
Hence, this setting is simply a wrapper for :doc:`bond_style harmonic <bond_harmonic>` with an equilibrium angle of 180 degrees.
Hence, this setting is simply a wrapper for :doc:`bond_style harmonic
<bond_harmonic>` with an equilibrium angle of 180 degrees.
In harmonic mode with preset *custom*, the additional paramters are:
@ -67,19 +81,29 @@ In harmonic mode with preset *custom*, the additional paramters are:
* :math:`K_\text{B}` (energy)
* :math:`\Delta \theta_\text{B}` (degrees)
:math:`\Delta \theta_\text{B}` is specified in degrees, but LAMMPS converts it to
radians internally; hence :math:`K_\text{H}` is effectively energy per
radian\^2 and :math:`K_\text{B}` is energy per radian.
:math:`\Delta \theta_\text{B}` is specified in degrees, but LAMMPS
converts it to radians internally; hence :math:`K_\text{H}` is
effectively energy per radian\^2 and :math:`K_\text{B}` is energy per
radian.
----------
In *buckling* mode, this angle style adds the *buckled* property to all atoms in the simulation, which is an integer flag indicating whether the bending angle at a given atom has exceeded :math:`\Delta \theta_\text{B}`. It can be accessed as an atomic variable, e.g. for custom dump commands, as *i_buckled*.
In *buckling* mode, this angle style adds the *buckled* property to
all atoms in the simulation, which is an integer flag indicating
whether the bending angle at a given atom has exceeded :math:`\Delta
\theta_\text{B}`. It can be accessed as an atomic variable, e.g. for
custom dump commands, as *i_buckled*.
.. note::
If the initial state of the simulation contains buckled nanotubes and :doc:`pair_style mesocnt <pair_mesocnt>` is used, the *i_buckled* atomic variable needs to be initialized before the pair_style is defined by doing a *run 0* command straight after the angle_style command. See below for an example.
If the initial state of the simulation contains buckled nanotubes
and :doc:`pair_style mesocnt <pair_mesocnt>` is used, the
*i_buckled* atomic variable needs to be initialized before the
pair_style is defined by doing a *run 0* command straight after the
angle_style command. See below for an example.
If CNTs are already buckled at the start of the simulation, this script will correctly initialize *i_buckled*:
If CNTs are already buckled at the start of the simulation, this
script will correctly initialize *i_buckled*:
.. code-block:: LAMMPS
@ -95,8 +119,8 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE and MESONT packages. See the :doc:`Build package <Build_package>` doc
page for more info.
MOLECULE and MESONT packages. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""
@ -112,7 +136,8 @@ none
.. _Srivastava_2:
**(Srivastava)** Zhigilei, Wei, Srivastava, Phys. Rev. B 71, 165417 (2005).
**(Srivastava)** Zhigilei, Wei, Srivastava, Phys. Rev. B 71, 165417
(2005).
.. _Zhigilei1_1:

26
doc/src/bond_mesocnt.rst
View File

@ -22,23 +22,25 @@ Examples
Description
"""""""""""
The *mesocnt* bond style is a wrapper for the :doc:`harmonic <bond_harmonic>` style, and uses the potential
The *mesocnt* bond style is a wrapper for the :doc:`harmonic
<bond_harmonic>` style, and uses the potential
.. math::
E = K (r - r_0)^2
where :math:`r_0` is the equilibrium bond distance. Note that the usual 1/2
factor is included in :math:`K`.
The style implements parametrisation presets of :math:`K` for mesoscopic simulations of
carbon nanotubes based on the atomistic simulations of :ref:`(Srivastava) <Srivastava_1>`.
where :math:`r_0` is the equilibrium bond distance. Note that the
usual 1/2 factor is included in :math:`K`. The style implements
parametrisation presets of :math:`K` for mesoscopic simulations of
carbon nanotubes based on the atomistic simulations of
:ref:`(Srivastava) <Srivastava_1>`.
Other presets can be readily implemented in the future.
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:
the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* preset = *C* or *custom*
* additional parameters depending on preset
@ -49,7 +51,8 @@ Preset *C* is for carbon nanotubes, and the additional parameters are:
* chiral index :math:`m` (unitless)
* :math:`r_0` (distance)
Preset *custom* is simply a direct wrapper for the :doc:`harmonic <bond_harmonic>` style, and the additional parameters are:
Preset *custom* is simply a direct wrapper for the :doc:`harmonic
<bond_harmonic>` style, and the additional parameters are:
* :math:`K` (energy/distance\^2)
* :math:`r_0` (distance)
@ -58,8 +61,8 @@ Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the MOLECULE
and MESONT packages. See the :doc:`Build package <Build_package>` page for more
info.
and MESONT packages. See the :doc:`Build package <Build_package>`
page for more info.
Related commands
""""""""""""""""
@ -75,4 +78,5 @@ none
.. _Srivastava_1:
**(Srivastava)** Zhigilei, Wei and Srivastava, Phys. Rev. B 71, 165417 (2005).
**(Srivastava)** Zhigilei, Wei and Srivastava, Phys. Rev. B 71, 165417
(2005).

171
doc/src/pair_mesocnt.rst
View File

@ -33,60 +33,84 @@ Examples
Description
"""""""""""
Style *mesocnt* implements a mesoscopic potential
for the interaction of carbon nanotubes (CNTs), or other
quasi-1D objects such as other kinds of nanotubes or nanowires. In this potential,
CNTs are modelled as chains of cylindrical segments in which
each infinitesimal surface element interacts with all other
CNT surface elements with the Lennard-Jones (LJ) term adopted from
the :doc:`airebo <pair_airebo>` style. The interaction energy
is then computed by integrating over the surfaces of all interacting
CNTs.
Style *mesocnt* implements a mesoscopic potential for the interaction
of carbon nanotubes (CNTs), or other quasi-1D objects such as other
kinds of nanotubes or nanowires. In this potential, CNTs are modelled
as chains of cylindrical segments in which each infinitesimal surface
element interacts with all other CNT surface elements with the
Lennard-Jones (LJ) term adopted from the :doc:`airebo <pair_airebo>`
style. The interaction energy is then computed by integrating over the
surfaces of all interacting CNTs.
In LAMMPS, cylindrical segments are represented by bonds. Each
segment is defined by its two end points ("nodes") which correspond
to atoms in LAMMPS. For the exact functional form of the potential
and implementation details, the reader is referred to the
original papers :ref:`(Volkov1) <Volkov1>` and
:ref:`(Volkov2) <Volkov2>`.
In LAMMPS, cylindrical segments are represented by bonds. Each segment
is defined by its two end points ("nodes") which correspond to atoms
in LAMMPS. For the exact functional form of the potential and
implementation details, the reader is referred to the original papers
:ref:`(Volkov1) <Volkov1>` and :ref:`(Volkov2) <Volkov2>`.
The potential supports two modes, *segment* and *chain*. By default, *chain* mode is enabled.
In *segment* mode, interactions are pair-wise between all neighboring segments based on a segment-segment approach (keyword *segment* in pair_style command).
In *chain* mode, interactions are calculated between each segment and infinitely or
The potential supports two modes, *segment* and *chain*. By default,
*chain* mode is enabled. In *segment* mode, interactions are
pair-wise between all neighboring segments based on a segment-segment
approach (keyword *segment* in pair_style command). In *chain* mode,
interactions are calculated between each segment and infinitely or
semi-infinitely long CNTs as described in :ref:`(Volkov1) <Volkov1>`.
Chains of segments are converted to these (semi-)infinite CNTs bases on an approximate
chain approach outlined in :ref:`(Volkov2) <Volkov2>`. Hence, interactions are calculated on a
segment-chain basis (keyword *chain* in the pair_style command).
Using *chain* mode allows to simplify the computation of the interactions
significantly and reduces the computational times to the
same order of magnitude as for regular bead spring models
where beads interact with the standard :doc:`pair_lj/cut <pair_lj>`
potential. However, this method is only valid when the curvature of the CNTs in the system is small.
When CNTs are buckled (see :doc:`angle_mesocnt <angle_mesocnt>`), local curvature can be very high and the pair_style automatically switches to *segment* mode for interactions involving buckled CNTs.
Chains of segments are converted to these (semi-)infinite CNTs bases
on an approximate chain approach outlined in :ref:`(Volkov2)
<Volkov2>`. Hence, interactions are calculated on a segment-chain
basis (keyword *chain* in the pair_style command). Using *chain* mode
allows to simplify the computation of the interactions significantly
and reduces the computational times to the same order of magnitude as
for regular bead spring models where beads interact with the standard
:doc:`pair_lj/cut <pair_lj>` potential. However, this method is only
valid when the curvature of the CNTs in the system is small. When
CNTs are buckled (see :doc:`angle_mesocnt <angle_mesocnt>`), local
curvature can be very high and the pair_style automatically switches
to *segment* mode for interactions involving buckled CNTs.
The potential further implements two different neighbor list construction modes. Mode *id* uses atom and mol IDs to construct neighbor lists while *topology* modes uses only the bond topology of the system. While *id* mode requires bonded atoms to have consecutive LAMMPS atom IDs and atoms in different CNTs to have different LAMMPS molecule IDs, *topology* mode has no such requirement. Using *id* mode is faster and is enabled by default.
The potential further implements two different neighbor list
construction modes. Mode *id* uses atom and mol IDs to construct
neighbor lists while *topology* modes uses only the bond topology of
the system. While *id* mode requires bonded atoms to have consecutive
LAMMPS atom IDs and atoms in different CNTs to have different LAMMPS
molecule IDs, *topology* mode has no such requirement. Using *id* mode
is faster and is enabled by default.
.. note::
Neighbor *id* mode requires all CNTs in the system to have distinct LAMMPS molecule IDs and bonded atoms to have consecutive LAMMPS atom IDs. If this is not possible (e.g. in simulations of CNT rings),
Neighbor *id* mode requires all CNTs in the system to have distinct
LAMMPS molecule IDs and bonded atoms to have consecutive LAMMPS atom
IDs. If this is not possible (e.g. in simulations of CNT rings),
*topology* mode needs to be enabled in the pair_style command.
In addition to the LJ interactions described above, style *mesocnt/viscous* explicitly models friction between neighboring segments. Friction forces are a function of the relative velocity between a segment and its neighboring approximate chain (even in *segment* mode) and only act along the axes of the interacting segment and chain. In this potential, friction forces are modelled as a shifted logistic function:
In addition to the LJ interactions described above, style
*mesocnt/viscous* explicitly models friction between neighboring
segments. Friction forces are a function of the relative velocity
between a segment and its neighboring approximate chain (even in
*segment* mode) and only act along the axes of the interacting segment
and chain. In this potential, friction forces are modelled as a
shifted logistic function:
.. math::
F^{\text{FRICTION}}(v) = \frac{F^{\text{max}}}{1 + \exp(-k(v-v_0))} - \frac{F^{\text{max}}}{1 + \exp(k v_0)}
F^{\text{FRICTION}}(v) = \frac{F^{\text{max}}}{1 +
\exp(-k(v-v_0))} - \frac{F^{\text{max}}}{1 + \exp(k v_0)}
----------
In the pair_style command, the modes described above can be toggeled using the *segment* or *chain* keywords.
The neighbor list cutoff defines the cutoff within which atoms are included in the neighbor list for constructing neighboring CNT chains.
This is different from the potential cutoff, which is directly calculated from parameters specified in the potential file. We recommend using a neighbor list cutoff of at least 3 times the maximum segment length used in the simulation to ensure proper neighbor chain construction.
In the pair_style command, the modes described above can be toggeled
using the *segment* or *chain* keywords. The neighbor list cutoff
defines the cutoff within which atoms are included in the neighbor
list for constructing neighboring CNT chains. This is different from
the potential cutoff, which is directly calculated from parameters
specified in the potential file. We recommend using a neighbor list
cutoff of at least 3 times the maximum segment length used in the
simulation to ensure proper neighbor chain construction.
.. note::
CNT ends are treated differently by all *mesocnt* styles. Atoms on CNT ends need to be
assigned different LAMMPS atom types than atoms not on CNT ends.
CNT ends are treated differently by all *mesocnt* styles. Atoms on
CNT ends need to be assigned different LAMMPS atom types than atoms
not on CNT ends.
Style *mesocnt* requires tabulated data provided in a single ASCII
text file, as well as a list of integers corresponding to all LAMMPS
@ -95,13 +119,18 @@ atom types representing CNT ends:
* filename
* :math:`N` CNT end atom types
For example, if your LAMMPS simulation of (10, 10) nanotubes has 4 atom types where atom types 1 and 3 are assigned to 'inner' nodes and atom types 2 and 4 are assigned to CNT end nodes, the pair_coeff command would be:
For example, if your LAMMPS simulation of (10, 10) nanotubes has 4
atom types where atom types 1 and 3 are assigned to 'inner' nodes and
atom types 2 and 4 are assigned to CNT end nodes, the pair_coeff
command would be:
.. code-block:: LAMMPS
pair_coeff * * C_10_10.mesocnt 2 4
Likewise, style *mesocnt/viscous* also requires the same information as style *mesocnt*, with the addition of 3 parameters for the viscous friction forces as listed above:
Likewise, style *mesocnt/viscous* also requires the same information
as style *mesocnt*, with the addition of 3 parameters for the viscous
friction forces as listed above:
* filename
* :math:`F^{\text{max}}`
@ -109,7 +138,8 @@ Likewise, style *mesocnt/viscous* also requires the same information as style *m
* :math:`v_0`
* :math:`N` CNT end atom types
Using the same example system as with style *mesocnt* with the addition of friction, the pair_coeff command is:
Using the same example system as with style *mesocnt* with the
addition of friction, the pair_coeff command is:
.. code-block:: LAMMPS
@ -122,29 +152,30 @@ available code provided on
https://github.com/phankl/cntpot
Using the same approach, it should also be possible to
generate potential files for other 1D systems mentioned above.
Using the same approach, it should also be possible to generate
potential files for other 1D systems mentioned above.
.. note::
Because of their size, *mesocnt* style potential files
are not bundled with LAMMPS. When compiling LAMMPS from
source code, the file ``C_10_10.mesocnt`` should be downloaded
separately from `https://download.lammps.org/potentials/C_10_10.mesocnt <https://download.lammps.org/potentials/C_10_10.mesocnt>`_
Because of their size, *mesocnt* style potential files are not
bundled with LAMMPS. When compiling LAMMPS from source code, the
file ``C_10_10.mesocnt`` should be downloaded separately from
`https://download.lammps.org/potentials/C_10_10.mesocnt
<https://download.lammps.org/potentials/C_10_10.mesocnt>`_
The first line of the potential file provides a time stamp and
general information. The second line lists four integers giving
the number of data points provided in the subsequent four
data tables. The third line lists four floating point numbers:
the CNT radius R, the LJ parameter sigma and two numerical
parameters delta1 and delta2. These four parameters are given
in Angstroms. This is followed by four data tables each separated
by a single empty line. The first two tables have two columns
and list the parameters uInfParallel and Gamma respectively.
The last two tables have three columns giving data on a quadratic
array and list the parameters Phi and uSemiParallel respectively.
uInfParallel and uSemiParallel are given in eV/Angstrom, Phi is
given in eV and Gamma is unitless.
general information. The second line lists four integers giving the
number of data points provided in the subsequent four data
tables. The third line lists four floating point numbers: the CNT
radius R, the LJ parameter sigma and two numerical parameters
delta1 and delta2. These four parameters are given in
Angstroms. This is followed by four data tables each separated by a
single empty line. The first two tables have two columns and list
the parameters uInfParallel and Gamma respectively. The last two
tables have three columns giving data on a quadratic array and list
the parameters Phi and uSemiParallel respectively. uInfParallel
and uSemiParallel are given in eV/Angstrom, Phi is given in eV and
Gamma is unitless.
----------
@ -153,13 +184,13 @@ Mixing, shift, table, tail correction, restart, rRESPA info
These pair styles does not support mixing.
These pair styles does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
These pair styles does not support the :doc:`pair_modify
<pair_modify>` shift, table, and tail options.
These pair styles do not write their information to :doc:`binary restart files <restart>`,
since it is stored in tabulated potential files.
Thus, you need to re-specify the pair_style and pair_coeff commands in
an input script that reads a restart file.
These pair styles do not write their information to :doc:`binary
restart files <restart>`, since it is stored in tabulated potential
files. Thus, you need to re-specify the pair_style and pair_coeff
commands in an input script that reads a restart file.
These pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. They do not support the
@ -170,16 +201,20 @@ These pair styles can only be used via the *pair* keyword of the
Restrictions
""""""""""""
These styles are part of the MESONT package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
These styles are part of the MESONT package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
These pair styles require the :doc:`newton <newton>` setting to be
"on" for pair interactions.
These pair styles require all 3 :doc:`special_bonds lj <special_bonds>` settings to be non-zero for proper neighbor list construction.
These pair styles require all 3 :doc:`special_bonds lj
<special_bonds>` settings to be non-zero for proper neighbor list
construction.
Pair style *mesocnt/viscous* requires you to use the :doc:`comm_modify vel yes
<comm_modify>` command so that velocities are stored by ghost atoms.
Pair style *mesocnt/viscous* requires you to use the :doc:`comm_modify
vel yes <comm_modify>` command so that velocities are stored by ghost
atoms.
Related commands
""""""""""""""""