peclet-dem 0.4.0
Performance-portable XPBD Discrete Element Method (Kokkos + ArborX)
Loading...
Searching...
No Matches
peclet::dem::Simulation Class Reference

Host-facing facade with std::vector setters/getters (binding-agnostic). More...

#include <sim.hpp>

Public Member Functions

 Simulation (int capacity)
 
 ~Simulation ()
 
void releaseViews ()
 
void setSphereShape (float radius)
 
void initializeShape (int shape_type, float radius, float height, float thickness)
 
void setSdfShape (const std::vector< float > &grid, int nx, int ny, int nz, F3 origin, F3 spacing, const std::vector< float > &shellFlat, F3 invInertia, float boundingRadius)
 
void setDomain (float lx, float ly, float lz, bool px, bool py, bool pz)
 
void setDomainMinMax (F3 mn, F3 mx)
 
void enablePeriodicity (bool x, bool y, bool z)
 
std::tuple< float, float, float > getDomainMin () const
 
std::tuple< float, float, float > getDomainMax () const
 
void setGravity (float gx, float gy, float gz)
 
void setThermostat (float temperature, float tau, float kB)
 
void setSolverIterations (int pos, int vel)
 
void setVelocityUseGS (bool useGS)
 
void setStabilization (bool enabled)
 Enable/disable the stabilization pass (default on).
 
void setStabilizationMode (const std::string &mode)
 Select the stabilization pass of the staged velocity solve: "off" (pure symmetric PGS), "onesided" (default: held-lower-side grounded impulses – arrests any collapse but is a momentum sink), "multilevel" (GraphMG contact-graph aggregation: coarse inelastic solves at super-body masses – momentum-conserving transport acceleration), "escalate" (extra symmetric sweeps up to 256; diagnostic/fallback), "ordered" (level-ordered symmetric sweeps; measurement mode, known insufficient for deep columns).
 
void setRestitutionModel (const std::string &model)
 Restitution model of the PGS velocity solve: "newton" (default; per-substep restitution on the pre-solve approach — the pre-existing behaviour) or "poisson" (event-level: each pair banks its kinetic compression impulse and releases e x the bank as a budget-capped separation-velocity target during unloading — restores the multi-substep-impact rebound that per-substep Newton structurally cannot return).
 
void setSleeping (bool enabled, float threshold_scale=2.0f, int consecutive=64, float wake_scale=40.0f)
 Island sleeping / freezing (single-GPU statics, default ON; PECLET_DEM_SLEEP=0 disables).
 
void setVerletSkin (float skin_frac)
 Verlet-cached impulse broadphase (single-GPU, non-periodic; default OFF).
 
int numAsleep ()
 Number of currently-sleeping real bodies (diagnostics / tests).
 
void setHertzMaterial (int mat, float youngs, float poisson)
 Per-material Young's modulus + Poisson ratio for the Hertz-Mindlin engine (material ids as in setMaterialIds; without ids every particle is material 0).
 
