## On this page

  

 

 # IRockyContactScalarsModel Struct Reference

 Last update: 17.07.2025 

`#include <<a class="el" href="rocky__contact__scalars_8hpp_source.xhtml">rocky_contact_scalars.hpp</a>>`

Inherits ScalarsModel&lt; rocky20::BaseContactScalarsController &gt;.

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

int [find](structIRockyContactScalarsModel.xhtml#ad35ceabceb6ec8d839a3e89086643f99) (const char \*name) void [reset](structIRockyContactScalarsModel.xhtml#a5066c63ea6e2b3b4791f4812b206a65f) (int scalar\_index) void [set\_dimension](structIRockyContactScalarsModel.xhtml#a95938d3b140e2fbf6b3f417ad88cefd8) (int scalar\_index, double dimension\_factor) int [add](structIRockyContactScalarsModel.xhtml#a00693cfaa879794cda713e943549644f) (const char \*name, const char \*unit, bool output=true) template&lt;class data\_type &gt; int [add](structIRockyContactScalarsModel.xhtml#a295989b18e690130d92c31881a61ba76) (const char \*name, const char \*unit, bool output) void [enable\_variable\_dynamic\_friction\_coefficient](structIRockyContactScalarsModel.xhtml#afd6b2a12584b9aca0884eef45b372e1c) () void [enable\_variable\_static\_friction\_coefficient](structIRockyContactScalarsModel.xhtml#a3a8d067f500bb3b7d39f1cb96f993f78) () void [enable\_variable\_restitution\_coefficient](structIRockyContactScalarsModel.xhtml#a7c098d6a1bb42017f323521a267459bd) () void [enable\_storage\_sliding\_distance](structIRockyContactScalarsModel.xhtml#a8e8fb75a47341a734ee04707a58f658f) () void [enable\_storage\_is\_sliding\_marker](structIRockyContactScalarsModel.xhtml#a2a383fbe3de38c7aab855c0b775a293b) () void [enable\_storage\_tangential\_contact\_force](structIRockyContactScalarsModel.xhtml#a5a65f842ce3bea36ee46b346a2741911) () void [enable\_storage\_normal\_relative\_velocity](structIRockyContactScalarsModel.xhtml#a30a72264168db13de798df7cdff440c5) () void [enable\_storage\_tangential\_relative\_velocity](structIRockyContactScalarsModel.xhtml#ad8ba6db25bce594fbb62b415b0634a95) () void [enable\_storage\_normal\_adhesion\_force](structIRockyContactScalarsModel.xhtml#a0b773628077520e21f189ab64b8b1e69) () void [enable\_storage\_tangential\_adhesion\_force](structIRockyContactScalarsModel.xhtml#ab390c75dee689878d04d1db89be3fb95) () void [enable\_storage\_previous\_normal\_vector](structIRockyContactScalarsModel.xhtml#a36a468305e9a49ba36de61846260c1f1) () void [enable\_previous\_moment\_vector](structIRockyContactScalarsModel.xhtml#ab2927b1c13fc4325a5bd28ba97e15230) () void [mark\_scalar\_as\_history\_dependent](structIRockyContactScalarsModel.xhtml#a29e181ff7eef3349c42038e6b7f9541a) (int scalar\_index) <a id="details" name="details"></a>## Detailed Description

During the setup phase of a module, an `<a class="el" href="structIRockyContactScalarsModel.xhtml">IRockyContactScalarsModel</a>` 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

<a id="a295989b18e690130d92c31881a61ba76" name="a295989b18e690130d92c31881a61ba76"></a>## [◆ ](#a295989b18e690130d92c31881a61ba76)add() \[1/2\]

template&lt;class data_type &gt; 

 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.ReturnsThe index that will uniquely identify the scalar variable during the execution of the simulation. 



<a id="a00693cfaa879794cda713e943549644f" name="a00693cfaa879794cda713e943549644f"></a>## [◆ ](#a00693cfaa879794cda713e943549644f)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.ReturnsThe index that will uniquely identify the scalar variable during the execution of the simulation. 



<a id="ab2927b1c13fc4325a5bd28ba97e15230" name="ab2927b1c13fc4325a5bd28ba97e15230"></a>## [◆ ](#ab2927b1c13fc4325a5bd28ba97e15230)enable\_previous\_moment\_vector()

 void IRockyContactScalarsModel::enable\_previous\_moment\_vector  ( ) 

This method is intended for modules implementing a custom rolling resistance modelin 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). 



<a id="a2a383fbe3de38c7aab855c0b775a293b" name="a2a383fbe3de38c7aab855c0b775a293b"></a>## [◆ ](#a2a383fbe3de38c7aab855c0b775a293b)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 contactis 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 `<a class="el" href="structIRockyContact.xhtml#a1acfe6d4f8e36c9fd417a658aac1c041">IRockyContact::get_is_sliding_marker</a>` method. 



