## On this page

  

 

 # IRockyContactOutputData Struct Reference

 Last update: 17.07.2025 

`#include <<a class="el" href="rocky__contact__output__data__api_8hpp_source.xhtml">rocky_contact_output_data_api.hpp</a>>`

## <a id="pub-methods" name="pub-methods"></a>Public Member Functions

ROCKY\_FUNCTIONS void [set\_normal\_force](structIRockyContactOutputData.xhtml#a396b63164b3e2d7792bca3c7ba1ae274) (double value) ROCKY\_FUNCTIONS void [set\_tangential\_force](structIRockyContactOutputData.xhtml#abaf1043a614caad9555e2c909eb21e12) (double3 value) ROCKY\_FUNCTIONS void [set\_home\_impact\_energy](structIRockyContactOutputData.xhtml#a6fa45c11ca5a3dc0e2e7ba76cceca590) (double value) ROCKY\_FUNCTIONS void [set\_near\_impact\_energy](structIRockyContactOutputData.xhtml#afaf9777156ccff17bad6b754bd9ec0e2) (double value) ROCKY\_FUNCTIONS void [set\_sliding](structIRockyContactOutputData.xhtml#ae0f380ec4f65945e54d4e3b939116979) (bool value) ROCKY\_FUNCTIONS void [set\_home\_moment](structIRockyContactOutputData.xhtml#a4016d11738ce592f4e0b2853c552db13) (double3 value) ROCKY\_FUNCTIONS void [set\_near\_moment](structIRockyContactOutputData.xhtml#a7eea9b368237f35e06d1e3381fef9a13) (double3 value) ROCKY\_FUNCTIONS void [set\_rolling\_dissipated\_power](structIRockyContactOutputData.xhtml#ad957c62e9c6bb92c8e13ef28ea8e0a3d) (double value) ROCKY\_FUNCTIONS double [get\_normal\_force](structIRockyContactOutputData.xhtml#adfb7782976874a10981521e52742a015) () ROCKY\_FUNCTIONS double3 [get\_tangential\_force](structIRockyContactOutputData.xhtml#a25aeef724bbfb9eb24d8297df024f208) () ROCKY\_FUNCTIONS double [get\_normal\_relative\_velocity](structIRockyContactOutputData.xhtml#adb3a62ea0f7da835ebeec3ec48d72214) () ROCKY\_FUNCTIONS double3 [get\_tangential\_relative\_velocity](structIRockyContactOutputData.xhtml#aff6677ca9cfa1f58ae87e308d7b19286) () <a id="details" name="details"></a>## Detailed Description

`<a class="el" href="structIRockyContactOutputData.xhtml">IRockyContactOutputData</a>` 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:

- Normal contact force calculation within the code associated to the   
    `ROCKY_PLUGIN_NORMAL_FORCE_ON_CONTACTS` hook:
    - `<a class="el" href="structIRockyContactOutputData.xhtml#a396b63164b3e2d7792bca3c7ba1ae274">IRockyContactOutputData::set_normal_force</a>`
- Tangential contact force calculation within the code associated to the   
    `ROCKY_PLUGIN_TANGENTIAL_FORCE_ON_CONTACTS` hook:
    - `<a class="el" href="structIRockyContactOutputData.xhtml#abaf1043a614caad9555e2c909eb21e12">IRockyContactOutputData::set_tangential_force</a>`
    - `<a class="el" href="structIRockyContactOutputData.xhtml#ae0f380ec4f65945e54d4e3b939116979">IRockyContactOutputData::set_sliding</a>`
- Impact energy calculation within the code associated to the   
    `ROCKY_PLUGIN_IMPACT_ENERGY_ON_CONTACTS` hook:
    - `<a class="el" href="structIRockyContactOutputData.xhtml#a6fa45c11ca5a3dc0e2e7ba76cceca590">IRockyContactOutputData::set_home_impact_energy</a>`
    - `<a class="el" href="structIRockyContactOutputData.xhtml#afaf9777156ccff17bad6b754bd9ec0e2">IRockyContactOutputData::set_near_impact_energy</a>`

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

<a id="adfb7782976874a10981521e52742a015" name="adfb7782976874a10981521e52742a015"></a>## [◆ ](#adfb7782976874a10981521e52742a015)get\_normal\_force()

 ROCKY\_FUNCTIONS double IRockyContactOutputData::get\_normal\_force  ( ) 

ReturnsThe 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.AttentionNote that the value returned by this method may differ from the value returned by `<a class="el" href="structIRockyContact.xhtml#a9e085d9bb5684b5d34c33525bb1d021c">IRockyContact::get_normal_contact_force</a>`, 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. 



<a id="adb3a62ea0f7da835ebeec3ec48d72214" name="adb3a62ea0f7da835ebeec3ec48d72214"></a>## [◆ ](#adb3a62ea0f7da835ebeec3ec48d72214)get\_normal\_relative\_velocity()

 ROCKY\_FUNCTIONS double IRockyContactOutputData::get\_normal\_relative\_velocity  ( ) 

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



<a id="a25aeef724bbfb9eb24d8297df024f208" name="a25aeef724bbfb9eb24d8297df024f208"></a>## [◆ ](#a25aeef724bbfb9eb24d8297df024f208)get\_tangential\_force()

 ROCKY\_FUNCTIONS double3 IRockyContactOutputData::get\_tangential\_force  ( ) 

ReturnsThe 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.AttentionNote that the value returned from this method may differ from the value returned by `<a class="el" href="structIRockyContact.xhtml#aca5aae0a4d0c2033bbad4da067657704">IRockyContact::get_tangential_contact_force</a>`, 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. 



<a id="aff6677ca9cfa1f58ae87e308d7b19286" name="aff6677ca9cfa1f58ae87e308d7b19286"></a>## [◆ ](#aff6677ca9cfa1f58ae87e308d7b19286)get\_tangential\_relative\_velocity()

 ROCKY\_FUNCTIONS double3 IRockyContactOutputData::get\_tangential\_relative\_velocity  ( ) 

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



<a id="a6fa45c11ca5a3dc0e2e7ba76cceca590" name="a6fa45c11ca5a3dc0e2e7ba76cceca590"></a>## [◆ ](#a6fa45c11ca5a3dc0e2e7ba76cceca590)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 aspecial 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. 



<a id="a4016d11738ce592f4e0b2853c552db13" name="a4016d11738ce592f4e0b2853c552db13"></a>## [◆ ](#a4016d11738ce592f4e0b2853c552db13)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 theparticle 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. 



<a id="afaf9777156ccff17bad6b754bd9ec0e2" name="afaf9777156ccff17bad6b754bd9ec0e2"></a>## [◆ ](#afaf9777156ccff17bad6b754bd9ec0e2)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 aspecial 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. 



<a id="a7eea9b368237f35e06d1e3381fef9a13" name="a7eea9b368237f35e06d1e3381fef9a13"></a>## [◆ ](#a7eea9b368237f35e06d1e3381fef9a13)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 theparticle 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. 



<a id="a396b63164b3e2d7792bca3c7ba1ae274" name="a396b63164b3e2d7792bca3c7ba1ae274"></a>## [◆ ](#a396b63164b3e2d7792bca3c7ba1ae274)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 customcontact 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. 



<a id="ad957c62e9c6bb92c8e13ef28ea8e0a3d" name="ad957c62e9c6bb92c8e13ef28ea8e0a3d"></a>## [◆ ](#ad957c62e9c6bb92c8e13ef28ea8e0a3d)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, dueto 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. 



<a id="ae0f380ec4f65945e54d4e3b939116979" name="ae0f380ec4f65945e54d4e3b939116979"></a>## [◆ ](#ae0f380ec4f65945e54d4e3b939116979)set\_sliding()

 ROCKY\_FUNCTIONS void IRockyContactOutputData::set\_sliding  ( bool  *value*) 

This method must be used by a module implementing a custom tangentialcontact 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. 



<a id="abaf1043a614caad9555e2c909eb21e12" name="abaf1043a614caad9555e2c909eb21e12"></a>## [◆ ](#abaf1043a614caad9555e2c909eb21e12)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 acustom 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.