Particles< ParticleTraits > Class Template Reference

The Particles class is the base class to be used for development of user-defined particles classes that describe application-specific particle populations. More...

#include <Particles.h>

Collaboration diagram for Particles< ParticleTraits >:

Collaboration graph
[legend]

List of all members.

Public Types

typedef Particles< ParticleTraits > This_t
 Typedefs for this object, and its trait class type.
typedef ParticleTraits Traits_t
typedef long Size_t
 The data type used to refer to the number of particles.
typedef
ParticleTraits::AttributeEngineTag_t 
AttributeEngineTag_t
 The tag type for the engine used to store attributes.
typedef
ParticleTraits::ParticleLayout_t 
ParticleLayout_t
 The full particle layout type (not just a tag).
typedef Engine< 1, double,
AttributeEngineTag_t
TempEngine_t
 The attribute layout type.
typedef TempEngine_t::Layout_t AttributeLayout_t
typedef
AttributeLayout_t::PatchID_t 
PatchID_t
 Type of data used to specify a patch number in dynamic operations.
typedef AttributeLayout_t::Domain_t AttributeDomain_t
 The type of domain used in the attribute layout.

Public Member Functions

 Particles (const ParticleLayout_t &pl)
 Construct a Particles object, using the given particle layout object.
 Particles ()
 Default constructor: this should be used if
  • The particle layout has a useful default constructor, and
  • The attribute layout has a useful default constructor, and
  • The initialize() method will be used later.

 Particles (const This_t &p)
 Copy constructor: only copy the layout data and destroy flag, do NOT copy the attributes.
void initialize (const ParticleLayout_t &pl)
 Initialize this object with the given particle layout.
 ~Particles ()
int destroyMethod () const
 Return our current destroy method code.
template<class DestroyMethod >
void setDestroyMethod (const DestroyMethod &)
 Change the current destroy method.
Size_t deferredDestroyAmount (PatchID_t pid=(-1)) const
 Return the number of particles we have queued to destroy in the next performDestroy call, for all the patches (if pid < 0), or just for the specified patch.
DynamicArray< int, Dynamic > & destroyList (int pid)
 Return a reference to the destroy list for local patch pid.
const DynamicArray< int,
Dynamic > & 
destroyList (int pid) const
template<class Out >
void print (Out &o) const
Attribute accessors
bool initialized () const
 Has this object been initialized?
Size_t size () const
 Return the total number of particles.
const AttributeDomain_tdomain () const
 Return the domain of the attributes of the Particles.
ParticleLayout_tparticleLayout ()
 Return a reference to the particle layout object.
const ParticleLayout_tparticleLayout () const
AttributeLayout_tattributeLayout ()
 Return a reference to the attribute layout object.
const AttributeLayout_tattributeLayout () const
AttributeList::Size_t attributes () const
 Return the number of attributes.
Attributeattribute (AttributeList::Size_t n)
 Return the Nth attribute.
const Attributeattribute (AttributeList::Size_t n) const
Attribute modifier methods
template<class T >
AttributeList::Size_t addAttribute (T &attrib)
 Add a new attribute to this object .
bool removeAttribute (AttributeList::Size_t index)
 Remove an Attribute from our list by index number.
Dynamic particle interface (sync, swap, create, destroy, etc.)
void sync ()
 Sync up this object, by letting all contexts know what the other contexts have created and destroyed, plus move particles around to their proper place.
template<class T >
void sync (const T &attrib)
 Sync up this object, but also specify an object that can be used as an attribute for the particle layout's distribution algorithm.
void swap ()
 Just perform the swap operation, which invokes the corresponding routine in the particle layout object to move particles around to other patches.
template<class T >
void swap (const T &attrib)
void renumber ()
 Recompute the global domain.
void create (Size_t np, PatchID_t patch=(-1), bool renum=true)
 Create the specified number of particles on the local context, and add them to the last local patch, or the specified patch.
void globalCreate (Size_t np, bool renum=true)
 Create the specified number of particles, total, spread across all patches.
template<class DomainType >
void destroy (const DomainType &dom, PatchID_t pid=(-1), bool renum=true)
 Destroy set of particles specified by DomainType, which may be a 1D Range of particle index numbers or a list of index numbers.
template<class Iter >
void destroy (Iter begin, Iter end, PatchID_t pid=(-1), bool renum=true)
 Same as above, but use begin/end iterator pair to specify domain.
template<class DomainType >
void deferredDestroy (const DomainType &domain, PatchID_t pid=(-1))
 Destroy the particles in the given global domain by storing them a list for use in a later performDestroy call.
template<class Iter >
void deferredDestroy (Iter begin, Iter end, PatchID_t pid=(-1))
 Same as above, but use begin/end iterator pair to specify domain.
void performDestroy (PatchID_t pid=(-1), bool renum=true)
 Carry out all the previously requested destroy commands, and renumber the domain if requested.
