class rgpot::nlist::Neighbours

Overview

Candidate pairs around one configuration. More…

#include <Neighbours.hpp>
 
class Neighbours {
public:
    // structs
 
    struct SpecKey;
 
    // methods
 
    void update(const double* xyz, std::size_t n, const double* box9, const Spec& spec);
    Mode mode() const;
    bool streaming() const;
    bool allPairs() const;
    bool reused() const;
    std::uint64_t builds() const;
    std::size_t slots() const;
    const std::vector<std::int32_t>& offsets() const;
    const std::vector<std::int32_t>& neighbours() const;
 
    template <typename Fn>
    void forDirected(std::int64_t begin, std::int64_t end, Fn&& fn) const;
 
    template <typename Fn>
    void forHalf(std::int64_t begin, std::int64_t end, Fn&& fn) const;
 
    template <typename Fn>
    void forCellTeam(bool half, int nthreads, Fn&& fn) const;
 
    template <typename Fn>
    void forAtom(std::int32_t i, Fn fn) const;
};

Detailed Documentation

Candidate pairs around one configuration.

A stored list is reused while every atom has moved by at most half the skin, and the cell, the count and the spec are unchanged. The list holds partner indices only and every walk takes the image from the current coordinates, so the move is measured to the nearest periodic image of the reference position: an atom wrapped back through a face of the cell has moved by its small step, not by a cell vector. The bins are redone after such a wrap, for the walks that read them. Skin 0 reuses the list only when the coordinates and the cell match.

An infinite cutoff or skin makes every pair a candidate. Such an update bins nothing and stores nothing, in any mode: each walk takes the pairs straight from the coordinates, i ascending and then j ascending, which is the order of the single cell the bins would hold.

Methods

bool allPairs() const

True when the search has no bound and the walks visit every pair. Such an update also reports streaming(). One atom has no pairs and keeps the empty stored list.

bool reused() const

True when the last update kept the previous list. The displacement test is withinSkin on the nearest image of each reference position.

std::uint64_t builds() const

Stored lists built so far. A reuse does not count.

std::size_t slots() const

Stored pair index. A stream leaves this empty.

template <typename Fn>
void forDirected(std::int64_t begin, std::int64_t end, Fn&& fn) const

Directed pairs for atoms in [begin, end). dx is r_i - r_j after the selected image. r2 is the squared length of that vector. Candidates lie inside the cutoff plus the skin; the caller drops the rest. In stored mode the partners of each atom are in increasing index order. A walk may copy fn, so state the caller reads back is captured by reference.

template <typename Fn>
void forHalf(std::int64_t begin, std::int64_t end, Fn&& fn) const

The pairs of forDirected with j > i only. Geometry for j <= i is not computed. A serial two-pass potential uses this so each unordered pair is visited once per pass.

template <typename Fn>
void forCellTeam(bool half, int nthreads, Fn&& fn) const

One walk of the directed pairs, split by cell into nthreads slices, each walked once by forEachSlice. The bins are built once and shared. fn(slice, i, j, dx, dy, dz, r2). A slice owns each cell, so a pair is visited once, and one thread walks a slice, so state kept per slice needs no lock. Without bins, as in an unbounded search, a slice owns a contiguous run of atoms. A slice may visit nothing: there can be more slices than cells, or than atoms without bins, and a cell may hold no pair.

template <typename Fn>
void forAtom(std::int32_t i, Fn fn) const

Neighbours of one atom from the bins already built. Does not allocate the tile stencil. A three-body stream uses this so the scratch is one atom, not every bond.