namespace ring¶
Overview¶
Topological network criteria functions. More…
namespace ring {
// structs
struct CageAffiliation;
struct EquatorChoice;
struct PackingCertificate;
struct RingSearchIndex;
struct SeededAtomLabels;
struct StackingPlanes;
// classes
class AffiliationUpdater;
class NeighBond;
// global functions
StackingPlanes stackingPlanes(const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList);
CageAffiliation cageAffiliation(const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList);
SeededAtomLabels seededCageAffiliation(const std::vector<std::vector<int>>& strictRings, const std::vector<std::vector<int>>& strictNList, const std::vector<std::vector<int>>& permissiveRings, const std::vector<std::vector<int>>& permissiveNList, bool ringAdjacentCompletion = false);
SeededAtomLabels seededCageAffiliation(const std::vector<std::vector<int>>& strictRings, const CageAffiliation& strictAffiliation, const std::vector<std::vector<int>>& permissiveRings, const CageAffiliation& permissiveAffiliation, const std::vector<std::vector<int>>& permissiveNList, bool ringAdjacentCompletion = false);
SeededAtomLabels ringAdjacentCompletion(const SeededAtomLabels& labels, const std::vector<std::vector<int>>& permissiveRings);
int bulkPolygonRingAnalysis(std::string path, const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList, molSys::PointCloud<molSys::Point<double>, double>& yCloud, int maxDepth, int firstFrame);
int topoBulkAnalysis(std::string path, const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList, molSys::PointCloud<molSys::Point<double>, double>& yCloud, int firstFrame, bool onlyTetrahedral = true);
RingSearchIndex buildRingSearchIndex(const std::vector<std::vector<int>>& rings, int numAtoms);
RingSearchIndex buildRingSearchIndex(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud);
std::vector<int> positionRank(const molSys::PointCloud<molSys::Point<double>, double>& yCloud);
std::vector<std::vector<int>> contractibleRings(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud);
std::vector<std::vector<int>> cageRings(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud, double cutoff);
std::vector<int> findDDC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<int>& listHC, std::vector<cage::Cage>& cageList);
std::vector<int> maximumEquators(const std::vector<EquatorChoice>& periph, const std::vector<int>& order, PackingCertificate* certificate);
std::vector<int> findDDC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<int>& listHC, std::vector<cage::Cage>& cageList, const RingSearchIndex& index, PackingCertificate* certificate = nullptr);
std::vector<int> findMixedRings(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, std::vector<int>& listDDC, std::vector<int>& listHC);
std::vector<int> findHC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<std::vector<int>>& nList, std::vector<cage::Cage>& cageList);
std::vector<int> findHC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<std::vector<int>>& nList, std::vector<cage::Cage>& cageList, const RingSearchIndex& index);
bool conditionOneDDC(const std::vector<std::vector<int>>& rings, std::vector<int>& peripheralRings, int iring);
bool conditionOneDDC(const std::vector<std::vector<int>>& rings, std::vector<int>& peripheralRings, int iring, const RingSearchIndex& index);
bool equatorialConditions(const std::vector<std::vector<int>>& rings, int iring, const RingSearchIndex& index, std::vector<int>* peripheralUnion, std::vector<int>* chosen = nullptr, const std::vector<int>* rank = nullptr, EquatorChoice* raw = nullptr);
bool basalConditions(const std::vector<std::vector<int>>& nList, const std::vector<int>& basal1, const std::vector<int>& basal2);
bool basalConditions(const NeighBond& bonds, const std::vector<int>& basal1, const std::vector<int>& basal2);
bool basalNeighbours(const std::vector<std::vector<int>>& nList, std::vector<int>& triplet, int atomOne, int atomTwo);
bool notNeighboursOfRing(const std::vector<std::vector<int>>& nList, std::vector<int>& triplet, const std::vector<int>& ring);
int findPrismatic(const std::vector<std::vector<int>>& rings, std::vector<int>& listHC, std::vector<strucType>& ringType, int iring, int jring, std::vector<int>& prismaticRings);
int findPrismatic(const std::vector<std::vector<int>>& rings, std::vector<int>& listHC, std::vector<strucType>& ringType, int iring, int jring, std::vector<int>& prismaticRings, const RingSearchIndex& index);
int getAtomTypesTopoBulk(const std::vector<std::vector<int>>& rings, const std::vector<ring::strucType>& ringType, std::vector<cage::iceType>& atomTypes);
int getStrucNumbers(const std::vector<ring::strucType>& ringType, const std::vector<cage::Cage>& cageList, int& numHC, int& numDDC, int& mixedRings, int& prismaticRings, int& basalRings);
} // namespace ring
Detailed Documentation¶
Topological network criteria functions.
This namespace contains functions for the topological network criteria for bulk and confined systems both.
Although the namespace is shared by bulk and confined topological network criteria, the functions are split into files specific to each set of criteria.
All the topological network criteria are based on the identification of primitive rings (using the Franzblau algorithm for primitive rings), following which specific rules for combinations of primitive rings are used to identify quasi-one-dimensional, quasi-two-dimensional and bulk ices.
Changelog¶
Amrita Goswami [amrita16thaug646@gmail.com]; date modified: Nov 13, 2019
Rohit Goswami [rog32@hi.is]; date modified: Mar 20, 2021
Global Functions¶
CageAffiliation cageAffiliation(const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList)
Batch computation of the affiliation predicates for six-membered rings. nList is by index with the leading self entry, as neighbourListByIndex produces.
SeededAtomLabels seededCageAffiliation(const std::vector<std::vector<int>>& strictRings, const std::vector<std::vector<int>>& strictNList, const std::vector<std::vector<int>>& permissiveRings, const std::vector<std::vector<int>>& permissiveNList, bool ringAdjacentCompletion = false)
Seeded affiliation over two graphs on the same atoms: the strict graph (typically the mutual k-nearest bonds) supplies seeds, the permissive supergraph (typically the union bonds) supplies completions, and a permissively affiliated atom is accepted only when its bonded component of affiliated atoms contains a seed.
Specificity on structureless input is structural rather than statistical: when the strict pass affiliates nothing, nothing is accepted regardless of what the permissive graph builds. Where both graphs label an atom, the strict labels win.
The fifth argument is the ring-adjacent completion flag. The default is false. When the flag is true the accepted labels pass through ringAdjacentCompletion() on the permissive six-rings. HC and DDC complete on separate flag vectors. seams cages complete sets the flag. tests/walk_compare leaves the flag false.
Parameters:
strictRings |
Six-membered rings of the strict graph. |
strictNList |
Strict graph, by index with leading self entries. |
permissiveRings |
Six-membered rings of the permissive graph. |
permissiveNList |
Permissive graph, same conventions. |
ringAdjacentCompletion |
When true, call ringAdjacentCompletion() on the accepted labels. Default false. |
SeededAtomLabels seededCageAffiliation(const std::vector<std::vector<int>>& strictRings, const CageAffiliation& strictAffiliation, const std::vector<std::vector<int>>& permissiveRings, const CageAffiliation& permissiveAffiliation, const std::vector<std::vector<int>>& permissiveNList, bool ringAdjacentCompletion = false)
The same labels from the affiliation of each graph’s six-rings, computed by the caller.
A frame walk passes AffiliationUpdater results here, so both graphs carry their per-ring answers across frames.
Parameters:
strictRings |
Six-membered rings of the strict graph. |
strictAffiliation |
cageAffiliation of strictRings. |
permissiveRings |
Six-membered rings of the permissive graph. |
permissiveAffiliation |
cageAffiliation of permissiveRings. |
permissiveNList |
Permissive graph, by index with leading self entries. |
ringAdjacentCompletion |
As in the overload above. |
SeededAtomLabels ringAdjacentCompletion(const SeededAtomLabels& labels, const std::vector<std::vector<int>>& permissiveRings)
Ring completion of seeded labels.
A permissive six-ring whose vertices all carry a cage label but one is a cage ring with a vacancy. The last vertex takes that label. The walk repeats until a fixed point. HC and DDC complete on separate flag vectors.
A liquid ring that only touches a nucleus has at most a few labelled vertices, so the all-but-one rule cannot walk into the liquid. An empty seed stays empty: no ring then has five labelled vertices.
The result is the least fixed point above the seed. Visiting order does not change the labelled set. lean/DseamsProofs/Completion.lean states that claim. Catch2 covers the C++ identity on a crystal, the refill of a single vacancy, and the structural zero.
Parameters:
labels |
Seeded per-atom flags. |
permissiveRings |
Six-membered rings of the permissive graph. |
int bulkPolygonRingAnalysis(std::string path, const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList, molSys::PointCloud<molSys::Point<double>, double>& yCloud, int maxDepth, int firstFrame)
Find out rings in the bulk, looping through all ring sizes upto the maxDepth The input ringsAllSizes array has rings of every size.
int topoBulkAnalysis(std::string path, const std::vector<std::vector<int>>& rings, const std::vector<std::vector<int>>& nList, molSys::PointCloud<molSys::Point<double>, double>& yCloud, int firstFrame, bool onlyTetrahedral = true)
Find out which rings are DDCs or HCs, which are comprised of 6-membered primitive rings. Start with a neighbour list (by index) and a vector of vectors of rings (also by index). TODO: try ‘square’ ice and ice0
RingSearchIndex buildRingSearchIndex(const std::vector<std::vector<int>>& rings, int numAtoms)
Builds the inverted atom-to-rings index used by the cage searches.
RingSearchIndex buildRingSearchIndex(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud)
As buildRingSearchIndex, ranking the atoms by position (ring::positionRank).
std::vector<int> positionRank(const molSys::PointCloud<molSys::Point<double>, double>& yCloud)
Rank of every atom of yCloud when the atoms are sorted by position wrapped into the box, compared by x, then y, then z. Throws std::invalid_argument when two atoms share a wrapped position
std::vector<std::vector<int>> contractibleRings(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud)
The rings of rings whose minimum-image bonds have integer lattice images summing to zero. Any other ring winds through the periodic cell and bounds no face. A cell narrower than a ring’s span has such rings. Without a box every ring is kept
std::vector<std::vector<int>> cageRings(const std::vector<std::vector<int>>& rings, const molSys::PointCloud<molSys::Point<double>, double>& yCloud, double cutoff)
Faces for a cage search: contractibleRings, after refusing a cutoff that can contain more than one periodic image of a pair. The narrowest face separation must be longer than twice cutoff. A cloud without a box keeps every ring. Throws std::invalid_argument when the cell is too thin for cutoff
std::vector<int> findDDC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<int>& listHC, std::vector<cage::Cage>& cageList)
Find out which hexagonal rings are DDC (Double Diamond Cages) rings. Returns a vector containing all the ring IDs which are DDC rings
std::vector<int> maximumEquators(const std::vector<EquatorChoice>& periph, const std::vector<int>& order, PackingCertificate* certificate)
Maximum set of mutually non-conflicting equatorial rings. periph [i].n is 0 when ring i is not a candidate. The returned ids are a maximum packing; certificate is filled when non-null.
std::vector<int> findDDC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<int>& listHC, std::vector<cage::Cage>& cageList, const RingSearchIndex& index, PackingCertificate* certificate = nullptr)
As findDDC, reusing an index the caller has already built. When certificate is given it receives the matching or search bound.
std::vector<int> findMixedRings(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, std::vector<int>& listDDC, std::vector<int>& listHC)
Find out which hexagonal rings are both DDCs (Double Diamond Cages) and HCs (Hexagonal Cages). Returns a vector containing all the ring IDs which are of this type
std::vector<int> findHC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<std::vector<int>>& nList, std::vector<cage::Cage>& cageList)
Find out which hexagonal rings are HC rings. Returns a vector containing all the ring IDs which are HC rings
std::vector<int> findHC(const std::vector<std::vector<int>>& rings, std::vector<strucType>& ringType, const std::vector<std::vector<int>>& nList, std::vector<cage::Cage>& cageList, const RingSearchIndex& index)
As findHC, reusing an index the caller has already built.
bool conditionOneDDC(const std::vector<std::vector<int>>& rings, std::vector<int>& peripheralRings, int iring)
First condition for the DDC: There must be at least 3 other rings in which each element of the equatorial ring is present
bool conditionOneDDC(const std::vector<std::vector<int>>& rings, std::vector<int>& peripheralRings, int iring, const RingSearchIndex& index)
As conditionOneDDC, reusing an index the caller has already built.
bool equatorialConditions(const std::vector<std::vector<int>>& rings, int iring, const RingSearchIndex& index, std::vector<int>* peripheralUnion, std::vector<int>* chosen = nullptr, const std::vector<int>* rank = nullptr, EquatorChoice* raw = nullptr)
Equatorial test of a DDC. Holds when every atom of ring iring lies in at least three other rings and, for some starting atom and direction of iring, six distinct rings P_k through its consecutive triplets satisfy the even/odd common-atom and alternate-pair conditions. When peripheralUnion is given it receives every ring that serves as a P_k in some valid assignment, sorted. When chosen and rank are given, chosen receives the six rings of the valid assignment whose ranks, sorted, are lexicographically least, in ascending rank.
bool basalConditions(const std::vector<std::vector<int>>& nList, const std::vector<int>& basal1, const std::vector<int>& basal2)
Tests whether two rings are basal rings (true) or not (false): some alternate triplet of basal1, starting at its first or second atom, is bonded one-to-one to an alternate triplet of basal2, and no atom of the other triplet of basal2 is bonded to basal1
bool basalConditions(const NeighBond& bonds, const std::vector<int>& basal1, const std::vector<int>& basal2)
As basalConditions, answering bonds from a prebuilt NeighBond.
bool basalNeighbours(const std::vector<std::vector<int>>& nList, std::vector<int>& triplet, int atomOne, int atomTwo)
Tests whether the last two elements of a triplet are neighbours of two atom IDs passed in
bool notNeighboursOfRing(const std::vector<std::vector<int>>& nList, std::vector<int>& triplet, const std::vector<int>& ring)
Tests to check that elements of a triplet are not neighbours of a ring (vector) passed
int findPrismatic(const std::vector<std::vector<int>>& rings, std::vector<int>& listHC, std::vector<strucType>& ringType, int iring, int jring, std::vector<int>& prismaticRings)
Finds the prismatic rings from basal rings iring and jring.
int findPrismatic(const std::vector<std::vector<int>>& rings, std::vector<int>& listHC, std::vector<strucType>& ringType, int iring, int jring, std::vector<int>& prismaticRings, const RingSearchIndex& index)
As findPrismatic, drawing candidate rings from the inverted index.
int getAtomTypesTopoBulk(const std::vector<std::vector<int>>& rings, const std::vector<ring::strucType>& ringType, std::vector<cage::iceType>& atomTypes)
Assigns a type of enum class iceType, to every atom, using information from ringType, which has the information of every ring
int getStrucNumbers(const std::vector<ring::strucType>& ringType, const std::vector<cage::Cage>& cageList, int& numHC, int& numDDC, int& mixedRings, int& prismaticRings, int& basalRings)
Determines the number of HCs, DDCs, Mixed rings, prismatic and basal rings.