Merge branch 'develop' into develop

Author: RKLindsey

doc/source/etc.rst

@@ -1,3 +1,4 @@
+
 .. _etc:
 
 ChIMES in LAMMPS
@@ -63,13 +64,75 @@ Note that the following must also be set in the main LAMMPS input file, to use C
     atom_style  atomic		
     atom_modify sort 0 0.0	
 
+**Important Considerations:**
+
+Atom Type Mass Matching
+"""""""""""""""""""""
+
+The element masses defined in the ChIMES parameter file must match the masses defined in the LAMMPS data file. The matching is done by comparing masses to within 0.001 atomic mass units. The order of atom types in the files does not matter - only the mass values need to match.
+
+For example, if your ChIMES parameter file defines elements with masses 12.011 and 15.999, then your LAMMPS data file must have atom types with matching masses, regardless of the order they appear in the files.
+
+**ChIMES Parameter File Example:**
+The parameter file defines atom types with specific masses:
+
+.. code-block:: text
+
+    ATOM TYPES: 2
+
+    # TYPEIDX #     # ATM_TYP #     # ATMCHRG #     # ATMMASS #
+    0               C               0               12.011
+    1               O               0               15.999
+
+**LAMMPS Data File Example:**
+The data file must have atom types with matching masses (order doesn't matter):
+
+.. code-block:: text
+  
+    2 atom types
+
+    Masses
+
+    1 12.0107  # C (matches ChIMES mass 12.011 within tolerance)
+    2 15.9994  # O (matches ChIMES mass 15.999 within tolerance)
+
+**Important:** If no mass matches are found between the ChIMES parameter file and LAMMPS data file, the simulation will terminate with an error, as ChIMES cannot be used for any interactions.
+
+Hybrid Overlay Usage
+"""""""""""""""""""
+
+ChIMES can be used simultaneously with other potentials using LAMMPS' hybrid/overlay pair style. This allows you to combine ChIMES with additional force fields for specific interactions.
+
+**Example of hybrid/overlay usage:**
+
+.. code-block:: text
+
+    pair_style      hybrid/overlay chimesFF momb 9.0 0.75 20.0 lj/cut 10.0
+    pair_coeff      * * chimesFF ${param_file}
+    pair_coeff      1 1 momb 0.0 1.0 1.0 418.26 2.904
+    pair_coeff      1 2 lj/cut 0.25   3.5
+    pair_coeff      2 2 lj/cut 0.25   3.5
+
+In this example, ChIMES is combined with MOMB (Many-body van der Waals) and Lennard-Jones potentials for different atom type interactions. 
+
+Models with D2 Dispersion Correction
+"""""""""""""""""""""""""""""""""""
+
+Using hybrid ChIMES and MOMB is specifically for adding D2 dispersion correction at the time of using LAMMPS. Whether to include MOMB and the parameters used is specific to the ChIMES parameterization and should not be added arbitrarily.
+
+**Important:** When using MOMB with ChIMES, you must include the ``make yes-extra-pair`` command in the install.sh script when compiling LAMMPS to enable the MOMB potential support.
+
+.. code-block:: text
+
+    # Compile
+
+    cd build/${lammps}/src
+    make yes-manybody
+    make yes-extra-pair
 
 .. Warning::
 
     1. Implementation assumes outer cutoffs for (n+1)-body interactions are always :math:`\le` those for n-body interactions
     2. This capability is still under testing - please `let us know <https://groups.google.com/g/chimes_software>`_ if you observe strange behavior
     3. Assumes user wants single-atom energies to be added to the system energy. If you don't want to, zero the energy offsets in the parameter file
 
-
-Examples
-^^^^^^^^^^^^^^^^

doc/source/fingerprint_example.pdf

@@ -29,26 +29,30 @@ Please see :ref:`the special Github instructions <page-getting_started-Open-GH>`
 Compiling and running the code
 ****************************************
 
-As described above, the ``chimes_calculator`` comprises library tools for evaluating ChIMES interactions. However, the repository contains several usage examples (see, e.g. :ref:`ChIMES Calculator <sec-use-examples-api>` and :ref:`ChIMES Calculator Serial Interface <sec-ser-use-examples-api>` examples.). These examples can be compiled by navigating to a given example sub directory (e.g. ``chimes FF/examples/cpp/``) and typing ``make``.
+As described above, the ``chimes_calculator`` comprises library tools for evaluating ChIMES interactions. Further information about the model architecture can be found in :ref:`ChIMES Calculator <page-chimesFF>`. ``chimesFF.h`` and ``chimesFF.cpp`` are the source files that implement the core logic of calculating ChIMES interactions given the cluster of atoms.  When the class defined therein is instantiated, it read in a ChIMES parameter file. It then can be used to evaluate individual terms in the many-body cluster expansion that defines the ChIMES potential. Specifically, it contains functions to compute energy, stress tensor, and per-atom forces for an individual 2-, 3- or 4-body cluster of atoms, given their coordinates.
 
