Skip to main content

Rocky Solver SDK 2024 R2

IRockyContact Struct Reference

Last update: 08.07.2024

#include <rocky_contact_api.hpp>

Public Member Functions

ROCKY_FUNCTIONS IRockyMaterial get_home_material () const
 
ROCKY_FUNCTIONS IRockyMaterial get_near_material () const
 
ROCKY_FUNCTIONS IRockyMaterialInteraction get_material_interaction () const
 
ROCKY_FUNCTIONS int get_material_interaction_index () const
 
ROCKY_FUNCTIONS IRockyParticle get_home_particle () const
 
ROCKY_FUNCTIONS int get_home_particle_group_index () const
 
ROCKY_FUNCTIONS IRockyParticle get_near_particle () const
 
ROCKY_FUNCTIONS int get_near_particle_group_index () const
 
ROCKY_FUNCTIONS IRockyGeometryTriangle get_near_triangle () const
 
ROCKY_FUNCTIONS int get_near_geometry_index () const
 
ROCKY_FUNCTIONS bool is_particle_particle_contact () const
 
ROCKY_FUNCTIONS bool is_particle_triangle_contact () const
 
ROCKY_FUNCTIONS bool is_frictional () const
 
ROCKY_FUNCTIONS bool is_adhesive () const
 
ROCKY_FUNCTIONS double get_previous_overlap () const
 
ROCKY_FUNCTIONS double get_overlap () const
 
ROCKY_FUNCTIONS double3 get_normal_unit_vector () const
 
ROCKY_FUNCTIONS double3 get_contact_position () const
 
ROCKY_FUNCTIONS double get_scale_factor () const
 
ROCKY_FUNCTIONS bool just_started_frictional () const
 
ROCKY_FUNCTIONS bool just_started_adhesive () const
 
ROCKY_FUNCTIONS bool just_finished_frictional () const
 
ROCKY_FUNCTIONS bool just_finished_adhesive () const
 
ROCKY_FUNCTIONS bool is_loading () const
 
ROCKY_FUNCTIONS bool is_unloading () const
 
ROCKY_FUNCTIONS bool is_positive_oriented () const
 
ROCKY_FUNCTIONS double get_current_time () const
 
ROCKY_FUNCTIONS double get_timestep () const
 
ROCKY_FUNCTIONS IRockyContactScalars get_particle_contact_scalars () const
 
ROCKY_FUNCTIONS IRockyContactScalars get_triangle_contact_scalars () const
 
ROCKY_FUNCTIONS double get_home_stiffness () const
 
ROCKY_FUNCTIONS double get_near_stiffness () const
 
ROCKY_FUNCTIONS double get_equivalent_stiffness () const
 
ROCKY_FUNCTIONS double get_home_stiffness_fraction () const
 
ROCKY_FUNCTIONS double get_reduced_young_modulus () const
 
ROCKY_FUNCTIONS double get_equivalent_mass () const
 
ROCKY_FUNCTIONS double get_equivalent_radius () const
 
ROCKY_FUNCTIONS double get_normal_contact_force () const
 
ROCKY_FUNCTIONS double3 get_tangential_contact_force () const
 
ROCKY_FUNCTIONS double3 calculate_relative_velocity () const
 
ROCKY_FUNCTIONS double get_restitution_coefficient () const
 
ROCKY_FUNCTIONS void set_restitution_coefficient (double value)
 
ROCKY_FUNCTIONS double get_dynamic_friction_coefficient () const
 
ROCKY_FUNCTIONS void set_dynamic_friction_coefficient (double value)
 
ROCKY_FUNCTIONS double get_static_friction_coefficient () const
 
ROCKY_FUNCTIONS void set_static_friction_coefficient (double value)
 
ROCKY_FUNCTIONS double get_sliding_distance () const
 
ROCKY_FUNCTIONS bool get_is_sliding_marker () const
 
ROCKY_FUNCTIONS double get_normal_relative_velocity () const
 
