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

Resolve merge conflicts

Browse Source
This commit is contained in:
Joel Clemmer
2021-01-13 09:42:57 -07:00
parent a25c77e512 9ff011728c
commit 2c92737cd5
541 changed files with 9281 additions and 7264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
doc/src/Build_extras.rst
View File

@ -37,6 +37,7 @@ This is the list of packages that may require additional steps.
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`MESSAGE <message>`
* :ref:`MLIAP <mliap>`
* :ref:`MSCG <mscg>`
* :ref:`OPT <opt>`
* :ref:`POEMS <poems>`
@ -770,6 +771,54 @@ be installed on your system.
----------
.. _mliap:
MLIAP package
---------------------------
Building the MLIAP package requires including the :ref:`SNAP <PKG-SNAP>`
package. There will be an error message if this requirement is not satisfied.
Using the *mliappy* model also requires enabling Python support, which
in turn requires the :ref:`PYTHON <PKG-PYTHON>`
package **and** requires you have the `cython <https://cython.org>`_ software
installed and with it a working ``cythonize`` command. This feature requires
compiling LAMMPS with Python version 3.6 or later.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D MLIAP_ENABLE_PYTHON=value # enable mliappy model (default is autodetect)
Without this setting, CMake will check whether it can find a
suitable Python version and the ``cythonize`` command and choose
the default accordingly. During the build procedure the provided
.pyx file(s) will be automatically translated to C++ code and compiled.
Please do **not** run ``cythonize`` manually in the ``src/MLIAP`` folder,
as that can lead to compilation errors if Python support is not enabled.
If you did by accident, please remove the generated .cpp and .h files.
.. tab:: Traditional make
The build uses the ``lib/python/Makefile.mliap_python`` file in the
compile/link process to add a rule to update the files generated by
the ``cythonize`` command in case the corresponding .pyx file(s) were
modified. You may need to modify ``lib/python/Makefile.lammps``
if the LAMMPS build fails.
To manually enforce building MLIAP with Python support enabled,
you can add
``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in your machine makefile.
You may have to manually run the ``cythonize`` command on .pyx file(s)
in the ``src`` folder, if this is not automatically done during
installing the MLIAP package. Please do **not** run ``cythonize``
in the ``src/MLIAP`` folder, as that can lead to compilation errors
if Python support is not enabled.
If you did by accident, please remove the generated .cpp and .h files.
----------
.. _mscg:
MSCG package

1
doc/src/Build_package.rst
View File

@ -1,5 +1,4 @@
Include packages in build
=========================
In LAMMPS, a package is a group of files that enable a specific set of

20
doc/src/Packages_details.rst
View File

@ -662,19 +662,31 @@ MLIAP package
**Contents:**
A general interface for machine-learning interatomic potentials.
A general interface for machine-learning interatomic potentials, including PyTorch.
**Install:**
To use this package, also the :ref:`SNAP package <PKG-SNAP>` needs to be installed.
To use this package, also the :ref:`SNAP package <PKG-SNAP>` package needs
to be installed. To make the *mliappy* model available, also the
:ref:`PYTHON package <PKG-PYTHON>` package needs to be installed, the version of
Python must be 3.6 or later, and the `cython <https://cython.org/>`_ software
must be installed.
**Author:** Aidan Thompson (Sandia).
**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
**Supporting info:**
* src/MLIAP: filenames -> commands
* src/MLIAP/README
* :doc:`pair_style mliap <pair_mliap>`
* examples/mliap
* :doc:`compute_style mliap <compute_mliap>`
* examples/mliap (see README)
When built with the *mliappy* model this package includes an extension for
coupling with Python models, including PyTorch. In this case, the Python
interpreter linked to LAMMPS will need the ``cython`` and ``numpy`` modules
installed. The provided examples build models with PyTorch, which would
therefore also needs to be installed to run those examples.
----------

12
doc/src/Speed_kokkos.rst
View File

