A class for storing a list that changes which members are active as a function of time. More...

#include <DynamicList.h>

Inheritance diagram for PLMD::DynamicList< T >:

Public Member Functions
	DynamicList ()
	Constructor. More...

T	operator[] (const unsigned &i) const
	An operator that returns the element from the current active list. More...

T	operator() (const unsigned &i) const
	An operator that returns the element from the full list (used in neighbour lists) More...

void	clear ()
	Clear the list. More...

unsigned	fullSize () const
	Return the total number of elements in the list. More...

unsigned	getNumberActive () const
	Return the number of elements that are currently active. More...

bool	isActive (const unsigned &) const
	Find out if a member is active. More...

void	setupMPICommunication (Communicator &comm)
	Setup MPI communication if things are activated/deactivated on different nodes. More...

void	addIndexToList (const T &ii)
	Add something to the active list. More...

void	createIndexListFromVector (const std::vector< T > &myind)
	Create the list from a vector. More...

int	getIndexOfElement (const T &t) const
	Find the index of in the list which has value t. More...

void	deactivate (const T &t)
	Make a particular element inactive. More...

void	deactivateAll ()
	Make everything in the list inactive. More...

void	activate (const unsigned ii)
	Make something active. More...

void	activateAll ()
	Make everything in the list active. More...

void	mpi_gatherActiveMembers (Communicator &comm)
	Do updateActiveMembers for a loop that has been distributed over multiple nodes. More...

void	updateActiveMembers ()
	Get the list of active members. More...

void	emptyActiveMembers ()
	Empty the list of active members. More...

void	putIndexInActiveArray (const unsigned &ii)
	This can be used for a fast version of updateActiveMembers in which only a subset of the indexes are checked. More...

void	completeUpdate ()
	This can be called on once update is complete. More...

bool	updateComplete () const
	This tells one if an update has been completed. More...

void	sortActiveList ()
	This sorts the elements in the active list. More...

std::vector< T >	retrieveActiveList ()
	Retriee the list of active objects. More...

Private Attributes
std::vector< T >	all
	This is the list of all the relevent members. More...

std::vector< unsigned >	onoff
	This tells us what members of all are on/off at any given time. More...

unsigned	nactive
	The current number of active members. More...

std::vector< unsigned >	active
	This is the list of active members. More...

unsigned	nprocessors
	the number of processors the jobs in the Dynamic list are distributed across More...

unsigned	rank
	The rank of the node we are on. More...

bool	allWereActivated
	These are flags that are used internally to ensure that dynamic lists are being used properly. More...

bool	allWereDeactivated

Friends
template<typename U >
void	mpi_gatherActiveMembers (Communicator &, std::vector< DynamicList< U > > &)
	This gathers data split across nodes list of Dynamic lists. More...

Detailed Description

template<typename T>
class PLMD::DynamicList< T >

A class for storing a list that changes which members are active as a function of time.

It also contains friends method that allows you to link two dynamic lists so that you can request stuff from list2 in list1 A PLMD::DynamicList can be used to change what elements in a list should be looped over at any given time. This class is, for the most part, used in tandem with PLMD::NeighbourList. For complex reasons related to the PLMD::MultiColvar object the dynamic list class is separate from PLMD::NeighbourList. This is no bad thing though as there may be occasions where one needs to change the elements currently involved in a calculation using some non neighbour list based method. To be clear though PLMD::NeighbourList will look after everything connected with PLMD::DynamicList other than the initial setup of PLMD::DynamicList and the loops over the active elements of the list.

The essence of a dynamic list is as follows. Consider the following loop:

std::vector<something> aa;
for(unsigned i=0;i<aa.size();++i){ aa[i].doSomething(); }

This takes all the members in aa and does something or other to them - simple. Now it may well be that the precise set of things from aa that you want to do in any given time or place is not always the same. We can thus use dynamic lists to control what particular things are done are done at a given time. That is to say we can use PLMD::DynamicList to specify a subset of things from aa to do at a given time. This is done by:

DynamicList list; std::vector<something> aa; unsigned kk;
for(unsigned i=0;i<list.getNumberActive();++i){ kk=list[i]; aa[kk].doSomething(); }