ROCKY_FUNCTIONS double3 get_tangential_relative_velocity () const
 
ROCKY_FUNCTIONS double get_normal_adhesion_force () const
 
ROCKY_FUNCTIONS double3 get_tangential_adhesion_force () const
 
ROCKY_FUNCTIONS double3 get_previous_normal_vector () const
 
ROCKY_FUNCTIONS double3 get_previous_moment_vector () const
 
ROCKY_FUNCTIONS void set_previous_moment_vector (double3 value)
 

Detailed Description

IRockyContact is an interface for the internal contact object in Rocky. A contact object is the code representation of the relationship between two particles or between a particle and a geometry triangle that have a force interaction at a given time. In the first case, it will be a particle-to-particle contact (sometimes abbreviated to particle-contact), whereas in the latter case, it will be a particle-to-triangle contact (sometimes abbreviated to triangle-contact).

A contact in which there exists an actual overlap between the entities is referred to as a frictional contact. If an adhesive model is active, an adhesive force might exist even if the entities are not physically touching each other. In that case, an adhesive contact will be established between those entities.

In a particle-to-particle contact, one of the particles is identified as home particle, whereas the other is identified as near particle. There is no special rule for labeling particles in this type of contacts, any of the two particles can be labeled as home or near. On the other hand, in a particle-to-triangle contact, the particle is always referred to as home particle, while the triangle is referred to as near triangle. Whenever it is necessary to distinguish between two contacting entities, the prefixes home and near are used in the associated method names. The normal unit vector associated to a contact is always constructed pointing to the home particle.

Contact scalars are special variables that store values per contact that are preserved between time iterations. The preservation of those values is guaranteed during the whole lifetime of a contact. Internally, contact scalars are stored separately for particle-to-particle contacts and for particle-to-triangle contacts. In order to differentiate them, the former are named particle contact scalars, whereas the latter are named triangle contact scalars

Member Function Documentation

◆ calculate_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContact::calculate_relative_velocity ( ) const
This method will calculate the relative velocity vector at the contact point.
This relative velocity is defined as the difference between the velocities of points located at the home particle and the near particle or geometry, both coincident instantaneously with the contact point.
Attention
Since this calculation can be costly, modules that need values of this relative velocity may alternatively enable the storage of its normal and tangential components. These components are calculated internally by Rocky during the contact force calculation stage, but discarded afterwards. However, by using the IRockyContactScalarsModel::enable_storage_normal_relative_velocity and IRockyContactScalarsModel::enable_storage_tangential_relative_velocity methods, a module can activate the storage of those components in order to make them available at any point during a time iteration.
Returns
The current relative velocity vector between two contacting particles or a particle and a geometry, at the contact point.

◆ get_contact_position()

ROCKY_FUNCTIONS double3 IRockyContact::get_contact_position ( ) const
Returns
The Cartesian coordinates of the point at which the contact force is applied.

◆ get_current_time()

ROCKY_FUNCTIONS double IRockyContact::get_current_time ( ) const
Returns
The current simulation time.

◆ get_dynamic_friction_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_dynamic_friction_coefficient ( ) const
Returns
The value of the coefficient of dynamic or kinetic friction associated to the contact. If this coefficient is defined as a variable property and its value is specified by a custom module, this method will return that value. Otherwise, it will return the value set through the Rocky UI for the corresponding material interaction.

◆ get_equivalent_mass()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_mass ( ) const
Returns
The value of the equivalent or effective mass for the contact. For more details, please refer to the DEM Technical Manual.

◆ get_equivalent_radius()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_radius ( ) const
Returns
The value of the equivalent or effective radius for the contact. For more details, please refer to the DEM Technical Manual.

◆ get_equivalent_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_equivalent_stiffness ( ) const
Returns
The value of the equivalent stiffness for the contact. The returned value is already multiplied by the numerical softening factor, which is commonly used as a practical way of increasing the simulation timestep. For more details, please refer to the DEM Technical Manual.

