fix(lmp): apply NEIGHMASK to neighbor list (#4269)

Fix #4250.

See lammps/lammps#581 (comment) for
an explanation of `NEIGHMASK`.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

- **New Features**
- Introduced a new function to set a mask for neighbor lists, enhancing
configurability.
	- Added a method to the `InputNlist` structure for setting the mask.
- Enhanced `ComputeDeeptensorAtom` and `FixDPLR` classes to utilize
neighbor list masks in computations.

- **Bug Fixes**
- Improved validation of bonded pairs in the `FixDPLR` class with
enhanced error handling.

- **Documentation**
- Updated documentation for new methods and functionalities related to
neighbor list management.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Signed-off-by: Jinzhe Zeng <jinzhe.zeng@rutgers.edu>

Author: njzjz

source/api_c/include/c_api.h

@@ -12,7 +12,7 @@ extern "C" {
 /** C API version. Bumped whenever the API is changed.
  * @since API version 22
  */
-#define DP_C_API_VERSION 22
+#define DP_C_API_VERSION 23
 
 /**
  * @brief Neighbor list.
@@ -68,6 +68,16 @@ extern DP_Nlist* DP_NewNlist_comm(int inum_,
                                   int* recvproc,
                                   void* world);
 
+/*
+ * @brief Set mask for a neighbor list.
+ *
+ * @param nl Neighbor list.
+ * @param mask mask.
+ * @since API version 23
+ *
+ **/
+extern void DP_NlistSetMask(DP_Nlist* nl, int mask);
+
 /**
  * @brief Delete a neighbor list.
  *

source/api_c/include/deepmd.hpp

@@ -611,6 +611,10 @@ struct InputNlist {
   int *numneigh;
   /// @brief Array stores the core region atom's neighbor index
   int **firstneigh;
+  /**
+   * @brief Set mask for this neighbor list.
+   */
+  void set_mask(int mask) { DP_NlistSetMask(nl, mask); };
 };
 
 /**

source/api_c/src/c_api.cc

@@ -42,6 +42,7 @@ DP_Nlist* DP_NewNlist_comm(int inum_,
   DP_Nlist* new_nl = new DP_Nlist(nl);
   return new_nl;
 }
+void DP_NlistSetMask(DP_Nlist* nl, int mask) { nl->nl.set_mask(mask); }
 void DP_DeleteNlist(DP_Nlist* nl) { delete nl; }
 
 DP_DeepPot::DP_DeepPot() {}

source/api_cc/src/common.cc

@@ -241,6 +241,9 @@ void deepmd::NeighborListData::copy_from_nlist(const InputNlist& inlist) {
     int jnum = inlist.numneigh[ii];
     jlist[ii].resize(jnum);
     memcpy(&jlist[ii][0], inlist.firstneigh[ii], jnum * sizeof(int));
+    for (int jj = 0; jj < jnum; ++jj) {
+      jlist[ii][jj] &= inlist.mask;
+    }
   }
 }
 

source/lib/include/neighbor_list.h

@@ -42,6 +42,8 @@ struct InputNlist {
   int* recvproc;
   /// MPI_comm data in lmp
   void* world;
+  /// mask to the neighbor index
+  int mask = 0xFFFFFFFF;
   InputNlist()
       : inum(0),
         ilist(NULL),
@@ -93,6 +95,10 @@ struct InputNlist {
         recvproc(recvproc),
         world(world) {};
   ~InputNlist() {};
+  /**
+   * @brief Set mask for this neighbor list.
+   */
+  void set_mask(int mask_) { mask = mask_; };
 };
 
 /**

source/lmp/compute_deeptensor_atom.cpp

@@ -136,6 +136,7 @@ void ComputeDeeptensorAtom::compute_peratom() {
   neighbor->build_one(list);
   deepmd_compat::InputNlist lmp_list(list->inum, list->ilist, list->numneigh,
                                      list->firstneigh);
+  lmp_list.set_mask(NEIGHMASK);
 
   // declare outputs
   std::vector<VALUETYPE> gtensor, force, virial, atensor, avirial;

source/lmp/fix_dplr.cpp

@@ -463,6 +463,7 @@ void FixDPLR::pre_force(int vflag) {
   NeighList *list = pair_deepmd->list;
   deepmd_compat::InputNlist lmp_list(list->inum, list->ilist, list->numneigh,
                                      list->firstneigh);
+  lmp_list.set_mask(NEIGHMASK);
   // declear output
   vector<FLOAT_PREC> tensor;
   // compute

source/lmp/pair_deepmd.cpp

@@ -565,6 +565,7 @@ void PairDeepMD::compute(int eflag, int vflag) {
         commdata_->nswap, commdata_->sendnum, commdata_->recvnum,
         commdata_->firstrecv, commdata_->sendlist, commdata_->sendproc,
         commdata_->recvproc, &world);
+    lmp_list.set_mask(NEIGHMASK);
     deepmd_compat::InputNlist extend_lmp_list;
     if (atom->sp_flag) {
       extend(extend_inum, extend_ilist, extend_numneigh, extend_neigh,
@@ -574,6 +575,7 @@ void PairDeepMD::compute(int eflag, int vflag) {
       extend_lmp_list =
           deepmd_compat::InputNlist(extend_inum, &extend_ilist[0],
                                     &extend_numneigh[0], &extend_firstneigh[0]);
+      extend_lmp_list.set_mask(NEIGHMASK);
     }
     if (single_model || multi_models_no_mod_devi) {
       // cvflag_atom is the right flag for the cvatom matrix