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>`
+Building the ML-IAP package requires including the :ref:`SNAP
-package.  There will be an error message if this requirement is not satisfied.
+<PKG-SNAP>` package.  There will be an error message if this requirement
-Using the *mliappy* model also requires enabling Python support, which
+is not satisfied.  Using the *mliappy* model also requires enabling
-in turn requires the :ref:`PYTHON <PKG-PYTHON>`
+Python support, which in turn requires to include the :ref:`PYTHON
-package **and** requires you have the `cython <https://cython.org>`_ software
+<PKG-PYTHON>` package **and** requires to have the `cython
-installed and with it a working ``cythonize`` command.  This feature requires
+<https://cython.org>`_ software installed and with it a working
-compiling LAMMPS with Python version 3.6 or later.
+``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
+      To enable building the ML-IAP package with Python support enabled,
-      ``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in your machine makefile.
+      you need to add ``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in
-      You may have to manually run the ``cythonize`` command on .pyx file(s)
+      your machine makefile.  You may have to manually run the
-      in the ``src`` folder, if this is not automatically done during
+      ``cythonize`` command on .pyx file(s) in the ``src`` folder, if
-      installing the MLIAP package.  Please do **not** run ``cythonize``
+      this is not automatically done during installing the ML-IAP
-      in the ``src/MLIAP`` folder, as that can lead to compilation errors
+      package.  Please do **not** run ``cythonize`` in the ``src/ML-IAP``
-      if Python support is not enabled.
+      folder, as that can lead to compilation errors if Python support
-      If you did by accident, please remove the generated .cpp and .h files.
+      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/ML-IAP: filenames -> commands
-* src/MLIAP/README
+* 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 *model* keyword is followed by the model style (*linear*,
-The *mliappy* model is only available
+*quadratic* or *mliappy*).  The *mliappy* model is only available if
-if lammps is built with MLIAPPY package.
+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 *descriptor* keyword is followed by a descriptor style, and
-The compute currently supports just one descriptor style, but it is
+additional arguments.  The compute currently supports two descriptor
-is straightforward to add new descriptor styles.
+styles *sna* and *so3*, but it is is straightforward to add additional
-The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
+descriptor styles.  The SNAP descriptor style *sna* is the same as that
-including the linear, quadratic, and chem variants.
+used by :doc:`pair_style snap <pair_snap>`, including the linear,
-A single additional argument specifies the descriptor filename
+quadratic, and chem variants.  A single additional argument specifies
-containing the parameters and setting used by the SNAP descriptor.
+the descriptor filename containing the parameters and setting used by
-The descriptor filename usually ends in the *.mliap.descriptor* extension.
+the SNAP descriptor.  The descriptor filename usually ends in the
-The format of this file is identical to the descriptor file in the
+*.mliap.descriptor* extension.  The format of this file is identical to
-:doc:`pair_style mliap <pair_mliap>`, and is described in detail
+the descriptor file in the :doc:`pair_style mliap <pair_mliap>`, and is
-there.
+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
+This compute is part of the ML-IAP package.  It is only enabled if
-was built with that package. In addition, building LAMMPS with the MLIAP package
+LAMMPS was built with that package. In addition, building LAMMPS with
-requires building LAMMPS with the SNAP package.
+the ML-IAP package requires building LAMMPS with the SNAP package.  The
-The *mliappy* model requires building LAMMPS with the PYTHON package.
+*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

@@ -84,35 +84,35 @@ Au_u3 = Gold universal 3
 The suffix of each file indicates the pair style it is used with:
 
 adp           ADP angular dependent potential
-airebo	      AI-REBO and REBO potentials
+airebo        AI-REBO and REBO potentials
 bop.table     BOP potential, tabulated form
 cdeam         concentration-dependent EAM
 comb          COMB potential
 comb3         COMB3 potential
-eam	      embedded atom method (EAM) single element, DYNAMO funcfl format
+eam           embedded atom method (EAM) single element, DYNAMO funcfl format
 eam.alloy     EAM multi-element alloy, DYNAMO setfl format
-eam.fs	      Finnis-Sinclair EAM format (single element or alloy)
+eam.fs        Finnis-Sinclair EAM format (single element or alloy)
 edip          EDIP potential for silicon-based materials
 eim           embedded-ion method (EIM) potential
 lcbop         LCBOP long-range bond-order potential
-meam	      modified EAM (MEAM) library and individual elements/alloys
+meam          modified EAM (MEAM) library and individual elements/alloys
 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         ML-IAP potential
-mliap.descriptor MLIAP potential descriptor
+mliap.descriptor ML-IAP potential descriptor
-mliap.model   MLIAP potential model
+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)
+reax          ReaxFF potential (see README.reax for more info)
 smtbq         second moment tight binding QEq (SMTBQ) potential
 snap          SNAP potential
 snapcoeff     SNAP potential
 snapparam     SNAP potential
 streitz       Coulombic portion of Streitz-Mintmire potential
-sw	      Stillinger-Weber potential
+sw            Stillinger-Weber potential
-tersoff	      Tersoff potential
+tersoff       Tersoff potential
 tersoff.mod   modified Tersoff potential
 tersoff.zbl   Tersoff with ZBL core
 vashishta     Vashishta 2-body and 3-body potential

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 \