raisim::GranularSystem

final class · #include <raisim/object/granular/GranularSystem.hpp>

A discrete-element (DEM) system of spherical particles stepped as one object (create it with World::addGranularParticles() or World::addGranularBox()). Particle contacts use a spring-dashpot normal force with history-based tangential friction and optional rolling friction and cohesion, integrated explicitly in Material::substeps substeps per world step. Particles also collide with world objects (single bodies, compounds, meshes, heightmaps, articulated systems) and with the optional ground plane, container box and periodic boundary set on this object. localIdx is a particle index. Removing a particle moves the last particle into its index.

Nested classes

struct BoxOptions — Parameters of World::addGranularBox(): equal particles on a regular grid inside an axis-aligned box.
struct Material — Material shared by all particles. Mass is density * sphere volume per particle.
struct ParticleMaterial — Per-material-id friction parameters. Pairs with different ids use the geometric mean of their friction.
struct StepStats — Diagnostic counters of the last step (see getLastStepStats()).

Public types

NormalContactModel

cpp

enum class NormalContactModel

Normal elastic force law.

Enumerator	Description
`LINEAR`	F = normalStiffness * overlap.
`HERTZ`	F = normalStiffness * sqrt(effectiveRadius) * overlap^1.5.

Constructors & destructor

GranularSystem

cpp

GranularSystem(
    const std::vector<Vec<3>> &positions,
    const std::vector<double> &radii,
    const Material &material)

Use World::addGranularParticles() instead of constructing it directly.

Parameters

Parameter	Description
`positions` (in)	initial particle centers in the world frame (m); at least one
`radii` (in)	particle radii (m), positive, one per position
`material` (in)	material parameters

Public member functions

getObjectType

cpp

ObjectType getObjectType() const final

Returns GRANULAR.

getNumParticles

cpp

size_t getNumParticles() const

Returns the number of particles.

getPositions

cpp

const std::vector<Vec<3>> &getPositions() const

Returns particle centers in the world frame (m).

getVelocities

cpp

const std::vector<Vec<3>> &getVelocities() const

Returns particle linear velocities in the world frame (m/s).

getAngularVelocities

cpp

const std::vector<Vec<3>> &getAngularVelocities() const

Returns particle angular velocities in the world frame (rad/s).

getRadii

cpp

const std::vector<double> &getRadii() const

Returns particle radii (m).

getParticleMaterialIds

cpp

const std::vector<uint16_t> &getParticleMaterialIds() const

Returns the material id of each particle.

getFixedParticleFlags

cpp

const std::vector<uint8_t> &getFixedParticleFlags() const

Returns 1 for fixed particles, 0 for dynamic ones.

getMaterial

cpp

const Material &getMaterial() const

Returns the shared material.

getBoundaryMaterial

cpp

const ParticleMaterial &getBoundaryMaterial() const

Returns the boundary material (see setBoundaryMaterial()).

getLastStepStats

cpp

const StepStats &getLastStepStats() const

Returns diagnostic counters of the last step.

setParticleMaterial

cpp

void setParticleMaterial(
    uint16_t materialId,
    const ParticleMaterial &material)

Define the friction parameters of a material id. Unset ids below it are filled with Material::friction / rollingFriction.

Parameters

Parameter	Description
`materialId` (in)	material id
`material` (in)	friction parameters (nonnegative)

setParticleMaterialId

cpp

void setParticleMaterialId(size_t localIdx, uint16_t materialId)

Assign a material id to a particle.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`materialId` (in)	material id (undefined ids use Material::friction / rollingFriction)

setBoundaryMaterial

cpp

void setBoundaryMaterial(const ParticleMaterial &material)

Set the material mixed with particle materials for ground, container, mesh, and rigid contacts. The friction used is the geometric mean of the particle and boundary values.

Parameters

Parameter	Description
`material` (in)	boundary friction parameters (nonnegative)

reserveParticles

cpp

void reserveParticles(size_t capacity)

Reserve storage for capacity particles to avoid reallocations when emitting.

Parameters

Parameter	Description
`capacity` (in)	number of particles

addParticle

cpp

size_t addParticle(
    const Vec<3> &position,
    double radius,
    const Vec<3> &velocity=Vec<3>{0.0, 0.0, 0.0},
    const Vec<3> &angularVelocity=Vec<3>{0.0, 0.0, 0.0},
    uint16_t materialId=0,
    bool fixed=false)

Add one particle. Fixed particles keep zero velocity and are treated as static rough-bed particles.

Parameters

Parameter	Description
`position` (in)	center in the world frame (m)
`radius` (in)	radius (m), positive
`velocity` (in)	initial linear velocity (m/s)
`angularVelocity` (in)	initial angular velocity (rad/s)
`materialId` (in)	particle material id
`fixed` (in)	create a fixed particle

