Defines a pair of periodic walls. Inherits from BaseBoundary. More...

#include <PeriodicBoundary.h>

Inheritance diagram for PeriodicBoundary:

Public Member Functions
	PeriodicBoundary ()
	default constructor More...

	~PeriodicBoundary ()
	destructor More...

PeriodicBoundary *	copy () const
	copy method More...

void	set (Vec3D normal, Mdouble distanceLeft, Mdouble distanceRight)
	Defines a periodic wall. More...

void	set (Vec3D normal, Mdouble distanceLeft, Mdouble distanceRight, Vec3D shiftDirection)
	For general parallelogramic domains, the direction of the shift vector can to be set manually. More...

void	moveLeft (Mdouble distanceLeft)
	Sets the distance from the origin of the 'left' periodic wall. More...

void	moveRight (Mdouble distanceRight)
	Sets the distance from the origin of the 'right' periodic wall. 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 More...

void	shiftPositions (Vec3D &postition1, Vec3D &postion2)
	shifts two positions More...

bool	isClosestToLeftBoundary () const
	Returns TRUE if last particle/position checked is closest to the 'left' wall, and FALSE if it is closest to the 'right' wall. More...

void	read (std::istream &is)
	reads boundary properties from istream More...

MERCURY_DEPRECATED void	oldRead (std::istream &is)
	deprecated version of CubeInsertionBoundary::read(). 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...

void	createPeriodicParticles (BaseParticle *p, ParticleHandler &pH)
	Checks distance of particle to closest wall and creates periodic copy if necessary. More...

bool	checkBoundaryAfterParticleMoved (BaseParticle *p, ParticleHandler &pH UNUSED)
	Checks if particle has crossed either boundary wall, and applies a shift if that is the case. NB: ALWAYS returns FALSE. 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...

BoundaryHandler *	getHandler () 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
bool	closestToLeftBoundary_
	true if closest wall is the left wall More...

Vec3D	normal_
	outward unit normal vector for right wall More...

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

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

Mdouble	scaleFactor_
	This is the normal to rescale the normal vector to a unit vectors. More...

Vec3D	shift_
	shift from left to right boundary More...

Detailed Description

Defines a pair of periodic walls. Inherits from BaseBoundary.

The particles are in {x: position_left<=normal*x <position_right}, with normal being the outward unit normal vector of the right wall. If a particle moves outside these boundaries, it will be shifted.

Definition at line 41 of file PeriodicBoundary.h.

Constructor & Destructor Documentation

PeriodicBoundary::PeriodicBoundary ( )

default constructor

constructor

Definition at line 33 of file PeriodicBoundary.cc.

References closestToLeftBoundary_, distanceLeft_, distanceRight_, and scaleFactor_.

Referenced by copy().

         : BaseBoundary()
 {
     closestToLeftBoundary_=true;
     distanceLeft_ = std::numeric_limits<double>::quiet_NaN();
     distanceRight_= std::numeric_limits<double>::quiet_NaN();
     scaleFactor_= std::numeric_limits<double>::quiet_NaN();
 
 #ifdef DEBUG_CONSTRUCTOR
     std::cout<<"PeriodicBoundary::PeriodicBoundary() finished"<<std::endl;
 #endif
 }

PeriodicBoundary::~PeriodicBoundary ( )

destructor

Definition at line 49 of file PeriodicBoundary.cc.

 {
 #ifdef DEBUG_DESTRUCTOR
     std::cout<<"PeriodicBoundary::~PeriodicBoundary() finished"<<std::endl;
 #endif   
 }

Member Function Documentation

bool PeriodicBoundary::checkBoundaryAfterParticleMoved	(	BaseParticle *	p,
		ParticleHandler &pH	UNUSED
	)

Checks if particle has crossed either boundary wall, and applies a shift if that is the case. NB: ALWAYS returns FALSE.

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.

Definition at line 358 of file PeriodicBoundary.cc.

References getDistance(), and shiftPosition().

 {
     if (getDistance(*p) < 0)
     {
         shiftPosition(p);
     }
     return false;
 }

PeriodicBoundary * PeriodicBoundary::copy ( ) const

virtual

copy method

Copy method; creates a copy on the heap and returns its pointer.

Implements BaseBoundary.

Definition at line 59 of file PeriodicBoundary.cc.

References PeriodicBoundary().

 {
     return new PeriodicBoundary(*this);
 }

void PeriodicBoundary::createPeriodicParticles	(	BaseParticle *	p,
		ParticleHandler &	pH
	)

Checks distance of particle to closest wall and creates periodic copy if necessary.

Checks the distance of given particle to the closest of both periodic 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

Definition at line 326 of file PeriodicBoundary.cc.

