## On this page
# Structure IRockyContactScalarsModel
Last update: 09.03.2026
**\#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](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a00693cfaa879794cda713e943549644f)
- [add](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a295989b18e690130d92c31881a61ba76)
- [enable\_previous\_moment\_vector](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1ab2927b1c13fc4325a5bd28ba97e15230)
- [enable\_storage\_is\_sliding\_marker](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a2a383fbe3de38c7aab855c0b775a293b)
- [enable\_storage\_normal\_adhesion\_force](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a0b773628077520e21f189ab64b8b1e69)
- [enable\_storage\_normal\_relative\_velocity](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a30a72264168db13de798df7cdff440c5)
- [enable\_storage\_previous\_normal\_vector](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a36a468305e9a49ba36de61846260c1f1)
- [enable\_storage\_sliding\_distance](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a8e8fb75a47341a734ee04707a58f658f)
- [enable\_storage\_tangential\_adhesion\_force](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1ab390c75dee689878d04d1db89be3fb95)
- [enable\_storage\_tangential\_contact\_force](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a5a65f842ce3bea36ee46b346a2741911)
- [enable\_storage\_tangential\_relative\_velocity](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1ad8ba6db25bce594fbb62b415b0634a95)
- [enable\_variable\_dynamic\_friction\_coefficient](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1afd6b2a12584b9aca0884eef45b372e1c)
- [enable\_variable\_restitution\_coefficient](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a7c098d6a1bb42017f323521a267459bd)
- [enable\_variable\_static\_friction\_coefficient](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a3a8d067f500bb3b7d39f1cb96f993f78)
- [find](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1ad35ceabceb6ec8d839a3e89086643f99)
- [mark\_scalar\_as\_history\_dependent](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a29e181ff7eef3349c42038e6b7f9541a)
- [reset](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a5066c63ea6e2b3b4791f4812b206a65f)
- [set\_dimension](structIRockyContactScalarsModel.md#structIRockyContactScalarsModel_1a95938d3b140e2fbf6b3f417ad88cefd8)
## Public functions
### Function find
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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
```cpp
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