Nneigh

Namespaces
namespace	nneigh
	Functions for building neighbour lists.

Classes
class	nneigh::SkinNeighborList
	Persistent neighbour list with a LAMMPS skin. More...

Enumerations
enum class	nneigh::BondGraph { nneigh::BondGraph::Cutoff , nneigh::BondGraph::KnnMutual , nneigh::BondGraph::KnnUnion }
	Bond graph for TUM. More...

Functions
void	nneigh::dumpBoundsToH (const std::vector< double > &box, const std::vector< double > &boxLow, double H[3][3], double origin[3])
	LAMMPS dump bound spans to restricted triclinic H (rows a, b, c).
void	nneigh::dumpCellLengths (const std::vector< double > &box, const std::vector< double > &boxLow, double lengths[3])
	Recovered restricted-triclinic lengths lx, ly, lz (H diagonal).
int	nneigh::dumpAxialDim (const std::vector< double > &box, const std::vector< double > &boxLow)
	Longest recovered length: 0 = x, 1 = y, 2 = z.
int	nneigh::dumpAxialDim (const molSys::PointCloud< molSys::Point< double >, double > &yCloud)
void	nneigh::dumpToFrac (const double H[3][3], const double origin[3], double x, double y, double z, double s[3])
	Cartesian to fractional coordinates via dump H.
void	nneigh::dumpFromFrac (const double H[3][3], const double origin[3], const double s[3], double r[3])
	Fractional to cartesian coordinates via dump H.
double	nneigh::dumpVolume (const std::vector< double > &box, const std::vector< double > &boxLow)
	Triclinic dump-cell volume |det(H)| from dumpBoundsToH.
double	nneigh::dumpVolume (const molSys::PointCloud< molSys::Point< double >, double > &yCloud)
std::vector< std::vector< int > >	nneigh::neighList (double rcutoff, const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI, int typeJ)
	All these functions use atom IDs and not indices.
std::vector< std::vector< int > >	nneigh::neighListPair (double rcutoff, const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI, int typeJ)
bool	nneigh::cellListRowsThreaded (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, const std::vector< int > &subset, double rcutoff, std::vector< std::vector< int > > &rows)
std::vector< std::vector< int > >	nneigh::neighListO (double rcutoff, const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI)
std::vector< std::vector< int > >	nneigh::halfNeighList (double rcutoff, const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI=1)
std::vector< std::vector< int > >	nneigh::neighbourListByIndex (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, const std::vector< std::vector< int > > &nList)
std::vector< std::vector< int > >	nneigh::getNewNeighbourListByIndex (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, double cutoff)
std::vector< std::vector< int > >	nneigh::kNearestNeighbourList (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int k, double candidateCutoff, int typeI, bool mutual=true)
	Bonded graph from the k nearest neighbours of each particle rather than a distance cutoff.
std::vector< std::vector< int > >	nneigh::kNearestNeighbourList (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int k, double candidateCutoff, const std::vector< int > &types, bool mutual=true)
	k-nearest graph on a type set (water oxygens).
std::pair< std::vector< std::vector< int > >, std::vector< std::vector< int > > >	nneigh::kNearestNeighbourPair (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int k, double candidateCutoff, int typeI)
	Mutual and union k-nearest graphs from one candidate search.
std::pair< std::vector< std::vector< int > >, std::vector< std::vector< int > > >	nneigh::kNearestNeighbourPair (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int k, double candidateCutoff, const std::vector< int > &types)
std::pair< double, double >	nneigh::shellSeparation (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int k, int typeI)
	The shell-separation certificate for the exact reduction of the k-nearest graph to the cutoff graph: returns {max_i d_k(i), min_i d_{k+1}(i)} over particles of the type.
std::vector< std::tuple< int, int, double > >	nneigh::nearestUnlike (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI, int typeJ)
	Nearest unlike image of each typeI particle among typeJ particles.
std::vector< std::pair< int, int > >	nneigh::mutualNearestUnlike (const molSys::PointCloud< molSys::Point< double >, double > &yCloud, int typeI, int typeJ)
	Subset of nearestUnlike where j's nearest typeI is i (mutual).
int	nneigh::clearNeighbourList (std::vector< std::vector< int > > &nList)
	Erases memory for a vector of vectors for the neighbour list.
BondGraph	nneigh::bondGraphFromName (const std::string &name)
const char *	nneigh::bondGraphName (BondGraph graph)
	nneigh::SkinNeighborList::SkinNeighborList (double cutoff, double skin, int typeI, BondGraph graph=BondGraph::KnnMutual, int k=4)
