MercuryDPM  Trunk
Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > Class Template Reference

Contains material and contact force properties. More...

#include <Interaction.h>

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

## Public Types

typedef MixedSpecies
< NormalForceSpecies,
FrictionForceSpecies,
MixedSpeciesType
The correct MixedSpecies type for this Species. More...

typedef Interaction< typename
NormalForceSpecies::InteractionType,
typename
FrictionForceSpecies::InteractionType,
typename
InteractionType

Public Types inherited from ParticleSpecies
typedef BaseInteraction InteractionType

typedef BaseSpecies MixedSpeciesType

## 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,
copy () const final
Creates a deep copy of the Species from which it is called. More...

void copyInto (BaseSpecies *bs) const final

BaseSpeciescopyMixed () const final
Creates a new MixedSpecies with the same force properties as the Species from which it is called. 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...

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

BaseInteractiongetEmptyInteraction () 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)
This function should not be called. More...

Public Member Functions inherited from ParticleSpecies
ParticleSpecies ()
The default constructor. More...

ParticleSpecies (const ParticleSpecies &p)
The default copy constructor. More...

~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)
Allows density_ to be changed. More...

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 BaseSpeciesgetMixedSpecies (const ParticleSpecies *s) const

Public Member Functions inherited from BaseSpecies
BaseSpecies ()
The default constructor. More...

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

SpeciesHandlergetHandler () 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...

BaseNormalForcegetNormalForce () const

BaseFrictionForcegetFrictionForce () const

void setInteractionDistance (Mdouble interactionDistance)
Sets BaseSpecies::interactionDistance_. More...

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

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
BaseNormalForcenormalForce_
A pointer to the normal force parameters 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...

BaseFrictionForcefrictionForce_
A pointer to the friction force parameters 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...

A pointer to the adhesive force parameters 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, class AdhesiveForceSpecies> 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

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

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.

Definition at line 42 of file Interaction.h.

## Member Typedef Documentation

template<class NormalForceSpecies, class FrictionForceSpecies, class AdhesiveForceSpecies>
 typedef Interaction Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::InteractionType

Definition at line 142 of file Species.h.

template<class NormalForceSpecies, class FrictionForceSpecies, class AdhesiveForceSpecies>

The correct MixedSpecies type for this Species.

The mixed species between two objects of type

is

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

Definition at line 141 of file Species.h.

## Constructor & Destructor Documentation

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::Species ( )

The default constructor.

Definition at line 204 of file Species.h.

References DEBUG, and logger.

206 {
207  logger(DEBUG, "Species::Species() finished");
208 }
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
Defines a contact force orthogonal to the contact normal.
Defines a contact force parallel to the contact normal.
Defines a short-range (non-contact) force parallel to the contact normal, usually adhesive...
ParticleSpecies()
The default constructor.
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

Definition at line 214 of file Species.h.

216 {
217  normalForce_ = this;
218  frictionForce_ = this;
223  logger(DEBUG, "Species::Species(const Species &p) finished");
224 }
void setBaseSpecies(BaseSpecies *baseSpecies)
Definition: BaseForce.h:40
BaseNormalForce * normalForce_
A pointer to the normal force parameters This pointer is used by the Interaction's to get a pointer ...
Definition: BaseSpecies.h:173
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
Defines a contact force orthogonal to the contact normal.
Defines a contact force parallel to the contact normal.
A pointer to the adhesive force parameters This pointer is used by the Interaction's to get a pointe...
Definition: BaseSpecies.h:187
Defines a short-range (non-contact) force parallel to the contact normal, usually adhesive...
ParticleSpecies()
The default constructor.
BaseFrictionForce * frictionForce_
A pointer to the friction force parameters This pointer is used by the Interaction's to get a pointe...
Definition: BaseSpecies.h:180
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::~Species ( )
virtual

The default destructor.

Definition at line 227 of file Species.h.

References DEBUG, and logger.

228 {
229  logger(DEBUG, "Species::~Species() finished");
230 }
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")

## Member Function Documentation

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copy ( ) const
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.

Definition at line 242 of file Species.h.

243 {
244  return new Species(*this);
245 }
Species()
The default constructor.
Definition: Species.h:204
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.

Definition at line 266 of file Species.h.

References getName(), logger, and WARN.

267 {
268  if (bs == nullptr)
269  {
270  logger(WARN, "Error in %::copyInto: cannot copy into a nullptr");
271  return;
272  }
274  if (s == nullptr)
275  {
276  logger(WARN, "Error in %::copyInto: copying of % failed", getName(), s->getName());
277  return;
278  }
279  *s = *this;
280 }
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
std::string getName() const final
Returns the name of the Species as it is used in the restart file.
Definition: Species.h:325
Contains material and contact force properties.
Definition: Interaction.h:42
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 BaseSpecies * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copyMixed ( ) const
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.

Definition at line 250 of file Species.h.

251 {
253 }
Contains contact force properties for contacts between particles with two different species...
Definition: MixedSpecies.h:42
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::deleteEmptyInteraction ( BaseInteraction * interaction ) const
finalvirtual

Implements BaseSpecies.

Definition at line 356 of file Species.h.

358 {
361  delete interactionDestroyer;
362 }
Contains information about the contact between two interactables, BaseInteraction::P_ and BaseInterac...
Definition: Interaction.h:115
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 BaseInteraction * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getEmptyInteraction ( ) const
finalvirtual

Implements BaseSpecies.

Definition at line 350 of file Species.h.

351 {
353 }
Contains information about the contact between two interactables, BaseInteraction::P_ and BaseInterac...
Definition: Interaction.h:115
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 std::string Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getName ( ) const
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.

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.

Definition at line 325 of file Species.h.

326 {
327  return NormalForceSpecies::getBaseName()
328  + FrictionForceSpecies::getBaseName()
330 }
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.

Definition at line 342 of file Species.h.

345 {
346  return new InteractionType(P, I, timeStamp);
347 }
Interaction< typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType > InteractionType
Definition: Species.h:142
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
 bool Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getUseAngularDOFs ( ) const
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

Implements BaseSpecies.

Definition at line 371 of file Species.h.

372 {
373  return FrictionForceSpecies::getUseAngularDOFs();
374 }
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 )
virtual

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.

Definition at line 385 of file Species.h.

References ERROR, getName(), and logger.

387 {
388  logger(ERROR, "%::mix() This function should not be called", getName());
389 }
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
std::string getName() const final
Returns the name of the Species as it is used in the restart file.
Definition: Species.h:325
template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
finalvirtual

Parameters
 [in] is input stream (typically the restart file)

Reimplemented from ParticleSpecies.

Definition at line 302 of file Species.h.

303 {
308 }
Reads the species properties from an input stream.
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.

Definition at line 290 of file Species.h.

References ParticleSpecies::write().

291 {
293  NormalForceSpecies::write(os);
294  FrictionForceSpecies::write(os);