void stepHertz (float dt, int substeps, float skin_frac)
 Advance substeps explicit soft-sphere Hertz-Mindlin steps of size dt (device-side loop; the (e, mu) pairs come from the impulse solver's material tables).
 
void setGlobalScale (float s)
 
void setDt (float dt)
 
void setMaterialParams (float restitution_normal, float restitution_tangent, float friction)
 
void setMaterialIds (const std::vector< int > &ids)
 Per-particle material ids (0..kMaxMaterials-1); pair (e, mu) values come from setPairMaterial.
 
void setPairMaterial (int a, int b, float restitution, float friction)
 Set the symmetric pair material (restitution, friction) for material ids (a, b).
 
void setWallMaterialId (int wid, int mat)
 Give an SDF wall a material id so particle-wall (e, mu) also resolves via the pair table.
 
void addPlane (float px, float py, float pz, float nx, float ny, float nz)
 
int addSdfWall (const std::vector< float > &grid, int nx, int ny, int nz, F3 origin, F3 spacing, float restitution, float friction)
 
void setWallVelocity (int wallIndex, F3 linVel, F3 angVel, F3 center)
 
void setPositions (const std::vector< float > &xyz)
 
void setScalesUniform (float s)
 
void setScales (const std::vector< float > &s)
 
void setVelocities (const std::vector< float > &v)
 
void setExternalForces (const std::vector< float > &f)
 
void clearExternalForces ()
 
const V3externalForcesView () const
 
const VfinvMassView () const
 
void setQuaternions (const std::vector< float > &q)
 
void setAngularVelocities (const std::vector< float > &w)
 
void setInvInertia (const std::vector< float > &ii)
 
void setInvMass (const std::vector< float > &im)
 
std::vector< float > getAngularVelocities () const
 
std::vector< float > getInvInertia () const
 
void setGrowthParams (float rate, float new_factor)
 
float growthFactor () const
 
float getGrowthRate () const
 
std::vector< float > getMasses () const
 
std::vector< float > getPositions () const
 
std::vector< float > getVelocities () const
 
std::vector< float > getQuaternions () const
 
std::vector< float > getScales () const
 
void step (float dt)
 
float computeOverlaps ()
 
void exportLammps (const std::string &filename, int step) const
 
void exportSdf (const std::string &filename, int rx, int ry, int rz)
 
std::vector< float > getSdfGrid (int rx, int ry, int rz)
 
int numParticles () const
 
const V3positionsView () const
 
const V3velocitiesView () const
 
int numContacts ()
 
int numManifolds ()
 
std::pair< int, int > debugColoringConflicts ()
 
float maxOverlap ()
 
std::tuple< double, float, int > restBankStats ()
 Poisson-restitution diagnostics: (sum, max, count>0) of the committed per-pair owed separation impulse (prevRestBank[0:prevPairCount], physical units).
 
std::tuple< double, float, int > restOrphanStats ()
 Orphan-account diagnostics: (sum, max, count>0) of the per-body orphaned budget.
 
void writeVtp (const std::string &filename) const
 

Static Public Member Functions

static void releaseAll ()
 
static std::vector< Simulation * > & registry ()
 

Detailed Description

Host-facing facade with std::vector setters/getters (binding-agnostic).

Definition at line 407 of file sim.hpp.

Constructor & Destructor Documentation

◆ Simulation()

◆ ~Simulation()

peclet::dem::Simulation::~Simulation ( )
inline

Definition at line 437 of file sim.hpp.

References registry().

Member Function Documentation

◆ releaseViews()

void peclet::dem::Simulation::releaseViews ( )
inline

Definition at line 446 of file sim.hpp.

◆ releaseAll()

static void peclet::dem::Simulation::releaseAll ( )
inlinestatic

Definition at line 454 of file sim.hpp.

References registry().

Referenced by NB_MODULE().

◆ registry()

static std::vector< Simulation * > & peclet::dem::Simulation::registry ( )
inlinestatic

Definition at line 458 of file sim.hpp.

Referenced by releaseAll(), Simulation(), and ~Simulation().

◆ setSphereShape()

void peclet::dem::Simulation::setSphereShape ( float  radius)
inline

Definition at line 463 of file sim.hpp.

References initializeShape(), and peclet::dem::SPHERE.

Referenced by NB_MODULE(), and Simulation().

◆ initializeShape()

void peclet::dem::Simulation::initializeShape ( int  shape_type,
float  radius,
float  height,
float  thickness 
)
inline

◆ setSdfShape()

void peclet::dem::Simulation::setSdfShape ( const std::vector< float > &  grid,
int  nx,
int  ny,
int  nz,
F3  origin,
F3  spacing,
const std::vector< float > &  shellFlat,
F3  invInertia,
float  boundingRadius 
)
inline

◆ setDomain()

void peclet::dem::Simulation::setDomain ( float  lx,
float  ly,
float  lz,
bool  px,
bool  py,
bool  pz 
)
inline

◆ setDomainMinMax()

◆ enablePeriodicity()

void peclet::dem::Simulation::enablePeriodicity ( bool  x,
bool  y,
bool  z 
)
inline

◆ getDomainMin()

std::tuple< float, float, float > peclet::dem::Simulation::getDomainMin ( ) const
inline

◆ getDomainMax()

std::tuple< float, float, float > peclet::dem::Simulation::getDomainMax ( ) const
inline

◆ setGravity()

void peclet::dem::Simulation::setGravity ( float  gx,
float  gy,
float  gz 
)
inline

Definition at line 632 of file sim.hpp.

References peclet::dem::Particles::gravity.

Referenced by NB_MODULE().

◆ setThermostat()

void peclet::dem::Simulation::setThermostat ( float  temperature,
float  tau,
float  kB 
)
inline

◆ setSolverIterations()

void peclet::dem::Simulation::setSolverIterations ( int  pos,
int  vel 
)
inline

◆ setVelocityUseGS()

void peclet::dem::Simulation::setVelocityUseGS ( bool  useGS)
inline

Definition at line 644 of file sim.hpp.

References peclet::dem::Particles::velocityUseGS.

Referenced by NB_MODULE().

◆ setStabilization()

void peclet::dem::Simulation::setStabilization ( bool  enabled)
inline

Enable/disable the stabilization pass (default on).

Off = pure momentum-conserving PGS everywhere – exact ballistic response, but deep static columns mid-collapse cannot be arrested within the iteration budget. Backward-compatible boolean form of setStabilizationMode: true selects "onesided", false selects "off".

Definition at line 649 of file sim.hpp.

References peclet::dem::Particles::stabilizationMode.

Referenced by NB_MODULE().

◆ setStabilizationMode()

void peclet::dem::Simulation::setStabilizationMode ( const std::string &  mode)
inline

Select the stabilization pass of the staged velocity solve: "off" (pure symmetric PGS), "onesided" (default: held-lower-side grounded impulses – arrests any collapse but is a momentum sink), "multilevel" (GraphMG contact-graph aggregation: coarse inelastic solves at super-body masses – momentum-conserving transport acceleration), "escalate" (extra symmetric sweeps up to 256; diagnostic/fallback), "ordered" (level-ordered symmetric sweeps; measurement mode, known insufficient for deep columns).

Definition at line 656 of file sim.hpp.

References peclet::dem::Particles::stabilizationMode.

Referenced by NB_MODULE().

◆ setRestitutionModel()

void peclet::dem::Simulation::setRestitutionModel ( const std::string &  model)
inline

Restitution model of the PGS velocity solve: "newton" (default; per-substep restitution on the pre-solve approach — the pre-existing behaviour) or "poisson" (event-level: each pair banks its kinetic compression impulse and releases e x the bank as a budget-capped separation-velocity target during unloading — restores the multi-substep-impact rebound that per-substep Newton structurally cannot return).

PECLET_DEM_REST_MODEL overrides at startup.

Definition at line 677 of file sim.hpp.

References peclet::dem::Particles::restitutionModel.

Referenced by NB_MODULE(), and Simulation().

◆ setSleeping()

void peclet::dem::Simulation::setSleeping ( bool  enabled,
float  threshold_scale = 2.0f,
int  consecutive = 64,
float  wake_scale = 40.0f 
)
inline

Island sleeping / freezing (single-GPU statics, default ON; PECLET_DEM_SLEEP=0 disables).

A REAL body whose linear AND angular motion stays below scale x the resting floor (2 dt |g|) for K substeps while grounded is put to sleep: velocity zeroed, integration skipped, and a manifold whose BOTH endpoints are asleep (a static wall counts) is excluded from the colouring / sweeps / multilevel hierarchy — so a settled bed collapses to the broad/narrow-phase floor. A sleeper keeps a small POSITIVE effective inverse mass in the solve (sleepImmovableFrac x its own; heavy but not perfectly rigid), so an awake body wedged between sleepers relieves against them instead of the PGS normal impulse diverging; its velocity is re-zeroed each substep so no momentum accumulates. It wakes only when disturbed (fast approaching neighbour, contact-set change, moving wall). Requires gravity on and no external (CFD-DEM drag) force; inert under MPI. PECLET_DEM_SLEEP overrides at startup.

Definition at line 698 of file sim.hpp.

References peclet::dem::Particles::sleepingEnabled, peclet::dem::Particles::sleepK, peclet::dem::Particles::sleepScale, and peclet::dem::Particles::wakeScale.

Referenced by NB_MODULE().

◆ setVerletSkin()

void peclet::dem::Simulation::setVerletSkin ( float  skin_frac)
inline

Verlet-cached impulse broadphase (single-GPU, non-periodic; default OFF).

skin_frac is the broadphase-skin fraction of the max grain radius: the ArborX rebuild is skipped while no particle has moved more than skin/2, so between rebuilds the candidate list is a superset and the narrowphase yields identical contacts. Composes with sleeping (a frozen bed never rebuilds).

Definition at line 713 of file sim.hpp.

References peclet::dem::Particles::impNumPairs, and peclet::dem::Particles::verletSkinFrac.

Referenced by NB_MODULE().

◆ numAsleep()

int peclet::dem::Simulation::numAsleep ( )
inline

Number of currently-sleeping real bodies (diagnostics / tests).

Definition at line 718 of file sim.hpp.

References peclet::dem::Particles::asleep, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ setHertzMaterial()

void peclet::dem::Simulation::setHertzMaterial ( int  mat,
float  youngs,
float  poisson 
)
inline

Per-material Young's modulus + Poisson ratio for the Hertz-Mindlin engine (material ids as in setMaterialIds; without ids every particle is material 0).

Definition at line 728 of file sim.hpp.

References peclet::dem::Particles::hertzE, and peclet::dem::Particles::hertzNu.

Referenced by NB_MODULE().

◆ stepHertz()

void peclet::dem::Simulation::stepHertz ( float  dt,
int  substeps,
float  skin_frac 
)
inline

Advance substeps explicit soft-sphere Hertz-Mindlin steps of size dt (device-side loop; the (e, mu) pairs come from the impulse solver's material tables).

Definition at line 742 of file sim.hpp.

References peclet::dem::demStepHertz(), and peclet::dem::Particles::dt.

Referenced by NB_MODULE().

◆ setGlobalScale()

void peclet::dem::Simulation::setGlobalScale ( float  s)
inline

Definition at line 746 of file sim.hpp.

References peclet::dem::Particles::globalScale, and peclet::dem::Particles::skin.

Referenced by NB_MODULE().

◆ setDt()

void peclet::dem::Simulation::setDt ( float  dt)
inline

Definition at line 750 of file sim.hpp.

References peclet::dem::Particles::dt.

Referenced by NB_MODULE().

◆ setMaterialParams()

void peclet::dem::Simulation::setMaterialParams ( float  restitution_normal,
float  restitution_tangent,
float  friction 
)
inline

◆ setMaterialIds()

void peclet::dem::Simulation::setMaterialIds ( const std::vector< int > &  ids)
inline

Per-particle material ids (0..kMaxMaterials-1); pair (e, mu) values come from setPairMaterial.

Ids default to 0; without any setPairMaterial call the global material applies everywhere.

Definition at line 762 of file sim.hpp.

References peclet::dem::Particles::materialId, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ setPairMaterial()

void peclet::dem::Simulation::setPairMaterial ( int  a,
int  b,
float  restitution,
float  friction 
)
inline

Set the symmetric pair material (restitution, friction) for material ids (a, b).

The first call allocates the pair table, initialised from the current global material for every pair.

Definition at line 771 of file sim.hpp.

References peclet::dem::Particles::frictionDynamic, peclet::dem::kMaxMaterials, peclet::dem::Particles::pairMaterials, and peclet::dem::Particles::restitutionNormal.

Referenced by NB_MODULE().

◆ setWallMaterialId()

void peclet::dem::Simulation::setWallMaterialId ( int  wid,
int  mat 
)
inline

Give an SDF wall a material id so particle-wall (e, mu) also resolves via the pair table.

Definition at line 793 of file sim.hpp.

References peclet::dem::Particles::numWalls, and peclet::dem::Particles::walls.

Referenced by NB_MODULE().

◆ addPlane()

void peclet::dem::Simulation::addPlane ( float  px,
float  py,
float  pz,
float  nx,
float  ny,
float  nz 
)
inline

Definition at line 801 of file sim.hpp.

References peclet::dem::Particles::numPlanes, and peclet::dem::Particles::planes.

Referenced by NB_MODULE().

◆ addSdfWall()

int peclet::dem::Simulation::addSdfWall ( const std::vector< float > &  grid,
int  nx,
int  ny,
int  nz,
F3  origin,
F3  spacing,
float  restitution,
float  friction 
)
inline

◆ setWallVelocity()

void peclet::dem::Simulation::setWallVelocity ( int  wallIndex,
F3  linVel,
F3  angVel,
F3  center 
)
inline

Definition at line 857 of file sim.hpp.

Referenced by NB_MODULE().

◆ setPositions()

◆ setScalesUniform()

void peclet::dem::Simulation::setScalesUniform ( float  s)
inline

◆ setScales()

void peclet::dem::Simulation::setScales ( const std::vector< float > &  s)
inline

◆ setVelocities()

void peclet::dem::Simulation::setVelocities ( const std::vector< float > &  v)
inline

Definition at line 931 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::vel.

Referenced by NB_MODULE().

◆ setExternalForces()

void peclet::dem::Simulation::setExternalForces ( const std::vector< float > &  f)
inline

Definition at line 942 of file sim.hpp.

References peclet::dem::Particles::extForce, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ clearExternalForces()

void peclet::dem::Simulation::clearExternalForces ( )
inline

Definition at line 951 of file sim.hpp.

References peclet::dem::Particles::extForce.

Referenced by NB_MODULE().

◆ externalForcesView()

const V3 & peclet::dem::Simulation::externalForcesView ( ) const
inline

Definition at line 952 of file sim.hpp.

References peclet::dem::Particles::extForce.

Referenced by NB_MODULE().

◆ invMassView()

const Vf & peclet::dem::Simulation::invMassView ( ) const
inline

Definition at line 953 of file sim.hpp.

References peclet::dem::Particles::invMass.

Referenced by NB_MODULE().

◆ setQuaternions()

void peclet::dem::Simulation::setQuaternions ( const std::vector< float > &  q)
inline

Definition at line 956 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::quat.

Referenced by NB_MODULE().

◆ setAngularVelocities()

void peclet::dem::Simulation::setAngularVelocities ( const std::vector< float > &  w)
inline

Definition at line 966 of file sim.hpp.

References peclet::dem::Particles::angVel, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ setInvInertia()

void peclet::dem::Simulation::setInvInertia ( const std::vector< float > &  ii)
inline

Definition at line 975 of file sim.hpp.

References peclet::dem::Particles::invInertia, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ setInvMass()

void peclet::dem::Simulation::setInvMass ( const std::vector< float > &  im)
inline

Definition at line 984 of file sim.hpp.

References peclet::dem::Particles::invMass, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ getAngularVelocities()

std::vector< float > peclet::dem::Simulation::getAngularVelocities ( ) const
inline

Definition at line 990 of file sim.hpp.

References peclet::dem::Particles::angVel, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ getInvInertia()

std::vector< float > peclet::dem::Simulation::getInvInertia ( ) const
inline

Definition at line 994 of file sim.hpp.

References peclet::dem::Particles::invInertia, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ setGrowthParams()

void peclet::dem::Simulation::setGrowthParams ( float  rate,
float  new_factor 
)
inline

◆ growthFactor()

float peclet::dem::Simulation::growthFactor ( ) const
inline

Definition at line 1009 of file sim.hpp.

References peclet::dem::Particles::growthFactor.

Referenced by NB_MODULE().

◆ getGrowthRate()

float peclet::dem::Simulation::getGrowthRate ( ) const
inline

Definition at line 1010 of file sim.hpp.

References peclet::dem::Particles::growthRate.

Referenced by NB_MODULE().

◆ getMasses()

std::vector< float > peclet::dem::Simulation::getMasses ( ) const
inline

Definition at line 1013 of file sim.hpp.

References peclet::dem::Particles::invMass, and peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ getPositions()

std::vector< float > peclet::dem::Simulation::getPositions ( ) const
inline

Definition at line 1022 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::pos.

Referenced by exportLammps(), and NB_MODULE().

◆ getVelocities()

std::vector< float > peclet::dem::Simulation::getVelocities ( ) const
inline

Definition at line 1026 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::vel.

Referenced by exportLammps(), and NB_MODULE().

◆ getQuaternions()

std::vector< float > peclet::dem::Simulation::getQuaternions ( ) const
inline

Definition at line 1030 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::quat.

Referenced by exportLammps(), and NB_MODULE().

◆ getScales()

std::vector< float > peclet::dem::Simulation::getScales ( ) const
inline

Definition at line 1034 of file sim.hpp.

References peclet::dem::Particles::numReal, and peclet::dem::Particles::scale.

Referenced by NB_MODULE().

◆ step()

void peclet::dem::Simulation::step ( float  dt)
inline

Definition at line 1040 of file sim.hpp.

References peclet::dem::demStep(), and peclet::dem::Particles::dt.

Referenced by exportLammps(), and NB_MODULE().

◆ computeOverlaps()

float peclet::dem::Simulation::computeOverlaps ( )
inline

Definition at line 1046 of file sim.hpp.

References peclet::dem::computeOverlapsKokkos().

Referenced by NB_MODULE().

◆ exportLammps()

◆ exportSdf()

void peclet::dem::Simulation::exportSdf ( const std::string &  filename,
int  rx,
int  ry,
int  rz 
)
inline

◆ getSdfGrid()

◆ numParticles()

int peclet::dem::Simulation::numParticles ( ) const
inline

Definition at line 1160 of file sim.hpp.

References peclet::dem::Particles::numReal.

Referenced by NB_MODULE().

◆ positionsView()

const V3 & peclet::dem::Simulation::positionsView ( ) const
inline

Definition at line 1164 of file sim.hpp.

References peclet::dem::Particles::pos.

Referenced by NB_MODULE().

◆ velocitiesView()

const V3 & peclet::dem::Simulation::velocitiesView ( ) const
inline

Definition at line 1165 of file sim.hpp.

References peclet::dem::Particles::vel.

Referenced by NB_MODULE().

◆ numContacts()

int peclet::dem::Simulation::numContacts ( )
inline

Definition at line 1166 of file sim.hpp.

References peclet::dem::Particles::contactCount, and peclet::dem::readInt().

Referenced by NB_MODULE().

◆ numManifolds()

int peclet::dem::Simulation::numManifolds ( )
inline

Definition at line 1167 of file sim.hpp.

References peclet::dem::Particles::manifoldCount, and peclet::dem::readInt().

Referenced by NB_MODULE().

◆ debugColoringConflicts()

◆ maxOverlap()

float peclet::dem::Simulation::maxOverlap ( )
inline

Definition at line 1223 of file sim.hpp.

References peclet::dem::Particles::maxOverlap.

Referenced by NB_MODULE().

◆ restBankStats()

std::tuple< double, float, int > peclet::dem::Simulation::restBankStats ( )
inline

Poisson-restitution diagnostics: (sum, max, count>0) of the committed per-pair owed separation impulse (prevRestBank[0:prevPairCount], physical units).

Definition at line 1230 of file sim.hpp.

References peclet::dem::Particles::prevPairCount, peclet::dem::Particles::prevRestBank, and peclet::dem::restBankStatsKokkos().

Referenced by NB_MODULE().

◆ restOrphanStats()

std::tuple< double, float, int > peclet::dem::Simulation::restOrphanStats ( )
inline

Orphan-account diagnostics: (sum, max, count>0) of the per-body orphaned budget.

Definition at line 1234 of file sim.hpp.

References peclet::dem::Particles::bodyOrphan, peclet::dem::Particles::numReal, and peclet::dem::restBankStatsKokkos().

Referenced by NB_MODULE().

◆ writeVtp()

void peclet::dem::Simulation::writeVtp ( const std::string &  filename) const
inline

The documentation for this class was generated from the following file: