Structure IRockyParticle
Last update: 09.03.2026
#include
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.
Members
- add_force
- add_moment
- add_to_contacts_search
- disable_related_particle_contacts
- disable_related_triangle_contacts
- enable_related_particle_contacts
- enable_related_triangle_contacts
- get_assembly_part_material
- get_breakage_scalars
- get_centroid_position
- get_cgm_scale_factor
- get_equivalent_diameter
- get_gravity
- get_impact_energy
- get_mass
- get_material
- get_material_index
- get_moment_of_inertia
- get_number_of_assembly_parts
- get_orientation_axis_angle
- get_orientation_quaternion
- get_original_mass
- get_particle_group_index
- get_poisson_ratio
- get_release_time
- get_resultant_force
- get_resultant_moment
- get_rolling_resistance_coefficient
- get_rotational_velocity
- get_scalars
- get_scalars
- get_size
- get_solid_volume
- get_specific_heat
- get_sphericity
- get_strength
- get_surface_area
- get_tag
- get_thermal_conductivity
- get_transfer_scalars
- get_translational_velocity
- get_volume
- is_assembly
- is_element
- remove
- remove_from_contacts_search
- set_frozen
- set_poisson_ratio
- set_specific_heat
- set_thermal_conductivity
Public functions
Function 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.
Return type: ROCKY_FUNCTIONS IRockyMaterial
Function get_centroid_position
ROCKY_FUNCTIONS double3 IRockyParticle::get_centroid_position() const
Returns:
The Cartesian coordinates of the current position of the particle's centroid.
Return type: ROCKY_FUNCTIONS double3
Function 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.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS double
Function get_size
ROCKY_FUNCTIONS double IRockyParticle::get_size() const
Returns:
The current value of the particle's size.
Return type: ROCKY_FUNCTIONS double
Function get_release_time
ROCKY_FUNCTIONS double IRockyParticle::get_release_time() const
Returns:
The time at which the particle was released.
Return type: ROCKY_FUNCTIONS double
Function get_cgm_scale_factor
ROCKY_FUNCTIONS double IRockyParticle::get_cgm_scale_factor() const
Returns:
The particle's Coarse-grain Modeling (CGM) scale factor.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS double
Function get_surface_area
ROCKY_FUNCTIONS double IRockyParticle::get_surface_area() const
Returns:
The current value of the particle's surface area.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS double
Function get_sphericity
ROCKY_FUNCTIONS double IRockyParticle::get_sphericity() const
Returns:
The particle's sphericity value, which is defined as the ratio of formula {"type":"element","name":"formula","attributes":{"id":"0"},"children":[{"type":"text","text":"$A_s$"}]} to formula {"type":"element","name":"formula","attributes":{"id":"1"},"children":[{"type":"text","text":"$A_p$"}]}, where formula {"type":"element","name":"formula","attributes":{"id":"0"},"children":[{"type":"text","text":"$A_s$"}]} is the surface area of a sphere with the same volume as the particle, whereas formula {"type":"element","name":"formula","attributes":{"id":"1"},"children":[{"type":"text","text":"$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.
Return type: ROCKY_FUNCTIONS double
Function get_translational_velocity
ROCKY_FUNCTIONS double3 IRockyParticle::get_translational_velocity() const
Returns:
The current particle's translational velocity vector expressed in Cartesian coordinates.
Return type: ROCKY_FUNCTIONS double3
Function get_rotational_velocity
ROCKY_FUNCTIONS double3 IRockyParticle::get_rotational_velocity() const
Returns:
The current particle's rotational velocity vector expressed in Cartesian coordinates.
Return type: ROCKY_FUNCTIONS double3
Function 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.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS double
Function get_gravity
ROCKY_FUNCTIONS double3 IRockyParticle::get_gravity() const
Returns:
The gravitational acceleration vector in Cartesian coordinates.
Return type: ROCKY_FUNCTIONS double3
Function 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.
Return type: ROCKY_FUNCTIONS int
Function get_material_index
ROCKY_FUNCTIONS int IRockyParticle::get_material_index() const
Returns:
The material index associated to that particle
Return type: ROCKY_FUNCTIONS int
Function get_rolling_resistance_coefficient
ROCKY_FUNCTIONS double IRockyParticle::get_rolling_resistance_coefficient() const
Returns:
The particle's rolling resistance coefficient
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS thrust::tuple double3, double >
Function 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 formula {"type":"element","name":"formula","attributes":{"id":"2"},"children":[{"type":"text","text":"$(q_r, q_i, q_j, q_k)$"}]}.
Return type: ROCKY_FUNCTIONS double4
Function 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.
Return type: ROCKY_FUNCTIONS double3
Function 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.
Return type: ROCKY_FUNCTIONS double3
Function 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.
Return type: ROCKY_FUNCTIONS double
Function 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:
- value: The thermal conductivity to be set.
Parameters:
- double value
Return type: ROCKY_FUNCTIONS void
Function 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.
Return type: ROCKY_FUNCTIONS double
Function 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:
- value: The Poisson's ratio to be set.
Parameters:
- double value
Return type: ROCKY_FUNCTIONS void
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.
Return type: ROCKY_FUNCTIONS double
Function 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.
Return type: ROCKY_FUNCTIONS int
Function 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:
- value: The specific heat to be set.
Parameters:
- double value
Return type: ROCKY_FUNCTIONS void
Function get_scalars
ROCKY_FUNCTIONS IRockyParticleScalars IRockyParticle::get_scalars()
Returns:
An IRockyParticleScalars object, that gives access to all particle scalars variables defined in the project.
Return type: ROCKY_FUNCTIONS IRockyParticleScalars
Function get_scalars
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.
Return type: ROCKY_FUNCTIONS const IRockyParticleScalars
Function 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.
Return type: ROCKY_FUNCTIONS IRockyParticleTransferScalars
Function 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.
Return type: ROCKY_FUNCTIONS IRockyParticleBreakageScalars
Function remove
ROCKY_FUNCTIONS void IRockyParticle::remove()
This method removes permanently the particle from the simulation.:
Return type: ROCKY_FUNCTIONS void
Function 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:
- force: The custom force vector in Cartesian coordinates.
Parameters:
- const double3 & force
Return type: ROCKY_FUNCTIONS void
Function 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:
- moment: The custom moment vector in Cartesian coordinates.
Parameters:
- const double3 & moment
Return type: ROCKY_FUNCTIONS void
Function 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:
- frozen: True if the particle should be frozen, false otherwise.
Parameters:
- bool frozen
Return type: ROCKY_FUNCTIONS void
Function 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.
Return type: ROCKY_FUNCTIONS void
Function 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
Return type: ROCKY_FUNCTIONS void
Function 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.:
Return type: ROCKY_FUNCTIONS void
Function 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.:
Return type: ROCKY_FUNCTIONS void
Function 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.
Return type: ROCKY_FUNCTIONS const double3
Function is_element
ROCKY_FUNCTIONS bool IRockyParticle::is_element() const
Returns:
True if the given particle is an element within a flexible particle, false otherwise.
Return type: ROCKY_FUNCTIONS bool
Function is_assembly
ROCKY_FUNCTIONS bool IRockyParticle::is_assembly() const
Returns:
True if the given particle is an assembly, false otherwise.
Return type: ROCKY_FUNCTIONS bool
Function 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.
Return type: ROCKY_FUNCTIONS size_t
Function get_assembly_part_material
ROCKY_FUNCTIONS IRockyMaterial IRockyParticle::get_assembly_part_material(size_t part_id) const
Parameters:
- part_id: The 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.
Parameters:
- size_t part_id
Return type: ROCKY_FUNCTIONS IRockyMaterial
Function remove_from_contacts_search
ROCKY_FUNCTIONS void IRockyParticle::remove_from_contacts_search()
This method disables the detection of all contacts for the particle.:
Return type: ROCKY_FUNCTIONS void
Function add_to_contacts_search
ROCKY_FUNCTIONS void IRockyParticle::add_to_contacts_search()
This method enables the detection of all contacts for the particle.:
Return type: ROCKY_FUNCTIONS void
[const]: https://img.shields.io/badge/-const-lightblue (const)