where we somewhere set up the list and make some decisions (in PLMD::NeighbourList for example) as to what elements from aa are currently active.

Setup

Setting up a dynamic list is a matter of declaring it and passing a set of indices to it. For the example above with aa one can do this using:

DynamicList list;
for(unsigned i=0;i<aa.size();++i) list.addIndexToList( i );

Doing this creates the list of all members.

Cycling over the full set of members

To cycle over the full set of members in the list one should do:

for(unsigned i=0;i<list.fullSize();++i){ kk=list(i); aa[kk].doSomething(); }

If the DynamicList was set up as per the example above then this code is equivalent to:

for(unsigned i=0;i<aa.size();++i){ aa[i].doSomething(); }

Activating and deactivating members

The important bussiness comes when we start activating and deactivating members. When we create a dynamic list none of the members are active for bussiness. Hence, getNumberActive() returns 0. There are four routines that we can use to change this situation.

activateAll()	make all members active
activate(i)	make the ith element of the list active (in the example above this mean we doSomething() for element i of aa)
deactivateAll()	make all members inactive
deactivate(i)	make th ith element of the list active (in the example above this mean we dont doSomething() for element i of aa)

Once you have activated and deactivated members to your hearts content you can then update the dynamic list using PLMD::DynamicList::updateActiveMembers(). Once this is done you can loop over only the members you have specifically made active using:

DynamicList list;
for(unsigned i=0;i<list.getNumberActive();++i){ kk=list[i]; aa[kk].doSomething(); }

as was described above.

Using MPI

If your loop is distributed over processesors you can still use dynamic lists to activate and deactivate members. When running with mpi however you must call PLMD::DynamicList::setupMPICommunication during initialization. To gather the members that have been activated/deactivated during the running of all the processes on all the nodes you must call PLMD::DynamicList::mpi_gatherActiveMembers in place of PLMD::DynamicList::updateActiveMembers.

A final note

When using dynamic_lists we strongly recommend that you first compile without the -DNDEBUG flag. When this flag is not present many checks are performed inside the dynamic list class, which will help you ensure that the dynamic list is used correctly.

Constructor & Destructor Documentation

◆ DynamicList()

template<typename T>

PLMD::DynamicList< T >::DynamicList ( )

inline

Constructor.

Member Function Documentation

◆ activate()

template<typename T >

void PLMD::DynamicList< T >::activate ( const unsigned ii )

Make something active.

◆ activateAll()

template<typename T >

void PLMD::DynamicList< T >::activateAll ( )

Make everything in the list active.

◆ addIndexToList()

template<typename T>

void PLMD::DynamicList< T >::addIndexToList ( const T & ii )

Add something to the active list.

◆ clear()

template<typename T >

void PLMD::DynamicList< T >::clear ( )

Clear the list.

◆ completeUpdate()

template<typename T >

void PLMD::DynamicList< T >::completeUpdate ( )

This can be called on once update is complete.

◆ createIndexListFromVector()

template<typename T>

void PLMD::DynamicList< T >::createIndexListFromVector ( const std::vector< T > & myind )

Create the list from a vector.

◆ deactivate()

template<typename T>

void PLMD::DynamicList< T >::deactivate ( const T & t )

Make a particular element inactive.

◆ deactivateAll()

template<typename T >

void PLMD::DynamicList< T >::deactivateAll ( )

Make everything in the list inactive.

◆ emptyActiveMembers()

template<typename T >

void PLMD::DynamicList< T >::emptyActiveMembers ( )

Empty the list of active members.

◆ fullSize()

template<typename T >

unsigned PLMD::DynamicList< T >::fullSize ( ) const

Return the total number of elements in the list.

◆ getIndexOfElement()

template<typename T>

int PLMD::DynamicList< T >::getIndexOfElement ( const T & t ) const

Find the index of in the list which has value t.

◆ getNumberActive()

template<typename T >

unsigned PLMD::DynamicList< T >::getNumberActive ( ) const

Return the number of elements that are currently active.

◆ isActive()

template<typename T >

bool PLMD::DynamicList< T >::isActive ( const unsigned & i ) const

Find out if a member is active.

◆ mpi_gatherActiveMembers()

template<typename T >