+For most applications, chimesFF should be integrated into a simulation code that can take a full system configuration, extract all n-body clusters while respecting periodic boundary conditions, and feed them into chimesFF. An example to do this is provided in :ref:`ChIMES Calculator Serial Interface <sec-ser-use-examples-api>`, which demonstrates how to use the ``chimes_calculator`` for an overall system evaluation. We also provide an implementation of chimesFF as a pair_style in lammps in the :ref:`The ChIMES Calculator with LAMMPS <page-etc>` page.
 
-Alternatively, the entire software suite can be compiled at once using CMake, via the install script - note that C++, C, *and* Fortran compilers are all required to use the this approach. 
+These examples can be compiled by navigating to a given example subdirectory (e.g. ``chimesFF/examples/cpp/``) and typing ``make``.
 
+You can compile and install the entire software suite in different computing environments. All require C, C++ and Fortran compilers:
 
-If your environment is correctly configured, you can simply execute ``./install.sh``.
+ * Standard Installation (Local Machine or Basic Environment)
 
-If you are on a HPC using module files, you may need to load them first. Module files are already configured for a handful of HPC - inspect the contents of modfiles to see if
-yours is listed. If it is (e.g., LLNL-LC.mod), execute ``export hosttype=LLNL-LC; ./install.sh`` to install. Otherwise, load the appropriate modules by hand before running the
-install script.
+      *  If your environment is correctly configured, you can simply execute ``./install.sh`` in the outer most directory.
 
-.. Note :: 
 
-   Consider submitting module files and corresponding install.sh changes as a PR, for your HPC!
+ * Installation on an HPC cluster
+
+      * You need to load pre-configured module files first. Module files are already configured for a handful of HPC in ``/modfiles/`` ; verify if yours is listed. If it is (e.g., LLNL-LC.mod), execute ``export hosttype=LLNL-LC; ./install.sh`` to install. Otherwise, load the appropriate modules by hand before running the install script.
 
+ * CMake-Based Installation
 
-, or executing the appropriate CMake commands by simply running ``./install.sh`` from the base ``chimes_calculator`` directory. If the latter option is used, a list of generated executables/library files and their respective install locations can be found in the generated ``build/install_manifest.txt`` file. Note that C++, C, *and* Fortran compilers are all required to use the ``./install.sh`` approach. 
+      * You can execute the appropriate CMake commands by simply running ``./install.sh`` from the base       ``chimes_calculator`` directory. If this option is used, a list of generated executables/library files and their respective install locations can be found in the generated ``build/install_manifest.txt`` file. 
 
+.. Note :: 
 
+   Consider submitting module files and corresponding install.sh changes as a PR, for your HPC! 
 
 
 Sample ChIMES parameter and input files are provided in the ``serial_interface/tests/force_fields`` and ``serial_interface/tests/configurations`` directories, allowing compiled executables to be tested via, e.g.:
@@ -58,10 +62,16 @@ Sample ChIMES parameter and input files are provided in the ``serial_interface/t
     serial_interface/examples/cpp/chimescalc \
     serial_interface/tests/force_fields/published_params.liqC.2b.cubic.txt \
     serial_interface/tests/configurations/liqC.2.5gcc_6000K.OUTCAR_#000.xyz | tee my_test.log 
+
+Compiling the ChIMES Calculator with LAMMPS
+*********************************************
+
+We implemented the CHIMES in the `LAMMPS <https://lammps.sandia.gov/>`_ and detailed information regarding Compiling and running can be found in :ref:`The ChIMES Calculator with LAMMPS <page-etc>`. 
 
 
-For additional details on using, integrating, and compiling, and contributing, see:
+For additional details on using, integrating, compiling, and contributing, see:
 
 * :ref:`The ChIMES Calculator <page-chimesFF>`
 * :ref:`The ChIMES Calculator Serial Interface <page-serial_interface>`
+* :ref:`The ChIMES Calculator with LAMMPS <page-etc>`
 * :ref:`Contributing <page-contributing>`

doc/source/getting_started.rst

@@ -6,7 +6,10 @@ The ChIMES Calculator Serial Interface
 Overview
 ********
 
-The ChIMES calculator serial interface provides an easier means of evaluating ChIMES interactions for a given system. In constrast to the ChIMES calculator (i.e. ``chimesFF``), which takes information on *individual* atom clusters and returns the cluster energy, stress tensor, via ``compute_xB`` functions, the serial interface (i.e. ``serial_chimes_interface``) takes *overall* system information and returns *overall* system energy, stress tensor, and forces. Though far less flexible than direct use of ``chimesFF``, ``serial_chimes_interface`` allows users to leverage ChIMES with much less coding. For further details on ``chimesFF``, see :ref:`The ChIMES Calculator <page-chimesFF>`. For a complete set of ChIMES references, see :ref:`Citing ChIMES <page-citing>`. Note that this functionality is primarily intended for instructive purposes, and is not recommended for large scale simulations.
+The ChIMES calculator serial interface provides an easier means of evaluating ChIMES interactions for a given system. In contrast to the ChIMES calculator (i.e. ``chimesFF``), which takes information on *individual* atom clusters and returns the cluster energy, stress tensor, via ``compute_xB`` functions, the serial interface (i.e. ``serial_chimes_interface``) takes *overall* system information and returns *overall* system energy, stress tensor, and forces. Though far less flexible than direct use of ``chimesFF``, ``serial_chimes_interface`` allows users to leverage ChIMES with much less coding. For examples of how to implement the ChIMES calculator serial interface with different APIs, refer to :ref:`Implementation Examples <sec-ser-use-examples-api>`. For further details on ``chimesFF``, see :ref:`The ChIMES Calculator <page-chimesFF>`. For a complete set of ChIMES references, see :ref:`Citing ChIMES <page-citing>`. 
+
+.. Note:: 
+    The serial interface is intended to primarily serve as an easy-to-read example of how to use/implement the chimesFF library in various user codes. Hence, the implementation is not optimized for computational efficiency and therefore not recommended for use in long or large scale simulations. For users seeking a computationally efficient out-of-the-box simulation capability, we recommend using our LAMMPS implementation. See the :ref:`ChIMES in LAMMPS <page-etc>` for more details.
 
 
 The ChIMES Calculator Serial Interface
@@ -24,7 +27,7 @@ The ChIMES calculator serial interface source files are located in ``serial_inte
 
 .. Warning::
 
-	For small simulation cells (e.g., a single atom in a face-centered cubic unit cell), the ChIMES calculator must be instantiated via ``serial_chimes_interface chimes(true)``. This allows for automatic replication in situations where the ChIMES outer cutoff is greater than one half of the smallest supercell length. Please note that use of extra-small simulation cells is ill-advised for aything except crystalline systems and should be used with caution. 
+	It is recommended to have a supercell length of at least double the outer cutoff. For small simulation cells (e.g., a single atom in a face-centered cubic unit cell), the ChIMES calculator must be instantiated via ``serial_chimes_interface chimes(true)``. This allows for automatic replication in situations where the ChIMES outer cutoff is greater than one half of the smallest supercell length. Please note that use of extra-small simulation cells is ill-advised for aything except crystalline systems and should be used with caution. 
 
     *Developer note: To recover behavior of the research code, instantiate with:* ``serial_chimes_interface chimes(false)``.
 
@@ -111,10 +114,10 @@ void        calculate_chimes            =======================   =====
                                         double array              Vector of x-coordinates for system atoms
                                         double array              Vector of y-coordinates for system atoms
                                         double array              Vector of z-coordinates for system atoms
-                                        char  array               System cell a lattice vector
+                                        char array                Vector of atom types for system atoms
+                                        double array              System cell a lattice vector
                                         double array              System cell b lattice vector
                                         double array              System cell c lattice vector
-                                        double array              Vector of atom types for system atoms
                                         double*                   Overall system energy (updated by function)
                                         double array              Vector of forces for system atoms (updated by function); ([atom index][fx, fy, fz])
                                         double array              System stress tensor (updated by function); ([s_xx, s_xy, s_xz, s_yx, s_yy, s_yz, s_zx, s_zy, s_zz])
@@ -178,10 +181,10 @@ void        f_calculate_chimes          =======================   =====
                                         C_double array              Vector of x-coordinates for system atoms
                                         C_double array              Vector of y-coordinates for system atoms
                                         C_double array              Vector of z-coordinates for system atoms
