MercuryDPM  Beta
MaserBoundary Class Reference

Variation on the PeriodicBoundary with maser-like properties. More...

#include <MaserBoundary.h>

Inheritance diagram for MaserBoundary:

## Public Member Functions

MaserBoundarycopy () const
Creates a copy on the heap. More...

void set (Vec3D normal, Mdouble distanceLeft, Mdouble distanceRight)
Sets all boundary properties at once. More...

reads boundary properties from istream More...

void write (std::ostream &os) const
writes boundary properties to ostream More...

virtual std::string getName () const
Returns the name of the object. More...

Mdouble getDistance (BaseParticle &p)
Returns the distance of the wall to the particle. More...

Mdouble getDistance (const Vec3D &position)
Returns the distance of the wall to the position. More...

void shiftPosition (BaseParticle *p)
shifts the particle to its 'periodic' position More...

void createPeriodicParticles (BaseParticle *p, ParticleHandler &pH)
Creates periodic particle when the particle is a maser particle and is sufficiently close to one of the boundary walls. More...

bool checkBoundaryAfterParticleMoved (BaseParticle *p, ParticleHandler &pH UNUSED)
Shifts the particle to its 'periodic' position if it is a maser particle and has crossed either of the walls. Creates a 'normal' particle at its current position if it is a maser particle which crossed the RIGHT boundary wall. More...

Converts a 'normal' particle into a maser particle. More...

Public Member Functions inherited from BaseBoundary
BaseBoundary ()
default constructor. More...

BaseBoundary (const BaseBoundary &b)
copy constructor More...

virtual ~BaseBoundary ()
destructor More...

virtual void createPeriodicParticles (BaseParticle *P UNUSED, ParticleHandler &pH UNUSED)
Creates periodic copies of given particle in case of periodic boundaries. More...

virtual bool checkBoundaryAfterParticleMoved (BaseParticle *P UNUSED, ParticleHandler &pH UNUSED)
Checks if given particle passed the boundary. More...

virtual void checkBoundaryBeforeTimeStep (DPMBase *md UNUSED)
Fills a (3D) boundary with particles. More...

void setHandler (BoundaryHandler *handler)
Sets the boundary's BoundaryHandler. More...

BoundaryHandlergetHandler () const
Returns the boundary's BoundaryHandler. More...

Public Member Functions inherited from BaseObject
BaseObject ()
Default constructor. More...

BaseObject (const BaseObject &p)
Copy constructor, copies all the objects BaseObject contains. More...

virtual ~BaseObject ()
virtual destructor More...

virtual void moveInHandler (const unsigned int index)
Except that it is virtual, it does the same thing as setIndex() does. More...

void setIndex (const unsigned int index)
Allows one to assign an index to an object in the handler/container. More...

void setId (const unsigned int id)
Assigns a unique identifier to each object in the handler (container) which remains constant even after the object is deleted from the container/handler. More...

unsigned int getIndex () const
Returns the index of the object in the handler. More...

unsigned int getId () const
Returns the unique identifier of any particular object. More...

## Private Attributes

Vec3D normal_
Normal unit vector of both maser walls. Points in the flowing direction. More...

Mdouble distanceLeft_
position of left boundary wall, s.t. normal*x=position_left More...

Mdouble distanceRight_
position of right boundary wall, s.t. normal*x=position_right More...

bool closestToLeftBoundary_
Dummy variable used when checking the proximity of particles to the boundary walls. TRUE if closest wall is the left boundary wall. More...

Vec3D shift_
Direction in which particles are to be shifted when they cross the boundary. More...

std::map< const
ParticleSpecies *, const
ParticleSpecies * >
speciesConversionNormalToMaser_
List of 'normal' particles' species, and their maser counterparts. More...

std::map< const
ParticleSpecies *, const
ParticleSpecies * >
speciesConversionMaserToNormal_
List of 'maser' particles' species, and their normal counterparts. More...

## Detailed Description

Variation on the PeriodicBoundary with maser-like properties.

Creates a boundary which is similar to a PeriodicBoundary, except that particles which leave

Definition at line 44 of file MaserBoundary.h.

## Member Function Documentation

 void MaserBoundary::addParticleToMaser ( BaseParticle * P )

Converts a 'normal' particle into a maser particle.