◆ get_home_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyContact::get_home_material ( ) const
Returns
An IRockyMaterial object that gives access to the values of physical properties associated to the material from which particle labeled as home is made.

◆ get_home_particle()

ROCKY_FUNCTIONS IRockyParticle IRockyContact::get_home_particle ( ) const
Returns
An IRockyParticle object representing the home particle. This object gives access to several instantaneous properties associated to that particle.

◆ get_home_particle_group_index()

ROCKY_FUNCTIONS int IRockyContact::get_home_particle_group_index ( ) const
Returns
The index that uniquely identifies the particle group to which the home particle belongs.

◆ get_home_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_home_stiffness ( ) const
Returns
The value of the stiffness associated to the home particle. For more details about the definition of this parameter, refer to the DEM Technical Manual. The returned value is already multiplied by the numerical softening factor, which is commonly used as a practical way of increasing the simulation timestep. For more details, please refer to the DEM Technical Manual.

◆ get_home_stiffness_fraction()

ROCKY_FUNCTIONS double IRockyContact::get_home_stiffness_fraction ( ) const
Returns
The fraction of the stiffness of the near entity to the sum of the stiffnesses of both entities in a contact. This fraction is used when splitting the work made by the contact force between the two contacting entities. For more details, please refer to the DEM Technical Manual.

◆ get_is_sliding_marker()

ROCKY_FUNCTIONS bool IRockyContact::get_is_sliding_marker ( ) const
Returns
The value of the sliding marker registered during the most recent calculation of the tangential component of the contact force. This value will be available only if its storage was enabled by using the IRockyContactScalarsModel::enable_storage_is_sliding_marker method. A segmentation fault will occur otherwise.

◆ get_material_interaction()

ROCKY_FUNCTIONS IRockyMaterialInteraction IRockyContact::get_material_interaction ( ) const
Returns
An IRockyMaterialInteraction object that gives access to the values of physical properties associated to the material interaction that corresponds to the contact.

◆ get_material_interaction_index()

ROCKY_FUNCTIONS int IRockyContact::get_material_interaction_index ( ) const
Returns
The internal index of the material interaction associated to the contact. Every pair of materials defined in a project has a unique index associated to it. Both built-in and custom material interactions are stored internally using the same indexes.

◆ get_near_geometry_index()

ROCKY_FUNCTIONS int IRockyContact::get_near_geometry_index ( ) const
Returns
The internal index that uniquely identifies the geometry to which belongs the geometry triangle in a particle-to-triangle contact.

◆ get_near_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyContact::get_near_material ( ) const
Returns
An IRockyMaterial object that gives access to the values of physical properties associated to the material from which the near particle or triangle is made.

◆ get_near_particle()

ROCKY_FUNCTIONS IRockyParticle IRockyContact::get_near_particle ( ) const
Returns
An IRockyParticle object representing the near particle in a particle-to-triangle contact. This object gives access to several instantaneous properties associated to that particle.

◆ get_near_particle_group_index()

ROCKY_FUNCTIONS int IRockyContact::get_near_particle_group_index ( ) const
Returns
The index that uniquely identifies the particle group to which the near particle belongs, in a particle-to-particle contact.

◆ get_near_stiffness()

ROCKY_FUNCTIONS double IRockyContact::get_near_stiffness ( ) const
Returns
The value of the stiffness associated to the near particle or the near triangle, depending on the contact type. The returned value is already multiplied by the numerical softening factor, which is commonly used as a practical way of increasing the simulation timestep. For more details, please refer to the DEM Technical Manual.

◆ get_near_triangle()

ROCKY_FUNCTIONS IRockyGeometryTriangle IRockyContact::get_near_triangle ( ) const
Returns
An IRockyGeometryTriangle object representing the near geometry triangle in a particle-to-triangle contact. This object gives access to some geometric properties associated to that triangle.

◆ get_normal_adhesion_force()

