IRockyJoint Struct Reference
Last update: 08.07.2024
IRockyJoint Struct Reference
#include <rocky_joint_api.hpp>
Public Member Functions | |
| ROCKY_FUNCTIONS double3 | get_elastic_force () const |
| ROCKY_FUNCTIONS thrust::tuple< double3, double3 > | get_moments_due_to_force (double3 force) const |
| ROCKY_FUNCTIONS double3 | get_elastic_moment () const |
| ROCKY_FUNCTIONS double3 | get_damping_force () const |
| ROCKY_FUNCTIONS double3 | get_damping_moment () const |
| ROCKY_FUNCTIONS double3 | get_normal_deformation () const |
| ROCKY_FUNCTIONS double3 | get_tangential_deformation () const |
| ROCKY_FUNCTIONS double3 | get_normal_deformation_velocity () const |
| ROCKY_FUNCTIONS double3 | get_tangential_deformation_velocity () const |
| ROCKY_FUNCTIONS int | get_number_angular_deformations () const |
| ROCKY_FUNCTIONS double | get_angular_deformation (int deformation_direction) const |
| ROCKY_FUNCTIONS double | get_angular_deformation_velocity (int deformation_direction) const |
| ROCKY_FUNCTIONS double3 | get_angular_deformation_direction (int deformation_direction) const |
| ROCKY_FUNCTIONS double | get_normal_stiffness () const |
| ROCKY_FUNCTIONS double | get_tangential_stiffness () const |
| ROCKY_FUNCTIONS double | get_angular_stiffness (int deformation_direction) const |
| ROCKY_FUNCTIONS double | get_normal_damping_coefficient () const |
| ROCKY_FUNCTIONS double | get_tangential_damping_coefficient () const |
| ROCKY_FUNCTIONS double | get_angular_damping_coefficient (int deformation_direction) const |
| ROCKY_FUNCTIONS double3 | get_normal_vector () const |
| ROCKY_FUNCTIONS double | get_area () const |
| ROCKY_FUNCTIONS double | get_area_moment_of_inertia (int deformation_direction) const |
| ROCKY_FUNCTIONS double | get_young_modulus () const |
| ROCKY_FUNCTIONS double | get_poisson_ratio () const |
| ROCKY_FUNCTIONS double | get_normal_elastic_ratio () const |
| ROCKY_FUNCTIONS double | get_tangential_elastic_ratio () const |
| ROCKY_FUNCTIONS double | get_torsion_elastic_ratio () const |
| ROCKY_FUNCTIONS double | get_bending_elastic_ratio () const |
| ROCKY_FUNCTIONS double | get_joint_damping_ratio () const |
| ROCKY_FUNCTIONS double | get_angle_scaling_factor () const |
| ROCKY_FUNCTIONS double | get_equivalent_mass () const |
| ROCKY_FUNCTIONS double | get_normal_stiffness_per_area () const |
| ROCKY_FUNCTIONS double | get_tangential_stiffness_per_area () const |
| ROCKY_FUNCTIONS double | get_young_modulus_multiplier () const |
| ROCKY_FUNCTIONS IRockyJointScalars | get_scalars () |
| ROCKY_FUNCTIONS thrust::tuple< double3, double > | get_home_element_orientation () const |
| ROCKY_FUNCTIONS thrust::tuple< double3, double > | get_near_element_orientation () const |
| ROCKY_FUNCTIONS double3 | get_home_element_centroid_position () const |
| ROCKY_FUNCTIONS double3 | get_near_element_centroid_position () const |
| ROCKY_FUNCTIONS double3 | get_home_arm () const |
| ROCKY_FUNCTIONS double3 | get_near_arm () const |
| ROCKY_FUNCTIONS thrust::tuple< int, int > | get_element_tags () const |
Detailed Description
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.
Member Function Documentation
◆ 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.
◆ 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 – torsion, 1 – first bending direction, 2 – 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.
◆ 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 – torsion direction, 1 – first bending direction, 2 – second bending direction.
- Returns
- The value of the angle for the given direction.
◆ 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 – torsion, 1 – first bending direction, 2 – second bending direction.
- Returns
- The unit vector in Cartesian coordinates associated to for the given direction.
◆ 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 – torsion, 1 – first bending direction, 2 – second bending direction.
- Returns
- The magnitude of the angular deformation velocity for the given direction.
◆ 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 – torsion, 1 – first bending direction, 2 – 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.
◆ 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.
◆ 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 – torsion, 1 – first bending direction, 2 – 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ get_home_arm()
| ROCKY_FUNCTIONS double3 IRockyJoint::get_home_arm | ( | ) | const |
- Returns
- The vector that joins the home element center to the joint center.
◆ get_home_element_centroid_position()
| ROCKY_FUNCTIONS double3 IRockyJoint::get_home_element_centroid_position | ( | ) | const |
- Returns
- The joint home element center point coordinates.
◆ 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.
◆ 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.
◆ 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.
◆ get_near_arm()
| ROCKY_FUNCTIONS double3 IRockyJoint::get_near_arm | ( | ) | const |
- Returns
- The vector that joins the near element center to the joint center.
◆ get_near_element_centroid_position()
| ROCKY_FUNCTIONS double3 IRockyJoint::get_near_element_centroid_position | ( | ) | const |
- Returns
- The joint near element center point coordinates.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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).
◆ 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.
◆ 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
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.