Turns given particle into a 'maser particle' by changing its species into a 'maser particle' copy species. If the particle species is not yet in the std::map speciesConversionNormalToMaser_, it and its maser copy species are added. This function should be called at the beginning of the simulation, right after actually filling the maser with particles, flagging each particle as one belonging to the maser.

Parameters
 [in,out] P The particle which is added to the maser. Its species is 'changed' to the maser copy species.

Definition at line 277 of file MaserBoundary.cc.

278 {
279  // check if particle species already known by the maser
280  auto conversion = speciesConversionNormalToMaser_.find(P->getSpecies());
281  if (conversion == speciesConversionNormalToMaser_.end())
282  {
283  // nope: species has to be added to the list
285  speciesConversionNormalToMaser_.insert(std::pair<const ParticleSpecies*, const ParticleSpecies*>(P->getSpecies(), newSpecies));
286  speciesConversionMaserToNormal_.insert(std::pair<const ParticleSpecies*, const ParticleSpecies*>(newSpecies, P->getSpecies()));
287  logger(INFO,"[MaserBoundary::addParticleToMaser()] New species conversion created");
288
289  // now the species IS added, so flag (convert) it!
290  P->setSpecies(newSpecies);
291  }
292  else
293  {
294  // yep: species known and flagged (i.e. 'converted')
296  P->setSpecies(conversion->second);
297  }
298 }
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
const ParticleSpecies * getSpecies() const
Returns a pointer to the species of this BaseInteractable.
void setSpecies(const ParticleSpecies *species)
Creates a copy of a Object and adds it to the BaseHandler.
Definition: BaseHandler.h:268
std::map< const ParticleSpecies *, const ParticleSpecies * > speciesConversionNormalToMaser_
List of 'normal' particles' species, and their maser counterparts.
std::map< const ParticleSpecies *, const ParticleSpecies * > speciesConversionMaserToNormal_
List of 'maser' particles' species, and their normal counterparts.
BoundaryHandler * getHandler() const
Returns the boundary's BoundaryHandler.
SpeciesHandler speciesHandler
A handler to that stores the species type i.e. elastic, linear visco-elastic... et cetera...
Definition: DPMBase.h:868
DPMBase * getDPMBase()
Gets the problem that is solved using this handler.
Definition: BaseHandler.h:512
virtual ParticleSpecies * copy() const =0
Creates a deep copy of the object from which it is called.
 bool MaserBoundary::checkBoundaryAfterParticleMoved ( BaseParticle * P, ParticleHandler &pH UNUSED )

Shifts the particle to its 'periodic' position if it is a maser particle and has crossed either of the walls. Creates a 'normal' particle at its current position if it is a maser particle which crossed the RIGHT boundary wall.

Checks whether given particle has crossed the closest wall, and if so, shifts its position so as to have it appear at the other wall

Parameters
 [in] p The particle to be checked and possibly shifted pH The ParticleHandler, which is unused in this implementation
Returns
ALWAYS returns FALSE for periodic boundaries. Only returns TRUE when particle gets actually deleted, e.g. in certain DeletionBoundary implementations.
Todo:

Apparently, somewhere in the ages past, at some time, there has existed a piece of code which prevents the particles crossing the periodic boundary on the left side from reappearing on the right. This was taken out somewhere between the dark ages an the current one (feb. 2015) and should be put back in. Only causes errors very rarely, and not in the compiler but rather in the actual physics going on (So its not detected by the MaserSelfTest). The current arrangement mainly causes problems with particles which oscillate on the boundary, continuously crossing from left to right and back. A visual consideration of this problem can be found in Documentation/Images/Maser_unperiodic_behaviour.jpg, which, granted, is appalling in its own right, but has yet to suffice in awaitance of a better (i.e. clearer) drawing. Therefore:

Create a new diagram explaining the problems with the previous (NOW: CURRENT!) implementation, and the exact differences between the two. I.e., an improved version of Documentation/Images/Maser_unperiodic_behaviour.jpg. (BvdH)

Definition at line 235 of file MaserBoundary.cc.

