stormm::energy::LocalExclusionMask Class Reference

The local exclusion mask is an generalized form of the ForwardExclusionMask, listing all exclusions in various ranges of an atom followed by additional masks. Like the ForwardExclusionMask, all atoms are assigned an index, but it points to a primary array of profiles, not quite like the primary masks of the ForwardExclusionList. There are a finite number of profiles, each containing a three-bit code to indicate how it is to be used. More...

#include <local_exclusionmask.h>

Public Member Functions
int	getAtomCount () const
	Get the number of atoms in the system.
int	getMode (int atom_index, int system_index=0) const
	Get the profile mode used by a particular atom as a positive integer.
size_t	getSecondaryMaskCount () const
	Get the number of secondary masks.
ullint	getProfile (int atom_index, int system_index=0) const
	Get the exclusion profile for an atom.
const Hybrid< uint2 >	getSecondaryMaskView (int atom_index, int system_index=0)
	Get a POINTER-kind Hybrid object for viewing all secondary masks associated with an atom. Each presents the exclusions for a cluster of atoms following some reference atom. Descriptions of parameters follow from getProfile() above.
const AtomGraph *	getTopologyPointer () const
	Get a pointer to the topology associated with this object.
const AtomGraphSynthesis *	getTopologySynthesisPointer () const
	Get a pointer to the topology synthesis associated with this object.