Returns the index of the new particle

emitBox

cpp

size_t emitBox(
    const Vec<3> &minCorner,
    const Vec<3> &maxCorner,
    double radius,
    double spacing,
    size_t maxParticles,
    const Vec<3> &velocity=Vec<3>{0.0, 0.0, 0.0},
    const Vec<3> &angularVelocity=Vec<3>{0.0, 0.0, 0.0},
    uint16_t materialId=0,
    bool fixed=false)

Emit a regular grid of particles inside the box. maxParticles bounds this call; zero emits none.

Parameters

Parameter	Description
`minCorner` (in)	minimum box corner in the world frame (m)
`maxCorner` (in)	maximum box corner in the world frame (m)
`radius` (in)	particle radius (m), positive
`spacing` (in)	grid spacing between centers (m), positive
`maxParticles` (in)	maximum number of particles to emit
`velocity` (in)	initial linear velocity (m/s)
`angularVelocity` (in)	initial angular velocity (rad/s)
`materialId` (in)	particle material id
`fixed` (in)	create fixed particles

Returns the number of emitted particles

emitBoxRandom

cpp

size_t emitBoxRandom(
    const Vec<3> &minCorner,
    const Vec<3> &maxCorner,
    double minRadius,
    double maxRadius,
    double spacing,
    size_t maxParticles,
    uint64_t seed,
    const Vec<3> &velocity=Vec<3>{0.0, 0.0, 0.0},
    const Vec<3> &angularVelocity=Vec<3>{0.0, 0.0, 0.0},
    uint16_t materialId=0,
    bool fixed=false)

Emit a deterministic jittered grid with radii sampled in [minRadius, maxRadius].

Parameters

Parameter	Description
`minCorner` (in)	minimum box corner in the world frame (m)
`maxCorner` (in)	maximum box corner in the world frame (m)
`minRadius` (in)	minimum radius (m), positive
`maxRadius` (in)	maximum radius (m), at least minRadius
`spacing` (in)	grid spacing (m), at least 2 * maxRadius
`maxParticles` (in)	maximum number of particles to emit
`seed` (in)	random seed; the same seed gives the same particles
`velocity` (in)	initial linear velocity (m/s)
`angularVelocity` (in)	initial angular velocity (rad/s)
`materialId` (in)	particle material id
`fixed` (in)	create fixed particles

Returns the number of emitted particles

removeParticle

cpp

void removeParticle(size_t localIdx)

Remove a particle. The last particle is moved into localIdx, so indices of other particles may change. Tendons attached to particles are updated by the world.

Parameters

Parameter	Description
`localIdx` (in)	particle index

removeParticlesBelowZ

cpp

size_t removeParticlesBelowZ(double zThreshold)

Remove every particle whose center is below zThreshold.

Parameters

Parameter	Description
`zThreshold` (in)	z threshold in the world frame (m)

Returns the number of removed particles

removeParticlesInBox

cpp

size_t removeParticlesInBox(
    const Vec<3> &minCorner,
    const Vec<3> &maxCorner)

Remove particles whose centers are inside the closed axis-aligned box.

Parameters

Parameter	Description
`minCorner` (in)	minimum corner in the world frame (m)
`maxCorner` (in)	maximum corner in the world frame (m)

Returns the number of removed particles

saveGranularState

cpp

void saveGranularState(
    const std::string &path,
    bool includeContactHistories=true) const

Save a binary granular checkpoint. Contact histories are optional because they can be large.

Parameters

Parameter	Description
`path` (in)	output file
`includeContactHistories` (in)	also save tangential contact histories

loadGranularState

cpp

void loadGranularState(const std::string &path)

Load a checkpoint produced by saveGranularState. Boundary settings such as ground/container are not serialized. Tendons attached to the particles stay on them, known by the id each particle got when added; a tendon on a particle the checkpoint does not hold is removed.

Parameters

Parameter	Description
`path` (in)	checkpoint file

Exceptions

Exception	Description
`std::logic_error`	during a split integration step if a tendon is attached to this system

setVelocity

cpp

void setVelocity(size_t localIdx, const Vec<3> &velocity)

Set a particle's linear velocity (ignored for fixed particles).

Parameters

Parameter	Description
`localIdx` (in)	particle index
`velocity` (in)	velocity in the world frame (m/s)

setAngularVelocity

cpp

void setAngularVelocity(size_t localIdx, const Vec<3> &angularVelocity)

Set a particle's angular velocity (ignored for fixed particles).

Parameters

Parameter	Description
`localIdx` (in)	particle index
`angularVelocity` (in)	angular velocity in the world frame (rad/s)

setParticleFixed

cpp

void setParticleFixed(size_t localIdx, bool fixed)

Toggle a particle between dynamic and fixed; fixed particles ignore velocity and external-force setters. Fixing a particle zeroes its velocities and pending forces.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`fixed` (in)	true to fix the particle