Boundary Condition methods
template<class Subject , class Object , class BCType >
void addBoundaryCondition (const Subject &s, const Object &o, const BCType &bc)
 Add a new boundary condition of given type, acting on info from the Subject and affecting values in the Object.
template<class Subject , class BCType >
void addBoundaryCondition (const Subject &s, const BCType &bc)
 Add a new boundary condition of given type, acting on info from the Subject and affecting values in the same Subject.
void removeBoundaryCondition (ParticleBCList::Size_t i)
 Remove the ith boundary condition in this Particles object.
void removeBoundaryConditions ()
 Remove all the boundary conditions.
void applyBoundaryConditions (PatchID_t pid=(-1))
 Apply the boundary conditions to the existing particles for all patches, or just one (if all, the value for the patch ID is < 0).
ParticleBCList::Size_t boundaryConditions () const
 Return number of boundary conditions.
ParticleBCItemboundaryCondition (ParticleBCList::Size_t i)
 Return the ith boundary condition in the list.
const ParticleBCItemboundaryCondition (ParticleBCList::Size_t i) const


Detailed Description

template<class ParticleTraits>
class Particles< ParticleTraits >

The Particles class is the base class to be used for development of user-defined particles classes that describe application-specific particle populations.

Particles is templated on a ParticleTraits class that provides typedefs for:

From these types, Particles can determine the geometry of the system, and the type of layout that should be used by the attributes. Particles provides the basic interface for collecting a set of heterogeneous Attributes, each of which describes a particular characteristic of all the particles. With this interface, the user can create or destroy particles, apply boundary conditions and update the particle data distribution.

Here is an example of what the ParticleTraits class might look like:

 template <class FieldLayoutType, class GeometryType>
 struct StdParticleTraits {
   typedef SpatialLayout<FieldLayoutType, GeometryType>  ParticleLayout_t;
   typedef MultiPatch AttributeEngineTag_t;
 };

Member Typedef Documentation

template<class ParticleTraits >
typedef Particles<ParticleTraits> Particles< ParticleTraits >::This_t

Typedefs for this object, and its trait class type.

template<class ParticleTraits >
typedef ParticleTraits Particles< ParticleTraits >::Traits_t

template<class ParticleTraits >
typedef long Particles< ParticleTraits >::Size_t

The data type used to refer to the number of particles.

template<class ParticleTraits >
typedef ParticleTraits::AttributeEngineTag_t Particles< ParticleTraits >::AttributeEngineTag_t

The tag type for the engine used to store attributes.

All attributes should use the same engine, since they will use the same layout object.

template<class ParticleTraits >
typedef ParticleTraits::ParticleLayout_t Particles< ParticleTraits >::ParticleLayout_t

The full particle layout type (not just a tag).

The particle layout determines what particles go where based on some algorithm. The layout should have the type of geometry, dimensions, etc., for the simulation domain of the particles.

template<class ParticleTraits >
typedef Engine<1, double, AttributeEngineTag_t> Particles< ParticleTraits >::TempEngine_t

The attribute layout type.

To get it, we need the type of engine in a typical attribute, so we use a temporary engine type (TempEngine_t has no other purpose but to be used in the next line to get its layout type).

template<class ParticleTraits >
typedef TempEngine_t::Layout_t Particles< ParticleTraits >::AttributeLayout_t

template<class ParticleTraits >
typedef AttributeLayout_t::PatchID_t Particles< ParticleTraits >::PatchID_t

Type of data used to specify a patch number in dynamic operations.

template<class ParticleTraits >
typedef AttributeLayout_t::Domain_t Particles< ParticleTraits >::AttributeDomain_t

The type of domain used in the attribute layout.


Constructor & Destructor Documentation

template<class ParticleTraits >
Particles< ParticleTraits >::Particles ( const ParticleLayout_t pl  ) 

Construct a Particles object, using the given particle layout object.

Let the particle layout object initialize the attribute data layout.

template<class ParticleTraits >
Particles< ParticleTraits >::Particles (  ) 

Default constructor: this should be used if

  • The particle layout has a useful default constructor, and
  • The attribute layout has a useful default constructor, and
  • The initialize() method will be used later.

template<class ParticleTraits >
Particles< ParticleTraits >::Particles ( const This_t p  ) 

Copy constructor: only copy the layout data and destroy flag, do NOT copy the attributes.

The new particle object starts out with just layouts and no attributes (except for the internal destroy list).

template<class ParticleTraits >
Particles< ParticleTraits >::~Particles (  ) 


Member Function Documentation

template<class ParticleTraits >
void Particles< ParticleTraits >::initialize ( const ParticleLayout_t pl  ) 

Initialize this object with the given particle layout.

template<class ParticleTraits >
bool Particles< ParticleTraits >::initialized (  )  const [inline]

