Structure IRockyJoint
Last update: 09.03.2026
#include
IRockyJoint is an interface for the internal joint object in Rocky. It contains methods that give access to joint physical properties and geometric data, in order to implement a custom model for the response of a joint to deformations. All property and variable values made available through IRockyJoint are dimensionless.
When it is necessary to distinguish between the two elements linked by a joint, one is referred to as home element, whereas the other is referred to as near element. The local coordinate framework associated to a joint has the normal unit vector always pointing from the home element to the near element. Whenever the name of a method or object associated to a joint includes the prefix home or near, that means the method or object is related to the home or near element.
Members
- get_angle_scaling_factor
- get_angular_damping_coefficient
- get_angular_deformation
- get_angular_deformation_direction
- get_angular_deformation_velocity
- get_angular_stiffness
- get_area
- get_area_moment_of_inertia
- get_bending_elastic_ratio
- get_damping_force
- get_damping_moment
- get_elastic_force
- get_elastic_moment
- get_element_tags
- get_equivalent_mass
- get_home_arm
- get_home_element_centroid_position
- get_home_element_orientation
- get_joint_damping_ratio
- get_moments_due_to_force
- get_near_arm
- get_near_element_centroid_position
- get_near_element_orientation
- get_normal_damping_coefficient
- get_normal_deformation
- get_normal_deformation_velocity
- get_normal_elastic_ratio
- get_normal_stiffness
- get_normal_stiffness_per_area
- get_normal_vector
- get_number_angular_deformations
- get_poisson_ratio
- get_scalars
- get_tangential_damping_coefficient
- get_tangential_deformation
- get_tangential_deformation_velocity
- get_tangential_elastic_ratio
- get_tangential_stiffness
- get_tangential_stiffness_per_area
- get_torsion_elastic_ratio
- get_young_modulus
- get_young_modulus_multiplier
Public functions
Function get_elastic_force
ROCKY_FUNCTIONS double3 IRockyJoint::get_elastic_force() const
Calculates the resultant force according to the linear elastic model:
described in the DEM Technical Manual. This is useful when the custom module is going to implement a new model only for joint moments, while using the standard linear elastic model for the joint force. The force provided by this method is defined as positive in relation to the home element, and negative in relation to the near element.
Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the normal and tangential forces, as defined in the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double3
Function get_moments_due_to_force
ROCKY_FUNCTIONS thrust::tuple double3, double3 > IRockyJoint::get_moments_due_to_force(double3 force) const
Calculates the moments of the joint force on the two linked elements.:
As the lever arm of the joint force can be different for the two elements, the corresponding moment on each one of them can have different magnitude. This method must be called always after calculating the joint force.
Parameters:
- force: The joint force as a vector in Cartesian coordinates.
Returns:
A tuple of two vectors in Cartesian coordinates, the first one is the moment on the home element, the second one is the moment on the near element.
Parameters:
- double3 force
Return type: ROCKY_FUNCTIONS thrust::tuple double3, double3 >
Function get_elastic_moment
ROCKY_FUNCTIONS double3 IRockyJoint::get_elastic_moment() const
Calculates the resultant moment according to the linear elastic model:
described in section 3.2.1 of the DEM Technical Manual. This is useful when the custom module is going to implement a new model only for the joint forces, while using the standard linear elastic model for the joint moments. The moment provided by this method is defined as positive in relation to the home element, and negative in relation to the near element.
Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the moments defined in equations 3.5, 3.6 and 3.7 of the DEM Technical Manual. When the flexible particle is a fiber, equation 3.7 is disregarded, because only one bending moment exists in that case.
Return type: ROCKY_FUNCTIONS double3
Function get_damping_force
ROCKY_FUNCTIONS double3 IRockyJoint::get_damping_force() const
Calculates a viscous force proportional to the linear deformation:
velocity of the joint. The addition of this force introduces a mechanism of energy dissipation that may help to attenuate internal vibrations between elements in a flexible particle. The force provided by this method is defined as positive in relation to the home element, and negative in relation to the near element.
Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the forces defined in equations 3.18 and 3.19 of the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double3
Function get_damping_moment
ROCKY_FUNCTIONS double3 IRockyJoint::get_damping_moment() const
Calculates a viscous moment proportional to the angular deformation velocity:
of the joint. The addition of this moment introduces a mechanism of energy dissipation that may help to attenuate internal angular oscillations between elements in a flexible particle.
Returns:
A vector in Cartesian coordinates, obtained as the vector sum of the moments defined in equations 3.20, 3.21 and 3.22 of the DEM Technical Manual. When the flexible particle is a fiber, equation 3.22 is disregarded because bending occurs in only one direction in that case. The moment provided by this method is defined as positive in relation to the home element, and negative in relation to the near element.
Return type: ROCKY_FUNCTIONS double3
Function get_normal_deformation
ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_deformation() const
Calculates the normal component of the linear deformation of the joint.:
The joint linear deformation is defined as the relative displacement vector between the joint center points in the two linked elements. This vector is oriented pointing from the home element to the near element.
Returns:
A vector in Cartesian coordinates, calculated as the product of the magnitude given and the normal unit vector. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double3
Function get_tangential_deformation
ROCKY_FUNCTIONS double3 IRockyJoint::get_tangential_deformation() const
Calculates the tangential component of the linear deformation of the joint.:
The joint linear deformation is defined as the relative displacement vector between the joint center points in the two linked elements.
Returns:
A vector in Cartesian coordinates. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double3
Function get_normal_deformation_velocity
ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_deformation_velocity() const
Calculates the normal component of the linear deformation:
velocity of the joint. This velocity is the time derivative of the relative displacement vector between the center points associated to the joint in the two linked elements. The decomposition of this vector into normal and tangential directions is analogous to the one depicted in figure 3.3 of the DEM Technical Manual.
Returns:
The normal component of the linear deformation velocity, expressed in Cartesian coordinates.
Return type: ROCKY_FUNCTIONS double3
Function get_tangential_deformation_velocity
ROCKY_FUNCTIONS double3 IRockyJoint::get_tangential_deformation_velocity() const
Calculates the tangential component of the linear deformation:
velocity of the joint. This velocity is the time derivative of the relative displacement vector between the center points associated to the joint in the two linked elements. The decomposition of this vector into normal and tangential directions is analogous to the one depicted in figure 3.3 of the DEM Technical Manual.
Returns:
The tangential component of the linear deformation velocity, expressed in Cartesian coordinates.
Return type: ROCKY_FUNCTIONS double3
Function get_number_angular_deformations
ROCKY_FUNCTIONS int IRockyJoint::get_number_angular_deformations() const
Returns:
An integer representing the number of possible angular deformations. For joints in a flexible fiber, it will return 2 (torsion and bending), while for joints in the other particle types, it will return 3 (torsion and two bending directions).
Return type: ROCKY_FUNCTIONS int
Function get_angular_deformation
ROCKY_FUNCTIONS double IRockyJoint::get_angular_deformation(int deformation_direction) const
Calculates the angular deformation of the joint in one of the:
possible three mutually orthogonal directions. Figure 3.7 of the DEM Technical Manual illustrates those angles and directions for the shell case.
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion direction, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
The value of the angle for the given direction.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double
Function get_angular_deformation_velocity
ROCKY_FUNCTIONS double IRockyJoint::get_angular_deformation_velocity(int deformation_direction) const
Calculates the angular deformation velocity of the joint:
in one of the possible three mutually orthogonal directions.
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
The magnitude of the angular deformation velocity for the given direction.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double
Function get_angular_deformation_direction
ROCKY_FUNCTIONS double3 IRockyJoint::get_angular_deformation_direction(int deformation_direction) const
Returns the unit vector in one of the three mutually orthogonal:
directions that define the joint local framework.
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
The unit vector in Cartesian coordinates associated to for the given direction.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double3
Function get_normal_stiffness
ROCKY_FUNCTIONS double IRockyJoint::get_normal_stiffness() const
Calculates the stiffness value for computing the joint normal:
force according to the linear elastic model. This stiffness can be used as a reference stiffness value for calculating the joint normal force with a custom joint model.
Returns:
The stiffness value calculated. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_tangential_stiffness
ROCKY_FUNCTIONS double IRockyJoint::get_tangential_stiffness() const
Calculates the stiffness value for computing the joint tangential:
force according to the linear elastic model. This stiffness can be used as a reference stiffness value for calculating the joint tangential force with a custom joint model.
Returns:
The stiffness value calculated. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_angular_stiffness
ROCKY_FUNCTIONS double IRockyJoint::get_angular_stiffness(int deformation_direction) const
Calculates the stiffness value for computing a joint moment:
in one of the three orthogonal local directions, according to the linear elastic model. This stiffness can be used as a reference stiffness value for calculating a joint moment with a custom joint model.
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
A stiffness value calculated with one of the following equations of the DEM Technical Manual: equation 3.10 if deformation_direction = 0, equation 3.11 if deformation_direction = 1, or equation 3.12 if deformation_direction = 2.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double
Function get_normal_damping_coefficient
ROCKY_FUNCTIONS double IRockyJoint::get_normal_damping_coefficient() const
Calculates the damping coefficient for computing the normal:
component of the viscous force.
Returns:
The damping coefficient calculated. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_tangential_damping_coefficient
ROCKY_FUNCTIONS double IRockyJoint::get_tangential_damping_coefficient() const
Calculates the damping coefficient for computing the tangential:
component of the viscous force.
Returns:
The damping coefficient calculated. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_angular_damping_coefficient
ROCKY_FUNCTIONS double IRockyJoint::get_angular_damping_coefficient(int deformation_direction) const
Calculates the damping coefficient for computing a viscous moment:
in one of the three orthogonal local directions.
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
A damping coefficient calculated with one of the following equations of the DEM Technical Manual: equation 3.25 if deformation_direction = 0, equation 3.26 if deformation_direction = 1, or equation 3.27 if deformation_direction = 2.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double
Function get_normal_vector
ROCKY_FUNCTIONS double3 IRockyJoint::get_normal_vector() const
Returns:
The unit normal vector associated to the joint. This vector is defined as indicated in Figure 3.2. It is oriented pointing always to the home element.
Return type: ROCKY_FUNCTIONS double3
Function get_area
ROCKY_FUNCTIONS double IRockyJoint::get_area() const
Returns:
The cross sectional area associated to the joint. For fibers, it will be the area of the circular section of the element with smaller diameter between the two connected by the joint. For shells, it will be the area of the rectangle whose dimensions are the shell thickness and the length of the corresponding triangle's edge. For polyhedra, it will be the area of the triangular face common to the two tetrahedral elements connected by the joint.
Return type: ROCKY_FUNCTIONS double
Function get_area_moment_of_inertia
ROCKY_FUNCTIONS double IRockyJoint::get_area_moment_of_inertia(int deformation_direction) const
Parameters:
- deformation_direction: An integer index that identifies the deformation direction. The three possible values for this parameter are: 0 &ndash torsion, 1 &ndash first bending direction, 2 &ndash second bending direction.
Returns:
The area moment of inertia of the cross section of the joint associated to deformation_direction. If deformation_direction = 0, the polar area moment of inertia is returned.
Parameters:
- int deformation_direction
Return type: ROCKY_FUNCTIONS double
Function get_young_modulus
ROCKY_FUNCTIONS double IRockyJoint::get_young_modulus() const
Returns:
The value of the Young's modulus specified in the Rocky UI for the material associated to the particle.
Return type: ROCKY_FUNCTIONS double
Function get_poisson_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_poisson_ratio() const
Returns:
The value of the Poisson's ratio specified in the Rocky UI for the material associated to the particle. If Poisson's ratio is configured as a variable property (i.e. each particle have a Poisson's ratio value), then the ratio is the average between home and near elements ratios.
Return type: ROCKY_FUNCTIONS double
Function get_normal_elastic_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_normal_elastic_ratio() const
The normal elastic ratio is defined as the ratio between the Young's modulus:
employed for calculating the stiffness in the normal direction to the Young's modulus specified for the particle's material.
Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the elastic ratio in the normal direction. Otherwise, it is assumed an isotropic behavior and it will return the value specified for the only elastic ratio that appears in the Rocky UI.
Return type: ROCKY_FUNCTIONS double
Function get_tangential_elastic_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_tangential_elastic_ratio() const
The tangential elastic ratio is defined as the ratio between the Young's modulus:
employed for calculating the stiffness in the tangential direction to the Young's modulus specified for the particle's material.
Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the elastic ratio in the tangential direction. Otherwise, it is assumed an isotropic behavior and it will return the value specified for the only elastic ratio that appears in the Rocky UI.
Return type: ROCKY_FUNCTIONS double
Function get_torsion_elastic_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_torsion_elastic_ratio() const
The torsion elastic ratio is defined as the ratio between the Young's modulus:
employed for calculating the stiffness for torsional deformations to the Young's modulus specified for the particle's material.
Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the elastic ratio for torsional deformations. Otherwise, it is assumed an isotropic behavior and it will return the value specified for the only elastic ratio that appears in the Rocky UI.
Return type: ROCKY_FUNCTIONS double
Function get_bending_elastic_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_bending_elastic_ratio() const
The bending elastic ratio is defined as the ratio between the Young's modulus:
employed for calculating the stiffness for bending deformations to the Young's modulus specified for the particle's material.
Returns:
If the [Anisotropic] option is enabled in the Rocky UI, it will return the value specified for the elastic ratio for bending deformations. Otherwise, it is assumed an isotropic behavior and it will return the value specified for the only elastic ratio that appears in the Rocky UI.
Return type: ROCKY_FUNCTIONS double
Function get_joint_damping_ratio
ROCKY_FUNCTIONS double IRockyJoint::get_joint_damping_ratio() const
Returns:
The value of the damping ratio specified for the joint, used in the joint damping model. This is a user input parameter with values between 0 and 1, which specifies the intensity of the damping applied to the joints. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_angle_scaling_factor
ROCKY_FUNCTIONS double IRockyJoint::get_angle_scaling_factor() const
When the number of elements making up a flexible particle is increased,:
the bending deformation angles tend to decrease, for the same configuration of external forces acting on the particle. This is a side effect of the discretized representation of a flexible particle. In order to prevent the abnormal influence of this phenomenon on models that have a bending angle as a parameter (for instance a threshold angle for the change of regime), that angle can be multiplied by the scaling factor provided by this function. This scaling factor is defined as the inverse of the number of elements of the particle, when it is a fiber. For shells, it is defined as the inverse of the square root of the number of elements.
Returns:
The angle scaling factor defined above.
Return type: ROCKY_FUNCTIONS double
Function get_equivalent_mass
ROCKY_FUNCTIONS double IRockyJoint::get_equivalent_mass() const
Returns:
The equivalent or effective mass used for calculating joint damping coefficients as indicated, for instance. For more details, please refer to the DEM Technical Manual.
Return type: ROCKY_FUNCTIONS double
Function get_normal_stiffness_per_area
ROCKY_FUNCTIONS double IRockyJoint::get_normal_stiffness_per_area() const
Returns:
The value of the normal stiffness per area unit associated to the joint. Please refer to the DEM Technical Manual for an explanation of how this parameter is calculated for different flexible particle shapes.
Return type: ROCKY_FUNCTIONS double
Function get_tangential_stiffness_per_area
ROCKY_FUNCTIONS double IRockyJoint::get_tangential_stiffness_per_area() const
Returns:
The value of the tangential stiffness per area unit associated to the joint. Please refer to the DEM Technical Manual for an explanation of how this parameter is calculated for different flexible particle shapes.
Return type: ROCKY_FUNCTIONS double
Function get_young_modulus_multiplier
ROCKY_FUNCTIONS double IRockyJoint::get_young_modulus_multiplier() const
Returns:
For custom fibers only, this will return the factor in the right-hand side of equation 3.15 in the DEM Technical Manual. For any other particle type, it will return 1.
Return type: ROCKY_FUNCTIONS double
Function get_scalars
ROCKY_FUNCTIONS IRockyJointScalars IRockyJoint::get_scalars()
If a scalar variable was defined during the setup of the module,:
this method can be used access such variables. Joint scalars are special variables that store custom values per joint, in order to preserve them between time iterations.
Returns:
The class to manipulate joint's scalars
Return type: ROCKY_FUNCTIONS IRockyJointScalars
Function get_home_element_orientation
ROCKY_FUNCTIONS thrust::tuple double3, double > IRockyJoint::get_home_element_orientation() const
Returns:
A tuple whose two components define the axis-angle home element orientation. The first one is a three dimensional vector representing the orientation axis, the second one is a single value representing the angle.
Return type: ROCKY_FUNCTIONS thrust::tuple double3, double >
Function get_near_element_orientation
ROCKY_FUNCTIONS thrust::tuple double3, double > IRockyJoint::get_near_element_orientation() const
Returns:
A tuple whose two components define the axis-angle near element orientation. The first one is a three dimensional vector representing the orientation axis, the second one is a single value representing the angle.
Return type: ROCKY_FUNCTIONS thrust::tuple double3, double >
Function get_home_element_centroid_position
ROCKY_FUNCTIONS double3 IRockyJoint::get_home_element_centroid_position() const
Returns:
The joint home element center point coordinates.
Return type: ROCKY_FUNCTIONS double3
Function get_near_element_centroid_position
ROCKY_FUNCTIONS double3 IRockyJoint::get_near_element_centroid_position() const
Returns:
The joint near element center point coordinates.
Return type: ROCKY_FUNCTIONS double3
Function get_home_arm
ROCKY_FUNCTIONS double3 IRockyJoint::get_home_arm() const
Returns:
The vector that joins the home element center to the joint center.
Return type: ROCKY_FUNCTIONS double3
Function get_near_arm
ROCKY_FUNCTIONS double3 IRockyJoint::get_near_arm() const
Returns:
The vector that joins the near element center to the joint center.
Return type: ROCKY_FUNCTIONS double3
Function get_element_tags
ROCKY_FUNCTIONS thrust::tuple int, int > IRockyJoint::get_element_tags() const
Returns:
The values of custom tags (integer values) assigned to the two elements attached to the joint. These tags are inherited from tags assigned to the segments that define the center line of a custom fiber. The values of those tags must be specified in the column labeled "tag" in the csv file that defines the geometry of a custom fiber. If tags are not defined for a custom fiber or if this function is used with flexible particles other than custom fibers, this function will return two values equal to -1.
Return type: ROCKY_FUNCTIONS thrust::tuple int, int >
[const]: https://img.shields.io/badge/-const-lightblue (const)
