1.1.6. Scatter/gather operations

This section has functions which gather per-atom data from one or more processors into a contiguous global list ordered by atom ID. The same list is returned to all calling processors. It also contains functions which scatter per-atom data from a contiguous global list across the processors that own those atom IDs. It also has a create_atoms() function which can create new atoms by scattering them appropriately to owning processors in the LAMMPS spatial decomposition.

It documents the following functions:

void lammps_gather_atoms(void *handle, char *name, int type, int count, void *data)
void lammps_gather_atoms_concat(void *handle, char *name, int type, int count, void *data)
void lammps_gather_atoms_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)
void lammps_scatter_atoms(void *handle, char *name, int type, int count, void *data)
void lammps_scatter_atoms_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)
void lammps_gather_bonds(void *handle, void *data)

Gather type and constituent atom info for all bonds

This function copies the list of all bonds into a buffer provided by the calling code. The buffer will be filled with bond type, bond atom 1, bond atom 2 for each bond. Thus the buffer has to be allocated to the dimension of 3 times the total number of bonds times the size of the LAMMPS “tagint” type, which is either 4 or 8 bytes depending on whether they are stored in 32-bit or 64-bit integers, respectively. This size depends on the compile time settings used when compiling the LAMMPS library and can be queried by calling lammps_extract_setting() with the keyword “tagint”.

When running in parallel, the data buffer must be allocated on all MPI ranks and will be filled with the information for all bonds in the system.

New in version 28Jul2021.

Below is a brief C code demonstrating accessing this collected bond information.

#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include "library.h"

int main(int argc, char **argv)
{
    int tagintsize;
    int64_t i, nbonds;
    void *handle, *bonds;

    handle = lammps_open_no_mpi(0, NULL, NULL);
    lammps_file(handle, "in.some_input");

    tagintsize = lammps_extract_setting(handle, "tagint");
    if (tagintsize == 4)
        nbonds = *(int32_t *)lammps_extract_global(handle, "nbonds");
     else
        nbonds = *(int64_t *)lammps_extract_global(handle, "nbonds");
    bonds = malloc(nbonds * 3 * tagintsize);

    lammps_gather_bonds(handle, bonds);

    if (lammps_extract_setting(handle, "world_rank") == 0) {
        if (tagintsize == 4) {
            int32_t *bonds_real = (int32_t *)bonds;
            for (i = 0; i < nbonds; ++i) {
                printf("bond % 4ld: type = %d, atoms: % 4d  % 4d\n",i,
                       bonds_real[3*i], bonds_real[3*i+1], bonds_real[3*i+2]);
            }
        } else {
            int64_t *bonds_real = (int64_t *)bonds;
            for (i = 0; i < nbonds; ++i) {
                printf("bond % 4ld: type = %ld, atoms: % 4ld  % 4ld\n",i,
                       bonds_real[3*i], bonds_real[3*i+1], bonds_real[3*i+2]);
            }
        }
    }

    lammps_close(handle);
    lammps_mpi_finalize();
    free(bonds);
    return 0;
}

Parameters

  • handle – pointer to a previously created LAMMPS instance

  • data – pointer to data to copy the result to

void lammps_gather(void *handle, char *name, int type, int count, void *data)
void lammps_gather_concat(void *handle, char *name, int type, int count, void *data)
void lammps_gather_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)
void lammps_scatter(void *handle, char *name, int type, int count, void *data)
void lammps_scatter_subset(void *handle, char *name, int type, int count, int ndata, int *ids, void *data)
int lammps_create_atoms(void *handle, int n, const int *id, const int *type, const double *x, const double *v, const int *image, int bexpand)

Create N atoms from list of coordinates

The prototype for this function when compiling with -DLAMMPS_BIGBIG is:

int lammps_create_atoms(void *handle, int n, int64_t *id, int *type, double *x, double *v, int64_t *image, int bexpand);

This function creates additional atoms from a given list of coordinates and a list of atom types. Additionally the atom-IDs, velocities, and image flags may be provided. If atom-IDs are not provided, they will be automatically created as a sequence following the largest existing atom-ID.

This function is useful to add atoms to a simulation or - in tandem with lammps_reset_box() - to restore a previously extracted and saved state of a simulation. Additional properties for the new atoms can then be assigned via the lammps_scatter_atoms() lammps_extract_atom() functions.

For non-periodic boundaries, atoms will not be created that have coordinates outside the box unless it is a shrink-wrap boundary and the shrinkexceed flag has been set to a non-zero value. For periodic boundaries atoms will be wrapped back into the simulation cell and its image flags adjusted accordingly, unless explicit image flags are provided.

The function returns the number of atoms created or -1 on failure, e.g. when called before as box has been created.

Coordinates and velocities have to be given in a 1d-array in the order X(1),Y(1),Z(1),X(2),Y(2),Z(2),…,X(N),Y(N),Z(N).

Parameters

  • handle – pointer to a previously created LAMMPS instance

  • n – number of atoms, N, to be added to the system

  • id – pointer to N atom IDs; NULL will generate IDs

  • type – pointer to N atom types (required)

  • x – pointer to 3N doubles with x-,y-,z- positions of the new atoms (required)

  • v – pointer to 3N doubles with x-,y-,z- velocities of the new atoms (set to 0.0 if NULL)

  • image – pointer to N imageint sets of image flags, or NULL

  • bexpand – if 1, atoms outside of shrink-wrap boundaries will still be created and not dropped and the box extended

Returns

number of atoms created on success; -1 on failure (no box, no atom IDs, etc.)