rename MLIAP package to ML-IAP

doc/src/Build_extras.rst

@@ -37,7 +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:`ML-IAP <mliap>`
    * :ref:`MSCG <mscg>`
    * :ref:`OPT <opt>`
    * :ref:`POEMS <poems>`
@@ -811,16 +811,17 @@ be installed on your system.
 
 .. _mliap:
 
-MLIAP package
+ML-IAP 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.
+Building the ML-IAP 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 to include the :ref:`PYTHON
+<PKG-PYTHON>` package **and** requires to 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::
 
@@ -834,9 +835,9 @@ compiling LAMMPS with Python version 3.6 or later.
       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,
+      Please do **not** run ``cythonize`` manually in the ``src/ML-IAP`` 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.
+      If you did it by accident, please remove the generated .cpp and .h files.
 
    .. tab:: Traditional make
 
@@ -845,15 +846,16 @@ compiling LAMMPS with Python version 3.6 or later.
       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.
+
+      To enable building the ML-IAP package with Python support enabled,
+      you need to 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 ML-IAP
+      package.  Please do **not** run ``cythonize`` in the ``src/ML-IAP``
+      folder, as that can lead to compilation errors if Python support
+      is not enabled.  If you did this by accident, please remove the
+      generated .cpp and .h files.
 
 ----------
 

doc/src/Packages_details.rst

@@ -44,7 +44,7 @@ page gives those details.
    * :ref:`MC <PKG-MC>`
    * :ref:`MESSAGE <PKG-MESSAGE>`
    * :ref:`MISC <PKG-MISC>`
-   * :ref:`MLIAP <PKG-MLIAP>`
+   * :ref:`ML-IAP <PKG-ML-IAP>`
    * :ref:`MOLECULE <PKG-MOLECULE>`
    * :ref:`MPIIO <PKG-MPIIO>`
    * :ref:`MSCG <PKG-MSCG>`
@@ -668,9 +668,9 @@ listing, "ls src/MISC", to see the list of commands.
 
 ----------
 
-.. _PKG-MLIAP:
+.. _PKG-ML-IAP:
 
-MLIAP package
+ML-IAP package
 -------------
 
 **Contents:**
@@ -689,8 +689,8 @@ must be installed.
 
 **Supporting info:**
 
-* src/MLIAP: filenames -> commands
-* src/MLIAP/README
+* src/ML-IAP: filenames -> commands
+* src/ML-IAP/README.md
 * :doc:`pair_style mliap <pair_mliap>`
 * :doc:`compute_style mliap <compute_mliap>`
 * examples/mliap (see README)

doc/src/Packages_standard.rst

@@ -59,7 +59,7 @@ package:
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`MISC <PKG-MISC>`           | miscellaneous single-file commands   | n/a                                                | no                                                   | no      |
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
-| :ref:`MLIAP <PKG-MLIAP>`         | multiple machine learning potentials | :doc:`pair_style mliap <pair_mliap>`               | mliap                                                | no      |
+| :ref:`ML-IAP <PKG-ML-IAP>`       | multiple machine learning potentials | :doc:`pair_style mliap <pair_mliap>`               | mliap                                                | no      |
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`MOLECULE <PKG-MOLECULE>`   | molecular system force fields        | :doc:`Howto bioFF <Howto_bioFF>`                   | peptide                                              | no      |
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+

doc/src/compute_mliap.rst

@@ -56,21 +56,22 @@ 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 the model style (*linear*, *quadratic* or *mliappy*).
-The *mliappy* model is only available
-if lammps is built with MLIAPPY package.
+The *model* keyword is followed by the model style (*linear*,
+*quadratic* or *mliappy*).  The *mliappy* model is only available if
+LAMMPS is built with the *mliappy* python module. There are
+:ref:`specific installation instructions <mliap>` for that.
 
-The *descriptor* keyword is followed by a descriptor style, and additional arguments.
-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.
-The format of this file is identical to the descriptor file in the
-:doc:`pair_style mliap <pair_mliap>`, and is described in detail
-there.
+The *descriptor* keyword is followed by a descriptor style, and
+additional arguments.  The compute currently supports two descriptor
+styles *sna* and *so3*, but it is is straightforward to add additional
+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.  The format of this file is identical to
+the descriptor file in the :doc:`pair_style mliap <pair_mliap>`, and is
+described in detail there.
 
 .. note::
 
