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 override
	copy method More...

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

void	set (Vec3D normal, Vec3D positionLeft, Vec3D positionRight)

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

Vec3D	getNormal () const
	returns the vector normal to the periodic boundary More...

Mdouble	getDistanceLeft () const
	Returns the distance of the left wall to the origin, in normal direction. More...

Mdouble	getDistanceRight () const
	Returns the distance of the right wall to the origin, in normal direction. More...

Vec3D	getShift () const
	Returns the vector going from the left to the right side of the periodic boundary. 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 (const BaseParticle &p) const
	Returns the distance of the wall to the particle. More...

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

void	shiftPosition (BaseParticle *p) const
	shifts the particle More...

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

bool	isClosestToLeftBoundary (const BaseParticle &p) 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...

bool	isClosestToLeftBoundary (const Vec3D &p) const

void	read (std::istream &is) override
	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 override
	writes boundary properties to ostream More...

virtual std::string	getName () const override
	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
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 37 of file PeriodicBoundary.cc.

References DEBUG, distanceLeft_, distanceRight_, logger, scaleFactor_, and WARN.

Referenced by copy().

         : BaseBoundary()
 {
     distanceLeft_ = std::numeric_limits<double>::quiet_NaN();
     distanceRight_ = std::numeric_limits<double>::quiet_NaN();
     scaleFactor_ = std::numeric_limits<double>::quiet_NaN();
 
 #ifdef MERCURY_USE_MPI
     MPIContainer& communicator = MPIContainer::Instance();
     if (communicator.getNumberOfProcessors() > 1)
     {
         logger(WARN,"PeriodicBoundaries are currently not implemented in parallel MercuryDPM");
     }
 #endif
     logger(DEBUG, "PeriodicBoundary::PeriodicBoundary() finished");
     logger(DEBUG, "PeriodicBoundary::PeriodicBoundary() finished");
 }

PeriodicBoundary::~PeriodicBoundary ( )

destructor

Definition at line 58 of file PeriodicBoundary.cc.

References DEBUG, and logger.

 {
     logger(DEBUG, "PeriodicBoundary::~PeriodicBoundary() finished");
 }

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 391 of file PeriodicBoundary.cc.

References getDistance(), and shiftPosition().

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

PeriodicBoundary * PeriodicBoundary::copy ( ) const

overridevirtual

copy method

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

Implements BaseBoundary.

Definition at line 66 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 358 of file PeriodicBoundary.cc.

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

 {
     //note that getDistance sets closestToLeftBoundary_ to true or false depending on which side is closest
     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 ( const BaseParticle & p ) const

Returns the distance of the wall to the particle.

Returns the distance to the closest wall of the boundary 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. Positive means that the particle is insid-> the periodic domain, negative means that it is outsid-> the periodic domain.

Parameters

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

Definition at line 182 of file PeriodicBoundary.cc.

References BaseInteractable::getPosition().

Referenced by checkBoundaryAfterParticleMoved(), DPMBase::checkParticleForInteractionLocalPeriodic(), and createPeriodicParticles().

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

Mdouble PeriodicBoundary::getDistance ( const Vec3D & position ) const

Returns the distance of the wall to the position.

Returns the distance to 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 192 of file PeriodicBoundary.cc.

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

 {
     Mdouble distanceFromPlaneThroughOrigin = Vec3D::dot(position, normal_);
     return std::min(distanceFromPlaneThroughOrigin - distanceLeft_, distanceRight_ - distanceFromPlaneThroughOrigin);
 }

Mdouble PeriodicBoundary::getDistanceLeft ( ) const

Returns the distance of the left wall to the origin, in normal direction.

Returns: The distance of the left wall to the origin, in normal direction

Definition at line 128 of file PeriodicBoundary.cc.

References distanceLeft_.

 {
     return distanceLeft_;
 }

Mdouble PeriodicBoundary::getDistanceRight ( ) const

Returns the distance of the right wall to the origin, in normal direction.

Returns: The distance of the left wall to the origin, in normal direction

Definition at line 136 of file PeriodicBoundary.cc.

References distanceRight_.

 {
     return distanceRight_;
 }

std::string PeriodicBoundary::getName ( ) const

overridevirtual

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 334 of file PeriodicBoundary.cc.

 {
     return "PeriodicBoundary";
 }

Vec3D PeriodicBoundary::getNormal ( ) const

returns the vector normal to the periodic boundary

Returns: The vector perpendicular to the periodic boundary

Definition at line 120 of file PeriodicBoundary.cc.

References normal_.

 {
     return normal_;
 }

Vec3D PeriodicBoundary::getShift ( ) const

Returns the vector going from the left to the right side of the periodic boundary.

Returns: The vector going from the left to the right sid-> of the periodic boundary

Definition at line 144 of file PeriodicBoundary.cc.

References shift_.

 {
     return shift_;
 }

bool PeriodicBoundary::isClosestToLeftBoundary ( const BaseParticle & p ) 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 254 of file PeriodicBoundary.cc.

References BaseInteractable::getPosition().

Referenced by shiftPosition(), and shiftPositions().

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

bool PeriodicBoundary::isClosestToLeftBoundary ( const Vec3D & p ) const

Definition at line 264 of file PeriodicBoundary.cc.

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

 {
     const Mdouble distance = Vec3D::dot(p, normal_);
     return (distanceRight_ - distance > distance - distanceLeft_);
 }

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 155 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 167 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 306 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 )

overridevirtual

reads boundary properties from istream

Reads the boundary properties from an istream

Parameters

[in] is the istream

Implements BaseBoundary.

Definition at line 291 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 79 of file PeriodicBoundary.cc.

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

Referenced by BoundaryHandler::readOldObject(), DPMBase::readParAndIniFiles(), set(), 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_;
     logger.assert_always(distanceRight_ > distanceLeft_,
                          "PeriodicBoundary::set: left distance needs to be smaller than right distance");
     shift_ = normal_ * (distanceRight_ - distanceLeft_);
 }

void PeriodicBoundary::set	(	Vec3D	normal,
		Vec3D	positionLeft,
		Vec3D	positionRight
	)

Definition at line 91 of file PeriodicBoundary.cc.

References Vec3D::dot(), and set().

 {
     set(normal, Vec3D::dot(positionLeft,normal), Vec3D::dot(positionRight,normal));
 }

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 105 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 ) const

shifts the particle

Parameters

[in] p A pointer to the particle which will be shifted.

Shifts the particle either to the left or right, using the method isClosestToLeftBoundary to determine which sid-> it should be shifted to.

Parameters

[in] p A pointer to the particle which will be shifted.

Definition at line 203 of file PeriodicBoundary.cc.

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

Referenced by checkBoundaryAfterParticleMoved(), DPMBase::checkParticleForInteractionLocalPeriodic(), and createPeriodicParticles().

 {
     if (isClosestToLeftBoundary(*p))
     {
         p->move(shift_);
     }
     else
     {
         p->move(-shift_);
     }
 }

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

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 235 of file PeriodicBoundary.cc.

References isClosestToLeftBoundary(), and shift_.

 {
     if (isClosestToLeftBoundary(position1))
     {
         position1 += shift_;
         position2 += shift_;
     }
     else
     {
         position1 -= shift_;
         position2 -= shift_;
     }
 }

void PeriodicBoundary::write ( std::ostream & os ) const

overridevirtual

writes boundary properties to ostream

Writes boundary's properties to an ostream

Parameters

[in] os the ostream

Implements BaseBoundary.

Definition at line 320 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_;
 }