-                                        C_char  array               System cell a lattice vector
+                                        C_char array                Vector of atom types for system atoms
+                                        C_double array              System cell a lattice vector
                                         C_double array              System cell b lattice vector
                                         C_double array              System cell c lattice vector
-                                        C_double array              Vector of atom types for system atoms
                                         C_double*                   Overall system energy (updated by function)
                                         C_double array              Vector of forces for system atoms (updated by function); ([atom index][fx, fy, fz])
                                         C_double array              System stress tensor (updated by function); ([s_xx, s_xy, s_xz, s_yx, s_yy, s_yz, s_zx, s_zy, s_zz])
@@ -328,10 +331,10 @@ See description calculate_chimes            =======================   =====
                                             float list                Vector of x-coordinates for system atoms
                                             float list                Vector of y-coordinates for system atoms
                                             float list                Vector of z-coordinates for system atoms
-                                            str list                  System cell a lattice vector
+                                            str list                  Vector of atom types for system atoms
+                                            float list                System cell a lattice vector
                                             float list                System cell b lattice vector
                                             float list                System cell c lattice vector
-                                            float list                Vector of atom types for system atoms
                                             float                     Overall system energy
                                             float list                Vector of forces for system atoms ([atom index][fx, fy, fz])
                                             float list                System stress tensor ([s_xx, s_xy, s_xz, s_yx, s_yy, s_yz, s_zx, s_zy, s_zz])
@@ -364,15 +367,18 @@ Implementation Examples
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 The following codes demonstrates how ``serial_chimes_interface.{h,cpp}`` can be used to obtain the overall stress tensor, energy, and per-atom forces for a given system configuration using C, C++ Fortran, and Python. See the ``main.*`` files in each corresponding subdirectory of ``serial_interface/examples`` for further implementation details. Note that sample system configurations (i.e. ``*xyz`` files) and parameter files can be found in ``serial_interface/test/configurations`` and ``serial_interface/test/force_fields``, respectively.
-For user generated tests, note that ``*.xyz`` files must provide lattice vectors in the comment line, e.g. lx 0.0 0.0 0.0 ly 0.0 0.0 0.0 lz. Click :ref:`here <page-units>` for an overview of ChIMES units.
+
+.. Note:: 
+
+    For user generated tests, note that ``*.xyz`` files must provide lattice vectors in the comment line, e.g. lx 0.0 0.0 0.0 ly 0.0 0.0 0.0 lz. Click :ref:`here <page-units>` for an overview of ChIMES units.
 
 .. Note::
 
     All implementation examples are intended to be run on Unix-based systems (e.g. Linux, OSX).
 
 .. Warning::
 
-     These codes are for demonstrative purposes only and come with no guarantees.
+    These codes are for demonstrative purposes only and come with no guarantees.
 
 .. Note::
 
@@ -400,21 +406,19 @@ For user generated tests, note that ``*.xyz`` files must provide lattice vectors
    * Navigate to ``serial_interface/examples/fortran``
    * Compile with: ``make all``
    * Test with: ``./chimescalc-test_serial-F <parameter file> <xyz file>``
-   * Additional notes:
 
 * **Fortran2008 Example:** Similarly, this ``main`` function establishes a pointer to a ``serial_chimes_interface`` object via calls to ``ChimesCalc_init()`` and subroutine calls within the ``ChimesCalc`` class, defined in ``chimescalc_serial_F08.f90.``
   Subroutines called from the Fortran2008 API act as an interface for the wrapper functions establied in the Fortran90 API. Actual linking is achieved at compilation. See the ``Makefile`` for details.
 
    * Navigate to ``serial_interface/examples/fortran08``
    * Compile with: ``make all``
    * Test with: ``./chimescalc-test_serial-F08 <parameter file> <xyz file>``
-   * Additional notes:
 
 * **Python Example:** This example accesses ``serial_chimes_interface`` functions through ``chimescalc_serial_py.py``, a ctypes-based python API for access to the C API functions
   (i.e. through ``chimescalc_serial_C.cpp``). Once ``chimescalc_serial_py.py`` is imported, it is associated with a compiled C API library file, i.e. ``lib-C_wrapper-serial_interface.so`` and  can be used to access ``serial_chimes_interface`` member functions.
 
    * Navigate to ``serial_interface/examples/python``
    * Compile ``libchimescalc-serial_dl.so`` with: ``make all``
    * Rename: ``cp libchimescalc-serial_dl.so libchimescalc_dl.so``
-   * Test with: ``python main.py <parameter file> <coordinate file>``
+   * Test with: ``python main.py <parameter file> <xyz file>``