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

Merge branch 'develop' into always-exceptions

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-06-22 10:53:36 -04:00
parent e1df51969d c5d9f901d9
commit fc365d3d5f
561 changed files with 26484 additions and 14127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/CODEOWNERS vendored
View File

@ -67,6 +67,7 @@ src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps
src/MISC/*_tracker.* @jtclemm
src/MC/fix_gcmc.* @athomps
src/MC/fix_sgcmc.* @athomps
src/REPLICA/fix_pimd_langevin.* @Yi-FanLi
# core LAMMPS classes
src/lammps.* @sjplimp

26
bench/in.chain
View File

@ -1,25 +1,25 @@
# FENE beadspring benchmark
units lj
atom_style bond
units lj
atom_style bond
special_bonds fene
read_data data.chain
read_data data.chain
neighbor 0.4 bin
neigh_modify every 1 delay 1
neighbor 0.4 bin
neigh_modify every 1 delay 1
bond_style fene
bond_coeff 1 30.0 1.5 1.0 1.0
bond_coeff 1 30.0 1.5 1.0 1.0
pair_style lj/cut 1.12
pair_modify shift yes
pair_coeff 1 1 1.0 1.0 1.12
pair_style lj/cut 1.12
pair_modify shift yes
pair_coeff 1 1 1.0 1.0 1.12
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
thermo 100
timestep 0.012
timestep 0.012
run 100
run 100

36
bench/in.chain.scaled
View File

@ -1,32 +1,32 @@
# FENE beadspring benchmark
variable x index 1
variable y index 1
variable z index 1
variable x index 1
variable y index 1
variable z index 1
units lj
atom_style bond
atom_modify map hash
units lj
atom_style bond
atom_modify map hash
special_bonds fene
read_data data.chain
read_data data.chain
replicate $x $y $z
replicate $x $y $z
neighbor 0.4 bin
neigh_modify every 1 delay 1
neighbor 0.4 bin
neigh_modify every 1 delay 1
bond_style fene
bond_coeff 1 30.0 1.5 1.0 1.0
bond_coeff 1 30.0 1.5 1.0 1.0
pair_style lj/cut 1.12
pair_modify shift yes
pair_coeff 1 1 1.0 1.0 1.12
pair_style lj/cut 1.12
pair_modify shift yes
pair_coeff 1 1 1.0 1.0 1.12
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
fix 1 all nve
fix 2 all langevin 1.0 1.0 10.0 904297
thermo 100
timestep 0.012
timestep 0.012
run 100
run 100

44
bench/in.chute
View File

@ -1,33 +1,33 @@
# LAMMPS benchmark of granular flow
# chute flow of 32000 atoms with frozen base at 26 degrees
units lj
atom_style sphere
boundary p p fs
newton off
comm_modify vel yes
units lj
atom_style sphere
boundary p p fs
newton off
comm_modify vel yes
read_data data.chute
read_data data.chute
pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
pair_coeff * *
pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
pair_coeff * *
neighbor 0.1 bin
neigh_modify every 1 delay 0
neighbor 0.1 bin
neigh_modify every 1 delay 0
timestep 0.0001
timestep 0.0001
group bottom type 2
group active subtract all bottom
neigh_modify exclude group bottom bottom
group bottom type 2
group active subtract all bottom
neigh_modify exclude group bottom bottom
fix 1 all gravity 1.0 chute 26.0
fix 2 bottom freeze
fix 3 active nve/sphere
fix 1 all gravity 1.0 chute 26.0
fix 2 bottom freeze
fix 3 active nve/sphere
compute 1 all erotate/sphere
thermo_style custom step atoms ke c_1 vol
thermo_modify norm no
thermo 100
compute 1 all erotate/sphere
thermo_style custom step atoms ke c_1 vol
thermo_modify norm no
thermo 100
run 100
run 100

50
bench/in.chute.scaled
View File

@ -1,38 +1,38 @@
# LAMMPS benchmark of granular flow
# chute flow of 32000 atoms with frozen base at 26 degrees
variable x index 1
variable y index 1
variable x index 1
variable y index 1
units lj
atom_style sphere
boundary p p fs
newton off
comm_modify vel yes
units lj
atom_style sphere
boundary p p fs
newton off
comm_modify vel yes
read_data data.chute
read_data data.chute
replicate $x $y 1
replicate $x $y 1
pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
pair_coeff * *
pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
pair_coeff * *
neighbor 0.1 bin
neigh_modify every 1 delay 0
neighbor 0.1 bin
neigh_modify every 1 delay 0
timestep 0.0001
timestep 0.0001
group bottom type 2
group active subtract all bottom
neigh_modify exclude group bottom bottom
group bottom type 2
group active subtract all bottom
neigh_modify exclude group bottom bottom
fix 1 all gravity 1.0 chute 26.0
fix 2 bottom freeze
fix 3 active nve/sphere
fix 1 all gravity 1.0 chute 26.0
fix 2 bottom freeze
fix 3 active nve/sphere
compute 1 all erotate/sphere
thermo_style custom step atoms ke c_1 vol
thermo_modify norm no
thermo 100
compute 1 all erotate/sphere
thermo_style custom step atoms ke c_1 vol
thermo_modify norm no
thermo 100
run 100
run 100

40
bench/in.eam
View File

@ -1,32 +1,32 @@
# bulk Cu lattice
variable x index 1
variable y index 1
variable z index 1
variable x index 1
variable y index 1
variable z index 1
variable xx equal 20*$x
variable yy equal 20*$y
variable zz equal 20*$z
variable xx equal 20*$x
variable yy equal 20*$y
variable zz equal 20*$z
units metal
atom_style atomic
units metal
atom_style atomic
lattice fcc 3.615
region box block 0 ${xx} 0 ${yy} 0 ${zz}
create_box 1 box
create_atoms 1 box
lattice fcc 3.615
region box block 0 ${xx} 0 ${yy} 0 ${zz}
create_box 1 box
create_atoms 1 box
pair_style eam
pair_coeff 1 1 Cu_u3.eam
pair_style eam
pair_coeff 1 1 Cu_u3.eam
velocity all create 1600.0 376847 loop geom
velocity all create 1600.0 376847 loop geom
neighbor 1.0 bin
neighbor 1.0 bin
neigh_modify every 1 delay 5 check yes
fix 1 all nve
fix 1 all nve
timestep 0.005
thermo 50
timestep 0.005
thermo 50
run 100
run 100

40
bench/in.lj
View File

@ -1,30 +1,30 @@
# 3d Lennard-Jones melt
variable x index 1
variable y index 1
variable z index 1
variable x index 1
variable y index 1
variable z index 1
variable xx equal 20*$x
variable yy equal 20*$y
variable zz equal 20*$z
variable xx equal 20*$x
variable yy equal 20*$y
variable zz equal 20*$z
units lj
atom_style atomic
units lj
atom_style atomic
lattice fcc 0.8442
region box block 0 ${xx} 0 ${yy} 0 ${zz}
create_box 1 box
create_atoms 1 box
mass 1 1.0
lattice fcc 0.8442
region box block 0 ${xx} 0 ${yy} 0 ${zz}
create_box 1 box
create_atoms 1 box
mass 1 1.0
velocity all create 1.44 87287 loop geom
velocity all create 1.44 87287 loop geom
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0 2.5
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0 2.5
neighbor 0.3 bin
neigh_modify delay 0 every 20 check no
neighbor 0.3 bin
neigh_modify delay 0 every 20 check no
fix 1 all nve
fix 1 all nve
run 100
run 100

28
bench/in.rhodo
View File

@ -1,27 +1,27 @@
# Rhodopsin model
units real
neigh_modify delay 5 every 1
units real
neigh_modify delay 5 every 1
atom_style full
bond_style harmonic
angle_style charmm
dihedral_style charmm
improper_style harmonic
pair_style lj/charmm/coul/long 8.0 10.0
pair_modify mix arithmetic
kspace_style pppm 1e-4
atom_style full
bond_style harmonic
angle_style charmm
dihedral_style charmm
improper_style harmonic
pair_style lj/charmm/coul/long 8.0 10.0
pair_modify mix arithmetic
kspace_style pppm 1e-4
read_data data.rhodo
fix 1 all shake 0.0001 5 0 m 1.0 a 232
fix 2 all npt temp 300.0 300.0 100.0 &
z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
special_bonds charmm
thermo 50
thermo_style multi
thermo_style multi
timestep 2.0
run 100
run 100

38
bench/in.rhodo.scaled
View File

@ -1,34 +1,34 @@
# Rhodopsin model
variable x index 1
variable y index 1
variable z index 1
variable x index 1
variable y index 1
variable z index 1
units real
neigh_modify delay 5 every 1
units real
neigh_modify delay 5 every 1
atom_style full
atom_modify map hash
bond_style harmonic
angle_style charmm
dihedral_style charmm
improper_style harmonic
pair_style lj/charmm/coul/long 8.0 10.0
pair_modify mix arithmetic
kspace_style pppm 1e-4
atom_style full
atom_modify map hash
bond_style harmonic
angle_style charmm
dihedral_style charmm
improper_style harmonic
pair_style lj/charmm/coul/long 8.0 10.0
pair_modify mix arithmetic
kspace_style pppm 1e-4
read_data data.rhodo
replicate $x $y $z
replicate $x $y $z
fix 1 all shake 0.0001 5 0 m 1.0 a 232
fix 2 all npt temp 300.0 300.0 100.0 &
z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
special_bonds charmm
thermo 50
thermo_style multi
thermo_style multi
timestep 2.0
run 100
run 100

2
cmake/CMakeLists.txt
View File

@ -435,7 +435,7 @@ if(BUILD_OMP)
target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
endif()
if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE)
if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR BUILD_TOOLS)
enable_language(C)
if (NOT USE_INTERNAL_LINALG)
find_package(LAPACK)

4
cmake/Modules/CodingStandard.cmake
View File

@ -5,6 +5,10 @@ if(CMAKE_VERSION VERSION_LESS 3.12)
set(Python3_VERSION ${PYTHON_VERSION_STRING})
endif()
else()
# use default (or custom) Python executable, if version is sufficient
if(Python_VERSION VERSION_GREATER_EQUAL 3.5)
set(Python3_EXECUTABLE ${Python_EXECUTABLE})
endif()
find_package(Python3 COMPONENTS Interpreter QUIET)
endif()

12
cmake/Modules/Documentation.cmake
View File

@ -4,14 +4,18 @@
option(BUILD_DOC "Build LAMMPS HTML documentation" OFF)
if(BUILD_DOC)
# Sphinx 3.x requires at least Python 3.5
# Current Sphinx versions require at least Python 3.8
if(CMAKE_VERSION VERSION_LESS 3.12)
find_package(PythonInterp 3.5 REQUIRED)
find_package(PythonInterp 3.8 REQUIRED)
set(VIRTUALENV ${PYTHON_EXECUTABLE} -m venv)
else()
# use default (or custom) Python executable, if version is sufficient
if(Python_VERSION VERSION_GREATER_EQUAL 3.8)
set(Python3_EXECUTABLE ${Python_EXECUTABLE})
endif()
find_package(Python3 REQUIRED COMPONENTS Interpreter)
if(Python3_VERSION VERSION_LESS 3.5)
message(FATAL_ERROR "Python 3.5 and up is required to build the HTML documentation")
if(Python3_VERSION VERSION_LESS 3.8)
message(FATAL_ERROR "Python 3.8 and up is required to build the HTML documentation")
endif()
set(VIRTUALENV ${Python3_EXECUTABLE} -m venv)
endif()

6
cmake/Modules/Packages/KOKKOS.cmake
View File

@ -49,8 +49,8 @@ if(DOWNLOAD_KOKKOS)
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}")
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
include(ExternalProject)
set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.7.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "f140e02b826223b1045207d9bc10d404" CACHE STRING "MD5 checksum of KOKKOS tarball")
set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.7.02.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "34d7860d548c06a4040236d959c9f99a" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK)
@ -75,7 +75,7 @@ if(DOWNLOAD_KOKKOS)
add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
elseif(EXTERNAL_KOKKOS)
find_package(Kokkos 3.7.01 REQUIRED CONFIG)
find_package(Kokkos 3.7.02 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)

2
cmake/Modules/Tools.cmake
View File

@ -33,6 +33,8 @@ if(BUILD_TOOLS)
endif()
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
add_subdirectory(${LAMMPS_TOOLS_DIR}/phonon ${CMAKE_BINARY_DIR}/phana_build)
endif()
if(BUILD_LAMMPS_SHELL)

4
doc/lammps.1
View File

@ -1,7 +1,7 @@
.TH LAMMPS "1" "28 March 2023" "2023-03-28"
.TH LAMMPS "1" "15 June 2023" "2023-06-15"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator. Version 28 March 2023
\- Molecular Dynamics Simulator. Version 15 June 2023
.SH SYNOPSIS
.B lmp

4
doc/src/Build_make.rst
View File

@ -117,8 +117,8 @@ their settings may become outdated, too:
.. code-block:: bash
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac
make mac # build serial LAMMPS on macOS
make mac_mpi # build parallel LAMMPS on macOS
make intel_cpu # build with the INTEL package optimized for CPUs
make knl # build with the INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs

8
doc/src/Build_manual.rst
View File

@ -53,10 +53,10 @@ incorporates programmer documentation extracted from the LAMMPS C++
sources through the `Doxygen <https://doxygen.nl/>`_ program. Currently
the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers)
and MOBI (for Amazon Kindle readers) are supported. For that to work a
Python 3 interpreter, the ``doxygen`` tools and internet access to
download additional files and tools are required. This download is
usually only required once or after the documentation folder is returned
to a pristine state with ``make clean-all``.
Python interpreter version 3.8 or later, the ``doxygen`` tools and
internet access to download additional files and tools are required.
This download is usually only required once or after the documentation
folder is returned to a pristine state with ``make clean-all``.
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into

7
doc/src/Commands_compute.rst
View File

@ -46,6 +46,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`com/chunk <compute_com_chunk>`
* :doc:`contact/atom <compute_contact_atom>`
* :doc:`coord/atom (k) <compute_coord_atom>`
* :doc:`count/type <compute_count_type>`
* :doc:`damage/atom <compute_damage_atom>`
* :doc:`dihedral <compute_dihedral>`
* :doc:`dihedral/local <compute_dihedral_local>`
@ -152,11 +153,11 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`sph/t/atom <compute_sph_t_atom>`
* :doc:`spin <compute_spin>`
* :doc:`stress/atom <compute_stress_atom>`
* :doc:`stress/cartesian <compute_stress_profile>`
* :doc:`stress/cylinder <compute_stress_profile>`
* :doc:`stress/cartesian <compute_stress_cartesian>`
* :doc:`stress/cylinder <compute_stress_curvilinear>`
* :doc:`stress/mop <compute_stress_mop>`
* :doc:`stress/mop/profile <compute_stress_mop>`
* :doc:`stress/spherical <compute_stress_profile>`
* :doc:`stress/spherical <compute_stress_curvilinear>`
* :doc:`stress/tally <compute_tally>`
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>`
* :doc:`temp (k) <compute_temp>`

1
doc/src/Commands_fix.rst
View File

@ -171,6 +171,7 @@ OPT.
* :doc:`pafi <fix_pafi>`
* :doc:`pair <fix_pair>`
* :doc:`phonon <fix_phonon>`
* :doc:`pimd/langevin <fix_pimd>`
* :doc:`pimd/nvt <fix_pimd>`
* :doc:`planeforce <fix_planeforce>`
* :doc:`plumed <fix_plumed>`

1
doc/src/Commands_pair.rst
View File

@ -37,6 +37,7 @@ OPT.
*
* :doc:`adp (ko) <pair_adp>`
* :doc:`agni (o) <pair_agni>`
* :doc:`aip/water/2dm (t) <pair_aip_water_2dm>`
* :doc:`airebo (io) <pair_airebo>`
* :doc:`airebo/morse (io) <pair_airebo>`
* :doc:`amoeba (g) <pair_amoeba>`

2
doc/src/Commands_removed.rst
View File

@ -41,7 +41,7 @@ warning.
LATTE package
-------------
.. deprecated:: TBD
.. deprecated:: 15Jun2023
The LATTE package with the fix latte command was removed from LAMMPS.
This functionality has been superseded by :doc:`fix mdi/qm <fix_mdi_qm>`

1
doc/src/Developer.rst
View File

@ -13,6 +13,7 @@ of time and requests from the LAMMPS user community.
Developer_org
Developer_code_design
Developer_parallel
Developer_atom
Developer_comm_ops
Developer_flow
Developer_write

88
doc/src/Developer_atom.rst Normal file
View File

@ -0,0 +1,88 @@
Accessing per-atom data
-----------------------
This page discusses how per-atom data is managed in LAMMPS, how it can
be accessed, what communication patters apply, and some of the utility
functions that exist for a variety of purposes.
Owned and ghost atoms
^^^^^^^^^^^^^^^^^^^^^
As described on the :doc:`parallel partitioning algorithms
<Developer_par_part>` page, LAMMPS uses a domain decomposition of the
simulation domain, either in a *brick* or *tiled* manner. Each MPI
process *owns* exactly one subdomain and the atoms within it. To compute
forces for tuples of atoms that are spread across sub-domain boundaries,
also a "halo" of *ghost* atoms are maintained within a the communication
cutoff distance of its subdomain.
The total number of atoms is stored in `Atom::natoms` (within any
typical class this can be referred to at `atom->natoms`. The number of
*owned* (or "local" atoms) are stored in `Atom::nlocal`; the number of
*ghost* atoms is stored in `Atom::nghost`. The sum of `Atom::nlocal`
over all MPI processes should be `Atom::natoms`. This is by default
regularly checked by the Thermo class, and if the sum does not match,
LAMMPS stops with a "lost atoms" error. For convenience also the
property `Atom::nmax` is available, this is the maximum of
`Atom::nlocal + Atom::nghost` across all MPI processes.
Per-atom properties are either managed by the atom style, or individual
classes. or as custom arrays by the individual classes. If only access
to *owned* atoms is needed, they are usually allocated to be of size
`Atom::nlocal`, otherwise of size `Atom::nmax`. Please note that not all
per-atom properties are available or updated on *ghost* atoms. For
example, per-atom velocities are only updated with :doc:`comm_modify vel
yes <comm_modify>`.
Atom indexing
^^^^^^^^^^^^^
When referring to individual atoms, they may be indexed by their local
*index*, their index in their `Atom::x` array. This is densely populated
containing first all *owned* atoms (index < `Atom::nlocal`) and then all
*ghost* atoms. The order of atoms in these arrays can change due to
atoms migrating between between subdomains, atoms being added or
deleted, or atoms being sorted for better cache efficiency. Atoms are
globally uniquely identified by their *atom ID*. There may be multiple
atoms with the same atom ID present, but only one of them may be an
*owned* atom.
To find the local *index* of an atom, when the *atom ID* is known, the
`Atom::map()` function may be used. It will return the local atom index
or -1. If the returned value is between 0 (inclusive) and `Atom::nlocal`
(exclusive) it is an *owned* or "local" atom; for larger values the atom
is present as a ghost atom; for a value of -1, the atom is not present
on the current subdomain at all.
If multiple atoms with the same tag exist in the same subdomain, they
can be found via the `Atom::sametag` array. It points to the next atom
index with the same tag or -1 if there are no more atoms with the same
tag. The list will be exhaustive when starting with an index of an
*owned* atom, since the atom IDs are unique, so there can only be one
such atom. Example code to count atoms with same atom ID in subdomain:
.. code-block:: c++
for (int i = 0; i < atom->nlocal; ++i) {
int count = 0;
while (sametag[i] >= 0) {
i = sametag[i];
++count;
}
printf("Atom ID: %ld is present %d times\n", atom->tag[i], count);
}
Atom class versus AtomVec classes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `Atom` class contains all kinds of flags and counters about atoms in
the system and that includes pointers to **all** per-atom properties
available for atoms. However, only a subset of these pointers are
non-NULL and which those are depends on the atom style. For each atom
style there is a corresponding `AtomVecXXX` class derived from the
`AtomVec` base class, where the XXX indicates the atom style. This
`AtomVecXXX` class will update the counters and per-atom pointers if
atoms are added or removed to the system or migrate between subdomains.

202
doc/src/Fortran.rst
View File

@ -56,17 +56,6 @@ C++ in the ``examples/COUPLE/simple`` folder of the LAMMPS distribution.
and Ubuntu 18.04 LTS and not compatible. Either newer compilers
need to be installed or the Linux updated.
.. versionchanged:: 8Feb2023
.. note::
A contributed Fortran interface is available in the
``examples/COUPLE/fortran2`` folder. However, since the completion
of the :f:mod:`LIBLAMMPS` module, this interface is now deprecated,
no longer actively maintained and will likely be removed in the
future. Please see the ``README`` file in that folder for more
information about it and how to contact its author and maintainer.
----------
Creating or deleting a LAMMPS object
@ -203,40 +192,62 @@ Below is an example demonstrating some of the possible uses.
.. code-block:: fortran
PROGRAM testprop
USE LIBLAMMPS
USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
TYPE(lammps) :: lmp
INTEGER(KIND=c_int64_t), POINTER :: natoms
REAL(KIND=c_double), POINTER :: dt
INTEGER(KIND=c_int64_t), POINTER :: ntimestep
REAL(KIND=c_double) :: pe, ke
PROGRAM testprop
USE LIBLAMMPS
USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
TYPE(lammps) :: lmp
INTEGER(KIND=c_int64_t), POINTER :: natoms, ntimestep, bval
REAL(KIND=c_double), POINTER :: dt, dval
INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
INTEGER(KIND=c_int) :: i
CHARACTER(LEN=11) :: key
REAL(KIND=c_double) :: pe, ke
lmp = lammps()
CALL lmp%file('in.sysinit')
natoms = lmp%extract_global('natoms')
WRITE(OUTPUT_UNIT,'(A,I0,A)') 'Running a simulation with ', natoms, ' atoms'
WRITE(OUTPUT_UNIT,'(I0,A,I0,A,I0,A)') lmp%extract_setting('nlocal'), &
' local and ', lmp%extract_setting('nghost'), ' ghost atoms. ', &
lmp%extract_setting('ntypes'), ' atom types'
lmp = lammps()
CALL lmp%file('in.sysinit')
natoms = lmp%extract_global('natoms')
WRITE(OUTPUT_UNIT,'(A,I0,A)') 'Running a simulation with ', natoms, ' atoms'
WRITE(OUTPUT_UNIT,'(I0,A,I0,A,I0,A)') lmp%extract_setting('nlocal'), &
' local and ', lmp%extract_setting('nghost'), ' ghost atoms. ', &
lmp%extract_setting('ntypes'), ' atom types'
CALL lmp%command('run 2 post no')
dt = lmp%extract_global('dt')
ntimestep = lmp%extract_global('ntimestep')
WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
' Changing timestep from', dt, ' to 0.5'
dt = 0.5_c_double
CALL lmp%command('run 2 post no')
CALL lmp%command('run 2 post no')
WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
pe = lmp%get_thermo('pe')
ke = lmp%get_thermo('ke')
PRINT*, 'PE = ', pe
PRINT*, 'KE = ', ke
ntimestep = lmp%last_thermo('step', 0)
nfield = lmp%last_thermo('num', 0)
WRITE(OUTPUT_UNIT,'(A,I0,A,I0)') 'Last thermo output on step: ', ntimestep, &
', number of fields: ', nfield
DO i=1, nfield
key = lmp%last_thermo('keyword',i)
typ = lmp%last_thermo('type',i)
IF (typ == lmp%dtype%i32) THEN
ival = lmp%last_thermo('data',i)
WRITE(OUTPUT_UNIT,*) key, ':', ival
ELSE IF (typ == lmp%dtype%i64) THEN
bval = lmp%last_thermo('data',i)
WRITE(OUTPUT_UNIT,*) key, ':', bval
ELSE IF (typ == lmp%dtype%r64) THEN
dval = lmp%last_thermo('data',i)
WRITE(OUTPUT_UNIT,*) key, ':', dval
END IF
END DO
CALL lmp%close(.TRUE.)
END PROGRAM testprop
dt = lmp%extract_global('dt')
ntimestep = lmp%extract_global('ntimestep')
WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
' Changing timestep from', dt, ' to 0.5'
dt = 0.5_c_double
CALL lmp%command('run 2 post no')
WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
pe = lmp%get_thermo('pe')
ke = lmp%get_thermo('ke')
WRITE(OUTPUT_UNIT,*) 'PE = ', pe
WRITE(OUTPUT_UNIT,*) 'KE = ', ke
CALL lmp%close(.TRUE.)
END PROGRAM testprop
---------------
@ -262,6 +273,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
:ftype style: type(lammps_style)
:f type: derived type to access lammps type constants
:ftype type: type(lammps_type)
:f dtype: derived type to access lammps data type constants
:ftype dtype: type(lammps_dtype)
:f close: :f:subr:`close`
:ftype close: subroutine
:f subroutine error: :f:subr:`error`
@ -278,6 +291,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
:ftype get_natoms: function
:f get_thermo: :f:func:`get_thermo`
:ftype get_thermo: function
:f last_thermo: :f:func:`last_thermo`
:ftype last_thermo: function
:f extract_box: :f:subr:`extract_box`
:ftype extract_box: subroutine
:f reset_box: :f:subr:`reset_box`
@ -587,6 +602,96 @@ Procedures Bound to the :f:type:`lammps` Derived Type
--------
.. f:function:: last_thermo(what, index)
This function will call :cpp:func:`lammps_last_thermo` and returns
either a string or a pointer to a cached copy of LAMMPS last thermodynamic
output, depending on the data requested through *what*. Note that *index*
uses 1-based indexing to access thermo output columns.
.. versionadded:: 15Jun2023
Note that this function actually does not return a value, but rather
associates the pointer on the left side of the assignment to point to
internal LAMMPS data (with the exception of string data, which are
copied and returned as ordinary Fortran strings). Pointers must be
of the correct data type to point to said data (typically
``INTEGER(c_int)``, ``INTEGER(c_int64_t)``, or ``REAL(c_double)``).
The pointer being associated with LAMMPS data is type-checked at
run-time via an overloaded assignment operator. The pointers
returned by this function point to temporary, read-only data that may
be overwritten at any time, so their target values need to be copied
to local storage if they are supposed to persist.
For example,
.. code-block:: fortran
PROGRAM thermo
USE LIBLAMMPS
USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
TYPE(lammps) :: lmp
INTEGER(KIND=c_int64_t), POINTER :: ntimestep, bval
REAL(KIND=c_double), POINTER :: dval
INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
INTEGER(KIND=c_int) :: i
CHARACTER(LEN=11) :: key
lmp = lammps()
CALL lmp%file('in.sysinit')
ntimestep = lmp%last_thermo('step', 0)
nfield = lmp%last_thermo('num', 0)
PRINT*, 'Last thermo output on step: ', ntimestep, ' Number of fields: ', nfield
DO i=1, nfield
key = lmp%last_thermo('keyword',i)
typ = lmp%last_thermo('type',i)
IF (typ == lmp%dtype%i32) THEN
ival = lmp%last_thermo('data',i)
PRINT*, key, ':', ival
ELSE IF (typ == lmp%dtype%i64) THEN
bval = lmp%last_thermo('data',i)
PRINT*, key, ':', bval
ELSE IF (typ == lmp%dtype%r64) THEN
dval = lmp%last_thermo('data',i)
PRINT*, key, ':', dval
END IF
END DO
CALL lmp%close(.TRUE.)
END PROGRAM thermo
would extract the last timestep where thermo output was done and the number
of columns it printed. Then it loops over the columns to print out column
header keywords and the corresponding data.
.. note::
If :f:func:`last_thermo` returns a string, the string must have a length
greater than or equal to the length of the string (not including the
terminal ``NULL`` character) that LAMMPS returns. If the variable's
length is too short, the string will be truncated. As usual in Fortran,
strings are padded with spaces at the end. If you use an allocatable
string, the string **must be allocated** prior to calling this function.
:p character(len=\*) what: string with the name of the thermo keyword
:p integer(c_int) index: 1-based column index
:to: :cpp:func:`lammps_last_thermo`
:r pointer [polymorphic]: pointer to LAMMPS data. The left-hand side of the
assignment should be either a string (if expecting string data) or a
C-compatible pointer (e.g., ``INTEGER(c_int), POINTER :: nlocal``) to the
extracted property.
.. warning::
Modifying the data in the location pointed to by the returned pointer
may lead to inconsistent internal data and thus may cause failures,
crashes, or bogus simulations. In general, it is much better
to use a LAMMPS input command that sets or changes these parameters.
Using an input command will take care of all side effects and necessary
updates of settings derived from such settings.
--------
.. f:subroutine:: extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag])
This subroutine will call :cpp:func:`lammps_extract_box`. All
@ -764,13 +869,14 @@ Procedures Bound to the :f:type:`lammps` Derived Type
.. note::
If :f:func:`extract_global` returns a string, the string must have length
greater than or equal to the length of the string (not including the
terminal ``NULL`` character) that LAMMPS returns. If the variable's
length is too short, the string will be truncated. As usual in Fortran,
strings are padded with spaces at the end. If you use an allocatable
string, the string **must be allocated** prior to calling this function,
but you can automatically reallocate it to the correct length after the
If :f:func:`extract_global` returns a string, the string must have
a length greater than or equal to the length of the string (not
including the terminal ``NULL`` character) that LAMMPS returns. If
the variable's length is too short, the string will be
truncated. As usual in Fortran, strings are padded with spaces at
the end. If you use an allocatable string, the string **must be
allocated** prior to calling this function, but you can
automatically reallocate it to the correct length after the
function returns, viz.,
.. code-block :: fortran

78
doc/src/Howto_broken_bonds.rst
View File

@ -1,48 +1,56 @@
Broken Bonds
============
Typically, bond interactions persist for the duration of a simulation in
LAMMPS. However, there are some exceptions that allow for bonds to
break, including the :doc:`quartic bond style <bond_quartic>` and the
bond styles in the :doc:`BPM package <Howto_bpm>` which contains the
:doc:`bpm/spring <bond_bpm_spring>` and :doc:`bpm/rotational
<bond_bpm_rotational>` bond styles. In these cases, a bond can be broken
if it is stretched beyond a user-defined threshold. LAMMPS accomplishes
this by setting the bond type to 0, such that the bond force is no
longer computed.
Typically, molecular bond interactions persist for the duration of a
simulation in LAMMPS. However, some commands break bonds dynamically,
including the following:
Users are normally able to weight the contribution of pair forces to atoms
that are bonded using the :doc:`special_bonds command <special_bonds>`.
When bonds break, this is not always the case. For the quartic bond style,
pair forces are always turned off between bonded particles. LAMMPS does
this 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. After the bond breaks, the pairwise interaction between the
two atoms is turned on, since they are no longer bonded.
* :doc:`bond_style quartic <bond_quartic>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`fix bond/react <fix_bond_react>`
* :doc:`BPM package <Howto_bpm>` bond styles
In the BPM package, one can either turn off all pair interactions between
bonded particles or leave them on, overlaying pair forces on top of bond
forces. To remove pair forces, the special bond list is dynamically
updated. More details can be found on the :doc:`Howto BPM <Howto_bpm>`
page.
A bond can break if it is stretched beyond a user-defined threshold or
more generally if other criteria are met.
Bonds can also be broken by fixes which change bond topology, including
:doc:`fix bond/break <fix_bond_break>` and
:doc:`fix bond/react <fix_bond_react>`. These fixes will automatically
trigger a rebuild of the neighbor list and update special bond data structures
when bonds are broken.
For the quartic bond style, when a bond is broken its bond type is set
to 0 to effectively break it and pairwise forces between the two atoms
in the broken bond are "turned on". Angles, dihedrals, etc cannot be
defined for a system when :doc:`bond_style quartic <bond_quartic>` is
used.
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.:
Similarly, bond styles in the BPM package are also incompatible with
angles, dihedrals, etc. and when a bond breaks its type is set to zero.
However, in the BPM package one can either turn off all pair interactions
between bonded particles or leave them on, overlaying pair forces on
top of bond forces. To remove pair forces, the special bond list is
dynamically updated. More details can be found on the :doc:`Howto BPM
<Howto_bpm>` page.
The :doc:`fix bond/break <fix_bond_break>` and :doc:`fix bond/react
<fix_bond_react>` commands allow breaking of bonds within a molecular
topology with may also define angles, dihedrals, etc. These commands
update internal topology data structures to remove broken bonds, as
well as the appropriate angle, dihedral, etc interactions which
include the bond. They also trigger a rebuild of the neighbor list
when this occurs, to turn on the appropriate pairwise forces.
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 be used to query
the status of broken bonds with type = 0 or permanently delete them,
e.g.:
.. code-block:: LAMMPS
delete_bonds all stats
delete_bonds all bond 0 remove
The compute :doc:`nbond/atom <compute_nbond_atom>` can also be used
to tally the current number of bonds per atom, excluding broken bonds.
The compute :doc:`count/type <compute_count_type>` command tallies the
current number of bonds (or angles, etc) for each bond (angle, etc)
type. It also tallies broken bonds with type = 0.
The compute :doc:`nbond/atom <compute_nbond_atom>` command tallies the
current number of bonds each atom is part of, excluding broken bonds
with type = 0.

6
doc/src/Howto_spc.rst
View File

@ -69,15 +69,13 @@ SPC/E with rigid bonds.
timestep 1.0
fix rigid all shake 0.0001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
run 0 post no
reset_timestep 0
velocity all create 300.0 5463576
fix integrate all nvt temp 300.0 300.0 1.0
fix integrate all nvt temp 300.0 300.0 100.0
thermo_style custom step temp press etotal density pe ke
thermo 1000
run 20000 upto
write_data tip4p.data nocoeff
write_data spce.data nocoeff
.. _spce_molecule:
.. code-block::

4
doc/src/Howto_tip3p.rst
View File

@ -128,11 +128,11 @@ TIP3P with rigid bonds.
fix rigid all shake 0.001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
run 0 post no
reset_timestep 0
timestep 1.0
velocity all create 300.0 5463576
fix integrate all nvt temp 300 300 1.0
fix integrate all nvt temp 300 300 100.0
thermo_style custom step temp press etotal pe

13
doc/src/Howto_tip4p.rst
View File

@ -180,17 +180,17 @@ file changed):
fix rigid all shake 0.001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
run 0 post no
reset_timestep 0
timestep 1.0
velocity all create 300.0 5463576
fix integrate all nvt temp 300 300 1.0
fix integrate all nvt temp 300 300 100.0
thermo_style custom step temp press etotal pe
thermo 1000
run 20000
write_data tip3p.data nocoeff
write_data tip4p-implicit.data nocoeff
Below is the code for a LAMMPS input file using the explicit method and
a TIP4P molecule file. Because of using :doc:`fix rigid/nvt/small
@ -203,6 +203,7 @@ rigid/nvt/small can identify rigid bodies by their molecule ID:
units real
atom_style charge
atom_modify map array
region box block -5 5 -5 5 -5 5
create_box 3 box
@ -219,14 +220,14 @@ rigid/nvt/small can identify rigid bodies by their molecule ID:
molecule water tip4p.mol
create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
timestep 0.1
fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
timestep 0.5
fix integrate all rigid/nvt/small molecule temp 300.0 300.0 100.0
velocity all create 300.0 5463576
thermo_style custom step temp press etotal density pe ke
thermo 1000
run 20000
write_data tip4p.data nocoeff
write_data tip4p-explicit.data nocoeff
.. _tip4p_molecule:
.. code-block::

5
doc/src/Howto_tip5p.rst
View File

@ -91,6 +91,7 @@ ID:
units real
atom_style charge
atom_modify map array
region box block -5 5 -5 5 -5 5
create_box 3 box
@ -107,8 +108,8 @@ ID:
molecule water tip5p.mol
create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
timestep 0.20
fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
timestep 0.5
fix integrate all rigid/nvt/small molecule temp 300.0 300.0 100.0
reset_timestep 0
velocity all create 300.0 5463576

12
doc/src/Install_conda.rst
View File

@ -1,13 +1,13 @@
Download an executable for Linux or Mac via Conda
-------------------------------------------------
Download an executable for Linux or macOS via Conda
---------------------------------------------------
Pre-compiled LAMMPS binaries are available for macOS and Linux via the
`Conda <conda_>`_ package management system.
First, one must set up the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS
install:
First, one must set up the Conda package manager on your system. Follow
the instructions to install `Miniconda <mini_conda_install_>`_, then
create a conda environment (named `my-lammps-env` or whatever you
prefer) for your LAMMPS install:
.. code-block:: bash

21
doc/src/Install_mac.rst
View File

@ -1,12 +1,12 @@
Download an executable for Mac
------------------------------
Download an executable for macOS
--------------------------------
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
`Homebrew <homebrew_>`_. (Alternatively, see the installation
instructions for :doc:`downloading an executable via Conda
<Install_conda>`.) The following LAMMPS packages are unavailable at
this time because of additional requirements not yet met: GPU, KOKKOS,
MSCG, MPIIO, POEMS, VORONOI.
LAMMPS can be downloaded, built, and configured for macOS with `Homebrew
<homebrew_>`_. (Alternatively, see the installation instructions for
:doc:`downloading an executable via Conda <Install_conda>`.) The
following LAMMPS packages are unavailable at this time because of
additional requirements not yet met: GPU, KOKKOS, MSCG, MPIIO, POEMS,
VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
@ -15,8 +15,9 @@ the following commands:
brew install lammps
This will install the executables "lammps_serial" and "lammps_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
This will install the executables "lammps_serial" and "lammps_mpi", as
well as the LAMMPS "doc", "potentials", "tools", "bench", and "examples"
directories.
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:

17
doc/src/Install_tarball.rst
View File

@ -2,7 +2,7 @@ Download source and documentation as a tarball
----------------------------------------------
You can download a current LAMMPS tarball from the `download page <download_>`_
of the `LAMMPS website <lws_>`_.
of the `LAMMPS website <lws_>`_ or from GitHub (see below).
.. _download: https://www.lammps.org/download.html
.. _bug: https://www.lammps.org/bug.html
@ -17,21 +17,21 @@ tarball occasionally updated. Feature releases occur every 4 to 8
weeks. The new contents in all feature releases are listed on the `bug
and feature page <bug_>`_ of the LAMMPS homepage.
Both tarballs include LAMMPS documentation (HTML and PDF files)
corresponding to that version.
Tarballs of older LAMMPS versions can also be downloaded from `this page
<older_>`_.
Once you have a tarball, unzip and untar it with the following
Tarballs downloaded from the LAMMPS homepage include the pre-translated
LAMMPS documentation (HTML and PDF files) corresponding to that version.
Once you have a tarball, uncompress and untar it with the following
command:
.. code-block:: bash
tar -xzvf lammps*.tar.gz
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
This will create a LAMMPS directory with the version date in its name,
e.g. lammps-28Mar23.
----------
@ -45,7 +45,8 @@ with the following command, to create a lammps-<version> directory:
unzip lammps*.zip
This version corresponds to the selected LAMMPS feature or stable
release.
release (as indicated by the matching git tag) and will only contain the
source code and no pre-built documentation.
.. _git: https://github.com/lammps/lammps/releases

6
doc/src/Library_properties.rst
View File

@ -5,6 +5,7 @@ This section documents the following functions:
- :cpp:func:`lammps_get_natoms`
- :cpp:func:`lammps_get_thermo`
- :cpp:func:`lammps_last_thermo`
- :cpp:func:`lammps_extract_box`
- :cpp:func:`lammps_reset_box`
- :cpp:func:`lammps_memory_usage`
@ -81,6 +82,11 @@ subdomains and processors.
-----------------------
.. doxygenfunction:: lammps_last_thermo
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_box
:project: progguide

23
doc/src/Modify.rst
View File

@ -1,23 +1,30 @@
Modifying & extending LAMMPS
****************************
LAMMPS is designed in a modular fashion and to be easy to modify or
extend with new functionality. In fact, about 95% of its source code
are optional. The following pages give basic instructions on what
is required when adding new styles of different kinds to LAMMPS.
LAMMPS has a modular design, so that it is easy to modify or extend with
new functionality. In fact, about 95% of its source code is optional.
The following pages give basic instructions on adding new features to
LAMMPS. More in-depth explanations and documentation of individual
functions and classes are given in :doc:`Developer`.
If you add a new feature to LAMMPS and think it will be of general
interest to other users, we encourage you to submit it for inclusion in
LAMMPS as a pull request on our `GitHub site
<https://github.com/lammps/lammps>`_, after reading about :doc:`how to
prepare your code for submission <Modify_contribute>` and :doc:`the
style requirements and recommendations <Modify_style>`.
LAMMPS. This process is explained in the following three pages:
* :doc:`how to prepare and submit your code <Modify_contribute>`
* :doc:`requirements for submissions <Modify_requirements>`
* :doc:`style guidelines <Modify_style>`
A summary description of various types of styles in LAMMPS follows.
A discussion of implementing specific styles from scratch is given
in :doc:`writing new styles <Developer_write>`.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
Modify_requirements
Modify_style
.. toctree::

184
doc/src/Modify_contribute.rst
View File

@ -2,74 +2,59 @@ Submitting new features for inclusion in LAMMPS
===============================================
We encourage LAMMPS users to submit new features they wrote for LAMMPS
to be included into the LAMMPS distribution and thus become easily
accessible to all LAMMPS users. The LAMMPS source code is managed with
git and public development is hosted on `GitHub
<https://github.com/lammps/lammps>`_. You can monitor the repository to
be notified of releases, follow the ongoing development, and comment on
topics of interest to you.
to be included in the LAMMPS distribution and thus become easily
accessible to all LAMMPS users. The LAMMPS source code is managed
with git and public development is hosted on `GitHub
<https://github.com/lammps/lammps>`_. You can monitor the repository
to be notified of releases, follow the ongoing development, and
comment on topics of interest to you.
This section contains general information regarding the preparation
and submission of new features to LAMMPS. If you are new to
development in LAMMPS, we recommend you read one of the tutorials on
developing a new :doc:`pair style <Developer_write_pair>` or :doc:`fix
style <Developer_write_fix>` which provide a friendly introduction to
what LAMMPS development entails and common vocabulary used on this
section.
Communication with the LAMMPS developers
----------------------------------------
For any larger modifications or programming project, you are encouraged
to contact the LAMMPS developers ahead of time in order to discuss
implementation strategies and coding guidelines. That will make it
easier to integrate your contribution and results in less work for
everybody involved. You are also encouraged to search through the list
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
and submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
duplicated by others.
For any larger modifications or programming project, you are
encouraged to contact the LAMMPS developers ahead of time to discuss
implementation strategies. That will make it easier to integrate your
contribution and typically results in less work for everyone involved.
You are also encouraged to search through the list of `open issues on
GitHub <https://github.com/lammps/lammps/issues>`_ and submit a new
issue for a planned feature, to avoid duplicating work (and possibly
being scooped).
For informal communication with the LAMMPS developers you may ask to
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
slack work space is by invitation only. Thus for access, please send an
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
working on. Only discussions related to LAMMPS development are
tolerated in that work space, so this is **NOT** for people that look
For informal communication with the LAMMPS developers, you may ask to
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_.
This slack work space is by invitation only. For access, please send
an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you
are working on. Only discussions related to LAMMPS development are
tolerated in that work space, so this is **NOT** for people looking
for help with compiling, installing, or using LAMMPS. Please post a
message to the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for
those purposes.
Packages versus individual files
--------------------------------
The remainder of this chapter describes how to add new "style" files of
various kinds to LAMMPS. Packages are simply collections of one or more
such new class files which are invoked as a new style within a LAMMPS
input script. In some cases collections of supporting functions or
classes are also included as separate files in a package, especially when
they can be shared between multiple styles. If designed correctly, these
additions typically do not require any changes to the core code of
LAMMPS; they are simply add-on files that are compiled with the rest of
LAMMPS. To make those styles work, you may need some trivial changes to
the core code; an example of a trivial change is making a parent-class
method "virtual" when you derive a new child class from it.
If you think your new feature or package requires some non-trivial
changes in core LAMMPS files, you should communicate with the LAMMPS
developers `on Slack <https://lammps.org/slack.html>`_, `on GitHub
<https://github.com/lammps/lammps/issues>`_, or `via email
<https://www.lammps.org/authors.html>`_, since we may have
recommendations about what changes to do where, or may not want to
include certain changes for some reason and thus you would need to look
for alternatives.
Time and effort required
------------------------
How quickly your contribution will be integrated can vary a lot. It
depends largely on how much effort it will cause the LAMMPS developers
to integrate and test it, how many and what kind of changes to the core
code are required, how quickly you can address them and of how much
interest it is to the larger LAMMPS community. Please see the section
on :doc:`LAMMPS programming style and requirements <Modify_style>` for
instructions, recommendations, and formal requirements. A small,
modular, well written contribution may be integrated within hours, but a
complex change that will require a redesign of some core functionality
in LAMMPS for a clean integration can take many months until it is
considered ready for inclusion (though this is rare).
How quickly your contribution will be integrated can vary widely. It
depends largely on how much effort is required by the LAMMPS
developers to integrate and test it, if any and what kind of changes
to the core code are required, how quickly you can address them, and
how much interest the contribution is to the larger LAMMPS
community. This process can be streamlined by following the
:doc:`requirements <Modify_requirements>` and :doc:`style
guidelines<Modify_style>`. A small, modular, well written
contribution may be integrated within hours, but a complex change that
requires a re-design of a core functionality in LAMMPS can take months
before inclusion (though this is rare).
Submission procedure
@ -78,36 +63,24 @@ Submission procedure
All changes to LAMMPS (including those from LAMMPS developers) are
integrated via pull requests on GitHub and cannot be merged without
passing the automated testing and an approving review by a LAMMPS core
developer. Thus before submitting your contribution, you should first
make certain, that your added or modified code compiles and works
correctly with the latest development version of LAMMPS and contains all
bug fixes from it.
developer. Before submitting your contribution, you should therefore
first ensure that your added or modified code compiles and works
correctly with the latest development version of LAMMPS and contains
all bug fixes from it.
Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
<Howto_github>` page for instructions on how to submit your changes or
new files through a GitHub pull request yourself. If you are unable or
unwilling to submit via GitHub yourself, you may also submit patch files
or full files to the LAMMPS developers and ask them to submit a pull
request on GitHub on your behalf. If this is the case, create a gzipped
tar file of all new or changed files or a corresponding patch file using
'diff -u' or 'diff -c' format and compress it with gzip. Please only
use gzip compression, as this works well and is available on all platforms.
Once you have prepared everything, see the :doc:`LAMMPS GitHub
Tutorial <Howto_github>` page for instructions on how to submit your
changes or new files through a GitHub pull request. If you are unable
or unwilling to submit via GitHub yourself, you may also send patch
files or full files to the `LAMMPS developers
<https://www.lammps.org/authors.html>`_ and ask them to submit a pull
request on GitHub on your behalf. If this is the case, create a
gzipped tar file of all new or changed files or a corresponding patch
file using 'diff -u' or 'diff -c' format and compress it with gzip.
Please only use gzip compression, as this works well and is available
on all platforms. This mode of submission may delay the integration
as it depends more on the LAMMPS developers.
If the new features/files are broadly useful we may add them as core
files to LAMMPS or as part of a :doc:`package <Packages_list>`. All
packages are listed and described on the :doc:`Packages details
<Packages_details>` doc page.
Licensing
---------
Note that by providing us files to release, you agree to make them
open-source, i.e. we can release them under the terms of the GPL
(version 2) with the rest of LAMMPS. And similarly as part of a LGPL
(version 2.1) distribution of LAMMPS that we make available to
developers on request only and with files that are not authorized for
that kind of distribution removed (e.g. interface to FFTW). See the
:doc:`LAMMPS license <Intro_opensource>` page for details.
External contributions
----------------------
@ -115,11 +88,42 @@ External contributions
If you prefer to do so, you can also develop and support your add-on
feature **without** having it included in the LAMMPS distribution, for
example as a download from a website of your own. See the `External
LAMMPS packages and tools <https://www.lammps.org/external.html>`_ page
of the LAMMPS website for examples of groups that do this. We are happy
to advertise your package and website from that page. Simply email the
`developers <https://www.lammps.org/authors.html>`_ with info about your
package and we will post it there. We recommend to name external
packages USER-\<name\> so they can be easily distinguished from bundled
packages that do not have the USER- prefix.
LAMMPS packages and tools <https://www.lammps.org/external.html>`_
page of the LAMMPS website for examples of groups that do this. We
are happy to advertise your package and website from that page.
Simply email the `developers <https://www.lammps.org/authors.html>`_
with info about your package, and we will post it there. We recommend
naming external packages USER-\<name\> so they can be easily
distinguished from packages in the LAMMPS distribution which do not
have the USER- prefix.
Location of files: individual files and packages
------------------------------------------------
We rarely accept new styles in the core src folder. Thus, please
review the list of :doc:`available Packages <Packages_details>` to see
if your contribution should be added to one of them. It should fit
into the general purpose of that package. If it does not fit well, it
may be added to one of the EXTRA- packages or the MISC package.
However, if your project includes many related features that are not
covered by one of the existing packages or is dependent on a library
(bundled or external), it is best to create a new package with its own
directory (with a name like FOO). In addition to your new files, the
directory should contain a README text file containing your name and
contact information and a brief description of what your new package
does.
Changes to core LAMMPS files
--------------------------------
If designed correctly, most additions do not require any changes to
the core code of LAMMPS; they are simply add-on files that are
compiled with the rest of LAMMPS. To make those styles work, you may
need some trivial changes to the core code. An example of a trivial
change is making a parent-class method "virtual" when you derive a new
child class from it. If your features involve more substantive
changes to the core LAMMPS files, it is particularly encouraged that
you communicate with the LAMMPS developers early in development.

85
doc/src/Modify_overview.rst
View File

@ -1,42 +1,44 @@
Overview
========
The best way to add a new feature to LAMMPS is to find a similar feature
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 high-level structure of LAMMPS and its class organization, but
functions (class methods) that do actual computations are mostly written
in C-style code and operate on simple C-style data structures (vectors
and arrays). A high-level overview of the programming style choices in
LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to
figure out what it does. You will need some knowledge of C++ to
understand the high-level structure of LAMMPS and its class
organization. Functions (class methods) that do actual computations
are mostly written in C-style code and operate on simple C-style data
structures (vectors and arrays). A high-level overview of the
programming style choices in LAMMPS is :doc:`given elsewhere
<Developer_code_design>`.
Most of the new features described on the :doc:`Modify <Modify>` doc
page 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 directory and re-building LAMMPS.
page 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 directory 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 should not make the rest of LAMMPS more complex or
cause side-effect bugs.
write. Thus, it should not make the rest of LAMMPS more complex or
cause bugs through unwanted side effects.
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
Here is a concrete example. Suppose you write 2 files
``pair_foo.cpp`` and ``pair_foo.h`` that define a new class
``PairFoo`` which 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:
.. code-block:: LAMMPS
pair_style foo 0.1 3.5
then your pair_foo.h file should be structured as follows:
then your ``pair_foo.h`` file should be structured as follows:
.. code-block:: c++
@ -51,28 +53,27 @@ then your pair_foo.h file should be structured as follows:
#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.
``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 example pair style, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.
As illustrated by this example, many features referred to in the
LAMMPS documentation are called a "style" of a particular command.
The :doc:`Modify page <Modify>` lists all the common styles in LAMMPS,
and discusses 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. Pure functions, which means
functions declared as virtual in the base class header file which are
also set to 0, are functions you **must** implement in your new derived
class to give it the functionality LAMMPS expects. Virtual functions
that are not set to 0 are functions you may override or not. Those
are usually defined with an empty function body.
and discusses the header file for the base class that these styles
derive from. Public variables in that file can be used and set by the
derived classes, and may also be used by the base class. Sometimes
they are also accessed by the rest of LAMMPS. Pure functions, which
means functions declared as virtual in the base class header file and
which are also set to 0, are functions you **must** implement in your
new derived class to give it the functionality LAMMPS expects. Virtual
functions that are not set to 0 are functions you may override or not.
Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also
@ -85,9 +86,9 @@ functionality:
post-processing step. Many computations are more easily and more
quickly done that way.
* Do not try to do anything within the timestepping of a run that is not
parallel. For example do not accumulate a bunch of data on a single
processor and analyze it. You run the risk of seriously degrading
the parallel efficiency this way.
parallel. For example, do not accumulate a bunch of data on a single
processor and analyze it. That would 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.

384
doc/src/Modify_requirements.rst Normal file
View File

@ -0,0 +1,384 @@
Requirements for contributions to LAMMPS
========================================
The following is a summary of the current requirements and
recommendations for including contributed source code or documentation
into the LAMMPS software distribution.
Motivation
----------
The LAMMPS developers are committed to provide a software package that
is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging
since a large part of LAMMPS consists of contributed code from many
different authors who may not be professionally trained programmers or
familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it is necessary to
follow established guidelines when accepting new contributions while
also working at the same time to improve the existing code.
The following requirements and recommendations are provided as a
guide. They indicate which individual requirements are strict, and
which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you
need additional explanations or clarifications, or you need assistance
in implementing the (strict) requirements for your contributions.
Requirements include:
* :ref:`Licensing requirements <ReqLicense>` (strict)
* :ref:`Integration testing <ReqIntegrationTesting>` (strict)
* :ref:`Documentation <ReqDocumentation>` (strict)
* :ref:`Programming language standards <ReqProgrammingStandards>` (strict)
* :ref:`Build system <ReqBuildSystem>` (strict)
* :ref:`Command or style names <ReqNaming>` (strict)
* :ref:`Programming style requirements <ReqProgrammingStyle>` (varied)
* :ref:`Examples <ReqExamples>` (preferred)
* :ref:`Error or warning messages and explanations <ReqErrorMessages>` (preferred)
* :ref:`Citation reminder <ReqCitation>` (optional)
* :ref:`Testing <ReqUnitTesting>` (optional)
.. _ReqLicense:
Licensing requirements (strict)
-------------------------------
Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license conditions.
This is the GNU public license in version 2 (not 3 or later) for the
publicly distributed versions, e.g. on the LAMMPS homepage or on
GitHub. We also have a version of LAMMPS under LGPL 2.1 terms which
is available on request; this will usually be the latest available or
a previous stable version with a few LGPL 2.1 incompatible files
removed. More details are found on the :doc:`LAMMPS open-source
license page <Intro_opensource>`.
Your new source files should have the LAMMPS copyright and GPL notice,
followed by your name and email address at the top, like other
user-contributed LAMMPS source files.
Contributions may be under a different license as long as that license
does not conflict with the aforementioned terms. Contributions that
use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the `src` tree) that are
licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation)
Please note, that this split licensing mode may complicate including
the contribution in binary packages.
.. _ReqIntegrationTesting:
Integration testing (strict)
----------------------------
Where possible we use available continuous integration tools to search
for common programming mistakes, portability limitations, incompatible
formatting, and undesired side effects. Contributed code must pass the
automated tests on GitHub before it can be merged with the LAMMPS
distribution. These tests compile LAMMPS in a variety of environments
and settings and run the bundled unit tests. At the discretion of the
LAMMPS developer managing the pull request, additional tests may be
activated that test for "side effects" on running a collection of
input decks and create consistent results. The translation of the
documentation to HTML and PDF is also tested.
This means that contributed source code **must** compile with the most
current version of LAMMPS with ``-DLAMMPS_BIGBIG`` in addition to the
default setting of ``-DLAMMPS_SMALLBIG``. The code needs to work
correctly in both cases, and also in serial and parallel using MPI.
Some "disruptive" changes may break tests and require updates to the
testing tools or scripts or tests themselves. This is rare. If in
doubt, contact the LAMMPS developer that is assigned to the pull
request.
.. _ReqDocumentation:
Documentation (strict)
----------------------
Contributions that add new styles or commands or augment existing ones
must include the corresponding new or modified documentation in
`ReStructuredText format <rst_>`_ (.rst files in the ``doc/src/``
folder). The documentation should be written in American English and the
.rst file must only use ASCII characters, so it can be cleanly
translated to PDF files (via `sphinx <https://www.sphinx-doc.org>`_ and
PDFLaTeX). Special characters may be included via embedded math
expression typeset in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
When adding new commands, they need to be integrated into the sphinx
documentation system, and the corresponding command tables and lists
updated. When translating the documentation into html files there
should be no warnings. When adding a new package, some lists
describing packages must also be updated as well as a package specific
description added. Likewise, if necessary, some package specific
build instructions should be included.
As appropriate, the text files with the documentation can include
inline mathematical expressions or figures (see ``doc/JPG`` for
examples). Additional PDF files with further details may also be
included; see ``doc/PDF`` for examples. The page should also include
literature citations as appropriate; see the bottom of
``doc/fix_nh.rst`` for examples and the earlier part of the same file
for how to format the cite itself. Citation labels must be unique
across **all** .rst files. The "Restrictions" section of the page
should indicate if your command is only available if LAMMPS is built
with the appropriate package. See other command doc files for
examples of how to do this.
Please run at least "make html" and "make spelling" from within the
doc/src directory, and carefully inspect and proofread the resulting
HTML format doc page before submitting your code. Upon submission of
a pull request, checks for error free completion of the HTML and PDF
build will be performed and also a spell check, a check for correct
anchors and labels, and a check for completeness of references to all
styles in their corresponding tables and lists is run. In case the
spell check reports false positives, they can be added to the file
``doc/utils/sphinx-config/false_positives.txt``
Contributions that add or modify the library interface or "public"
APIs from the C++ code or the Fortran module must include suitable
doxygen comments in the source and corresponding changes to the
documentation sources for the "Programmer Guide" guide section of the
LAMMPS manual.
If your feature requires some more complex steps and explanations to
be used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations of models
that require use of multiple commands.
As a rule-of-thumb, the more clear and self-explanatory you make your
documentation, README files and examples, and the easier you make it
for people to get started, the more likely it is that users will try
out your new feature.
.. _ReqProgrammingStandards:
Programming language standards (strict)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The core of LAMMPS is written in C++11 in a style that can be mostly
described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to
keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improve the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition, a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of :doc:`platform neutral functions
<Developer_platform>` for improved portability are provided.
Contributions with code requiring more recent C++ standards are only
accepted as packages with the post C++11 standard code confined to the
package so that it is optional.
Included Fortran code has to be compatible with the Fortran 2003
standard. Since not all platforms supported by LAMMPS provide good
support for compiling Fortran files, it should be considered to rewrite
these parts as C++ code, if possible and thus allow for a wider adoption
of the contribution. As of January 2023, all previously included
Fortran code for the LAMMPS executable has been replaced by equivalent
C++ code.
Python code must be compatible with Python 3.5 and later. Large parts
of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also
compatible with Python 2.7. Compatibility with Python 2.7 is desirable,
but compatibility with Python 3.5 is **required**.
Compatibility with older programming language standards is very
important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and where LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
.. _ReqBuildSystem:
Build system (strict)
---------------------
LAMMPS currently supports two build systems: one that is based on
:doc:`traditional Makefiles <Build_make>` and one that is based on
:doc:`CMake <Build_cmake>`. Therefore, your contribution must be
compatible with and support both build systems.
For a single pair of header and implementation files that are an
independent feature, it is usually only required to add them to
``src/.gitignore``.
For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages 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 and modifications to ``src/Depend.sh`` to trigger the checks.
See other README and Install.sh files in other directories as
examples.
Similarly, for CMake support, changes may need to be made to
``cmake/CMakeLists.txt``, some of the files in ``cmake/presets``, and
possibly a file with specific instructions needs to be added to
``cmake/Modules/Packages/``. Please check out how this is handled for
existing packages and ask the LAMMPS developers if you need assistance.
.. _ReqNaming:
Command or style names, file names, and keywords (strict)
---------------------------------------------------------
All user-visible command or style names should be all lower case and
should only use letters, numbers, or forward slashes. They should be
descriptive and initialisms should be avoided unless they are well
established (e.g. lj for Lennard-Jones). For a compute style
"some/name" the source files must be called ``compute_some_name.h`` and
``compute_some_name.cpp``. The "include guard" in the header file would
then be ``LMP_COMPUTE_SOME_NAME_H`` and the class name
``ComputeSomeName``.
.. _ReqProgrammingStyle:
Programming style requirements (varied)
---------------------------------------
To maintain source code consistency across contributions from many
people, there are various programming style requirements for
contributions to LAMMPS. Some of these requirements are strict and
must be followed, while others are only preferred and thus may be
skipped. An in-depth discussion of the style guidelines is provided
in the :doc:`programming style doc page <Modify_style>`.
.. _ReqExamples:
Examples (preferred)
--------------------
For many new features, it is preferred that example scripts (simple,
small, fast to complete on 1 CPU) are included that demonstrate the
use of new or extended functionality. These are typically include
under the examples or examples/PACKAGES directory and are further
described on the :doc:`examples page <Examples>`. Guidelines for
input scripts include:
- commands that generate output should be commented out (except when the
output is the sole purpose or the feature, e.g. for a new compute)
- commands like :doc:`log <log>`, :doc:`echo <echo>`, :doc:`package
<package>`, :doc:`processors <processors>`, :doc:`suffix <suffix>` may
**not** be used in the input file (exception: "processors * * 1" or
similar is acceptable when used to avoid unwanted domain decomposition
of empty volumes)
- outside of the log files, no generated output should be included
- custom thermo_style settings may not include output measuring CPU or other
time as it complicates comparisons between different runs
- input files should be named ``in.name``, data files should be named
``data.name`` and log files should be named ``log.version.name.<compiler>.<ncpu>``
- the total file size of all the inputs and outputs should be small
- where possible, potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links
.. _ReqErrorMessages:
Error or warning messages and explanations (preferred)
------------------------------------------------------
.. versionchanged:: 4May2022
Starting with LAMMPS version 4 May 2022, the LAMMPS developers have
agreed on a new policy for error and warning messages.
Previously, all error and warning strings were supposed to be listed in
the class header files with an explanation. Those would then be
regularly "harvested" and transferred to alphabetically sorted lists in
the manual. To avoid excessively long lists and to reduce effort, this
came with a requirement to have rather generic error messages (e.g.
"Illegal ... command"). To identify the specific cause, the name of the
source file and the line number of the error location would be printed,
so that one could look up the cause by reading the source code.
The new policy encourages more specific error messages that ideally
indicate the cause directly, and requiring no further lookup. This is
aided by the `{fmt} library <https://fmt.dev>`_ enabling Error class
methods that take a variable number of arguments and an error text that
will be treated like a {fmt} syntax format string. Error messages should
still preferably be kept to a single line or two lines at most.
For more complex explanations or errors that have multiple possible
reasons, a paragraph should be added to the `Error_details` page with an
error code reference (e.g. ``.. _err0001:``) then the utility function
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
to generate a URL that will directly lead to that paragraph. An error
for missing arguments can be easily generated using the
:cpp:func:`utils::missing_cmd_args()
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
An example for this approach would be the
``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that may have multiple possible reasons which complicates debugging,
and thus require some additional explanation.
The transformation of existing LAMMPS code to this new scheme is
ongoing. Given the size of the LAMMPS code base, it will take a
significant amount of time to complete. For new code, however,
following the new approach is strongly preferred. The expectation is
that the new scheme will make understanding errors easier for LAMMPS
users, developers, and maintainers.
.. _ReqCitation:
Citation reminder (optional)
-----------------------------
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/DIFFRACTION/compute_saed.cpp`` for an example.
A BibTeX format citation is stored in a string variable at the top of
the file, and a single line of code registering this variable is added
to the constructor of the class. When your feature is used, then
LAMMPS (by default) will print the brief info and the DOI in the first
line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions
may be added so long as they are only registered when the
corresponding keyword activating this functionality is used.
With these options, it is possible to have LAMMPS output a specific
citation reminder whenever a user invokes your feature from their
input script. Please note that you should *only* use this for the
*most* relevant paper for a feature and a publication that you or your
group authored. E.g. adding a citation in the source 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
included in the documentation page you provide describing your
contribution. If you are not sure what the best option would be,
please contact the LAMMPS developers for advice.
.. _ReqUnitTesting:
Testing (optional)
------------------
If your contribution contains new utility functions or a supporting
class (i.e. anything that does not depend on a LAMMPS object), new
unit tests should be added to a suitable folder in the ``unittest``
tree. When adding a new LAMMPS style computing forces or selected
fixes, a ``.yaml`` file with a test configuration and reference data
should be added for the styles where a suitable tester program already
exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this
section in the manual <testing>` for more information on how to
enable, run, and expand testing.

588
doc/src/Modify_style.rst
View File

@ -1,351 +1,58 @@
LAMMPS programming style and requirements for contributions
===========================================================
The following is a summary of the current requirements and
recommendations for including contributed source code or documentation
into the LAMMPS software distribution.
Motivation
----------
The LAMMPS developers are committed to providing a software package that
is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging since
a large part of LAMMPS consists of contributed code from many different
authors and not many of them are professionally trained programmers and
familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it becomes a
necessity to be more discriminating with new contributions while also
working at the same time to improve the existing code.
The following requirements and recommendations are provided to help
maintaining or improving that status. Where possible we utilize
available continuous integration tools to search for common programming
mistakes, portability limitations, incompatible formatting, and
undesired side effects. It is indicated which requirements are strict,
and which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you need
additional explanations or clarifications or in case you need assistance
in realizing the (strict) requirements for your contributions.
Licensing requirements (strict)
-------------------------------
Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license
conditions. This is the GNU public license in version 2 (not 3 or later)
for the publicly distributed versions, e.g. on the LAMMPS homepage or on
GitHub. On request we also make a version of LAMMPS available under
LGPL 2.1 terms; this will usually be the latest available or a previous
stable version with a few LGPL 2.1 incompatible files removed. More details
are found on the :doc:`LAMMPS open-source license page <Intro_opensource>`.
Your new source files should have the LAMMPS copyright, GPL notice, and
your name and email address at the top, like other user-contributed
LAMMPS source files.
Contributions may be under a different license as long as that
license does not conflict with the aforementioned terms. Contributions
that use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the `src` tree) that are
licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation)
Please note, that this split licensed mode may complicate including the
contribution in binary packages.
Using pull requests on GitHub (preferred)
-----------------------------------------
All contributions to LAMMPS are processed as pull requests on GitHub
(this also applies to the work of the core LAMMPS developers). A
:doc:`tutorial for submitting pull requests on GitHub <Howto_github>` is
provided. If this is still problematic, contributors may contact any of
the core LAMMPS developers for help or to create a pull request on their
behalf. This latter way of submission may delay the integration as it
depends on the amount of time required to prepare the pull request and
free time available by the LAMMPS developer in question to spend on this
task.
Integration testing (strict)
----------------------------
Contributed code, like all pull requests, must pass the automated
tests on GitHub before it can be merged with the LAMMPS distribution.
These tests compile LAMMPS in a variety of environments and settings and
run the bundled unit tests. At the discretion of the LAMMPS developer
managing the pull request, additional tests may be activated that test
for "side effects" on running a collection of input decks and create
consistent results. Also, the translation of the documentation to HTML
and PDF is tested for.
More specifically, this means that contributed source code **must**
compile with the most current version of LAMMPS with ``-DLAMMPS_BIGBIG``
in addition to the default setting of ``-DLAMMPS_SMALLBIG``. The code
needs to work correctly in both cases and also in serial and parallel
using MPI.
Some "disruptive" changes may break tests and require updates to the
testing tools or scripts or tests themselves. This is rare. If in
doubt, contact the LAMMPS developer that is assigned to the pull request
for further details and explanations and suggestions of what needs to be
done.
Documentation (strict)
----------------------
Contributions that add new styles or commands or augment existing ones
must include the corresponding new or modified documentation in
`ReStructuredText format <rst_>`_ (.rst files in the ``doc/src/``
folder). The documentation shall be written in American English and the
.rst file must use only ASCII characters so it can be cleanly translated
to PDF files (via `sphinx <https://www.sphinx-doc.org>`_ and PDFLaTeX).
Special characters may be included via embedded math expression typeset
in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
When adding new commands, they need to be integrated into the sphinx
documentation system, and the corresponding command tables and lists
updated. When translating the documentation into html files there should
be no warnings. When adding a new package also some lists describing
packages must be updated as well as a package specific description added
and, if necessary, some package specific build instructions included.
As appropriate, the text files with the documentation can include inline
mathematical expression or figures (see ``doc/JPG`` for examples).
Additional PDF files with further details (see ``doc/PDF`` for examples) may
also be included. The page should also include literature citations as
appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and the
earlier part of the same file for how to format the cite itself.
Citation labels must be unique across **all** .rst files. The
"Restrictions" section of the page should indicate if your command is
only available if LAMMPS is built with the appropriate FOO package. See
other package doc files for examples of how to do this.
Please run at least "make html" and "make spelling" and carefully
inspect and proofread the resulting HTML format doc page before
submitting your code. Upon submission of a pull request, checks for
error free completion of the HTML and PDF build will be performed and
also a spell check, a check for correct anchors and labels, and a check
for completeness of references all styles in their corresponding tables
and lists is run. In case the spell check reports false positives they
can be added to the file ``doc/utils/sphinx-config/false_positives.txt``
Contributions that add or modify the library interface or "public" APIs
from the C++ code or the Fortran module must include suitable doxygen
comments in the source and corresponding changes to the documentation
sources for the "Programmer Guide" guide section of the LAMMPS manual.
Examples (preferred)
--------------------
In most cases, it is preferred that example scripts (simple, small, fast
to complete on 1 CPU) are included that demonstrate the use of new or
extended functionality. These are typically under the examples or
examples/PACKAGES directory. A few guidelines for such example input
decks.
- commands that generate output should be commented out (except when the
output is the sole purpose or the feature, e.g. for a new compute).
- commands like :doc:`log <log>`, :doc:`echo <echo>`, :doc:`package
<package>`, :doc:`processors <processors>`, :doc:`suffix <suffix>` may
**not** be used in the input file (exception: "processors * * 1" or
similar is acceptable when used to avoid unwanted domain decomposition
of empty volumes).
- outside of the log files, no generated output should be included
- custom thermo_style settings may not include output measuring CPU or other time
as that makes comparing the thermo output between different runs more complicated.
- input files should be named ``in.name``, data files should be named
``data.name`` and log files should be named ``log.version.name.<compiler>.<ncpu>``
- the total file size of all the inputs and outputs should be small
- where possible, potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links
Howto document (optional)
-------------------------
If your feature requires some more complex steps and explanations to be
used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations for bundled
examples.
As a general rule-of-thumb, the more clear and self-explanatory you make
your documentation, README files and examples, and the easier you make
it for people to get started, the more likely it is that users will try
out your new feature.
Programming style requirements (varied)
---------------------------------------
The LAMMPS developers aim to employ a consistent programming style and
naming conventions across the entire code base, as this helps with
maintenance, debugging, and understanding the code, both for developers
and users.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp`
may serve as representative examples.
Command or Style names, file names, and keywords (mostly strict)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All user-visible command or style names should be all lower case and
should only use letters, numbers, or forward slashes. They should be
descriptive and initialisms should be avoided unless they are well
established (e.g. lj for Lennard-Jones). For a compute style
"some/name" the source files must be called `compute_some_name.h` and
`compute_some_name.cpp`. The "include guard" would then be
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
Whitespace and permissions (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files
should be added with Unix-style line endings (LF-only). Git will
automatically convert those in both directions when running on Windows;
use dos2unix on Linux machines to convert files. Text files should have
a line ending on the last line.
All files should have 0644 permissions, i.e writable to the user only
and readable by all and no executable permissions. Executable
permissions (0755) should only be on shell scripts or python or similar
scripts for interpreted script languages.
You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try removing the detected
issues.
Indentation and placement of braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS uses 2 characters per indentation level and lines should be
kept within 100 characters wide.
For new files added to the "src" tree, a `clang-format
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
provided under the name `.clang-format`. This file is compatible with
clang-format version 8 and later. With that file present, files can be
reformatted according to the configuration with a command like:
`clang-format -i new-file.cpp`. Ideally, this is done while writing the
code or before a pull request is submitted. Blocks of code where the
reformatting from clang-format yields undesirable output may be
protected with placing a pair `// clang-format off` and `// clang-format
on` comments around that block.
Error or warning messages and explanations (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 4May2022
Starting with LAMMPS version 4 May 2022 the LAMMPS developers have
agreed on a new policy for error and warning messages.
Previously, all error and warning strings were supposed to be listed in
the class header files with an explanation. Those would then be
regularly "harvested" and transferred to alphabetically sorted lists in
the manual. To avoid excessively long lists and to reduce effort, this
came with a requirement to have rather generic error messages (e.g.
"Illegal ... command"). To identify the specific cause, the name of the
source file and the line number of the error location would be printed,
so that one could look up the cause by reading the source code.
The new policy encourages more specific error messages that ideally
indicate the cause directly and no further lookup would be needed.
This is aided by using the `{fmt} library <https://fmt.dev>`_ to convert
the Error class commands so that they take a variable number of arguments
and error text will be treated like a {fmt} syntax format string.
Error messages should still kept to a single line or two lines at the most.
For more complex explanations or errors that have multiple possible
reasons, a paragraph should be added to the `Error_details` page with an
error code reference (e.g. ``.. _err0001:``) then the utility function
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
to generate an URL that will directly lead to that paragraph. An error
for missing arguments can be easily generated using the
:cpp:func:`utils::missing_cmd_args()
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
The transformation of existing LAMMPS code to this new scheme is ongoing
and - given the size of the LAMMPS source code - will take a significant
amount of time until completion. However, for new code following the
new approach is strongly preferred. The expectation is that the new
scheme will make it easier for LAMMPS users, developers, and
maintainers.
An example for this approach would be the
``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that seem difficult to debug for users because they may have
one of multiple possible reasons, and thus require some additional explanations.
Programming language standards (required)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The core of LAMMPS is written in C++11 in a style that can be mostly
described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to
keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improve the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of
:doc:`platform neutral functions <Developer_platform>` for improved
portability are provided.
Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts
of LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also
compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very
important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
Programming conventions (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following is a collection of conventions that should be applied when
writing code for LAMMPS. Following these steps will make it much easier
to integrate your contribution. Please have a look at the existing files
in packages in the src directory for examples. As a demonstration for
how can be adapted to these conventions you may compare the REAXFF
package with the what it looked like when it was called USER-REAXC. If
you are uncertain, please ask.
- system headers or from installed libraries are include with angular
brackets (example: ``#include <vector>``), while local include file
use double quotes (example: ``#include "atom.h"``).
- when including system header files from the C library use the
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
C-style names (``<stdlib.h>`` or ``<string.h>``)
- the order of ``#include`` statements in a file ``some_name.cpp`` that
implements a class ``SomeName`` defined in a header file
LAMMPS programming style
========================
The aim of the LAMMPS developers is to use a consistent programming
style and naming conventions across the entire code base, as this
helps with maintenance, debugging, and understanding the code, both
for developers and users. This page provides a list of standard style
choices used in LAMMPS. Some of these standards are required, while
others are just preferred. Following these conventions will make it
much easier to integrate your contribution. If you are uncertain,
please ask.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and
`utils.cpp` may serve as representative examples.
Include files (varied)
^^^^^^^^^^^^^^^^^^^^^^
- Header files that define a new LAMMPS style (i.e. that have a
``SomeStyle(some/name,SomeName);`` macro in them) should only use
the include file for the base class and otherwise use forward
declarations and pointers; when interfacing to a library use the
PIMPL (pointer to implementation) approach where you have a pointer
to a struct that contains all library specific data (and thus
requires the library header) but use a forward declaration and
define the struct only in the implementation file. This is a
**strict** requirement since this is where type clashes between
packages and hard-to-find bugs have regularly manifested in the
past.
- Header files, especially those defining a "style", should only use
the absolute minimum number of include files and **must not**
contain any ``using`` statements. Typically, that would only be the
header for the base class. Instead, any include statements should
be put in the corresponding implementation files and forward
declarations be used. For implementation files, the "include what
you use" principle should be employed. However, there is the
notable exception that when the ``pointers.h`` header is included
(or one of the base classes derived from it) certain headers will
always be included and thus do not need to be explicitly specified.
These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`,
`utils.h`, `vector`, `fmt/format.h`, `climits`, `cinttypes`. This
also means any such file can assume that `FILE`, `NULL`, and
`INT_MAX` are defined.
- System headers or headers from installed libraries are included with
angular brackets (example: ``#include <vector>``), while local
include files use double quotes (example: ``#include "atom.h"``)
- When including system header files from the C library use the
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
C-style names (``<stdlib.h>`` or ``<string.h>``)
- The order of ``#include`` statements in a file ``some_name.cpp``
that implements a class ``SomeName`` defined in a header file
``some_name.h`` should be as follows:
- ``#include "some_name.h"`` followed by an empty line
@ -353,34 +60,70 @@ you are uncertain, please ask.
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
"modify.h"`` in alphabetical order followed by an empty line
- system header files from the C++ or C standard library followed by
- System header files from the C++ or C standard library followed by
an empty line
- ``using namespace LAMMPS_NS`` or other namespace imports.
Whitespace (preferred)
^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files
should have Unix-style line endings (LF-only). Git will automatically
convert those in both directions when running on Windows; use dos2unix
on Linux machines to convert files to Unix-style line endings. The
last line of text files include a line ending.
You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try to remove the detected
issues.
Placement of braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For new files added to the "src" tree, a `clang-format
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
provided under the name `.clang-format`. This file is compatible with
clang-format version 8 and later. With that file present, files can be
reformatted according to the configuration with a command like:
`clang-format -i new-file.cpp`. Ideally, this is done while writing
the code or before a pull request is submitted. Blocks of code where
the reformatting from clang-format yields hard-to-read or otherwise
undesirable output may be protected with placing a pair `//
clang-format off` and `// clang-format on` comments around that block.
Miscellaneous standards (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- I/O is done via the C-style stdio library and **not** iostreams.
- Do not use so-called "alternative tokens" like ``and``, ``or``,
``not`` and similar, but rather use the corresponding operators
``&&``, ``||``, and ``!``. The alternative tokens are not available
by default on all compilers, and also we want to maintain a consistent
programming style.
by default on all compilers.
- Output to the screen and the logfile should be using the corresponding
FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg`
convenience function where possible.
- Output to the screen and the logfile should use the corresponding
FILE pointers and only be done on MPI rank 0. Use the
:cpp:func:`utils::logmesg` convenience function where possible.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
`C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please
follow the `C++ Core Guideline C.128
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
That means, you should only use `virtual` to declare a new virtual
function, `override` to indicate you are overriding an existing virtual
function, and `final` to prevent any further overriding.
function, `override` to indicate you are overriding an existing
virtual function, and `final` to prevent any further overriding.
- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
- Trivial destructors: Do not write destructors when they are empty
and `default`.
.. code-block:: c++
// don't write destructors for A or B like this
class A : protected Pointers {
public:
A();
@ -394,6 +137,7 @@ you are uncertain, please ask.
};
// instead, let the compiler create the implicit default destructor by not writing it
class A : protected Pointers {
public:
A();
@ -404,37 +148,11 @@ you are uncertain, please ask.
B();
};
- Header files, especially those defining a "style", should only use
the absolute minimum number of include files and **must not** contain
any ``using`` statements. Typically that would be only the header for
the base class. Instead any include statements should be put into the
corresponding implementation files and forward declarations be used.
For implementation files, the "include what you use" principle should
be employed. However, there is the notable exception that when the
``pointers.h`` header is included (or one of the base classes derived
from it) certain headers will always be included and thus do not need
to be explicitly specified.
These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, `utils.h`,
`vector`, `fmt/format.h`, `climits`, `cinttypes`.
This also means any such file can assume that `FILE`, `NULL`, and
`INT_MAX` are defined.
- Header files that define a new LAMMPS style (i.e. that have a
``SomeStyle(some/name,SomeName);`` macro in them) should only use the
include file for the base class and otherwise use forward declarations
and pointers; when interfacing to a library use the PIMPL (pointer
to implementation) approach where you have a pointer to a struct
that contains all library specific data (and thus requires the library
header) but use a forward declaration and define the struct only in
the implementation file. This is a **strict** requirement since this
is where type clashes between packages and hard to find bugs have
regularly manifested in the past.
- Please use clang-format only to reformat files that you have
contributed. For header files containing a ``SomeStyle(keyword,
ClassName)`` macros it is required to have this macro embedded with a
pair of ``// clang-format off``, ``// clang-format on`` comments and
the line must be terminated with a semi-colon (;). Example:
ClassName)`` macros it is required to have this macro embedded with
a pair of ``// clang-format off``, ``// clang-format on`` comments
and the line must be terminated with a semicolon (;). Example:
.. code-block:: c++
@ -447,92 +165,10 @@ you are uncertain, please ask.
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your files
to protect individual sections from being reformatted.
You may also use ``// clang-format on/off`` throughout your files to
protect individual sections from being reformatted.
- We rarely accept new styles in the core src folder. Thus please
review the list of :doc:`available Packages <Packages_details>` to see
if your contribution could be added to be added to one of them. It
should fit into the general purposed of that package. If it does not
fit well, it may be added to one of the EXTRA- packages or the MISC
package.
Contributing a package
----------------------
If your contribution has several related features that are not covered
by one of the existing packages or is dependent on a library (bundled or
external), it is best to make it a package directory with a name like
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.
Build system (strongly preferred)
---------------------------------
LAMMPS currently supports two build systems: one that is based on
:doc:`traditional Makefiles <Build_make>` and one that is based on
:doc:`CMake <Build_cmake>`. Thus your contribution must be compatible
with and support both.
For a single pair of header and implementation files that are an
independent feature, it is usually only required to add them to
`src/.gitignore``.
For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages 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 and
modifications to src/Depend.sh to trigger the checks. See other README
and Install.sh files in other directories as examples.
Similarly for CMake support, changes may need to be made to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a
file with specific instructions needs to be added to
cmake/Modules/Packages/. Please check out how this is handled for
existing packages and ask the LAMMPS developers if you need assistance.
Citation reminder (suggested)
-----------------------------
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/DIFFRACTION/compute_saed.cpp`` for an example.
A BibTeX format citation is stored in a string variable at the top
of the file and a single line of code registering this variable is
added to the constructor of the class. When your feature is used,
by default, LAMMPS will print the brief info and the DOI
in the first line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions
may be added for as long as they are only registered when the
corresponding keyword activating this functionality is used. With these
options it is possible to have LAMMPS output a specific citation
reminder whenever a user invokes your feature from their input script.
Please note that you should *only* use this for the *most* relevant
paper for a feature and a publication that you or your group authored.
E.g. adding a citation 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 latter kind of citation should just be included in the
documentation page you provide describing your contribution. If you are
not sure what the best option would be, please contact the LAMMPS
developers for advice.
Testing (optional)
------------------
If your contribution contains new utility functions or a supporting class
(i.e. anything that does not depend on a LAMMPS object), new unit tests
should be added to a suitable folder in the ``unittest`` tree.
When adding a new LAMMPS style computing forces or selected fixes,
a ``.yaml`` file with a test configuration and reference data should be
added for the styles where a suitable tester program already exists
(e.g. pair styles, bond styles, etc.). Please see
:ref:`this section in the manual <testing>` for more information on
how to enable, run, and expand testing.
- All files should have 0644 permissions, i.e. writable by the user
only and readable by all and no executable permissions. Executable
permissions (0755) should only be for shell scripts or python or
similar scripts for interpreted script languages.

BIN
doc/src/PDF/colvars-refman-lammps.pdf
View File

Binary file not shown.

5
doc/src/Python_properties.rst
View File

@ -53,6 +53,7 @@ against invalid accesses.
* :py:meth:`version() <lammps.lammps.version()>`: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
* :py:meth:`get_thermo() <lammps.lammps.get_thermo()>`: return current value of a thermo keyword
* :py:meth:`last_thermo() <lammps.lammps.last_thermo()>`: return a dictionary of the last thermodynamic output
* :py:meth:`get_natoms() <lammps.lammps.get_natoms()>`: total # of atoms as int
* :py:meth:`reset_box() <lammps.lammps.reset_box()>`: reset the simulation box size
* :py:meth:`extract_setting() <lammps.lammps.extract_setting()>`: return a global setting
@ -60,6 +61,10 @@ against invalid accesses.
* :py:meth:`extract_box() <lammps.lammps.extract_box()>`: extract box info
* :py:meth:`create_atoms() <lammps.lammps.create_atoms()>`: create N atoms with IDs, types, x, v, and image flags
**Properties**:
* :py:attr:`last_thermo_step <lammps.lammps.last_thermo_step>`: the last timestep thermodynamic output was computed
.. tab:: PyLammps/IPyLammps API
In addition to the functions provided by :py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>` objects

10
doc/src/Speed_kokkos.rst
View File

@ -285,6 +285,16 @@ one or more nodes, each with two GPUs:
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
.. note::
The default binsize for :doc:`atom sorting <atom_modify>` on GPUs
is equal to the default CPU neighbor binsize (i.e. 2x smaller than the
default GPU neighbor binsize). When running simple pair-wise
potentials like Lennard Jones on GPUs, using a 2x larger binsize for
atom sorting (equal to the default GPU neighbor binsize) and a more
frequent sorting than default (e.g. sorting every 100 time steps
instead of 1000) may improve performance.
.. code-block:: bash
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff

6
doc/src/Tools.rst
View File

@ -883,9 +883,9 @@ dependencies and redirects the download to the local cache.
phonon tool
------------------------
The phonon subdirectory contains a post-processing tool useful for
analyzing the output of the :doc:`fix phonon <fix_phonon>` command in
the PHONON package.
The phonon subdirectory contains a post-processing tool, *phana*, useful
for analyzing the output of the :doc:`fix phonon <fix_phonon>` command
in the PHONON package.
See the README file for instruction on building the tool and what
library it needs. And see the examples/PACKAGES/phonon directory

7
doc/src/atom_modify.rst
View File

@ -153,6 +153,13 @@ cache locality will be undermined.
order of atoms in a :doc:`dump <dump>` file will also typically change
if sorting is enabled.
.. note::
When running simple pair-wise potentials like Lennard Jones on GPUs
with the KOKKOS package, using a larger binsize (e.g. 2x larger than
default) and a more frequent reordering than default (e.g. every 100
time steps) may improve performance.
Restrictions
""""""""""""

18
doc/src/bond_bpm_rotational.rst
View File

@ -24,14 +24,17 @@ Syntax
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
*overlay/pair* value = none
*overlay/pair* value = *yes* or *no*
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
*break/no*
indicates that bonds should not break during a run
*normalize* value = *yes* or *no*
normalizes normal and shear forces by the reference length
*break* value = *yes* or *no*
indicates whether bonds break during a run
Examples
""""""""
@ -136,16 +139,19 @@ or :doc:`read_restart <read_restart>` commands:
* :math:`\gamma_r` (force*distance/velocity units)
* :math:`\gamma_t` (force*distance/velocity units)
However, the *normalize* option will normalize the radial and shear forces
by :math:`r_0` such that :math:`k_r` and :math:`k_s` are unit less.
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
the *overlay/pair* keyword. These settings require specific
the *overlay/pair* option. These settings require specific
:doc:`special_bonds <special_bonds>` settings described in the
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
.. versionadded:: 28Mar2023
If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
If the *break* option is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
@ -251,7 +257,7 @@ Related commands
Default
"""""""
The option defaults are *smooth* = *yes*
The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
----------

20
doc/src/bond_bpm_spring.rst
View File

@ -24,14 +24,17 @@ Syntax
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
*overlay/pair* value = none
*overlay/pair* value = *yes* or *no*
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
*break/no*
indicates that bonds should not break during a run
*normalize* value = *yes* or *no*
normalizes bond forces by the reference length
*break* value = *yes* or *no*
indicates whether bonds break during a run
Examples
""""""""
@ -66,7 +69,7 @@ particles based on a model described by Clemmer and Robbins
F = k (r - r_0) w
where :math:`k_r` is a stiffness, :math:`r` is the current distance
where :math:`k` is a stiffness, :math:`r` is the current distance
and :math:`r_0` is the initial distance between the two particles, and
:math:`w` is an optional smoothing factor discussed below. Bonds will
break at a strain of :math:`\epsilon_c`. This is done by setting by
@ -102,16 +105,19 @@ the data file or restart files read by the :doc:`read_data
* :math:`\epsilon_c` (unit less)
* :math:`\gamma` (force/velocity units)
However, the *normalize* option will normalize the elastic bond force by
:math:`r_0` such that :math:`k` is unit less.
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
the *overlay/pair* keyword. These settings require specific
the *overlay/pair* option. These settings require specific
:doc:`special_bonds <special_bonds>` settings described in the
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
.. versionadded:: 28Mar2023
If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
If the *break* option is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
@ -206,7 +212,7 @@ Related commands
Default
"""""""
The option defaults are *smooth* = *yes*
The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
----------

14
doc/src/bond_style.rst
View File

@ -32,13 +32,13 @@ 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.
remain in force for the duration of the simulation (unless new bonds
are created or existing bonds break, which is possible in some fixes
and 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.

7
doc/src/compute.rst
View File

@ -200,6 +200,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :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:`count/type <compute_count_type>` - count of atoms or bonds by type
* :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
* :doc:`dihedral <compute_dihedral>` - energy of each dihedral sub-style
* :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral
@ -306,11 +307,11 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`sph/t/atom <compute_sph_t_atom>` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`spin <compute_spin>` - magnetic quantities for a system of atoms having spins
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`stress/cartesian <compute_stress_profile>` - stress tensor in cartesian coordinates
* :doc:`stress/cylinder <compute_stress_profile>` - stress tensor in cylindrical coordinates
* :doc:`stress/cartesian <compute_stress_cartesian>` - stress tensor in cartesian coordinates
* :doc:`stress/cylinder <compute_stress_curvilinear>` - stress tensor in cylindrical coordinates
* :doc:`stress/mop <compute_stress_mop>` - normal components of the local stress tensor using the method of planes
* :doc:`stress/mop/profile <compute_stress_mop>` - profile of the normal components of the local stress tensor using the method of planes
* :doc:`stress/spherical <compute_stress_profile>` - stress tensor in spherical coordinates
* :doc:`stress/spherical <compute_stress_curvilinear>` - stress tensor in spherical coordinates
* :doc:`stress/tally <compute_tally>` - stress between two groups of atoms via the tally callback mechanism
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>` - per-atom chemical concentration of a specified species for each tDPD particle
* :doc:`temp <compute_temp>` - temperature of group of atoms

5
doc/src/compute_bond_local.rst
View File

@ -76,7 +76,10 @@ The value *force* is the magnitude of the force acting between the
pair of atoms in the bond.
The values *fx*, *fy*, and *fz* are the xyz components of
*force* between the pair of atoms in the bond.
*force* between the pair of atoms in the bond. For bond styles that apply
non-central forces, such as :doc:`bond_style bpm/rotational
<bond_bpm_rotational>`, these values only include the :math:`(x,y,z)`
components of the normal force component.
The remaining properties are all computed for motion of the two atoms
relative to the center of mass (COM) velocity of the 2 atoms in the

130
doc/src/compute_count_type.rst Normal file
View File

@ -0,0 +1,130 @@
.. index:: compute count/type
compute count/type command
==========================
Syntax
""""""
.. code-block:: LAMMPS
compute ID group-ID count/type mode
* ID, group-ID are documented in :doc:`compute <compute>` command
* count/type = style name of this compute command
* mode = {atom} or {bond} or {angle} or {dihedral} or {improper}
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all count/type atom
compute 1 flowmols count/type bond
Description
"""""""""""
.. versionadded:: 15Jun2023
Define a computation that counts the current number of atoms for each
atom type. Or the number of bonds (angles, dihedrals, impropers) for
each bond (angle, dihedral, improper) type.
The former can be useful if atoms are added to or deleted from the
system in random ways, e.g. via the :doc:`fix deposit <fix_deposit>`,
:doc:`fix pour <fix_pour>`, or :doc:`fix evaporate <fix_evaporate>`
commands. The latter can be useful in reactive simulations where
molecular bonds are broken or created, as well as angles, dihedrals,
impropers.
Note that for this command, bonds (angles, etc) are the topological
kind enumerated in a data file, initially read by the :doc:`read_data
<read_data>` command or defined by the :doc:`molecule <molecule>`
command. They do not refer to implicit bonds defined on-the-fly by
bond-order or reactive pair styles based on the current conformation
of small clusters of atoms.
These commands can turn off topological bonds (angles, etc) by setting
their bond (angle, etc) types to negative values. This command
includes the turned-off bonds (angles, etc) in the count for each
type:
* :doc:`fix shake <fix_shake>`
* :doc:`delete_bonds <delete_bonds>`
These commands can create and/or break topological bonds (angles,
etc). In the case of breaking, they remove the bond (angle, etc) from
the system, so that they no longer exist (:doc:`bond_style quartic
<bond_quartic>` and :doc:`BPM bond styles <Howto_bpm>` are exceptions,
see the discussion below). Thus they are not included in the counts
for each type:
* :doc:`delete_bonds remove <delete_bonds>`
* :doc:`bond_style quartic <bond_quartic>`
* :doc:`fix bond/react <fix_bond_react>`
* :doc:`fix bond/create <fix_bond_create>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`BPM package <Howto_bpm>` bond styles
----------
If the {mode} setting is {atom} then the count of atoms for each atom
type is tallied. Only atoms in the specified group are counted.
If the {mode} setting is {bond} then the count of bonds for each bond
type is tallied. Only bonds with both atoms in the specified group
are counted.
For {mode} = {bond}, broken bonds with a bond type of zero are also
counted. The :doc:`bond_style quartic <bond_quartic>` and :doc:`BPM
bond styles <Howto_bpm>` break bonds by doing this. See the :doc:`
Howto broken bonds <Howto_broken_bonds>` doc page for more details.
Note that the group setting is ignored for broken bonds; all broken
bonds in the system are counted.
If the {mode} setting is {angle} then the count of angles for each
angle type is tallied. Only angles with all 3 atoms in the specified
group are counted.
If the {mode} setting is {dihedral} then the count of dihedrals for
each dihedral type is tallied. Only dihedrals with all 4 atoms in the
specified group are counted.
If the {mode} setting is {improper} then the count of impropers for
each improper type is tallied. Only impropers with all 4 atoms in the
specified group are counted.
----------
Output info
"""""""""""
This compute calculates a global vector of counts. If the mode is
{atom} or {bond} or {angle} or {dihedral} or {improper}, then the
vector length is the number of atom types or bond types or angle types
or dihedral types or improper types, respectively.
If the mode is {bond} this compute also calculates a global scalar
which is the number of broken bonds with type = 0, as explained above.
These values can be used by any command that uses global scalar or
vector values from a compute as input. See the :doc:`Howto output
<Howto_output>` page for an overview of LAMMPS output options.
The scalar and vector values calculated by this compute are "extensive".
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
none
Default
"""""""
none

12
doc/src/compute_fabric.rst
View File

@ -146,13 +146,13 @@ m to :math:`M` (inclusive). A middle asterisk means all types from m to n
Output info
"""""""""""
This compute calculates a local vector of doubles and a scalar. The vector
stores the unique components of the first requested tensor in the order
:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`
followed by the same components for all subsequent tensors.
This compute calculates a global vector of doubles and a global scalar. The
vector stores the unique components of the first requested tensor in the
order :math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`,
:math:`yz` followed by the same components for all subsequent tensors.
The length of the vector is therefore six times the number of requested
tensors. The scalar output is the number of pairwise interactions included in
the calculation of the fabric tensor.
tensors. The scalar output is the number of pairwise interactions included
in the calculation of the fabric tensor.
Restrictions
""""""""""""

4
doc/src/compute_pair_local.rst
View File

@ -66,7 +66,9 @@ The value *eng* is the interaction energy for the pair of atoms.
The value *force* is the force acting between the pair of atoms, which
is positive for a repulsive force and negative for an attractive
force. The values *fx*, *fy*, and *fz* are the :math:`(x,y,z)` components of
*force* on atom I.
*force* on atom I. For pair styles that apply non-central forces,
such as :doc:`granular pair styles <pair_gran>`, these values only include
the :math:`(x,y,z)` components of the normal force component.
A pair style may define additional pairwise quantities which can be
accessed as *p1* to *pN*, where :math:`N` is defined by the pair style.

123
doc/src/compute_stress_cartesian.rst Normal file
View File

@ -0,0 +1,123 @@
.. index:: compute stress/cartesian
compute stress/cartesian command
==================================
Syntax
""""""
.. code-block:: LAMMPS
compute ID group-ID stress/cartesian args
* ID, group-ID are documented in :doc:`compute <compute>` command
* args = argument specific to the compute style
.. parsed-literal::
*stress/cartesian* args = dim1 bin_width1 dim2 bin_width2 keyword
dim1 = *x* or *y* or *z*
bin_width1 = width of the bin
dim2 = *x* or *y* or *z* or *NULL*
bin_width2 = width of the bin
keyword = *ke* or *pair* or *bond*
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all stress/cartesian x 0.1 NULL 0
compute 1 all stress/cartesian y 0.1 z 0.1
compute 1 all stress/cartesian x 0.1 NULL 0 ke pair
Description
"""""""""""
Compute *stress/cartesian* defines computations that calculate profiles of the
diagonal components of the local stress tensor over one or two Cartesian
dimensions, as described in :ref:`(Ikeshoji)<Ikeshoji2>`. The stress tensor is
split into a kinetic contribution :math:`P^k` and a virial contribution
:math:`P^v`. The sum gives the total stress tensor :math:`P = P^k+P^v`.
This compute obeys momentum balance through fluid interfaces. They use the
Irving--Kirkwood contour, which is the straight line between particle pairs.
.. versionadded:: 15Jun2023
Added support for bond styles
This compute only supports pair and bond (no angle, dihedral, improper,
or kspace) forces. By default, if no extra keywords are specified, all
supported contributions to the stress are included (ke, pair, bond). If any
keywords are specified, then only those components are summed.
Output info
"""""""""""
The output columns for *stress/cartesian* are the position of the
center of the local volume in the first and second dimensions, number
density, :math:`P^k_{xx}`, :math:`P^k_{yy}`, :math:`P^k_{zz}`,
:math:`P^v_{xx}`, :math:`P^v_{yy}`, and :math:`P^v_{zz}`. There are 8
columns when one dimension is specified and 9 columns when two
dimensions are specified. The number of bins (rows) is
:math:`(L_1/b_1)(L_2/b_2)`, where :math:`L_1` and :math:`L_2` are the lengths
of the simulation box in the specified dimensions and :math:`b_1` and
:math:`b_2` are the specified bin widths. When only one dimension is
specified, the number of bins (rows) is :math:`L_1/b_1`.
This array can be output with :doc:`fix ave/time <fix_ave_time>`,
.. code-block:: LAMMPS
compute p all stress/cartesian x 0.1
fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector
The values calculated by this compute are "intensive". The stress
values will be in pressure :doc:`units <units>`. The number density
values are in inverse volume :doc:`units <units>`.
NOTE 1: The local stress does not include any Lennard-Jones tail
corrections to the stress added by the
:doc:`pair_modify tail yes <pair_modify>`
command, since those are contributions to the global system pressure.
NOTE 2: The local stress profiles generated by these computes are
similar to those obtained by the
:doc:`method-of-planes (MOP) <compute_stress_mop>`.
A key difference is that compute
:doc:`stress/mop/profile <compute_stress_mop>`
considers particles crossing a set of planes, while
*stress/cartesian* computes averages for a set of small volumes.
Moreover, this compute computes the diagonal components of the stress
tensor :math:`P_{xx}`, :math:`P_{yy}`, and :math:`P_{zz}`, while
*stress/mop/profile* computes the components
:math:`P_{ix}`, :math:`P_{iy}`, and :math:`P_{iz}`, where :math:`i` is the
direction normal to the plane.
More information on the similarities and differences can be found in
:ref:`(Ikeshoji)<Ikeshoji2>`.
Restrictions
""""""""""""
These computes calculate the stress tensor contributions for pair and bond
forces only (no angle, dihedral, improper, or kspace force).
It requires pairwise force calculations not available for most
many-body pair styles.
These computes are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build
package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`,
:doc:`compute stress/mop/profile <compute_stress_mop>`, :doc:`compute stress/spherical <compute_stress_curvilinear>`,
:doc:`compute stress/cylinder <compute_stress_curvilinear>`
----------
.. _Ikeshoji2:
**(Ikeshoji)** Ikeshoji, Hafskjold, Furuholt, Mol Sim, 29, 101-109, (2003).

63
doc/src/compute_stress_profile.rst → doc/src/compute_stress_curvilinear.rst
View File

@ -1,11 +1,6 @@
.. index:: compute stress/cartesian
.. index:: compute stress/cylinder
.. index:: compute stress/spherical
compute stress/cartesian command
==================================
compute stress/cylinder command
=================================
@ -20,15 +15,11 @@ Syntax
compute ID group-ID style args
* ID, group-ID are documented in :doc:`compute <compute>` command
* style = stress/cartesian or stress/spherical or stress/cylinder
* style = stress/spherical or stress/cylinder
* args = argument specific to the compute style
.. parsed-literal::
*stress/cartesian* args = dim bin_width
dim = *x* or *y* or *z*
bin_width = width of the bin
one or two dim/bin_width pairs may be appended
*stress/cylinder* args = zlo zh Rmax bin_width keyword
zlo = minimum z-boundary for cylinder
zhi = maximum z-boundary for cylinder
@ -46,8 +37,6 @@ Examples
.. code-block:: LAMMPS
compute 1 all stress/cartesian x 0.1
compute 1 all stress/cartesian y 0.25 z 0.1
compute 1 all stress/cylinder -10.0 10.0 15.0 0.25
compute 1 all stress/cylinder -10.0 10.0 15.0 0.25 ke no
compute 1 all stress/spherical 0 0 0 0.1 10
@ -55,41 +44,28 @@ Examples
Description
"""""""""""
Compute *stress/cartesian*, compute *stress/cylinder*, and compute
Compute *stress/cylinder*, and compute
*stress/spherical* define computations that calculate profiles of the
diagonal components of the local stress tensor in the specified
coordinate system. The stress tensor is split into a kinetic
contribution :math:`P^k` and a virial contribution :math:`P^v`. The sum
gives the total stress tensor :math:`P = P^k+P^v`. These computes can
for example be used to calculate the diagonal components of the local
stress tensor of interfaces with flat, cylindrical, or spherical
stress tensor of surfaces with cylindrical or spherical
symmetry. These computes obeys momentum balance through fluid
interfaces. They use the Irving--Kirkwood contour, which is the straight
line between particle pairs.
The *stress/cartesian* computes the stress profile along one or two
Cartesian coordinates, as described in :ref:`(Ikeshoji)<Ikeshoji2>`. The
compute *stress/cylinder* computes the stress profile along the
The compute *stress/cylinder* computes the stress profile along the
radial direction in cylindrical coordinates, as described in
:ref:`(Addington)<Addington1>`. The compute *stress/spherical*
computes the stress profile along the radial direction in spherical
coordinates, as described in :ref:`(Ikeshoji)<Ikeshoji2>`.
coordinates, as described in :ref:`(Ikeshoji)<Ikeshoji4>`.
Output info
"""""""""""
The output columns for *stress/cartesian* are the position of the
center of the local volume in the first and second dimensions, number
density, :math:`P^k_{xx}`, :math:`P^k_{yy}`, :math:`P^k_{zz}`,
:math:`P^v_{xx}`, :math:`P^v_{yy}`, and :math:`P^v_{zz}`. There are 8
columns when one dimension is specified and 9 columns when two
dimensions are specified. The number of bins (rows) is
:math:`(L_1/b_1)(L_2/b_2)`, where :math:`L_1` and :math:`L_2` are the lengths
of the simulation box in the specified dimensions and :math:`b_1` and
:math:`b_2` are the specified bin widths. When only one dimension is
specified, the number of bins (rows) is :math:`L_1/b_1`.
The default output columns for *stress/cylinder* are the radius to the
center of the cylindrical shell, number density, :math:`P^k_{rr}`,
:math:`P^k_{\phi\phi}`, :math:`P^k_{zz}`, :math:`P^v_{rr}`,
@ -111,7 +87,7 @@ This array can be output with :doc:`fix ave/time <fix_ave_time>`,
.. code-block:: LAMMPS
compute p all stress/cartesian x 0.1
compute 1 all stress/spherical 0 0 0 0.1 10
fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector
The values calculated by this compute are "intensive". The stress
@ -123,25 +99,15 @@ corrections to the stress added by the
:doc:`pair_modify tail yes <pair_modify>`
command, since those are contributions to the global system pressure.
NOTE 2: The local stress profiles generated by these computes are
similar to those obtained by the
:doc:`method-of-planes (MOP) <compute_stress_mop>`.
A key difference
is that compute `stress/mop/profile <compute_stress_mop>`
considers particles crossing a set of planes, while
*stress/cartesian* computes averages for a set of small volumes.
More information on the similarities and differences can be found in
:ref:`(Ikeshoji)<Ikeshoji2>`.
Restrictions
""""""""""""
These computes calculate the stress tensor contributions for pair
styles only (i.e., no bond, angle, dihedral, etc. contributions, and in
the presence of bonded interactions, the result will be incorrect due to
exclusions for special bonds) and requires pairwise force calculations
not available for most many-body pair styles.
Note that :math:`k`-space calculations are also excluded.
These computes calculate the stress tensor contributions for pair styles
only (i.e., no bond, angle, dihedral, etc. contributions, and in the
presence of bonded interactions, the result may be incorrect due to
exclusions for :doc:`special bonds <special_bonds>` excluding pairs of atoms
completely). It requires pairwise force calculations not available for most
many-body pair styles. Note that :math:`k`-space calculations are also excluded.
These computes are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build
@ -150,7 +116,8 @@ package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`, :doc:`compute stress/mop/profile <compute_stress_mop>`
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`,
:doc:`compute stress/mop/profile <compute_stress_mop>`, :doc:`compute stress/cartesian <compute_stress_cartesian>`
Default
"""""""
@ -159,7 +126,7 @@ The keyword default for ke in style *stress/cylinder* is yes.
----------
.. _Ikeshoji2:
.. _Ikeshoji4:
**(Ikeshoji)** Ikeshoji, Hafskjold, Furuholt, Mol Sim, 29, 101-109, (2003).

123
doc/src/compute_stress_mop.rst
View File

@ -18,7 +18,7 @@ Syntax
* style = *stress/mop* or *stress/mop/profile*
* dir = *x* or *y* or *z* is the direction normal to the plane
* args = argument specific to the compute style
* keywords = *kin* or *conf* or *total* (one of more can be specified)
* keywords = *kin* or *conf* or *total* or *pair* or *bond* or *angle* (one or more can be specified)
.. parsed-literal::
@ -45,85 +45,112 @@ Examples
Description
"""""""""""
Compute *stress/mop* and compute *stress/mop/profile* define computations that
calculate components of the local stress tensor using the method of
planes :ref:`(Todd) <mop-todd>`. Specifically in compute *stress/mop* calculates 3
components are computed in directions *dir*,\ *x*\ ; *dir*,\ *y*\ ; and
*dir*,\ *z*\ ; where *dir* is the direction normal to the plane, while
in compute *stress/mop/profile* the profile of the stress is computed.
Compute *stress/mop* and compute *stress/mop/profile* define
computations that calculate components of the local stress tensor using
the method of planes :ref:`(Todd) <mop-todd>`. Specifically in compute
*stress/mop* calculates 3 components are computed in directions *dir*,\
*x*\ ; *dir*,\ *y*\ ; and *dir*,\ *z*\ ; where *dir* is the direction
normal to the plane, while in compute *stress/mop/profile* the profile
of the stress is computed.
Contrary to methods based on histograms of atomic stress (i.e., using
:doc:`compute stress/atom <compute_stress_atom>`), the method of planes is
compatible with mechanical balance in heterogeneous systems and at
:doc:`compute stress/atom <compute_stress_atom>`), the method of planes
is compatible with mechanical balance in heterogeneous systems and at
interfaces :ref:`(Todd) <mop-todd>`.
The stress tensor is the sum of a kinetic term and a configurational
term, which are given respectively by Eq. (21) and Eq. (16) in
:ref:`(Todd) <mop-todd>`. For the kinetic part, the algorithm considers that
atoms have crossed the plane if their positions at times :math:`t-\Delta t`
and :math:`t` are one on either side of the plane, and uses the velocity at
time :math:`t-\Delta t/2` given by the velocity Verlet algorithm.
:ref:`(Todd) <mop-todd>`. For the kinetic part, the algorithm considers
that atoms have crossed the plane if their positions at times
:math:`t-\Delta t` and :math:`t` are one on either side of the plane,
and uses the velocity at time :math:`t-\Delta t/2` given by the velocity
Verlet algorithm.
Between one and three keywords can be used to indicate which
contributions to the stress must be computed: kinetic stress (kin),
configurational stress (conf), and/or total stress (total).
.. versionadded:: 15Jun2023
NOTE 1: The configurational stress is computed considering all pairs of atoms where at least one atom belongs to group group-ID.
contributions from bond and angle potentials
Between one and six keywords can be used to indicate which contributions
to the stress must be computed: total stress (total), kinetic stress
(kin), configurational stress (conf), stress due to bond stretching
(bond), stress due to angle bending (angle) and/or due to pairwise
non-bonded interactions (pair). The angle keyword is currently
available only for the *stress/mop* command and **not** the
*stress/mop/profile* command.
NOTE 1: The configurational stress is computed considering all pairs of
atoms where at least one atom belongs to group group-ID.
NOTE 2: The local stress does not include any Lennard-Jones tail
corrections to the stress added by the :doc:`pair_modify tail yes <pair_modify>`
command, since those are contributions to the global system pressure.
corrections to the stress added by the :doc:`pair_modify tail yes
<pair_modify>` command, since those are contributions to the global
system pressure.
NOTE 3: The local stress profile generated by compute *stress/mop/profile*
is similar to that obtained by compute
:doc:`stress/cartesian <compute_stress_profile>`.
A key difference is that compute *stress/mop/profile* considers particles
crossing a set of planes, while compute *stress/cartesian* computes averages
for a set of small volumes. More information
on the similarities and differences can be found in
:ref:`(Ikeshoji)<Ikeshoji2>`.
NOTE 3: The local stress profile generated by compute
*stress/mop/profile* is similar to that obtained by compute
:doc:`stress/cartesian <compute_stress_cartesian>`.
A key difference is that compute *stress/mop/profile*
considers particles crossing a set of planes, while
*stress/cartesian* computes averages for a set
of small volumes.
Moreover, *stress/cartesian* compute computes the diagonal components of the stress
tensor :math:`P_{xx}`, :math:`P_{yy}`, and :math:`P_{zz}`, while
*stress/mop/profile* computes the components
:math:`P_{ix}`, :math:`P_{iy}`, and :math:`P_{iz}`, where :math:`i` is the
direction normal to the plane.
Output info
"""""""""""
Compute *stress/mop* calculates a global vector (indices starting at 1), with 3
values for each declared keyword (in the order the keywords have been
declared). For each keyword, the stress tensor components are ordered as
follows: stress_dir,x, stress_dir,y, and stress_dir,z.
Compute *stress/mop* calculates a global vector (indices starting at 1),
with 3 values for each declared keyword (in the order the keywords have
been declared). For each keyword, the stress tensor components are
ordered as follows: stress_dir,x, stress_dir,y, and stress_dir,z.
Compute *stress/mop/profile* instead calculates a global array, with 1 column
giving the position of the planes where the stress tensor was computed,
and with 3 columns of values for each declared keyword (in the order the
keywords have been declared). For each keyword, the profiles of stress
tensor components are ordered as follows: stress_dir,x; stress_dir,y;
and stress_dir,z.
Compute *stress/mop/profile* instead calculates a global array, with 1
column giving the position of the planes where the stress tensor was
computed, and with 3 columns of values for each declared keyword (in the
order the keywords have been declared). For each keyword, the profiles
of stress tensor components are ordered as follows: stress_dir,x;
stress_dir,y; and stress_dir,z.
The values are in pressure :doc:`units <units>`.
The values produced by this compute can be accessed by various :doc:`output commands <Howto_output>`.
For instance, the results can be written to a file using the
:doc:`fix ave/time <fix_ave_time>` command. Please see the example
in the examples/PACKAGES/mop folder.
The values produced by this compute can be accessed by various
:doc:`output commands <Howto_output>`. For instance, the results can be
written to a file using the :doc:`fix ave/time <fix_ave_time>`
command. Please see the example in the examples/PACKAGES/mop folder.
Restrictions
""""""""""""
These styles are part of the EXTRA-COMPUTE package. They are only enabled if
LAMMPS is built with that package. See the :doc:`Build package <Build_package>`
doc page on for more info.
These styles are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS is built with that package. See the :doc:`Build
package <Build_package>` doc page on for more info.
The method is only implemented for 3d orthogonal simulation boxes whose
size does not change in time, and axis-aligned planes.
The method only works with two-body pair interactions, because it
requires the class method pair->single() to be implemented. In
particular, it does not work with more than two-body pair interactions,
intra-molecular interactions, and long range (kspace) interactions.
requires the class method ``Pair::single()`` to be implemented, which is
not possible for manybody potentials. In particular, compute
*stress/mop/profile* does not work with more than two-body pair
interactions, long range (kspace) interactions and
angle/dihedral/improper intramolecular interactions. Similarly, compute
*stress/mop* does not work with more than two-body pair interactions,
long range (kspace) interactions and dihedral/improper intramolecular
interactions but works with all bond interactions with the class method
single() implemented and all angle interactions with the class method
born_matrix() implemented.
Related commands
""""""""""""""""
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`, :doc:`compute stress/cartesian <compute_stress_profile>`, :doc:`compute stress/cylinder <compute_stress_profile>`, :doc:`compute stress/spherical <compute_stress_profile>`
:doc:`compute stress/atom <compute_stress_atom>`,
:doc:`compute pressure <compute_pressure>`,
:doc:`compute stress/cartesian <compute_stress_cartesian>`,
:doc:`compute stress/cylinder <compute_stress_curvilinear>`,
:doc:`compute stress/spherical <compute_stress_curvilinear>`
Default
"""""""

22
doc/src/compute_tally.rst
View File

@ -187,16 +187,22 @@ Both the scalar and vector values calculated by this compute are
Restrictions
""""""""""""
This compute is part of the TALLY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the TALLY package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Not all pair styles can be evaluated in a pairwise mode as required by
this compute. For example, 3-body and other many-body potentials,
such as :doc:`Tersoff <pair_tersoff>` and
:doc:`Stillinger-Weber <pair_sw>` cannot be used. :doc:`EAM <pair_eam>`
potentials only include the pair potential portion of the EAM
interaction when used by this compute, not the embedding term. Also
bonded or Kspace interactions do not contribute to this compute.
this compute. For example, 3-body and other many-body potentials, such
as :doc:`Tersoff <pair_tersoff>` and :doc:`Stillinger-Weber <pair_sw>`
cannot be used. :doc:`EAM <pair_eam>` potentials only include the pair
potential portion of the EAM interaction when used by this compute, not
the embedding term. Also bonded or Kspace interactions do not
contribute to this compute.
These computes are not compatible with accelerated pair styles from the
GPU, INTEL, KOKKOS, or OPENMP packages. They will either create an error
or print a warning when required data was not tallied in the required way
and thus the data acquisition functions from these computes not called.
When used with dynamic groups, a :doc:`run 0 <run>` command needs to
be inserted in order to initialize the dynamic groups before accessing

10
doc/src/dump_modify.rst
View File

@ -753,9 +753,13 @@ run, this option is ignored since the output is already balanced.
----------
The *thermo* keyword only applies the dump styles *netcdf* and *yaml*.
It triggers writing of :doc:`thermo <thermo>` information to the dump file
alongside per-atom data. The values included in the dump file are
identical to the values specified by :doc:`thermo_style <thermo_style>`.
It triggers writing of :doc:`thermo <thermo>` information to the dump
file alongside per-atom data. The values included in the dump file are
cached values from the last thermo output and include the exact same the
values as specified by the :doc:`thermo_style <thermo_style>` command.
Because these are cached values, they are only up-to-date when dump
output is on a timestep that also has thermo output. Dump style *yaml*
will skip thermo output on incompatible steps.
----------

2
doc/src/dump_molfile.rst
View File

@ -63,7 +63,7 @@ like element names.
The *path* keyword determines which in directories. This is a "path"
like other search paths, i.e. it can contain multiple directories
separated by a colon (or semi-colon on windows). This keyword is
separated by a colon (or semicolon on Windows). This keyword is
optional and default to ".", the current directory.
The *unwrap* option of the :doc:`dump_modify <dump_modify>` command allows

3
doc/src/fix.rst
View File

@ -323,7 +323,8 @@ accelerated styles exist.
* :doc:`pafi <fix_pafi>` - constrained force averages on hyper-planes to compute free energies (PAFI)
* :doc:`pair <fix_pair>` - access per-atom info from pair styles
* :doc:`phonon <fix_phonon>` - calculate dynamical matrix from MD simulations
* :doc:`pimd/nvt <fix_pimd>` - Feynman path integral molecular dynamics with Nose-Hoover thermostat
* :doc:`pimd/langevin <fix_pimd>` - Feynman path-integral molecular dynamics with stochastic thermostat
* :doc:`pimd/nvt <fix_pimd>` - Feynman path-integral molecular dynamics with Nose-Hoover thermostat
* :doc:`planeforce <fix_planeforce>` - constrain atoms to move in a plane
* :doc:`plumed <fix_plumed>` - wrapper on PLUMED free energy library
* :doc:`poems <fix_poems>` - constrain clusters of atoms to move as coupled rigid bodies

2
doc/src/fix_adapt.rst
View File

@ -163,6 +163,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`harmonic/cut <pair_harmonic_cut>` | k, cutoff | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`kim <pair_kim>` | scale | type global |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lennard/mdf <pair_mdf>` | A,B | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/class2 <pair_class2>` | epsilon,sigma | type pairs |

2
doc/src/fix_dpd_source.rst
View File

@ -61,7 +61,7 @@ heat conduction with a source term (see Fig.12 in :ref:`(Li2014) <Li2014b>`)
or diffusion with a source term (see Fig.1 in :ref:`(Li2015) <Li2015b>`), as
an analog of a periodic Poiseuille flow problem.
.. deprecated:: TBD
.. deprecated:: 15Jun2023
The *sphere* and *cuboid* keywords will be removed in a future version
of LAMMPS. The same functionality and more can be achieved with a region.

30
doc/src/fix_efield.rst
View File

@ -19,7 +19,7 @@ Syntax
* ex,ey,ez = E-field component values (electric field units)
* any of ex,ey,ez can be a variable (see below)
* zero or more keyword/value pairs may be appended to args
* keyword = *region* or *energy*
* keyword = *region* or *energy* or *potential*
.. parsed-literal::
@ -27,6 +27,8 @@ Syntax
region-ID = ID of region atoms must be in to have added force
*energy* value = v_name
v_name = variable with name that calculates the potential energy of each atom in the added E-field
*potential* value = v_name
v_name = variable with name that calculates the electric potential of each atom in the added E-field
Examples
""""""""
@ -112,7 +114,8 @@ one or more variables, and if you are performing dynamics via the
:doc:`run <run>` command. If the keyword is not used, LAMMPS will set
the energy to 0.0, which is typically fine for dynamics.
The *energy* keyword is required if the added force is defined with
The *energy* keyword (or *potential* keyword, described below)
is required if the added force is defined with
one or more variables, and you are performing energy minimization via
the "minimize" command for charged particles. It is not required for
point-dipoles, but a warning is issued since the minimizer in LAMMPS
@ -122,7 +125,7 @@ minimize the orientation of dipoles in an applied electric field.
The *energy* keyword specifies the name of an atom-style
:doc:`variable <variable>` which is used to compute the energy of each
atom as function of its position. Like variables used for *ex*,
*ey*, *ez*, the energy variable is specified as v_name, where name
*ey*, *ez*, the energy variable is specified as "v_name", where "name"
is the variable name.
Note that when the *energy* keyword is used during an energy
@ -133,6 +136,27 @@ due to the electric field were a spring-like F = kx, then the energy
formula should be E = -0.5kx\^2. If you don't do this correctly, the
minimization will not converge properly.
.. versionadded:: 15Jun2023
The *potential* keyword can be used as an alternative to the *energy* keyword
to specify the name of an atom-style variable, which is used to compute the
added electric potential to each atom as a function of its position. The
variable should have units of electric field multiplied by distance (that is,
in `units real`, the potential should be in volts). As with the *energy*
keyword, the variable name is specified as "v_name". The energy added by this
fix is then calculated as the electric potential multiplied by charge.
The *potential* keyword is mainly intended for correct charge
equilibration in simulations with :doc:`fix qeq/reaxff<fix_qeq_reaxff>`,
since with variable charges the electric potential can be known
beforehand but the energy cannot. A small additional benefit is that
the *energy* keyword requires an additional conversion to energy units
which the *potential* keyword avoids. Thus, when the *potential*
keyword is specified, the *energy* keyword must not be used. As with
*energy*, the *potential* keyword is not allowed if the added field is a
constant vector. The *potential* keyword is not supported by *fix
efield/tip4p*.
----------
Restart, fix_modify, output, run start/stop, minimize info

2
doc/src/fix_pair.rst
View File

@ -85,7 +85,7 @@ columns 4-6 will store the "uinp" values.
.. code-block:: LAMMPS
pair_style amoeba
fix ex all pair amoeba 10 uind 0 uinp 0
fix ex all pair 10 amoeba uind 0 uinp 0
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

293
doc/src/fix_pimd.rst
View File

@ -1,5 +1,9 @@
.. index:: fix pimd/langevin
.. index:: fix pimd/nvt
fix pimd/langevin command
=========================
fix pimd/nvt command
====================
@ -8,72 +12,107 @@ Syntax
.. parsed-literal::
fix ID group-ID pimd/nvt keyword value ...
fix ID group-ID style keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* pimd/nvt = style name of this fix command
* style = *pimd/langevin* or *pimd/nvt* = style name of this fix command
* zero or more keyword/value pairs may be appended
* keyword = *method* or *fmass* or *sp* or *temp* or *nhc*
* keywords for style *pimd/nvt*
.. parsed-literal::
*keywords* = *method* or *fmass* or *sp* or *temp* or *nhc*
*method* value = *pimd* or *nmpimd* or *cmd*
*fmass* value = scaling factor on mass
*sp* value = scaling factor on Planck constant
*temp* value = temperature (temperarate units)
*temp* value = temperature (temperature units)
*nhc* value = Nc = number of chains in Nose-Hoover thermostat
* keywords for style *pimd/langevin*
.. parsed-literal::
*keywords* = *method* or *integrator* or *ensemble* or *fmmode* or *fmass* or *scale* or *temp* or *thermostat* or *tau* or *iso* or *aniso* or *barostat* or *taup* or *fixcom* or *lj*
*method* value = *nmpimd*
*integrator* value = *obabo* or *baoab*
*fmmode* value = *physical* or *normal*
*fmass* value = scaling factor on mass
*temp* value = temperature (temperature unit)
temperature = target temperature of the thermostat
*thermostat* values = style seed
style value = *PILE_L*
seed = random number generator seed
*tau* value = thermostat damping parameter (time unit)
*scale* value = scaling factor of the damping times of non-centroid modes of PILE_L thermostat
*iso* or *aniso* values = pressure (pressure unit)
pressure = scalar external pressure of the barostat
*barostat* value = *BZP* or *MTTK*
*taup* value = barostat damping parameter (time unit)
*fixcom* value = *yes* or *no*
*lj* values = epsilon sigma mass planck mvv2e
epsilon = energy scale for reduced units (energy units)
sigma = length scale for reduced units (length units)
mass = mass scale for reduced units (mass units)
planck = Planck's constant for other unit style
mvv2e = mass * velocity^2 to energy conversion factor for other unit style
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all pimd/nvt method nmpimd fmass 1.0 sp 2.0 temp 300.0 nhc 4
fix 1 all pimd/langevin ensemble npt integrator obabo temp 113.15 thermostat PILE_L 1234 tau 1.0 iso 1.0 barostat BZP taup 1.0
Description
"""""""""""
.. versionchanged:: 28Mar2023
Fix pimd was renamed to fix pimd/nvt.
Fix pimd was renamed to fix *pimd/nvt* and fix *pimd/langevin* was added.
This command performs quantum molecular dynamics simulations based on
the Feynman path integral to include effects of tunneling and
These fix commands perform quantum molecular dynamics simulations based
on the Feynman path-integral to include effects of tunneling and
zero-point motion. In this formalism, the isomorphism of a quantum
partition function for the original system to a classical partition
function for a ring-polymer system is exploited, to efficiently sample
configurations from the canonical ensemble :ref:`(Feynman) <Feynman>`.
The classical partition function and its components are given
by the following equations:
.. math::
Z = & \int d{\bf q} d{\bf p} \cdot \textrm{exp} [ -\beta H_{eff} ] \\
H_{eff} = & \bigg(\sum_{i=1}^P \frac{p_i^2}{2m_i}\bigg) + V_{eff} \\
H_{eff} = & \bigg(\sum_{i=1}^P \frac{p_i^2}{2M_i}\bigg) + V_{eff} \\
V_{eff} = & \sum_{i=1}^P \bigg[ \frac{mP}{2\beta^2 \hbar^2} (q_i - q_{i+1})^2 + \frac{1}{P} V(q_i)\bigg]
:math:`M_i` is the fictitious mass of the :math:`i`-th mode, and m is the actual mass of the atoms.
The interested user is referred to any of the numerous references on
this methodology, but briefly, each quantum particle in a path
integral simulation is represented by a ring-polymer of P quasi-beads,
labeled from 1 to P. During the simulation, each quasi-bead interacts
with beads on the other ring-polymers with the same imaginary time
index (the second term in the effective potential above). The
quasi-beads also interact with the two neighboring quasi-beads through
the spring potential in imaginary-time space (first term in effective
potential). To sample the canonical ensemble, a Nose-Hoover massive
chain thermostat is applied :ref:`(Tuckerman) <pimd-Tuckerman>`. With the
massive chain algorithm, a chain of NH thermostats is coupled to each
degree of freedom for each quasi-bead. The keyword *temp* sets the
target temperature for the system and the keyword *nhc* sets the
number *Nc* of thermostats in each chain. For example, for a
simulation of N particles with P beads in each ring-polymer, the total
number of NH thermostats would be 3 x N x P x Nc.
this methodology, but briefly, each quantum particle in a path integral
simulation is represented by a ring-polymer of P quasi-beads, labeled
from 1 to P. During the simulation, each quasi-bead interacts with
beads on the other ring-polymers with the same imaginary time index (the
second term in the effective potential above). The quasi-beads also
interact with the two neighboring quasi-beads through the spring
potential in imaginary-time space (first term in effective potential).
To sample the canonical ensemble, any thermostat can be applied.
Fix *pimd/nvt* applies a Nose-Hoover massive chain thermostat
:ref:`(Tuckerman) <pimd-Tuckerman>`. With the massive chain
algorithm, a chain of NH thermostats is coupled to each degree of
freedom for each quasi-bead. The keyword *temp* sets the target
temperature for the system and the keyword *nhc* sets the number *Nc* of
thermostats in each chain. For example, for a simulation of N particles
with P beads in each ring-polymer, the total number of NH thermostats
would be 3 x N x P x Nc.
Fix *pimd/langevin* implements a Langevin thermostat in the normal mode
representation, and also provides a barostat to sample the NPH/NPT ensembles.
.. note::
Fix pimd/nvt implements a complete velocity-verlet integrator
combined with NH massive chain thermostat, so no other time
integration fix should be used.
Both these *fix* styles implement a complete velocity-verlet integrator
combined with a thermostat, so no other time integration fix should be used.
The *method* keyword determines what style of PIMD is performed. A
value of *pimd* is standard PIMD. A value of *nmpimd* is for
@ -81,7 +120,7 @@ normal-mode PIMD. A value of *cmd* is for centroid molecular dynamics
(CMD). The difference between the styles is as follows.
In standard PIMD, the value used for a bead's fictitious mass is
arbitrary. A common choice is to use Mi = m/P, which results in the
arbitrary. A common choice is to use :math:`M_i = m/P`, which results in the
mass of the entire ring-polymer being equal to the real quantum
particle. But it can be difficult to efficiently integrate the
equations of motion for the stiff harmonic interactions in the ring
@ -97,6 +136,10 @@ normal-mode PIMD. A value of *cmd* is for centroid molecular dynamics
overall translation of the ring-polymer and is assigned the mass of
the real particle.
.. note::
Fix pimd/langevin only supports *method* value *nmpimd*. This should be enough
for most PIMD applications for quantum thermodynamics purpose.
Motion of the centroid can be effectively uncoupled from the other
normal modes by scaling the fictitious masses to achieve a partial
adiabatic separation. This is called a Centroid Molecular Dynamics
@ -108,17 +151,86 @@ normal-mode PIMD. A value of *cmd* is for centroid molecular dynamics
only the k > 0 modes are thermostatted, not the centroid degrees of
freedom.
The keyword *integrator* specifies the Trotter splitting method used by *fix pimd/langevin*.
See :ref:`(Liu) <Liu>` for a discussion on the OBABO and BAOAB splitting schemes. Typically
either of the two should work fine.
The keyword *fmass* sets a further scaling factor for the fictitious
masses of beads, which can be used for the Partial Adiabatic CMD
:ref:`(Hone) <Hone>`, or to be set as P, which results in the fictitious
masses to be equal to the real particle masses.
The keyword *fmmode* of *fix pimd/langevin* determines the mode of fictitious
mass preconditioning. There are two options: *physical* and *normal*. If *fmmode* is
*physical*, then the physical mass of the particles are used (and then multiplied by
*fmass*). If *fmmode* is *normal*, then the physical mass is first multiplied by the
eigenvalue of each normal mode, and then multiplied by *fmass*. More precisely, the
fictitious mass of *fix pimd/langevin* is determined by two factors: *fmmode* and *fmass*.
If *fmmode* is *physical*, then the fictitious mass is
.. math::
M_i = \mathrm{fmass} \times m
If *fmmode* is *normal*, then the fictitious mass is
.. math::
M_i = \mathrm{fmass} \times \lambda_i \times m
where :math:`\lambda_i` is the eigenvalue of the :math:`i`-th normal mode.
.. note::
Fictitious mass is only used in the momentum of the equation of motion
(:math:`\mathbf{p}_i=M_i\mathbf{v}_i`), and not used in the spring elastic energy
(:math:`\sum_{i=1}^P \frac{1}{2}m\omega_P^2(q_i - q_{i+1})^2`, :math:`m` is always the
actual mass of the particles).
The keyword *sp* is a scaling factor on Planck's constant, which can
be useful for debugging or other purposes. The default value of 1.0
is appropriate for most situations.
The keyword *ensemble* for fix style *pimd/langevin* determines which ensemble is it
going to sample. The value can be *nve* (microcanonical), *nvt* (canonical), *nph* (isoenthalpic),
and *npt* (isothermal-isobaric).
The keyword *temp* specifies temperature parameter for fix styles *pimd/nvt* and *pimd/langevin*. It should read
a positive floating-point number.
.. note::
For pimd simulations, a temperature values should be specified even for nve ensemble. Temperature will make a difference
for nve pimd, since the spring elastic frequency between the beads will be affected by the temperature.
The keyword *thermostat* reads *style* and *seed* of thermostat for fix style *pimd/langevin*. *style* can only
be *PILE_L* (path integral Langevin equation local thermostat, as described in :ref:`Ceriotti <Ceriotti2>`), and *seed* should a positive integer number, which serves as the seed of the pseudo random number generator.
.. note::
The fix style *pimd/langevin* uses the stochastic PILE_L thermostat to control temperature. This thermostat works on the normal modes
of the ring polymer. The *tau* parameter controls the centroid mode, and the *scale* parameter controls the non-centroid modes.
The keyword *tau* specifies the thermostat damping time parameter for fix style *pimd/langevin*. It is in time unit. It only works on the centroid mode.
The keyword *scale* specifies a scaling parameter for the damping times of the non-centroid modes for fix style *pimd/langevin*. The default
damping time of the non-centroid mode :math:`i` is :math:`\frac{P}{\beta\hbar}\sqrt{\lambda_i\times\mathrm{fmass}}` (*fmmode* is *physical*) or :math:`\frac{P}{\beta\hbar}\sqrt{\mathrm{fmass}}` (*fmmode* is *normal*). The damping times of all non-centroid modes are the default values divided by *scale*.
The barostat parameters for fix style *pimd/langevin* with *npt* or *nph* ensemble is specified using one of *iso* and *aniso*
keywords. A *pressure* value should be given with pressure unit. The keyword *iso* means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure), and dilate/contract the dimensions together. The keyword *aniso* means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components of the stress tensor as the driving forces, and the specified scalar external pressure.
The keyword *barostat* reads *style* of barostat for fix style *pimd/langevin*. *style* can
be *BZP* (Bussi-Zykova-Parrinello, as described in :ref:`Bussi <Bussi>`) or *MTTK* (Martyna-Tuckerman-Tobias-Klein, as described in :ref:`Martyna1 <Martyna3>` and :ref:`Martyna2 <Martyna4>`).
The keyword *taup* specifies the barostat damping time parameter for fix style *pimd/langevin*. It is in time unit.
The keyword *fixcom* specifies whether the center-of-mass of the extended ring-polymer system is fixed during the pimd simulation.
Once *fixcom* is set to be *yes*, the center-of-mass velocity will be distracted from the centroid-mode velocities in each step.
The keyword *lj* should be used if :doc:`lj units <units>` is used for *fix pimd/langevin*. Typically one may want to use
reduced units to run the simulation, and then convert the results into some physical units (for example, :doc:`metal units <units>`). In this case, the 5 quantities in the physical mass units are needed: epsilon (energy scale), sigma (length scale), mass, Planck's constant, mvv2e (mass * velocity^2 to energy conversion factor). Planck's constant and mvv2e can be found in src/update.cpp. If there is no need to convert reduced units to physical units, set all these five value to 1.
The PIMD algorithm in LAMMPS is implemented as a hyper-parallel scheme
as described in :ref:`(Calhoun) <Calhoun>`. In LAMMPS this is done by using
as described in :ref:`Calhoun <Calhoun>`. In LAMMPS this is done by using
:doc:`multi-replica feature <Howto_replica>` in LAMMPS, where each
quasi-particle system is stored and simulated on a separate partition
of processors. The following diagram illustrates this approach. The
@ -152,22 +264,49 @@ related tasks for each of the partitions, e.g.
.. code-block:: LAMMPS
dump dcd all dcd 10 system_${ibead}.dcd
dump 1 all custom 100 ${ibead}.xyz id type x y z vx vy vz ix iy iz fx fy fz
restart 1000 system_${ibead}.restart1 system_${ibead}.restart2
read_restart system_${ibead}.restart2
.. note::
Fix *pimd/langevin* dumps the Cartesian coordinates, but dumps the velocities and
forces in the normal mode representation. If the Cartesian velocities and forces are
needed, it is easy to perform the transformation when doing post-processing.
It is recommended to dump the image flags (*ix iy iz*) for fix *pimd/langevin*. It
will be useful if you want to calculate some estimators during post-processing.
Major differences of *fix pimd/nvt* and *fix pimd/langevin* are:
#. *Fix pimd/nvt* includes Cartesian pimd, normal mode pimd, and centroid md. *Fix pimd/langevin* only intends to support normal mode pimd, as it is commonly enough for thermodynamic sampling.
#. *Fix pimd/nvt* uses Nose-Hoover chain thermostat. *Fix pimd/langevin* uses Langevin thermostat.
#. *Fix pimd/langevin* provides barostat, so the npt ensemble can be sampled. *Fix pimd/nvt* only support nvt ensemble.
#. *Fix pimd/langevin* provides several quantum estimators in output.
#. *Fix pimd/langevin* allows multiple processes for each bead. For *fix pimd/nvt*, there is a large chance that multi-process tasks for each bead may fail.
#. The dump of *fix pimd/nvt* are all Cartesian. *Fix pimd/langevin* dumps normal-mode velocities and forces, and Cartesian coordinates.
Initially, the inter-replica communication and normal mode transformation parts of *fix pimd/langevin* are written based on
those of *fix pimd/nvt*, but are significantly revised.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Fix pimd/nvt writes the state of the Nose/Hoover thermostat over all
Fix *pimd/nvt* writes the state of the Nose/Hoover thermostat over all
quasi-beads to :doc:`binary restart files <restart>`. See the
:doc:`read_restart <read_restart>` command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
Fix *pimd/langevin* writes the state of the barostat overall beads to
:doc:`binary restart files <restart>`. Since it uses a stochastic thermostat,
the state of the thermostat is not written. However, the state of the system
can be restored by reading the restart file, except that it will re-initialize
the random number generator.
None of the :doc:`fix_modify <fix_modify>` options
are relevant to fix pimd/nvt.
Fix pimd/nvt computes a global 3-vector, which can be accessed by
Fix *pimd/nvt* computes a global 3-vector, which can be accessed by
various :doc:`output commands <Howto_output>`. The three quantities in
the global vector are:
@ -176,21 +315,80 @@ the global vector are:
#. the current value of the scalar virial estimator for the kinetic
energy of the quantum system :ref:`(Herman) <Herman>`.
The vector values calculated by fix pimd/nvt are "extensive", except for the
The vector values calculated by fix *pimd/nvt* are "extensive", except for the
temperature, which is "intensive".
No parameter of fix pimd/nvt can be used with the *start/stop* keywords
of the :doc:`run <run>` command. Fix pimd/nvt is not invoked during
Fix *pimd/langevin* computes a global vector of quantities, which
can be accessed by various :doc:`output commands <Howto_output>`. Note that
it outputs multiple log files, and different log files contain information
about different beads or modes (see detailed explanations below). If *ensemble*
is *nve* or *nvt*, the vector has 10 values:
#. kinetic energy of the normal mode
#. spring elastic energy of the normal mode
#. potential energy of the bead
#. total energy of all beads (conserved if *ensemble* is *nve*)
#. primitive kinetic energy estimator
#. virial energy estimator
#. centroid-virial energy estimator
#. primitive pressure estimator
#. thermodynamic pressure estimator
#. centroid-virial pressure estimator
The first 3 are different for different log files, and the others are the same for different log files.
If *ensemble* is *nph* or *npt*, the vector stores internal variables of the barostat. If *iso* is used,
the vector has 15 values:
#. kinetic energy of the normal mode
#. spring elastic energy of the normal mode
#. potential energy of the bead
#. total energy of all beads (conserved if *ensemble* is *nve*)
#. primitive kinetic energy estimator
#. virial energy estimator
#. centroid-virial energy estimator
#. primitive pressure estimator
#. thermodynamic pressure estimator
#. centroid-virial pressure estimator
#. barostat velocity
#. barostat kinetic energy
#. barostat potential energy
#. barostat cell Jacobian
#. enthalpy of the extended system (sum of 4, 12, 13, and 14; conserved if *ensemble* is *nph*)
If *aniso* or *x* or *y* or *z* is used for the barostat, the vector has 17 values:
#. kinetic energy of the normal mode
#. spring elastic energy of the normal mode
#. potential energy of the bead
#. total energy of all beads (conserved if *ensemble* is *nve*)
#. primitive kinetic energy estimator
#. virial energy estimator
#. centroid-virial energy estimator
#. primitive pressure estimator
#. thermodynamic pressure estimator
#. centroid-virial pressure estimator
#. x component of barostat velocity
#. y component of barostat velocity
#. z component of barostat velocity
#. barostat kinetic energy
#. barostat potential energy
#. barostat cell Jacobian
#. enthalpy of the extended system (sum of 4, 14, 15, and 16; conserved if *ensemble* is *nph*)
No parameter of fix *pimd/nvt* or *pimd/langevin* can be used with the *start/stop* keywords
of the :doc:`run <run>` command. Fix *pimd/nvt* or *pimd/langevin* is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the REPLICA package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
These fixes are part of the REPLICA package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Fix pimd/nvt cannot be used with :doc:`lj units <units>`.
Fix *pimd/nvt* cannot be used with :doc:`lj units <units>`.
Fix *pimd/langevin* can be used with :doc:`lj units <units>`. See the above part for how to use it.
A PIMD simulation can be initialized with a single data file read via
the :doc:`read_data <read_data>` command. However, this means all
@ -207,7 +405,7 @@ variable, e.g.
Default
"""""""
The keyword defaults for fix pimd/nvt are method = pimd, fmass = 1.0, sp
The keyword defaults for fix *pimd/nvt* are method = pimd, fmass = 1.0, sp
= 1.0, temp = 300.0, and nhc = 2.
----------
@ -243,3 +441,22 @@ Path Integrals, McGraw-Hill, New York (1965).
**(Herman)** M. F. Herman, E. J. Bruskin, B. J. Berne, J Chem Phys, 76, 5150 (1982).
.. _Bussi:
**(Bussi)** G. Bussi, T. Zykova-Timan, M. Parrinello, J Chem Phys, 130, 074101 (2009).
.. _Ceriotti3:
**(Ceriotti)** M. Ceriotti, M. Parrinello, T. Markland, D. Manolopoulos, J. Chem. Phys. 133, 124104 (2010).
.. _Martyna3:
**(Martyna1)** G. Martyna, D. Tobias, M. Klein, J. Chem. Phys. 101, 4177 (1994).
.. _Martyna4:
**(Martyna2)** G. Martyna, A. Hughes, M. Tuckerman, J. Chem. Phys. 110, 3275 (1999).
.. _Liujian:
**(Liu)** J. Liu, D. Li, X. Liu, J. Chem. Phys. 145, 024103 (2016).

23
doc/src/fix_print.rst
View File

@ -44,6 +44,20 @@ one word. If it contains variables it must be enclosed in double
quotes to ensure they are not evaluated when the input script line is
read, but will instead be evaluated each time the string is printed.
.. versionadded:: 15Jun2023
support for vector style variables
See the :doc:`variable <variable>` command for a description of
*equal* and *vector* style variables which are typically the most
useful ones to use with the print command. Equal- and vector-style
variables can calculate formulas involving mathematical operations,
atom properties, group properties, thermodynamic properties, global
values calculated by a :doc:`compute <compute>` or :doc:`fix <fix>`,
or references to other :doc:`variables <variable>`. Vector-style
variables are printed in a bracketed, comma-separated format,
e.g. [1,2,3,4] or [12.5,2,4.6,10.1].
.. note::
As discussed on the :doc:`Commands parse <Commands_parse>` doc
@ -77,15 +91,6 @@ timesteps 10,20,30,100,200,300,1000,2000,etc:
The specified group-ID is ignored by this fix.
See the :doc:`variable <variable>` command for a description of
*equal* style variables which are the most useful ones to use with the
fix print command, since they are evaluated afresh each timestep that
the fix print line is output. Equal-style variables calculate
formulas involving mathematical operations, atom properties, group
properties, thermodynamic properties, global values calculated by a
:doc:`compute <compute>` or :doc:`fix <fix>`, or references to other
:doc:`variables <variable>`.
If the *file* or *append* keyword is used, a filename is specified to
which the output generated by this fix will be written. If *file* is
used, then the filename is overwritten if it already exists. If

9
doc/src/fix_qeq_reaxff.rst
View File

@ -128,9 +128,12 @@ periodic cell dimensions less than 10 Angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used, it may only use a
constant electric field, and the electric field vector may only have
components in non-periodic directions.
but there may be only one fix efield instance used and the electric field
vector may only have components in non-periodic directions. Equal-style
variables can be used for electric field vector components without any further
settings. Atom-style variables can be used for spatially-varying electric field
vector components, but the resulting electric potential must be specified
as an atom-style variable using the *potential* keyword for `fix efield`.
Related commands
""""""""""""""""

26
doc/src/fix_reaxff_species.rst
View File

@ -25,7 +25,7 @@ Syntax
.. parsed-literal::
*cutoff* value = I J Cutoff
I, J = atom types
I, J = atom types (see asterisk form below)
Cutoff = Bond-order cutoff value for this pair of atom types
*element* value = Element1, Element2, ...
*position* value = posfreq filepos
@ -49,7 +49,7 @@ Examples
.. code-block:: LAMMPS
fix 1 all reaxff/species 10 10 100 species.out
fix 1 all reaxff/species 1 2 20 species.out cutoff 1 1 0.40 cutoff 1 2 0.55
fix 1 all reaxff/species 1 2 20 species.out cutoff 1 1 0.40 cutoff 1 2*3 0.55
fix 1 all reaxff/species 1 100 100 species.out element Au O H position 1000 AuOH.pos
fix 1 all reaxff/species 1 100 100 species.out delete species.del masslimit 0 50
@ -88,13 +88,24 @@ If the filename ends with ".gz", the output file is written in gzipped
format. A gzipped dump file will be about 3x smaller than the text version,
but will also take longer to write.
.. versionadded:: 15Jun2023
Support for wildcards added
Optional keyword *cutoff* can be assigned to change the minimum
bond-order values used in identifying chemical bonds between pairs of
atoms. Bond-order cutoffs should be carefully chosen, as bond-order
cutoffs that are too small may include too many bonds (which will
result in an error), while cutoffs that are too large will result in
fragmented molecules. The default cutoff of 0.3 usually gives good
results.
cutoffs that are too small may include too many bonds (which will result
in an error), while cutoffs that are too large will result in fragmented
molecules. The default cutoff of 0.3 usually gives good results. A
wildcard asterisk can be used in place of or in conjunction with the I,J
arguments to set the bond-order cutoff for multiple pairs of atom types.
This takes the form "\*" or "\*n" or "n\*" or "m\*n". If :math:`N` is
the number of atom types, then an asterisk with no numeric values means
all types from 1 to :math:`N`. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to
:math:`N` (inclusive). A middle asterisk means all types from m to n
(inclusive).
The optional keyword *element* can be used to specify the chemical
symbol printed for each LAMMPS atom type. The number of symbols must
@ -148,7 +159,8 @@ formulae). The *specieslist* and *masslimit* keywords cannot both be
used in the same *reaxff/species* fix. The *delete_rate_limit*
keyword can enforce an upper limit on the overall rate of molecule
deletion. The number of deletion occurrences is limited to Nlimit
within an interval of Nsteps timesteps. When using the
within an interval of Nsteps timesteps. Nlimit can be specified with
an equal-style :doc:`variable <variable>`. When using the
*delete_rate_limit* keyword, no deletions are permitted to occur
within the first Nsteps timesteps of the first run (after reading a
either a data or restart file).

2
doc/src/fix_wall.rst
View File

@ -209,7 +209,7 @@ it as a single keyword.
Optionally, the expression may use "rc" to refer to the cutoff distance
for the given wall. Further constants in the expression can be defined
in the same string as additional expressions separated by semi-colons.
in the same string as additional expressions separated by semicolons.
The expression "k*(r-rc)^2;k=100.0" represents a repulsive-only harmonic
spring as in fix *wall/harmonic* with a force constant *K* (same as
:math:`\epsilon` above) of 100 energy units. More details on the Lepton

3
doc/src/kspace_modify.rst
View File

@ -142,7 +142,8 @@ the code will stop with an error message. When this option is set to
For a typical application, using the automatic parameter generation
will provide simulations that are either inaccurate or slow. Using this
option is thus not recommended. For guidelines on how to obtain good
parameters, see the :doc:`How-To <Howto_dispersion>` discussion.
parameters, see the :doc:`long-range dispersion howto <Howto_dispersion>`
discussion.
----------

102
doc/src/package.rst
View File

@ -49,7 +49,7 @@ Syntax
*intel* args = NPhi keyword value ...
Nphi = # of co-processors per node
zero or more keyword/value pairs may be appended
keywords = *mode* or *omp* or *lrt* or *balance* or *ghost* or *tpc* or *tptask* or *no_affinity*
keywords = *mode* or *omp* or *lrt* or *balance* or *ghost* or *tpc* or *tptask* or *pppm_table* or *no_affinity*
*mode* value = *single* or *mixed* or *double*
single = perform force calculations in single precision
mixed = perform force calculations in mixed precision
@ -68,10 +68,13 @@ Syntax
Ntpc = max number of co-processor threads per co-processor core (default = 4)
*tptask* value = Ntptask
Ntptask = max number of co-processor threads per MPI task (default = 240)
*pppm_table* value = *yes* or *no*
*yes* = Precompute pppm values in table (doesn't change accuracy)
*no* = Compute pppm values on the fly
*no_affinity* values = none
*kokkos* args = keyword value ...
zero or more keyword/value pairs may be appended
keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *gpu/aware* or *pair/only*
keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *sort* or *gpu/aware* or *pair/only*
*neigh* value = *full* or *half*
full = full neighbor list
half = half neighbor list built in thread-safe manner
@ -102,6 +105,9 @@ Syntax
*comm/pair/reverse* value = *no* or *device*
*no* = perform communication pack/unpack in non-KOKKOS mode
*device* = perform pack/unpack on device (e.g. on GPU)
*sort* value = *no* or *device*
*no* = perform atom sorting in non-KOKKOS mode
*device* = perform atom sorting on device (e.g. on GPU)
*gpu/aware* = *off* or *on*
*off* = do not use GPU-aware MPI
*on* = use GPU-aware MPI (default)
@ -389,13 +395,13 @@ is identical to the default *verlet* style aside from supporting the
LRT feature. This feature requires setting the pre-processor flag
-DLMP_INTEL_USELRT in the makefile when compiling LAMMPS.
The *balance* keyword sets the fraction of :doc:`pair style <pair_style>` work offloaded to the co-processor for split
values between 0.0 and 1.0 inclusive. While this fraction of work is
running on the co-processor, other calculations will run on the host,
including neighbor and pair calculations that are not offloaded, as
well as angle, bond, dihedral, kspace, and some MPI communications.
If *split* is set to -1, the fraction of work is dynamically adjusted
automatically throughout the run. This typically give performance
The *balance* keyword sets the fraction of :doc:`pair style <pair_style>` work
offloaded to the co-processor for split values between 0.0 and 1.0 inclusive.
While this fraction of work is running on the co-processor, other calculations
will run on the host, including neighbor and pair calculations that are not
offloaded, as well as angle, bond, dihedral, kspace, and some MPI
communications. If *split* is set to -1, the fraction of work is dynamically
adjusted automatically throughout the run. This typically give performance
within 5 to 10 percent of the optimal fixed fraction.
The *ghost* keyword determines whether or not ghost atoms, i.e. atoms
@ -427,6 +433,13 @@ with 16 threads, for a total of 128.
Note that the default settings for *tpc* and *tptask* are fine for
most problems, regardless of how many MPI tasks you assign to a Phi.
.. versionadded:: 15Jun2023
The *pppm_table* keyword with the argument yes allows to use a
pre-computed table to efficiently spread the charge to the PPPM grid.
This feature is enabled by default but can be turned off using the
keyword with the argument *no*.
The *no_affinity* keyword will turn off automatic setting of core
affinity for MPI tasks and OpenMP threads on the host when using
offload to a co-processor. Affinity settings are used when possible
@ -554,6 +567,17 @@ pack/unpack communicated data. When running small systems on a GPU,
performing the exchange pack/unpack on the host CPU can give speedup
since it reduces the number of CUDA kernel launches.
The *sort* keyword determines whether the host or device performs atom
sorting, see the :doc:`atom_modify sort <atom_modify>` command. The
value options for the *sort* keyword are *no* or *device* similar to the
*comm* keywords above. If a value of *host* is used it will be
automatically be changed to *no* since the *sort* keyword does not
support *host* mode. The value of *no* will also always be used when
running on the CPU, i.e. setting the value to *device* will have no
effect if the simulation is running on the CPU. Not all fix styles with
extra atom data support *device* mode and in that case a warning will be
given and atom sorting will run in *no* mode instead.
The *gpu/aware* keyword chooses whether GPU-aware MPI will be used. When
this keyword is set to *on*, buffers in GPU memory are passed directly
through MPI send/receive calls. This reduces overhead of first copying
@ -685,39 +709,37 @@ Related commands
Default
"""""""
For the GPU package, the default is Ngpu = 0 and the option defaults
are neigh = yes, newton = off, binsize = 0.0, split = 1.0, gpuID = 0
to Ngpu-1, tpa = 1, omp = 0, and platform=-1. These settings are made
automatically if the "-sf gpu" :doc:`command-line switch <Run_options>`
is used. If it is not used, you must invoke the package gpu command
in your input script or via the "-pk gpu" :doc:`command-line switch <Run_options>`.
For the GPU package, the default is Ngpu = 0 and the option defaults are neigh
= yes, newton = off, binsize = 0.0, split = 1.0, gpuID = 0 to Ngpu-1, tpa = 1,
omp = 0, and platform=-1. These settings are made automatically if the "-sf
gpu" :doc:`command-line switch <Run_options>` is used. If it is not used, you
must invoke the package gpu command in your input script or via the "-pk gpu"
:doc:`command-line switch <Run_options>`.
For the INTEL package, the default is Nphi = 1 and the option
defaults are omp = 0, mode = mixed, lrt = no, balance = -1, tpc = 4,
tptask = 240. The default ghost option is determined by the pair
style being used. This value is output to the screen in the offload
report at the end of each run. Note that all of these settings,
except "omp" and "mode", are ignored if LAMMPS was not built with Xeon
Phi co-processor support. These settings are made automatically if the
"-sf intel" :doc:`command-line switch <Run_options>` is used. If it is
not used, you must invoke the package intel command in your input
script or via the "-pk intel" :doc:`command-line switch <Run_options>`.
For the INTEL package, the default is Nphi = 1 and the option defaults are omp
= 0, mode = mixed, lrt = no, balance = -1, tpc = 4, tptask = 240, pppm_table =
yes. The default ghost option is determined by the pair style being used.
This value is output to the screen in the offload report at the end of each
run. Note that all of these settings, except "omp" and "mode", are ignored if
LAMMPS was not built with Xeon Phi co-processor support. These settings are
made automatically if the "-sf intel" :doc:`command-line switch <Run_options>`
is used. If it is not used, you must invoke the package intel command in your
input script or via the "-pk intel" :doc:`command-line switch <Run_options>`.
For the KOKKOS package, the option defaults for GPUs are neigh = full,
neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default
value, comm = device, neigh/transpose = off, gpu/aware = on. When
LAMMPS can safely detect that GPU-aware MPI is not available, the
default value of gpu/aware becomes "off". For CPUs or Xeon Phis, the
option defaults are neigh = half, neigh/qeq = half, newton = on,
binsize = 0.0, and comm = no. The option neigh/thread = on when there
are 16K atoms or less on an MPI rank, otherwise it is "off". These
settings are made automatically by the required "-k on"
:doc:`command-line switch <Run_options>`. You can change them by using
the package kokkos command in your input script or via the :doc:`-pk
neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default value,
comm = device, sort = device, neigh/transpose = off, gpu/aware = on. When
LAMMPS can safely detect that GPU-aware MPI is not available, the default value
of gpu/aware becomes "off". For CPUs or Xeon Phis, the option defaults are
neigh = half, neigh/qeq = half, newton = on, binsize = 0.0, comm = no, and sort
= no. The option neigh/thread = on when there are 16K atoms or less on an MPI
rank, otherwise it is "off". These settings are made automatically by the
required "-k on" :doc:`command-line switch <Run_options>`. You can change them
by using the package kokkos command in your input script or via the :doc:`-pk
kokkos command-line switch <Run_options>`.
For the OMP package, the default is Nthreads = 0 and the option
defaults are neigh = yes. These settings are made automatically if
the "-sf omp" :doc:`command-line switch <Run_options>` is used. If it
is not used, you must invoke the package omp command in your input
script or via the "-pk omp" :doc:`command-line switch <Run_options>`.
For the OMP package, the default is Nthreads = 0 and the option defaults are
neigh = yes. These settings are made automatically if the "-sf omp"
:doc:`command-line switch <Run_options>` is used. If it is not used, you must
invoke the package omp command in your input script or via the "-pk omp"
:doc:`command-line switch <Run_options>`.

167
doc/src/pair_aip_water_2dm.rst Normal file
View File

@ -0,0 +1,167 @@
.. index:: pair_style aip/water/2dm
.. index:: pair_style aip/water/2dm/opt
pair_style aip/water/2dm command
===================================
Accelerator Variant: *aip/water/2dm/opt*
Syntax
""""""
.. code-block:: LAMMPS
pair_style [hybrid/overlay ...] aip/water/2dm cutoff tap_flag
* cutoff = global cutoff (distance units)
* tap_flag = 0/1 to turn off/on the taper function
Examples
""""""""
.. code-block:: LAMMPS
pair_style hybrid/overlay aip/water/2dm 16.0 1
pair_coeff * * aip/water/2dm COH.aip.water.2dm C Ow Hw
pair_style hybrid/overlay aip/water/2dm 16.0 lj/cut/tip4p/long 2 3 1 1 0.1546 10 8.5
pair_coeff 2 2 lj/cut/tip4p/long 8.0313e-3 3.1589 # O-O
pair_coeff 2 3 lj/cut/tip4p/long 0.0 0.0 # O-H
pair_coeff 3 3 lj/cut/tip4p/long 0.0 0.0 # H-H
pair_coeff * * aip/water/2dm COH.aip.water.2dm C Ow Hw
Description
"""""""""""
.. versionadded:: 15Jun2023
The *aip/water/2dm* style computes the anisotropic interfacial potential
(AIP) potential for interfaces of water with two-dimensional (2D)
materials as described in :ref:`(Feng) <Feng>`.
.. math::
E = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\
V_{ij} = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)}
\left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] -
\frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}}
\cdot \frac{C_6}{r^6_{ij}} \right \}\\
\rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\
\rho_{ji}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\
f(\rho) = & C e^{ -( \rho / \delta )^2 } \\
{\rm Tap}(r_{ij}) = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 -
70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 +
84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 -
35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1
Where :math:`\mathrm{Tap}(r_{ij})` is the taper function which provides
a continuous cutoff (up to third derivative) for interatomic separations
larger than :math:`r_c` :doc:`pair_style ilp_graphene_hbn
<pair_ilp_graphene_hbn>`.
.. note::
This pair style uses the atomic normal vector definition from
:ref:`(Feng) <Feng>`), where the atomic normal vectors of the
hydrogen atoms are assumed to lie along the corresponding
oxygen-hydrogen bonds and the normal vector of the central oxygen
atom is defined as their average.
The provided parameter file, ``COH.aip.water.2dm``, is intended for use
with *metal* :doc:`units <units>`, with energies in meV. Two additional
parameters, *S*, and *rcut* are included in the parameter file. *S* is
designed to facilitate scaling of energies; *rcut* is the cutoff for an
internal, short distance neighbor list that is generated for speeding up
the calculation of the normals for all atom pairs.
.. note::
The parameters presented in the provided parameter file,
``COH.aip.water.2dm``, are fitted with the taper function enabled by
setting the cutoff equal to 16.0 Angstrom. Using a different cutoff
or taper function setting should be carefully checked as they can
lead to significant errors. These parameters provide a good
description in both short- and long-range interaction regimes. This
is essential for simulations in high pressure regime (i.e., the
interlayer distance is smaller than the equilibrium distance).
This potential must be used in combination with hybrid/overlay. Other
interactions can be set to zero using :doc:`pair_coeff settings
<pair_coeff>` with the pair style set to *none*\ .
This pair style tallies a breakdown of the total interlayer potential
energy into sub-categories, which can be accessed via the :doc:`compute
pair <compute_pair>` command as a vector of values of length 2. The 2
values correspond to the following sub-categories:
1. *E_vdW* = vdW (attractive) energy
2. *E_Rep* = Repulsive energy
To print these quantities to the log file (with descriptive column
headings) the following commands could be included in an input script:
.. code-block:: LAMMPS
compute 0 all pair aip/water/2dm
variable Evdw equal c_0[1]
variable Erep equal c_0[2]
thermo_style custom step temp epair v_Erep v_Evdw
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair style does not support the pair_modify mix, shift, table, and
tail options.
This pair style does not write their information to binary restart
files, since it is stored in potential files. Thus, you need to
re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
Restrictions
""""""""""""
This pair style is part of the INTERLAYER package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This pair style requires the newton setting to be *on* for pair
interactions.
The ``COH.aip.water.2dm`` potential file provided with LAMMPS is
parameterized for *metal* units. You can use this pair style with any
LAMMPS units, but you would need to create your own potential file with
parameters in the appropriate units, if your simulation does not use
*metal* units.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`,
:doc:`pair_none <pair_none>`,
:doc:`pair_style hybrid/overlay <pair_hybrid>`,
:doc:`pair_style drip <pair_drip>`,
:doc:`pair_style ilp_tmd <pair_ilp_tmd>`,
:doc:`pair_style saip_metal <pair_saip_metal>`,
:doc:`pair_style ilp_graphene_hbn <pair_ilp_graphene_hbn>`,
:doc:`pair_style pair_kolmogorov_crespi_z <pair_kolmogorov_crespi_z>`,
:doc:`pair_style pair_kolmogorov_crespi_full <pair_kolmogorov_crespi_full>`,
:doc:`pair_style pair_lebedeva_z <pair_lebedeva_z>`,
:doc:`pair_style pair_coul_shield <pair_coul_shield>`.
Default
"""""""
tap_flag = 1
----------
.. _Feng:
**(Feng)** Z. Feng and W. Ouyang et al., J. Phys. Chem. C. 127, 8704-8713 (2023).

32
doc/src/pair_dpd.rst
View File

@ -26,8 +26,8 @@ Syntax
pair_style dpd T cutoff seed
pair_style dpd/tstat Tstart Tstop cutoff seed
* T = temperature (temperature units)
* Tstart,Tstop = desired temperature at start/end of run (temperature units)
* T = temperature (temperature units) (dpd only)
* Tstart,Tstop = desired temperature at start/end of run (temperature units) (dpd/tstat only)
* cutoff = global cutoff for DPD interactions (distance units)
* seed = random # seed (positive integer)
@ -40,9 +40,9 @@ Examples
pair_coeff * * 3.0 1.0
pair_coeff 1 1 3.0 1.0 1.0
pair_style dpd/tstat 1.0 1.0 2.5 34387
pair_coeff * * 1.0
pair_coeff 1 1 1.0 1.0
pair_style hybrid/overlay lj/cut 2.5 dpd/tstat 1.0 1.0 2.5 34387
pair_coeff * * lj/cut 1.0 1.0
pair_coeff * * dpd/tstat 1.0
Description
"""""""""""
@ -53,7 +53,7 @@ Style *dpd* computes a force field for dissipative particle dynamics
Style *dpd/tstat* invokes a DPD thermostat on pairwise interactions,
which is equivalent to the non-conservative portion of the DPD force
field. This pairwise thermostat can be used in conjunction with any
:doc:`pair style <pair_style>`, and in leiu of per-particle thermostats
:doc:`pair style <pair_style>`, and instead of per-particle thermostats
like :doc:`fix langevin <fix_langevin>` or ensemble thermostats like
Nose Hoover as implemented by :doc:`fix nvt <fix_nh>`. To use
*dpd/tstat* as a thermostat for another pair style, use the
@ -105,14 +105,18 @@ commands:
* :math:`\gamma` (force/velocity units)
* cutoff (distance units)
The last coefficient is optional. If not specified, the global DPD
The cutoff coefficient is optional. If not specified, the global DPD
cutoff is used. Note that sigma is set equal to sqrt(2 T gamma),
where T is the temperature set by the :doc:`pair_style <pair_style>`
command so it does not need to be specified.
For style *dpd/tstat*, the coefficients defined for each pair of
atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same,
except that A is not included.
atoms types via the :doc:`pair_coeff <pair_coeff>` command are:
* :math:`\gamma` (force/velocity units)
* cutoff (distance units)
The cutoff coefficient is optional.
The GPU-accelerated versions of these styles are implemented based on
the work of :ref:`(Afshar) <Afshar>` and :ref:`(Phillips) <Phillips>`.
@ -135,6 +139,12 @@ the work of :ref:`(Afshar) <Afshar>` and :ref:`(Phillips) <Phillips>`.
numbers are applied and thus the individual forces and therefore
also the virial/pressure.
.. note::
For more consistent time integration and force computation you may
consider using :doc:`fix mvv/dpd <fix_mvv_dpd>` instead of :doc:`fix
nve <fix_nve>`.
----------
.. include:: accel_styles.rst
@ -206,7 +216,9 @@ command for more details.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`pair_style srp <pair_srp>`
:doc:`pair_style dpd/ext <pair_dpd_ext>`, :doc:`pair_coeff <pair_coeff>`,
:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
:doc:`pair_style srp <pair_srp>`, :doc:`fix mvv/dpd <fix_mvv_dpd>`.
Default
"""""""

39
doc/src/pair_dpd_ext.rst
View File

@ -18,7 +18,6 @@ Accelerator Variants: dpd/ext/tstat/kk dpd/ext/tstat/omp
Syntax
""""""
.. code-block:: LAMMPS
pair_style dpd/ext T cutoff seed
@ -32,16 +31,15 @@ Syntax
Examples
""""""""
.. code-block:: LAMMPS
pair_style dpd/ext 1.0 2.5 34387
pair_coeff 1 1 25.0 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 40.0 4.5 4.5 0.5 0.5 1.2
pair_style dpd/ext/tstat 1.0 1.0 2.5 34387
pair_coeff 1 1 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 4.5 4.5 0.5 0.5 1.2
pair_style hybrid/overlay lj/cut 2.5 dpd/ext/tstat 1.0 1.0 2.5 34387
pair_coeff * * lj/cut 1.0 1.0
pair_coeff * * 4.5 4.5 0.5 0.5 1.2
Description
"""""""""""
@ -128,20 +126,39 @@ the :doc:`pair_style <pair_style>` command so it does not need to be
specified.
For the style *dpd/ext/tstat*, the coefficients defined for each pair of
atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same,
except that A is not included.
atoms types via the :doc:`pair_coeff <pair_coeff>` command are:
* :math:`\gamma_{\parallel}` (force/velocity units)
* :math:`\gamma_{\perp}` (force/velocity units)
* :math:`s_{\parallel}` (unitless)
* :math:`s_{\perp}` (unitless)
* :math:`r_c` (distance units)
The last coefficient is optional.
.. note::
If you are modeling DPD polymer chains, you may want to use the
:doc:`pair_style srp <pair_srp>` command in conjunction with these pair
styles. It is a soft segmental repulsive potential (SRP) that can
styles. It is a soft segmental repulsive potential (SRP) that can
prevent DPD polymer chains from crossing each other.
.. note::
The virial calculation for pressure when using this pair style includes
all the components of force listed above, including the random force.
The virial calculation for pressure when using these pair styles
includes all the components of force listed above, including the
random force. Since the random force depends on random numbers,
everything that changes the order of atoms in the neighbor list
(e.g. different number of MPI ranks or a different neighbor list
skin distance) will also change the sequence in which the random
numbers are applied and thus the individual forces and therefore
also the virial/pressure.
.. note::
For more consistent time integration and force computation you may
consider using :doc:`fix mvv/dpd <fix_mvv_dpd>` instead of :doc:`fix
nve <fix_nve>`.
----------
@ -207,7 +224,7 @@ Related commands
:doc:`pair_style dpd <pair_dpd>`, :doc:`pair_coeff <pair_coeff>`,
:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
:doc:`pair_style srp <pair_srp>`
:doc:`pair_style srp <pair_srp>`, :doc:`fix mvv/dpd <fix_mvv_dpd>`.
**Default:** none

2
doc/src/pair_granular.rst
View File

@ -736,7 +736,7 @@ or
.. math::
E_{eff,ij} = \frac{E_{ij}}{2(1-\nu_{ij})}
E_{eff,ij} = \frac{E_{ij}}{2(1-\nu_{ij}^2)}
These pair styles write their information to :doc:`binary restart files <restart>`, so a pair_style command does not need to be
specified in an input script that reads a restart file.

20
doc/src/pair_ilp_graphene_hbn.rst
View File

@ -155,8 +155,8 @@ interactions.
The BNCH.ILP potential file provided with LAMMPS (see the potentials
directory) are parameterized for *metal* units. You can use this
potential with any LAMMPS units, but you would need to create your
BNCH.ILP potential file with coefficients listed in the appropriate
potential with any LAMMPS units, but you would need to create your own
custom BNCH.ILP potential file with coefficients listed in the appropriate
units, if your simulation does not use *metal* units.
Related commands
@ -181,6 +181,14 @@ tap_flag = 1
----------
.. _Ouyang1:
**(Ouyang1)** W. Ouyang, D. Mandelli, M. Urbakh and O. Hod, Nano Lett. 18, 6009-6016 (2018).
.. _Ouyang2:
**(Ouyang2)** W. Ouyang et al., J. Chem. Theory Comput. 16(1), 666-676 (2020).
.. _Leven1:
**(Leven1)** I. Leven, I. Azuri, L. Kronik and O. Hod, J. Chem. Phys. 140, 104106 (2014).
@ -196,11 +204,3 @@ tap_flag = 1
.. _Kolmogorov2:
**(Kolmogorov)** A. N. Kolmogorov, V. H. Crespi, Phys. Rev. B 71, 235415 (2005).
.. _Ouyang1:
**(Ouyang1)** W. Ouyang, D. Mandelli, M. Urbakh and O. Hod, Nano Lett. 18, 6009-6016 (2018).
.. _Ouyang2:
**(Ouyang2)** W. Ouyang et al., J. Chem. Theory Comput. 16(1), 666-676 (2020).

4
doc/src/pair_ilp_tmd.rst
View File

@ -135,8 +135,8 @@ interactions.
The TMD.ILP potential file provided with LAMMPS (see the potentials
directory) are parameterized for *metal* units. You can use this
potential with any LAMMPS units, but you would need to create your
BNCH.ILP potential file with coefficients listed in the appropriate
potential with any LAMMPS units, but you would need to create your own
custom TMD.ILP potential file with coefficients listed in the appropriate
units, if your simulation does not use *metal* units.
Related commands

2
doc/src/pair_kolmogorov_crespi_full.rst
View File

@ -129,7 +129,7 @@ interactions.
The CH.KC potential file provided with LAMMPS (see the potentials
folder) is parameterized for metal units. You can use this pair style
with any LAMMPS units, but you would need to create your own custom
CC.KC potential file with all coefficients converted to the appropriate
CH.KC potential file with all coefficients converted to the appropriate
units.
Related commands

8
doc/src/pair_lepton.rst
View File

@ -61,9 +61,11 @@ Description
.. versionadded:: 8Feb2023
.. versionchanged:: TBD
added pair styles *lepton* and *lepton/coul*
added pair style lepton/sphere
.. versionchanged:: 15Jun2023
added pair style *lepton/sphere*
Pair styles *lepton*, *lepton/coul*, *lepton/sphere* compute pairwise
interactions between particles which depend on the distance and have a
@ -76,7 +78,7 @@ instead reference the radii of the two atoms of the pair with "radi" and
:doc:`data files <read_data>` or the :doc:`set command <set>`.
Note that further constants in the expressions can be defined in the
same string as additional expressions separated by semi-colons as shown
same string as additional expressions separated by semicolons as shown
in the examples above.
The expression `"200.0*(r-1.5)^2"` represents a harmonic potential

21
doc/src/pair_lj.rst
View File

@ -43,8 +43,7 @@ given by
.. math::
E = 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} -
\left(\frac{\sigma}{r}\right)^6 \right]
\qquad r < r_c
\left(\frac{\sigma}{r}\right)^6 \right] \qquad r < r_c
:math:`r_c` is the cutoff.
@ -64,12 +63,24 @@ file or restart files read by the :doc:`read_data <read_data>` or
* :math:`\sigma` (distance units)
* LJ cutoff (distance units)
Note that :math:`\sigma` is defined in the LJ formula as the zero-crossing
distance for the potential, not as the energy minimum at :math:`2^{\frac{1}{6}} \sigma`.
The last coefficient is optional. If not specified, the global
LJ cutoff specified in the pair_style command is used.
Note that :math:`\sigma` is defined in the LJ formula as the
zero-crossing distance for the potential, *not* as the energy minimum at
:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The _same_ potential function becomes:
.. math::
E = \epsilon \left[ \left(\frac{r_0}{r}\right)^{12} -
2 \left(\frac{r_0}{r}\right)^6 \right] \qquad r < r_c
When using the minimum as reference width. In the literature both
formulations are used, but the describe the same potential, only the
:math:`\sigma` value must be computed by :math:`\sigma = r_0 /
2^{\frac{1}{6}}` for use with LAMMPS, if this latter formulation is
used.
----------
A version of these styles with a soft core, *lj/cut/soft*, suitable

2
doc/src/pair_lj_cut_sphere.rst
View File

@ -33,7 +33,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 15Jun2023
The *lj/cut/sphere* style compute the standard 12/6 Lennard-Jones potential,
given by

2
doc/src/pair_lj_expand_sphere.rst
View File

@ -33,7 +33,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 15Jun2023
The *lj/expand/sphere* style compute a 12/6 Lennard-Jones potential with
a distance shifted by :math:`\Delta = \frac{1}{2} (d_i + d_j)`, the

4
doc/src/pair_saip_metal.rst
View File

@ -134,8 +134,8 @@ interactions.
The CHAu.ILP potential file provided with LAMMPS (see the potentials
directory) are parameterized for *metal* units. You can use this
potential with any LAMMPS units, but you would need to create your
BNCH.ILP potential file with coefficients listed in the appropriate
potential with any LAMMPS units, but you would need to create your own
custom CHAu.ILP potential file with coefficients listed in the appropriate
units, if your simulation does not use *metal* units.
Related commands

1
doc/src/pair_style.rst
View File

@ -114,6 +114,7 @@ accelerated styles exist.
* :doc:`adp <pair_adp>` - angular dependent potential (ADP) of Mishin
* :doc:`agni <pair_agni>` - AGNI machine-learning potential
* :doc:`aip/water/2dm <pair_aip_water_2dm>` - anisotropic interfacial potential for water in 2d geometries
* :doc:`airebo <pair_airebo>` - AIREBO potential of Stuart
* :doc:`airebo/morse <pair_airebo>` - AIREBO with Morse instead of LJ
* :doc:`amoeba <pair_amoeba>` -

40
doc/src/print.rst
View File

@ -46,6 +46,20 @@ lines of output, the string can be enclosed in triple quotes, as in
the last example above. If the text string contains variables, they
will be evaluated and their current values printed.
.. versionadded:: 15Jun2023
support for vector style variables
See the :doc:`variable <variable>` command for a description of
*equal* and *vector* style variables which are typically the most
useful ones to use with the print command. Equal- and vector-style
variables can calculate formulas involving mathematical operations,
atom properties, group properties, thermodynamic properties, global
values calculated by a :doc:`compute <compute>` or :doc:`fix <fix>`,
or references to other :doc:`variables <variable>`. Vector-style
variables are printed in a bracketed, comma-separated format,
e.g. [1,2,3,4] or [12.5,2,4.6,10.1].
.. note::
As discussed on the :doc:`Commands parse <Commands_parse>` doc
@ -60,6 +74,15 @@ will be evaluated and their current values printed.
This is also explained on the :doc:`Commands parse
<Commands_parse>` doc page.
If you want the print command to be executed multiple times (with
changing variable values), there are 3 options. First, consider using
the :doc:`fix print <fix_print>` command, which will print a string
periodically during a simulation. Second, the print command can be
used as an argument to the *every* option of the :doc:`run <run>`
command. Third, the print command could appear in a section of the
input script that is looped over (see the :doc:`jump <jump>` and
:doc:`next <next>` commands).
If the *file* or *append* keyword is used, a filename is specified to
which the output will be written. If *file* is used, then the
filename is overwritten if it already exists. If *append* is used,
@ -74,23 +97,6 @@ logfile can be turned on or off as desired. In multi-partition
calculations, the *screen* option and the corresponding output only
apply to the screen and logfile of the individual partition.
If you want the print command to be executed multiple times (with
changing variable values), there are 3 options. First, consider using
the :doc:`fix print <fix_print>` command, which will print a string
periodically during a simulation. Second, the print command can be
used as an argument to the *every* option of the :doc:`run <run>`
command. Third, the print command could appear in a section of the
input script that is looped over (see the :doc:`jump <jump>` and
:doc:`next <next>` commands).
See the :doc:`variable <variable>` command for a description of *equal*
style variables which are typically the most useful ones to use with
the print command. Equal-style variables can calculate formulas
involving mathematical operations, atom properties, group properties,
thermodynamic properties, global values calculated by a
:doc:`compute <compute>` or :doc:`fix <fix>`, or references to other
:doc:`variables <variable>`.
Restrictions
""""""""""""
none

2
doc/src/read_dump.rst
View File

@ -132,7 +132,7 @@ files can be written by LAMMPS via the :doc:`dump dcd <dump>` command.
The *path* value specifies a list of directories which LAMMPS will
search for the molfile plugins appropriate to the specified *style*\ .
The syntax of the *path* value is like other search paths: it can
contain multiple directories separated by a colon (or semi-colon on
contain multiple directories separated by a colon (or semicolon on
windows). The *path* keyword is optional and defaults to ".",
i.e. the current directory.

21
doc/src/special_bonds.rst
View File

@ -92,9 +92,24 @@ The Coulomb factors are applied to any Coulomb (charge interaction)
term that the potential calculates. The LJ factors are applied to the
remaining terms that the potential calculates, whether they represent
LJ interactions or not. The weighting factors are a scaling
prefactor on the energy and force between the pair of atoms. A value
of 1.0 means include the full interaction; a value of 0.0 means
exclude it completely.
prefactor on the energy and force between the pair of atoms.
A value of 1.0 means include the full interaction without flagging the
pair as a "special pair"; a value of 0.0 means exclude the pair
completely from the neighbor list, except for pair styles that require a
:doc:`kspace style <kspace_style>` and pair styles :doc:`amoeba
<pair_amoeba>`, :doc:`hippo <pair_amoeba>`, :doc:`thole <pair_thole>`,
:doc:`coul/exclude <pair_coul>`, and pair styles that include
"coul/dsf" or "coul/wolf".
.. note::
To include pairs that would otherwise be excluded (so they are
included in the neighbor list for certain analysis compute styles),
you can use a very small but non-zero value like 1.0e-100 instead of
0.0. Due to using floating-point math, the computed force, energy,
and virial contributions from the pairs will be too small to cause
differences.
The first of the 3 coefficients (LJ or Coulombic) is the weighting
factor on 1-2 atom pairs, which are pairs of atoms directly bonded to

774
doc/src/variable.rst
View File

@ -11,12 +11,19 @@ Syntax
variable name style args ...
* name = name of variable to define
* style = *delete* or *index* or *loop* or *world* or *universe* or *uloop* or *string* or *format* or *getenv* or *file* or *atomfile* or *python* or *timer* or *internal* or *equal* or *vector* or *atom*
* style = *delete* or *atomfile* or *file* or *format* or *getenv* or *index* or *internal* or *loop* or *python* or *string* or *timer* or *uloop* or *universe* or *world* or *equal* or *vector* or *atom*
.. parsed-literal::
*delete* = no args
*atomfile* arg = filename
*file* arg = filename
*format* args = vname fstr
vname = name of equal-style variable to evaluate
fstr = C-style format string
*getenv* arg = one string
*index* args = one or more strings
*internal* arg = numeric value
*loop* args = N
N = integer size of loop, loop from 1 to N inclusive
*loop* args = N pad
@ -27,24 +34,18 @@ Syntax
*loop* args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100
*world* args = one string for each partition of processors
*universe* args = one or more strings
*python* arg = function
*string* arg = one string
*timer* arg = no arguments
*uloop* args = N
N = integer size of loop
*uloop* args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
*string* arg = one string
*format* args = vname fstr
vname = name of equal-style variable to evaluate
fstr = C-style format string
*getenv* arg = one string
*file* arg = filename
*atomfile* arg = filename
*python* arg = function
*timer* arg = no arguments
*internal* arg = numeric value
*equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
*universe* args = one or more strings
*world* args = one string for each partition of processors
*equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, built-in functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI, version, on, off, true, false, yes, no
thermo keywords = vol, ke, press, etc from :doc:`thermo_style <thermo_style>`
@ -66,13 +67,14 @@ Syntax
bound(group,dir,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label)
feature functions = is_active(category,feature), is_available(category,feature), is_defined(category,id)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label)
feature functions = is_available(category,feature), is_active(category,feature), is_defined(category,id)
atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
atom vector = id, mass, type, mol, radius, q, x, y, z, vx, vy, vz, fx, fy, fz
compute references = c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i]
fix references = f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i]
variable references = v_name, v_name[i]
vector initialization = [1,3,7,10] (for *vector* variables only)
Examples
""""""""
@ -95,6 +97,7 @@ Examples
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15 pad
variable str format x %.6g
variable myvec vector [1,3,7,10]
variable x delete
.. code-block:: LAMMPS
@ -252,9 +255,10 @@ commands before the variable would become exhausted. For example,
----------
This section describes how all the various variable styles are defined
and what they store. Except for the *equal* and *vector* and *atom*
styles, which are explained in the next section.
The next sections describe in how all the various variable styles are
defined and what they store. The styles are listed alphabetically,
except for the *equal* and *vector* and *atom* styles, which are
explained together after all the others.
Many of the styles store one or more strings. Note that a single
string can contain spaces (multiple words), if it is enclosed in
@ -262,111 +266,7 @@ quotes in the variable command. When the variable is substituted for
in another input script command, its returned string will then be
interpreted as multiple arguments in the expanded command.
For the *index* style, one or more strings are specified. Initially,
the first string is assigned to the variable. Each time a
:doc:`next <next>` command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
Index-style variables with a single string value can also be set by
using the :doc:`command-line switch -var <Run_options>`.
The *loop* style is identical to the *index* style except that the
strings are the integers from 1 to N inclusive, if only one argument N
is specified. This allows generation of a long list of runs
(e.g. 1000) without having to list N strings in the input script.
Initially, the string "1" is assigned to the variable. Each time a
:doc:`next <next>` command is used with the variable name, the next
string ("2", "3", etc) is assigned. All processors assign the same
string to the variable. The *loop* style can also be specified with
two arguments N1 and N2. In this case the loop runs from N1 to N2
inclusive, and the string N1 is initially assigned to the variable.
N1 <= N2 and N2 >= 0 is required.
For the *world* style, one or more strings are specified. There must
be one string for each processor partition or "world". LAMMPS can be
run with multiple partitions via the :doc:`-partition command-line
switch <Run_options>`. This variable command assigns one string to
each world. All processors in the world are assigned the same string.
The next command cannot be used with equal-style variables, since
there is only one value per world. This style of variable is useful
when you wish to run different simulations on different partitions, or
when performing a parallel tempering simulation (see the :doc:`temper
<temper>` command), to assign different temperatures to different
partitions.
For the *universe* style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". LAMMPS can be run with multiple partitions via the
:doc:`-partition command-line switch <Run_options>`. This variable
command initially assigns one string to each world. When a
:doc:`next <next>` command is encountered using this variable, the first
processor partition to encounter it, is assigned the next available
string. This continues until all the variable strings are consumed.
Thus, this command can be used to run 50 simulations on 8 processor
partitions. The simulations will be run one after the other on
whatever partition becomes available, until they are all finished.
Universe-style variables are incremented using the files
"tmp.lammps.variable" and "tmp.lammps.variable.lock" which you will
see in your directory during such a LAMMPS run.
The *uloop* style is identical to the *universe* style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
For the *string* style, a single string is assigned to the variable.
Two differences between this style and using the *index* style exist:
a variable with *string* style can be redefined, e.g. by another command later
in the input script, or if the script is read again in a loop. The other
difference is that *string* performs variable substitution even if the
string parameter is quoted.
For the *format* style, an equal-style or compatible variable is
specified along with a C-style format string, e.g. "%f" or "%.10g",
which must be appropriate for formatting a double-precision
floating-point value and may not have extra characters. The default
format is "%.15g". This variable style allows an equal-style variable
to be formatted precisely when it is evaluated.
Note that if you simply wish to print a variable value with desired
precision to the screen or logfile via the :doc:`print <print>` or
:doc:`fix print <fix_print>` commands, you can also do this by
specifying an "immediate" variable with a trailing colon and format
string, as part of the string argument of those commands. This is
explained on the :doc:`Commands parse <Commands_parse>` doc page.
For the *getenv* style, a single string is assigned to the variable
which should be the name of an environment variable. When the
variable is evaluated, it returns the value of the environment
variable, or an empty string if it not defined. This style of
variable can be used to adapt the behavior of LAMMPS input scripts via
environment variable settings, or to retrieve information that has
been previously stored with the :doc:`shell putenv <shell>` command.
Note that because environment variable settings are stored by the
operating systems, they persist even if the corresponding *getenv*
style variable is deleted, and also are set for sub-shells executed
by the :doc:`shell <shell>` command.
For the *file* style, a filename is provided which contains a list of
strings to assign to the variable, one per line. The strings can be
numeric values if desired. See the discussion of the next() function
below for equal-style variables, which will convert the string of a
file-style variable into a numeric value in a formula.
When a file-style variable is defined, the file is opened and the
string on the first line is read and stored with the variable. This
means the variable can then be evaluated as many times as desired and
will return that string. There are two ways to cause the next string
from the file to be read: use the :doc:`next <next>` command or the
next() function in an equal- or atom-style variable, as discussed
below.
The rules for formatting the file are as follows. A comment character
"#" can be used anywhere on a line; text starting with the comment
character is stripped. Blank lines are skipped. The first "word" of
a non-blank line, delimited by white-space, is the "string" assigned
to the variable.
----------
For the *atomfile* style, a filename is provided which contains one or
more sets of values, to assign on a per-atom basis to the variable.
@ -406,6 +306,97 @@ will be assigned to that atom. IDs can be listed in any order.
atoms is first set to 0.0. Thus values for atoms whose ID does not
appear in the set, will remain 0.0.
----------
For the *file* style, a filename is provided which contains a list of
strings to assign to the variable, one per line. The strings can be
numeric values if desired. See the discussion of the next() function
below for equal-style variables, which will convert the string of a
file-style variable into a numeric value in a formula.
When a file-style variable is defined, the file is opened and the
string on the first line is read and stored with the variable. This
means the variable can then be evaluated as many times as desired and
will return that string. There are two ways to cause the next string
from the file to be read: use the :doc:`next <next>` command or the
next() function in an equal- or atom-style variable, as discussed
below.
The rules for formatting the file are as follows. A comment character
"#" can be used anywhere on a line; text starting with the comment
character is stripped. Blank lines are skipped. The first "word" of
a non-blank line, delimited by white-space, is the "string" assigned
to the variable.
----------
For the *format* style, an equal-style or compatible variable is
specified along with a C-style format string, e.g. "%f" or "%.10g",
which must be appropriate for formatting a double-precision
floating-point value and may not have extra characters. The default
format is "%.15g". This variable style allows an equal-style variable
to be formatted precisely when it is evaluated.
Note that if you simply wish to print a variable value with desired
precision to the screen or logfile via the :doc:`print <print>` or
:doc:`fix print <fix_print>` commands, you can also do this by
specifying an "immediate" variable with a trailing colon and format
string, as part of the string argument of those commands. This is
explained on the :doc:`Commands parse <Commands_parse>` doc page.
----------
For the *getenv* style, a single string is assigned to the variable
which should be the name of an environment variable. When the
variable is evaluated, it returns the value of the environment
variable, or an empty string if it not defined. This style of
variable can be used to adapt the behavior of LAMMPS input scripts via
environment variable settings, or to retrieve information that has
been previously stored with the :doc:`shell putenv <shell>` command.
Note that because environment variable settings are stored by the
operating systems, they persist even if the corresponding *getenv*
style variable is deleted, and also are set for sub-shells executed
by the :doc:`shell <shell>` command.
----------
For the *index* style, one or more strings are specified. Initially,
the first string is assigned to the variable. Each time a
:doc:`next <next>` command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
Index-style variables with a single string value can also be set by
using the :doc:`command-line switch -var <Run_options>`.
----------
For the *internal* style a numeric value is provided. This value will
be assigned to the variable until a LAMMPS command sets it to a new
value. There are currently only two LAMMPS commands that require
*internal* variables as inputs, because they reset them:
:doc:`create_atoms <create_atoms>` and :doc:`fix controller
<fix_controller>`. As mentioned above, an internal-style variable can
be used in place of an equal-style variable anywhere else in an input
script, e.g. as an argument to another command that allows for
equal-style variables.
----------
The *loop* style is identical to the *index* style except that the
strings are the integers from 1 to N inclusive, if only one argument N
is specified. This allows generation of a long list of runs
(e.g. 1000) without having to list N strings in the input script.
Initially, the string "1" is assigned to the variable. Each time a
:doc:`next <next>` command is used with the variable name, the next
string ("2", "3", etc) is assigned. All processors assign the same
string to the variable. The *loop* style can also be specified with
two arguments N1 and N2. In this case the loop runs from N1 to N2
inclusive, and the string N1 is initially assigned to the variable.
N1 <= N2 and N2 >= 0 is required.
----------
For the *python* style a Python function name is provided. This needs
to match a function name specified in a :doc:`python <python>` command
which returns a value to this variable as defined by its *return*
@ -433,25 +424,52 @@ python-style variable can be used in place of an equal-style variable
anywhere in an input script, e.g. as an argument to another command
that allows for equal-style variables.
For the *timer* style no additional argument is specified. The value of
the variable is set by querying the current elapsed wall time of the
simulation. This is done at the point in time when the variable is
defined in the input script. If a second timer-style variable is also
defined, then a simple formula can be used to calculate the elapsed time
between the two timers, as in the example at the top of this manual
entry. As mentioned above, timer-style variables can be redefined
elsewhere in the input script, so the same pair of variables can be used
in a loop or to time a series of operations.
----------
For the *internal* style a numeric value is provided. This value will
be assigned to the variable until a LAMMPS command sets it to a new
value. There are currently only two LAMMPS commands that require
*internal* variables as inputs, because they reset them:
:doc:`create_atoms <create_atoms>` and :doc:`fix controller
<fix_controller>`. As mentioned above, an internal-style variable can
be used in place of an equal-style variable anywhere else in an input
script, e.g. as an argument to another command that allows for
equal-style variables.
For the *string* style, a single string is assigned to the variable.
Two differences between this style and using the *index* style exist:
a variable with *string* style can be redefined, e.g. by another command later
in the input script, or if the script is read again in a loop. The other
difference is that *string* performs variable substitution even if the
string parameter is quoted.
----------
The *uloop* style is identical to the *universe* style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
----------
For the *universe* style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". LAMMPS can be run with multiple partitions via the
:doc:`-partition command-line switch <Run_options>`. This variable
command initially assigns one string to each world. When a
:doc:`next <next>` command is encountered using this variable, the first
processor partition to encounter it, is assigned the next available
string. This continues until all the variable strings are consumed.
Thus, this command can be used to run 50 simulations on 8 processor
partitions. The simulations will be run one after the other on
whatever partition becomes available, until they are all finished.
Universe-style variables are incremented using the files
"tmp.lammps.variable" and "tmp.lammps.variable.lock" which you will
see in your directory during such a LAMMPS run.
----------
For the *world* style, one or more strings are specified. There must
be one string for each processor partition or "world". LAMMPS can be
run with multiple partitions via the :doc:`-partition command-line
switch <Run_options>`. This variable command assigns one string to
each world. All processors in the world are assigned the same string.
The next command cannot be used with equal-style variables, since
there is only one value per world. This style of variable is useful
when you wish to run different simulations on different partitions, or
when performing a parallel tempering simulation (see the :doc:`temper
<temper>` command), to assign different temperatures to different
partitions.
----------
@ -495,36 +513,39 @@ is a valid (though strange) variable formula:
Specifically, a formula can contain numbers, constants, thermo
keywords, math operators, math functions, group functions, region
functions, atom values, atom vectors, compute references, fix
references, and references to other variables.
functions, special functions, feature functions, atom values, atom
vectors, compute references, fix references, and references to other
variables.
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Number | 0.2, 100, 1.0e20, -15.4, etc |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Constant | PI, version, on, off, true, false, yes, no |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Thermo keywords | vol, pe, ebond, etc |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Math operators | (), -x, x+y, x-y, x\*y, x/y, x\^y, x%y, x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x \|\| y, x \|\^ y, !x |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Math functions | sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), logfreq2(x,y,z), logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Group functions | count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), label2type(kind,label) |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Atom values | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Atom vectors | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Compute references | c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Fix references | f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Other variables | v_name, v_name[i] |
+--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Number | 0.2, 100, 1.0e20, -15.4, etc |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Constant | PI, version, on, off, true, false, yes, no |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Thermo keywords | vol, pe, ebond, etc |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Math operators | (), -x, x+y, x-y, x\*y, x/y, x\^y, x%y, x == y, x != y, x < y, x <= y, x > y, x >= y, x && y, x \|\| y, x \|\^ y, !x |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Math functions | sqrt(x), exp(x), ln(x), log(x), abs(x), sin(x), cos(x), tan(x), asin(x), acos(x), atan(x), atan2(y,x), random(x,y,z), normal(x,y,z), ceil(x), floor(x), round(x), ramp(x,y), stagger(x,y), logfreq(x,y,z), logfreq2(x,y,z), logfreq3(x,y,z), stride(x,y,z), stride2(x,y,z,a,b,c), vdisplace(x,y), swiggle(x,y,z), cwiggle(x,y,z) |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Group functions | count(ID), mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim), bound(ID,dir), gyration(ID), ke(ID), angmom(ID,dim), torque(ID,dim), inertia(ID,dimdim), omega(ID,dim) |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label) |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Feature functions | is_available(category,feature), is_active(category,feature), is_defined(category,id) |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Atom values | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i] |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Atom vectors | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Compute references | c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i] |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Fix references | f_ID, f_ID[i], f_ID[i][j], F_ID, F_ID[i] |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Other variables | v_name, v_name[i] |
+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Most of the formula elements produce a scalar value. Some produce a
global or per-atom vector of values. Global vectors can be produced
@ -574,9 +595,9 @@ will not work, since the *version* has been introduced more recently):
if $(version<20140513) then "communicate vel yes" else "comm_modify vel yes"
The thermo keywords allowed in a formula are those defined by the
:doc:`thermo_style custom <thermo_style>` command. Thermo keywords that
require a :doc:`compute <compute>` to calculate their values such as
"temp" or "press", use computes stored and invoked by the
:doc:`thermo_style custom <thermo_style>` command. Thermo keywords
that require a :doc:`compute <compute>` to calculate their values such
as "temp" or "press", use computes stored and invoked by the
:doc:`thermo_style <thermo_style>` command. This means that you can
only use those keywords in a variable if the style you are using with
the thermo_style command (and the thermo keywords associated with that
@ -714,10 +735,12 @@ new timestep. X,y,z > 0 and y < z are required. The generated
timesteps are on a base-z logarithmic scale, starting with x, and the
y value is how many of the z-1 possible timesteps within one
logarithmic interval are generated. I.e. the timesteps follow the
sequence x,2x,3x,...y\*x,x\*z,2x\*z,3x\*z,...y\*x\*z,x\*z\^2,2x\*z\^2,etc. For
sequence
x,2x,3x,...y\*x,x\*z,2x\*z,3x\*z,...y\*x\*z,x\*z\^2,2x\*z\^2,etc. For
any current timestep, the next timestep in the sequence is returned.
Thus if logfreq(100,4,10) is used in a variable by the :doc:`dump_modify every <dump_modify>` command, it will generate this sequence of
output timesteps:
Thus if logfreq(100,4,10) is used in a variable by the
:doc:`dump_modify every <dump_modify>` command, it will generate this
sequence of output timesteps:
.. parsed-literal::
@ -726,9 +749,10 @@ output timesteps:
The logfreq2(x,y,z) function is similar to logfreq, except a single
logarithmic interval is divided into y equally-spaced timesteps and
all of them are output. Y < z is not required. Thus, if
logfreq2(100,18,10) is used in a variable by the :doc:`dump_modify every <dump_modify>` command, then the interval between 100 and
1000 is divided as 900/18 = 50 steps, and it will generate the
sequence of output timesteps:
logfreq2(100,18,10) is used in a variable by the :doc:`dump_modify
every <dump_modify>` command, then the interval between 100 and 1000
is divided as 900/18 = 50 steps, and it will generate the sequence of
output timesteps:
.. parsed-literal::
@ -970,53 +994,94 @@ types, bond types and so on. For the full list of available keywords
*name* and their meaning, see the documentation for extract_setting()
via the link in this paragraph.
The label2type() function converts type labels into numeric types, using label
maps created by the :doc:`labelmap <labelmap>` or :doc:`read_data <read_data>`
commands. The first argument is the label map kind (atom, bond, angle,
dihedral, or improper) and the second argument is the label. The function
returns the corresponding numeric type.
The label2type(kind,label) function converts type labels into numeric
types, using label maps created by the :doc:`labelmap <labelmap>` or
:doc:`read_data <read_data>` commands. The first argument is the label
map kind (atom, bond, angle, dihedral, or improper) and the second
argument is the label. The function returns the corresponding numeric
type or triggers an error if the queried label does not exist.
.. versionadded:: 15Jun2023
The is_typelabel(kind,label) function has the same arguments as
label2type(), but returns 1 if the type label has been assigned,
otherwise it returns 0. This function can be used to check if a
particular type label already exists in the simulation.
----------
Feature Functions
-----------------
Feature functions allow to probe the running LAMMPS executable for
whether specific features are either active, defined, or available. The
functions take two arguments, a *category* and a corresponding
*argument*\ . The arguments are strings and thus cannot be formulas
Feature functions allow probing of the running LAMMPS executable for
whether specific features are available, active, or defined. All 3 of
the functions take two arguments, a *category* and a category-specific
second argument. Both are strings and thus cannot be formulas
themselves; only $-style immediate variable expansion is possible.
Return value is either 1.0 or 0.0 depending on whether the function
evaluates to true or false, respectively.
The return value of the functions is either 1.0 or 0.0 depending on
whether the function evaluates to true or false, respectively.
The *is_active(category,feature)* function allows to query for active
settings which are grouped by categories. Currently supported categories
and arguments are:
The *is_available(category,name)* function queries whether a specific
feature is available in the LAMMPS executable that is being run, i.e
whether it was included or enabled at compile time.
* *package*\ : argument = *gpu* or *intel* or *kokkos* or *omp*
* *newton*\ : argument = *pair* or *bond* or *any*
* *pair*\ : argument = *single* or *respa* or *manybody* or *tail* or *shift*
* *comm_style*\ : argument = *brick* or *tiled*
* *min_style*\ : argument = any of the compiled in minimizer styles
* *run_style*\ : argument = any of the compiled in run styles
* *atom_style*\ : argument = any of the compiled in atom style)
* *pair_style*\ : argument = any of the compiled in pair styles
* *bond_style*\ : argument = any of the compiled in bond styles
* *angle_style*\ : argument = any of the compiled in angle styles
* *dihedral_style*\ : argument = any of the compiled in dihedral styles
* *improper_style*\ : argument = any of the compiled in improper styles
* *kspace_style*\ : argument = any of the compiled in kspace styles
This supports the following categories: *command*, *compute*, *fix*,
*pair_style* and *feature*\ . For all the categories except *feature*
the *name* is a style name, e.g. *nve* for the *fix* category. Note
that many LAMMPS input script commands such as *create_atoms* are
actually instances of a command style which LAMMPS defines, as opposed
to built-in commands. For all of these styles except *command*,
appending of active suffixes is also tried before reporting failure.
Most of the settings are self-explanatory, the *single* argument in the
*pair* category allows to check whether a pair style supports a
Pair::single() function as needed by compute group/group and others
features or LAMMPS, *respa* allows to check whether the inner/middle/outer
mode of r-RESPA is supported. In the various style categories,
the checking is also done using suffix flags, if available and enabled.
The *feature* category checks the availability of the following
compile-time enabled features: GZIP support, PNG support, JPEG
support, FFMPEG support, and C++ exceptions for error
handling. Corresponding names are *gzip*, *png*, *jpeg*, *ffmpeg* and
*exceptions*\ .
Example 1: disable use of suffix for pppm when using GPU package
(i.e. run it on the CPU concurrently to running the pair style on the
GPU), but do use the suffix otherwise (e.g. with OPENMP).
Example: Only dump in a given format if the compiled binary supports it.
.. code-block:: LAMMPS
if "$(is_available(feature,png))" then "print 'PNG supported'" else "print 'PNG not supported'"
if "$(is_available(feature,ffmpeg)" then "dump 3 all movie 25 movie.mp4 type type zoom 1.6 adiam 1.0"
The *is_active(category,feature)* function queries whether a specific
feature is currently active within LAMMPS. The features are grouped
by categories. Supported categories and features are:
* *package*\ : features = *gpu* or *intel* or *kokkos* or *omp*
* *newton*\ : features = *pair* or *bond* or *any*
* *pair*\ : features = *single* or *respa* or *manybody* or *tail* or *shift*
* *comm_style*\ : features = *brick* or *tiled*
* *min_style*\ : features = a minimizer style name
* *run_style*\ : features = a run style name
* *atom_style*\ : features = an atom style name
* *pair_style*\ : features = a pair style name
* *bond_style*\ : features = a bond style name
* *angle_style*\ : features = an angle style name
* *dihedral_style*\ : features = a dihedral style name
* *improper_style*\ : features = an improper style name
* *kspace_style*\ : features = a kspace style name
Most of the settings are self-explanatory. For the *package*
category, a package may have been included in the LAMMPS build, but
not have enabled by any input script command, and hence be inactive.
The *single* feature in the *pair* category checks whether the
currently defined pair style supports a Pair::single() function as
needed by compute group/group and others features or LAMMPS.
Similarly, the *respa* feature checks whether the inner/middle/outer
mode of r-RESPA is supported by the current pair style.
For the categories with *style* in their name, only a single instance
of the style is ever active at any time in a LAMMPS simulation. Thus
the check is whether the currently active style matches the specified
name. This check is also done using suffix flags, if available and
enabled.
Example 1: Disable use of suffix for PPPM when using GPU package
(i.e. run it on the CPU concurrently while running the pair style on
the GPU), but do use the suffix otherwise (e.g. with OPENMP).
.. code-block:: LAMMPS
@ -1024,39 +1089,23 @@ GPU), but do use the suffix otherwise (e.g. with OPENMP).
if $(is_active(package,gpu)) then "suffix off"
kspace_style pppm
Example 2: use r-RESPA with inner/outer cutoff, if supported by pair
style, otherwise fall back to using pair and reducing the outer time
step
Example 2: Use r-RESPA with inner/outer cutoff, if supported by the
current pair style, otherwise fall back to using r-RESPA with simply
the pair keyword and reducing the outer time step.
.. code-block:: LAMMPS
timestep $(2.0*(1.0+2.0*is_active(pair,respa)))
if $(is_active(pair,respa)) then "run_style respa 4 3 2 2 improper 1 inner 2 5.5 7.0 outer 3 kspace 4" else "run_style respa 3 3 2 improper 1 pair 2 kspace 3"
if $(is_active(pair,respa)) then "run_style respa 4 3 2 2 improper 1 inner 2 5.5 7.0 outer 3 kspace 4" else "run_style respa 3 3 2 improper 1 pair 2 kspace 3"
The *is_available(category,name)* function allows to query whether
a specific optional feature is available, i.e. compiled in.
This currently works for the following categories: *command*,
*compute*, *fix*, *pair_style* and *feature*\ . For all categories
except *command* and *feature* also appending active suffixes is
tried before reporting failure.
The *feature* category is used to check the availability of compiled in
features such as GZIP support, PNG support, JPEG support, FFMPEG support,
and C++ exceptions for error handling. Corresponding values for name are
*gzip*, *png*, *jpeg*, *ffmpeg* and *exceptions*\ .
This enables writing input scripts which only dump using a given format if
the compiled binary supports it.
.. code-block:: LAMMPS
if "$(is_available(feature,png))" then "print 'PNG supported'" else "print 'PNG not supported'"
if "$(is_available(feature,ffmpeg)" then "dump 3 all movie 25 movie.mp4 type type zoom 1.6 adiam 1.0"
The *is_defined(categoy,id)* function allows to query categories like
*compute*, *dump*, *fix*, *group*, *region*, and *variable* whether an
entry with the provided name or id is defined.
The *is_defined(category,id)* function checks whether an instance of a
style or variable with a specific ID or name is currently defined
within LAMMPS. The supported categories are *compute*, *dump*,
*fix*, *group*, *region*, and *variable*. Each of these styles (as
well as the variable command) can be specified multiple times within
LAMMPS, each with a unique *id*. This function checks whether the
specified *id* exists. For category *variable", the *id* is the
variable name.
----------
@ -1268,6 +1317,35 @@ Vectors" discussion above.
----------
Vector Initialization
---------------------
.. versionadded:: 15Jun2023
*Vector*-style variables only can be initialized with a special
syntax, instead of using a formula. The syntax is a bracketed,
comma-separated syntax like the following:
.. code-block:: LAMMPS
variable myvec vector [1,3.5,7,10.2]
The 3rd argument formula is replaced by the vector values in brackets,
separated by commas. This example creates a 4-length vector with
specific numeric values, each of which can be specified as an integer
or floating point value. Note that while whitespace can be added
before or after individual values, no other mathematical operations
can be specified. E.g. "3*10" or "3*v_abc" are not valid vector
elements, nor is "10*[1,2,3,4]" valid for the entire vector.
Unlike vector variables specified with formulas, this vector variable
is static; its length and values never changes. Its values can be
used in other commands (including vector-style variables specified
with formulas) via the usual syntax for accessing individual vector
elements or the entire vector.
----------
Immediate Evaluation of Variables
"""""""""""""""""""""""""""""""""
@ -1285,18 +1363,19 @@ with a leading $ sign (e.g. $x or ${abc}) versus with a leading "v\_"
(e.g. v_x or v_abc). The former can be used in any input script
command, including a variable command. The input script parser
evaluates the reference variable immediately and substitutes its value
into the command. As explained on the :doc:`Commands parse <Commands_parse>` doc page, you can also use un-named
"immediate" variables for this purpose. For example, a string like
this $((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates
the string between the parenthesis as an equal-style variable formula.
into the command. As explained on the :doc:`Commands parse
<Commands_parse>` doc page, you can also use un-named "immediate"
variables for this purpose. For example, a string like this
$((xlo+xhi)/2+sqrt(v_area)) in an input script command evaluates the
string between the parenthesis as an equal-style variable formula.
Referencing a variable with a leading "v\_" is an optional or required
kind of argument for some commands (e.g. the :doc:`fix ave/chunk <fix_ave_chunk>` or :doc:`dump custom <dump>` or
:doc:`thermo_style <thermo_style>` commands) if you wish it to evaluate
a variable periodically during a run. It can also be used in a
variable formula if you wish to reference a second variable. The
second variable will be evaluated whenever the first variable is
evaluated.
kind of argument for some commands (e.g. the :doc:`fix ave/chunk
<fix_ave_chunk>` or :doc:`dump custom <dump>` or :doc:`thermo_style
<thermo_style>` commands) if you wish it to evaluate a variable
periodically during a run. It can also be used in a variable formula
if you wish to reference a second variable. The second variable will
be evaluated whenever the first variable is evaluated.
As an example, suppose you use this command in your input script to
define the variable "v" as
@ -1309,8 +1388,9 @@ before a run where the simulation box size changes. You might think
this will assign the initial volume to the variable "v". That is not
the case. Rather it assigns a formula which evaluates the volume
(using the thermo_style keyword "vol") to the variable "v". If you
use the variable "v" in some other command like :doc:`fix ave/time <fix_ave_time>` then the current volume of the box will be
evaluated continuously during the run.
use the variable "v" in some other command like :doc:`fix ave/time
<fix_ave_time>` then the current volume of the box will be evaluated
continuously during the run.
If you want to store the initial volume of the system, you can do it
this way:
@ -1347,132 +1427,75 @@ will occur when the formula for "vratio" is evaluated later.
Variable Accuracy
"""""""""""""""""
Obviously, LAMMPS attempts to evaluate variables containing formulas
(\ *equal* and *atom* style variables) accurately whenever the
evaluation is performed. Depending on what is included in the
formula, this may require invoking a :doc:`compute <compute>`, either
directly or indirectly via a thermo keyword, or accessing a value
previously calculated by a compute, or accessing a value calculated
and stored by a :doc:`fix <fix>`. If the compute is one that calculates
the pressure or energy of the system, then these quantities need to be
tallied during the evaluation of the interatomic potentials (pair,
bond, etc) on timesteps that the variable will need the values.
Obviously, LAMMPS attempts to evaluate variables which contain
formulas (\ *equal* and *vector* and *atom* style variables)
accurately whenever the evaluation is performed. Depending on what is
included in the formula, this may require invoking a :doc:`compute
<compute>`, either directly or indirectly via a thermo keyword, or
accessing a value previously calculated by a compute, or accessing a
value calculated and stored by a :doc:`fix <fix>`. If the compute is
one that calculates the energy or pressure of the system, then the
corresponding energy or virial quantities need to be tallied during
the evaluation of the interatomic potentials (pair, bond, etc) on any
timestep that the variable needs the tallies. An input script can
also request variables be evaluated before or after or in between
runs, e.g. by including them in a :doc:`print <print>` command.
LAMMPS keeps track of all of this during a :doc:`run <run>` or :doc:`energy minimization <minimize>`. An error will be generated if you
attempt to evaluate a variable on timesteps when it cannot produce
accurate values. For example, if a :doc:`thermo_style custom <thermo_style>` command prints a variable which accesses
values stored by a :doc:`fix ave/time <fix_ave_time>` command and the
timesteps on which thermo output is generated are not multiples of the
averaging frequency used in the fix command, then an error will occur.
LAMMPS keeps track of all of this as it performs a doc:`run <run>` or
:doc:`minimize <minimize>` simulation, as well as in between
simulations. An error will be generated if you attempt to evaluate a
variable when LAMMPS knows it cannot produce accurate values. For
example, if a :doc:`thermo_style custom <thermo_style>` command prints
a variable which accesses values stored by a :doc:`fix ave/time
<fix_ave_time>` command and the timesteps on which thermo output is
generated are not multiples of the averaging frequency used in the fix
command, then an error will occur.
An input script can also request variables be evaluated before or
after or in between runs, e.g. by including them in a
:doc:`print <print>` command. In this case, if a compute is needed to
evaluate a variable (either directly or indirectly), LAMMPS will not
invoke the compute, but it will use a value previously calculated by
the compute, and can do this only if it was invoked on the current
timestep. Fixes will always provide a quantity needed by a variable,
but the quantity may or may not be current. This leads to one of
three kinds of behavior:
However, there are two special cases to be aware when a variable
requires invocation of a compute (directly or indirectly). The first
is if the variable is evaluated before the first doc:`run <run>` or
:doc:`minimize <minimize>` command in the input script. In this case,
LAMMPS will generate an error. This is because many computes require
initializations which have not yet taken place. One example is the
calculation of degrees of freedom for temperature computes. Another
example are the computes mentioned above which require tallying of
energy or virial quantities; these values are not tallied until the
first simulation begins.
(1) The variable may be evaluated accurately. If it contains
references to a compute or fix, and these values were calculated on
the last timestep of a preceding run, then they will be accessed and
used by the variable and the result will be accurate.
The second special case is when a variable that depends on a compute
is evaluated in between doc:`run <run>` or :doc:`minimize <minimize>`
commands. It is possible for other input script commands issued
following the previous run, but before the variable is evaluated, to
change the system. For example, the doc:`delete_atoms <delete_atoms>`
command could be used to remove atoms. Since the compute will not
re-initialize itself until the next simulation or it may depend on
energy/virial computations performed before the system was changed, it
will potentially generate an incorrect answer when evaluated. Note
that LAMMPS will not generate an error in this case; the evaluated
variable may simply be incorrect.
(2) LAMMPS may not be able to evaluate the variable and will generate
an error message stating so. For example, if the variable requires a
quantity from a :doc:`compute <compute>` that has not been invoked on
the current timestep, LAMMPS will generate an error. This means, for
example, that such a variable cannot be evaluated before the first run
has occurred. Likewise, in between runs, a variable containing a
compute cannot be evaluated unless the compute was invoked on the last
timestep of the preceding run, e.g. by thermodynamic output.
One way to get around this problem is to perform a 0-timestep run
before using the variable. For example, these commands
The way to get around both of these special cases is to perform a
0-timestep run before evaluating the variable. For example, these
commands
.. code-block:: LAMMPS
variable t equal temp
print "Initial temperature = $t"
# delete_atoms random fraction 0.5 yes all NULL 49839
# run 0 post no
variable t equal temp # this thermo keyword invokes a temperature compute
print "Temperature of system = $t"
run 1000
will generate an error if the run is the first run specified in the
input script, because generating a value for the "t" variable requires
a compute for calculating the temperature to be invoked.
will generate an error if the "run 1000" command is the first
simulation in the input script. If there were a previous run, these
commands will print the correct temperature of the system. But if the
:doc:`delete_atoms <delete_atoms>` command is uncommented, the printed
temperature will be incorrect, because information stored by
temperature compute is no longer valid.
However, this sequence of commands would be fine:
.. code-block:: LAMMPS
run 0
variable t equal temp
print "Initial temperature = $t"
run 1000
The 0-timestep run initializes and invokes various computes, including
the one for temperature, so that the value it stores is current and
can be accessed by the variable "t" after the run has completed. Note
that a 0-timestep run does not alter the state of the system, so it
does not change the input state for the 1000-timestep run that
follows. Also note that the 0-timestep run must actually use and
invoke the compute in question (e.g. via :doc:`thermo <thermo_style>` or
:doc:`dump <dump>` output) in order for it to enable the compute to be
used in a variable after the run. Thus if you are trying to print a
variable that uses a compute you have defined, you can ensure it is
invoked on the last timestep of the preceding run by including it in
thermodynamic output.
Unlike computes, :doc:`fixes <fix>` will never generate an error if
their values are accessed by a variable in between runs. They always
return some value to the variable. However, the value may not be what
you expect if the fix has not yet calculated the quantity of interest
or it is not current. For example, the :doc:`fix indent <fix_indent>`
command stores the force on the indenter. But this is not computed
until a run is performed. Thus if a variable attempts to print this
value before the first run, zeroes will be output. Again, performing
a 0-timestep run before printing the variable has the desired effect.
(3) The variable may be evaluated incorrectly and LAMMPS may have no
way to detect this has occurred. Consider the following sequence of
commands:
.. code-block:: LAMMPS
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
variable e equal pe
print "Final potential energy = $e"
The first run is performed using one setting for the pairwise
potential defined by the :doc:`pair_style <pair_style>` and
:doc:`pair_coeff <pair_coeff>` commands. The potential energy is
evaluated on the final timestep and stored by the :doc:`compute pe
<compute_pe>` compute (this is done by the :doc:`thermo_style
<thermo_style>` command). Then a pair coefficient is changed,
altering the potential energy of the system. When the potential
energy is printed via the "e" variable, LAMMPS will use the potential
energy value stored by the :doc:`compute pe <compute_pe>` compute,
thinking it is current. There are many other commands which could
alter the state of the system between runs, causing a variable to
evaluate incorrectly.
The solution to this issue is the same as for case (2) above, namely
perform a 0-timestep run before the variable is evaluated to ensure
the system is up-to-date. For example, this sequence of commands
would print a potential energy that reflected the changed pairwise
coefficient:
.. code-block:: LAMMPS
pair_coeff 1 1 1.0 1.0
run 1000
pair_coeff 1 1 1.5 1.0
run 0
variable e equal pe
print "Final potential energy = $e"
Both these issues are resolved, if the "run 0" command is uncommented.
This is because the "run 0" simulation will initialize (or
re-initialize) the temperature compute correctly.
----------
@ -1482,11 +1505,12 @@ Restrictions
Indexing any formula element by global atom ID, such as an atom value,
requires the :doc:`atom style <atom_style>` to use a global mapping in
order to look up the vector indices. By default, only atom styles
with molecular information create global maps. The :doc:`atom_modify map <atom_modify>` command can override the default, e.g. for
with molecular information create global maps. The :doc:`atom_modify
map <atom_modify>` command can override the default, e.g. for
atomic-style atom styles.
All *universe*\ - and *uloop*\ -style variables defined in an input script
must have the same number of values.
All *universe*\ - and *uloop*\ -style variables defined in an input
script must have the same number of values.
Related commands
""""""""""""""""

4
doc/utils/requirements.txt
View File

@ -1,8 +1,8 @@
Sphinx >= 5.0.0, <7.0.0
Sphinx >= 5.3.0, <7.1.0
sphinxcontrib-spelling
sphinxcontrib-jquery
git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs
git+https://github.com/executablebooks/sphinx-tabs@v3.4.1
breathe
Pygments
six

11
doc/utils/sphinx-config/false_positives.txt
View File

@ -55,6 +55,7 @@ Ai
Aidan
aij
aimd
aip
airebo
Aj
ajaramil
@ -528,6 +529,7 @@ collisional
Columic
colvars
Colvars
COH
COLVARS
comID
Commun
@ -550,6 +552,7 @@ conformational
Connor
conp
conq
const
ConstMatrix
Contrib
cooperativity
@ -1090,6 +1093,7 @@ Fellinger
femtosecond
femtoseconds
fene
Feng
Fennell
fep
FEP
@ -1562,6 +1566,7 @@ invertibility
ionicities
ionizable
ionocovalent
iOS
iostreams
iparam
ipi
@ -1620,6 +1625,7 @@ Izumi
Izvekov
izz
Izz
Jacobian
Jacobsen
Jadhao
Jadhav
@ -2026,6 +2032,7 @@ Marchetti
Marchi
Mariella
Marinica
Markland
Marrink
Marroquin
Marsaglia
@ -3594,6 +3601,7 @@ THz
Tigran
Tij
Tildesley
Timan
timeI
timespan
timestamp
@ -3735,6 +3743,8 @@ Umin
un
unary
uncomment
uncommented
uncompress
uncompute
underprediction
undump
@ -4088,4 +4098,5 @@ zu
zx
zy
Zybin
Zykova
zz

13
examples/COUPLE/README
View File

@ -19,12 +19,12 @@ See these sections of the LAMMPS manual for details:
Build LAMMPS as a library (doc/html/Build_basics.html)
Link LAMMPS as a library to another code (doc/html/Build_link.html)
Coupling LAMMPS to other codes (doc/html/Howto_couple.html)
Using LAMMPS in client/server mode (doc/html/Howto_client_server.html)
Library interface to LAMMPS (doc/html/Howto_library.html)
Detailed documentation of the LAMMPS interfaces (doc/html/Library.html)
The library interface to LAMMPS is in src/library.cpp. Routines can
be easily added to this file so an external program can perform the
LAMMPS tasks desired.
The core library interface to LAMMPS is in src/library.cpp. Routines
can be easily added to this file so an external program can perform
the LAMMPS tasks desired.
-------------------------------------------------------------------
@ -36,10 +36,5 @@ plugin example for loading LAMMPS at runtime from a shared library
lammps_spparks grain-growth Monte Carlo with strain via MD,
coupling to SPPARKS kinetic MC code
library collection of useful inter-code communication routines
fortran2 a more sophisticated wrapper on the LAMMPS library API that
can be called from Fortran
fortran_dftb wrapper written by Nir Goldman (LLNL), as an
extension to fortran2, used for calling LAMMPS
from Fortran DFTB+ tight-binding code
Each sub-directory has its own README with more details.

1
examples/COUPLE/fortran2/.gitignore vendored
View File

@ -1 +0,0 @@
*.mod

96
examples/COUPLE/fortran2/LAMMPS-wrapper.cpp
View File

@ -1,96 +0,0 @@
/* -----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ------------------------------------------------------------------------
Contributing author: Karl D. Hammond <hammondkd@missouri.edu>
University of Missouri (USA), 2012
------------------------------------------------------------------------- */
/* This is set of "wrapper" functions to assist LAMMPS.F90, which itself
provides a (I hope) robust Fortran interface to library.cpp and
library.h. All functions herein COULD be added to library.cpp instead of
including this as a separate file. See the README for instructions. */
#include <mpi.h>
#include "LAMMPS-wrapper.h"
#define LAMMPS_LIB_MPI 1
#include <library.h>
#include <lammps.h>
#include <atom.h>
#include <fix.h>
#include <compute.h>
#include <modify.h>
#include <error.h>
#include <cstdlib>
using namespace LAMMPS_NS;
void lammps_open_fortran_wrapper (int argc, char **argv,
MPI_Fint communicator, void **ptr)
{
MPI_Comm C_communicator = MPI_Comm_f2c (communicator);
lammps_open (argc, argv, C_communicator, ptr);
}
int lammps_get_ntypes (void *ptr)
{
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ntypes = lmp->atom->ntypes;
return ntypes;
}
void lammps_error_all (void *ptr, const char *file, int line, const char *str)
{
class LAMMPS *lmp = (class LAMMPS *) ptr;
lmp->error->all (file, line, str);
}
int lammps_extract_compute_vectorsize (void *ptr, char *id, int style)
{
int *size;
size = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_VECTOR);
if (size) return *size;
return 0;
}
void lammps_extract_compute_arraysize (void *ptr, char *id, int style,
int *nrows, int *ncols)
{
int *tmp;
tmp = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_ROWS);
if (tmp) *nrows = *tmp;
tmp = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_COLS);
if (tmp) *ncols = *tmp;
return;
}
int lammps_extract_fix_vectorsize (void *ptr, char *id, int style)
{
int *size;
size = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_VECTOR, 0, 0);
if (size) return *size;
return 0;
}
void lammps_extract_fix_arraysize (void *ptr, char *id, int style,
int *nrows, int *ncols)
{
int *tmp;
tmp = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_ROWS, 0, 0);
if (tmp) *nrows = *tmp;
tmp = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_COLS, 0, 0);
if (tmp) *ncols = *tmp;
return;
}
/* vim: set ts=3 sts=3 expandtab: */

41
examples/COUPLE/fortran2/LAMMPS-wrapper.h
View File

@ -1,41 +0,0 @@
/* -----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ------------------------------------------------------------------------
Contributing author: Karl D. Hammond <hammondkd@missouri.edu>
University of Missouri (USA), 2012
------------------------------------------------------------------------- */
/* This is set of "wrapper" functions to assist LAMMPS.F90, which itself
provides a (I hope) robust Fortran interface to library.cpp and
library.h. All prototypes herein COULD be added to library.h instead of
including this as a separate file. See the README for instructions. */
#ifdef __cplusplus
extern "C" {
#endif
/* Prototypes for auxiliary functions */
void lammps_open_fortran_wrapper (int, char**, MPI_Fint, void**);
int lammps_get_ntypes (void*);
int lammps_extract_compute_vectorsize (void*, char*, int);
void lammps_extract_compute_arraysize (void*, char*, int, int*, int*);
int lammps_extract_fix_vectorsize (void*, char*, int);
void lammps_extract_fix_arraysize (void*, char*, int, int*, int*);
void lammps_error_all (void*, const char*, int, const char*);
#ifdef __cplusplus
}
#endif
/* vim: set ts=3 sts=3 expandtab: */

1788
examples/COUPLE/fortran2/LAMMPS.F90
View File

