Detailed Description

A Verlet neighbor list.

A PairList (or Verlet list) is a list of neighboring pairs of Atoms that are separated by a distance less than a specified cutoff. The cutoff for the Verlet list is the sum of a potential cutoff, which is passed as a parameter to initialize(), and a "skin", which is read by readParameters().

After a PairList is constructed, the initialize() method must be called to allocate memory for both the data structures required to store the PairList and for a private CellList object that is used to construct the PairList.

To build or rebuild a PairList, after it has been allocated, one must invoke clear() to clear the private CellList, call addAtom(Atom&) once for every atom in the System, within a loop over atoms, and then call build() to actually construct the PairList. The addAtom() method adds an Atom to an internal CellList, and then build() uses the CellList to build a list of pairs. Atomic positions must not be changed during this process.

A PairIterator object must be used to iterate over all of the pairs in a completed PairList (see documentation for PairIterator for usage).

A completed PairList is guaranteed to remain valid as long as no Atom in the system has moved more than a distance skin/2 from its position when the PairList was last built. The isCurrent() function determines if this criterion is satisfied, by comparing current atomic positions to positions that were stored when the PairList was last built. In an MD simulation, isCurrent() should be called after every time step, and the PairList should be rebuilt if its return value is false.

Definition at line 61 of file mcMd/neighbor/PairList.h.

#include <PairList.h>

Inheritance diagram for McMd::PairList:

Public Member Functions
	PairList ()
	Default constructor. More...

virtual	~PairList ()
	Destructor. More...

void	readParameters (std::istream &in)
	Read atomCapacity and pairCapacity (maximum numbers of atoms and pairs). More...

virtual void	loadParameters (Serializable::IArchive &ar)
	Load internal state from an archive. More...

virtual void	save (Serializable::OArchive &ar)
	Save internal state to an archive. More...

Mutators
void	initialize (int atomIdEnd, double potentialCutoff)
	Allocate memory and initialize. More...

void	setup (const Boundary &boundary)
	Setup an empty grid of cells for the internal cell list. More...

void	clear ()
	Clear the PairList and CellList. More...

void	addAtom (Atom &atom)
	Add an Atom to the CellList. More...

void	build (const Boundary &boundary)
	Use a complete CellList to build a new PairList. More...

void	begin (PairIterator &iterator) const
	Initialize a PairIterator. More...

Accessors (miscellaneous)
int	nAtom () const
	Get the number of pairs currently in the PairList. More...

int	nPair () const
	Get the number of pairs currently in the PairList. More...

bool	isInitialized () const
	Has the initialize function been called? More...

bool	isCurrent (const Boundary &boundary) const
	Returns true if PairList is current, false otherwise. More...

bool	isValid () const
	Return true if valid, or throw Exception. More...

Statistics
int	maxNAtom () const
	Get the maximum number of atoms encountered thus far. More...

int	maxNPair () const
	Get the maximum number of pairs encountered thus far. More...

int	buildCounter () const
	Return number of times the PairList has been built thus far. More...

void	clearStatistics ()
	Clear statistical accumulators (maxNAtom, maxNPair, buildCounter). More...

Public Member Functions inherited from Util::ParamComposite
	ParamComposite ()
	Constructor. More...

	ParamComposite (const ParamComposite &other)
	Copy constructor. More...

	ParamComposite (int capacity)
	Constructor. More...

virtual	~ParamComposite ()
	Virtual destructor. More...

void	resetParam ()
	Resets ParamComposite to its empty state. More...

virtual void	readParam (std::istream &in)
	Read the parameter file block. More...

virtual void	readParamOptional (std::istream &in)
	Read optional parameter file block. More...

virtual void	writeParam (std::ostream &out)
	Write all parameters to an output stream. More...

virtual void	load (Serializable::IArchive &ar)
	Load all parameters from an input archive. More...

virtual void	loadOptional (Serializable::IArchive &ar)
	Load an optional ParamComposite. More...

void	saveOptional (Serializable::OArchive &ar)
	Saves isActive flag, and then calls save() iff isActive is true. More...

void	readParamComposite (std::istream &in, ParamComposite &child, bool next=true)
	Add and read a required child ParamComposite. More...

void	readParamCompositeOptional (std::istream &in, ParamComposite &child, bool next=true)
	Add and attempt to read an optional child ParamComposite. More...

