Skip to main content

Rocky Solver SDK 2024 R2

IRockyParticle Struct Reference

Last update: 08.07.2024

#include <rocky_particle_api.hpp>

Public Member Functions

ROCKY_FUNCTIONS IRockyMaterial get_material () const
 
ROCKY_FUNCTIONS double3 get_centroid_position () const
 
ROCKY_FUNCTIONS double get_mass () const
 
ROCKY_FUNCTIONS double get_original_mass () const
 
ROCKY_FUNCTIONS double get_size () const
 
ROCKY_FUNCTIONS double get_release_time () const
 
ROCKY_FUNCTIONS double get_cgm_scale_factor () const
 
ROCKY_FUNCTIONS double get_volume () const
 
ROCKY_FUNCTIONS double get_solid_volume () const
 
ROCKY_FUNCTIONS double get_surface_area () const
 
ROCKY_FUNCTIONS double get_equivalent_diameter () const
 
ROCKY_FUNCTIONS double get_sphericity () const
 
ROCKY_FUNCTIONS double3 get_translational_velocity () const
 
ROCKY_FUNCTIONS double3 get_rotational_velocity () const
 
ROCKY_FUNCTIONS double get_impact_energy () const
 
ROCKY_FUNCTIONS double get_strength () const
 
ROCKY_FUNCTIONS double3 get_gravity () const
 
ROCKY_FUNCTIONS int get_particle_group_index () const
 
ROCKY_FUNCTIONS int get_material_index () const
 
ROCKY_FUNCTIONS double get_rolling_resistance_coefficient () const
 
ROCKY_FUNCTIONS thrust::tuple< double3, double > get_orientation_axis_angle () const
 
ROCKY_FUNCTIONS double4 get_orientation_quaternion () const
 
ROCKY_FUNCTIONS double3 get_resultant_force () const
 
ROCKY_FUNCTIONS double3 get_resultant_moment () const
 
ROCKY_FUNCTIONS double get_thermal_conductivity () const
 
ROCKY_FUNCTIONS void set_thermal_conductivity (double value)
 
ROCKY_FUNCTIONS double get_poisson_ratio () const
 
ROCKY_FUNCTIONS void set_poisson_ratio (double value)
 
ROCKY_FUNCTIONS double get_specific_heat () const
 
ROCKY_FUNCTIONS int get_tag () const
 
ROCKY_FUNCTIONS void set_specific_heat (double value)
 
ROCKY_FUNCTIONS IRockyParticleScalars get_scalars ()
 
ROCKY_FUNCTIONS const IRockyParticleScalars get_scalars () const
 
ROCKY_FUNCTIONS IRockyParticleTransferScalars get_transfer_scalars ()
 
ROCKY_FUNCTIONS IRockyParticleBreakageScalars get_breakage_scalars ()
 
ROCKY_FUNCTIONS void remove ()
 
ROCKY_FUNCTIONS void add_force (const double3 &force)
 
ROCKY_FUNCTIONS void add_moment (const double3 &moment)
 
ROCKY_FUNCTIONS void set_frozen (bool frozen)
 
ROCKY_FUNCTIONS void disable_related_particle_contacts ()
 
ROCKY_FUNCTIONS void enable_related_particle_contacts ()
 
ROCKY_FUNCTIONS void disable_related_triangle_contacts ()
 
ROCKY_FUNCTIONS void enable_related_triangle_contacts ()
 
ROCKY_FUNCTIONS const double3 get_moment_of_inertia () const
 
ROCKY_FUNCTIONS bool is_element () const
 
ROCKY_FUNCTIONS bool is_assembly () const
 
ROCKY_FUNCTIONS size_t get_number_of_assembly_parts () const
 
ROCKY_FUNCTIONS IRockyMaterial get_assembly_part_material (size_t part_id) const
 
ROCKY_FUNCTIONS void remove_from_contacts_search ()
 
ROCKY_FUNCTIONS void add_to_contacts_search ()
 

Detailed Description

IRockyParticle is an interface for the internal particle object in Rocky. A particle object is the code representation of an individual particle in a Rocky simulation. It has several access methods to particle-related properties, as well as particle scalars, which are special variables that store values per particle that are preserved between time iterations. Values of particle scalars can be displayed in a 3D window as any other built-in particle property in Rocky. All property and variable values made available through IRockyParticle are dimensionless.