@ -38,14 +38,14 @@ produce an executable compatible with a specific hardware.
:class: note
Kokkos with CUDA currently implicitly assumes that the MPI library is
CUDA-aware. This is not always the case, especially when using
GPU-aware. This is not always the case, especially when using
pre-compiled MPI libraries provided by a Linux distribution. This is
not a problem when using only a single GPU with a single MPI
rank. When running with multiple MPI ranks, you may see segmentation
faults without CUDA-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos cuda/aware off <Run_options>` to the
faults without GPU-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos gpu/aware off <Run_options>` to the
LAMMPS command line or by using the command :doc:`package kokkos
cuda/aware off <package>` in the input file.
gpu/aware off <package>` in the input file.
.. admonition:: AMD GPU support
:class: note
@ -242,8 +242,8 @@ case, also packing/unpacking communication buffers on the host may give
speedup (see the KOKKOS :doc:`package <package>` command). Using CUDA MPS
is recommended in this scenario.
Using a CUDA-aware MPI library is highly recommended. CUDA-aware MPI use can be
avoided by using :doc:`-pk kokkos cuda/aware no <package>`. As above for
Using a GPU-aware MPI library is highly recommended. GPU-aware MPI use can be
avoided by using :doc:`-pk kokkos gpu/aware off <package>`. As above for
multi-core CPUs (and no GPU), if N is the number of physical cores/node,
then the number of MPI tasks/node should not exceed N.

19
doc/src/compute_mliap.rst
View File

@ -18,7 +18,7 @@ Syntax
.. parsed-literal::
*model* values = style
style = *linear* or *quadratic*
style = *linear* or *quadratic* or *mliappy*
*descriptor* values = style filename
style = *sna*
filename = name of file containing descriptor definitions
@ -56,13 +56,15 @@ and it is also straightforward to add new descriptor styles.
The compute *mliap* command must be followed by two keywords
*model* and *descriptor* in either order.
The *model* keyword is followed by a model style, currently limited to
either *linear* or *quadratic*.
The *model* keyword is followed by the model style (*linear*, *quadratic* or *mliappy*).
The *mliappy* model is only available
if lammps is built with MLIAPPY package.
The *descriptor* keyword is followed by a descriptor style, and additional arguments.
Currently the only descriptor style is *sna*, indicating the bispectrum component
descriptors used by the Spectral Neighbor Analysis Potential (SNAP) potentials of
:doc:`pair_style snap <pair_snap>`.
The compute currently supports just one descriptor style, but it is
is straightforward to add new descriptor styles.
The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
including the linear, quadratic, and chem variants.
A single additional argument specifies the descriptor filename
containing the parameters and setting used by the SNAP descriptor.
The descriptor filename usually ends in the *.mliap.descriptor* extension.
@ -162,9 +164,10 @@ potentials, see the examples in `FitSNAP <https://github.com/FitSNAP/FitSNAP>`_.
Restrictions
""""""""""""
This compute is part of the MLIAP package. It is only enabled if
LAMMPS was built with that package. In addition, building LAMMPS with the MLIAP package
This compute is part of the MLIAP package. It is only enabled if LAMMPS
was built with that package. In addition, building LAMMPS with the MLIAP package
requires building LAMMPS with the SNAP package.
The *mliappy* model requires building LAMMPS with the PYTHON package.
See the :doc:`Build package <Build_package>` doc page for more info.
Related commands

6
doc/src/compute_orientorder_atom.rst
View File

@ -115,8 +115,8 @@ The optional keyword *chunksize* is only applicable when using the
the KOKKOS package and is ignored otherwise. This keyword controls
the number of atoms in each pass used to compute the bond-orientational
order parameters and is used to avoid running out of memory. For example
if there are 4000 atoms in the simulation and the *chunksize*
is set to 2000, the parameter calculation will be broken up
if there are 32768 atoms in the simulation and the *chunksize*
is set to 16384, the parameter calculation will be broken up
into two passes.
The value of :math:`Q_l` is set to zero for atoms not in the
@ -193,7 +193,7 @@ Default
The option defaults are *cutoff* = pair style cutoff, *nnn* = 12,
*degrees* = 5 4 6 8 10 12 i.e. :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`,
*wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 2000
*wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 16384
----------

2
doc/src/fix_ave_correlate.rst
View File

@ -93,7 +93,7 @@ from a compute, fix, or variable, then see the :doc:`fix ave/chunk <fix_ave_chun
:doc:`fix ave/histo <fix_ave_histo>` commands. If you wish to convert a
per-atom quantity into a single global value, see the :doc:`compute reduce <compute_reduce>` command.
The input values must either be all scalars. What kinds of
The input values must be all scalars. What kinds of
correlations between input values are calculated is determined by the
*type* keyword as discussed below.

47
doc/src/package.rst
View File

