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

0 in case a compute has multiple neighbor list requests.

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

Note

The array of neighbors is part of the neighbor list itself, so the neighbor indices are stored the same way LAMMPS uses them internally. For systems with special neighbors (pairs of atoms connected by bonds, angles, or dihedrals), the two highest bits of a neighbor index may be set to record whether that pair is a 1-2, 1-3, or 1-4 neighbor. Such indices are very large or negative numbers and must have those bits removed before they can be used as local atom indices, e.g. with j = neighbors[jj] & 0x1FFFFFFF;. The value of (neighbors[jj] >> 30) & 3 is 1, 2, or 3 for 1-2, 1-3, or 1-4 neighbors, respectively, and 0 for all other neighbors.

No bits are set for special neighbors with weighting factors of 1.0 for both Lennard-Jones and Coulomb interactions. Special neighbors with weighting factors of 0.0 for both are removed from the neighbor list instead, except for the cases listed in the special_bonds command documentation (e.g. when a KSpace style is used), where the bits are set for all special neighbors.

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