General NeighbourList Interface

[cortner]

There is a use-case for a general interface to different neighbourlist implementations.

(Previous discussions have failed to lead anywhere...)

[cortner]

Notes on NeighbourList Discussions

Acronyms

• NL = NeighbourLists.jl
• CLM = CellListMap.jl
• MIC = minimum-image convention

Some general comments

• Currently there seem to be two mature neighourlists in Julia, NL and CLM. CLM has better performance, while NL is more robust in corner cases, in particular small domains. NearestNeighbours.jl can also be used to produce neighbourlists for isolated systems and even for PBC but only with MIC.
• It is tempting to first implement a nlist that only works in the MIC and cubic case. I want to caution against this. It may be useful for large-scale materials and bio-molecular simulation, but it would be essentially unusable for ML models (potentials, hamiltonians, CG) since (i) those models are normally trained on small structures without MIC and even unit cells that are not cubic; (ii) ML models are increasingly incorporating semi-local interaction ranging from 8-20 A. A cell would need to be quite large to still satisfy MIC with 20 A. Moreover, it is not entirely trivial to extend the neighbourlist beyond MIC and might require restructuring.

Goals

• Common interface to NL and CLM, and all future neighbourlist implementations.
• Testing framework. (Currently NL tests against NearestNeighbours.jl, ASE and Kermode & Pastewka implementations)
• There could be a front-end that selects a suitable nlist implementation based on properties of the structure (e.g. MIC)

Suggestions for a general nlist interface

• Check for capabilities (e.g. !MIC, pbc, !cubic)
• For site potentials we need

   Js, Rs, Zs, z0 = get_neighbours(nlist, i, ...)
   Js : indices of neighbours 
   Rs : vectors ri - rj 
   Zs : particle ids of neighbours 
   z0 : particle id of center i 

• For Brillouin zone integration (e.g. Hamiltonians we also needshifts

   Ss : shifts into neighbouring cell 
        could be retrieved from Rs and position(j) - position(i)

• To enable efficient vectorization on modern CPUs and GPUs there should also be a way to retrieve batches of atomic environments, e.g., this could be done in the form

   Is, Js, Zs, Z0s = get_neigs_batch(nlist, 1:16, ...) 

• For pair interaction type models there could be a separate interface that returns a list of all pairs Is, Js, Rs, ... = get_pairs(nlist, ...)
• There could be iterate type protocols to wrap the foregoing information. But the explicit access can be important in some cases so I would not drop that from the interface.

The above list only explains the kind of information that is required. How that information is more efficiently stored and retrieved will hopefully also be discussed but I currently have no strong view on that.

Steps towards a common interface

• I would be happy to give up the NL repo to become and interface and move the current NL implementation to a differently named package or as a prototype implementation as a sub-module of NL.
• CLM and NL currently return information differently. I do not believe it would be difficult to modify those lists and/or write wrappers so they can provide an interface similar to what is sketched out above.