setGroundPlane

cpp

void setGroundPlane(double height, bool enabled=true)

Set a horizontal ground plane z = height that only the particles collide with (uses the boundary material).

Parameters

Parameter	Description
`height` (in)	plane height in the world frame (m)
`enabled` (in)	enable or disable the plane

disableGroundPlane

cpp

void disableGroundPlane()

Disable the ground plane set by setGroundPlane().

setContainerBox

cpp

void setContainerBox(
    const Vec<3> &minCorner,
    const Vec<3> &maxCorner,
    bool enabled=true)

Confine the particles in an axis-aligned box with an open top (four side walls and a floor; uses the boundary material).

Parameters

Parameter	Description
`minCorner` (in)	minimum corner in the world frame (m)
`maxCorner` (in)	maximum corner in the world frame (m); strictly above minCorner on every axis
`enabled` (in)	enable or disable the container

disableContainerBox

cpp

void disableContainerBox()

Disable the container set by setContainerBox().

setPeriodicBoundary

cpp

void setPeriodicBoundary(
    const Vec<3> &minCorner,
    const Vec<3> &maxCorner,
    bool x,
    bool y,
    bool z)

Wrap particle centers in enabled axes after integration. minCorner must be below maxCorner on every axis (also disabled ones).

Parameters

Parameter	Description
`minCorner` (in)	minimum corner of the periodic cell (m)
`maxCorner` (in)	maximum corner of the periodic cell (m)
`x` (in)	wrap along x
`y` (in)	wrap along y
`z` (in)	wrap along z

disablePeriodicBoundary

cpp

void disablePeriodicBoundary()

Disable the periodic boundary on all axes.

prepareWorldContacts

cpp

void prepareWorldContacts(World &world)

Internal: advances the DEM substeps before the rigid-body solve (called by World).

Parameters

Parameter	Description
`world` (in)	the owning world

updateCollision

cpp

void updateCollision() final

Internal: synchronizes the collision geometry with the current pose.

updateContactAabbs

cpp

void updateContactAabbs() final

Internal: recomputes the world-frame AABBs used by the broadphase.

preContactSolverUpdate1

cpp

void preContactSolverUpdate1(const Vec<3> &gravity, double dt) final

Internal: first per-step update before the contact solver (called by World).

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration (m/s^2)
`dt` (in)	time step (s)

preContactSolverUpdate2

cpp

void preContactSolverUpdate2(
    const Vec<3> &gravity,
    double dt,
    contact::ContactProblems &problems) final

Internal: second per-step update before the contact solver (called by World).

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration (m/s^2)
`dt` (in)	time step (s)
`problems` (in, out)	contact problems of the world

integrate

cpp

void integrate(double dt, World &world) final

Internal: integrates the state after the contact solve (called by World).

Parameters

Parameter	Description
`dt` (in)	time step (s)
`world` (in)	the owning world

setExternalForce

cpp

void setExternalForce(size_t localIdx, const Vec<3> &force) final

apply forces at the Center of Mass

Parameters

Parameter	Description
`localIdx` (in)	local body index
`force` (in)	force in the world frame (N)

cpp

void setExternalForce(
    size_t localIdx,
    const Vec<3> &pos,
    const Vec<3> &force) final

Same as setExternalForce(size_t, const Vec<3>&): the force acts at the particle center and pos is only recorded. Ignored for fixed particles.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos` (in)	application point (recorded only)
`force` (in)	force in the world frame (N)

setExternalTorque

cpp

void setExternalTorque(size_t localIdx, const Vec<3> &torque) final

apply torque on a body

Parameters

Parameter	Description
`localIdx` (in)	local body index
`torque` (in)	torque in the world frame (Nm)

setConstraintForce

cpp

void setConstraintForce(
    size_t localIdx,
    const Vec<3> &pos,
    const Vec<3> &force) final

Internal: apply a constraint force (expressed in the world frame) at specific location of the body (expressed in the body frame). Unlike setExternalForce(), it is not visualized.

Parameters

Parameter	Description
`localIdx` (in)	local body index
`pos` (in)	application point in the body frame
`force` (in)	force in the world frame (N)

getMass

cpp

double getMass(size_t localIdx) const final

Parameters

Parameter	Description
`localIdx` (in)	local body (or particle) index

Returns the mass of the local body (kg)

getBodyType

cpp

BodyType getBodyType(size_t localIdx) const final

Parameters

Parameter	Description
`localIdx` (in)	particle index

Returns STATIC for fixed particles, DYNAMIC otherwise

getPosition

cpp

void getPosition(size_t localIdx, Vec<3> &pos_w) const final

get the position of a local body (its body frame origin) or particle.

Parameters

Parameter	Description
`localIdx` (in)	local body (or particle) index
`pos_w` (out)	position in the world frame (m)

cpp

void getPosition(
    size_t localIdx,
    const Vec<3> &pos_b,
    Vec<3> &pos_w) const final

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos_b` (in)	offset from the particle center (world-aligned, since particles have no orientation)
`pos_w` (out)	particle center + pos_b

