ParticleInteractLayout.h

Go to the documentation of this file.

// -*- C++ -*-
/***************************************************************************
 *
 * The IPPL Framework
 * 
 *
 * Visit http://people.web.psi.ch/adelmann/ for more details
 *
 ***************************************************************************/

#ifndef PARTICLE_INTERACT_LAYOUT_H
#define PARTICLE_INTERACT_LAYOUT_H

/*
 * ParticleInteractLayout - particle layout based on spatial decomposition,
 *   with particle interaction (nearest-neighbor with cutoff)
 *
 * This is a specialized version of ParticleLayout, which places particles
 * on processors based on their spatial location relative to a fixed grid.
 * In particular, this can maintain particles on processors based on a
 * specified FieldLayout or RegionLayout, so that particles are always on
 * the same node as the node containing the Field region to which they are
 * local.  This may also be used if there is no associated Field at all,
 * in which case a grid is selected based on an even distribution of
 * particles among processors.
 */

// include files
#include "Particle/ParticleSpatialLayout.h"
#include "Particle/ParticleInteractAttrib.h"
#include "Particle/IpplParticleBase.h"
#include "Region/RegionLayout.h"

#include <vector>
#include <iostream>

// forward declarations
class UserList;
template <unsigned Dim> class FieldLayout;
template <unsigned Dim, class T> class UniformCartesian;
template <class T, unsigned Dim, class Mesh> class ParticleInteractLayout;
template <class T, unsigned Dim, class Mesh>
std::ostream& operator<<(std::ostream&, const ParticleInteractLayout<T,Dim,Mesh>&);


// ParticleInteractLayout class definition.  Template parameters are the type
// and dimension of the ParticlePos object used for the particles.  The
// dimension of the position must match the dimension of the FieldLayout
// object used in this particle layout, if any.
// Optional template parameter for the mesh type
template < class T, unsigned Dim, class Mesh=UniformCartesian<Dim,T> >
class ParticleInteractLayout : public ParticleSpatialLayout<T, Dim, Mesh> {

public:
  // a struct which holds data for a single pairwise interaction
  struct pair_t {
    unsigned first;             // index of 2nd member of pair
    T second;                   // separation of particles
    pair_t(unsigned f, T s) : first(f), second(s) { }
    pair_t() { }
  };

  // type of iterator over pairs
  typedef typename std::vector<pair_t>::iterator pair_iterator;

  typedef typename ParticleLayout<T, Dim>::SingleParticlePos_t
    SingleParticlePos_t;
  typedef typename ParticleLayout<T, Dim>::Index_t Index_t;

  // type of attributes this layout should use for position, ID, and rad
  typedef ParticleInteractAttrib<SingleParticlePos_t> ParticlePos_t;
  typedef ParticleInteractAttrib<Index_t>             ParticleIndex_t;
  typedef ParticleInteractAttrib<T>                   ParticleInterRadius_t;

public:
  // constructor: The Field layout to which we match our particle's
  // locations.
  ParticleInteractLayout(FieldLayout<Dim>&);

  // constructor: this one also takes a Mesh
  ParticleInteractLayout(FieldLayout<Dim>&, Mesh&);

  // a similar constructor, but this one takes a RegionLayout.
  ParticleInteractLayout(const RegionLayout<T,Dim,Mesh>&);

  // a default constructor ... in this case, no layout will
  // be assumed by this class.  A layout may be given later via the
  // 'setLayout' method, either as a FieldLayout or as a RegionLayout.
  ParticleInteractLayout();

  // destructor
  ~ParticleInteractLayout();

  //
  // Particle swapping/update routines
  //

  // Update the location and indices of all atoms in the given IpplParticleBase
  // object.  This handles swapping particles among processors if
  // needed, and handles create and destroy requests.  When complete,
  // all nodes have correct layout information.
  void update(IpplParticleBase< ParticleInteractLayout<T,Dim,Mesh> >& p,
              const ParticleAttrib<char>* canSwap=0);

  //
  // Nearest-neighbor interaction calculation routines
  //