<a id="a0b773628077520e21f189ab64b8b1e69" name="a0b773628077520e21f189ab64b8b1e69"></a>## [◆ ](#a0b773628077520e21f189ab64b8b1e69)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 theadhesion 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 `<a class="el" href="structIRockyContact.xhtml#a21587a9de6f69f4af1d215c3879fca66">IRockyContact::get_normal_adhesion_force</a>` method. 



<a id="a30a72264168db13de798df7cdff440c5" name="a30a72264168db13de798df7cdff440c5"></a>## [◆ ](#a30a72264168db13de798df7cdff440c5)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 `<a class="el" href="structIRockyContact.xhtml#af05c086a0b75c761b13fa744061789e4">IRockyContact::calculate_relative_velocity</a>` 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 `<a class="el" href="structIRockyContact.xhtml#a379476b7b01576be8fc0eb3f0dde7a1e">IRockyContact::get_normal_relative_velocity</a>` method. 



<a id="a36a468305e9a49ba36de61846260c1f1" name="a36a468305e9a49ba36de61846260c1f1"></a>## [◆ ](#a36a468305e9a49ba36de61846260c1f1)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'snormal 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 `<a class="el" href="structIRockyContact.xhtml#afa684887b3dcfad056850ccfdf399ec3">IRockyContact::get_previous_normal_vector</a>` 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). 



<a id="a8e8fb75a47341a734ee04707a58f658f" name="a8e8fb75a47341a734ee04707a58f658f"></a>## [◆ ](#a8e8fb75a47341a734ee04707a58f658f)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 `<a class="el" href="structIRockyContact.xhtml#afe041153be8e43d3e5d7c7a500a49501">IRockyContact::get_sliding_distance</a>` method. 



<a id="ab390c75dee689878d04d1db89be3fb95" name="ab390c75dee689878d04d1db89be3fb95"></a>## [◆ ](#ab390c75dee689878d04d1db89be3fb95)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 theadhesion 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 `<a class="el" href="structIRockyContact.xhtml#a20d7ffad55e1c1c28c848eb3b09c41f2">IRockyContact::get_tangential_adhesion_force</a>` method. 



<a id="a5a65f842ce3bea36ee46b346a2741911" name="a5a65f842ce3bea36ee46b346a2741911"></a>## [◆ ](#a5a65f842ce3bea36ee46b346a2741911)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 tangentialforce 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 `<a class="el" href="structIRockyContact.xhtml#aca5aae0a4d0c2033bbad4da067657704">IRockyContact::get_tangential_contact_force</a>` method. 



<a id="ad8ba6db25bce594fbb62b415b0634a95" name="ad8ba6db25bce594fbb62b415b0634a95"></a>## [◆ ](#ad8ba6db25bce594fbb62b415b0634a95)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 therelative 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 `<a class="el" href="structIRockyContact.xhtml#af05c086a0b75c761b13fa744061789e4">IRockyContact::calculate_relative_velocity</a>` 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 `<a class="el" href="structIRockyContact.xhtml#a9fab3f0e6f78ea64e96209fbbd540b85">IRockyContact::get_tangential_relative_velocity</a>` method. 



<a id="afd6b2a12584b9aca0884eef45b372e1c" name="afd6b2a12584b9aca0884eef45b372e1c"></a>## [◆ ](#afd6b2a12584b9aca0884eef45b372e1c)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 contactsthat 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 `<a class="el" href="structIRockyContact.xhtml#aaa4594d0c921983edc1d1033661c6500">IRockyContact::set_dynamic_friction_coefficient</a>` method. 



<a id="a7c098d6a1bb42017f323521a267459bd" name="a7c098d6a1bb42017f323521a267459bd"></a>## [◆ ](#a7c098d6a1bb42017f323521a267459bd)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 `<a class="el" href="structIRockyContact.xhtml#ad5f45118ba3d4bdedd2194640fc4c79d">IRockyContact::set_restitution_coefficient</a>` method. In this case, that value will override the constant values specified for this property through the Rocky UI. 



<a id="a3a8d067f500bb3b7d39f1cb96f993f78" name="a3a8d067f500bb3b7d39f1cb96f993f78"></a>## [◆ ](#a3a8d067f500bb3b7d39f1cb96f993f78)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 contactsthat 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 `<a class="el" href="structIRockyContact.xhtml#a5a3233239461058a2f33a9f49494666c">IRockyContact::set_static_friction_coefficient</a>` method. 



<a id="ad35ceabceb6ec8d839a3e89086643f99" name="ad35ceabceb6ec8d839a3e89086643f99"></a>## [◆ ](#ad35ceabceb6ec8d839a3e89086643f99)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.ReturnsThe index that uniquely identifies the wanted scalar if it was actually found. It returns -1 otherwise. 



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



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



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

 void IRockyContactScalarsModel::set\_dimension  ( int  *scalar\_index*,    double  *dimension\_factor*   ) 

The purpose of this method is to associate a dimensional factorto 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 `<a class="el" href="structIRockyModel.xhtml">IRockyModel</a>` 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.