revision: v0.14
Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > Class Template Reference

Contains material and contact force properties. More...

#include <Species.h>

Public Types

typedef MixedSpecies< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpeciesMixedSpeciesType
 The correct MixedSpecies type for this Species. More...
 
typedef Interaction< typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType > InteractionType
 

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

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

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.

dot_inline_dotgraph_7.png

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.

206 {
207  logger(DEBUG, "Species::Species() finished");
208 }

References FATAL, 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]sthe species that is copied
216 {
217  normalForce_ = this;
218  frictionForce_ = this;
219  adhesiveForce_ = this;
220  normalForce_->setBaseSpecies(this);
221  frictionForce_->setBaseSpecies(this);
222  adhesiveForce_->setBaseSpecies(this);
223  logger(DEBUG, "Species::Species(const Species &p) finished");
224 }

References FATAL, and logger.

◆ ~Species()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::~Species
virtual

The default destructor.

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

References DEBUG, and logger.

Member Function Documentation

◆ copy()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies > * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copy
final

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();

243 {
244  return new Species(*this);
245 }

◆ copyInto()

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

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

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 }

References getName(), logger, and WARN.

◆ copyMixed()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
BaseSpecies * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::copyMixed
final

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.

◆ deleteEmptyInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
void Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::deleteEmptyInteraction ( BaseInteraction interaction) const
final

◆ getEmptyInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
BaseInteraction * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getEmptyInteraction
final

◆ getName()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
std::string Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getName
final

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

◆ getNewInteraction()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
BaseInteraction * Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::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.

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

Parameters
[in]Pfirst of the two objects that interact
[in]Isecond of the two objects that interact
[in]timeStampcurrent value of DPMBase::time_
Returns
pointer to the newly created Interaction.
345 {
346  return new InteractionType(P, I, timeStamp);
347 }

◆ getUseAngularDOFs()

template<class NormalForceSpecies , class FrictionForceSpecies , class AdhesiveForceSpecies >
bool Species< NormalForceSpecies, FrictionForceSpecies, AdhesiveForceSpecies >::getUseAngularDOFs
final

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

◆ 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 
)

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]Sthe first of the two species whose properties are mixed to create the new species
[in]Tthe second of the two species whose properties are mixed to create the new species
387 {
388  logger(ERROR, "%::mix() This function should not be called", getName());
389 }

References ERROR, getName(), and logger.

◆ read()

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

Called by SpeciesHandler::readAndAddObject.

Parameters
[in]isinput stream (typically the restart file)
303 {
305  NormalForceSpecies::read(is);
306  FrictionForceSpecies::read(is);
307  AdhesiveForceSpecies::read(is);
308 }

References ParticleSpecies::read().

◆ write()

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

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]osoutput stream (typically the restart file)
291 {
293  NormalForceSpecies::write(os);
294  FrictionForceSpecies::write(os);
295  AdhesiveForceSpecies::write(os);
296 }

References ParticleSpecies::write().


The documentation for this class was generated from the following files:
ParticleSpecies::write
void write(std::ostream &os) const override
Writes the species properties to an output stream.
Definition: ParticleSpecies.cc:76
logger
Logger< MERCURY_LOGLEVEL > logger("MercuryKernel")
Definition of different loggers with certain modules. A user can define its own custom logger here.
Species::getName
std::string getName() const final
Returns the name of the Species as it is used in the restart file.
Definition: Species.h:325
ParticleSpecies
Definition: ParticleSpecies.h:37
NormalForceSpecies
Defines a contact force parallel to the contact normal.
MixedSpecies
Contains contact force properties for contacts between particles with two different species.
Definition: MixedSpecies.h:43
ERROR
LL< Log::ERROR > ERROR
Error log level.
Definition: Logger.cc:53
FrictionForceSpecies
Defines a contact force orthogonal to the contact normal.
Species
Contains material and contact force properties.
Definition: Species.h:35
WARN
LL< Log::WARN > WARN
Warning log level.
Definition: Logger.cc:54
Log::FATAL
@ FATAL
Species::InteractionType
Interaction< typename NormalForceSpecies::InteractionType, typename FrictionForceSpecies::InteractionType, typename AdhesiveForceSpecies::InteractionType > InteractionType
Definition: Species.h:142
Interaction
Contains information about the contact between two interactables, BaseInteraction::P_ and BaseInterac...
Definition: Interaction.h:116
Species::Species
Species()
The default constructor.
Definition: Species.h:204
AdhesiveForceSpecies
Defines a short-range (non-contact) force parallel to the contact normal, usually adhesive.
ParticleSpecies::read
void read(std::istream &is) override
Reads the species properties from an input stream.
Definition: ParticleSpecies.cc:88