ROCKY_FUNCTIONS double IRockyContact::get_normal_adhesion_force ( ) const
Returns
The value of the normal component of the adhesion force calculated during the last adhesion force calculation stage executed. This value will be available only if its storage was enabled by using the IRockyContactScalarsModel::enable_storage_normal_adhesion_force method. A segmentation fault will occur otherwise.

◆ get_normal_contact_force()

ROCKY_FUNCTIONS double IRockyContact::get_normal_contact_force ( ) const
Returns
The value of the normal component of the contact force, calculated according to the active normal contact force model. Depending on the point from where this function is called, a different force value can be returned. If called from ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS, the returned value will correspond to the normal force component calculated during the previous timestep. On the other hand, if called from ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS, the value will be the recently calculated normal force component for the current timestep. Moreover, this function is not supposed to be called from ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS, since this hook is meant to be used to calculate and set the normal force component for the contact.

◆ get_normal_relative_velocity()

ROCKY_FUNCTIONS double IRockyContact::get_normal_relative_velocity ( ) const
Returns
The value of the normal component of the contact's relative velocity calculated during the last contact force calculation stage executed. This value will be available only if its storage was enabled by using the IRockyContactScalarsModel::enable_storage_normal_relative_velocity method. A segmentation fault will occur otherwise.

◆ get_normal_unit_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_normal_unit_vector ( ) const
Returns
The unit normal vector in Cartesian coordinates. Conventionally, this vector is oriented always pointing to the home particle.

◆ get_overlap()

ROCKY_FUNCTIONS double IRockyContact::get_overlap ( ) const
Returns
The value of the current overlap, which is the small distance that a particle overlaps with another particle or a boundary, measured in the normal direction. In contact models, it is taken as a measurement of the total deformation of the contacting entities at any given time during a collision. Therefore, it is usually the main input parameter for calculating the normal contact force. For adhesive contacts in which physical contact has not been reached yet, this function will return a negative value. In this case, the absolute value of the overlap can be interpreted as the gap between the interacting entities, measured in the direction defined by the normal unit vector. It is common for adhesive forces to be functions of this gap distance.

◆ get_particle_contact_scalars()

ROCKY_FUNCTIONS IRockyContactScalars IRockyContact::get_particle_contact_scalars ( ) const
Returns
An IRockyContactScalars object that gives access to all particle-to-particle contact scalars defined in the project.

◆ get_previous_moment_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_previous_moment_vector ( ) const
Returns
The value the previous rolling resistance moment stored by a custom module that implements a custom rolling resistance model. This moment will be available only if a corresponding scalar was enabled by using the IRockyContactScalarsModel::enable_previous_moment_vector method and the module explicitly stored its value in the previous iteration, by using the IRockyContact::set_previous_moment_vector method.

◆ get_previous_normal_vector()

ROCKY_FUNCTIONS double3 IRockyContact::get_previous_normal_vector ( ) const
Returns
The value of the contact's normal unit vector recorded during the previous time iteration. This value will be available only if its automatic storage was enabled by using the IRockyContactScalarsModel::enable_storage_previous_normal_vector method. A segmentation fault will occur otherwise.

◆ get_previous_overlap()

ROCKY_FUNCTIONS double IRockyContact::get_previous_overlap ( ) const
Returns
The value of the overlap corresponding to the previous timestep.

◆ get_reduced_young_modulus()

ROCKY_FUNCTIONS double IRockyContact::get_reduced_young_modulus ( ) const
Returns
The value of the reduced Young's modulus. This property is usually used in the Hertzian contact model and models derived from it. The returned value is already multiplied by the numerical softening factor, which is commonly used as a practical way of increasing the simulation timestep. For more details, please refer to the DEM Technical Manual.

◆ get_restitution_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_restitution_coefficient ( ) const
Returns
The value of the coefficient of restitution associated to the contact. If the restitution coefficient is a variable property specified by a custom module, this method will return that value. Otherwise, it will return the value set through the Rocky UI for the corresponding material interaction.

◆ get_scale_factor()