236 {
237  // check if particle passed either of the boundary walls
238  if (getDistance(*P) < 0)
239  {
240  // check if species is found in the list of maser particle species
241  auto conversion = speciesConversionMaserToNormal_.find(P->getSpecies());
242  if (conversion != speciesConversionMaserToNormal_.end()) //Test if it is a maser particle
243  {
244  // yes: shift it periodically!
245  shiftPosition(P);
246
247  /*
248  // check if to be shifted leftward or rightward. Now done by MaserBoundary::shiftPosition().
249  if (closestToLeftBoundary_)
250  {
251  P->move(shift_);
252  closestToLeftBoundary_ = false;
253  }
254  else
255  {
256  P->move(-shift_);
257  closestToLeftBoundary_ = true;
259  //pCopy->setIndSpecies(conversion->second);
260  }
261  */
262  }
263  }
264  return false;
265 }
Mdouble getDistance(BaseParticle &p)
Returns the distance of the wall to the particle.
const ParticleSpecies * getSpecies() const
Returns a pointer to the species of this BaseInteractable.
void shiftPosition(BaseParticle *p)
shifts the particle to its 'periodic' position
std::map< const ParticleSpecies *, const ParticleSpecies * > speciesConversionMaserToNormal_
List of 'maser' particles' species, and their normal counterparts.
 MaserBoundary * MaserBoundary::copy ( ) const
virtual

Creates a copy on the heap.

Copy method, creates a copy of the object on the heap and returns a pointer to it.

Returns
pointer to the copy

Implements BaseBoundary.

Definition at line 40 of file MaserBoundary.cc.

41 {
42  return new MaserBoundary(*this);
43 }
Variation on the PeriodicBoundary with maser-like properties.
Definition: MaserBoundary.h:44
 void MaserBoundary::createPeriodicParticles ( BaseParticle * P, ParticleHandler & pH )

Creates periodic particle when the particle is a maser particle and is sufficiently close to one of the boundary walls.

Checks the distance of given particle to the closest of both walls, and creates a periodic copy of the particle if needed (i.e. if the particle is closer to the periodic wall than the radius of the largest particle in the system).

Parameters
 [in] P Particle to be checked and possibly periodically copied [in,out] pH System's ParticleHandler, (1) from which the interaction radius of its largest particle is retrieved to determine the maximum distance from the wall at which a particle should still have a periodic copy created, and (2) to which a possible periodic copy of the particle will be added
Todo:
The code has not implemented the actual outflow of 'normal' particles from the right boundary wall. I.e., the maser now is 'simply' a normal Periodic Boundary, with a lot of potential ;). I think the 'original author' planned to implement the outflow below, which is still left to be done. (BvdH) NB: a better place would be in the MaserBoundary::shiftPosition() or MaserBoundary::checkBoundaryAfterParticleMoved() method, which are called when the particles actually cross either of the boundary walls.

Definition at line 164 of file MaserBoundary.cc.

165 {
166  // check if particle is close to either of the boundary walls
168  {
169  auto conversion = speciesConversionMaserToNormal_.find(P->getSpecies());
170  if (conversion != speciesConversionMaserToNormal_.end()) //Test if it is a maser particle
171  {
172  // Copy the particle if it IS a maser particle
173  BaseParticle* F0 = P->copy();
175
176  // shift to the periodic location
177  shiftPosition(F0);
178
179  //Set the 'from' particle. If Particle is multiply shifted, get correct original particle
180  BaseParticle* From = P;
181  while (From->getPeriodicFromParticle() != nullptr)
182  {
183  From = From->getPeriodicFromParticle();
184  }
185  F0->setPeriodicFromParticle(From);
186
187  // add the periodic particle to the handler
189
202  {
203  }
204  else
205  {
206  }
207  }
208  }
209 }
BaseParticle * getLargestParticle() const
Gets a pointer to the largest BaseParticle (by interactionRadius) in this ParticleHandler.
Mdouble getDistance(BaseParticle &p)
Returns the distance of the wall to the particle.
const ParticleSpecies * getSpecies() const
Returns a pointer to the species of this BaseInteractable.
void setPeriodicFromParticle(BaseParticle *p)
Assigns the pointer to the 'original' particle this one's a periodic copy of.
BaseParticle * getPeriodicFromParticle() const
Returns the 'original' particle this one's a periodic copy of.
void shiftPosition(BaseParticle *p)
shifts the particle to its 'periodic' position
Adds a BaseParticle to the ParticleHandler.
std::map< const ParticleSpecies *, const ParticleSpecies * > speciesConversionMaserToNormal_
List of 'maser' particles' species, and their normal counterparts.
void copyInteractionsForPeriodicParticles(const BaseInteractable &p)
Copies interactions to this BaseInteractable whenever a periodic copy made.
bool closestToLeftBoundary_
Dummy variable used when checking the proximity of particles to the boundary walls. TRUE if closest wall is the left boundary wall.
Returns the particle's interaction radius, which might be different from radius_ (e.g., when dealing with wet particles)
virtual BaseParticle * copy() const
Particle copy method. It calls to copy constructor of this Particle, useful for polymorfism.
 Mdouble MaserBoundary::getDistance ( BaseParticle & p )

