[gmx-developers] Fairly detailed question regarding cell lists in Gromacs in general and nsgrid_core specifically

[Pedro Gonnet]

Hi,

I'm trying to understand how Gromacs builds its neighbor lists and have
been looking, more specifically, at the function nsgrid_core in ns.c.

If I understand the underlying data organization correctly, the grid
(t_grid) contains an array of cells in which the indices of charge
groups are stored. Pairs of such charge groups are identified and stored
in the neighbor list (put_in_list).

What I don't really understand is how these pairs are identified.
Usually one would loop over all cells, loop over each charge group
therein, loop over all neighboring cells and store the charge groups
therein which are within the cutoff distance. 

I assume that the first loop, over all cells, is somehow computed with
the for-loops starting at lines 2135, 2151 and 2173 of ns.c. However, I
don't really understand how this is done: What do these loops loop over
exactly?

In any case, the coordinates of the particle in the outer loop seem to
land in the variables XI, YI and ZI. The inner loop (for-loops starting
in lines 2213, 2216 and 2221 of ns.c) then runs through the neighboring
cells. If I understand correctly, cj is the id of the neighboring cell,
nrj the number of charge groups in that cell and cgj0 the offset of the
charge groups in the data.

What I don't really understand here are the lines 2232--2241:

        /* Check if all j's are out of range so we
         * can skip the whole cell.
         * Should save some time, especially with DD.
         */
        if (nrj == 0 ||
            (grida[cgj0] >= max_jcg &&
             (grida[cgj0] >= jcg1 || grida[cgj0+nrj-1] < jcg0)))
        {
            continue;
        }

Apparently, some cells can be excluded, but what are the exact criteria?
The test on nrj is somewhat obvious, but what is stored in grid->a?

There is probably no short answer to my questions, but if anybody could
at least point me to any documentation or description of how the
neighbors are collected in this routine, I would be extremely thankful!

Cheers, Pedro