ROCKY_FUNCTIONS double IRockyContact::get_scale_factor ( ) const
Returns
The value of the scale factor, which is a reduction factor of the contact force attributed to an individual contact, in cases when multiple contacts points arise simultaneously between two entities. This factor is used also within collision statistics modules for determining the number of collisions based on the number of contacts registered, in cases when each collision has associated multiple contact points.

◆ get_sliding_distance()

ROCKY_FUNCTIONS double IRockyContact::get_sliding_distance ( ) const
Returns
The value of the sliding distance calculated during the most recent simulation timestep. The value of this distance will be available only if its storage was enabled during the setup of the module by using the IRockyContactScalarsModel::enable_storage_sliding_distance method. A segmentation fault will occur otherwise.

◆ get_static_friction_coefficient()

ROCKY_FUNCTIONS double IRockyContact::get_static_friction_coefficient ( ) const
Returns
The value of the coefficient of static friction associated to the contact. If this coefficient is defined as a variable property and its value is specified by a custom module, this method will return that value. Otherwise, it will return the value set through the Rocky UI for the corresponding material interaction.

◆ get_tangential_adhesion_force()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_adhesion_force ( ) const
Returns
The value of the tangential component of the adhesion force calculated during the last adhesion force calculation stage executed. This value will be available only if its storage was enabled by using the IRockyContactScalarsModel::enable_storage_tangential_adhesion_force method. A segmentation fault will occur otherwise.

◆ get_tangential_contact_force()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_contact_force ( ) const
Returns
The tangential component of the contact force as a vector in Cartesian coordinates, calculated according to the active tangential contact force model. Conventionally, the returned tangential force is the one whose orientation coincides with the tangential force acting on the home particle.
If called from ROCKY_PLUGIN_PRE_FORCE_ON_CONTACTS, the returned value will correspond to the tangential force component calculated during the previous timestep. On the other hand, if called from ROCKY_PLUGIN_POST_FORCE_ON_CONTACTS or from other hooks executed after that point, the value will be the recently calculated tangential force component for the current timestep. Moreover, this function is not supposed to be called from ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS, since this hook is meant to be used to calculate and set the tangential force component for the contact. For tangential force models other than the Linear Spring Coulomb Limit and Mindlin-Deresiewicz models, the storage of this force must be enabled explicitly by using the IRockyContactScalarsModel::enable_storage_tangential_contact_force method.

◆ get_tangential_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContact::get_tangential_relative_velocity ( ) const
Returns
The value of the tangential component of the contact's relative velocity calculated during the last contact force calculation stage executed. This value will be available only if its storage was enabled by using the IRockyContactScalarsModel::enable_storage_tangential_relative_velocity method. A segmentation fault will occur otherwise.

◆ get_timestep()

ROCKY_FUNCTIONS double IRockyContact::get_timestep ( ) const
Returns
The magnitude of the simulation timestep.

◆ get_triangle_contact_scalars()

ROCKY_FUNCTIONS IRockyContactScalars IRockyContact::get_triangle_contact_scalars ( ) const
Returns
An IRockyContactScalars object that gives access to all particle-to-triangle contact scalars defined in the project.

◆ is_adhesive()

ROCKY_FUNCTIONS bool IRockyContact::is_adhesive ( ) const
Returns
True if the contact is adhesive, which is the case for all contacts if an adhesive force model is active in the project. The method returns false, otherwise.

◆ is_frictional()

ROCKY_FUNCTIONS bool IRockyContact::is_frictional ( ) const
Returns
True if the contact is frictional, that is, the contacting entities are touching each other. The method returns false, otherwise.

◆ is_loading()

ROCKY_FUNCTIONS bool IRockyContact::is_loading ( ) const
Returns
True if the contact is in a loading period (overlap increasing), false otherwise.

◆ is_particle_particle_contact()

ROCKY_FUNCTIONS bool IRockyContact::is_particle_particle_contact ( ) const
Returns
True if the contact is a particle-to-particle contact, false otherwise.

