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)
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::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< 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 326 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 356 of file neighbours.hpp.

                                                               {
    return nList_;
  }

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 128 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 114 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 71 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 102 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 148 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 134 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 166 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 157 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 346 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()

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()

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 355 of file neighbours.hpp.

{ return changedAtoms_; }

lastRebuilt()

bool nneigh::SkinNeighborList::lastRebuilt ( ) const

inlinenodiscard

Definition at line 353 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 (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.