Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > Class Template Reference

Contains material and contact force properties. More...

#include <Species.h>

Inheritance diagram for Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >:

Public Types
typedef MixedSpecies< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >	MixedSpeciesType
	The correct MixedSpecies type for this Species. More...
typedef Interaction< typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType >	InteractionType
Public Types inherited from ParticleSpecies
typedef BaseInteraction	InteractionType
typedef BaseSpecies	MixedSpeciesType
Public Types inherited from EmptyFrictionSpecies
typedef EmptyFrictionInteraction	InteractionType
	The correct Interaction type for this FrictionForceSpecies. More...
Public Types inherited from EmptyAdhesiveSpecies
typedef EmptyAdhesiveInteraction	InteractionType
	The correct Interaction type for this AdhesiveForceSpecies. More...

Public Member Functions
	Species ()
	The default constructor. More...
	Species (const Species &s)
	The default copy constructor. More...
virtual	~Species ()
	The default destructor. More...
Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > *	copy () const final
	Creates a deep copy of the Species from which it is called. More...
void	copyInto (BaseSpecies *bs) const final
BaseSpecies *	copyMixed () const final
	Creates a new MixedSpecies with the same force properties as the Species from which it is called. More...
void	read (std::istream &is) final
	Called by SpeciesHandler::readAndAddObject. More...
void	write (std::ostream &os) const final
	Writes the Species properties to an output stream. More...
std::string	getName () const final
	Returns the name of the Species as it is used in the restart file. More...
BaseInteraction *	getNewInteraction (BaseInteractable *const P, BaseInteractable *const I, unsigned timeStamp) const final
	When a contact between two particles is determined, an Interaction object is created, as the type of Interaction depends on the Species type. More...
BaseInteraction *	getEmptyInteraction () const final
void	deleteEmptyInteraction (BaseInteraction *interaction) const final
bool	getUseAngularDOFs () const final
	Returns true if torques have to be calculated. More...
void	mixAll (BaseSpecies *const S, BaseSpecies *const T) final
	This function should not be called. More...
void	actionsAfterTimeStep (BaseParticle *particle) const final
Public Member Functions inherited from ParticleSpecies
	ParticleSpecies ()
	The default constructor. More...
	ParticleSpecies (const ParticleSpecies &p)
	The default copy constructor. More...
	ParticleSpecies (BaseNormalForce *normalForce, BaseFrictionForce *frictionForce, BaseAdhesiveForce *adhesiveForce)
	~ParticleSpecies ()
	The default destructor. More...
std::string	getBaseName () const
	Used in Species::getName to obtain a unique name for each Species. More...
void	setDensity (Mdouble density)
Mdouble	getMassFromRadius (Mdouble radius) const
Mdouble	getMassFromRadius (const Mdouble radius, SpeciesHandler &speciesHandler)
Mdouble	getVolumeFromRadius (Mdouble radius) const
Mdouble	getDensity () const
	Allows density_ to be accessed. More...
void	computeMass (BaseParticle *p) const
	Compute Particle mass function, which required a reference to the Species vector. It computes the Particles mass, Inertia and the inverses. More...
void	setTemperatureDependentDensity (const std::function< double(double)> &temperatureDependentDensity)
const std::function< double(double)> &	getTemperatureDependentDensity () const
Mdouble	getSmallestParticleMass () const
	Computes mass of the lightest particle (by mass) belonging to this species. This computation calls getLightestInverseParticleMassLocal, such that the computation is done on each node. More...
Mdouble	getMaxInteractionDistance () const
	returns the largest separation distance at which adhesive short-range forces can occur. More...
void	setMaxInteractionDistance (Mdouble interactionDistance=0)
	Sets maxInteractionDistance_. More...
const BaseSpecies *	getMixedSpecies (const ParticleSpecies *s) const
Public Member Functions inherited from BaseSpecies
	BaseSpecies ()
	The default constructor. More...
	BaseSpecies (BaseNormalForce *normalForce, BaseFrictionForce *frictionForce_, BaseAdhesiveForce *adhesiveForce)
	BaseSpecies (const BaseSpecies &p)
	The copy constructor. More...
	~BaseSpecies ()
	The default destructor. More...
void	setHandler (SpeciesHandler *handler)
	Sets the pointer to the handler to which this species belongs. More...
SpeciesHandler *	getHandler () const
	Returns the pointer to the handler to which this species belongs. More...
Mdouble	getInteractionDistance () const
	returns the largest separation distance at which adhesive short-range forces can occur. More...