  // Retrieve a Forward-style iterator for the beginning and end of the
  // Nth (local) particle's nearest-neighbor pairlist.
  // If this is the first call of this
  // method after update(), this must make sure up-to-date info on particles
  // from neighboring nodes is available.
  void getPairlist(unsigned, pair_iterator&, pair_iterator&,
                   IpplParticleBase< ParticleInteractLayout<T,Dim,Mesh> >&);

  // specify the interaction radius ... two versions, one which gives a
  // single value for all atoms, the other giving a ParticleAttrib<T>
  // object with interaction radii for all the atoms in this object
  void setInteractionRadius(const T& r) {
    InterRadius = r;
    InterRadiusArray = 0;
    return;
  }
  void setInteractionRadius(ParticleInterRadius_t& rAttrib) {
    InterRadiusArray = &rAttrib;
    return;
  }

  // Return the maximum interaction radius of the entire system.  This is
  // the value from the most recent call to update()
  T getMaxInteractionRadius() { return MaxGlobalInterRadius; }

  // Return the interaction radius of atom i.
  T getInteractionRadius(unsigned i) {
    return (InterRadiusArray != 0 ? (*InterRadiusArray)[i] : InterRadius);
  }

  // directly set NeedGhostSwap flag to indicate whether this is needed
  // useful when a ParticleAttrib other than position R is modified and
  // we do not need to call update().
  void setNeedGhostSwap(bool cond=true) {
    NeedGhostSwap = cond;
  }

  //
  // virtual functions for FieldLayoutUser's (and other UserList users)
  //

  // Repartition onto a new layout
  virtual void Repartition(UserList *);

private:
  // information needed to compute which ghost particles to send/receive
  bool NeedGhostSwap;
  bool* InterNodeList;
  bool* SentToNodeList;
  unsigned InteractionNodes;

  // pairlist storage - a set of vectors
  std::vector< std::vector<pair_t>* > PairList;

  // interaction radius data.  If the attribute pointer is null, use the
  // scalar value instead.
  // also, the maximum interaction radius for the local particles, and for all
  // the particles
  T InterRadius, MaxGlobalInterRadius;
  ParticleInterRadius_t *InterRadiusArray;

  // perform common constructor tasks
  void setup();

  // recalculate where we need to send ghost particles for building
  // nearest-neighbor interaction lists
  void rebuild_interaction_data();

  // recalculate where we need to send ghost particles for building
  // nearest-neighbor interaction lists
  // special version which accounts for periodic boundary conditions
  void rebuild_interaction_data(const bool periodicBC[2*Dim]);

  // copy particles to other nodes for pairlist computation.  The arguments
  // are the current number of local particles, and the IpplParticleBase object.
  // This will also calculate the pairlists if necessary.
  void swap_ghost_particles(unsigned,
                    IpplParticleBase< ParticleInteractLayout<T,Dim,Mesh> >&);

  // copy particles to other nodes for pairlist computation.  The arguments
  // are the current number of local particles, and the IpplParticleBase object.
  // This will also calculate the pairlists if necessary.
  // special version to take account of periodic boundaries
  void swap_ghost_particles(unsigned,
                    IpplParticleBase< ParticleInteractLayout<T,Dim,Mesh> >&,
                    const bool periodicBC[2*Dim]);

  // find the pairs between our local particles and particles a1 ... (a2 - 1).
  // if the last argument is true, initialize all the pairlists to be empty.
  void find_pairs(const unsigned LocalNum, const unsigned a1,
                  const unsigned a2, const bool initLists,
                  IpplParticleBase< ParticleInteractLayout<T,Dim,Mesh> >& PData);

  // change the value of the maximum local interaction radius
  void setMaxInteractionRadius(T maxval) { MaxGlobalInterRadius = maxval; }

  // Return the maximum interaction radius of the local particles.
  T getMaxLocalInteractionRadius();
};

#include "Particle/ParticleInteractLayout.hpp"

#endif  // PARTICLE_INTERACT_LAYOUT_H

/***************************************************************************
 * $RCSfile: ParticleInteractLayout.h,v $   $Author: adelmann $
 * $Revision: 1.1.1.1 $   $Date: 2003/01/23 07:40:29 $
 * IPPL_VERSION_ID: $Id: ParticleInteractLayout.h,v 1.1.1.1 2003/01/23 07:40:29 adelmann Exp $ 
 ***************************************************************************/