getVelocity

cpp

void getVelocity(size_t localIdx, Vec<3> &vel_w) const final

get the linear velocity of a local body or particle.

Parameters

Parameter	Description
`localIdx` (in)	local body (or particle) index
`vel_w` (out)	linear velocity in the world frame (m/s)

cpp

void getVelocity(
    size_t localIdx,
    const Vec<3> &pos_b,
    Vec<3> &vel_w) const final

Returns the particle's linear velocity; pos_b is ignored.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos_b` (in)	ignored
`vel_w` (out)	linear velocity in the world frame (m/s)

getOrientation

cpp

void getOrientation(size_t localIdx, Mat<3, 3> &rot) const final

Particles have no orientation state: rot is always the identity.

Parameters

Parameter	Description
`localIdx` (in)	unused
`rot` (out)	identity

getContactPointVel

cpp

void getContactPointVel(size_t pointId, Vec<3> &vel) const final

Internal: returns the linear velocity of particle pointId in the world frame.

Parameters

Parameter	Description
`pointId` (in)	particle index
`vel` (out)	velocity

clearExternalForcesAndTorques

cpp

void clearExternalForcesAndTorques() final

Remove all external forces and torques set for the next step.

Inherited members

From raisim::Object: addContactToPerObjectContact, clearPerObjectContact, getContactAabb, getContactAabbCount, getContacts, getExternalForce, getExternalForcePosition, getExternalTorque, getExternalTorquePosition, getId, getIndexInWorld, getName, getRenderRevision, Id, lock, lockMutex, setIndexInWorld, setName, try_lock, unlock, unlockMutex

AlignedAllocator

Rasset

RayCollisionList

World

Compound

Mesh

FileCache

ArticulatedSystem

DeformableTerrain

DeformableObject

GranularPoolSleepController

GranularSystem

Tendon

TendonCoupling

DepthCamera

InertialMeasurementUnit

RGBCamera

SpinningLidar

contact

BisectionContactSolver

mjcf

rscene

server

SceneFileServer

server::scene_files

urdf

raisim::GranularSystem ​

Nested classes ​

Public types ​

NormalContactModel ​

Constructors & destructor ​

GranularSystem ​

Public member functions ​

getObjectType ​

getNumParticles ​

getPositions ​

getVelocities ​

getAngularVelocities ​

getRadii ​

getParticleMaterialIds ​

getFixedParticleFlags ​

getMaterial ​

getBoundaryMaterial ​

getLastStepStats ​

setParticleMaterial ​

setParticleMaterialId ​

setBoundaryMaterial ​

reserveParticles ​

addParticle ​

emitBox ​

emitBoxRandom ​

removeParticle ​

removeParticlesBelowZ ​

removeParticlesInBox ​

saveGranularState ​

loadGranularState ​

setVelocity ​

setAngularVelocity ​

setParticleFixed ​

setGroundPlane ​

disableGroundPlane ​

setContainerBox ​

disableContainerBox ​

setPeriodicBoundary ​

disablePeriodicBoundary ​

prepareWorldContacts ​

updateCollision ​

updateContactAabbs ​

preContactSolverUpdate1 ​

preContactSolverUpdate2 ​

integrate ​

setExternalForce ​

setExternalTorque ​

setConstraintForce ​

getMass ​

getBodyType ​

getPosition ​

getVelocity ​

getOrientation ​

getContactPointVel ​

raisim::GranularSystem

Nested classes

Public types

NormalContactModel

Constructors & destructor

GranularSystem

Public member functions

getObjectType

getNumParticles

getPositions

getVelocities

getAngularVelocities

getRadii

getParticleMaterialIds

getFixedParticleFlags

getMaterial

getBoundaryMaterial

getLastStepStats

setParticleMaterial

setParticleMaterialId

setBoundaryMaterial

reserveParticles

addParticle

emitBox

emitBoxRandom

removeParticle

removeParticlesBelowZ

removeParticlesInBox

saveGranularState

loadGranularState

setVelocity

setAngularVelocity

setParticleFixed

setGroundPlane

disableGroundPlane

setContainerBox

disableContainerBox

setPeriodicBoundary

disablePeriodicBoundary

prepareWorldContacts

updateCollision

updateContactAabbs

preContactSolverUpdate1

preContactSolverUpdate2

integrate

setExternalForce

setExternalTorque

setConstraintForce

getMass

getBodyType

getPosition

getVelocity

getOrientation

getContactPointVel

clearExternalForcesAndTorques

Inherited members