Member Function Documentation

◆ add_force()

ROCKY_FUNCTIONS void IRockyParticle::add_force ( const double3 &  force)
This method sums a custom calculated force to the contact and body forces
acting on the particle.
Parameters
forceThe custom force vector in Cartesian coordinates.

◆ add_moment()

ROCKY_FUNCTIONS void IRockyParticle::add_moment ( const double3 &  moment)
This method sums a custom calculated moment to the moments
acting on the particle.
Parameters
momentThe custom moment vector in Cartesian coordinates.

◆ add_to_contacts_search()

ROCKY_FUNCTIONS void IRockyParticle::add_to_contacts_search ( )
This method enables the detection of all contacts for the particle.

◆ disable_related_particle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::disable_related_particle_contacts ( )
This method activates the conditional disabling of particle-to-particle contacts detection.
A given particle-to-particle contact will be ignored during the detection stage only if this method has been applied to both particles.

◆ disable_related_triangle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::disable_related_triangle_contacts ( )
This method disables the detection of particle-to-triangle contacts for the particle.

◆ enable_related_particle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::enable_related_particle_contacts ( )
This method deactivates the conditional disabling of particle-to-particle contact detection,
previously activated using the IRockyParticle::disable_related_particle_contacts

◆ enable_related_triangle_contacts()

ROCKY_FUNCTIONS void IRockyParticle::enable_related_triangle_contacts ( )
This method enables the detection of particle-to-triangle contacts for the particle.

◆ get_assembly_part_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyParticle::get_assembly_part_material ( size_t  part_id) const
Parameters
part_idThe index of an assembly part.
Returns
An IRockyMaterial object that gives access to the values of physical properties associated to the material from which the assembly part referent to part_id is made.

◆ get_breakage_scalars()

ROCKY_FUNCTIONS IRockyParticleBreakageScalars IRockyParticle::get_breakage_scalars ( )
Returns
An IRockyParticleBreakageScalars object, that gives access to all particle breakage scalars variables defined in the project.

◆ get_centroid_position()

ROCKY_FUNCTIONS double3 IRockyParticle::get_centroid_position ( ) const
Returns
The Cartesian coordinates of the current position of the particle's centroid.

◆ get_cgm_scale_factor()

ROCKY_FUNCTIONS double IRockyParticle::get_cgm_scale_factor ( ) const
Returns
The particle's Coarse-grain Modeling (CGM) scale factor.

◆ get_equivalent_diameter()

ROCKY_FUNCTIONS double IRockyParticle::get_equivalent_diameter ( ) const
Returns
The equivalent diameter of the particle, which is defined as the diameter of a sphere of volume equal to the particle's volume.

◆ get_gravity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_gravity ( ) const
Returns
The gravitational acceleration vector in Cartesian coordinates.

◆ get_impact_energy()

ROCKY_FUNCTIONS double IRockyParticle::get_impact_energy ( ) const
Returns
The sum of the impact energy registered in all active contacts on the surface of the particle until the current time.
Attention
This value will be available only if an instantaneous breakage model is enabled in the simulation.

◆ get_mass()

ROCKY_FUNCTIONS double IRockyParticle::get_mass ( ) const
Returns
The current value of the particle's mass. This value will be different from the original particle's mass only if the mass increment particle scalar is enabled in the simulation.

◆ get_material()

ROCKY_FUNCTIONS IRockyMaterial IRockyParticle::get_material ( ) const
Returns
An IRockyMaterial object that gives access to the values of physical properties associated to the material from which the particle is made.
Attention
Invoking this method on assembly particles results on undefined behavior, as assembly particles may have multiple materials. Prefer to use IRockyParticle::get_assembly_part_material instead.

◆ get_material_index()

ROCKY_FUNCTIONS int IRockyParticle::get_material_index ( ) const
Returns
The material index associated to that particle

◆ get_moment_of_inertia()

ROCKY_FUNCTIONS const double3 IRockyParticle::get_moment_of_inertia ( ) const
Returns
A 3D vector whose components are the principal values of the particle's moment of inertia tensor.

◆ get_number_of_assembly_parts()