@ -68,7 +68,7 @@ Syntax
*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 *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/reverse* or *cuda/aware* or *pair/only*
keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* *pair/comm/forward* *fix/comm/forward* or *comm/reverse* or *gpu/aware* or *pair/only*
*neigh* value = *full* or *half*
full = full neighbor list
half = half neighbor list built in thread-safe manner
@ -84,16 +84,18 @@ Syntax
*binsize* value = size
size = bin size for neighbor list construction (distance units)
*comm* value = *no* or *host* or *device*
use value for comm/exchange and comm/forward and comm/reverse
use value for comm/exchange and comm/forward and pair/comm/forward and fix/comm/forward and comm/reverse
*comm/exchange* value = *no* or *host* or *device*
*comm/forward* value = *no* or *host* or *device*
*pair/comm/forward* value = *no* or *device*
*fix/comm/forward* value = *no* or *device*
*comm/reverse* value = *no* or *host* or *device*
no = perform communication pack/unpack in non-KOKKOS mode
host = perform pack/unpack on host (e.g. with OpenMP threading)
device = perform pack/unpack on device (e.g. on GPU)
*cuda/aware* = *off* or *on*
off = do not use CUDA-aware MPI
on = use CUDA-aware MPI (default)
*gpu/aware* = *off* or *on*
off = do not use GPU-aware MPI
on = use GPU-aware MPI (default)
*pair/only* = *off* or *on*
off = use device acceleration (e.g. GPU) for all available styles in the KOKKOS package (default)
on = use device acceleration only for pair styles (and host acceleration for others)
@ -498,7 +500,8 @@ because the GPU is faster at performing pairwise interactions, then this
rule of thumb may give too large a binsize and the default should be
overridden with a smaller value.
The *comm* and *comm/exchange* and *comm/forward* and *comm/reverse*
The *comm* and *comm/exchange* and *comm/forward* and *pair/comm/forward*
and *fix/comm/forward* and comm/reverse*
keywords determine whether the host or device performs the packing and
unpacking of data when communicating per-atom data between processors.
"Exchange" communication happens only on timesteps that neighbor lists
@ -506,18 +509,22 @@ are rebuilt. The data is only for atoms that migrate to new processors.
"Forward" communication happens every timestep. "Reverse" communication
happens every timestep if the *newton* option is on. The data is for
atom coordinates and any other atom properties that needs to be updated
for ghost atoms owned by each processor.
for ghost atoms owned by each processor. "Pair/comm" controls additional
communication in pair styles, such as pair_style EAM. "Fix/comm" controls
additional communication in fixes, such as fix SHAKE.
The *comm* keyword is simply a short-cut to set the same value for both
the *comm/exchange* and *comm/forward* and *comm/reverse* keywords.
The *comm* keyword is simply a short-cut to set the same value for all
the comm keywords.
The value options for all 3 keywords are *no* or *host* or *device*\ . A
The value options for the keywords are *no* or *host* or *device*\ . A
value of *no* means to use the standard non-KOKKOS method of
packing/unpacking data for the communication. A value of *host* means to
use the host, typically a multi-core CPU, and perform the
packing/unpacking in parallel with threads. A value of *device* means to
use the device, typically a GPU, to perform the packing/unpacking
operation.
operation. If a value of *host* is used for the *pair/comm/forward* or
*fix/comm/forward* keyword, it will be automatically be changed to *no*
since these keywords don't support *host* mode.
The optimal choice for these keywords depends on the input script and
the hardware used. The *no* value is useful for verifying that the
@ -538,18 +545,18 @@ 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 *cuda/aware* keyword chooses whether CUDA-aware MPI will be used. When
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
the data to the host CPU. However CUDA-aware MPI is not supported on all
the data to the host CPU. However GPU-aware MPI is not supported on all
systems, which can lead to segmentation faults and would require using a
value of *off*\ . If LAMMPS can safely detect that CUDA-aware MPI is not
value of *off*\ . If LAMMPS can safely detect that GPU-aware MPI is not
available (currently only possible with OpenMPI v2.0.0 or later), then
the *cuda/aware* keyword is automatically set to *off* by default. When
the *cuda/aware* keyword is set to *off* while any of the *comm*
the *gpu/aware* keyword is automatically set to *off* by default. When
the *gpu/aware* keyword is set to *off* while any of the *comm*
keywords are set to *device*\ , the value for these *comm* keywords will
be automatically changed to *no*\ . This setting has no effect if not
running on GPUs or if using only one MPI rank. CUDA-aware MPI is available
running on GPUs or if using only one MPI rank. GPU-aware MPI is available
for OpenMPI 1.8 (or later versions), Mvapich2 1.9 (or later) when the
"MV2_USE_CUDA" environment variable is set to "1", CrayMPI, and IBM
Spectrum MPI when the "-gpu" flag is used.
@ -558,7 +565,7 @@ The *pair/only* keyword can change how the KOKKOS suffix "kk" is applied
when using an accelerator device. By default device acceleration is
always used for all available styles. With *pair/only* set to *on* the
suffix setting will choose device acceleration only for pair styles and
run all other force computations concurrently on the host CPU.
run all other force computations on the host CPU.
The *comm* flags will also automatically be changed to *no*\ . This can
result in better performance for certain configurations and system sizes.
@ -671,8 +678,8 @@ 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, cuda/aware = on. When LAMMPS can safely detect
that CUDA-aware MPI is not available, the default value of cuda/aware
value, comm = device, 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