@@ -164,10 +165,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
-requires building LAMMPS with the SNAP package.
-The *mliappy* model requires building LAMMPS with the PYTHON package.
+This compute is part of the ML-IAP package.  It is only enabled if
+LAMMPS was built with that package. In addition, building LAMMPS with
+the ML-IAP package requires building LAMMPS with the SNAP package.  The
+*mliappy* model also requires building LAMMPS with the PYTHON package.
 See the :doc:`Build package <Build_package>` doc page for more info.
 
 Related commands

doc/src/pair_mliap.rst

@@ -192,9 +192,9 @@ This pair style can only be used via the *pair* keyword of the
 Restrictions
 """"""""""""
 
-This pair style is part of the MLIAP package.  It is only enabled if
+This pair style is part of the ML-IAP 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
+the ML-IAP 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.
 

potentials/README

@@ -100,9 +100,9 @@ meam.spline   modified EAM (MEAM) spline potential
 meam.sw.spline modified EAM (MEAM) Stillinger-Weber spline potential
 mesocnt       mesoscopic carbon nanotube (CNT) potential
 mgpt          model generalized pseudopotential theory (MGPT) potential
-mliap         MLIAP potential
-mliap.descriptor MLIAP potential descriptor
-mliap.model   MLIAP potential model
+mliap         ML-IAP potential
+mliap.descriptor ML-IAP potential descriptor
+mliap.model   ML-IAP potential model
 nb3b.harmonic nonbonded 3-body harmonic potential
 poly          polymorphic 3-body potential
 reax          ReaxFF potential (see README.reax for more info)

python/lammps/mliap/loader.py

@@ -39,13 +39,13 @@ def activate_mliappy(lmp):
         # End Importlib magic to find the embedded python module
 
     except Exception as ee:
-        raise ImportError("Could not load MLIAP python coupling module.") from ee
+        raise ImportError("Could not load ML-IAP python coupling module.") from ee
 
 def load_model(model):
     try:
         import mliap_model_python_couple
     except ImportError as ie:
-        raise ImportError("MLIAP python module must be activated before loading\n"
+        raise ImportError("ML-IAP python module must be activated before loading\n"
                           "the pair style. Call lammps.mliap.activate_mliappy(lmp)."
                           ) from ie
     mliap_model_python_couple.load_from_python(model)

src/Depend.sh

@@ -107,7 +107,7 @@ if (test $1 = "PERI") then
 fi
 
 if (test $1 = "PYTHON") then
-  depend MLIAP
+  depend ML-IAP
 fi
 
 if (test $1 = "RIGID") then
@@ -118,7 +118,7 @@ fi
 
 if (test $1 = "SNAP") then
   depend KOKKOS
-  depend MLIAP
+  depend ML-IAP
 fi
 
 if (test $1 = "USER-CGSDK") then

src/ML-IAP/Install.sh

@@ -29,7 +29,7 @@ action () {
 # enforce package dependency
 if (test $1 = 1 || test $1 = 2) then
   if (test ! -e ../sna.h) then
-     echo "Must install SNAP package to use MLIAP package"
+     echo "Must install SNAP package to use ML-IAP package"
      exit 1
   fi
 fi

src/ML-IAP/README.md

@@ -0,0 +1,56 @@
+This package provides a general interface to families of
+machine-learning interatomic potentials (MLIAPs).  This interface
+consists of a `mliap pair style` and a `mliap compute`.  The `mliap pair
+style` is used when running simulations with energies and forces
+calculated by an MLIAP. The interface allows separate 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. The mliap pair_style supports the following models:
+
+- `linear`,
+- `quadratic`,
+- `nn` (neural networks)
+- `mliappy` (general Python interface to things like PyTorch).
+
+It currently supports two classes of descriptors, `sna` (the SNAP
+descriptors) and `so3` (the SO3 descriptor).  It is straightforward to
+add new descriptor and model styles.
+
+The `compute mliap` style provides gradients of the energy, force, and
+stress tensor w.r.t. model parameters.  These are useful when training
+MLIAPs to match target data.  Any `model` or `descriptor` that has been
+implemented for the `mliap` pair style can also be accessed by the
+`mliap` compute.  In addition to the energy, force, and stress
+gradients, w.r.t.  each `model` parameter, the compute also calculates
+the energy, force, and stress contributions from a user-specified
+reference potential.
+
+## Generating the model files from the third-party packages
+- To train the `linear` and `quadratic` models with the SNAP descriptors, see the examples in [FitSNAP](https://github.com/FitSNAP/FitSNAP).
+- To train the `nn` model with the SNAP descriptors, check the examples in [PyXtal\_FF](https://github.com/qzhu2017/PyXtal_FF).
+
+## Building the ML-IAP package with Python support
+
+The `mliappy` energy model requires that the MLIAP package is compiled
+with Python support enabled. This extension, written by Nick Lubbers
+(LANL), provides a coupling to PyTorch and other Python modules. This
+should be automatically enabled by default if the prerequisite software
+is installed when compiling with CMake. It can be enforced during CMake
+configuration by setting the variable `MLIAP_ENABLE_PYTHON=yes` or for
+conventional build by adding `-DMLIAP_PYTHON` to the `LMP_INC` variable
+in your makefile and running the cythonize script on the .pyx file(s)
+copied to the src folder.
+
+Using the `mliappy` energy model also requires to install the PYTHON
+package and have the [cython](https://cython.org) software
+installed. During configuration/compilation the cythonize script will be
+used to convert the provided .pyx file(s) to C++ code.  Please do *NOT*
+run the cythonize script manually in the src/ML-IAP folder. If you have
+done so by accident, you need to delete the generated .cpp and .h
+file(s) in the src/ML-IAP folder or there may be problems during
+compilation.
+
+More information on building LAMMPS with this package is
+[here](https://docs.lammps.org/Build_extras.html#mliap).

src/MLIAP/README.md

@@ -1,41 +0,0 @@
-This package provides a general interface to families of machine-learning interatomic potentials (MLIAPs).
-This interface consists of a `mliap pair style` and a `mliap compute`.
-The `mliap pair style` is used when running simulations with energies and
-forces calculated by an MLIAP. The interface allows separate
-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. The pair_style
-supports the following models:
-
-- `linear`,
-- `quadratic`,
-- `nn` (neural networks)
-- `mliappy` (general Python interface to things like PyTorch).
-
-It currently supports only one class of descriptors, `sna`, the SNAP descriptors.
-It is straightforward to add new descriptor and model styles.
-
-The `mliap compute` style provides gradients of the energy, force,
-and stress tensor w.r.t. model parameters.
-These are useful when training MLIAPs to match target data.
-Any `model` or `descriptor` that has been implemented for the
-`mliap` pair style can also be accessed by the `mliap` compute.
-In addition to the energy, force, and stress gradients, w.r.t.
-each `model` parameter, the compute also calculates the energy,
-force, and stress contributions from a user-specified
-reference potential.
-
-## Generating the model files from the third-party packages
-- To train the `linear` and `quadratic` models with the SNAP descriptors, see the examples in [FitSNAP](https://github.com/FitSNAP/FitSNAP).
-- To train the `nn` model with the SNAP descriptors, check the examples in [PyXtal\_FF](https://github.com/qzhu2017/PyXtal_FF).
-
-## Building MLIAP with Python support
-
-The `mliappy` energy model requires that the MLIAP package be compiled with Python support enabled. This extension, written by Nick Lubbers (LANL), provides a coupling to PyTorch and other Python modules. This should be automatically enabled by default if the prerequisite software is installed. It can be enforced during CMake configuration by setting the variable `MLIAP_ENABLE_PYTHON=yes` or for conventional build by adding `-DMLIAP_PYTHON` to the `LMP_INC` variable in your makefile and running the cythonize script on the .pyx file(s) copied to the src folder.
-
-This requires to also install the PYTHON package and have the [cython](https://cython.org) software installed. During configuration/compilation
-the cythonize script will be used to convert the provided .pyx file(s) to C++ code.  Please do not run the cythonize script in the src/MLIAP folder. If you have done so by accident, you need to delete the generated .cpp and .h file(s) in the src/MLIAP folder or there may be problems during compilation.
-
-More information on building LAMMPS with this package is [here](https://docs.lammps.org/Build_extras.html#mliap).

src/Makefile

@@ -48,7 +48,7 @@ endif
 
 PACKAGE = asphere body class2 colloid compress coreshell dipole gpu \
 	  granular kim kokkos kspace latte manybody mc message misc \
-	  mliap molecule mpiio mscg opt peri plugin poems \
+	  ml-iap molecule mpiio mscg opt peri plugin poems \
 	  python qeq replica rigid shock snap spin srd voronoi
 
 PACKUSER = user-adios user-atc user-awpmd user-brownian user-bocs user-cgdna \