template<typename Type >
ScalarParam< Type > &	read (std::istream &in, const char *label, Type &value)
	Add and read a new required ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	readOptional (std::istream &in, const char *label, Type &value)
	Add and read a new optional ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	readCArray (std::istream &in, const char label, Type value, int n)
	Add and read a required C array parameter. More...

template<typename Type >
CArrayParam< Type > &	readOptionalCArray (std::istream &in, const char label, Type value, int n)
	Add and read an optional C array parameter. More...

template<typename Type >
DArrayParam< Type > &	readDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read a required DArray < Type > parameter. More...

template<typename Type >
DArrayParam< Type > &	readOptionalDArray (std::istream &in, const char *label, DArray< Type > &array, int n)
	Add and read an optional DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read a required FArray < Type, N > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	readOptionalFArray (std::istream &in, const char *label, FArray< Type, N > &array)
	Add and read an optional FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	readCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read a required CArray2DParam < Type > 2D C-array. More...

template<typename Type >
CArray2DParam< Type > &	readOptionalCArray2D (std::istream &in, const char label, Type value, int m, int n, int np)
	Add and read an optional CArray2DParam < Type > 2D C-array parameter. More...

template<typename Type >
DMatrixParam< Type > &	readDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read a required DMatrix < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	readOptionalDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and read an optional DMatrix < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	readDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read a required symmetrix DMatrix. More...

template<typename Type >
DSymmMatrixParam< Type > &	readOptionalDSymmMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int n)
	Add and read an optional DMatrix matrix parameter. More...

Begin &	readBegin (std::istream &in, const char *label, bool isRequired=true)
	Add and read a class label and opening bracket. More...

End &	readEnd (std::istream &in)
	Add and read the closing bracket. More...

Blank &	readBlank (std::istream &in)
	Add and read a new Blank object, representing a blank line. More...

void	loadParamComposite (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load a required child ParamComposite. More...

void	loadParamCompositeOptional (Serializable::IArchive &ar, ParamComposite &child, bool next=true)
	Add and load an optional child ParamComposite if isActive. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value, bool isRequired)
	Add and load a new ScalarParam < Type > object. More...

template<typename Type >
ScalarParam< Type > &	loadParameter (Serializable::IArchive &ar, const char *label, Type &value)
	Add and load new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n, bool isRequired)
	Add a C array parameter and load its elements. More...

template<typename Type >
CArrayParam< Type > &	loadCArray (Serializable::IArchive &ar, const char label, Type value, int n)
	Add and load a required CArrayParam< Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n, bool isRequired)
	Add an load a DArray < Type > array parameter. More...

template<typename Type >
DArrayParam< Type > &	loadDArray (Serializable::IArchive &ar, const char *label, DArray< Type > &array, int n)
	Add and load a required DArray< Type > array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array, bool isRequired)
	Add and load an FArray < Type, N > fixed-size array parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	loadFArray (Serializable::IArchive &ar, const char *label, FArray< Type, N > &array)
	Add and load a required FArray < Type > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np, bool isRequired)
	Add and load a CArray2DParam < Type > C 2D array parameter. More...

template<typename Type >
CArray2DParam< Type > &	loadCArray2D (Serializable::IArchive &ar, const char label, Type value, int m, int n, int np)
	Add and load a required < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired)
	Add and load a DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DMatrixParam< Type > &	loadDMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int m, int n)
	Add and load a required DMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n, bool isRequired)
	Add and load a symmetric DSymmMatrixParam < Type > matrix parameter. More...

template<typename Type >
DSymmMatrixParam< Type > &	loadDSymmMatrix (Serializable::IArchive &ar, const char *label, DMatrix< Type > &matrix, int n)
	Add and load a required DSymmMatrixParam < Type > matrix parameter. More...

void	addParamComposite (ParamComposite &child, bool next=true)
	Add a child ParamComposite object to the format array. More...

Begin &	addBegin (const char *label)
	Add a Begin object representing a class name and bracket. More...

End &	addEnd ()
	Add a closing bracket. More...

Blank &	addBlank ()
	Create and add a new Blank object, representing a blank line. More...

std::string	className () const
	Get class name string. More...

bool	isRequired () const
	Is this ParamComposite required in the input file? More...

bool	isActive () const
	Is this parameter active? More...

Public Member Functions inherited from Util::ParamComponent
virtual	~ParamComponent ()
	Destructor. More...

void	setIndent (const ParamComponent &parent, bool next=true)
	Set indent level. More...

std::string	indent () const
	Return indent string for this object (string of spaces). More...

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)
	Serialize this ParamComponent as a string. More...

