Rocky Solver SDK 2024 R2

IRockyContactScalarsModel Struct Reference

Last update: 08.07.2024

#include <rocky_contact_scalars.hpp>

Inherits ScalarsModel< rocky20::BaseContactScalarsController >.

Public Member Functions

int find (const char *name)
 
void reset (int scalar_index)
 
void set_dimension (int scalar_index, double dimension_factor)
 
int add (const char *name, const char *unit, bool output=true)
 
template<class data_type >
int add (const char *name, const char *unit, bool output)
 
void enable_variable_dynamic_friction_coefficient ()
 
void enable_variable_static_friction_coefficient ()
 
void enable_variable_restitution_coefficient ()
 
void enable_storage_sliding_distance ()
 
void enable_storage_is_sliding_marker ()
 
void enable_storage_tangential_contact_force ()
 
void enable_storage_normal_relative_velocity ()
 
void enable_storage_tangential_relative_velocity ()
 
void enable_storage_normal_adhesion_force ()
 
void enable_storage_tangential_adhesion_force ()
 
void enable_storage_previous_normal_vector ()
 
void enable_previous_moment_vector ()
 
void mark_scalar_as_history_dependent (int scalar_index)
 

Detailed Description

During the setup phase of a module, an IRockyContactScalarsModel object allows users to add new contact scalars, find contact scalars created in other modules, or activate contact scalars known to Rocky. Contact scalars are special variables attached to contacts that store per-contact values preserved between time iterations during a simulation.

Member Function Documentation

◆ add() [1/2]

template<class data_type >
int IRockyContactScalarsModel::add ( const char *  name,
const char *  unit,
bool  output 
)
This method creates a new scalar variable of type data_type
for storing custom values during a simulation, preserving them between time iterations.
Parameters
nameThe name given to the scalar variable. The purpose of this name is twofold. First, it enables to find this scalar variable from other module, in order to share their values. Second, if the scalar variable can be displayed in a 3D window as a property, this name will identify it in the Rocky UI.
unitA string specifying the unit in S.I. associated to the scalar variable.
outputEnables/disables the storage in disk at output times, for the visualization and post-processing of the scalar values.
Returns
The index that will uniquely identify the scalar variable during the execution of the simulation.

◆ add() [2/2]

int IRockyContactScalarsModel::add ( const char *  name,
const char *  unit,
bool  output = true 
)
This method creates a new scalar variable of type double
for storing custom values during a simulation, preserving them between time iterations.
Parameters
nameThe name given to the scalar variable. The purpose of this name is twofold. First, it enables to find this scalar variable from other module, in order to share their values. Second, if the scalar variable can be displayed in a 3D window as a property, this name will identify it in the Rocky UI.
unitA string specifying the unit in S.I. associated to the scalar variable.
outputEnables/disables the storage in disk at output times, for the visualization and post-processing of the scalar values.
Returns
The index that will uniquely identify the scalar variable during the execution of the simulation.

◆ enable_previous_moment_vector()

void IRockyContactScalarsModel::enable_previous_moment_vector ( )
This method is intended for modules implementing a custom rolling resistance model
in which the rolling resistance is updated on each time iteration. It enables a contact scalar that can be used by a module for storing the moment calculated at a given time iteration in order to make it available in the following iteration. It is highly recommended to use that contact scalar instead of a regular contact scalar, because the Rocky solver will correct the orientation of the stored vector automatically if the contact topology is altered because of an internal reorganization of the array of contacts (a regular contact scalar will not be corrected in such an event).

◆ enable_storage_is_sliding_marker()

void IRockyContactScalarsModel::enable_storage_is_sliding_marker ( )
This method enables a known-scalar that will store a marker that indicates whether a contact
is sliding or not at a given moment. Normally this marker is used only internally in Rocky, but this method can make it available to custom models that may need that information. When that storage has been enabled, the value of the marker for sliding can be accessed by using the IRockyContact::get_is_sliding_marker method.

◆ enable_storage_normal_adhesion_force()

void IRockyContactScalarsModel::enable_storage_normal_adhesion_force ( )
This method enables a known-scalar that stores the value of the normal component of the
adhesion force. In this way, if an adhesive force model is active in a simulation, a custom module will have access to the value of that force. When that storage has been enabled, the value of the normal adhesion force can be accessed by using the IRockyContact::get_normal_adhesion_force method.

◆ enable_storage_normal_relative_velocity()

void IRockyContactScalarsModel::enable_storage_normal_relative_velocity ( )
This method enables a known-scalar that stores the value of the normal component of the
relative velocity at a contact. In this way that value, which is normally calculated internally by the Rocky solver and used on its own calculations, will be made available for custom modules as well. This can be preferable to the use of the IRockyContact::calculate_relative_velocity method, since that calculation may be expensive. When its storage has been enabled, the value of the normal relative velocity component can be accessed by using the IRockyContact::get_normal_relative_velocity method.

◆ enable_storage_previous_normal_vector()

void IRockyContactScalarsModel::enable_storage_previous_normal_vector ( )
This method enables a known-scalar that stores automatically the value of the contact's
normal unit vector at the end of a time iteration, with the purpose of making it available during the next time iteration. If the storage of this vector has been enabled, it can be accessed during a simulation by using the IRockyContact::get_previous_normal_vector method. By comparing this vector to the current normal unit vector, a custom module will be able to determine if a change on the contact's normal direction has occurred between iterations. The Rocky solver will correct the orientation of this vector automatically if the contact topology is altered because of an internal reorganization of the array of contacts (a regular contact scalar will not be corrected in such an event).