BondGraph	nneigh::SkinNeighborList::graph () const
const std::vector< std::vector< int > > &	nneigh::SkinNeighborList::update (const molSys::PointCloud< molSys::Point< double >, double > &yCloud)
bool	nneigh::SkinNeighborList::lastRebuilt () const
int	nneigh::SkinNeighborList::lastChangedAtoms () const
	Atoms whose cutoff bond set changed on the last update.
const std::vector< std::vector< int > > &	nneigh::SkinNeighborList::bonds () const

Detailed Description

Enumeration Type Documentation

BondGraph

enum class nneigh::BondGraph

strong

Bond graph for TUM.

Chosen at runtime so the three published assignments can be compared on the same frames. cutoff: pairs inside the distance cutoff (2020 graph). knn: mutual k-nearest (TUM v2 without hysteresis). knn-union: union k-nearest (the completion graph of the seeded rule).

Enumerator
Cutoff
KnnMutual
KnnUnion

Definition at line 383 of file neighbours.hpp.

{ Cutoff, KnnMutual, KnnUnion };

Function Documentation

bondGraphFromName()

BondGraph nneigh::bondGraphFromName

(

const std::string &

name

)

bondGraphName()

const char * nneigh::bondGraphName

(

BondGraph

graph

)

bonds()

const std::vector< std::vector< int > > & nneigh::SkinNeighborList::bonds ( ) const

inlinenodiscard

Definition at line 413 of file neighbours.hpp.

                                                               {
    return nList_;
  }

cellListRowsThreaded()

bool nneigh::cellListRowsThreaded	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		const std::vector< int > &	subset,
		double	rcutoff,
		std::vector< std::vector< int > > &	rows )

Threaded cell-list neighbour rows. rows[k] holds the indices within rcutoff of subset[k] under the minimum image convention, ascending and without the atom itself. Atoms are binned in fractional coordinates of the recovered triclinic cell H; every axis needs at least three cells of perpendicular width rcutoff, so that the nearest image of every neighbour sits in one of the 27 surrounding cells. Returns false, with rows untouched, when the cell is too small for that, and the caller takes the vesin or brute-force path. Each row is built by one thread.

clearNeighbourList()

int nneigh::clearNeighbourList ( std::vector< std::vector< int > > & nList )

nodiscard

Erases memory for a vector of vectors for the neighbour list.

dumpAxialDim() [1/2]

int nneigh::dumpAxialDim ( const molSys::PointCloud< molSys::Point< double >, double > & yCloud )

inline

Definition at line 131 of file neighbours.hpp.

                                                                 {
  return dumpAxialDim(yCloud.box, yCloud.boxLow);
}

dumpAxialDim() [2/2]

int nneigh::dumpAxialDim ( const std::vector< double > & box, const std::vector< double > & boxLow )

inline

Longest recovered length: 0 = x, 1 = y, 2 = z.

Definition at line 117 of file neighbours.hpp.

                                                         {
  double lengths[3];
  dumpCellLengths(box, boxLow, lengths);
  int axial = 0;
  if (lengths[1] > lengths[axial]) {
    axial = 1;
  }
  if (lengths[2] > lengths[axial]) {
    axial = 2;
  }
  return axial;
}

dumpBoundsToH()

void nneigh::dumpBoundsToH ( const std::vector< double > & box, const std::vector< double > & boxLow, double H[3][3], double origin[3] )

inline

LAMMPS dump bound spans to restricted triclinic H (rows a, b, c).

box[0..2] are xhi_bound - xlo_bound etc. Optional box[3..5] are tilt xy, xz, yz. boxLow is the bound lo. Inverse of xlo_bound = xlo + min(0, xy, xz, xy+xz).

Definition at line 74 of file neighbours.hpp.

                                            {
  const double xspan = box.size() > 0 ? box[0] : 0.0;
  const double yspan = box.size() > 1 ? box[1] : 0.0;
  const double zspan = box.size() > 2 ? box[2] : 0.0;
  const double xlo_b = boxLow.size() > 0 ? boxLow[0] : 0.0;
  const double ylo_b = boxLow.size() > 1 ? boxLow[1] : 0.0;
  const double zlo_b = boxLow.size() > 2 ? boxLow[2] : 0.0;
  const double xy = box.size() >= 6 ? box[3] : 0.0;
  const double xz = box.size() >= 6 ? box[4] : 0.0;
  const double yz = box.size() >= 6 ? box[5] : 0.0;
  const double xmin = std::min(std::min(0.0, xy), std::min(xz, xy + xz));
  const double xmax = std::max(std::max(0.0, xy), std::max(xz, xy + xz));
  const double ymin = std::min(0.0, yz);
  const double ymax = std::max(0.0, yz);
  H[0][0] = xspan - xmax + xmin;
  H[0][1] = 0.0;
  H[0][2] = 0.0;
  H[1][0] = xy;
  H[1][1] = yspan - ymax + ymin;
  H[1][2] = 0.0;
  H[2][0] = xz;
  H[2][1] = yz;
  H[2][2] = zspan;
  origin[0] = xlo_b - xmin;
  origin[1] = ylo_b - ymin;
  origin[2] = zlo_b;
}