References ParticleHandler::addObject(), BaseParticle::copy(), BaseInteractable::copyInteractionsForPeriodicParticles(), getDistance(), BaseParticle::getInteractionRadius(), ParticleHandler::getLargestParticle(), BaseParticle::getPeriodicFromParticle(), BaseParticle::setPeriodicFromParticle(), and shiftPosition().

 {
     if (getDistance(*p) < p->getInteractionRadius() + pH.getLargestParticle()->getInteractionRadius())
     {
         //Step 1: Copy the particle to new ghost particle.
         BaseParticle*  pGhost = p->copy();
         
         //Step 2: Copy the interactions of the ghost particle.
         pGhost->copyInteractionsForPeriodicParticles(*p);
 
         //Step 3: Shift the ghost to the 'reflected' location.
         shiftPosition(pGhost);
                 
         //Step 4: If Particle is double shifted, get correct original particle
         BaseParticle* from = p;
         while (from->getPeriodicFromParticle() != nullptr)
             from = from->getPeriodicFromParticle();
         pGhost->setPeriodicFromParticle(from);
         
         pH.addObject(pGhost);
     }
 }

Mdouble PeriodicBoundary::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. Since this function should be called before calculating any Particle-Wall interactions, it can also be used to set the shift vector in case of curved walls.

Parameters

[in] p A reference to the particle which distance to the periodic boundary is calculated

Definition at line 134 of file PeriodicBoundary.cc.

References BaseInteractable::getPosition().

Referenced by checkBoundaryAfterParticleMoved(), and createPeriodicParticles().

 {
     return getDistance(p.getPosition());
 }

Mdouble PeriodicBoundary::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 which distance to the periodic boundary is to be calculated

Definition at line 145 of file PeriodicBoundary.cc.

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

 {
     Mdouble distance = Vec3D::dot(position, normal_);
     
     if (distance - distanceLeft_ < distanceRight_ - distance)
     {
         closestToLeftBoundary_ = true;
         return distance - distanceLeft_;
     }
     else
     {
         closestToLeftBoundary_ = false;
         return distanceRight_ - distance;
     }
 }

std::string PeriodicBoundary::getName ( ) const

virtual

Returns the name of the object.

Returns the name of the object class

Returns: the object's class' name, i.e. 'CubeInsertionBoundary'

Implements BaseObject.

Definition at line 302 of file PeriodicBoundary.cc.

 {
     return "PeriodicBoundary";
 }

bool PeriodicBoundary::isClosestToLeftBoundary ( ) const

Returns TRUE if last particle/position checked is closest to the 'left' wall, and FALSE if it is closest to the 'right' wall.

Definition at line 233 of file PeriodicBoundary.cc.

References closestToLeftBoundary_.

 {
     return closestToLeftBoundary_;
 }

void PeriodicBoundary::moveLeft ( Mdouble distanceLeft )

Sets the distance from the origin of the 'left' periodic wall.

Allows the left periodic boundary to be moved to a new position and automatically changes its shift value

Parameters

[in] distanceLeft The distance (from the origin) to which the left boundary is moved

Definition at line 108 of file PeriodicBoundary.cc.

References distanceLeft_, distanceRight_, normal_, scaleFactor_, and shift_.

 {
     distanceLeft_ = distanceLeft * scaleFactor_;
     shift_ = normal_ * (distanceRight_ - distanceLeft_);
 }

void PeriodicBoundary::moveRight ( Mdouble distanceRight )

Sets the distance from the origin of the 'right' periodic wall.

Allows the right periodic wall to be moved to a new position and automatically changes its shift value

Parameters

[in] distanceRight The distance (from the origin) to which the right boundary is moved

Definition at line 120 of file PeriodicBoundary.cc.

References distanceLeft_, distanceRight_, normal_, scaleFactor_, and shift_.

 {
     distanceRight_ = distanceRight * scaleFactor_;
     shift_ = normal_ * (distanceRight_ - distanceLeft_);
 }

void PeriodicBoundary::oldRead ( std::istream & is )

deprecated version of CubeInsertionBoundary::read().

Deprecated version of read().

Deprecated:: Should be gone by Mercury 2.0. Instead, use CubeInsertionBoundary::read().

Definition at line 274 of file PeriodicBoundary.cc.

References distanceLeft_, distanceRight_, normal_, scaleFactor_, and shift_.

 {
     std::string dummy;
     is >> dummy >> normal_
             >> dummy >> scaleFactor_
             >> dummy >> distanceLeft_
             >> dummy >> distanceRight_
             >> dummy >> shift_;
 }

void PeriodicBoundary::read ( std::istream & is )

virtual

reads boundary properties from istream