◆ enable_storage_sliding_distance()

void IRockyContactScalarsModel::enable_storage_sliding_distance ( )
This method enables a known-scalar that stores the value calculated for the sliding
distance during the processing of the contact forces. In this way, that value will be accessible to custom models that may need it for their own calculations. The sliding distance is the distance that a contact point moves parallel to the tangential contact plane during a timestep. When its storage has been enabled, the value of the sliding distance can be accessed by using the IRockyContact::get_sliding_distance method.

◆ enable_storage_tangential_adhesion_force()

void IRockyContactScalarsModel::enable_storage_tangential_adhesion_force ( )
This method enables a known-scalar that stores the value of the tangential component of the
adhesion force. Only some external modules, such as the Liquid Bridge Model module, implement a model in which the adhesion force may have a tangential component. If one of such modules is active in a simulation, a custom module will have access to the value of that force when its storage has been enabled with this method. Then, during the simulation, the value of the tangential adhesion force can be accessed by using the IRockyContact::get_tangential_adhesion_force method.

◆ enable_storage_tangential_contact_force()

void IRockyContactScalarsModel::enable_storage_tangential_contact_force ( )
This method enables a known-scalar that makes available to custom modules the tangential
force vector that is calculated by any contact tangential force model active in a simulation. The value of this force is not always automatically accessible by custom models. For instance, if users want to use the tangential force value when the Coulomb Limit or any other custom contact tangential force model is active, they will need to enable its storage using this method. When that storage has been enabled, the value of the tangential force vector can be accessed by using the IRockyContact::get_tangential_contact_force method.

◆ enable_storage_tangential_relative_velocity()

void IRockyContactScalarsModel::enable_storage_tangential_relative_velocity ( )
This method enables a known-scalar that stores the value of the normal component of the
relative velocity at a contact. In this way that value, which is normally calculated internally by the Rocky solver and used on its own calculations, will be made available for custom modules as well. This can be preferable to the use of the IRockyContact::calculate_relative_velocity method, since that calculation may be expensive. When its storage has been enabled, the value of the tangential relative velocity vector can be accessed by using the IRockyContact::get_tangential_relative_velocity method.

◆ enable_variable_dynamic_friction_coefficient()

void IRockyContactScalarsModel::enable_variable_dynamic_friction_coefficient ( )
This method enables the dynamic coefficient of friction as a variable property for contacts
that will override the constant values specified per material interaction in the Rocky UI. When a custom module enables this variable property, it becomes responsible for setting a custom value for every contact in the simulation by using the IRockyContact::set_dynamic_friction_coefficient method.

◆ enable_variable_restitution_coefficient()

void IRockyContactScalarsModel::enable_variable_restitution_coefficient ( )
This method enables a known-scalar that defines the restitution coefficient as a variable
property at contacts. When this scalar is enabled, a different value of the restitution coefficient can be specified for each contact that arises in a simulation, using the IRockyContact::set_restitution_coefficient method. In this case, that value will override the constant values specified for this property through the Rocky UI.

◆ enable_variable_static_friction_coefficient()

void IRockyContactScalarsModel::enable_variable_static_friction_coefficient ( )
This method enables the static coefficient of friction as a variable property for contacts
that will override the constant values specified per material interaction in the Rocky UI. When a custom module enables this variable property, it becomes responsible for setting a custom value for every contact in the simulation by using the IRockyContact::set_static_friction_coefficient method.

◆ find()

int IRockyContactScalarsModel::find ( const char *  name)
This method searches for a scalar variable already created by other modules,
in order to allow access to its values, or store new values on it, during the execution of the simulation.
Parameters
nameThe name given to the scalar at the moment of its creation.
Returns
The index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise.

◆ mark_scalar_as_history_dependent()

void IRockyContactScalarsModel::mark_scalar_as_history_dependent ( int  scalar_index)
This method must be used to inform Rocky that a given particle-to-particle contact
scalar stores a 3D vector whose value depends on the history of the contact. Typical cases are 3D vectors whose values are obtained incrementally over time, or a 3D vector whose value is stored for the next time iteration in order to approximate its time derivative. When such scalars are marked using this method, Rocky takes care of preserving the orientation of the vector whenever an internal reordering of the particle indices causes a topological reversal of the contact. If a particle-to-particle contact scalar depending on time is not marked with this method, contact reversals may destabilize the simulation or may lead to completely incorrect results.
Parameters
scalar_indexThe index that identifies the specific contact scalar that must be marked as dependent on history. Only particle-to-particle contact scalars of type double3 are able to be marked with this method. Any other scalar type will not be affected by contact reversals.

◆ reset()

void IRockyContactScalarsModel::reset ( int  scalar_index)
This method resets to zero all values stored in a scalar variable.
Parameters
scalar_indexThe index attributed to the scalar variable at the moment of its creation.

◆ set_dimension()

void IRockyContactScalarsModel::set_dimension ( int  scalar_index,
double  dimension_factor 
)
The purpose of this method is to associate a dimensional factor
to a scalar variable. This factor will be used to nondimensionalize their values. For instance, if the scalar represents a force, a force dimensional factor must be associated through this method. Dimensional factors for the fundamental magnitudes are provided by functions of a IRockyModel object.
Parameters
scalar_indexThe index attributed to the scalar variable at the moment of its creation.
dimension_factorThe appropriate dimensional factor for the scalar variable.

Connect with Ansys