Has this object been initialized?

template<class ParticleTraits >
Size_t Particles< ParticleTraits >::size (  )  const [inline]

Return the total number of particles.

template<class ParticleTraits >
const AttributeDomain_t& Particles< ParticleTraits >::domain (  )  const [inline]

Return the domain of the attributes of the Particles.

References Particles< ParticleTraits >::attributeLayout().

template<class ParticleTraits >
ParticleLayout_t& Particles< ParticleTraits >::particleLayout (  )  [inline]

Return a reference to the particle layout object.

template<class ParticleTraits >
const ParticleLayout_t& Particles< ParticleTraits >::particleLayout (  )  const [inline]

template<class ParticleTraits >
AttributeLayout_t& Particles< ParticleTraits >::attributeLayout (  )  [inline]

Return a reference to the attribute layout object.

Referenced by Particles< ParticleTraits >::domain().

template<class ParticleTraits >
const AttributeLayout_t& Particles< ParticleTraits >::attributeLayout (  )  const [inline]

template<class ParticleTraits >
AttributeList::Size_t Particles< ParticleTraits >::attributes (  )  const [inline]

Return the number of attributes.

References AttributeList::size().

template<class ParticleTraits >
Attribute* Particles< ParticleTraits >::attribute ( AttributeList::Size_t  n  )  [inline]

Return the Nth attribute.

References AttributeList::attribute().

template<class ParticleTraits >
const Attribute* Particles< ParticleTraits >::attribute ( AttributeList::Size_t  n  )  const [inline]

template<class ParticleTraits >
int Particles< ParticleTraits >::destroyMethod (  )  const [inline]

Return our current destroy method code.

template<class ParticleTraits >
template<class DestroyMethod >
void Particles< ParticleTraits >::setDestroyMethod ( const DestroyMethod &   )  [inline]

Change the current destroy method.

This changes a flag, which is examined during the next sync() or performDestroy() call to determine how to perform the cached destroy requests. So changing this flag will affect all cached destroys, not just the ones issued after this call.

template<class ParticleTraits >
Size_t Particles< ParticleTraits >::deferredDestroyAmount ( PatchID_t  pid = (-1)  )  const

Return the number of particles we have queued to destroy in the next performDestroy call, for all the patches (if pid < 0), or just for the specified patch.

template<class ParticleTraits >
DynamicArray<int,Dynamic>& Particles< ParticleTraits >::destroyList ( int  pid  )  [inline]

Return a reference to the destroy list for local patch pid.

References PAssert.

template<class ParticleTraits >
const DynamicArray<int,Dynamic>& Particles< ParticleTraits >::destroyList ( int  pid  )  const [inline]

References PAssert.

template<class ParticleTraits >
template<class T >
AttributeList::Size_t Particles< ParticleTraits >::addAttribute ( T &  attrib  )  [inline]

Add a new attribute to this object .

.. it will be initialized with the proper attribute layout, and put in our list. It must have the proper engine type. The attribute can be given an optional name for use in later look-ups of the attribute. Return the index of the newly added attribute.

References AttributeList::add().

template<class ParticleTraits >
bool Particles< ParticleTraits >::removeAttribute ( AttributeList::Size_t  index  )  [inline]

Remove an Attribute from our list by index number.

Return success.

References AttributeList::remove().

template<class ParticleTraits >
void Particles< ParticleTraits >::sync (  )  [inline]

Sync up this object, by letting all contexts know what the other contexts have created and destroyed, plus move particles around to their proper place.

The no-argument version of sync() should be used for particle layouts that do not need to know the position or other information to do their job. Sync will also apply all cached delete operations and apply boundary conditions. The order of operations is:

  • apply boundary conditions
  • perform cached destroys
  • swap particles to proper patches

template<class ParticleTraits >
template<class T >
void Particles< ParticleTraits >::sync ( const T &  attrib  )  [inline]

Sync up this object, but also specify an object that can be used as an attribute for the particle layout's distribution algorithm.

For example, this could be a position attribute when using a spatial layout. The object should have the same interface and layout as the other particle attributes. If more than one attribute is needed (e.g., separate components of the position), they must be packaged up as a single attribute using, for example, the global function "vector". Sync will also apply all cached delete operations and apply boundary conditions.

template<class ParticleTraits >
void Particles< ParticleTraits >::swap (  )  [inline]

Just perform the swap operation, which invokes the corresponding routine in the particle layout object to move particles around to other patches.