File diff suppressed because it is too large Load Diff

41
examples/COUPLE/fortran2/Makefile
View File

@ -1,41 +0,0 @@
SHELL = /bin/sh
# Path to LAMMPS extraction directory
LAMMPS_ROOT = ../../..
LAMMPS_SRC = $(LAMMPS_ROOT)/src
# Uncomment the line below if using the MPI stubs library
MPI_STUBS = #-I$(LAMMPS_SRC)/STUBS
FC = mpifort # replace with your Fortran compiler
CXX = mpicxx # replace with your C++ compiler
CXXLIB = -lstdc++ # replace with your C++ runtime libs
# Flags for Fortran compiler, C++ compiler, and C preprocessor, respectively
FFLAGS = -O2 -fPIC
CXXFLAGS = -O2 -fPIC
CPPFLAGS = -DOMPI_SKIP_MPICXX=1 -DMPICH_SKIP_MPICXX
all : liblammps_fortran.a liblammps_fortran.so
@echo "WARNING: this Fortran interface is obsolete and is no longer
maintained. See $(LAMMPS_ROOT)/fortran for the new, maintained interface
(largely written by the same author). You may continue to use this interface if
desired, but it may eventually be removed from LAMMPS."
liblammps_fortran.so : LAMMPS.o LAMMPS-wrapper.o
$(FC) $(FFLAGS) -shared -o $@ $^ $(CXXLIB)
liblammps_fortran.a : LAMMPS.o LAMMPS-wrapper.o
$(AR) rs $@ $^
LAMMPS.o lammps.mod : LAMMPS.F90
$(FC) $(CPPFLAGS) $(FFLAGS) -c $<
LAMMPS-wrapper.o : LAMMPS-wrapper.cpp LAMMPS-wrapper.h
$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -I$(LAMMPS_SRC) $(MPI_STUBS)
clean :
$(RM) *.o *.mod liblammps_fortran.a liblammps_fortran.so
dist :
tar -czf Fortran-interface.tar.gz LAMMPS-wrapper.h LAMMPS-wrapper.cpp LAMMPS.F90 makefile README