BaseNormalForce *	getNormalForce () const
BaseFrictionForce *	getFrictionForce () const
BaseAdhesiveForce *	getAdhesiveForce () const
void	setInteractionDistance (Mdouble interactionDistance)
Public Member Functions inherited from BaseObject
	BaseObject ()=default
	Default constructor. More...
	BaseObject (const BaseObject &p)=default
	Copy constructor, copies all the objects BaseObject contains. More...
virtual	~BaseObject ()=default
	virtual destructor More...
virtual void	moveInHandler (unsigned int index)
	Except that it is virtual, it does the same thing as setIndex() does. More...
void	setIndex (unsigned int index)
	Allows one to assign an index to an object in the handler/container. More...
void	setId (unsigned long 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...
void	setGroupId (unsigned groupId)
unsigned	getGroupId () const
Public Member Functions inherited from EmptyFrictionSpecies
	EmptyFrictionSpecies ()
	The default constructor. More...
	EmptyFrictionSpecies (const EmptyFrictionSpecies &s UNUSED)
	The default copy constructor. More...
	~EmptyFrictionSpecies ()
	The default destructor. More...
void	read (std::istream &is)
	Reads the species properties from an input stream. More...
void	write (std::ostream &os) const
	Writes the species properties to an output stream. More...
std::string	getBaseName () const
	Used in Species::getName to obtain a unique name for each Species. More...
void	mix (EmptyFrictionSpecies *S, EmptyFrictionSpecies *T)
	creates default values for mixed species More...
Public Member Functions inherited from BaseForce
BaseSpecies *	getBaseSpecies () const
void	setBaseSpecies (BaseSpecies *baseSpecies)
Public Member Functions inherited from EmptyAdhesiveSpecies
	EmptyAdhesiveSpecies ()
	The default constructor. More...
	EmptyAdhesiveSpecies (const EmptyAdhesiveSpecies &s UNUSED)
	The default copy constructor. More...
	~EmptyAdhesiveSpecies ()
	The default destructor. More...
void	read (std::istream &is)
	Reads the species properties from an input stream. More...
void	write (std::ostream &os) const
	Writes the species properties to an output stream. More...
std::string	getBaseName () const
	Used in Species::getName to obtain a unique name for each Species. More...
void	mix (EmptyAdhesiveSpecies *S, EmptyAdhesiveSpecies *T)
	creates default values for mixed species More...

Additional Inherited Members
Static Public Member Functions inherited from BaseSpecies
static Mdouble	average (Mdouble a, Mdouble b)
	Returns the harmonic mean of two variables. More...
static Mdouble	averageInf (Mdouble a, Mdouble b)
	Returns the harmonic mean of two variables, returning inf if either is inf. More...
Protected Attributes inherited from BaseSpecies
BaseNormalForce *	normalForce_
	A pointer to the normal force parameters \detail This pointer is used by the Interaction's to get a pointer to the species The pointer is set in the constructors of SPecies and MixedSpecies. More...
BaseFrictionForce *	frictionForce_
	A pointer to the friction force parameters \detail This pointer is used by the Interaction's to get a pointer to the species The pointer is set in the constructors of SPecies and MixedSpecies. More...
BaseAdhesiveForce *	adhesiveForce_
	A pointer to the adhesive force parameters \detail This pointer is used by the Interaction's to get a pointer to the species The pointer is set in the constructors of SPecies and MixedSpecies. More...

Detailed Description

template<class NormalForceSpecies, class FrictionForceSpecies = EmptyFrictionSpecies, class AdhesiveForceSpecies = EmptyAdhesiveSpecies>
class Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >

Contains material and contact force properties.

The species class contains both material and contact force properties. As there are many types of contact forces, the class is templated to allow for different force models.

This is done in a diamond inheritance structure: First, four kinds of Species are created:

• ParticleSpecies: Contains material properties like density.
• NormalForceSpecies: Describes the normal contact force, therefore contains properties such as stiffness and dissipation.
• FrictionForceSpecies: Describes the tangential contact force, therefore contains properties such as SlidingFrictionCoefficient and SlidingDissipation.
• AdhesiveForceSpecies: Describes the short-range normal contact force, which are typically adhesive. Therefore, it contains properties such as interactionDistance and adhesiveStiffness. A full Species object is then derived by inheriting from all of the above.

There is only one ParticleSpecies; the three force species can be added using templates. E.g. to create a species with linear elastic-dissipative normal forces, sliding friction forces, and linear reversible short-range adhesion forces, use

Species<LinearViscoelasticNormalSpecies, SlidingFrictionSpecies, LinearReversibleAdhesiveSpecies> species;

EmptyFrictionSpecies and EmptyAdhesiveSpecies are the default template parameters, therefore they don't have to be explicitly named. A species with only linear elastic-dissipative normal forces and sliding friction tangential forces is created using

Species<LinearViscoelasticNormalSpecies, SlidingFrictionSpecies> species;

Also, to avoid that the user has to use templates, many combination of forces are predefined as a typedef, with the names of the force laws concatenated, e.g.

typedef Species<LinearViscoelasticNormalSpecies, SlidingFrictionSpecies> LinearViscoelasticSlidingFrictionSpecies;

Therefore to create such a Species, one has to type

LinearViscoelasticSlidingFrictionSpecies species;

If your code contains multiple Species, then MixedSpecies have to be defined, which contain the description of the forces acting between two species (it does not need a ParticleSpecies, since it is never used to assign mass to an object).
Note, we assume that all Species have to be of the same type when multiple Species are used.

Since these MixedSpecies don't require a set of particle properties (such as density), they are created without a ParticleSpecies. The MixedSpecies is predefined as a typedef inside the Species definition, and can be accessed using

LinearViscoelasticSlidingFrictionSpecies::MixedSpeciesType mixedSpecies;

When a contact between two particles is determined, an Interaction object is created by Species::getNewInteraction, as the type of Interaction depends on the Species type. See Interaction for details.

Member Typedef Documentation

InteractionType

template<class NormalForceSpecies , class FrictionForceSpecies = EmptyFrictionSpecies, class AdhesiveForceSpecies = EmptyAdhesiveSpecies>

typedef Interaction<typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType> Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::InteractionType

MixedSpeciesType

template<class NormalForceSpecies , class FrictionForceSpecies = EmptyFrictionSpecies, class AdhesiveForceSpecies = EmptyAdhesiveSpecies>

typedef MixedSpecies<NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies> Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::MixedSpeciesType

The correct MixedSpecies type for this Species.

The mixed species between two objects of type

Species<NormalForceSpecies,FrictionForceSpecies,AdhesiveForceSpecies>

is

MixedSpecies<NormalForceSpecies,FrictionForceSpecies,AdhesiveForceSpecies>

To access this MixedSpecies type, you can use this typedef.

Constructor & Destructor Documentation

Species() [1/2]

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::Species

The default constructor.

        : ParticleSpecies(this,this,this), NormalForceSpecies(), FrictionForceSpecies(), AdhesiveForceSpecies()
{
    logger(DEBUG, "Species::Species() finished");
}

References DEBUG, and logger.

Species() [2/2]

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::Species

(

const Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > &

s

)

The default copy constructor.

Parameters

[in]

s

the species that is copied

        : ParticleSpecies(s), NormalForceSpecies(s), FrictionForceSpecies(s), AdhesiveForceSpecies(s)
{
    normalForce_ = this;
    frictionForce_ = this;
    adhesiveForce_ = this;
    normalForce_->setBaseSpecies(this);
    frictionForce_->setBaseSpecies(this);
    adhesiveForce_->setBaseSpecies(this);
    logger(DEBUG, "Species::Species(const Species &p) finished");
}

References BaseSpecies::adhesiveForce_, DEBUG, BaseSpecies::frictionForce_, logger, BaseSpecies::normalForce_, and BaseForce::setBaseSpecies().

~Species()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::~Species

virtual

The default destructor.

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

References DEBUG, and logger.

Member Function Documentation

actionsAfterTimeStep()

template<class NormalForceSpecies , class FrictionForceSpecies = EmptyFrictionSpecies, class AdhesiveForceSpecies = EmptyAdhesiveSpecies>

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::actionsAfterTimeStep ( BaseParticle *  particle ) const

inlinefinalvirtual

Reimplemented from ParticleSpecies.

                                                                  {
        NormalForceSpecies::actionsAfterTimeStep(particle);
    }

copy()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copy

finalvirtual

Creates a deep copy of the Species from which it is called.

Creates a deep copy of the Species. As this depends on the template parameters of Species, the definition of this function is in the Species class.

To create a copy of a Species, use

species->copy();

Implements ParticleSpecies.

{
    return new Species(*this);
}

copyInto()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copyInto ( BaseSpecies< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > *  bs ) const

finalvirtual

Copies the content of this into the species bs, if they are of the same type.

Useful for polymorphism: speciesHandler.getObject(i)->copyInto(bs); creates a deep copy (i.e. also copies properties of the derived species), whereas bs = speciesHandler.getObject(i); would only create a shallow copy.

Note: this also copies the index and id. Is that a good idea or not? TW

Implements BaseSpecies.

{
    if (bs == nullptr)
    {
        logger(WARN, "Error in %::copyInto: cannot copy into a nullptr");
        return;
    }
    auto* s = dynamic_cast<Species<NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies>*>(bs);
    if (s == nullptr)
    {
        logger(WARN, "Error in %::copyInto: copying of species failed", getName());
        return;
    }
    *s = *this;
}

References getName(), logger, and WARN.

copyMixed()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

BaseSpecies * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copyMixed

finalvirtual

Creates a new MixedSpecies with the same force properties as the Species from which it is called.

Species copy method. It calls to copy constructor of this Species, useful for polymorphism.

Implements ParticleSpecies.

{
    return new MixedSpecies<NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies>(*this);
}

deleteEmptyInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::deleteEmptyInteraction ( BaseInteraction *  interaction ) const

finalvirtual

Implements BaseSpecies.

{
    Interaction<typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType>* interactionDestroyer;
    interactionDestroyer = dynamic_cast<Interaction<typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType>*>(interaction);
    delete interactionDestroyer;
}

getEmptyInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

BaseInteraction * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getEmptyInteraction

finalvirtual

Implements BaseSpecies.

{
    return new Interaction<typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType>();
}

getName()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

std::string Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getName

finalvirtual

Returns the name of the Species as it is used in the restart file.

Returns the name of the Species as it is used in the restart file. The name of the species is a concatenation of the names of the three force
components, e.g.

Species<LinearViscoelasticNormalSpecies,SlidingFrictionSpecies,ReversibleAdhesiveSpecies> species; std::cout << species.getName();

will output "LinearViscoelasticSlidingFrictionReversibleAdhesiveSpecies". The EmptyFrictionSpecies and the EmptyAdhesiveSpecies return empty strings, such that

Species<LinearViscoelasticNormalSpecies> species; std::cout << species.getName();

will output "LinearViscoelasticSpecies".

Returns

The name of the Species.

Implements BaseObject.

{
    return NormalForceSpecies::getBaseName()
           + FrictionForceSpecies::getBaseName()
           + AdhesiveForceSpecies::getBaseName() + "Species";
}

getNewInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

BaseInteraction * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getNewInteraction ( BaseInteractable *const  P, BaseInteractable *const  I, unsigned  timeStamp  ) const

finalvirtual

When a contact between two particles is determined, an Interaction object is created, as the type of Interaction depends on the Species type.

The input parameters of this function are directly passed into the constructor for the new interaction. See Interaction for details.

Parameters

[in]	P	first of the two objects that interact
[in]	I	second of the two objects that interact
[in]	timeStamp	current value of DPMBase::time_

Returns

pointer to the newly created Interaction.

Implements BaseSpecies.

{
    return new InteractionType(P, I, timeStamp);
}

References Global_Physical_Variables::P.

getUseAngularDOFs()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

bool Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getUseAngularDOFs

finalvirtual

Returns true if torques have to be calculated.

Returns true for any FrictionForceSpecies except EmptyFrictionSpecies, because for spherical particles, torques are only caused by tangential forces. See SpeciesHandler::useAngularDOFs for more details

Returns

true iff torques have to be calculated

Reimplemented from EmptyFrictionSpecies.

{
    return FrictionForceSpecies::getUseAngularDOFs();
}

mixAll()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::mixAll ( BaseSpecies< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > *const S  UNUSED, BaseSpecies< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > *const T  UNUSED  )

finalvirtual

This function should not be called.

This function should not be called as the mix of two Species results in a MixedSpecies, not a Species. However, I don't know how to avoid creating this function, as BaseSpecies pointers are used for the MixedSpecies, so BaseSpecies must have this function defined.

Parameters

[in]	S	the first of the two species whose properties are mixed to create the new species
[in]	T	the second of the two species whose properties are mixed to create the new species

Implements BaseSpecies.

{
    logger(ERROR, "%::mix() This function should not be called", getName());
}

References ERROR, getName(), and logger.

read()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::read ( std::istream &  is )

finalvirtual

Called by SpeciesHandler::readAndAddObject.

Parameters

[in]

is

input stream (typically the restart file)

Reimplemented from ParticleSpecies.

{
    ParticleSpecies::read(is);
    NormalForceSpecies::read(is);
    FrictionForceSpecies::read(is);
    AdhesiveForceSpecies::read(is);
}

References ParticleSpecies::read().

write()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >

void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::write ( std::ostream &  os ) const

finalvirtual

Writes the Species properties to an output stream.

It prints human readable Species information to the output stream, typically to Files::restartFile::fstream_ The basic species information is written in ParticleSpecies::write; then the three force types write additional information to the stream.

Parameters

[out]

os

output stream (typically the restart file)

Reimplemented from ParticleSpecies.

{
    ParticleSpecies::write(os);
    NormalForceSpecies::write(os);
    FrictionForceSpecies::write(os);
    AdhesiveForceSpecies::write(os);
}

References ParticleSpecies::write().

---

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

• Interaction.h
• Species.h