ROCKY_FUNCTIONS size_t IRockyParticle::get_number_of_assembly_parts ( ) const
Returns
The number of parts that compose the assembly.

◆ get_orientation_axis_angle()

ROCKY_FUNCTIONS thrust::tuple< double3, double > IRockyParticle::get_orientation_axis_angle ( ) const
Returns
A tuple whose two components define the axis-angle particle orientation. The first one is a three dimensional vector representing the orientation axis, the second one is a single value representing the angle.

◆ get_orientation_quaternion()

ROCKY_FUNCTIONS double4 IRockyParticle::get_orientation_quaternion ( ) const
Returns
The quaternion that represents the particle's orientation, expressed as a four-dimensional array \((q_r, q_i, q_j, q_k)\).

◆ get_original_mass()

ROCKY_FUNCTIONS double IRockyParticle::get_original_mass ( ) const
Returns
The original value of the mass of a particle when it enters into the simulation.

◆ get_particle_group_index()

ROCKY_FUNCTIONS int IRockyParticle::get_particle_group_index ( ) const
Returns
The index that uniquely identifies the particle group to which the particle belongs.

◆ get_poisson_ratio()

ROCKY_FUNCTIONS double IRockyParticle::get_poisson_ratio ( ) const
Returns
The particle's Poisson's ratio value. If this property was defined as variable in the module's specification file, the method will return the value specifically assigned to the particle. Otherwise, it will return the value specified in the Rocky UI for the particle's associated material.

◆ get_release_time()

ROCKY_FUNCTIONS double IRockyParticle::get_release_time ( ) const
Returns
The time at which the particle was released.

◆ get_resultant_force()

ROCKY_FUNCTIONS double3 IRockyParticle::get_resultant_force ( ) const
Returns
The resultant force vector acting on the particle, in Cartesian coordinates. This force is a combination of the forces calculated during the current time iteration that are applied on the particle, including contact forces, joint forces, fluid forces, and other forces coming from custom modules. If this method is called before the force calculation stage it will return a zero vector.
Attention
The force of gravity acting on the particle is not included in this resultant force.

◆ get_resultant_moment()

ROCKY_FUNCTIONS double3 IRockyParticle::get_resultant_moment ( ) const
Returns
The resultant moment vector applied to the particle, in Cartesian coordinates. The resultant moment is the combination of all moments caused by the forces acting upon the particle, including contact forces, joint forces, fluid forces, and other forces coming from custom modules. If this method is called before the force calculation stage it will return a zero vector.

◆ get_rolling_resistance_coefficient()

ROCKY_FUNCTIONS double IRockyParticle::get_rolling_resistance_coefficient ( ) const
Returns
The particle's rolling resistance coefficient

◆ get_rotational_velocity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_rotational_velocity ( ) const
Returns
The current particle's rotational velocity vector expressed in Cartesian coordinates.

◆ get_scalars() [1/2]

ROCKY_FUNCTIONS IRockyParticleScalars IRockyParticle::get_scalars ( )
Returns
An IRockyParticleScalars object, that gives access to all particle scalars variables defined in the project.

◆ get_scalars() [2/2]

ROCKY_FUNCTIONS const IRockyParticleScalars IRockyParticle::get_scalars ( ) const
Returns
A const IRockyParticleScalars object, that gives access to all particle scalars variables defined in the project.

◆ get_size()

ROCKY_FUNCTIONS double IRockyParticle::get_size ( ) const
Returns
The current value of the particle's size.

◆ get_solid_volume()

ROCKY_FUNCTIONS double IRockyParticle::get_solid_volume ( ) const
Returns
The current value of the particle's solid volume. If the particle is porous (porosity > 0), the solid volume is the volume of the solid matrix. Otherwise, the volume returned by this function will coincide with the one returned by the get_volume function.

◆ get_specific_heat()

ROCKY_FUNCTIONS double IRockyParticle::get_specific_heat ( ) const
Returns
The particle's specific heat value. If this property was defined as variable in the module's specification file, the method will return the value specifically assigned to the particle. Otherwise, it will return the value specified in the Rocky UI for the particle's associated material.

◆ get_sphericity()

