mcMd/neighbor/PairList.h

#ifndef MCMD_PAIR_LIST_H
#define MCMD_PAIR_LIST_H

/*
* Simpatico - Simulation Package for Polymeric and Molecular Liquids
*
* Copyright 2010 - 2017, The Regents of the University of Minnesota
* Distributed under the terms of the GNU General Public License.
*/

#include "CellList.h"
#include <simp/boundary/Boundary.h>
#include <util/param/ParamComposite.h>
#include <util/containers/DArray.h>
#include <util/space/Vector.h>

class PairListTest;

namespace McMd
{

   using namespace Util;
   using namespace Simp;

   class Atom;
   class PairIterator;
   
   class PairList : public ParamComposite 
   {

      // Null value for any non-negative index
      static const int NullIndex = -1;   

   public:
  
      PairList();
   
      virtual ~PairList();
   
      void readParameters(std::istream &in);
   
      virtual void loadParameters(Serializable::IArchive &ar);

      virtual void save(Serializable::OArchive &ar);



      void initialize(int atomIdEnd, double potentialCutoff);
  
      void setup(const Boundary &boundary);

      void clear();

      void addAtom(Atom& atom);

      void build(const Boundary& boundary);

      void begin(PairIterator &iterator) const;
 

 
      int nAtom() const;

      int nPair() const;

      bool isInitialized() const;
   
      bool isCurrent(const Boundary &boundary) const;

      bool isValid() const;
  

 
      int maxNAtom() const;

      int maxNPair() const;

      int buildCounter() const;

      void clearStatistics();


   private:
  
      CellList  cellList_;

      DArray<Atom*>  atom1Ptrs_;  

      DArray<Atom*>  atom2Ptrs_;  

      DArray<int>  first_; 

      DArray<Vector>  oldPositions_;

      double  skin_;
   
      double cutoff_;
   
      int  atomCapacity_;     
   
      int  pairCapacity_;     
   
      int  nAtom1_;      

      int  nAtom2_; 
   
      int  nAtom_;     
   
      int  tList1_;     

      int  maxNAtom_;     
   
      int  maxNAtom2_;     
   
      int  buildCounter_;

      bool isInitialized_;
  
      void allocate();

      /* 
      * Implementation Notes:
      *
      * The pair list is stored in Atom* pointer arrays atom1Ptrs_, atom2Ptrs_, 
      * and in an integer array first_. Each element of atom1Ptrs_ contains a 
      * pointer to the first atom in a pair (the primary Atom). Each element 
      * of atom2Ptrs_ contains a pointer to the second atom in a pair (the 
      * secondary Atom).  Secondary atoms that are neighbors of the same 
      * primary atom are listed consecutively.  Element first_[i] contains the 
      * array index of the first element in atom2Ptrs_ that contains a neighbor 
      * of primary atom atom1Ptrs_[i]. Pointers to neighbors of primary atom
      * *atom1Ptrs_[i] are thus stored in elements first_[i] <= j < first_[i+1]
      * of atom2Ptrs_.  Each pair is included only once, by including only 
      * pairs in which atom2Ptrs_[j]->id() > atom1Ptrs_[i]->id(), so
      * the Id of the secondary atom in a pair is always greater than that of
      * the primary atom.  The total number of primary atoms in atom1Ptrs_ is 
      * nAtom1_. The total number of secondary atoms in Array atom2Ptrs_ (or 
      * the total number of distinct pairs) is nAtom2_. The total number of
      * Atoms in the System in nAtom_.
      *
      * The only way legal way to loop over all atom pairs, using the public 
      * interface of a PairList, is to use a PairListIterator. See the 
      * documentation of PairListIterator for a discussion of its usage. The 
      * resulting loop over pairs is equivalent to the following double loop 
      * over private member variables of PairList:
      * 
      *    int i, j;
      *    Atom* atom1Ptr;
      *    Atom* atom2Ptr;
      *
      *    \\ Loop over primary Atoms
      *    for (i = 0; i < nAtom1_; ++i) {
      *       atom1Ptr = atom1Ptrs_[i];
      *
      *       // Loop over secondary atoms
      *       for (j = first_[i]; j < first_[i+1]; ++j) {
      *           atom2Ptr = atom2Ptrs_[j];
      *
      *           // ... Do something with Atoms *atom1Ptr and *atom2Ptr.
      *
      *       }
      *    }
      *
      * Note that DArray<int> first_ contains nAtom1_ + 1 elements. The first
      * element, element first_[0] is equal to 0, and the last element,
      * first_[nAtom1_], is always equal to nAtom2_, the total number of 
      * pairs.
      *
      * The number of primary Atoms nAtom1_ is generally less than nAtom_, the 
      * total number of atoms, because some Atoms have no neighbors with integer
      * Ids higher than their own. This is always true, for example, for the
      * Atom with the highest Id. Pointers to such atoms, which do not appear
      * in the first nAtom1_ elements of atom1Ptrs_, are instead stored  in the
      * last elements of the atom1Ptrs_ array , in elements tList1 + 1, .... ,
      * atomCapacity_ - 1. The previous position Vectors for these Atoms are 
      * stored in the corresponding elements of the oldPositions_ array. 
      * These pointers and previous positions retained because they are used 
      * in the isCurrent() method to calculate how far these Atoms have moved 
      * since the last time the PairList was built.
      */

   // friends:
   
      // Unit test classes
      friend class ::PairListTest;
   
   }; // end class PairList


   /*
   * Add an Atom to the CellList.
   */ 
   inline void PairList::addAtom(Atom &atom)
   {  cellList_.addAtom(atom); }

   /*
   * Get the current number of atoms in the pairlist.
   */ 
   inline int PairList::nAtom() const
   {  return nAtom_; }

   /*
   * Get the current number of pairs.
   */ 
   inline int PairList::nPair() const
   {  return nAtom2_; }

   /*
   * Get the maximum value of aAtom() since instantiation.
   */ 
   inline int PairList::maxNAtom() const
   {  return maxNAtom_; }

   /*
   * Get the maximum value of nPair() since instantiation.
   */ 
   inline int PairList::maxNPair() const
   {  return maxNAtom2_; }

   /*
   * Get the number of times this PairList has been built.
   */ 
   inline int PairList::buildCounter() const
   {  return buildCounter_; }

   /*
   * Has the initialize function been called?
   */ 
   inline bool PairList::isInitialized() const
   {  return isInitialized_; }

} 
#endif