Reads the boundary properties from an istream

Parameters

[in] is the istream

Implements BaseBoundary.

Definition at line 259 of file PeriodicBoundary.cc.

References distanceLeft_, distanceRight_, normal_, BaseBoundary::read(), scaleFactor_, and shift_.

 {
     BaseBoundary::read(is);
     std::string dummy;
     is >> dummy >> normal_
             >> dummy >> scaleFactor_
             >> dummy >> distanceLeft_
             >> dummy >> distanceRight_
             >> dummy >> shift_;
 }

void PeriodicBoundary::set	(	Vec3D	normal,
		Mdouble	distanceLeft,
		Mdouble	distanceRight
	)

Defines a periodic wall.

Defines the boundary, given a normal vector such that all particles are within {x: position_left<=normal*x<position_right}. The shift vector is set assuming that the domain is rectangular (shift parallel to normal).

Parameters

[in]	normal	The normal vector pointing from the left wall into the domain
[in]	distanceLeft	The (signed) distance between the left wall and the origin
[in]	distanceRight	The (signed) distance between the right wall and the origin

Definition at line 72 of file PeriodicBoundary.cc.

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

Referenced by BoundaryHandler::readOldObject(), DPMBase::readParAndIniFiles(), ChuteBottom::setupInitialConditions(), and Chute::setupSideWalls().

 {
     // factor is used to set normal to unit length
     scaleFactor_ = 1. / std::sqrt(Vec3D::dot(normal, normal));
     normal_ = normal * scaleFactor_;
     distanceLeft_ = distanceLeft * scaleFactor_;
     distanceRight_ = distanceRight * scaleFactor_;
     shift_ = normal_ * (distanceRight_ - distanceLeft_);
 }

void PeriodicBoundary::set	(	Vec3D	normal,
		Mdouble	distanceLeft,
		Mdouble	distanceRight,
		Vec3D	shiftDirection
	)

For general parallelogramic domains, the direction of the shift vector can to be set manually.

like PeriodicBoundary::set(normal, distanceLeft, distanceRight), but including the possibility of setting the shift direction vector.

Parameters

[in]	normal	The normal vector pointing from the left wall into the domain
[in]	distanceLeft	The (signed) distance between the left wall and the origin
[in]	distanceRight	The (signed) distance between the right wall and the origin
[in]	shiftDirection	The vector over which particles will be shifted when moving through the PeriodicBoundary

Definition at line 91 of file PeriodicBoundary.cc.

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

 {
     // factor is used to set normal to unit length
     scaleFactor_ = 1. / std::sqrt(Vec3D::dot(normal, normal));
     normal_ = normal * scaleFactor_;
     distanceLeft_ = distanceLeft * scaleFactor_;
     distanceRight_ = distanceRight * scaleFactor_;
     // factor is used to set shift vector to correct length
     scaleFactor_ = (distanceRight_ - distanceLeft_) * Vec3D::dot(shiftDirection, normal_);
     shift_ = shiftDirection * scaleFactor_;
 }

void PeriodicBoundary::shiftPosition ( BaseParticle * p )

shifts the particle

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 PeriodicBoundary::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.

Definition at line 178 of file PeriodicBoundary.cc.

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

Referenced by checkBoundaryAfterParticleMoved(), and createPeriodicParticles().

 {
     if (closestToLeftBoundary_)
     {
         p->move(shift_);
         closestToLeftBoundary_ = false;
     }
     else
     {
         p->move(-shift_);
         closestToLeftBoundary_ = true;
     }
 }

void PeriodicBoundary::shiftPositions	(	Vec3D &	position1,
		Vec3D &	position2
	)

shifts two positions

Shifts two given positions by the shift_ vector.

Parameters

[in]	position1	The first position to be shifted
[in]	position2	The second position to be shifted

Todo:: (AT) see toDo of PeriodicBoundary::shiftPosition().

Definition at line 212 of file PeriodicBoundary.cc.

References closestToLeftBoundary_, and shift_.

 {
     if (closestToLeftBoundary_)
     {
         position1 += shift_;
         position2 += shift_;
         closestToLeftBoundary_ = false;
     }
     else
     {
         position1 -= shift_;
         position2 -= shift_;
         closestToLeftBoundary_ = true;
     }
 }

void PeriodicBoundary::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 288 of file PeriodicBoundary.cc.

References distanceLeft_, distanceRight_, normal_, scaleFactor_, shift_, and BaseBoundary::write().

         {
     BaseBoundary::write(os);
     os << " normal " << normal_
             << " scaleFactor " << scaleFactor_
             << " distanceLeft " << distanceLeft_
             << " distanceRight " << distanceRight_
             << " shift " << shift_;
 }