LocalExclusionMaskReader	data (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the abstract for the object.
	LocalExclusionMask (const AtomGraph *ag_in=nullptr, NonbondedTheme theme_in=NonbondedTheme::ALL)
	Constructor requires a topology, and creates a blank object if nullptr is supplied.
	LocalExclusionMask (const AtomGraph &ag_in, NonbondedTheme theme_in=NonbondedTheme::ALL)
	LocalExclusionMask (const AtomGraphSynthesis *poly_ag_in, NonbondedTheme theme_in=NonbondedTheme::ALL)
	LocalExclusionMask (const AtomGraphSynthesis &poly_ag_in, NonbondedTheme theme_in=NonbondedTheme::ALL)
	LocalExclusionMask (const LocalExclusionMask &original)=default
	The default copy and move constructors as well as the copy and move assignment operator will suffice for this object, which has no POINTER-kind Hybrid objects among its members.
	LocalExclusionMask (LocalExclusionMask &&original)=default
LocalExclusionMask &	operator= (const LocalExclusionMask &other)=default
LocalExclusionMask &	operator= (LocalExclusionMask &&other)=default
int	getProfileCount () const
	Get the number of unique profiles.
int	getProfileCount (int mode_index) const
std::vector< uint2 >	getSecondaryMasks (int atom_index, int system_index=0) const
	Get a copy of all secondary masks associated with an atom. Descriptions of parameters follow from getProfile() above.
bool	testExclusion (int atom_i, int atom_j) const
	Return TRUE if two atoms in the same molecular system share an excluded interaction and FALSE if they interact according to the standard potential.
bool	testExclusion (int atom_i, int atom_j, int system_index) const
void	setTopology (const AtomGraph *ag_in)
	Set (or reset) the topology for the object. All exclusion masks and profiles will be rebuilt if the topology changes.
void	setTopology (const AtomGraph &ag_in)
void	setTopology (const AtomGraphSynthesis *poly_ag_in)
void	setTopology (const AtomGraphSynthesis &poly_ag_in)

Detailed Description

The local exclusion mask is an generalized form of the ForwardExclusionMask, listing all exclusions in various ranges of an atom followed by additional masks. Like the ForwardExclusionMask, all atoms are assigned an index, but it points to a primary array of profiles, not quite like the primary masks of the ForwardExclusionList. There are a finite number of profiles, each containing a three-bit code to indicate how it is to be used.

When accessed, the profile is a 64-bit unsigned long long int, with several modes of operation indicated by its high three bits. For the purposes of the following discussion, we will take atom (i) of the topology (or the atom with absolute index (i) out of a synthesis of topologies) to access profile (j) and possibly secondary masks (k1) through (kN) when determining the existence of an excluded interaction with some other atom (m).

The first mode is the simplest, and covers nearly all situations that will be found in a typical MD simulation. The low 61 bits describe a mask such that the 31st bit, always 0, is the exclusion of the atom itself. Bits 1-30 indicate exclusions for atoms 30, 29, ..., 2, 1 topological position prior to the atom of interest (i). Bits 32-61 indicate exclusions for atoms 1, 2, ..., 29, 30 positions after atom (i). After retrieving the profile, the existence of an exclusion between (i) and some other atom (m) is computed by:

int del_im = (m) - (i); const bool excluded = (abs(del_im) < 31 && (((profile of i) >> (30 + del_im)) & 0x1));

Mode A: 000 ---------------------------— 1 ---------------------------—

The mode of an atom with no exclusions, whether a monatomic ion or a water oxygen in the context of a van-der Waals pairlist, is also mode A: every atom excludes itself.

In the second mode, when the 62nd bit is set to one, the 31 bits are used in much the same way as the low 61 bits of the profile in Mode A. However, the next higher 10 bits indicate a patch of exclusions offset by -(NNNNN + 15) from atom (i) and the next higher 10 bits a similar patch of exclusions offset +(PPPPP + 15) atom (i). The code for evaluating exclusions is somewhat more involved but these types of masks will be rare.

Mode B: 001 PPPPP NNNNN -------— -------— ------------— 1 ------------—

In the diagram above, NNNNN and PPPPP are unsigned integers extracted from bits 55-57 and 58-60, respectively, and one bit is left unused. This more complex footprint, which can accommodate atoms with exclusions up to 56 topological indices away from the home atom, can be easily evaluated in most modes, if the difference between (i) and (m) is greater than 56.

In the third mode of operation, the 63rd bit of the profile is set to 1. The low 31 bits of the profile continue to function as before, but the next 14 represent a mask that is shifted relative to the original atom by -32768 to +32767 indices, as indicated by the high group of 16 bits just below the three mode bits (read the S bits below as an unsigned integer in the range [0, 65536) and subtract 32768). This is effective for the largest known proteins with disulfide bridges connecting one end of the chain to another.

Mode C: 010 SSSSSSSSSSSSSSSS -----------— ------------— 1 ------------—

In the fourth mode of operation, the 64th bit of the profile is set to 1. In this mode, the low 31 bits continue to function as they did in modes A and B, but the next 23 bits indicate an lower bound index into a secondary array, much as in the ForwardExclusionMask mode, where additional groups of exclusions are to be found. The highest 7 bits just behind the mode bits are taken as an unsigned integer indicating an upper bound, the number of consecutive indices to access from within the secondary array. The secondary array is a collection of unsigned int pairs, the "x" member being another local exclusion mask and the "y" member being a shift relative to the original atom. This mode would only be activated when there are extreme numbers of far-flung and non-contiguous exclusions for a single atom.

Mode D: 011 KKKKKKK IIIIIIIIIIIIIIIIIIIIIIII ------------— 1 ------------—

In the sixth mode of operation, the 62nd and 64th bits of the profile are set to 1. The profile itself no longer provides local exclusion masks. Instead, the low 40 bits operate as the index into the array of secondary masks while the higher 21 bits (those just behind the mode bits) provide the upper bound on the number of masks from the secondary array to access. Any system operating in this mode would have to contain exclusions of extreme complexity and the amount of available computer memory would become an issue before the format is broken. It could also be inefficient if taken to the extreme, where every atom has a large and far-flung but unique exclusions profile. Still, many thousands of atoms could be accommodated in this manner.

Mode E: 100 KKKKKKKKKKKKKKKKKKKKKK IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII

The final mode is applied when only a few atoms' exclusions (up to 32) are so astoundingly complex that it is easier to simply enumerate them for all atoms of the system (or group of systems) and perform a non-caching read of the pre-tabulated lists. This is not expected to occur in any ordinary MD simulation. The five lowest bits of the profile indicate the index of the pre-tabulated list to take in this mode.

Mode F: 101 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX IIIII

One final mode may be useful, but the list is quite thorough.

Member Function Documentation

data()

LocalExclusionMaskReader stormm::energy::LocalExclusionMask::data

(

HybridTargetLevel

tier = HybridTargetLevel::HOST

)

const

Get the abstract for the object.

Parameters

tier	Indicate whether to target pointers to memory on the CPU host or GPU device

getMode()

int stormm::energy::LocalExclusionMask::getMode	(	int	atom_index,
		int	system_index = 0 ) const

Get the profile mode used by a particular atom as a positive integer.

Parameters

atom_index	Index of the atom of interest
system_index	Index of the system of interest (applicable for topology syntheses)

getProfile()

ullint stormm::energy::LocalExclusionMask::getProfile	(	int	atom_index,
		int	system_index = 0 ) const

Get the exclusion profile for an atom.

Parameters

atom_index	Topological index of the atom of interest
system_index	Index of the system of interest (applicable for topology syntheses)

getProfileCount()

int stormm::energy::LocalExclusionMask::getProfileCount

(

)

const

Get the number of unique profiles.

Overloaded:

• Get the total number of profiles
• Get the number of profiles using a particular mode

Parameters

mode_index

The index number of the mode of operation for the profile

setTopology()

void stormm::energy::LocalExclusionMask::setTopology

(

const AtomGraph *

ag_in

)

Set (or reset) the topology for the object. All exclusion masks and profiles will be rebuilt if the topology changes.

Overloaded:

• Provide a single topology by pointer or const reference
• Provide a synthesis of topologies by pointer or const reference

Parameters

ag_in

The new topology to set

testExclusion()

bool stormm::energy::LocalExclusionMask::testExclusion	(	int	atom_i,
		int	atom_j ) const

Return TRUE if two atoms in the same molecular system share an excluded interaction and FALSE if they interact according to the standard potential.

Overloaded:

• Provide two atom indices to test the exclusion of two atoms in a single topology
• Provide the system index in order to test the exclusion of two atoms in one system out of a synthesis

Parameters

atom_i	Index of the first atom within the topology of interest
atom_j	Index of the second atom within the topology of interest
system_index	The system of interest (valid only for objects built on a topology synthesis)

---

The documentation for this class was generated from the following files:

• src/Potential/local_exclusionmask.h
• src/Potential/local_exclusionmask.cpp