dumpCellLengths()

void nneigh::dumpCellLengths ( const std::vector< double > & box, const std::vector< double > & boxLow, double lengths[3] )

inline

Recovered restricted-triclinic lengths lx, ly, lz (H diagonal).

Definition at line 105 of file neighbours.hpp.

                                               {
  double H[3][3];
  double origin[3];
  dumpBoundsToH(box, boxLow, H, origin);
  lengths[0] = H[0][0];
  lengths[1] = H[1][1];
  lengths[2] = H[2][2];
}

dumpFromFrac()

void nneigh::dumpFromFrac ( const double H[3][3], const double origin[3], const double s[3], double r[3] )

inline

Fractional to cartesian coordinates via dump H.

Definition at line 151 of file neighbours.hpp.

                                                         {
  r[0] = origin[0] + H[0][0] * s[0] + H[1][0] * s[1] + H[2][0] * s[2];
  r[1] = origin[1] + H[1][1] * s[1] + H[2][1] * s[2];
  r[2] = origin[2] + H[2][2] * s[2];
}

dumpToFrac()

void nneigh::dumpToFrac ( const double H[3][3], const double origin[3], double x, double y, double z, double s[3] )

inline

Cartesian to fractional coordinates via dump H.

Definition at line 137 of file neighbours.hpp.

                                                        {
  const double lx = H[0][0];
  const double ly = H[1][1];
  const double lz = H[2][2];
  const double xy = H[1][0];
  const double xz = H[2][0];
  const double yz = H[2][1];
  s[2] = (z - origin[2]) / lz;
  s[1] = (y - origin[1] - yz * s[2]) / ly;
  s[0] = (x - origin[0] - xy * s[1] - xz * s[2]) / lx;
}

dumpVolume() [1/2]

double nneigh::dumpVolume ( const molSys::PointCloud< molSys::Point< double >, double > & yCloud )

inline

Definition at line 169 of file neighbours.hpp.

                                                                 {
  return dumpVolume(yCloud.box, yCloud.boxLow);
}

dumpVolume() [2/2]

double nneigh::dumpVolume ( const std::vector< double > & box, const std::vector< double > & boxLow )

inline

Triclinic dump-cell volume |det(H)| from dumpBoundsToH.

Bound spans Lx*Ly*Lz are not the cell volume when tilt is present.

Definition at line 160 of file neighbours.hpp.

                                                          {
  double H[3][3];
  double origin[3];
  dumpBoundsToH(box, boxLow, H, origin);
  const double vol = H[0][0] * H[1][1] * H[2][2];
  return vol < 0.0 ? -vol : vol;
}

getNewNeighbourListByIndex()

std::vector< std::vector< int > > nneigh::getNewNeighbourListByIndex	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		double	cutoff )

Gets a neighbour list by index, according to a pointCloud given as the input. Assume no slices or other skullduggery

graph()

BondGraph nneigh::SkinNeighborList::graph ( ) const

inlinenodiscard

Definition at line 403 of file neighbours.hpp.

{ return graph_; }

halfNeighList()

std::vector< std::vector< int > > nneigh::halfNeighList	(	double	rcutoff,
		const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI = 1 )

Half neighbour list for one type (vesin cell list, brute-force fallback) You can only use this for neighbour lists with one type

kNearestNeighbourList() [1/2]

std::vector< std::vector< int > > nneigh::kNearestNeighbourList	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	k,
		double	candidateCutoff,
		const std::vector< int > &	types,
		bool	mutual = true )

k-nearest graph on a type set (water oxygens).

Substrate, ions and other species never appear as neighbours. An empty set is no atoms.

kNearestNeighbourList() [2/2]

std::vector< std::vector< int > > nneigh::kNearestNeighbourList	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	k,
		double	candidateCutoff,
		int	typeI,
		bool	mutual = true )

Bonded graph from the k nearest neighbours of each particle rather than a distance cutoff.

