All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Attributes | Friends | List of all members
PLMD::DynamicList< T > Class Template Reference

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 >:
Inheritance graph
[legend]

Public Member Functions

 DynamicList ()
 Constructor. More...
 
operator[] (const unsigned &i) const
 An operator that returns the element from the current active list. More...
 
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...
 
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 updateIndex (const unsigned &ii)
 This can be used for a fast version of updateActiveMembers in which only a subset of the indexes are checked. 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...
 
unsigned linkIndex (const unsigned &ii) const
 Return the index of this atom. 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...
 
std::vector< int > translator
 This translates a position from all to active. 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

template<typename T>
PLMD::DynamicList< T >::DynamicList ( )
inline

Constructor.

Member Function Documentation

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

Make something active.

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

Make everything in the list active.

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

Add something to the active list.

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

Clear the list.

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

Make a particular element inactive.

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

Make everything in the list inactive.

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

Empty the list of active members.

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

Return the total number of elements in the list.

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

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

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

Return the number of elements that are currently active.

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

Find out if a member is active.

template<typename T >
unsigned PLMD::DynamicList< T >::linkIndex ( const unsigned &  ii) const

Return the index of this atom.

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

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

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)

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

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

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

Retriee the list of active objects.

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

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

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

This sorts the elements in the active list.

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

Get the list of active members.

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

This tells one if an update has been completed.

template<typename T >
void PLMD::DynamicList< T >::updateIndex ( const unsigned &  ii)

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

Friends And Related Function Documentation

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

template<typename T>
std::vector<unsigned> PLMD::DynamicList< T >::active
private

This is the list of active members.

template<typename T>
std::vector<T> PLMD::DynamicList< T >::all
private

This is the list of all the relevent members.

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.

template<typename T>
bool PLMD::DynamicList< T >::allWereDeactivated
private
template<typename T>
unsigned PLMD::DynamicList< T >::nactive
private

The current number of active members.

template<typename T>
unsigned PLMD::DynamicList< T >::nprocessors
private

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

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.

template<typename T>
unsigned PLMD::DynamicList< T >::rank
private

The rank of the node we are on.

template<typename T>
std::vector<int> PLMD::DynamicList< T >::translator
private

This translates a position from all to active.


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