Rocky Solver SDK 2024 R2

IRockyContactOutputData Struct Reference

Last update: 08.07.2024

#include <rocky_contact_output_data_api.hpp>

Public Member Functions

ROCKY_FUNCTIONS void set_normal_force (double value)
 
ROCKY_FUNCTIONS void set_tangential_force (double3 value)
 
ROCKY_FUNCTIONS void set_home_impact_energy (double value)
 
ROCKY_FUNCTIONS void set_near_impact_energy (double value)
 
ROCKY_FUNCTIONS void set_sliding (bool value)
 
ROCKY_FUNCTIONS void set_home_moment (double3 value)
 
ROCKY_FUNCTIONS void set_near_moment (double3 value)
 
ROCKY_FUNCTIONS void set_rolling_dissipated_power (double value)
 
ROCKY_FUNCTIONS double get_normal_force ()
 
ROCKY_FUNCTIONS double3 get_tangential_force ()
 
ROCKY_FUNCTIONS double get_normal_relative_velocity ()
 
ROCKY_FUNCTIONS double3 get_tangential_relative_velocity ()
 

Detailed Description

IRockyContactOutputData is an interface to define some property values related to a contact, which are needed during the calculation steps of a custom contact model. The values defined through this interface can include normal and tangential forces, and impact energy.

Each set method present in this interface is intended to be used at a different calculation step of the contact model:

It is mandatory that the values of the properties above be defined in the respective method. If not defined, the behavior of the particles during the simulation can become indeterminate. Please refer to the individual methods' documentation for further details about each of them.

Member Function Documentation

◆ get_normal_force()

ROCKY_FUNCTIONS double IRockyContactOutputData::get_normal_force ( )
Returns
The normal component of the contact force calculated during the current iteration. This method is intended to be called after the normal force is calculated from the contact model pipeline (ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS in a custom implementation). If called before the moment when the normal force is set for the current contact in the current iteration, the value returned is undetermined.
Attention
Note that the value returned by this method may differ from the value returned by IRockyContact::get_normal_contact_force, as the latter returns the current normal force value in memory, which is usually zero (for new contacts) or the value calculated in the last normal force step for this contact.

◆ get_normal_relative_velocity()

ROCKY_FUNCTIONS double IRockyContactOutputData::get_normal_relative_velocity ( )
Returns
The normal component of the relative velocity at the contact point. This relative velocity is defined as the difference between the absolute velocities of points on the home particle and the near particle or boundary that instantaneously coincide with the contact point.

◆ get_tangential_force()

ROCKY_FUNCTIONS double3 IRockyContactOutputData::get_tangential_force ( )
Returns
The tangential component of the contact force calculated at the current iteration as a vector in Cartesian coordinates. This method is intended to be called after the tangential force calculation step from the contact model pipeline (ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS in a custom implementation). If called before the moment when the tangential force is set for the current contact in the current iteration, the value returned is undetermined.
Attention
Note that the value returned from this method may differ from the value returned by IRockyContact::get_tangential_contact_force, as the latter returns the current tangential force vector in memory, which is usually zero (for new contacts) or the value calculated in the last tangential force step for this contact.

◆ get_tangential_relative_velocity()

ROCKY_FUNCTIONS double3 IRockyContactOutputData::get_tangential_relative_velocity ( )
Returns
The tangential component of the relative velocity at the contact point. This relative velocity is defined as the difference between the absolute velocities of points on the home particle and the near particle or boundary that instantaneously coincide with the contact point.

◆ set_home_impact_energy()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_home_impact_energy ( double  value)
This method must be used if users want to specify an impact energy obtained by means of a
special calculation scheme, different from the one defined in the DEM Technical Manual. The impact energy value specified by this method for the home particle will be used in Rocky for processing instantaneous breakage, energy spectra and collision statistics. In the specific case of instantaneous breakage, Rocky will sum the impact energies from all contacts associated to a particle in order to quantify the damage on the particle. This method is intended to be called from ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS, since this hook is the one designed for calculating and setting the impact energy values. Using it outside this hook can lead to undefined behavior.
Parameters
valueThe impact energy for the home particle just calculated using a custom model.

◆ set_home_moment()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_home_moment ( double3  value)
This method sets the value of the rolling resistance moment that must be applied to the
particle labeled as home particle at a contact. This method is intended to be called from ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS, as this hook is designed specifically to be used by a module implementing a custom rolling resistance model, to calculate and set the rolling resistance moments acting on the particles at a contact. Using this method outside that hook can lead to undefined behavior.
Parameters
valueThe rolling resistance moment vector acting over the home particle.

◆ set_near_impact_energy()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_near_impact_energy ( double  value)
This method must be used if users want to specify an impact energy obtained by means of a
special calculation scheme, different from the one defined in the DEM Technical Manual. The impact energy value specified by this method for the near particle will be used in Rocky for processing instantaneous breakage, energy spectra and collision statistics. In the specific case of instantaneous breakage, Rocky will sum the impact energies from all contacts associated to a particle in order to quantify the damage on the particle. This method is intended to be called from ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS, since this hook is the one designed for calculating and setting the impact energy values. Using it outside this hook can lead to undefined behavior.
Parameters
valueThe impact energy for the near particle just calculated using a custom model.

◆ set_near_moment()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_near_moment ( double3  value)
This method sets the value of the rolling resistance moment that must be applied to the
particle labeled as near particle at a particle-to-particle contact. This method is intended to be called from ROCKY_PLUGIN_ROLLING_RESISTANCE_ON_CONTACTS, as this hook is designed specifically to be used by a module implementing a custom rolling resistance model, to calculate and set the rolling resistance moments acting on the particles at a contact. Using this method outside that hook can lead to undefined behavior.
Parameters
valueThe rolling resistance moment vector acting over the near particle.

◆ set_normal_force()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_normal_force ( double  value)
This method sets the value of the normal component of the contact force calculated by a custom
contact model. Rocky will sum this force to both entities associated to the contact (two particles or a particle and a geometry triangle) using the appropriate signs. This method is intended 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. Using it outside this hook can lead to undefined behavior.
Parameters
valueThe normal component of the contact force just calculated using a custom model.

◆ set_rolling_dissipated_power()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_rolling_dissipated_power ( double  value)
This method sets the value of the instantaneous power dissipated at a contact, due
to the action of the rolling resistance moments calculated by a custom rolling resistance model. The value of this power will be used exclusively by collision statistics and energy spectra modules, if they are active in a simulation. Because of that, the use of this method by a module implementing such a rolling resistance model is optional. If a power value is not provided and the aforementioned statistics modules need it, the Rocky solver will calculate it using a first-order accurate approximation.
Parameters
valueThe instantaneous power dissipated at a contact by rolling resistance.

◆ set_sliding()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_sliding ( bool  value)
This method must be used by a module implementing a custom tangential
contact force model as it specifies whether the particles (or the particle and the triangle) involved in the contact are sliding on each other. This method is intended 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. Using it outside this hook can lead to undefined behavior. Not defining the sliding status of the contact inside the hook can also lead to unexpected results.
Parameters
valueThe sliding status of the contact just calculated using a custom contact model.

◆ set_tangential_force()

ROCKY_FUNCTIONS void IRockyContactOutputData::set_tangential_force ( double3  value)
This method sets the value of the tangential component of the contact force calculated by a
custom contact model. Rocky will sum this force to both entities associated to the contact (two particles or a particle and a geometry triangle) using the appropriate signs. This method is intended 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. Using it outside this hook can lead to undefined behavior.
Parameters
valueThe tangential component of the contact force just calculated using a custom model.

Connect with Ansys