cage_affiliation.hpp File Reference

Order-free per-ring cage classification with an exact incremental update. More...

#include <memory>
#include <vector>

Go to the source code of this file.

Classes
struct	ring::CageAffiliation
	Per-ring affiliation flags, indexed like the input ring vector. More...
class	ring::AffiliationUpdater
	Exact incremental affiliation across frames. More...
struct	ring::SeededAtomLabels
	Per-atom cage flags from seeded (hysteresis) affiliation. More...

Namespaces
namespace	ring
	Topological network criteria functions.

Functions
CageAffiliation	ring::cageAffiliation (const std::vector< std::vector< int > > &rings, const std::vector< std::vector< int > > &nList)
SeededAtomLabels	ring::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)
	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.

Detailed Description

Order-free per-ring cage classification with an exact incremental update.

The greedy cage assembly in findHC/findDDC claims rings as it accepts cages, so which rings are tested depends on visiting order. The affiliation predicates here are claim-free restatements of the same geometric conditions, evaluated for every ring independently:

• A ring is HC-affiliated when it is a basal ring of some ordered pair passing the basal conditions, or a prismatic ring of such a pair.
• A ring is DDC-affiliated when it passes the equatorial conditions (excluding HC-affiliated rings from candidacy, as the published scheme does), or is one of the six peripheral rings of a ring that passes.

Locality theorem. Let two six-membered rings be adjacent when one contains an atom within one bond-hop of an atom of the other (a symmetric relation, written A(r) for the set adjacent to r). Every quantity the predicates read is confined to a bounded adjacency neighbourhood:

1. An ordered basal pair P(i,j) requires an atom of j to neighbour the first or second atom of i, so j is in A(i); evaluating P reads only rings i, j and the neighbour rows of their atoms.
2. A prismatic ring k of a pair (i,j) shares a triplet with i and three further atoms with j, so both i and j lie in A(k).
3. The equatorial conditions for ring i read only rings sharing an atom with i – a subset of A(i) – plus the HC affiliation of i itself.
4. A peripheral ring r of an equator i shares an atom with i, so i lies in A(r).

Hence HC affiliation of r is a function of the rings in A(r) and the neighbour rows of their atoms, and DDC affiliation of r is a function of the rings in A(A(r)) and their rows. Between two frames, affiliation can therefore change only for rings whose second adjacency neighbourhood touches an added ring, a removed ring, or an atom whose neighbour row changed. The incremental updater recomputes exactly that closure and carries every other ring's stored answer, so its output equals a full recomputation by construction.

Definition in file cage_affiliation.hpp.