1.1.7. Neighbor list access

The following functions enable access to neighbor lists generated by LAMMPS or querying of their properties:


int lammps_find_compute_neighlist(void *handle, const char *id, int request)

Find index of a neighbor list requested by a compute

The neighbor list request from a compute is identified by the compute ID and the request ID. The request ID is typically 0, but will be

Parameters
  • handle – pointer to a previously created LAMMPS instance cast to void *.

  • id – Identifier of compute instance

  • reqid – request id to identify neighbor list in case there are multiple requests from the same compute

Returns

return neighbor list index if found, otherwise -1


int lammps_find_fix_neighlist(void *handle, const char *id, int request)

Find index of a neighbor list requested by a fix

The neighbor list request from a fix is identified by the fix ID and the request ID. The request ID is typically 0, but will be > 0 in case a fix has multiple neighbor list requests.

Parameters
  • handle – pointer to a previously created LAMMPS instance cast to void *.

  • id – Identifier of fix instance

  • reqid – request id to identify neighbor list in case there are multiple requests from the same fix

Returns

return neighbor list index if found, otherwise -1


int lammps_find_pair_neighlist(void *handle, const char *style, int exact, int nsub, int request)

Find index of a neighbor list requested by a pair style

This function determines which of the available neighbor lists for pair styles matches the given conditions. It first matches the style name. If exact is 1 the name must match exactly, if exact is 0, a regular expression or sub-string match is done. If the pair style is hybrid or hybrid/overlay the style is matched against the sub styles instead. If a the same pair style is used multiple times as a sub-style, the nsub argument must be > 0 and represents the nth instance of the sub-style (same as for the pair_coeff command, for example). In that case nsub=0 will not produce a match and this function will return -1.

The final condition to be checked is the request ID (reqid). This will normally be 0, but some pair styles request multiple neighbor lists and set the request ID to a value > 0.

Parameters
  • handle – pointer to a previously created LAMMPS instance cast to void *.

  • style – String used to search for pair style instance

  • exact – Flag to control whether style should match exactly or only a regular expression / sub-string match is applied.

  • nsub – match nsub-th hybrid sub-style instance of the same style

  • reqid – request id to identify neighbor list in case there are multiple requests from the same pair style instance

Returns

return neighbor list index if found, otherwise -1


int lammps_neighlist_num_elements(void *handle, int idx)

Return the number of entries in the neighbor list with given index

Parameters
  • handle – pointer to a previously created LAMMPS instance cast to void *.

  • idx – neighbor list index

Returns

return number of entries in neighbor list, -1 if idx is not a valid index


void lammps_neighlist_element_neighbors(void *handle, int idx, int element, int *iatom, int *numneigh, int **neighbors)

Return atom local index, number of neighbors, and array of neighbor local atom indices of neighbor list entry

Parameters
  • handle – pointer to a previously created LAMMPS instance cast to void *.

  • idx – index of this neighbor list in the list of all neighbor lists

  • element – index of this neighbor list entry

  • iatom[out] local atom index (i.e. in the range [0, nlocal + nghost), -1 if invalid idx or element value

  • numneigh[out] number of neighbors of atom iatom or 0

  • neighbors[out] pointer to array of neighbor atom local indices or NULL