36
doc/src/pair_mliap.rst
View File

@ -16,7 +16,7 @@ Syntax
.. parsed-literal::
*model* values = style filename
style = *linear* or *quadratic*
style = *linear* or *quadratic* or *mliappy*
filename = name of file containing model definitions
*descriptor* values = style filename
style = *sna*
@ -40,12 +40,15 @@ definitions of the interatomic potential functional form (*model*)
and the geometric quantities that characterize the atomic positions
(*descriptor*). By defining *model* and *descriptor* separately,
it is possible to use many different models with a given descriptor,
or many different descriptors with a given model. Currently, the pair_style
supports just two models, *linear* and *quadratic*,
and one descriptor, *sna*, the SNAP descriptor used by :doc:`pair_style snap <pair_snap>`, including the linear, quadratic,
and chem variants. Work is currently underway to extend
the interface to handle neural network energy models,
and it is also straightforward to add new descriptor styles.
or many different descriptors with a given model. The
pair style currently supports just one descriptor style, but it is
is straightforward to add new descriptor styles.
The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
including the linear, quadratic, and chem variants.
The available models are *linear*, *quadratic*, and *mliappy*.
The *mliappy* style can be used to couple python models,
e.g. PyTorch neural network energy models, and requires building
LAMMPS with the PYTHON package (see below).
In order to train a model, it is useful to know the gradient or derivative
of energy, force, and stress w.r.t. model parameters. This information
can be accessed using the related :doc:`compute mliap <compute_mliap>` command.
@ -59,9 +62,8 @@ that specify the mapping of MLIAP
element names to LAMMPS atom types,
where N is the number of LAMMPS atom types.
The *model* keyword is followed by a model style, currently limited to
either *linear* or *quadratic*. In both cases,
this is followed by a single argument specifying the model filename containing the
The *model* keyword is followed by the model style. This is followed
by a single argument specifying the model filename containing the
parameters for a set of elements.
The model filename usually ends in the *.mliap.model* extension.
It may contain parameters for many elements. The only requirement is that it
@ -82,6 +84,16 @@ for the :doc:`pair_style snap <pair_snap>` coefficient file.
Specifically, the line containing the element weight and radius is omitted,
since these are handled by the *descriptor*.
Notes on mliappy models:
When the *model* keyword is *mliappy*, the filename should end in '.pt',
'.pth' for pytorch models, or be a pickle file. To load a model from
memory (i.e. an existing python object), specify the filename as
"LATER", and then call `lammps.mliap.load_model(model)` from python
before using the pair style. When using lammps via the library mode, you will need to call
`lammps.mliappy.activate_mliappy(lmp)` on the active lammps object
before the pair style is defined. This call locates and loads the mliap-specific
python module that is built into lammps.
The *descriptor* keyword is followed by a descriptor style, and additional arguments.
Currently the only descriptor style is *sna*, indicating the bispectrum component
descriptors used by the Spectral Neighbor Analysis Potential (SNAP) potentials of
@ -138,11 +150,13 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This style is part of the MLIAP package. It is only enabled if LAMMPS
This pair style is part of the MLIAP package. It is only enabled if LAMMPS
was built with that package. In addition, building LAMMPS with the MLIAP package
requires building LAMMPS with the SNAP package.
The *mliappy* model requires building LAMMPS with the PYTHON package.
See the :doc:`Build package <Build_package>` doc page for more info.
Related commands
""""""""""""""""

6
doc/src/pair_snap.rst
View File

@ -152,7 +152,7 @@ The default values for these keywords are
* *chemflag* = 0
* *bnormflag* = 0
* *wselfallflag* = 0
* *chunksize* = 2000
* *chunksize* = 4096
If *quadraticflag* is set to 1, then the SNAP energy expression includes additional quadratic terms
that have been shown to increase the overall accuracy of the potential without much increase
@ -189,8 +189,8 @@ pair style *snap* with the KOKKOS package and is ignored otherwise.
This keyword controls
the number of atoms in each pass used to compute the bispectrum
components and is used to avoid running out of memory. For example
if there are 4000 atoms in the simulation and the *chunksize*
is set to 2000, the bispectrum calculation will be broken up
if there are 8192 atoms in the simulation and the *chunksize*
is set to 4096, the bispectrum calculation will be broken up
into two passes.
Detailed definitions for all the other keywords