Returns the distance of the wall to the particle.

Returns the distance to the closest wall of the boundary to the particle, , and sets closestToLeftBoundary_ = true if the left wall is the wall closest to the particle.

Parameters
 [in] p A reference to the particle of which the distance to the boundary wall is to be calculated

Definition at line 93 of file MaserBoundary.cc.

References BaseInteractable::getPosition().

Referenced by checkBoundaryAfterParticleMoved(), and createPeriodicParticles().

94 {
95  return getDistance(p.getPosition());
96 }
Mdouble getDistance(BaseParticle &p)
Returns the distance of the wall to the particle.
const Vec3D & getPosition() const
Returns the position of this BaseInteractable.
 Mdouble MaserBoundary::getDistance ( const Vec3D & position )

Returns the distance of the wall to the position.

Returns the distance to the wall closest to the position, and sets closestToLeftBoundary_ = true if the left wall is the wall closest to the position.

Parameters
 [in] position (A reference to) the position of which the distance to the boundary wall is to be calculated

Definition at line 104 of file MaserBoundary.cc.

References closestToLeftBoundary_, distanceLeft_, distanceRight_, Vec3D::dot(), and normal_.

105 {
106  Mdouble distance = Vec3D::dot(position, normal_);
107
108  if (distance - distanceLeft_ < distanceRight_ - distance)
109  {
110  closestToLeftBoundary_ = true;
111  return distance - distanceLeft_;
112  }
113  else
114  {
115  closestToLeftBoundary_ = false;
116  return distanceRight_ - distance;
117  }
118 }
Mdouble distanceLeft_
position of left boundary wall, s.t. normal*x=position_left
Vec3D normal_
Normal unit vector of both maser walls. Points in the flowing direction.
double Mdouble
static Mdouble dot(const Vec3D &a, const Vec3D &b)
Calculates the dot product of two Vec3D: .
Definition: Vector.cc:187
Mdouble distanceRight_
position of right boundary wall, s.t. normal*x=position_right
bool closestToLeftBoundary_
Dummy variable used when checking the proximity of particles to the boundary walls. TRUE if closest wall is the left boundary wall.
 std::string MaserBoundary::getName ( ) const
virtual

Returns the name of the object.

Returns the name of the object class

Returns
the object's class' name, i.e. 'MaserBoundary'

Implements BaseObject.

Definition at line 82 of file MaserBoundary.cc.

83 {
84  return "MaserBoundary";
85 }
 void MaserBoundary::read ( std::istream & is )
virtual

Reads the boundary properties from an istream

Parameters
 [in,out] is the istream

Implements BaseBoundary.

Definition at line 64 of file MaserBoundary.cc.

65 {
67 }
Reads the object's id_ from given istream NB: purely virtual function.
Definition: BaseBoundary.cc:67
 void MaserBoundary::set ( Vec3D normal, Mdouble distanceLeft, Mdouble distanceRight )

Sets all boundary properties at once.

Set all the properties of the boundary at once.

Parameters
 [in] normal Normal unit vector of the (parallel) boundary walls [in] distanceLeft The distance of the left wall to the origin [in] distanceRight The distance of the right wall to the origin

Definition at line 51 of file MaserBoundary.cc.

References distanceLeft_, distanceRight_, normal_, and shift_.

