Structure IRockyContactScalarsModel

#include <rocky_contact_scalars.hpp>

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.

Inherits from:

• ScalarsModel< rocky20::BaseContactScalarsController >

Members

• add
• add
• enable_previous_moment_vector
• enable_storage_is_sliding_marker
• enable_storage_normal_adhesion_force
• enable_storage_normal_relative_velocity
• enable_storage_previous_normal_vector
• enable_storage_sliding_distance
• enable_storage_tangential_adhesion_force
• enable_storage_tangential_contact_force
• enable_storage_tangential_relative_velocity
• enable_variable_dynamic_friction_coefficient
• enable_variable_restitution_coefficient
• enable_variable_static_friction_coefficient
• find
• mark_scalar_as_history_dependent
• reset
• set_dimension

Public functions

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

• name: The 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.

Parameters:

• const char * name

Return type: int

Function reset

void IRockyContactScalarsModel::reset(int scalar_index)

This method resets to zero all values stored in a scalar variable.:

Parameters:

• scalar_index: The index attributed to the scalar variable at the moment of its creation.

Parameters:

• int scalar_index

Return type: void

Function 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_index: The index attributed to the scalar variable at the moment of its creation.
• dimension_factor: The appropriate dimensional factor for the scalar variable.

Parameters:

• int scalar_index
• double dimension_factor

Return type: void

Function add

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:

• name: The 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.
• unit: A string specifying the unit in S.I. associated to the scalar variable.
• output: Enables/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.

Parameters:

• const char * name
• const char * unit
• bool output = true

Return type: int

Function add

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:

• name: The 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.
• unit: A string specifying the unit in S.I. associated to the scalar variable.
• output: Enables/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.

Parameters:

• const char * name
• const char * unit
• bool output

Return type: int

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

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

Return type: void

Function 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_index: The 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.

Parameters:

• int scalar_index

Return type: void