1.1.7. Neighbor list access — LAMMPS documentation

\(\renewcommand{\AA}{\text{Å}}\)

# 1.1.7. Neighbor list access

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

- `lammps_find_compute_neighlist()`

- `lammps_find_fix_neighlist()`

- `lammps_find_pair_neighlist()`

- `lammps_neighlist_num_elements()`

- `lammps_neighlist_element_neighbors()`

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

  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