The default intersection symmetrization (mutual = true) bonds i and j only when each lists the other among its k nearest; the union alternative bonds on either nomination. In a crystal the first shell is mutual and the two coincide; on disordered packings the mutual graph is sparser, which starves accidental ring structure – measured on the dense null, mutual scores zero false crystal where union reaches 2.5%. Nominations are a periodic linked-cell k-nearest search via linkcell (Allen and Tildesley): vesin is cutoff-only and KD-trees have no minimum-image convention. candidateCutoff is only a cell-size hint. On an undistorted tetrahedral lattice with k = 4 this graph equals the first-shell cutoff graph. Rows are by atom ID with the leading self entry, like neighListO.

kNearestNeighbourPair() [1/2]

std::pair< std::vector< std::vector< int > >, std::vector< std::vector< int > > > nneigh::kNearestNeighbourPair	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	k,
		double	candidateCutoff,
		const std::vector< int > &	types )

kNearestNeighbourPair() [2/2]

std::pair< std::vector< std::vector< int > >, std::vector< std::vector< int > > > nneigh::kNearestNeighbourPair	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	k,
		double	candidateCutoff,
		int	typeI )

Mutual and union k-nearest graphs from one candidate search.

Seeded affiliation needs both; building them separately repeats the cell list.

lastChangedAtoms()

int nneigh::SkinNeighborList::lastChangedAtoms ( ) const

inlinenodiscard

Atoms whose cutoff bond set changed on the last update.

Definition at line 412 of file neighbours.hpp.

{ return changedAtoms_; }

lastRebuilt()

bool nneigh::SkinNeighborList::lastRebuilt ( ) const

inlinenodiscard

Definition at line 410 of file neighbours.hpp.

{ return rebuilt_; }

mutualNearestUnlike()

std::vector< std::pair< int, int > > nneigh::mutualNearestUnlike	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI,
		int	typeJ )

Subset of nearestUnlike where j's nearest typeI is i (mutual).

A contact pair is this mutual edge, not first-shell membership.

nearestUnlike()

std::vector< std::tuple< int, int, double > > nneigh::nearestUnlike	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI,
		int	typeJ )

Nearest unlike image of each typeI particle among typeJ particles.

Returns cloud-index pairs (i, j) and the MIC distance (sqrt of gen::periodicDistSq). On an ion cloud, typeI = 1 (cation vertex) and typeJ = 2 (anion vertex). This is the nearest unlike neighbour, not a coordination number.

neighbourListByIndex()

std::vector< std::vector< int > > nneigh::neighbourListByIndex	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		const std::vector< std::vector< int > > &	nList )

The following function outputs a neighbour list using indices and NOT atom IDs

Converts the neighbour list build with atom IDs into a neighbour list of atom indices, according to the pointCloud

neighList()

std::vector< std::vector< int > > nneigh::neighList	(	double	rcutoff,
		const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI,
		int	typeJ )

All these functions use atom IDs and not indices.

Full neighbour list for pairs of type I and type J (vesin cell list, brute-force fallback). The neighbour list does not differentiate between the types of atoms

neighListO()

std::vector< std::vector< int > > nneigh::neighListO	(	double	rcutoff,
		const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI )

Full neighbour list for one type (threaded cell list from 2048 atoms when OpenMP is compiled, vesin cell list, brute-force fallback) You can only use this for neighbour lists with one type

neighListPair()

std::vector< std::vector< int > > nneigh::neighListPair	(	double	rcutoff,
		const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	typeI,
		int	typeJ )

I-J neighbour list (I==J is like-type and reuses neighListO). Unlike-type pairs use the same dump MIC as neighListO.

shellSeparation()

std::pair< double, double > nneigh::shellSeparation	(	const molSys::PointCloud< molSys::Point< double >, double > &	yCloud,
		int	k,
		int	typeI )

The shell-separation certificate for the exact reduction of the k-nearest graph to the cutoff graph: returns {max_i d_k(i), min_i d_{k+1}(i)} over particles of the type.

When max_i d_k(i) <= rcutoff <= min_i d_{k+1}(i), the two graphs coincide edge for edge and every downstream graph predicate is identical. Brute force, intended for validation.

SkinNeighborList()

nneigh::SkinNeighborList::SkinNeighborList	(	double	cutoff,
		double	skin,
		int	typeI,
		BondGraph	graph = BondGraph::KnnMutual,
		int	k = 4 )

graph selects cutoff vs k-nearest (mutual or union). k is the neighbour count for the knn graphs (default 4).

update()

const std::vector< std::vector< int > > & nneigh::SkinNeighborList::update

(

const molSys::PointCloud< molSys::Point< double >, double > &

yCloud

)

Refresh from a new frame. The returned list is ID-keyed with a leading self entry, the same shape as neighListO.