ROCKY_FUNCTIONS double IRockyParticle::get_sphericity ( ) const
Returns
The particle's sphericity value, which is defined as the ratio of \(A_s\) to \(A_p\), where \(A_s\) is the surface area of a sphere with the same volume as the particle, whereas \(A_p\) is the surface area of the particle itself. In general terms, the sphericity measures how closely the particle's actual shape resembles the shape of a perfect sphere.

◆ get_strength()

ROCKY_FUNCTIONS double IRockyParticle::get_strength ( ) const
Returns
A random value between 0 and 1 assigned to a particle at the time of generation. This value can be related to the breakage probability in a custom instantaneous breakage model.

◆ get_surface_area()

ROCKY_FUNCTIONS double IRockyParticle::get_surface_area ( ) const
Returns
The current value of the particle's surface area.

◆ get_tag()

ROCKY_FUNCTIONS int IRockyParticle::get_tag ( ) const
Returns
The tag value inherited from the tags assigned to the segments of a custom fiber, if the IRockyParticle object represents an element 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. All elements that arise from the subdivision of a given segment inherit the tag value assigned to that segment. If tags are not defined for a custom fiber or if this function is used with particles which are not elements of a custom fiber, this function will return -1.

◆ get_thermal_conductivity()

ROCKY_FUNCTIONS double IRockyParticle::get_thermal_conductivity ( ) const
Returns
The particle's thermal conductivity. If this property was defined as variable in the module's specification file, the method will return the value specifically assigned to the particle. Otherwise, it will return the value specified in the Rocky UI for the particle's associated material.

◆ get_transfer_scalars()

ROCKY_FUNCTIONS IRockyParticleTransferScalars IRockyParticle::get_transfer_scalars ( )
Returns
An IRockyParticleTransferScalars object, that gives access to all particle transfer scalars variables defined in the project.

◆ get_translational_velocity()

ROCKY_FUNCTIONS double3 IRockyParticle::get_translational_velocity ( ) const
Returns
The current particle's translational velocity vector expressed in Cartesian coordinates.

◆ get_volume()

ROCKY_FUNCTIONS double IRockyParticle::get_volume ( ) const
Returns
The current value of the particle's volume. If the particle is porous (porosity > 0), the volume returned is the particle's total or bulk volume, that is the volume obtained by summing the solid volume and the pore volume.

◆ is_assembly()

ROCKY_FUNCTIONS bool IRockyParticle::is_assembly ( ) const
Returns
True if the given particle is an assembly, false otherwise.

◆ is_element()

ROCKY_FUNCTIONS bool IRockyParticle::is_element ( ) const
Returns
True if the given particle is an element within a flexible particle, false otherwise.

◆ remove()

ROCKY_FUNCTIONS void IRockyParticle::remove ( )
This method removes permanently the particle from the simulation.

◆ remove_from_contacts_search()

ROCKY_FUNCTIONS void IRockyParticle::remove_from_contacts_search ( )
This method disables the detection of all contacts for the particle.

◆ set_frozen()

ROCKY_FUNCTIONS void IRockyParticle::set_frozen ( bool  frozen)
This method sets the frozen state of a particle. When the frozen state of a particle
is set to true, the solution of the motion equations for this particle are skipped afterwards.
Parameters
frozenTrue if the particle should be frozen, false otherwise.

◆ set_poisson_ratio()

ROCKY_FUNCTIONS void IRockyParticle::set_poisson_ratio ( double  value)
This method sets the Poisson's ratio value for the particle. This operation will
be allowed only if Poisson's ratio was defined as a variable property for particles in the module's specification file. Otherwise, a segmentation fault will occur.
Parameters
valueThe Poisson's ratio to be set.

◆ set_specific_heat()

ROCKY_FUNCTIONS void IRockyParticle::set_specific_heat ( double  value)
This method sets the specific heat value for the particle. This operation will
be allowed only if Poisson's ratio was defined as a variable property for particles in the module's specification file. Otherwise, a segmentation fault will occur.
Parameters
valueThe specific heat to be set.

◆ set_thermal_conductivity()

ROCKY_FUNCTIONS void IRockyParticle::set_thermal_conductivity ( double  value)
This method sets the thermal conductivity value for the particle. This operation will
be allowed only if thermal conductivity was defined as a variable property for particles in the module's specification file. Otherwise, a segmentation fault will occur.
Parameters
valueThe thermal conductivity to be set.