273
examples/COUPLE/fortran2/README
View File

@ -1,273 +0,0 @@
!! NOTE -------------------------------------------------------------------
! This interface is obsolete and may be removed in a future release of
! LAMMPS. The interface in fortran/lammps.f90 replaces this one. That API
! is maintained by the LAMMPS developers and has documentation written for
! it; it is based loosely on this one, but binds all procedures to a lammps
! derived type. That interface was written in large
! part by the same author, but is also supported by other developers.
!--------------------------------------------------------------------------
LAMMPS.F90 defines a Fortran 2003 module, LAMMPS, which wraps all functions in
src/library.h so they can be used directly from Fortran-encoded programs.
All functions in src/library.h that use and/or return C-style pointers have
Fortran wrapper functions that use Fortran-style arrays, pointers, and
strings; all C-style memory management is handled internally with no user
intervention. See --USE-- for notes on how this interface differs from the
C interface (and the Python interface).
This interface was created by Karl Hammond who you can contact with
questions:
Karl D. Hammond
University of Missouri
hammondkd at missouri.edu
-------------------------------------
--COMPILATION--
First, be advised that mixed-language programming is not trivial. It requires
you to link in the required libraries of all languages you use (in this case,
those for Fortran, C, and C++), as well as any other libraries required.
You are also advised to read the --USE-- section below before trying to
compile.
The following steps will work to compile this module (replace ${LAMMPS_SRC}
with the path to your LAMMPS source directory).
Steps 3-5 are accomplished, possibly after some modifications to
the makefile, by make using the attached makefile. Said makefile also builds
the dynamically-linkable library (liblammps_fortran.so).
** STATIC LIBRARY INSTRUCTIONS **
(1) Compile LAMMPS as a static library.
Call the resulting file ${LAMMPS_LIB}, which will have an actual name
like liblmp_openmpi.a. If compiling using the MPI stubs in
${LAMMPS_SRC}/STUBS, you will need to know where libmpi_stubs.a
is as well (I'll call it ${MPI_STUBS} hereafter)
(2) Copy said library to your Fortran program's source directory or replace
${LAMMPS_LIB} with its full path in the instructions below.
(3) Compile (but don't link!) LAMMPS.F90. Example:
mpifort -c LAMMPS.f90
OR
gfortran -c LAMMPS.F90
NOTE: you may get a warning such as,
subroutine lammps_open_wrapper (argc, argv, communicator, ptr) &
Variable 'communicator' at (1) is a parameter to the BIND(C)
procedure 'lammps_open_wrapper' but may not be C interoperable
This is normal (see --IMPLEMENTATION NOTES--).
(4) Compile (but don't link) LAMMPS-wrapper.cpp. You will need its header
file as well. You will have to provide the locations of LAMMPS's
header files. For example,
mpicxx -c -I${LAMMPS_SRC} LAMMPS-wrapper.cpp
OR
g++ -c -I${LAMMPS_SRC} -I${LAMMPS_SRC}/STUBS LAMMPS-wrapper.cpp
OR
icpc -c -I${LAMMPS_SRC} -I${LAMMPS_SRC}/STUBS LAMMPS-wrapper.cpp
(5) OPTIONAL: Make a library from the object files so you can carry around
two files instead of three. Example:
ar rs liblammps_fortran.a LAMMPS.o LAMMPS-wrapper.o
This will create the file liblammps_fortran.a that you can use in place
of "LAMMPS.o LAMMPS-wrapper.o" later. Note that you will still
need to have the .mod file from part (3).
It is also possible to add LAMMPS.o and LAMMPS-wrapper.o into the
LAMMPS library (e.g., liblmp_openmpi.a) instead of creating a separate
library, like so:
ar rs ${LAMMPS_LIB} LAMMPS.o LAMMPS-wrapper.o
In this case, you can now use the Fortran wrapper functions as if they
were part of the usual LAMMPS library interface (if you have the module
file visible to the compiler, that is).
(6) Compile (but don't link) your Fortran program. Example:
mpifort -c myfreeformatfile.f90
mpifort -c myfixedformatfile.f
OR
gfortran -c myfreeformatfile.f90
gfortran -c myfixedformatfile.f
The object files generated by these steps are collectively referred to
as ${my_object_files} in the next step(s).
IMPORTANT: If the Fortran module from part (3) is not in the current
directory or in one searched by the compiler for module files, you will
need to include that location via the -I flag to the compiler, like so:
mpifort -I${LAMMPS_SRC}/examples/COUPLE/fortran2 -c myfreeformatfile.f90
(7) Link everything together, including any libraries needed by LAMMPS (such
as the C++ standard library, the C math library, the JPEG library, fftw,
etc.) For example,
mpifort LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \
${LAMMPS_LIB} -lmpi_cxx -lstdc++ -lm
OR
gfortran LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \
${LAMMPS_LIB} ${MPI_STUBS} -lstdc++ -lm
OR
ifort LAMMPS.o LAMMPS-wrapper.o ${my_object_files} \
${LAMMPS_LIB} ${MPI_STUBS} -cxxlib -lm
Any other required libraries (e.g. -ljpeg, -lfftw) should be added to
the end of this line.
You should now have a working executable.
** DYNAMIC LIBRARY INSTRUCTIONS **
(1) Compile LAMMPS as a dynamic library
(make makeshlib && make -f Makefile.shlib [targetname]).
(2) Compile, but don't link, LAMMPS.F90 using the -fPIC flag, such as
mpifort -fPIC -c LAMMPS.f90
(3) Compile, but don't link, LAMMPS-wrapper.cpp in the same manner, e.g.
mpicxx -fPIC -c LAMMPS-wrapper.cpp
(4) Make the dynamic library, like so:
mpifort -fPIC -shared -o liblammps_fortran.so LAMMPS.o LAMMPS-wrapper.o
(5) Compile your program, such as,
mpifort -I${LAMMPS_SRC}/examples/COUPLE/fortran2 -c myfreeformatfile.f90
where ${LAMMPS_SRC}/examples/COUPLE/fortran2 contains the .mod file from
step (3)
(6) Link everything together, such as
mpifort ${my_object_files} -L${LAMMPS_SRC} \
-L${LAMMPS_SRC}/examples/COUPLE/fortran2 -llammps_fortran \
-llammps_openmpi -lmpi_cxx -lstdc++ -lm
If you wish to avoid the -L flags, add the directories containing your
shared libraries to the LIBRARY_PATH environment variable. At run time, you
will have to add these directories to LD_LIBRARY_PATH as well; otherwise,
your executable will not find the libraries it needs.
-------------------------------------
--USAGE--
To use this API, your program unit (PROGRAM/SUBROUTINE/FUNCTION/MODULE/etc.)
should look something like this:
program call_lammps
use LAMMPS
! Other modules, etc.
implicit none
type (lammps_instance) :: lmp ! This is a pointer to your LAMMPS instance
real (C_double) :: fix
real (C_double), dimension(:), pointer :: fix2
! Rest of declarations
call lammps_open_no_mpi ('lmp -in /dev/null -screen out.lammps',lmp)
! Set up rest of program here
call lammps_file (lmp, 'in.example')
call lammps_extract_fix (fix, lmp, '2', 0, 1, 1, 1)
call lammps_extract_fix (fix2, lmp, '4', 0, 2, 1, 1)
call lammps_close (lmp)
end program call_lammps
Important notes:
* Though I dislike the use of pointers, they are necessary when communicating
with C and C++, which do not support Fortran's ALLOCATABLE attribute.
* There is no need to deallocate C-allocated memory; this is done for you in
the cases when it is done (which are all cases when pointers are not
accepted, such as global fix data)
* All arguments which are char* variables in library.cpp are character (len=*)
variables here. For example,
call lammps_command (lmp, 'units metal')
will work as expected.
* The public functions (the only ones you can use) have interfaces as
described in the comments at the top of LAMMPS.F90. They are not always
the same as those in library.h, since C strings are replaced by Fortran
strings and the like.
* The module attempts to check whether you have done something stupid (such
as assign a 2D array to a scalar), but it's not perfect. For example, the
command
call lammps_extract_global (nlocal, ptr, 'nlocal')
will give nlocal correctly if nlocal is a pointer to type INTEGER, but it
will give the wrong answer if nlocal is a pointer to type REAL. This is a
feature of the (void*) type cast in library.cpp. There is no way I can
check this for you! It WILL catch you if you pass it an allocatable or
fixed-size array when it expects a pointer.
* Arrays constructed from temporary data from LAMMPS are ALLOCATABLE, and
represent COPIES of data, not the originals. Functions like
lammps_extract_atom, which return actual LAMMPS data, are pointers.
* IMPORTANT: Due to the differences between C and Fortran arrays (C uses
row-major vectors, Fortran uses column-major vectors), all arrays returned
from LAMMPS have their indices swapped.
* An example of a complete program, simple.f90, is included with this
package.
-------------------------------------
--TROUBLESHOOTING--
Compile-time errors (when compiling LAMMPS.F90, that is) probably indicate
that your compiler is not new enough to support Fortran 2003 features. For
example, GCC 4.1.2 will not compile this module, but GCC 4.4.0 will.
If your compiler balks at 'use, intrinsic :: ISO_C_binding,' try removing the
intrinsic part so it looks like an ordinary module. However, it is likely
that such a compiler will also have problems with everything else in the
file as well.
If you get a segfault as soon as the lammps_open call is made, check that you
compiled your program AND LAMMPS-wrapper.cpp using the same MPI headers. Using
the stubs for one and the actual MPI library for the other will cause Bad
Things to happen.
If you find run-time errors, please pass them along via the LAMMPS Users
mailing list (please CC me as well; address above). Please provide a minimal
working example along with the names and versions of the compilers you are
using. Please make sure the error is repeatable and is in MY code, not yours
(generating a minimal working example will usually ensure this anyway).
-------------------------------------
--IMPLEMENTATION NOTES--
The Fortran procedures have the same names as the C procedures, and
their purpose is the same, but they may take different arguments. Here are
some of the important differences:
* lammps_open and lammps_open_no_mpi take a string instead of argc and
argv. This is necessary because C and C++ have a very different way
of treating strings than Fortran. If you want the command line to be
passed to lammps_open (as it often would be from C/C++), use the
GET_COMMAND intrinsic to obtain it.
* All C++ functions that accept char* pointers now accept Fortran-style
strings within this interface instead.
* All of the lammps_extract_[something] functions, which return void*
C-style pointers, have been replaced by generic subroutines that return
Fortran variables (which may be arrays). The first argument houses the
variable/pointer to be returned (pretend it's on the left-hand side); all
other arguments are identical except as stipulated above.
Note that it is not possible to declare generic functions that are selected
based solely on the type/kind/rank (TKR) signature of the return value,
only based on the TKR of the arguments.
* The SHAPE of the first argument to lammps_extract_[something] is checked
against the "shape" of the C array (e.g., double vs. double* vs. double**).
Calling a subroutine with arguments of inappropriate rank will result in an
error at run time.
* The indices i and j in lammps_extract_fix are used the same way they
are in f_ID[i][j] references in LAMMPS (i.e., starting from 1). This is
different than the way library.cpp uses these numbers, but is more
consistent with the way arrays are accessed in LAMMPS and in Fortran.
* The char* pointer normally returned by lammps_command is thrown away
in this version; note also that lammps_command is now a subroutine
instead of a function.
* The pointer to LAMMPS itself is of type(lammps_instance), which is itself
a synonym for type(C_ptr), part of ISO_C_BINDING. Type (C_ptr) is
C's void* data type.
* This module will almost certainly generate a compile-time warning,
such as,
subroutine lammps_open_wrapper (argc, argv, communicator, ptr) &
Variable 'communicator' at (1) is a parameter to the BIND(C)
procedure 'lammps_open_wrapper' but may not be C interoperable
This happens because lammps_open_wrapper actually takes a Fortran
INTEGER argument, whose type is defined by the MPI library itself. The
Fortran integer is converted to a C integer by the MPI library (if such
conversion is actually necessary).
* lammps_extract_global returns COPIES of the (scalar) data, as does the
C version.
* lammps_extract_atom, lammps_extract_compute, and lammps_extract_fix
have a first argument that will be associated with ACTUAL LAMMPS DATA.
This means the first argument must be:
* The right rank (via the DIMENSION modifier)
* A C-interoperable POINTER type (i.e., INTEGER (C_int) or
REAL (C_double)).
* lammps_extract_variable returns COPIES of the data, as the C library
interface does. There is no need to deallocate using lammps_free.
* The 'data' argument to lammps_gather_atoms and lammps_scatter atoms must
be ALLOCATABLE. It should be of type INTEGER or DOUBLE PRECISION. It
does NOT need to be C inter-operable (and indeed should not be).
* The 'count' argument of lammps_scatter_atoms is unnecessary; the shape of
the array determines the number of elements LAMMPS will read.

16
examples/COUPLE/fortran2/in.simple
View File

@ -1,16 +0,0 @@
units lj
atom_modify map array
lattice bcc 1.0
region simbox block 0 10 0 10 0 10
create_box 2 simbox
create_atoms 1 region simbox
pair_style lj/cut 2.5
pair_coeff * * 1.0 1.0
mass 1 58.2 # These are made-up numbers
mass 2 28.3
velocity all create 1200.0 7474848 dist gaussian
fix 1 all nve
fix 2 all dt/reset 1 1E-5 1E-3 0.01 units box
fix 4 all ave/histo 10 5 100 0.5 1.5 50 f_2 file temp.histo ave running
thermo_style custom step dt temp press etotal f_4[1][1]
thermo 100

112
examples/COUPLE/fortran2/simple.f90
View File

@ -1,112 +0,0 @@
program simple
use MPI
use LAMMPS
! The following line is unnecessary, as I have included these three entities
! with the LAMMPS module, but I leave them in anyway to remind people where
! they came from
use, intrinsic :: ISO_C_binding, only : C_double, C_ptr, C_int
implicit none
! Notes:
! * If LAMMPS returns a scalar that is allocated by the library interface
! (see library.cpp), then that memory is deallocated automatically and
! the argument to lammps_extract_fix must be a SCALAR.
! * If LAMMPS returns a pointer to an array, consisting of internal LAMMPS
! data, then the argument must be an interoperable Fortran pointer.
! Interoperable means it is of type INTEGER (C_INT) or of type
! REAL (C_DOUBLE) in this context.
! * Pointers should NEVER be deallocated, as that would deallocate internal
! LAMMPS data!
! * Note that just because you can read the values of, say, a compute at
! any time does not mean those values represent the "correct" values.
! LAMMPS will abort you if you try to grab a pointer to a non-current
! entity, but once it's bound, it's your responsibility to check that
! it's current before evaluating.
! * IMPORTANT: Two-dimensional arrays (such as 'x' from extract_atom)
! will be transposed from what they might look like in C++. This is
! because of different bookkeeping conventions between Fortran and C
! that date back to about 1970 or so (when C was written).
! * Arrays start from 1, EXCEPT for mass from extract_atom, which
! starts from 0. This is because the C array actually has a blank
! first element (and thus mass[1] corresponds to the mass of type 1)
type (C_ptr) :: lmp
real (C_double), pointer :: compute => NULL()
real (C_double) :: fix, fix2
real (C_double), dimension(:), pointer :: compute_v => NULL()
real (C_double), dimension(:,:), pointer :: x => NULL()
real (C_double), dimension(:), pointer :: mass => NULL()
integer, dimension(:), allocatable :: types
double precision, dimension(:), allocatable :: r
integer :: error, narg, me, nprocs
character (len=1024) :: command_line
call MPI_Init (error)
call MPI_Comm_rank (MPI_COMM_WORLD, me, error)
call MPI_Comm_size (MPI_COMM_WORLD, nprocs, error)
! You are free to pass any string you like to lammps_open or
! lammps_open_no_mpi; here is how you pass it the command line
!call get_command (command_line)
!call lammps_open (command_line, MPI_COMM_WORLD, lmp)
! And here's how to to it with a string constant of your choice
call lammps_open_no_mpi ('lmp -log log.simple', lmp)
call lammps_file (lmp, 'in.simple')
call lammps_command (lmp, 'run 500')
! This extracts f_2 as a scalar (the last two arguments can be arbitrary)
call lammps_extract_fix (fix, lmp, '2', LMP_STYLE_GLOBAL, LMP_TYPE_SCALAR, 1, 1)
print *, 'Fix is ', fix
! This extracts f_4[1][1] as a scalar
call lammps_extract_fix (fix2, lmp, '4', LMP_STYLE_GLOBAL, LMP_TYPE_ARRAY, 1, 1)
print *, 'Fix 2 is ', fix2
! This extracts the scalar compute of compute thermo_temp
call lammps_extract_compute (compute, lmp, 'thermo_temp', LMP_STYLE_GLOBAL, LMP_TYPE_SCALAR)
print *, 'Compute is ', compute
! This extracts the vector compute of compute thermo_temp
call lammps_extract_compute (compute_v, lmp, 'thermo_temp', LMP_STYLE_GLOBAL, LMP_TYPE_VECTOR)
print *, 'Vector is ', compute_v
! This extracts the masses
call lammps_extract_atom (mass, lmp, 'mass')
print *, 'Mass is ', mass(1:)
! Extracts a pointer to the arrays of positions for all atoms
call lammps_extract_atom (x, lmp, 'x')
if ( .not. associated (x) ) print *, 'x is not associated'
print *, 'x is ', x(:,1) ! Prints x, y, z for atom 1
! Extracts pointer to atom types
call lammps_gather_atoms (lmp, 'type', 1, types)
print *, 'types is ', types(1:3)
! Allocates an array and assigns all positions to it
call lammps_gather_atoms (lmp, 'x', 3, r)
print *, 'natoms = ', int(lammps_get_natoms(lmp))
print *, 'size(r) = ', size(r)
print *, 'r is ', r(1:6)
! Puts those position data back
call lammps_scatter_atoms (lmp, 'x', r)
call lammps_command (lmp, 'run 1')
print *, 'x is ', x(:,1) ! Note that the position updates!
print *, 'Compute is ', compute ! This did only because "temp" is part of
! the thermo output; the vector part did
! not, and won't until we give LAMMPS a
! thermo output or other command that
! requires its value
call lammps_close (lmp)
call MPI_Finalize (error)
end program simple

96
examples/COUPLE/fortran_dftb/LAMMPS-wrapper.cpp
View File

@ -1,96 +0,0 @@
/* -----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ------------------------------------------------------------------------
Contributing author: Karl D. Hammond <hammondkd@missouri.edu>
University of Missouri (USA), 2012
------------------------------------------------------------------------- */
/* This is set of "wrapper" functions to assist LAMMPS.F90, which itself
provides a (I hope) robust Fortran interface to library.cpp and
library.h. All functions herein COULD be added to library.cpp instead of
including this as a separate file. See the README for instructions. */
#include <mpi.h>
#include "LAMMPS-wrapper.h"
#define LAMMPS_LIB_MPI 1
#include <library.h>
#include <lammps.h>
#include <atom.h>
#include <fix.h>
#include <compute.h>
#include <modify.h>
#include <error.h>
#include <cstdlib>
using namespace LAMMPS_NS;
void lammps_open_fortran_wrapper (int argc, char **argv,
MPI_Fint communicator, void **ptr)
{
MPI_Comm C_communicator = MPI_Comm_f2c (communicator);
lammps_open (argc, argv, C_communicator, ptr);
}
int lammps_get_ntypes (void *ptr)
{
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ntypes = lmp->atom->ntypes;
return ntypes;
}
void lammps_error_all (void *ptr, const char *file, int line, const char *str)
{
class LAMMPS *lmp = (class LAMMPS *) ptr;
lmp->error->all (file, line, str);
}
int lammps_extract_compute_vectorsize (void *ptr, char *id, int style)
{
int *size;
size = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_VECTOR);
if (size) return *size;
return 0;
}
void lammps_extract_compute_arraysize (void *ptr, char *id, int style,
int *nrows, int *ncols)
{
int *tmp;
tmp = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_ROWS);
if (tmp) *nrows = *tmp;
tmp = (int *) lammps_extract_compute(ptr, id, style, LMP_SIZE_COLS);
if (tmp) *ncols = *tmp;
return;
}
int lammps_extract_fix_vectorsize (void *ptr, char *id, int style)
{
int *size;
size = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_VECTOR, 0, 0);
if (size) return *size;
return 0;
}
void lammps_extract_fix_arraysize (void *ptr, char *id, int style,
int *nrows, int *ncols)
{
int *tmp;
tmp = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_ROWS, 0, 0);
if (tmp) *nrows = *tmp;
tmp = (int *) lammps_extract_fix(ptr, id, style, LMP_SIZE_COLS, 0, 0);
if (tmp) *ncols = *tmp;
return;
}
/* vim: set ts=3 sts=3 expandtab: */

40
examples/COUPLE/fortran_dftb/LAMMPS-wrapper.h
View File

@ -1,40 +0,0 @@
/* -----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ------------------------------------------------------------------------
Contributing author: Karl D. Hammond <hammondkd@missouri.edu>
University of Missouri (USA), 2012
------------------------------------------------------------------------- */
/* This is set of "wrapper" functions to assist LAMMPS.F90, which itself
provides a (I hope) robust Fortran interface to library.cpp and
library.h. All prototypes herein COULD be added to library.h instead of
including this as a separate file. See the README for instructions. */
#ifdef __cplusplus
extern "C" {
#endif
/* Prototypes for auxiliary functions */
void lammps_open_fortran_wrapper (int, char**, MPI_Fint, void**);
int lammps_get_ntypes (void*);
int lammps_extract_compute_vectorsize (void*, char*, int);
void lammps_extract_compute_arraysize (void*, char*, int, int*, int*);
int lammps_extract_fix_vectorsize (void*, char*, int);
void lammps_extract_fix_arraysize (void*, char*, int, int*, int*);
void lammps_error_all (void*, const char*, int, const char*);
#ifdef __cplusplus
}
#endif
/* vim: set ts=3 sts=3 expandtab: */

80
examples/COUPLE/fortran_dftb/LAMMPS-wrapper2.cpp
View File

@ -1,80 +0,0 @@
/* -----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
/* ------------------------------------------------------------------------
Contributing author: Nir Goldman, LLNL <ngoldman@llnl.gov>, 2016
------------------------------------------------------------------------- */
/* This is set of "wrapper" functions to assist LAMMPS.F90, which itself
provides a (I hope) robust Fortran interface to library.cpp and
library.h. All functions herein COULD be added to library.cpp instead of
including this as a separate file. See the README for instructions. */
#include <mpi.h>
#include "LAMMPS-wrapper2.h"
#include <library.h>
#include <lammps.h>
#include <atom.h>
#include <input.h>
#include <modify.h>
#include <fix.h>
#include <fix_external.h>
#include <compute.h>
#include <modify.h>
#include <error.h>
#include <cstdlib>
using namespace LAMMPS_NS;
extern "C" void f_callback(void *, bigint, int, tagint *, double **, double **);
void lammps_set_callback (void *ptr) {
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ifix = lmp->modify->find_fix_by_style("external");
FixExternal *fix = (FixExternal *) lmp->modify->fix[ifix];
fix->set_callback(f_callback, ptr);
return;
}
void lammps_set_external_vector_length (void *ptr, int n) {
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ifix = lmp->modify->find_fix_by_style("external");
FixExternal *fix = (FixExternal *) lmp->modify->fix[ifix];
fix->set_vector_length(n);
return;
}
void lammps_set_external_vector (void *ptr, int n, double val) {
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ifix = lmp->modify->find_fix_by_style("external");
FixExternal *fix = (FixExternal *) lmp->modify->fix[ifix];
fix->set_vector (n, val);
return;
}
void lammps_set_user_energy (void *ptr, double energy) {
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ifix = lmp->modify->find_fix_by_style("external");
FixExternal *fix = (FixExternal *) lmp->modify->fix[ifix];
fix->set_energy_global(energy);
return;
}
void lammps_set_user_virial (void *ptr, double *virial) {
class LAMMPS *lmp = (class LAMMPS *) ptr;
int ifix = lmp->modify->find_fix_by_style("external");
FixExternal *fix = (FixExternal *) lmp->modify->fix[ifix];
fix->set_virial_global(virial);
return;
}

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