◆ is_particle_triangle_contact()

ROCKY_FUNCTIONS bool IRockyContact::is_particle_triangle_contact ( ) const
Returns
True if the contact is a particle-to-triangle contact, false otherwise.

◆ is_positive_oriented()

ROCKY_FUNCTIONS bool IRockyContact::is_positive_oriented ( ) const
Returns
True if the topological orientation of the contact coincides with the conventional positive orientation.

◆ is_unloading()

ROCKY_FUNCTIONS bool IRockyContact::is_unloading ( ) const
Returns
True if the contact is in a unloading period (overlap decreasing), false otherwise.

◆ just_finished_adhesive()

ROCKY_FUNCTIONS bool IRockyContact::just_finished_adhesive ( ) const
Returns
True if the contact is adhesive and it has finished (the gap distance between the contacting entities became larger than the adhesive distance) at the current timestep.
Attention
This method will work properly only if called within the ROCKY_PLUGIN_POST_FORCE_ON_FINISHED_CONTACTS hook.

◆ just_finished_frictional()

ROCKY_FUNCTIONS bool IRockyContact::just_finished_frictional ( ) const
Returns
True if the contact is frictional and it has finished (the contacting entities stopped touching each other) at the current timestep.
Attention
This method will work properly only if called within the ROCKY_PLUGIN_POST_FORCE_ON_FINISHED_CONTACTS hook.

◆ just_started_adhesive()

ROCKY_FUNCTIONS bool IRockyContact::just_started_adhesive ( ) const
Returns
True if the contact is adhesive and it has begun at the current timestep, false otherwise.

◆ just_started_frictional()

ROCKY_FUNCTIONS bool IRockyContact::just_started_frictional ( ) const
Returns
True if the contact is frictional and it has begun at the current timestep, false otherwise.

◆ set_dynamic_friction_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_dynamic_friction_coefficient ( double  value)
This method sets the value of the coefficient of dynamic friction at a frictional
contact. It can be used only if that coefficient was defined as a variable property in the module's specification file. It is important to note that the value of this coefficient must be set at the beginning of a contact, before the stage of contact forces calculation. Otherwise, the value set by this method will not be used in that calculation, causing undefined behavior in the collisions.
Parameters
valueThe value of the coefficient of dynamic friction that must be used in the contact.

◆ set_previous_moment_vector()

ROCKY_FUNCTIONS void IRockyContact::set_previous_moment_vector ( double3  value)
This method allows a module implementing a custom rolling resistance model
to store the value of the rolling resistance moment for availability in the next time iteration. It can be used only if the corresponding contact scalar was enabled by using the IRockyContactScalarsModel::enable_previous_moment_vector method. The difference of the contact scalar that stores this moment in relation to a regular contact scalar is that the orientation of the stored vector is always preserved, regardless of possible internal changes in the topology of the contact.
Parameters
valueThe value of the rolling resistance moment just calculated.

◆ set_restitution_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_restitution_coefficient ( double  value)
This method sets the value of the coefficient of restitution for a collision.
It can be used only if the coefficient of restitution was defined as a variable property in the module's specification file. It is important to note that the value of the restitution coefficient must be set at the beginning of a contact, before the stage of contact forces calculation. Otherwise, the value set by this method will not be used in that calculation, causing unphysical behavior in the collisions.
Parameters
valueThe value of the coefficient of restitution that must be used in the contact.

◆ set_static_friction_coefficient()

ROCKY_FUNCTIONS void IRockyContact::set_static_friction_coefficient ( double  value)
This method sets the value of the coefficient of static friction at a frictional contact.
It can be used only if that coefficient was defined as a variable property in the module's specification file. It is important to note that the value of this coefficient must be set at the beginning of a contact, before the stage of contact forces calculation. Otherwise, the value set by this method will not be used in that calculation, causing unphysical behavior in the collisions.
Parameters
valueThe value of the coefficient of static friction that must be used in the contact.