Rocky Solver SDK 2026 R1

Structure IRockyContactOutputData

Last update: 09.03.2026

#include

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.

Members

Public functions

Function 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:

  • value: The normal component of the contact force just calculated using a custom model.

Parameters:

  • double value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The tangential component of the contact force just calculated using a custom model.

Parameters:

  • double3 value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The impact energy for the home particle just calculated using a custom model.

Parameters:

  • double value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The impact energy for the near particle just calculated using a custom model.

Parameters:

  • double value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The sliding status of the contact just calculated using a custom contact model.

Parameters:

  • bool value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The rolling resistance moment vector acting over the home particle.

Parameters:

  • double3 value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The rolling resistance moment vector acting over the near particle.

Parameters:

  • double3 value

Return type: ROCKY_FUNCTIONS void

Function 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:

  • value: The instantaneous power dissipated at a contact by rolling resistance.

Parameters:

  • double value

Return type: ROCKY_FUNCTIONS void

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

Return type: ROCKY_FUNCTIONS double

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

Return type: ROCKY_FUNCTIONS double3

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

Return type: ROCKY_FUNCTIONS double

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

Return type: ROCKY_FUNCTIONS double3

[const]: https://img.shields.io/badge/-const-lightblue (const)

Connect with Ansys