void PLMD::DynamicList< T >::mpi_gatherActiveMembers ( Communicator & comm )

Do updateActiveMembers for a loop that has been distributed over multiple nodes.

◆ operator()()

template<typename T>

T PLMD::DynamicList< T >::operator() ( const unsigned & i ) const

inline

An operator that returns the element from the full list (used in neighbour lists)

◆ operator[]()

template<typename T>

T PLMD::DynamicList< T >::operator[] ( const unsigned & i ) const

inline

An operator that returns the element from the current active list.

◆ putIndexInActiveArray()

template<typename T >

void PLMD::DynamicList< T >::putIndexInActiveArray ( const unsigned & ii )

This can be used for a fast version of updateActiveMembers in which only a subset of the indexes are checked.

◆ retrieveActiveList()

template<typename T >

std::vector< T > PLMD::DynamicList< T >::retrieveActiveList ( )

Retriee the list of active objects.

◆ setupMPICommunication()

template<typename T >

void PLMD::DynamicList< T >::setupMPICommunication ( Communicator & comm )

Setup MPI communication if things are activated/deactivated on different nodes.

◆ sortActiveList()

template<typename T >

void PLMD::DynamicList< T >::sortActiveList ( )

This sorts the elements in the active list.

◆ updateActiveMembers()

template<typename T >

void PLMD::DynamicList< T >::updateActiveMembers ( )

Get the list of active members.

◆ updateComplete()

template<typename T >

bool PLMD::DynamicList< T >::updateComplete ( ) const

This tells one if an update has been completed.

Friends And Related Function Documentation

◆ mpi_gatherActiveMembers

template<typename T>

template<typename U >

void mpi_gatherActiveMembers	(	Communicator &	comm,
		std::vector< DynamicList< U > > &	ll
	)

friend

This gathers data split across nodes list of Dynamic lists.

Member Data Documentation

◆ active

template<typename T>

std::vector<unsigned> PLMD::DynamicList< T >::active

private

This is the list of active members.

◆ all

template<typename T>

std::vector<T> PLMD::DynamicList< T >::all

private

This is the list of all the relevent members.

◆ allWereActivated

template<typename T>

bool PLMD::DynamicList< T >::allWereActivated

private

These are flags that are used internally to ensure that dynamic lists are being used properly.

◆ allWereDeactivated

template<typename T>

bool PLMD::DynamicList< T >::allWereDeactivated

private

◆ nactive

template<typename T>

unsigned PLMD::DynamicList< T >::nactive

private

The current number of active members.

◆ nprocessors

template<typename T>

unsigned PLMD::DynamicList< T >::nprocessors

private

the number of processors the jobs in the Dynamic list are distributed across

◆ onoff

template<typename T>

std::vector<unsigned> PLMD::DynamicList< T >::onoff

private

This tells us what members of all are on/off at any given time.

◆ rank

template<typename T>

unsigned PLMD::DynamicList< T >::rank

private

The rank of the node we are on.

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

tools/DynamicList.h

Public Member Functions

Private Attributes

Friends

Detailed Description

template<typename T> class PLMD::DynamicList< T >

Setup

Cycling over the full set of members

Activating and deactivating members

Using MPI

A final note

Constructor & Destructor Documentation

◆ DynamicList()

Member Function Documentation

◆ activate()

◆ activateAll()

◆ addIndexToList()

◆ clear()

◆ completeUpdate()

◆ createIndexListFromVector()

◆ deactivate()

◆ deactivateAll()

◆ emptyActiveMembers()

◆ fullSize()

◆ getIndexOfElement()

◆ getNumberActive()

◆ isActive()

◆ mpi_gatherActiveMembers()

◆ operator()()

◆ operator[]()

◆ putIndexInActiveArray()

◆ retrieveActiveList()

◆ setupMPICommunication()

◆ sortActiveList()

◆ updateActiveMembers()

◆ updateComplete()

Friends And Related Function Documentation

◆ mpi_gatherActiveMembers

Member Data Documentation

◆ active

◆ all

◆ allWereActivated

◆ allWereDeactivated

◆ nactive

◆ nprocessors

◆ onoff

◆ rank

template<typename T>
class PLMD::DynamicList< T >