Public Member Functions inherited from Util::Serializable
virtual	~Serializable ()
	Destructor. More...

Public Member Functions inherited from Util::MpiFileIo
	MpiFileIo ()
	Constructor. More...

	MpiFileIo (const MpiFileIo &other)
	Copy constructor. More...

bool	isIoProcessor () const
	Can this processor do file I/O ? More...

void	setIoCommunicator (MPI::Intracomm &communicator)
	Set the communicator. More...

void	clearCommunicator ()
	Clear (nullify) the communicator. More...

bool	hasIoCommunicator () const
	Does this object have an associated MPI communicator? More...

MPI::Intracomm &	ioCommunicator () const
	Get the MPI communicator by reference. More...

Additional Inherited Members
Public Types inherited from Util::Serializable
typedef BinaryFileOArchive	OArchive
	Type of output archive used by save method. More...

typedef BinaryFileIArchive	IArchive
	Type of input archive used by load method. More...

Static Public Member Functions inherited from Util::ParamComponent
static void	initStatic ()
	Initialize static echo member to false. More...

static void	setEcho (bool echo=true)
	Enable or disable echoing for all subclasses of ParamComponent. More...

static bool	echo ()
	Get echo parameter. More...

Protected Member Functions inherited from Util::ParamComposite
void	setClassName (const char *className)
	Set class name string. More...

void	setIsRequired (bool isRequired)
	Set or unset the isActive flag. More...

void	setIsActive (bool isActive)
	Set or unset the isActive flag. More...

void	setParent (ParamComponent &param, bool next=true)
	Set this to the parent of a child component. More...

void	addComponent (ParamComponent &param, bool isLeaf=true)
	Add a new ParamComponent object to the format array. More...

template<typename Type >
ScalarParam< Type > &	add (std::istream &in, const char *label, Type &value, bool isRequired=true)
	Add a new required ScalarParam < Type > object. More...

template<typename Type >
CArrayParam< Type > &	addCArray (std::istream &in, const char label, Type value, int n, bool isRequired=true)
	Add (but do not read) a required C array parameter. More...

template<typename Type >
DArrayParam< Type > &	addDArray (std::istream &in, const char *label, DArray< Type > &array, int n, bool isRequired=true)
	Add (but do not read) a DArray < Type > parameter. More...

template<typename Type , int N>
FArrayParam< Type, N > &	addFArray (std::istream &in, const char *label, FArray< Type, N > &array, bool isRequired=true)
	Add (but do not read) a FArray < Type, N > array parameter. More...

template<typename Type >
CArray2DParam< Type > &	addCArray2D (std::istream &in, const char label, Type value, int m, int n, int np, bool isRequired=true)
	Add (but do not read) a CArray2DParam < Type > 2D C-array. More...

template<typename Type >
DMatrixParam< Type > &	addDMatrix (std::istream &in, const char *label, DMatrix< Type > &matrix, int m, int n, bool isRequired=true)
	Add and read a required DMatrix < Type > matrix parameter. More...

Protected Member Functions inherited from Util::ParamComponent
	ParamComponent ()
	Constructor. More...

	ParamComponent (const ParamComponent &other)
	Copy constructor. More...

Constructor & Destructor Documentation

McMd::PairList::PairList ( )

Default constructor.

Definition at line 22 of file mcMd/neighbor/PairList.cpp.

References Util::ParamComposite::setClassName().

McMd::PairList::~PairList ( )

virtual

Destructor.

Deallocates arrays atom1Ptrs_, atom2Ptrs_, first_, and oldPositions_.

Definition at line 45 of file mcMd/neighbor/PairList.cpp.

Member Function Documentation

void McMd::PairList::readParameters ( std::istream & in )

virtual

Read atomCapacity and pairCapacity (maximum numbers of atoms and pairs).

Parameters

in	input stream

Reimplemented from Util::ParamComposite.

Definition at line 51 of file mcMd/neighbor/PairList.cpp.

void McMd::PairList::loadParameters ( Serializable::IArchive & ar )

virtual

Load internal state from an archive.

Parameters

ar	input/loading archive

Reimplemented from Util::ParamComposite.

Definition at line 61 of file mcMd/neighbor/PairList.cpp.

void McMd::PairList::save ( Serializable::OArchive & ar )

virtual

Save internal state to an archive.

Parameters

ar	output/saving archive

Reimplemented from Util::ParamComposite.