No other operation is done (destroys, BC's, etc). To do ALL the update operations, call sync() (which in turn will call swap(), among other things). We have versions of swap() that takes the same types of arguments as sync().

template<class ParticleTraits >
template<class T >
void Particles< ParticleTraits >::swap ( const T &  attrib  )  [inline]

template<class ParticleTraits >
void Particles< ParticleTraits >::renumber (  )  [inline]

Recompute the global domain.

No particle swapping or application of boundary conditions is done here.

Referenced by Particles< ParticleTraits >::create().

template<class ParticleTraits >
void Particles< ParticleTraits >::create ( Size_t  np,
PatchID_t  patch = (-1),
bool  renum = true 
) [inline]

Create the specified number of particles on the local context, and add them to the last local patch, or the specified patch.

The domain is renumbered after the create operation if the last argument is true. Note that if you are renumbering, you really must call this function in SPMD style on every context.

References Particles< ParticleTraits >::renumber().

template<class ParticleTraits >
void Particles< ParticleTraits >::globalCreate ( Size_t  np,
bool  renum = true 
)

Create the specified number of particles, total, spread across all patches.

An equal (or close to) number of particles are added to each patch on each context. This must be called in SPMD-style. The domain is renumbered after the create operation if the second argument is true.

template<class ParticleTraits >
template<class DomainType >
void Particles< ParticleTraits >::destroy ( const DomainType &  dom,
PatchID_t  pid = (-1),
bool  renum = true 
) [inline]

Destroy set of particles specified by DomainType, which may be a 1D Range of particle index numbers or a list of index numbers.

This version does the destroy immediately, instead of deferring it until later. If the patchID is < 0, the domain should be a global domain. If the patchID is >= 0, the domain should be a "local" one, where index = 0 refers to the first particle in that patch. If the final argument is true (the default), the domain is renumbered after the destroy is complete.

template<class ParticleTraits >
template<class Iter >
void Particles< ParticleTraits >::destroy ( Iter  begin,
Iter  end,
PatchID_t  pid = (-1),
bool  renum = true 
) [inline]

Same as above, but use begin/end iterator pair to specify domain.

template<class ParticleTraits >
template<class DomainType >
void Particles< ParticleTraits >::deferredDestroy ( const DomainType &  domain,
PatchID_t  pid = (-1) 
) [inline]

Destroy the particles in the given global domain by storing them a list for use in a later performDestroy call.

This lets you perform several different destroy operations without going through all the shifting-around work until destroys are done. This does NOT renumber the domain. If the patchID is < 0, the domain should be a global domain. If the patchID is >= 0, the domain should be a "local" one, where index = 0 refers to the first particle in that patch.

template<class ParticleTraits >
template<class Iter >
void Particles< ParticleTraits >::deferredDestroy ( Iter  begin,
Iter  end,
PatchID_t  pid = (-1) 
) [inline]

Same as above, but use begin/end iterator pair to specify domain.

template<class ParticleTraits >
void Particles< ParticleTraits >::performDestroy ( PatchID_t  pid = (-1),
bool  renum = true 
)

Carry out all the previously requested destroy commands, and renumber the domain if requested.

If the requested patch ID is < 0, do all deferred destroys, otherwise do it for just the requested patch.

template<class ParticleTraits >
template<class Subject , class Object , class BCType >
void Particles< ParticleTraits >::addBoundaryCondition ( const Subject &  s,
const Object &  o,
const BCType &  bc 
) [inline]

Add a new boundary condition of given type, acting on info from the Subject and affecting values in the Object.

template<class ParticleTraits >
template<class Subject , class BCType >
void Particles< ParticleTraits >::addBoundaryCondition ( const Subject &  s,
const BCType &  bc 
) [inline]

Add a new boundary condition of given type, acting on info from the Subject and affecting values in the same Subject.

template<class ParticleTraits >
void Particles< ParticleTraits >::removeBoundaryCondition ( ParticleBCList::Size_t  i  ) 

Remove the ith boundary condition in this Particles object.

template<class ParticleTraits >
void Particles< ParticleTraits >::removeBoundaryConditions (  ) 

Remove all the boundary conditions.

template<class ParticleTraits >
void Particles< ParticleTraits >::applyBoundaryConditions ( PatchID_t  pid = (-1)  ) 

Apply the boundary conditions to the existing particles for all patches, or just one (if all, the value for the patch ID is < 0).

template<class ParticleTraits >
ParticleBCList::Size_t Particles< ParticleTraits >::boundaryConditions (  )  const [inline]

Return number of boundary conditions.

References ParticleBCList::size().

template<class ParticleTraits >
ParticleBCItem* Particles< ParticleTraits >::boundaryCondition ( ParticleBCList::Size_t  i  )  [inline]

Return the ith boundary condition in the list.

template<class ParticleTraits >
const ParticleBCItem* Particles< ParticleTraits >::boundaryCondition ( ParticleBCList::Size_t  i  )  const [inline]

template<class ParticleTraits >
template<class Out >
void Particles< ParticleTraits >::print ( Out &  o  )  const [inline]


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

Generated on Wed Mar 16 06:20:26 2011 for FreePOOMA by  doxygen 1.5.9