52 {
53  // factor is used to set normal to unit length
54  normal_ = normal;
55  distanceLeft_ = distanceLeft;
56  distanceRight_ = distanceRight;
58 }
Mdouble distanceLeft_
position of left boundary wall, s.t. normal*x=position_left
Vec3D normal_
Normal unit vector of both maser walls. Points in the flowing direction.
Mdouble distanceRight_
position of right boundary wall, s.t. normal*x=position_right
Vec3D shift_
Direction in which particles are to be shifted when they cross the boundary.
 void MaserBoundary::shiftPosition ( BaseParticle * p )

shifts the particle to its 'periodic' position

Shifts the particle (using the closestToLeftBoundary_ value)

Parameters
 [in] p A pointer to the particle which will be shifted.
Todo:
Reconsider the way in which the shifting of particles is done. Now, the procedure is as follows: > PARTICLE's distance to either of the two walls is gotten by MaserBoundary::getDistance > Which of the two walls the particle is closest to, is saved in the BOUNDARY's boolean data member closestToLeftBoundary_ > PARTICLE's position is then shifted based on the BOUNDARY's closestToLeftBoundary_ data member and shift vector What might go wrong, is that it is allowed now to do a shift operation on the particle without being forced to first have the closestToLeftBoundary_ boolean set based on the same particle. Suggestion: get rid of the closestToLeftBoundary_ data member all together (it is a property of the particle after all, rather than one of the boundary), and implement the obtaining of which boundary to shift relatively to directly into the shift function. (NB: The PeriodicBoundary class contains the same TODO).

Definition at line 138 of file MaserBoundary.cc.

References closestToLeftBoundary_, BaseInteractable::move(), and shift_.

Referenced by checkBoundaryAfterParticleMoved(), and createPeriodicParticles().

139 {
141  {
142  p->move(shift_);
143  closestToLeftBoundary_ = false;
144  }
145  else
146  {
147  p->move(-shift_);
148  closestToLeftBoundary_ = true;
149  }
150 }
bool closestToLeftBoundary_
Dummy variable used when checking the proximity of particles to the boundary walls. TRUE if closest wall is the left boundary wall.
virtual void move(const Vec3D &move)
Moves this BaseInteractable by adding an amount to the position.
Vec3D shift_
Direction in which particles are to be shifted when they cross the boundary.
 void MaserBoundary::write ( std::ostream & os ) const
virtual

writes boundary properties to ostream

Writes boundary's properties to an ostream

Parameters
 [in] os the ostream

Implements BaseBoundary.

Definition at line 73 of file MaserBoundary.cc.

References BaseBoundary::write().

74 {
76 }
void write(std::ostream &os) const =0
Adds object's id_ to given ostream NB: purely virtual function.
Definition: BaseBoundary.cc:76

## Member Data Documentation

 bool MaserBoundary::closestToLeftBoundary_
private

Dummy variable used when checking the proximity of particles to the boundary walls. TRUE if closest wall is the left boundary wall.

Definition at line 122 of file MaserBoundary.h.

Referenced by createPeriodicParticles(), getDistance(), and shiftPosition().

 Mdouble MaserBoundary::distanceLeft_
private

position of left boundary wall, s.t. normal*x=position_left

Definition at line 113 of file MaserBoundary.h.

Referenced by getDistance(), and set().

 Mdouble MaserBoundary::distanceRight_
private

position of right boundary wall, s.t. normal*x=position_right

Definition at line 117 of file MaserBoundary.h.

Referenced by getDistance(), and set().

 Vec3D MaserBoundary::normal_
private

Normal unit vector of both maser walls. Points in the flowing direction.

Definition at line 109 of file MaserBoundary.h.

Referenced by getDistance(), and set().

 Vec3D MaserBoundary::shift_
private

Direction in which particles are to be shifted when they cross the boundary.

I.e., the vector pointing from a point the left boundary wall to the equivalent point on the right one.

Definition at line 128 of file MaserBoundary.h.

Referenced by set(), and shiftPosition().

 std::map MaserBoundary::speciesConversionMaserToNormal_
private

List of 'maser' particles' species, and their normal counterparts.

Definition at line 138 of file MaserBoundary.h.

Referenced by addParticleToMaser(), checkBoundaryAfterParticleMoved(), and createPeriodicParticles().

 std::map MaserBoundary::speciesConversionNormalToMaser_
private

List of 'normal' particles' species, and their maser counterparts.

Definition at line 133 of file MaserBoundary.h.