Definition at line 76 of file mcMd/neighbor/PairList.cpp.

Referenced by McMd::MdEwaldPairPotentialImpl< Interaction >::save(), and McMd::MdPairPotentialImpl< Interaction >::save().

void McMd::PairList::initialize	(	int	atomIdEnd,
		double	potentialCutoff
	)

Allocate memory and initialize.

Initial allocation of memory required by the PairList.

Precondition: readParameters() must be invoked before initialize(), so that values of atomCapacity, pairCapacity, skin are known. The initialize() method can only be called once.

Parameters

atomIdEnd	maximum allowed atom Id, plus 1
potentialCutoff	range of pair potential, without skin

Definition at line 88 of file mcMd/neighbor/PairList.cpp.

References Util::DArray< Data >::allocate(), McMd::CellList::setAtomCapacity(), and UTIL_THROW.

Referenced by McMd::MdEwaldPairPotentialImpl< Interaction >::readParameters(), and McMd::MdPairPotentialImpl< Interaction >::readParameters().

void McMd::PairList::setup ( const Boundary & boundary )

Setup an empty grid of cells for the internal cell list.

Definition at line 147 of file mcMd/neighbor/PairList.cpp.

References McMd::CellList::setup().

Referenced by McMd::MdPairPotential::buildPairList().

void McMd::PairList::clear ( )

Clear the PairList and CellList.

Precondition: This PairList must be allocated.

Definition at line 160 of file mcMd/neighbor/PairList.cpp.

References McMd::CellList::clear().

void McMd::PairList::addAtom ( Atom & atom )

inline

Add an Atom to the CellList.

After the clear() method is invoked, every Atom in a System must be passed to this method sequentially, within a loop over Atoms. The Atom positions must not change within this loop.

Parameters

atom	Atom to be added.

Definition at line 355 of file mcMd/neighbor/PairList.h.

Referenced by McMd::MdPairPotential::buildPairList().

void McMd::PairList::build ( const Boundary & boundary )

Use a complete CellList to build a new PairList.

Preconditions:

This PairList must be allocated
All atoms must have been added to the CellList.
Atomic positions must not have changed since they were added.

Parameters

boundary current Boundary object.

Definition at line 173 of file mcMd/neighbor/PairList.cpp.

References Simp::OrthorhombicBoundary::distanceSq(), McMd::CellList::getCellNeighbors(), McMd::Atom::id(), isInitialized(), McMd::Mask::isMasked(), McMd::Atom::mask(), McMd::Atom::position(), Util::FSArray< Data, Capacity >::size(), McMd::CellList::totCells(), and UTIL_THROW.

Referenced by McMd::MdPairPotential::buildPairList().

void McMd::PairList::begin ( PairIterator & iterator ) const

Initialize a PairIterator.

Parameters

iterator a PairList, initialized on output

Definition at line 295 of file mcMd/neighbor/PairList.cpp.

Referenced by McMd::MdEwaldPairPotentialImpl< Interaction >::addForces(), McMd::MdPairPotentialImpl< Interaction >::addForces(), McMd::MdEwaldPairPotentialImpl< Interaction >::computeEnergy(), McMd::MdPairPotentialImpl< Interaction >::computeEnergy(), McMd::MdEwaldPairPotentialImpl< Interaction >::computeStress(), McMd::PairIterator::PairIterator(), McMd::MdPairEnergyCoefficients::sample(), and McMd::NvtDpdVvIntegrator::setup().

int McMd::PairList::nAtom ( ) const

inline

Get the number of pairs currently in the PairList.

Definition at line 361 of file mcMd/neighbor/PairList.h.

int McMd::PairList::nPair ( ) const

inline

Get the number of pairs currently in the PairList.

Definition at line 367 of file mcMd/neighbor/PairList.h.

bool McMd::PairList::isInitialized ( ) const

inline

Has the initialize function been called?

Definition at line 391 of file mcMd/neighbor/PairList.h.

Referenced by build(), McMd::MdPairPotential::buildPairList(), isCurrent(), and isValid().

bool McMd::PairList::isCurrent ( const Boundary & boundary ) const

Returns true if PairList is current, false otherwise.

The PairList is considered current if no atom has moved a distance skin/2 since the PairList was built, and obsolete otherwise. The parameter skin is the difference between the Verlet radius that was used to construct the PairList and the maximum range of any nonbonded potential (i.e., the maxCutoff member of a PairPotential object).

Parameters

boundary Boundary object containing simulation cell dimensions