C++ API reference¶
The reference below is generated from the documented public C++ headers. Worker internals and CUDA implementation headers are intentionally excluded.
Solver¶
-
class DEMSolver¶
Main DEM-Engine solver.
Fixed-size owner `ToDevice` and `FromDevice` methods validate ranges, capacities, and CUDA pointer metadata by default. Their trailing `validate` argument may be disabled when the caller guarantees those preconditions and needs to avoid validation overhead. Required device routing and documented transformations still apply.
Public Functions
Add an analytical plane to the simulation.
- Parameters:
pos – A point on the plane.
normal – The normal direction of the plane. Note entities are always considered in-contact with the plane from the positive normal direction.
material – Material of the plane.
- Returns:
A handle to the added plane object.
Load clumps into the simulation.
- Parameters:
input_types – Vector of the types of the clumps (vector of shared pointers).
input_xyz – Vector of the initial locations of the clumps.
- Returns:
Handle to the loaded batch of clumps.
-
std::shared_ptr<DEMClumpBatch> AddClumps(DEMClumpBatch &input_batch)¶
Load input clumps (topology types and initial locations) on a per-pair basis.
Note that the initial location means the location of the clumps’ CoM coordinates in the global frame.
Load clumps (of the same template) into the simulation.
- Parameters:
input_type – The type (shared pointer pointing to the clump type handle).
input_xyz – Vector of the initial locations of the clumps.
- Returns:
Handle to the loaded batch of clumps.
Load a clump into the simulation.
- Parameters:
input_type – The type (shared pointer pointing to the clump type handle).
input_xyz – Initial location of the clump.
- Returns:
Handle to the clump.
Single-pose convenience overload of AddCombinedFromTemplate.
Instantiate a combined template at a user-specified global pose.
Creates n_instances * n_members owners and records combined-group runtime metadata used for combined-owner contact/kinematics policies.
- Parameters:
combined_template – A handle returned by LoadCombinedClumpType or LoadCombinedMeshType.
init_pos – A vector of global positions for each instantiation in the batch.
init_oriQ – A vector of global orientations for each instantiation in the batch.
- Returns:
A combined-instances handle that references all instantiated member owners in the batch.
-
std::shared_ptr<DEMExternObj> AddExternalObject()¶
Add an (analytical or clump-represented) external object to the simulation system.
-
void AddFamilyPrescribedAcc(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, const std::string &pre = "none")¶
The entities in this family will always experience an extra acceleration defined using this method.
- Parameters:
ID – Family number.
X – X component of the acceleration expression.
Y – Y component of the acceleration expression.
Z – Z component of the acceleration expression.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void AddFamilyPrescribedAngAcc(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, const std::string &pre = "none")¶
The entities in this family will always experience an extra angular acceleration defined using this method.
- Parameters:
ID – Family number.
X – X component of the angular-acceleration expression.
Y – Y component of the angular-acceleration expression.
Z – Z component of the angular-acceleration expression.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void AddKernelInclude(const std::string &lib_name)¶
Add a library that the kernels will be compiled with (so that the user can use the provided methods in their customized code, like force model).
- Parameters:
lib_name – The lib to include. For example, “math_functions.h”.
-
std::shared_ptr<DEMMesh> AddMesh(DEMMesh &mesh)¶
Load a mesh-represented object into the simulation, using the internal mesh format.
Instantiate a mesh from a template and add it to the simulation.
- Parameters:
mesh_template – The mesh template (shared pointer returned from LoadMeshType).
init_pos – Initial position of the mesh instance.
- Returns:
A shared pointer to the instantiated mesh.
-
void AddOwnerNextStepAcc(bodyID_t ownerID, const std::vector<float3> &acc)¶
Add an extra accelerations to consecutive owners for the next time step.
- Parameters:
ownerID – The number of the starting owner.
acc – The extra acceleration to add. N (the size of this vector) elements will be modified based on its values.
-
void AddOwnerNextStepAccFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Queue global-frame linear accelerations for consecutive owners directly from CUDA memory.
This is the device-input counterpart of AddOwnerNextStepAcc. It replaces any previously queued next-step linear-acceleration contribution for the selected owners. During the next force/integration step, contact acceleration is accumulated on top and gravity is applied separately. The queued contribution is consumed after one step. The call is synchronous, so `source` may be reused when it returns.
- Parameters:
ownerID – First owner in the consecutive range.
source – CUDA memory containing `count` float3 global-frame accelerations.
source_device – Logical CUDA device owning `source`; remote input is copied to dT before unpacking.
count – Number of consecutive owners. A zero count is a no-op.
validate – If true, validate the owner range and CUDA pointer metadata. Disable only when the caller guarantees those preconditions and needs to avoid validation overhead.
-
void AddOwnerNextStepAngAcc(bodyID_t ownerID, const std::vector<float3> &angAcc)¶
Add an extra angular accelerations to consecutive owners for the next time step.
- Parameters:
ownerID – The number of the starting owner.
angAcc – The extra angular acceleration to add. N (the size of this vector) elements will be modified based on its values.
-
void AddOwnerNextStepAngAccFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Queue local-frame angular accelerations for consecutive owners directly from CUDA memory.
This is the device-input counterpart of AddOwnerNextStepAngAcc and uses each owner’s local principal- axis frame. It replaces any previously queued next-step angular-acceleration contribution for the selected owners. Contact angular acceleration is accumulated on top during the next force/integration step, and the queued contribution is consumed after that step. The call is synchronous, so `source` may be reused when it returns.
- Parameters:
ownerID – First owner in the consecutive range.
source – CUDA memory containing `count` float3 local-frame angular accelerations.
source_device – Logical CUDA device owning `source`; remote input is copied to dT before unpacking.
count – Number of consecutive owners. A zero count is a no-op.
validate – See AddOwnerNextStepAccFromDevice.
-
std::shared_ptr<DEMMesh> AddShellMesh(DEMMesh &mesh, float shell_thickness)¶
Load a shell mesh (triangular surface plus finite thickness) into the simulation.
- Parameters:
mesh – Mesh object.
shell_thickness – Full shell thickness, in simulation length units. Must be finite and non-negative.
-
std::shared_ptr<DEMMesh> AddWavefrontMeshObject(const std::string &filename, bool load_normals = true, bool load_uv = false)¶
Load a mesh-represented object from a mesh file (.obj, .stl, or .ply).
- Parameters:
filename – Path to the mesh file.
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded mesh object.
Load a mesh-represented object from a mesh file (.obj, .stl, or .ply).
- Parameters:
filename – Path to the mesh file.
mat – Material to assign to the mesh.
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded mesh object.
-
inline std::shared_ptr<DEMMesh> AddWavefrontMeshObject(DEMMesh &mesh)¶
A legacy method. Use AddMesh instead.
Load a shell mesh from a mesh file (.obj, .stl, or .ply).
- Parameters:
filename – Path to the mesh file.
mat – Material to assign to the shell mesh.
shell_thickness – Full shell thickness, in simulation length units. Must be finite and non-negative.
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded shell mesh object.
-
std::shared_ptr<DEMMesh> AddWavefrontShellObject(const std::string &filename, float shell_thickness, bool load_normals = true, bool load_uv = false)¶
Load a shell mesh from a mesh file (.obj, .stl, or .ply), without assigning material immediately.
- Parameters:
filename – Path to the mesh file.
shell_thickness – Full shell thickness, in simulation length units. Must be finite and non-negative.
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded shell mesh object.
-
size_t ChangeClumpFamily(unsigned int fam_num, const std::pair<double, double> &X = std::pair<double, double>(-1e15, 1e15), const std::pair<double, double> &Y = std::pair<double, double>(-1e15, 1e15), const std::pair<double, double> &Z = std::pair<double, double>(-1e15, 1e15), const std::set<unsigned int> &orig_fam = std::set<unsigned int>())¶
Change the family number for the clumps in a box region to the specified value.
- Parameters:
fam_num – The family number to change into.
X – {L, U} that discribes the lower and upper bound of the X coord of the box region.
Y – The lower and upper bound of the Y coord of the box region.
Z – The lower and upper bound of the Z coord of the box region.
orig_fam – Only clumps that originally have these family numbers will be modified. Leave empty to apply changes regardless of original family numbers.
- Returns:
The number of owners that get changed by this call.
-
void ChangeFamily(unsigned int ID_from, unsigned int ID_to)¶
Change all entities with family number ID_from to have a new number ID_to, immediately.
This is callable when kT and dT are hanging, not when they are actively working, or the behavior is not defined.
-
void ChangeFamilyWhen(unsigned int ID_from, unsigned int ID_to, const std::string &condition)¶
Change all entities with family number ID_from to have a new number ID_to, when the condition defined by the string is satisfied by the entities in question.
This should be called before initialization, and will be baked into the solver, so the conditions will be checked and changes applied every time step.
-
void ClearCache()¶
Remove host-side cached vectors (so you can re-define them, and then re-initialize system)
-
inline void ClearLog()¶
Clear stored solver logs (errors, warnings, messages).
-
void ClearThreadCollaborationStats()¶
Reset the collaboration stats between dT and kT back to the initial value (0).
You should call this if you want to start over and re-inspect the stats of the new run; otherwise, it is generally not needed, you can go ahead and destroy DEMSolver.
-
void ClearTimingStats()¶
Reset the recordings of the wall time and percentages of wall time spend on various solver tasks.
-
void CorrectFamilyAngVel(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, const std::string &pre = "none")¶
The entities in this family will always experience an added angular-velocity correction defined using this method.
At the same time, they are still subject to the “simulation physics”.
- Parameters:
ID – Family number.
X – X component of the angular-velocity-correction expression.
Y – Y component of the angular-velocity-correction expression.
Z – Z component of the angular-velocity-correction expression.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void CorrectFamilyLinVel(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, const std::string &pre = "none")¶
The entities in this family will always experience an added linear-velocity correction defined using this method.
At the same time, they are still subject to the “simulation physics”.
- Parameters:
ID – Family number.
X – X component of the velocity-correction expression.
Y – Y component of the velocity-correction expression.
Z – Z component of the velocity-correction expression.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void CorrectFamilyPosition(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, const std::string &pre = "none")¶
The entities in this family will always experience an added positional correction defined using this method.
At the same time, they are still subject to the “simulation physics”.
- Parameters:
ID – Family number.
X – X component of the position-correction expression.
Y – Y component of the position-correction expression.
Z – Z component of the position-correction expression.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void CorrectFamilyQuaternion(unsigned int ID, const std::string &q_formula)¶
The entities in this family will always experience an added quaternion correction defined using this method.
At the same time, they are still subject to the “simulation physics”.
- Parameters:
ID – Family number.
q_formula – The code from which the quaternion should be calculated. Must return a float4. For example, “float tmp=make_float4(1,1,1,1); return tmp;”.
-
std::shared_ptr<DEMInspector> CreateInspector(const std::string &quantity, const std::string ®ion)¶
-
std::shared_ptr<DEMInspector> CreateInspector(const std::string &quantity = "clump_max_z")¶
Create a inspector object that can help query some statistical info of the clumps in the simulation.
-
std::shared_ptr<DEMForceModel> DefineContactForceModel(const std::string &model)¶
Define a custom contact force model by a string. Returns a shared_ptr to the force model in use.
-
explicit DEMSolver(const std::vector<int> &device_ids)¶
Construct a solver on explicitly selected logical CUDA devices.
One ID places both workers on that device; two IDs assign dT and kT respectively. IDs follow CUDA_VISIBLE_DEVICES remapping.
-
DEMSolver(unsigned int nGPUs = 2)¶
Construct a solver using the requested number of visible CUDA devices.
One GPU places both workers on device 0; two GPUs place dT on device 0 and kT on device 1 when available, falling back to device 0 on a one-GPU system.
-
inline void DisableAdaptiveBinSize()¶
Disable the use of adaptive bin size.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
inline void DisableAdaptiveUpdateFreq()¶
Disable adaptive max update step count.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
void DisableAllMeshWearModels()¶
Disable all active mesh wear models.
-
void DisableContactBetweenFamilies(unsigned int ID1, unsigned int ID2)¶
Instruct the solver that the 2 input families should not have contacts (a.k.a.
ignored, if such a pair is encountered in contact detection). These 2 families can be the same (which means no contact within members of that family).
-
void DisableFamilyOutput(unsigned int ID)¶
Prevent entites associated with this family to be outputted to files.
-
inline void DisableJitifyClumpTemplates()¶
Use flattened sphere component configuration arrays whose entries are associated with individual spheres, rather than jitifying them it into GPU kernels.
-
inline void DisableJitifyMassProperties()¶
Use flattened mass property arrays whose entries are associated with individual spheres, rather than jitifying them it into GPU kernels.
-
void DisableMeshWearModel(bodyID_t ownerID)¶
Disable mesh wear model for one owner.
-
void DisableTrianglePVTracking()¶
Disable per-triangle P/V/PxV tracking and clear tracking state.
-
void DoDynamics(double thisCallDuration)¶
Advance simulation by this amount of time (but does not attempt to sync kT and dT).
This can work with both long and short call durations and allows interplay with co-simulation APIs.
-
void DoDynamicsThenSync(double thisCallDuration)¶
Advance simulation by this amount of time, and at the end of this call, synchronize kT and dT.
This is suitable for a longer call duration and without co-simulation.
-
inline void DoStepDynamics()¶
Equivalent to calling DoDynamics with the time step size as the argument.
Let dT do this call and return the reduce value of the inspected quantity.
Duplicate a batch of clumps that is loaded into the system.
- Parameters:
ptr – Shared pointer for the object to duplicate.
- Returns:
A duplicate of the object (with effectively a deep copy).
Duplicate a clump template that is loaded into the system.
- Parameters:
ptr – Shared pointer for the object to duplicate.
- Returns:
A duplicate of the object (with effectively a deep copy).
Duplicate a material that is loaded into the system.
- Parameters:
ptr – Shared pointer for the object to duplicate.
- Returns:
A duplicate of the object (with effectively a deep copy).
Duplicate a mesh object that is loaded into the system.
- Parameters:
ptr – Shared pointer for the mesh object to duplicate.
- Returns:
A duplicate of the mesh object (with effectively a deep copy).
-
void EnableContactBetweenFamilies(unsigned int ID1, unsigned int ID2)¶
Re-enable contact between 2 families after the system is initialized.
-
inline void EnableContactWildcardOutput(bool enable = true)¶
Enable/disable outputting contact wildcard values to the contact file.
-
inline void EnableMeshPatchColorOutput(bool enable = true)¶
Enable/disable patch color metadata in PLY mesh output.
-
void EnableMeshWearModel(bodyID_t ownerID, double wear_rate, double update_interval, double start_time = 0.0, double end_time = -1.0, float normal_sign = -1.0f)¶
Enable a mesh wear model driven by per-triangle P*V.
- Parameters:
ownerID – Mesh owner ID.
wear_rate – Wear-rate coefficient [length / (P*V * time)].
update_interval – Geometry update interval [s], must be >= solver time step.
start_time – Wear start time [s].
end_time – Wear end time [s], negative value means no end time.
normal_sign – Wear direction sign along triangle normal (+1) or opposite to it (-1).
-
inline void EnableOwnerWildcardOutput(bool enable = true)¶
Enable/disable outputting owner wildcard values to file.
-
inline void EnsureKernelErrMsgLineNum(bool flag = true)¶
If true, each jitification string substitution will do a one-liner to one-liner replacement, so that if the kernel compilation fails, the error message line number will reflex the actual spot where that happens (instead of some random number)
-
void FlushMeshWearModels()¶
Force-apply any pending wear deformation immediately.
-
std::vector<float> GetAllOwnerWildcardValue(const std::string &name)¶
Get the owner wildcard’s values of all entities.
-
inline float GetAvgPrimitiveContacts() const¶
Get the current number of contacts each primitive geometry (sphere or triangle) has.
- Returns:
Number of contacts.
-
inline float GetAvgSphContacts() const¶
-
inline size_t GetBinNum()¶
Get the current number of bins (for contact detection).
Must be called from synchronized stance.
- Returns:
Number of bins.
-
inline double GetBinSize()¶
Get the current bin (for contact detection) size.
Must be called from synchronized stance.
- Returns:
Bin size.
-
std::shared_ptr<DEMMesh> &GetCachedMesh(bodyID_t ownerID)¶
Get a handle for the mesh this tracker is tracking.
- Returns:
Pointer to the mesh.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts() const¶
Get all clump—clump contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts(const std::set<family_t> &family_to_include) const¶
Get all clump—clump contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Parameters:
family_to_include – Contacts that involve a body in a family not listed in this argument are ignored.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetClumpContacts(std::vector<std::pair<family_t, family_t>> &family_pair) const¶
Get all clump—clump contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Parameters:
family_pair – Functions returns a vector of contact body family number pairs. First is the family number of contact body A, and Second is that of contact body B.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
std::vector<float3> GetClumpPositionsHandover() const¶
Handover helper: get all clump-owner center positions in one call.
- Returns:
Position vector with one entry per clump owner, ordered by owner ID.
-
bool GetCombinedInstanceInfo(size_t combined_instance_id, bodyID_t &master_owner_id, std::vector<bodyID_t> &member_owner_ids, std::vector<float3> &member_rel_pos, std::vector<float4> &member_rel_oriQ)¶
Query resolved owner IDs and fixed relative transforms for one combined instance.
Returns `false` if the index is invalid or owner IDs are not resolved yet (e.g., before Initialize/Update assigns owner numbering).
- Parameters:
combined_instance_id – Zero-based index in the combined-instance cache.
master_owner_id – Output master owner ID of this combined group.
member_owner_ids – Output owner IDs for all members (same order as template components).
member_rel_pos – Output fixed member-relative positions in master frame.
member_rel_oriQ – Output fixed member-relative orientations in master frame.
- Returns:
True if metadata is available and outputs are populated.
-
std::shared_ptr<ContactInfoContainer> GetContactDetailedInfo(float force_thres = -1.0) const¶
Get all contact pairs’ detailed information (actual content based on the setting with SetContactOutputContent; default are owner IDs, contact point location, contact force, and associated wildcard values) in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Parameters:
force_thres – Only contacts with force larger than this value are returned. Setting it to a small positive number to, instead of getting all potential contacts, only get the ones that are currently confirmed to generate force.
- Returns:
A map that may have the following keys: “ContactType”, “Point”, “AOwner”, “BOwner”, “AOwnerFamily”, “BOwnerFamily”, “Force”, “Torque”, “Normal” and wildcard names, each corresponding to a vector of values. The “ContactType” is a vector of strings, each indicating the type of contact (e.g., “sphere-sphere”, “sphere-triangle”, etc.). The “Point” is a vector of float3s, each indicating the contact point location in global coordinates. The “AOwner” and “BOwner” are vectors of body IDs for the two bodies in contact. The “Force” is a vector of float3s, each indicating the contact force at the contact point. The “Torque” is a vector of float3s, each indicating the torque at the contact point. The “Normal” is a vector of float3s, each indicating the normal direction at the contact point.
-
inline std::shared_ptr<DEMForceModel> GetContactForceModel()¶
Get the current force model.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts() const¶
Get all contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts(const std::set<family_t> &family_to_include) const¶
Get all contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Parameters:
family_to_include – Contacts that involve a body in a family not listed in this argument are ignored.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
std::vector<std::pair<bodyID_t, bodyID_t>> GetContacts(std::vector<std::pair<family_t, family_t>> &family_pair) const¶
Get all contact ID pairs in the simulation system.
Note all GetContact-like methods reports potential contacts (not necessarily confirmed contacts), meaning they are similar to what WriteContactFileIncludingPotentialPairs does, not what WriteContactFile does.
Do not call this method with high frequency, as it is not efficient.
- Parameters:
family_pair – Functions returns a vector of contact body family number pairs. First is the family number of contact body A, and Second is that of contact body B.
- Returns:
A sorted (based on contact body A’s owner ID) vector of contact pairs. First is the owner ID of contact body A, and Second is that of contact body B.
-
inline bool GetCudaDebugSync() const¶
Return whether process-wide CUDA debug synchronization is enabled.
-
inline size_t GetDeviceMemUsageDynamic() const¶
Get the device memory usage (in bytes) on dT.
- Returns:
Number of bytes.
-
inline size_t GetDeviceMemUsageKinematic() const¶
Get the device memory usage (in bytes) on kT.
- Returns:
Number of bytes.
-
float GetExpandFactor() const¶
Get the current expand factor in simulation.
-
std::vector<float> GetFamilyOwnerWildcardValue(unsigned int N, const std::string &name)¶
Get the owner wildcard’s values of all entities in family N.
-
inline std::vector<int> GetGPUDeviceIDs() const¶
Return the logical CUDA devices assigned to dT and kT, in that order.
-
inline bool GetGPUTimersEnabled() const¶
Return whether GPU event-based timing is enabled.
-
inline size_t GetHostMemUsageDynamic() const¶
Get the host memory usage (in bytes) on dT.
- Returns:
Number of bytes.
-
inline size_t GetHostMemUsageKinematic() const¶
Get the host memory usage (in bytes) on kT.
- Returns:
Number of bytes.
-
inline bool GetInitStatus() const¶
Return whether this simulation system is initialized.
-
inline std::vector<std::string> GetJitifyOptions() const¶
Get current jitification options. It is needed by some of this simulation system’s friend classes.
-
inline std::unordered_map<std::string, std::string> GetJitStringSubs() const¶
Get the jitification string substitution laundary list.
It is needed by some of this simulation system’s friend classes.
-
std::vector<float3> GetMeshNodesGlobal(bodyID_t ownerID)¶
Get the current locations of all the nodes in the mesh being tracked.
- Parameters:
ownerID – The ownerID of the mesh.
- Returns:
A vector of float3 representing the global coordinates of the mesh nodes.
-
inline size_t GetNumClumps() const¶
Return the number of clumps that are currently in the simulation. Must be used after initialization.
-
inline size_t GetNumCombinedInstances() const¶
Number of combined instances currently cached.
This count is pre-initialization setup metadata and is cleared by cache-clearing workflows.
-
inline size_t GetNumContacts() const¶
Get the number of kT-reported potential contact pairs.
- Returns:
Number of potential contact pairs.
-
inline size_t GetNumOwners() const¶
Return the total number of owners (clumps + meshes + analytical objects) that are currently in the simulation.
Must be used after initialization.
-
std::vector<float3> GetOwnerAcc(bodyID_t ownerID, bodyID_t n = 1) const¶
Get the acceleration of n consecutive owners.
-
void GetOwnerAccToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with global-frame contact accelerations.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float3> GetOwnerAngAcc(bodyID_t ownerID, bodyID_t n = 1) const¶
Get the angular acceleration of n consecutive owners.
-
void GetOwnerAngAccGlobalToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with global-frame contact angular accelerations.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
void GetOwnerAngAccLocalToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with local-frame contact angular accelerations.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float3> GetOwnerAngVel(bodyID_t ownerID, bodyID_t n = 1) const¶
Get angular velocity of n consecutive owners.
-
void GetOwnerAngVelGlobalToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with global-frame angular velocities of consecutive owners.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
void GetOwnerAngVelLocalToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with local-frame angular velocities of consecutive owners.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<bodyID_t> GetOwnerContactClumps(bodyID_t ownerID) const¶
Get the clumps that are in contact with this owner as a vector.
No multi-owner bulk version. This is due to efficiency concerns. If getting multiple owners’ contacting clumps is needed, use family-based GetContacts method, then the owner ID list-based c method if you further need the contact forces information.
- Parameters:
ownerID – The ID of the owner that is being queried.
- Returns:
Clump owner IDs in contact with this owner.
-
size_t GetOwnerContactForces(const std::vector<bodyID_t> &ownerIDs, std::vector<float3> &points, std::vector<float3> &forces)¶
Get all contact forces that concern a list of owners.
- Parameters:
ownerIDs – The IDs of the owners.
points – Fill this vector of float3 with the XYZ components of the contact points.
forces – Fill this vector of float3 with the XYZ components of the forces.
- Returns:
Number of force pairs.
-
size_t GetOwnerContactForces(const std::vector<bodyID_t> &ownerIDs, std::vector<float3> &points, std::vector<float3> &forces, std::vector<float3> &torques, bool torque_in_local = false)¶
Get all contact forces that concern a list of owners.
If a contact involves at least one of the owner IDs provided as the first arg this method, it will be outputted. Note if a contact involves two IDs of the user-provided list, then the force for that contact will be given as the force experienced by whichever owner that appears earlier in the ID list.
- Parameters:
ownerIDs – The IDs of the owners.
points – Fill this vector of float3 with the XYZ components of the contact points.
forces – Fill this vector of float3 with the XYZ components of the forces.
torques – Fill this vector of float3 with the XYZ components of the torques (in local frame).
torque_in_local – If true, output torque in this body’s local ref frame.
- Returns:
Number of force pairs.
-
size_t GetOwnerContactForcesToDevice(const std::vector<bodyID_t> &ownerIDs, float3 *points, float3 *forces, float3 *torques, size_t capacity, int destination_device, bool torque_in_local = false)¶
Compact contact points, forces, and extra torques concerning ownerIDs into caller-provided CUDA memory.
-
size_t GetOwnerContactForcesToDevice(const std::vector<bodyID_t> &ownerIDs, float3 *points, float3 *forces, size_t capacity, int destination_device)¶
Compact contact points and forces concerning ownerIDs into caller-provided CUDA memory.
Capacity must be at least the solver’s current total contact count; the returned value is the useful count.
-
void GetOwnerContactWrench(std::vector<float3> &forces, std::vector<float3> &torques, bodyID_t ownerID, bodyID_t count = 1) const¶
Get one reduced contact wrench for each consecutive owner.
Each force is the global-frame sum of recorded contact forces on that owner. Each torque is the corresponding global-frame moment about DEME’s current owner position, including force-generated moments and force-model-only torque such as rolling resistance. Owners without recorded contact receive a zero wrench. This reads the current dT force records; it does not trigger contact detection or force evaluation. Contact recording must remain enabled (the default).
- Parameters:
forces – Output global resultant forces, resized to `count`.
torques – Output global resultant torques, resized to `count`.
ownerID – First owner in the consecutive range.
count – Number of owners to reduce. A zero count clears both output vectors.
-
void GetOwnerContactWrenchToDevice(float3 *force_destination, float3 *torque_destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t count = 1) const¶
Write one reduced contact wrench per consecutive owner directly to CUDA memory.
This is the device-output counterpart of GetOwnerContactWrench and uses the same reduction. Each force is the global-frame sum of recorded contact forces on an owner. Each torque is the corresponding global-frame moment about DEME’s current owner position, including force-generated moments and force-model-only torque such as rolling resistance. Owners without recorded contact receive a zero wrench. This reads the current dT force records; it does not trigger contact detection or force evaluation. Contact recording must remain enabled (the default). The call is synchronous, so both destination buffers may be consumed when it returns.
- Parameters:
force_destination – Writable CUDA memory for `count` float3 resultant forces.
torque_destination – Writable CUDA memory for `count` float3 resultant torques.
capacity – Available elements in each destination buffer; must be at least `count`.
destination_device – Logical CUDA device owning both destination buffers. CUDA selects the available inter-device transfer route for cross-device output.
ownerID – First owner in the consecutive range.
count – Number of owners to reduce. A zero count is a no-op.
-
std::vector<unsigned int> GetOwnerFamily(bodyID_t ownerID, bodyID_t n = 1) const¶
Get the family number of n consecutive owners.
- Parameters:
ownerID – First owner’s ID.
n – The number of consecutive owners.
- Returns:
The family number.
-
void GetOwnerFamilyToDevice(unsigned int *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with owner family numbers as unsigned integers.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float> GetOwnerMass(bodyID_t ownerID, bodyID_t n = 1) const¶
Get the mass of n consecutive owners.
- Parameters:
ownerID – First owner’s ID.
n – The number of consecutive owners.
- Returns:
The mass.
-
void GetOwnerMassToDevice(float *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with owner masses.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float3> GetOwnerMOI(bodyID_t ownerID, bodyID_t n = 1) const¶
Get the moment of inertia (in principal axis frame) of n consecutive owners.
- Parameters:
ownerID – First owner’s ID.
n – The number of consecutive owners.
- Returns:
The moment of inertia (in principal axis frame).
-
void GetOwnerMOIToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with owner principal moments of inertia.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float4> GetOwnerOriQ(bodyID_t ownerID, bodyID_t n = 1) const¶
Get quaternion of n consecutive owners.
-
void GetOwnerOriQToDevice(float4 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with public-order (x, y, z, w) orientation quaternions.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float3> GetOwnerPosition(bodyID_t ownerID, bodyID_t n = 1) const¶
Get position of n consecutive owners.
-
void GetOwnerPositionToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with positions of consecutive owners.
Capacity is measured in elements.
- Parameters:
validate – If true, validate the owner range, capacity, and CUDA pointer metadata. Disable only when the caller guarantees those preconditions and needs to avoid validation overhead.
-
std::vector<float3> GetOwnerVelocity(bodyID_t ownerID, bodyID_t n = 1) const¶
Get velocity of n consecutive owners.
-
void GetOwnerVelocityToDevice(float3 *destination, size_t capacity, int destination_device, bodyID_t ownerID, bodyID_t n = 1, bool validate = true) const¶
Fill caller-provided CUDA memory with velocities of consecutive owners.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
std::vector<float> GetOwnerWildcardValue(bodyID_t ownerID, const std::string &name, bodyID_t n = 1)¶
Get the owner wildcard’s values of some owners.
- Parameters:
ownerID – Starting owner’s ID.
name – Wildcard’s name.
n – Total number of owners to query, starting from ownerID.
- Returns:
Value of this wildcard.
-
void GetOwnerWildcardValueToDevice(float *destination, size_t capacity, int destination_device, bodyID_t ownerID, const std::string &name, bodyID_t n = 1, bool validate = true)¶
Fill caller-provided CUDA memory with one owner wildcard over a consecutive owner range.
- Parameters:
validate – See GetOwnerPositionToDevice.
-
double GetSimTime() const¶
Get the simulation time passed since the start of simulation.
-
inline double GetTimeStepSize() const¶
Get the current time step size in simulation.
-
bool GetTrackedOwnerTrianglePV(bodyID_t ownerID, std::vector<float> &avgP, std::vector<float> &avgV, std::vector<float> &avgPV, bool reset_window = true)¶
Get frame-window averaged per-triangle P, V and P*V for one tracked owner.
- Parameters:
ownerID – Mesh owner ID used in SetTrianglePVTrackingOwners.
avgP – Output vector of averaged normal-force shares per triangle.
avgV – Output vector of averaged tangential slip speeds per triangle.
avgPV – Output vector of averaged P*V values per triangle.
reset_window – If true, clear the current accumulation window after reading.
- Returns:
True if the owner is currently tracked; false otherwise.
-
float GetUpdateFreq() const¶
Get the current update frequency used by the solver.
- Returns:
The current update frequency.
-
void GetVisualizationFrame(DEMVisualizationFrame &frame, bool include_velocities = false) const¶
Fill reusable owner arrays at a synchronized simulation boundary; never call concurrently with dynamics.
-
DEMVisualizationScene GetVisualizationScene() const¶
Get cached-renderer geometry in owner-local coordinates. Refresh when the frame revision changes.
-
DEMVisualizationSnapshot GetVisualizationSnapshot(bool include_spheres = true, bool include_triangles = true) const¶
Capture renderable sphere and triangle geometry at the current solver state.
This call synchronously transfers the required owner state to the host. It does not advance the simulation and should not be called concurrently with DoDynamics(). Disabled geometry categories are not transferred into the returned snapshot.
-
inline bool GetWhetherForceCollectInKernel()¶
Return whether the solver is currently reducing force in the force calculation kernel.
-
void Initialize(bool dry_run = false)¶
Intialize the simulation system.
Instruct if and how we should add boundaries to the simulation world upon initialization.
Choose between “none”, “all” (add 6 boundary planes) and “top_open” (add 5 boundary planes and leave the z-directon top open). Also specifies the material that should be assigned to those bounding boundaries.
-
void InstructBoxDomainDimension(const std::pair<float, float> &x, const std::pair<float, float> &y, const std::pair<float, float> &z, const std::string &dir_exact = "none")¶
Set the size of the simulation “world”.
- Parameters:
x – Lower and upper limit for X coordinate.
y – Lower and upper limit for Y coordinate.
z – Lower and upper limit for Z coordinate.
dir_exact – The direction for which the user-instructed size must strictly agree with the actual generated size. Pick between “X”, “Y”, “Z” or “none”.
-
void InstructBoxDomainDimension(float x, float y, float z, const std::string &dir_exact = "none")¶
Instruct the dimension of the `world’.
On initialization, this info will be used to figure out how to assign the num of voxels in each direction. If your `useful’ domain is not box-shaped, then define a box that contains your domian.
-
inline void InstructNumOwners(size_t numOwners)¶
Explicitly instruct the sizes for the arrays at initialization time.
This is useful when the number of owners tends to change (especially gradually increase) frequently in the simulation, by reducing the need for reallocation. Note however, whatever instruction the user gives here it won’t affect the correctness of the simulation, since if the arrays are not long enough they will always be auto-resized. This is not implemented yet :/
-
std::shared_ptr<DEMClumpTemplate> LoadClumpType(DEMClumpTemplate &clump)¶
An overload of LoadClumpType where the user builds the DEMClumpTemplate struct themselves then supply it.
An overload of LoadClumpType which loads sphere components from a file and all components use the same material.
An overload of LoadClumpType which loads sphere components from a file.
An overload of LoadClumpType where all components use the same material.
Load a clump type into the API-level cache.
- Returns:
the shared ptr to the clump type just loaded.
Load a rigid combined-clump template with fixed member-relative transforms.
All components must be clump templates. The combined template stores member poses in a master-member-relative frame so the whole group can later be instantiated at arbitrary global pose. If `component_rel_oriQ` is empty, identity orientation is assumed for all members.
- Parameters:
component_templates – Member clump templates in this combined group.
component_rel_pos – Member positions in the user-provided template frame.
component_rel_oriQ – Member orientations in the user-provided template frame (optional).
master_component – Index of the member chosen as the master reference frame.
- Returns:
A combined template handle that can be instantiated via AddCombinedFromTemplate.
Load a rigid combined-mesh template with fixed member-relative transforms.
All components must be mesh templates. The combined template stores member poses in a master-member-relative frame so the whole group can later be instantiated at arbitrary global pose. If `component_rel_oriQ` is empty, identity orientation is assumed for all members.
- Parameters:
component_templates – Member mesh templates in this combined group.
component_rel_pos – Member positions in the user-provided template frame.
component_rel_oriQ – Member orientations in the user-provided template frame (optional).
master_component – Index of the member chosen as the master reference frame.
- Returns:
A combined template handle that can be instantiated via AddCombinedFromTemplate.
-
std::shared_ptr<DEMMaterial> LoadMaterial(const std::unordered_map<std::string, float> &mat_prop)¶
Load materials properties (Young’s modulus, Poisson’s ratio…) into the system.
- Parameters:
mat_prop – Property name—value pairs, as an unordered_map.
- Returns:
A shared pointer for this material.
-
std::shared_ptr<DEMMaterial> LoadMaterial(DEMMaterial &a_material)¶
Load materials properties into the system.
- Parameters:
a_material – A DEMMaterial object.
- Returns:
A shared pointer for this material.
-
std::shared_ptr<DEMMesh> LoadMeshType(const std::string &filename, bool load_normals = true, bool load_uv = false)¶
Load a mesh type into the API-level cache as a template.
- Parameters:
filename – Path to the mesh file (.obj, .stl, or .ply).
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded mesh template.
Load a mesh type into the API-level cache as a template.
The mesh is not immediately added to the simulation, but stored as a template that can be instantiated multiple times at different locations. This is similar to LoadClumpType() for clump templates.
- Parameters:
filename – Path to the mesh file (.obj, .stl, or .ply).
mat – Material to assign to the mesh.
load_normals – Whether to load normals from the file.
load_uv – Whether to load UV coordinates from the file.
- Returns:
A shared pointer to the loaded mesh template.
-
std::shared_ptr<DEMMesh> LoadMeshType(DEMMesh &mesh)¶
Load a mesh type into the API-level cache as a template.
- Parameters:
mesh – A DEMMesh object.
- Returns:
A shared pointer to the loaded mesh template.
A simplified version of LoadClumpType: it just loads a one-sphere clump template, with explicit MOI supplied.
A simplified version of LoadClumpType: it just loads a one-sphere clump template.
-
void MarkFamilyPersistentContact(unsigned int N1, unsigned int N2)¶
Make it so that if for any currently-existing contact, if its two contact geometries are in family N1 and N2 respectively, this contact will never be removed.
This contact might be created through contact detection, or being a contact the user manually loaded at the start of simulation. Note this is a one-time assignment and will not continuously mark future emerging contact to be persistent.
- Parameters:
N1 – Family number 1.
N2 – Family number 2.
-
void MarkFamilyPersistentContactBoth(unsigned int N)¶
Make it so that for any currently-existing contact, if both of its contact geometries are in family N, then this contact will never be removed.
This contact might be created through contact detection, or being a contact the user manually loaded at the start of simulation. Note this is a one-time assignment and will not continuously mark future emerging contact to be persistent.
- Parameters:
N – Family number.
-
void MarkFamilyPersistentContactEither(unsigned int N)¶
Make it so that for any currently-existing contact, if one of its contact geometries is in family N, then this contact will never be removed.
This contact might be created through contact detection, or being a contact the user manually loaded at the start of simulation. Note this is a one-time assignment and will not continuously mark future emerging contact to be persistent.
- Parameters:
N – Family number.
-
void MarkPersistentContact()¶
Make it so that all currently-existing contacts in this simulation will never be removed.
The contacts might be created through contact detection, or being manually loaded at the start of simulation. Note this is a one-time assignment and will not continuously mark future emerging contact to be persistent.
-
inline void PrintKinematicScratchSpaceUsage() const¶
Print kT’s scratch space usage. This is a debug method.
-
void PurgeFamily(unsigned int family_num)¶
Removes all entities associated with a family from the arrays (to save memory space).
Create a DEMTracker to allow direct control/modification/query to this external object/batch of clumps/triangle mesh object.
C++ users do not have to use this method. Using Track is enough. This method is for Python wrapper.
-
std::shared_ptr<DEMForceModel> ReadContactForceModel(const std::string &filename)¶
Read user custom contact force model from a file (which by default should reside in kernel/DEMUserScripts).
Returns a shared_ptr to the force model in use.
-
void ReleaseFlattenedArrays()¶
Release the memory for the flattened arrays (which are used for initialization pre-processing and transferring info the worker threads).
-
void RemoveFamilyPersistentContact(unsigned int N1, unsigned int N2)¶
Cancel contact persistence qualification. Work like the inverse of MarkFamilyPersistentContact.
-
void RemoveFamilyPersistentContactBoth(unsigned int N)¶
Cancel contact persistence qualification. Work like the inverse of MarkFamilyPersistentContactBoth.
-
void RemoveFamilyPersistentContactEither(unsigned int N)¶
Cancel contact persistence qualification. Work like the inverse of MarkFamilyPersistentContactEither.
-
inline void RemoveKernelInclude()¶
Remove all extra libraries that the kernels `include’ in their headers.
-
void RemovePersistentContact()¶
Cancel contact persistence qualification. Work like the inverse of MarkPersistentContact.
-
void RequestContactUpdate()¶
Request an immediate contact detection update.
-
inline void SetAdaptiveBinSizeAcc(float acc)¶
Set how fast kT changes adjustment direction.
Note
After initialization, call UpdateSimParams() for this change to take effect in the worker.
- Parameters:
acc – 0.01: slowly change direction; 1: quickly change direction
-
inline void SetAdaptiveBinSizeDelaySteps(unsigned int n)¶
Adjust how frequent kT updates the bin size.
Note
After initialization, call UpdateSimParams() for this change to take effect in the worker.
- Parameters:
n – Number of contact detections before kT makes one adjustment to bin size.
-
inline void SetAdaptiveBinSizeLowerProactivity(float ratio)¶
Set how proactive the solver is in avoiding undersized bins.
Note
After initialization, call UpdateSimParams() for this change to take effect in the worker.
- Parameters:
ratio – 0: not proavtive; 1: very proactive.
-
inline void SetAdaptiveBinSizeMaxRate(float rate)¶
Set the max rate that the bin size can change in one adjustment.
Note
After initialization, call UpdateSimParams() for this change to take effect in the worker.
- Parameters:
rate – 0: never changes; 1: can double or halve size in one go; suggest using default.
-
inline void SetAdaptiveBinSizeUpperProactivity(float ratio)¶
Set how proactive the solver is in avoiding oversized bins.
Note
After initialization, call UpdateSimParams() for this change to take effect in the worker.
- Parameters:
ratio – 0: not proavtive; 1: very proactive.
-
void SetAdaptiveTimeStepType(const std::string &type)¶
Set the strategy for auto-adapting time step size.
- Parameters:
type – “none”, “hertz_const”, “max_vel” or “int_diff”. Currently, only “hertz_const” has behavior; it computes a fixed setup-time timestep from Hertzian material stiffness, minimum clump mass, and minimum radius.
-
void SetAllowIntraCombinedOwnerContacts(bool allow = true)¶
Allow/disallow contact generation among owners that belong to the same combined owner group.
Default is false (contacts within one combined group are suppressed).
-
inline void SetCDMaxUpdateFreq(unsigned int max_freq)¶
Set the upper bound of kT update frequency.
This only affects when the update freq is updated automatically. To manually control the freq, use SetCDUpdateFreq then call DisableAdaptiveUpdateFreq.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
- Parameters:
max_freq – dT will not receive updates less frequently than 1 update per max_freq steps.
-
inline void SetCDNumStepsMaxDriftAheadOfAvg(float n)¶
Set the number of steps dT configures its max drift above average.
Note
After initialization, call UpdateSimParams() for this change to take effect in dT.
- Parameters:
n – Number of steps. Suggest using default.
-
void SetCDNumStepsMaxDriftHistorySize(unsigned int n)¶
Set the drift-regulator history size.
Note
After initialization, call UpdateSimParams() for this change to take effect in dT.
- Parameters:
n – Number of kT updates. Suggest using default.
-
inline void SetCDNumStepsMaxDriftMultipleOfAvg(float m)¶
Set the maximum-drift multiplier.
Note
After initialization, call UpdateSimParams() for this change to take effect in dT.
- Parameters:
m – The multiplier. Suggest using default.
-
inline void SetCDUpdateFreq(int freq)¶
Set the number of dT steps before it waits for a contact-pair info update from kT.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers and interaction manager.
-
inline void SetCollectAccRightAfterForceCalc(bool flag = true)¶
Reduce contact forces to accelerations right after calculating them, in the same kernel.
This may give some performance boost if you have only polydisperse spheres, no clumps.
Note
After initialization, call UpdateSimParams() for this change to take effect in dT.
-
void SetContactOutputContent(const std::vector<std::string> &content)¶
Specify the information that needs to go into the contact pair output files.
- Parameters:
content – A list of “CNT_TYPE”, “FORCE”, “POINT”, “COMPONENT”, “NORMAL”, “TORQUE”, “CNT_WILDCARD”, “OWNER”, “GEO_ID” and/or “NICKNAME”.
-
inline void SetContactOutputContent(unsigned int content)¶
Specify the information that needs to go into the contact pair output files.
-
void SetContactOutputFormat(const std::string &format)¶
Specify the file format of contact pairs.
- Parameters:
format – Choice among “CSV”, “BINARY”.
-
inline void SetContactOutputFormat(OUTPUT_FORMAT format)¶
Specify the file format of contact pairs.
-
void SetContactWildcards(const std::set<std::string> &wildcards)¶
Set the names for the extra quantities that will be associated with each contact pair.
-
void SetContactWildcardValue(const std::string &name, float val)¶
Change the value of contact wildcards to val.
Apply to all simulation bodies that are present.
- Parameters:
name – Name of the contact wildcard to modify.
val – The value to change to.
-
inline void SetCudaDebugSync(bool enable = true)¶
Process-wide switch to synchronize after CUDA operations that enqueue stream work.
Enabled by default for debugging; disable it for normal asynchronous performance.
-
inline void SetDEME2MeshBehavior(bool use = true)¶
Control whether subsequently loaded meshes use DEME 2 patch behavior.
When enabled, every triangle of each subsequently loaded mesh is assigned to an individual patch. When disabled, the solver leaves patch assignment unchanged. This setting defaults to false and does not modify meshes that were loaded previously.
- Parameters:
use – Whether to apply DEME 2 patch behavior to subsequently loaded meshes.
-
void SetErrorOutAngularVelocity(float ang_vel)¶
Set the angular velocity which when exceeded, the solver errors out.
A huge number can be used to discourage this error type. Defaulted to 1e4.
- Parameters:
ang_vel – Error-out angular velocity.
-
void SetErrorOutAvgContacts(float num_cnts)¶
Set the average number of contacts a primitive geometry (sphere or triangle) has, before the solver errors out.
A huge number can be used to discourage this error type. Defaulted to 100.
- Parameters:
num_cnts – Error-out contact number.
-
void SetErrorOutVelocity(float vel)¶
Set the velocity which when exceeded, the solver errors out.
A huge number can be used to discourage this error type. Defaulted to 1e3.
- Parameters:
vel – Error-out velocity.
-
inline void SetExpandFactor(float beta, bool fix = true)¶
(Explicitly) set the amount by which the radii of the spheres (and the thickness of the boundaries) are expanded for the purpose of contact detection (safe, and creates false positives).
If fix is set to true, then this expand factor does not change even if the user uses variable time step size. After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
inline void SetExpandSafetyAdder(float vel)¶
Set a “base” velocity, which we will always add to our estimated maximum system velocity, when deriving the thinckness of the contact “safety” margin.
This need not to be large unless the simulation velocity can increase significantly in one kT update cycle. After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
inline void SetExpandSafetyMultiplier(float param)¶
Assign a multiplier to our estimated maximum system velocity, when deriving the thinckness of the contact “safety” margin.
This can be greater than one if the simulation velocity can increase significantly in one kT update cycle, but this is not common and should be close to 1 in general. After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
void SetExpandSafetyType(const std::string &insp_type)¶
Set the method this solver uses to derive current system velocity (for safety purposes in contact detection).
- Parameters:
insp_type – A string. If “auto”: the solver automatically derives. After initialization, call UpdateSimParams() for this change to take effect in the workers.
Set all clumps in this family to have this material.
- Parameters:
N – Family number.
mat – Material type.
-
void SetFamilyContactWildcardValue(unsigned int N1, unsigned int N2, const std::string &name, float val)¶
Change the value of contact wildcards to val if one of the contact geometry is in family N1, and the other is in N2.
- Parameters:
N1 – First family number.
N2 – Second family number.
name – Name of the contact wildcard to modify.
val – The value to change to.
-
void SetFamilyContactWildcardValueBoth(unsigned int N, const std::string &name, float val)¶
Change the value of contact wildcards to val if both of the contact geometries are in family N.
- Parameters:
N – Family number. Only if both contact geometries are in N, this contact wildcard is modified.
name – Name of the contact wildcard to modify.
val – The value to change to.
-
void SetFamilyContactWildcardValueEither(unsigned int N, const std::string &name, float val)¶
Change the value of contact wildcards to val if either of the contact geometries is in family N.
- Parameters:
N – Family number. If one contact geometry is in N, this contact wildcard is modified.
name – Name of the contact wildcard to modify.
val – The value to change to.
-
void SetFamilyExtraMargin(unsigned int N, float extra_size)¶
Add an extra contact margin to entities in a family so they are registered as potential contact pairs earlier.
You typically need this method when the custom force model contains non-contact forces. The solver needs this extra margin to preemptively registered contact pairs. If the extra margin is not added, then the contact pair will not be computed until entities are in physical contact. Note this margin should be as small as needed, since it potentially increases the total number of contact pairs greatly.
- Parameters:
N – Family number.
extra_size – The thickness of the extra contact margin.
-
void SetFamilyFixed(unsigned int ID)¶
Mark all entities in this family to be fixed.
Set all meshes in this family to have this material.
- Parameters:
N – Family number.
mat – Material type.
-
void SetFamilyOwnerWildcardValue(unsigned int N, const std::string &name, const std::vector<float> &vals)¶
Modify the owner wildcard’s values of all entities in family N.
-
inline void SetFamilyOwnerWildcardValue(unsigned int N, const std::string &name, float val)¶
-
void SetFamilyPrescribedAngVel(unsigned int ID)¶
Let the angular velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedAngVel(unsigned int ID, const std::string &velX, const std::string &velY, const std::string &velZ, bool dictate = true, const std::string &pre = "none")¶
Set the prescribed angular velocity to all entities in a family.
- Parameters:
ID – Family number.
velX – X component of angular velocity.
velY – Y component of angular velocity.
velZ – Z component of angular velocity.
dictate – If true, this family will not be influenced by the force exerted from other simulation entites (both linear and rotational motions); if false, only specified components (that is, not specified with “none”) will not be influenced by the force exerted from other simulation entites.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void SetFamilyPrescribedAngVelX(unsigned int ID)¶
Let the X component of the angular velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedAngVelY(unsigned int ID)¶
Let the Y component of the angular velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedAngVelZ(unsigned int ID)¶
Let the Z component of the angular velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedLinVel(unsigned int ID)¶
Let the linear velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedLinVel(unsigned int ID, const std::string &velX, const std::string &velY, const std::string &velZ, bool dictate = true, const std::string &pre = "none")¶
If dictate is set to true, then.
Set the prescribed linear velocity to all entities in a family.
- Parameters:
ID – Family number.
velX – X component of velocity.
velY – Y component of velocity.
velZ – Z component of velocity.
dictate – If true, this family will not be influenced by the force exerted from other simulation entites (both linear and rotational motions); if false, only specified components (that is, not specified with “none”) will not be influenced by the force exerted from other simulation entites.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void SetFamilyPrescribedLinVelX(unsigned int ID)¶
Let the X component of the linear velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedLinVelY(unsigned int ID)¶
Let the Y component of the linear velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedLinVelZ(unsigned int ID)¶
Let the Z component of the linear velocities of all entites in this family always remain “as is” and not be influenced by the force exerted from other simulation entites.
-
void SetFamilyPrescribedPosition(unsigned int ID)¶
Let the linear positions of all entites in this family always remain “as is”.
-
void SetFamilyPrescribedPosition(unsigned int ID, const std::string &X, const std::string &Y, const std::string &Z, bool dictate = true, const std::string &pre = "none")¶
Keep the positions of all entites in this family to remain exactly the user-specified values.
- Parameters:
ID – Family number.
X – X coordinate (can be an expression).
Y – Y coordinate (can be an expression).
Z – Z coordinate (can be an expression).
dictate – If true, prevent entities in this family to have (both linear and rotational) positional updates resulted from the “simulation physics”; if false, only specified components (that is, not specified with “none”) will not be influenced by the force exerted from other simulation entites.
pre – Prerequisite code. For example, you can generate a float3 with this prerequisite code, then assign XYZ components based on this float3.
-
void SetFamilyPrescribedPositionX(unsigned int ID)¶
Let the X component of the linear positions of all entites in this family always remain “as is”.
-
void SetFamilyPrescribedPositionY(unsigned int ID)¶
Let the Y component of the linear positions of all entites in this family always remain “as is”.
-
void SetFamilyPrescribedPositionZ(unsigned int ID)¶
Let the Z component of the linear positions of all entites in this family always remain “as is”.
-
void SetFamilyPrescribedQuaternion(unsigned int ID)¶
Let the orientation quaternions of all entites in this family always remain “as is”.
-
void SetFamilyPrescribedQuaternion(unsigned int ID, const std::string &q_formula, bool dictate = true)¶
Keep the orientation quaternions of all entites in this family to remain exactly the user-specified values.
- Parameters:
ID – Family number.
q_formula – The code from which the quaternion should be calculated. Must return a float4. For example, “float tmp=make_float4(1,1,1,1); return tmp;”.
dictate – If true, prevent entities in this family to have (both linear and rotational) positional updates resulted from the “simulation physics”; otherwise, the “simulation physics” still takes effect.
-
inline void SetForceCalcThreadsPerBlock(unsigned int nTh)¶
Set the number of threads per block in force calculation (256, 128, 64 etc.).
-
void SetGPUTimersEnabled(bool enabled)¶
Enable or disable GPU event-based timing.
Disabling this avoids cudaEvent overhead in timed sections. Call this when the solver is not actively running dynamics.
-
inline void SetGravitationalAcceleration(const std::vector<float> &g)¶
-
void SetGravitationalAcceleration(float3 g)¶
Set gravitational pull. This takes effect immediately when called from a synchronized stance after Initialize().
-
inline void SetInitBinNumTarget(size_t num)¶
Set the target number of bins (for contact detection) at the start of the simulation upon initialization.
-
inline void SetInitBinSize(double bin_size)¶
Explicitly instruct the bin size (for contact detection) that the solver should use.
-
inline void SetInitBinSizeAsMultipleOfSmallestSphere(float bin_size)¶
Explicitly instruct the bin size (for contact detection) that the solver should use, as a multiple of the radius of the smallest sphere in simulation.
-
inline void SetInitTimeStep(double ts_size)¶
Legacy pre-initialization name for SetTimeStepSize. Kept for backward compatibility.
-
void SetIntegrator(const std::string &intg)¶
Set the time integrator for this simulator.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
- Parameters:
intg – “forward_euler” or “extended_taylor” or “centered_difference”.
-
inline void SetIntegrator(TIME_INTEGRATOR intg)¶
Set the time integrator for this simulator.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
inline void SetJitifyClumpTemplates(bool use = true)¶
Instruct the solver to rearrange and consolidate clump templates information, then jitify it into GPU kernels (if set to true), rather than using flattened sphere component configuration arrays whose entries are associated with individual spheres.
-
inline void SetJitifyMassProperties(bool use = true)¶
Instruct the solver to rearrange and consolidate mass property information (for all owner types), then jitify it into GPU kernels (if set to true), rather than using flattened mass property arrays whose entries are associated with individual owners.
-
inline void SetJitifyOptions(const std::vector<std::string> &options)¶
Set the jitification options. It is only needed by advanced users.
-
inline void SetKernelInclude(const std::string &includes)¶
Set the kernels’ headers’ extra include lines.
Useful for customization.
- Parameters:
includes – The extra headers, as a string.
Set the value for a material property that by nature involves a pair of a materials (e.g.
friction coefficient).
- Parameters:
name – The name of this property (which should have already been referred to in a previous LoadMaterial call).
mat1 – Material 1 that is involved in this pair.
mat2 – Material 2 that is involved in this pair.
val – The value.
-
void SetMaxSphereInBin(unsigned int max_sph)¶
Used to force the solver to error out when there are too many spheres in a bin.
A huge number can be used to discourage this error type.
- Parameters:
max_sph – Max number of spheres in a bin.
-
void SetMaxTriangleInBin(unsigned int max_tri)¶
Used to force the solver to error out when there are too many spheres in a bin.
A huge number can be used to discourage this error type.
- Parameters:
max_tri – Max number of triangles in a bin.
-
void SetMaxTriTriPenetration(double max_margin)¶
Set the maximum allowed triangle—triangle penetration used as the margin added in kT contact detection.
This value caps the penetration margin added to the triangle—triangle contact detection to prevent excessively large values. The default is a huge value, so if not called, it doesn’t affect the workflow. Note it only affects kT’s contact detection algorithm’s proactiveness in detecting future contacts, not capping the actual physical contact used in force calculation.
- Parameters:
max_margin – Maximum allowed penetration margin (must be non-negative).
-
void SetMaxVelocity(float max_vel)¶
Input the maximum expected particle velocity.
If “force” is set to false, the solver will not use a velocity larger than max_vel for determining the margin thickness; if “force” is set to true, the solver will not calculate maximum system velocity and will always use max_vel to calculate the margin thickness.
Set the maximum expected simulation velocity. Note this call is not necessarily required; the solver can automatically derive the maximum velocity. The velocity here means the magnitude of velocity of primtive geometries (spheres and triangles).
Additionally, the solver will not use a velocity larger than this for determining the margin thickness, and velocity larger than this will be considered a system anomaly.
- Parameters:
max_vel – Expected max velocity. After initialization, call UpdateSimParams() for this change to take effect in the workers.
-
void SetMeshOutputContent(const std::vector<std::string> &content)¶
Specify mesh VTK output fields by name. Supported names mirror MESH_OUTPUT_CONTENT.
-
inline void SetMeshOutputContent(MESH_OUTPUT_CONTENT content)¶
-
inline void SetMeshOutputContent(unsigned int content)¶
Specify per-triangle metadata to include in mesh VTK output. XYZ geometry is always written.
-
void SetMeshOutputFormat(const std::string &format)¶
Specify the output file format of meshes.
- Parameters:
format – A choice between “VTK”, “OBJ”.
-
inline void SetMeshOutputFormat(MESH_FORMAT format)¶
Specify the file format of meshes.
-
void SetMeshParticlesLowPoly(bool use = true)¶
Declare that all meshed particles in the simulation have a low polygon count.
Toggle this on only when mesh-mesh contacts are always SAT-traceable, i.e. no triangle from one mesh is expected to be completely submerged inside another mesh.
- Parameters:
use – If true, skip per-triangle mesh-mesh penetration-margin bookkeeping.
-
void SetMeshUniversalContact(bool use = true)¶
Set whether the meshes should have contacts with other meshes and analytical objects.
Set to false to speedup the simulation if its involved meshes are not expected to have contacts. The default is false.
- Parameters:
use – If true, meshes can have contacts with clumps, other meshes and analytical objects. If false, meshes can have contacts only with clumps.
-
inline void SetNoForceRecord(bool flag = true)¶
Instruct the solver that there is no need to record the contact force (and contact point location etc.) in an array.
If set to true, the contact forces must be reduced to accelerations right in the force calculation kernel (meaning SetCollectAccRightAfterForceCalc is effectively called too). Calling this method could reduce some memory usage, but will disable contact pair output.
Note
After initialization, call UpdateSimParams() for this change to take effect in dT.
-
void SetOutputContent(const std::vector<std::string> &content)¶
Specify the information that needs to go into the clump or sphere output files.
- Parameters:
content – A list of “XYZ”, “QUAT”, “ABSV”, “VEL”, “ANG_VEL”, “ABS_ACC”, “ACC”, “ANG_ACC”, “FAMILY”, “MAT”, and/or “OWNER_WILDCARD”.
-
inline void SetOutputContent(unsigned int content)¶
Specify the information that needs to go into the clump or sphere output files.
-
void SetOutputFormat(const std::string &format)¶
Choose sphere and clump output file format.
- Parameters:
format – Choice among “CSV”, “BINARY”, and “VTK”. VTK is supported by WriteSphereFile.
-
inline void SetOutputFormat(OUTPUT_FORMAT format)¶
Choose output format.
-
void SetOwnerAngVel(bodyID_t ownerID, const std::vector<float3> &angVel)¶
Set angular velocity of consecutive owners starting from ownerID, based on input angular velocity vector.
N (the size of the input vector) elements will be modified.
-
void SetOwnerAngVelFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Synchronously set local-frame angular velocities directly from CUDA memory.
A zero count is a no-op.
- Parameters:
validate – See SetOwnerPositionFromDevice.
-
void SetOwnerAngVelGlobalFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Synchronously set global angular velocities directly from CUDA memory.
Conversion to DEME’s local frame uses each owner’s orientation at the time of this call. A zero count is a no-op.
- Parameters:
validate – See SetOwnerPositionFromDevice.
-
void SetOwnerFamily(bodyID_t ownerID, unsigned int fam, bodyID_t n = 1)¶
Set the family number of consecutive owners.
- Parameters:
ownerID – The ID of the owner.
fam – Family number.
n – Number of consecutive owners.
-
void SetOwnerOriQ(bodyID_t ownerID, const std::vector<float4> &oriQ)¶
Set quaternion of consecutive owners starting from ownerID.
Finite, nonzero inputs are normalized before being stored; invalid quaternions are rejected. N (the size of the input vector) elements will be modified.
-
void SetOwnerOriQFromDevice(bodyID_t ownerID, const float4 *source, int source_device, size_t count = 1, bool validate = true)¶
Synchronously set public-order (x, y, z, w) orientations directly from CUDA memory.
Inputs are normalized before being stored; with validation enabled, non-finite and zero-length quaternions are rejected. A zero count is a no-op.
- Parameters:
validate – See SetOwnerPositionFromDevice. When false, the extra validity-check kernel is skipped, but quaternion normalization remains part of the setter’s semantics.
-
void SetOwnerPosition(bodyID_t ownerID, const std::vector<float3> &pos)¶
Set position of consecutive owners starting from ownerID, based on input position vector.
N (the size of the input vector) elements will be modified.
-
void SetOwnerPositionFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Synchronously set global positions for consecutive owners directly from CUDA memory.
The source may belong to any logical CUDA device accessible to this process; remote input is copied to dT before unpacking. A zero count is a no-op.
- Parameters:
source_device – Logical CUDA device owning `source`.
validate – If true, validate the owner range and CUDA pointer metadata. Disable only when the caller guarantees those preconditions and needs to avoid validation overhead.
-
void SetOwnerVelocity(bodyID_t ownerID, const std::vector<float3> &vel)¶
Set velocity of consecutive owners starting from ownerID, based on input velocity vector.
N (the size of the input vector) elements will be modified.
-
void SetOwnerVelocityFromDevice(bodyID_t ownerID, const float3 *source, int source_device, size_t count = 1, bool validate = true)¶
Synchronously set global linear velocities directly from CUDA memory.
A zero count is a no-op.
- Parameters:
validate – See SetOwnerPositionFromDevice.
-
void SetOwnerWildcards(const std::set<std::string> &wildcards)¶
Set the names for the extra quantities that will be associated with each owner.
-
void SetOwnerWildcardValue(bodyID_t ownerID, const std::string &name, const std::vector<float> &vals)¶
Set the wildcard values of some owners.
- Parameters:
ownerID – The ID of the starting (first) owner that needs to be modified.
name – The name of the wildcard.
vals – A vector of values that will be assigned to the owners starting from ownerID.
-
inline void SetOwnerWildcardValue(bodyID_t ownerID, const std::string &name, float val, size_t n = 1)¶
Set the wildcard values of some owners.
- Parameters:
ownerID – The ID of the starting (first) owner that needs to be modified.
name – The name of the wildcard.
val – The value to set.
n – The number of owners starting from the first that will be modified by this call. Default is 1.
-
void SetPersistentContact(bool use = true)¶
Set whether the solver should expect the user to mark certain contacts as persistent across kT updates.
Set this to true if you later will call MarkPersistentContact series of methods.
- Parameters:
use – If true, the solver will expect the user to mark certain contacts as persistent across kT updates. If false, all contacts are treated as non-persistent.
-
void SetSimplePatchCombination(bool use = true)¶
Set whether to use simple patch ID-based triangle combination.
- Parameters:
use – If true, all triangles sharing the same patch ID pair are combined into one patch contact.
-
void SetSimTime(double time)¶
Set the simulation time manually.
-
inline void SetSortContactPairs(bool use_sort)¶
Do not use this method. It has no effect.
-
void SetStablePatchIslandIDs(bool use = true)¶
Set whether flooded patch-island IDs should be stabilized across contact-detection steps.
-
void SetTimeStepSize(double ts_size)¶
Set the time step size before or after initialization.
Post-initialization calls must be made from a synchronized stance and take effect on the next step.
-
void SetTrianglePVTrackingOwners(const std::vector<bodyID_t> &mesh_owner_ids)¶
Enable per-triangle P/V/PxV tracking for the specified mesh owners.
Owner IDs are simulation owner IDs; each selected owner must be a mesh owner. Tracking buffers are reset when this method is called.
-
void SetTriNodeRelPos(size_t owner, size_t triID, const std::vector<float3> &new_nodes)¶
Rewrite the relative positions of the flattened triangle soup.
-
void SetTriTriContactRejectionRatio(float ratio)¶
Set the ratio threshold used to reject suspicious triangle-triangle contacts.
A negative value disables this guard when the corresponding contact kernel support is enabled.
-
void SetTriTriPenetration(double penetration)¶
Manually seed the current triangle—triangle penetration margin in dT.
This fills every entry of the per-triangle maxTriTriPenetration array with the same value, which will be used in the NEXT contact detection run in kT. One use case is if at the start of simulation, there is already significant mesh—mesh penetration, then without calling this method, the solver might not be able to resolve triangles that are deeply inside another mesh. Use this method to boost the solver’s mesh—mesh contact detection proactiveness for one step, then the solver will automatically know how much of an extra margin it needs to add from this step onwards.
- Parameters:
penetration – The penetration value to assign to each triangle (must be non-negative).
-
void SetUseAngularVelocityMargin(bool use)¶
Control whether angular velocity contributes to the contact detection margin.
Default is auto: false for pure single-sphere clumps; true when multi-sphere clumps or meshes exist.
-
void SetVerbosity(const std::string &verbose)¶
Set the verbosity level of the solver.
- Parameters:
verbose – “QUIET”, “ERROR”, “WARNING”, “INFO”, “METRIC” or “DEBUG”. Recommend “INFO”.
-
void SetVerbosity(verbosity_t verbose)¶
Set output detail level.
-
void ShowAnomalies()¶
Show the anomalies that have been recorded in the log.
This is useful for debugging and for users to understand what potentially went wrong in their simulation.
-
void ShowMemStats() const¶
Print the current memory usage in pretty format.
-
void ShowThreadCollaborationStats()¶
Show the collaboration stats between dT and kT.
This is more useful for tweaking the number of time steps that dT should be allowed to be in advance of kT.
-
void ShowTimingStats()¶
Show the wall time and percentages of wall time spend on various solver tasks.
-
void ShowWarnings()¶
Show error and warnings.
-
void SyncMemoryTransfer()¶
If the user used async-ed version of a tracker’s get/set methods (to get a speed boost in many piecemeal accesses of a long array), this method should be called to mark the end of to-host transactions.
But usually, the user would use sync-ed version of the methods by default and this call is not needed in that case.
Create a single tracker that tracks all member owners in a combined-instances batch.
The tracker references all owners instantiated by the batch. Since AddCombinedFromTemplate creates owners in consecutive memory, a single tracker with an offset range covers them all. Use the offset parameter in tracker query methods to access individual owners.
Create a DEMTracker to allow direct control/modification/query to this external object/batch of clumps/triangle mesh object.
By default, it refers to the first clump in this batch. The user can refer to other clumps in this batch by supplying an offset when using this tracker’s querying or assignment methods.
-
void Update()¶
Transfer newly loaded clumps and meshes to the GPU-side in mid-simulation.
-
inline void UpdateClumps()¶
Legacy method name for Update.
-
void UpdateSimParams()¶
Transferthe cached sim params to the workers.
Used for sim environment modification after system initialization.
-
void UpdateStepSize(double ts)¶
Legacy post-initialization name for SetTimeStepSize.
Kept for backward compatibility.
- Parameters:
ts – Time step size.
-
void UpdateTriNodeRelPos(size_t owner, size_t triID, const std::vector<float3> &updates)¶
Update the relative positions of the flattened triangle soup.
-
inline void UseAdaptiveBinSize(bool use = true)¶
Enable or disable the use of adaptive bin size (by default it is on).
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
- Parameters:
use – Enable or disable.
-
inline void UseAdaptiveUpdateFreq(bool use = true)¶
Enable or disable adaptive max update step count.
Note
After initialization, call UpdateSimParams() for this change to take effect in the workers.
- Parameters:
use – Enable or disable.
-
std::shared_ptr<DEMForceModel> UseFrictionalHertzianModel()¶
Instruct the solver to use frictonal (history-based) Hertzian contact force model.
-
std::shared_ptr<DEMForceModel> UseFrictionlessHertzianModel()¶
Instruct the solver to use frictonless Hertzian contact force model.
-
inline void UseHertzConstTimeStep()¶
Use the setup-time Hertzian constant timestep estimate.
-
void WaitForPendingOutput() const¶
Wait for any in-flight async output to finish.
-
inline void WriteAnalyticalFile(const std::filesystem::path &outfilename, unsigned int circumferential_resolution = 32) const¶
-
void WriteAnalyticalFile(const std::string &outfilename, unsigned int circumferential_resolution = 32) const¶
Write directly displayable VTK surfaces for all analytical boundary components.
Infinite primitives are clipped to the domain specified by InstructBoxDomainDimension.
-
inline void WriteClumpFile(const std::filesystem::path &outfilename, unsigned int accuracy = 10) const¶
-
void WriteClumpFile(const std::string &outfilename, unsigned int accuracy = 10) const¶
Output methods enqueue asynchronous writes; call WaitForPendingOutput() to block for completion.
Write the current status of clumps to a file
-
inline void WriteContactFile(const std::filesystem::path &outfilename) const¶
-
void WriteContactFile(const std::string &outfilename, float force_thres = 1e-12) const¶
Write all contact pairs to a file.
The outputted torque using this method is in global, rather than each object’s local coordinate system.
- Parameters:
outfilename – Output filename.
force_thres – Forces with magnitude smaller than this amount will not be outputted.
-
inline void WriteContactFileIncludingPotentialPairs(const std::filesystem::path &outfilename) const¶
-
inline void WriteContactFileIncludingPotentialPairs(const std::string &outfilename) const¶
Write all contact pairs kT-supplied to a file, thus including the potential ones (those are not yet in contact, or recently used to be in contact).
The outputted torque using this method is in global, rather than each object’s local coordinate system.
- Parameters:
outfilename – Output filename.
-
inline void WriteMeshFile(const std::filesystem::path &outfilename) const¶
-
void WriteMeshFile(const std::string &outfilename) const¶
Write the current status of all meshes to a file.
-
inline void WriteSphereFile(const std::filesystem::path &outfilename) const¶
-
void WriteSphereFile(const std::string &outfilename) const¶
Write the current status of “clumps” to a file, but not as clumps, instead, as each individual sphere.
CSV and VTK formats are supported. VTK stores sphere centers and the `r` radius scalar as point data for ParaView’s Glyph filter, avoiding duplicated sphere tessellations in every output frame.
-
~DEMSolver()¶
Public Static Functions
-
static inline std::unordered_map<std::string, std::vector<float3>> ReadClumpAngVelFromCsv(const std::string &infilename)¶
Read clump angular velocity from a CSV file (whose format is consistent with this solver’s clump output file).
Returns an unordered_map which maps each unique clump type name to a vector of float3 (angular velocity).
-
static inline std::unordered_map<std::string, std::vector<float3>> ReadClumpFloat3FromCsv(const std::string &infilename, const std::string &x_header, const std::string &y_header, const std::string &z_header, const std::string &clump_header)¶
Read 3 columns of your choice from a CSV filem and group them by clump_header.
- Parameters:
infilename – CSV filename.
x_header – CSV header for the first col.
y_header – CSV header for the second col.
z_header – CSV header for the third col.
clump_header – The identifier column to separate types of clumps.
- Returns:
Unordered_map which maps types of clumps to a respective vector of float3s.
-
static inline std::unordered_map<std::string, std::vector<float4>> ReadClumpQuatFromCsv(const std::string &infilename)¶
Read clump quaternions from a CSV file (whose format is consistent with this solver’s clump output file).
Returns an unordered_map which maps each unique clump type name to a vector of float4 (4 components of the quaternion, (Qx, Qy, Qz, Qw) = (0, 0, 0, 1) means 0 rotation).
-
static inline std::unordered_map<std::string, std::vector<float3>> ReadClumpVelFromCsv(const std::string &infilename)¶
Read clump velocity from a CSV file (whose format is consistent with this solver’s clump output file).
Returns an unordered_map which maps each unique clump type name to a vector of float3 (velocity).
-
static inline std::unordered_map<std::string, std::vector<float3>> ReadClumpXyzFromCsv(const std::string &infilename)¶
Read clump coordinates from a CSV file (whose format is consistent with this solver’s clump output file).
Returns an unordered_map which maps each unique clump type name to a vector of float3 (XYZ coordinates).
-
static inline std::vector<std::pair<bodyID_t, bodyID_t>> ReadContactPairsFromCsv(const std::string &infilename, const std::string &cntType = OUTPUT_FILE_SPH_SPH_CONTACT_NAME, const std::string &cntColName = OUTPUT_FILE_CNT_TYPE_NAME, const std::string &first_name = OUTPUT_FILE_GEO_ID_1_NAME, const std::string &second_name = OUTPUT_FILE_GEO_ID_2_NAME)¶
Read all contact pairs (geometry ID) from a contact file.
-
static inline std::unordered_map<std::string, std::vector<float>> ReadContactWildcardsFromCsv(const std::string &infilename, const std::string &cntType = OUTPUT_FILE_SPH_SPH_CONTACT_NAME, const std::string &cntColName = OUTPUT_FILE_CNT_TYPE_NAME)¶
Read all contact wildcards from a contact file.
Tracking and inspection¶
-
class DEMTracker¶
A helper for querying or modifying tracked owners, mainly for co-simulation.
Fixed-size `ToDevice` and `FromDevice` methods validate owner ranges, capacities, and CUDA pointer metadata by default. Their trailing `validate` argument may be set to false when the caller guarantees those preconditions and needs to avoid validation overhead. Required device-routing constraints and the documented data transformations, including quaternion normalization, still apply when validation is disabled.
Public Functions
-
void AddAcc(const std::vector<float3> &acc)¶
Add an extra acc to n consecutive tracked objects, (only) for the next time step.
Note if the user intends to add a persistent external force, then using family prescription is the better method.
-
void AddAcc(float3 acc, size_t offset = 0)¶
Add an extra acc to the tracked body, (only) for the next time step.
Note if the user intends to add a persistent external force, then using family prescription is the better method.
-
void AddAccFromDevice(const float3 *source, int source_device, bool validate = true)¶
Queue one global-frame linear acceleration per tracked owner directly from CUDA memory.
This is the device-input counterpart of the vector AddAcc overload. Values preserve tracker owner order and replace any previously queued next-step linear-acceleration contribution for those owners. Contact acceleration is accumulated on top during the next force/integration step, gravity is applied separately, and the queued contribution is consumed after one step. The call is synchronous.
- Parameters:
source – CUDA memory containing one float3 global-frame acceleration per tracked owner.
source_device – Logical CUDA device owning `source`; remote input is copied to dT before unpacking.
validate – Whether to validate the owner range and CUDA pointer metadata.
-
void AddAngAcc(const std::vector<float3> &angAcc)¶
Add an extra angular acceleration to n consecutive tracked objects, (only) for the next time step.
Note if the user intends to add a persistent external torque, then using family prescription is the better method.
-
void AddAngAcc(float3 angAcc, size_t offset = 0)¶
Add an extra angular acceleration to the tracked body, (only) for the next time step.
Note if the user intends to add a persistent external torque, then using family prescription is the better method.
-
void AddAngAccFromDevice(const float3 *source, int source_device, bool validate = true)¶
Queue one local-frame angular acceleration per tracked owner directly from CUDA memory.
This is the device-input counterpart of the vector AddAngAcc overload. Values preserve tracker owner order, use each owner’s local principal-axis frame, and replace any previously queued next-step angular- acceleration contribution. Contact angular acceleration is accumulated on top during the next force/integration step, and the queued contribution is consumed after one step. The call is synchronous.
- Parameters:
source – CUDA memory containing one float3 local-frame angular acceleration per tracked owner.
source_device – Logical CUDA device owning `source`; remote input is copied to dT before unpacking.
validate – Whether to validate the owner range and CUDA pointer metadata.
-
std::vector<float3> AngularVelocitiesGlobal()¶
Get the angular velocity of all objects tracked by this tracker, in global coordinate system.
-
void AngularVelocitiesGlobalToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked global-frame angular velocities.
-
std::vector<float3> AngularVelocitiesLocal()¶
Get the angular velocity of all tracked objects in their own local coordinate system.
Applying OriQ to it would give you the ang vel in global frame.
-
void AngularVelocitiesLocalToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked local-frame angular velocities.
-
float3 AngVelGlobal(size_t offset = 0)¶
Get the angular velocity of this tracked object in global coordinate system.
-
float3 AngVelLocal(size_t offset = 0)¶
Get the angular velocity of this tracked object in its own local coordinate system.
Applying OriQ to it would give you the ang vel in global frame.
-
float3 ContactAcc(size_t offset = 0)¶
Get the portion of the acceleration of this tracked object, that is the result of its contact with other simulation entities.
The acceleration is in global frame.
In most cases, this means the acceleration excluding the gravitational acceleration.
-
std::vector<float3> ContactAccelerations()¶
Get the acceleration experienced by all objects tracked by this tracker, that is the result of their contact with other simulation entities.
The acceleration is in global frame.
In most cases, this means the acceleration excluding the gravitational acceleration.
-
void ContactAccelerationsToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked global-frame contact accelerations.
-
float3 ContactAngAccGlobal(size_t offset = 0)¶
Get the a portion of the angular acceleration of this tracked object, that is the result of its contact with other simulation entities.
The acceleration is in this object’s global frame.
In most cases, this means the angular acceleration excluding the gravitational acceleration.
-
float3 ContactAngAccLocal(size_t offset = 0)¶
Get the a portion of the angular acceleration of this tracked object, that is the result of its contact with other simulation entities.
The acceleration is in this object’s local frame.
In most cases, this means the angular acceleration excluding the gravitational acceleration.
-
std::vector<float3> ContactAngularAccelerationsGlobal()¶
Get the angular acceleration experienced by all objects tracked by this tracker, that is the result of their contact with other simulation entities.
The acceleration is in this object’s global frame.
In most cases, this means the angular acceleration excluding the gravitational acceleration.
-
void ContactAngularAccelerationsGlobalToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked global-frame contact angular accelerations.
-
std::vector<float3> ContactAngularAccelerationsLocal()¶
Get the angular acceleration experienced by all objects tracked by this tracker, that is the result of their contact with other simulation entities.
The acceleration is in this object’s local frame.
In most cases, this means the angular acceleration excluding the gravitational acceleration.
-
void ContactAngularAccelerationsLocalToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked local-frame contact angular accelerations.
-
void ContactWrenches(std::vector<float3> &forces, std::vector<float3> &torques)¶
Get one reduced contact wrench for every owner tracked by this tracker.
Forces are global-frame contact-force resultants. Torques are global-frame moments about each owner’s current DEME position and include force-generated moments plus force-model-only torque such as rolling resistance. The vectors preserve tracker owner order and contain zero for owners without recorded contact. This reads the current dT force records without triggering contact detection or force evaluation. Contact recording must remain enabled (the default).
- Parameters:
forces – Output resultant forces, resized to the number of tracked owners.
torques – Output resultant torques, resized to the number of tracked owners.
-
void ContactWrenchesToDevice(float3 *force_destination, float3 *torque_destination, size_t capacity, int destination_device)¶
Write one reduced contact wrench per tracked owner directly to CUDA memory.
This is the device-output counterpart of ContactWrenches and preserves tracker owner order. Forces are global-frame contact-force resultants. Torques are global-frame moments about each owner’s current DEME position and include force-generated moments plus force-model-only torque. Owners without recorded contact receive a zero wrench. This reads current dT force records without triggering contact detection or force evaluation. Contact recording must remain enabled. The call is synchronous; CUDA selects the available inter-device transfer route for cross-device output.
- Parameters:
force_destination – Writable CUDA memory for one float3 force per tracked owner.
torque_destination – Writable CUDA memory for one float3 torque per tracked owner.
capacity – Available elements in each destination buffer; must cover every tracked owner.
destination_device – Logical CUDA device owning both destination buffers.
-
void FamiliesToDevice(unsigned int *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked family numbers as unsigned integers.
-
std::vector<std::vector<float>> GetAngularVelocitiesGlobal()¶
-
std::vector<std::vector<float>> GetAngularVelocitiesLocal()¶
-
std::vector<float> GetAngVelGlobal(size_t offset = 0)¶
-
std::vector<float> GetAngVelLocal(size_t offset = 0)¶
-
std::vector<float> GetContactAcc(size_t offset = 0)¶
-
std::vector<std::vector<float>> GetContactAccelerations()¶
-
std::vector<float> GetContactAngAccGlobal(size_t offset = 0)¶
-
std::vector<float> GetContactAngAccLocal(size_t offset = 0)¶
-
std::vector<std::vector<float>> GetContactAngularAccelerationsGlobal()¶
-
std::vector<std::vector<float>> GetContactAngularAccelerationsLocal()¶
-
std::vector<bodyID_t> GetContactClumps(size_t offset = 0)¶
Get the clumps that are in contact with this tracked owner as a vector.
No bulk version that gets the contacting clumps for all the entities tracked by this tracker. This is efficiency concern. If you need to get all contact pairs involving all clumps tracked by this tracker, consider putting them in one family and use DEMSolver’s GetClumpContacts method, then the owner ID list-based GetOwnerContactForces method if you further need the contact forces information.
- Parameters:
offset – Offset to the first item this tracker is tracking. Default is 0.
- Returns:
Clump owner IDs in contact with this owner.
-
size_t GetContactForces(std::vector<float3> &points, std::vector<float3> &forces, size_t offset = 0)¶
Get all contact forces that concern this track object, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
offset – The offset to this owner (where to start querying). If first entity, input 0.
- Returns:
Number of force pairs.
-
size_t GetContactForcesAndGlobalTorque(std::vector<float3> &points, std::vector<float3> &forces, std::vector<float3> &torques, size_t offset = 0)¶
Get all contact forces and global torques that concern this track object, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences. Since we are getting all force pairs, the torque should be considered as “extra torque”, since you should be able to derive the normal and tangential force-induced torques based on all the force pairs. The extra torques emerge depending on your force model. For example, in the default force model, rolling friction could contribute to the torque. But if you do not have rolling friction, then you do not have torque here. The torques are given in the global frame of this object that is being tracked.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
torques – The contact torque. The torque is in global frame.
offset – The offset to this owner (where to start querying). If first entity, input 0.
- Returns:
Number of force pairs.
-
size_t GetContactForcesAndGlobalTorqueForAll(std::vector<float3> &points, std::vector<float3> &forces, std::vector<float3> &torques)¶
Get all contact forces and global torques that concern all objects tracked by this tracker, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences. Since we are getting all force pairs, the torque should be considered as “extra torque”, since you should be able to derive the normal and tangential force-induced torques based on all the force pairs. The extra torques emerge depending on your force model. For example, in the default force model, rolling friction could contribute to the torque. But if you do not have rolling friction, then you do not have torque here. The torques are given in the global frame of this object that is being tracked. If a contact involves two owners this tracker tracks, then the force for that contact will be given as the force experienced by whichever owner that appears earlier in the list of owners.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
torques – The contact torque. The torque is in global frame.
- Returns:
Number of force pairs.
-
size_t GetContactForcesAndGlobalTorqueForAllToDevice(float3 *points, float3 *forces, float3 *torques, size_t capacity, int destination_device)¶
Fill CUDA memory with contact points, forces, and global extra torques for all tracked owners.
-
size_t GetContactForcesAndGlobalTorqueToDevice(float3 *points, float3 *forces, float3 *torques, size_t capacity, int destination_device, size_t offset = 0)¶
Fill CUDA memory with contact points, forces, and global extra torques for one tracked owner.
-
size_t GetContactForcesAndLocalTorque(std::vector<float3> &points, std::vector<float3> &forces, std::vector<float3> &torques, size_t offset = 0)¶
Get all contact forces and local torques that concern this track object, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences. Since we are getting all force pairs, the torque should be considered as “extra torque”, since you should be able to derive the normal and tangential force-induced torques based on all the force pairs. The extra torques emerge depending on your force model. For example, in the default force model, rolling friction could contribute to the torque. But if you do not have rolling friction, then you do not have torque here. The torques are given in the local frame of this object that is being tracked.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
torques – The contact torque. The torque is in local frame.
offset – The offset to this owner (where to start querying). If first entity, input 0.
- Returns:
Number of force pairs.
-
size_t GetContactForcesAndLocalTorqueForAll(std::vector<float3> &points, std::vector<float3> &forces, std::vector<float3> &torques)¶
Get all contact forces and local torques that concern all objects tracked by this tracker, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences. Since we are getting all force pairs, the torque should be considered as “extra torque”, since you should be able to derive the normal and tangential force-induced torques based on all the force pairs. The extra torques emerge depending on your force model. For example, in the default force model, rolling friction could contribute to the torque. But if you do not have rolling friction, then you do not have torque here. The torques are given in the local frame of this object that is being tracked. If a contact involves two owners this tracker tracks, then the force for that contact will be given as the force experienced by whichever owner that appears earlier in the list of owners.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
torques – The contact torque. The torque is in local frame.
- Returns:
Number of force pairs.
-
size_t GetContactForcesAndLocalTorqueForAllToDevice(float3 *points, float3 *forces, float3 *torques, size_t capacity, int destination_device)¶
Fill CUDA memory with contact points, forces, and local extra torques for all tracked owners.
-
size_t GetContactForcesAndLocalTorqueToDevice(float3 *points, float3 *forces, float3 *torques, size_t capacity, int destination_device, size_t offset = 0)¶
Fill CUDA memory with contact points, forces, and local extra torques for one tracked owner.
-
size_t GetContactForcesForAll(std::vector<float3> &points, std::vector<float3> &forces)¶
Get all contact forces that concern all objects tracked by this tracker, as a vector.
Every force pair will be queried using this function, instead of a reduced total force that this object experiences. If a contact involves two owners this tracker tracks, then the force for that contact will be given as the force experienced by whichever owner that appears earlier in the list of owners.
- Parameters:
points – The contact point XYZ as float3 vector.
forces – The force in XYZ as float3 vector. The force in global frame.
- Returns:
Number of force pairs.
-
size_t GetContactForcesForAllToDevice(float3 *points, float3 *forces, size_t capacity, int destination_device)¶
Fill CUDA memory with contact points/forces concerning all tracked owners.
-
size_t GetContactForcesToDevice(float3 *points, float3 *forces, size_t capacity, int destination_device, size_t offset = 0)¶
Fill CUDA memory with contact points/forces for one tracked owner. Capacity must cover the total contact count.
-
std::vector<unsigned int> GetFamilies()¶
Get the family numbers of all the tracked object.
- Returns:
The family numbers as a vector.
-
unsigned int GetFamily(size_t offset = 0)¶
Get the family number of the tracked object.
- Parameters:
offset – The offset of the entites to get family number out of.
- Returns:
The family number.
-
std::shared_ptr<DEMMesh> &GetMesh()¶
Get a handle for the mesh this tracker is tracking.
- Returns:
Pointer to the mesh.
-
std::vector<float3> GetMeshNodesGlobal()¶
Get the current locations of all the nodes in the mesh being tracked.
- Returns:
A vector of float3 representing the global coordinates of the mesh nodes.
-
std::vector<float> GetMOI(size_t offset = 0)¶
-
std::vector<std::vector<float>> GetMOIs()¶
-
std::vector<std::vector<float>> GetOrientationQuaternions()¶
Get all quaternions that represent the orientation of all the tracked objects’ own coordinate systems.
- Returns:
A vector of 4-float vectors. The order is (x, y, z, w). If compared against Chrono naming convention, then it is saying our ordering here is (e1, e2, e3, e0).
-
std::vector<float> GetOriQ(size_t offset = 0)¶
Get the quaternion that represents the orientation of this tracked object’s own coordinate system.
- Returns:
A vector of 4 floats. The order is (x, y, z, w). If compared against Chrono naming convention, then it is saying our ordering here is (e1, e2, e3, e0).
-
bodyID_t GetOwnerID(size_t offset = 0)¶
Get the owner ID of the tracked obj.
-
std::vector<bodyID_t> GetOwnerIDs()¶
Get the owner IDs of all the tracked objects.
-
float GetOwnerWildcardValue(const std::string &name, size_t offset = 0)¶
Get the owner’s wildcard value.
-
std::vector<float> GetOwnerWildcardValues(const std::string &name)¶
Get the owner wildcard values for all the owners entities tracked by this tracker.
- Parameters:
name – Name of the wildcard.
- Returns:
All the values.
-
std::vector<float> GetPos(size_t offset = 0)¶
-
std::vector<std::vector<float>> GetPositions()¶
-
std::vector<float> GetVel(size_t offset = 0)¶
-
std::vector<std::vector<float>> GetVelocities()¶
-
float Mass(size_t offset = 0)¶
Get the mass of the tracked object.
- Parameters:
offset – The offset to this entites. If first entites, input 0.
- Returns:
Mass.
-
std::vector<float> Masses()¶
Get the masses of all the tracked objects.
- Returns:
Masses as a vector.
-
void MassesToDevice(float *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked masses.
-
float3 MOI(size_t offset = 0)¶
Get the moment of inertia (in principal axis frame) of the tracked object.
- Parameters:
offset – The offset to this entites. If first entites, input 0.
- Returns:
The moment of inertia (in principal axis frame).
-
std::vector<float3> MOIs()¶
Get the moment of inertia (in principal axis frame) of all the tracked objects.
- Returns:
The moment of inertia (in principal axis frame) of each element as a vector.
-
void MOIsToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked principal moments of inertia.
-
std::vector<float4> OrientationQuaternions()¶
Get all quaternions that represent the orientation of all the tracked objects’ own coordinate systems.
-
void OrientationQuaternionsToDevice(float4 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked public-order (x, y, z, w) quaternions.
-
float4 OriQ(size_t offset = 0)¶
Get the quaternion that represents the orientation of this tracked object’s own coordinate system.
-
void OwnerWildcardValuesToDevice(const std::string &name, float *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with one wildcard value for every tracked owner.
-
float3 Pos(size_t offset = 0)¶
Get the position of this tracked object.
-
std::vector<float3> Positions()¶
Get the positions of all tracked objects.
-
void PositionsToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked positions. Capacity is measured in float3 elements.
-
void SetAngularVelocitiesFromDevice(const float3 *source, int source_device, bool validate = true)¶
Synchronously set all tracked local-frame angular velocities from CUDA memory.
-
void SetAngularVelocitiesGlobalFromDevice(const float3 *source, int source_device, bool validate = true)¶
Synchronously set all tracked global angular velocities from CUDA memory.
-
void SetAngVel(const std::vector<float3> &angVel)¶
Set the angular velocity of n consecutive tracked objects in their own local coordinate systems.
-
void SetAngVel(float3 angVel, size_t offset = 0)¶
Set the angular velocity of this tracked object in its own local coordinate system.
-
void SetFamily(unsigned int fam_num)¶
Change the family numbers of all the entities tracked by this tracker.
- Parameters:
fam_num – Family number to change to.
-
void SetFamily(unsigned int fam_num, size_t offset)¶
Change the family number of one entities tracked by this tracker.
- Parameters:
fam_num – Family number to change to.
offset – The offset to this entites. If first entites, input 0.
-
void SetOrientationQuaternionsFromDevice(const float4 *source, int source_device, bool validate = true)¶
Synchronously set and normalize all tracked public-order (x, y, z, w) quaternions from CUDA memory.
-
void SetOriQ(const std::vector<float4> &oriQ)¶
Set the quaternion which represents the orientation of n consecutive tracked objects’ coordinate systems.
-
void SetOriQ(float4 oriQ, size_t offset = 0)¶
Set the quaternion which represents the orientation of this tracked object’s coordinate system.
-
void SetOwnerWildcardValue(const std::string &name, float wc, size_t offset = 0)¶
Set owner wildcard value of a owner this tracker is tracking.
- Parameters:
name – Name of the wildcard.
wc – Wildcard value.
offset – The offset to this owner (where to start the modification). If first owner, input 0.
-
void SetOwnerWildcardValues(const std::string &name, const std::vector<float> &wc)¶
Set owner wildcard values of all the owners this tracker is tracking.
- Parameters:
name – Name of the wildcard.
wc – Wildcard values as a vector (must have same length as the number of tracked owners).
-
void SetPos(const std::vector<float3> &pos)¶
Set the positions of n consecutive tracked objects.
-
void SetPos(float3 pos, size_t offset = 0)¶
Set the position of this tracked object.
-
void SetPositionsFromDevice(const float3 *source, int source_device, bool validate = true)¶
Synchronously set all tracked global positions from CUDA memory.
-
void SetVel(const std::vector<float3> &vel)¶
Set the velocity of n consecutive tracked objects in global frame.
-
void SetVel(float3 vel, size_t offset = 0)¶
Set the velocity of this tracked object in global frame.
-
void SetVelocitiesFromDevice(const float3 *source, int source_device, bool validate = true)¶
Synchronously set all tracked global linear velocities from CUDA memory.
-
void UpdateMesh(const std::vector<float3> &new_nodes)¶
Apply the new mesh node positions such that the tracked mesh is replaced by the new_nodes.
This affects triangle facets’ relative positions wrt the mesh center (CoM) only; mesh’s overall position/rotation in simulation is not affected. So if provided input is the new mesh location with consideration of its CoM’s motion, then you should not use tracker to further modify the mesh’s CoM; if the provided input is the new mesh location without considering the displacement of mesh’s CoM (aka only the mesh deformation), then you should then use tracker to further update the mesh’s CoM.
- Parameters:
new_nodes – New locations of mesh nodes. The length of the argument vector must agree with the number of nodes in the tracked mesh.
-
void UpdateMeshByIncrement(const std::vector<float3> &deformation)¶
Change the coordinates of each mesh node by the given amount.
This affects triangle facets’ relative positions wrt the mesh center (CoM) only; mesh’s overall position/rotation in simulation is not affected. So if provided input is the mesh deformation with consideration of its CoM’s motion, then you should not use tracker to further modify the mesh’s CoM; if the provided input is the mesh deformation without considering the displacement of mesh’s CoM, then you should then use tracker to further update the mesh’s CoM.
- Parameters:
deformation – Deformation of mesh nodes. The length of the argument vector must agree with the number of nodes in the tracked mesh.
-
float3 Vel(size_t offset = 0)¶
Get the velocity of this tracked object in global frame.
-
std::vector<float3> Velocities()¶
Get the velocities of all objects tracked by this tracker, in global frame.
-
void VelocitiesToDevice(float3 *destination, size_t capacity, int destination_device, bool validate = true)¶
Fill CUDA-accessible memory with all tracked global-frame velocities.
-
inline ~DEMTracker()¶
Public Members
-
std::shared_ptr<DEMTrackedObj> obj¶
-
void AddAcc(const std::vector<float3> &acc)¶
-
class DEMInspector¶
A class that the user can construct to inspect a certain property (such as void ratio, maximum Z coordinate…) of their simulation entites, in a given region.
Public Functions
-
inline DEMInspector(DEMSolver *sim_sys, DEMDynamicThread *dT_sys, const std::string &quantity, const std::string ®ion)¶
-
float *dT_GetDeviceValues()¶
Get values on device without forcing a host sync (internal dT worker use).
-
float *dT_GetValue()¶
Get the value (as a vector) of the quantity that you wish to inspect.
Get value directly within dT (returns host pointer by default)
-
float GetDeviceValue()¶
Get the reduce value of the quantity that you wish to inspect (returns device pointer).
-
float *GetDeviceValues()¶
Get the values of the quantity that you wish to inspect (for non-reduced inspections, returns device pointer).
-
float GetValue()¶
Get the reduce value of the quantity that you wish to inspect.
-
float *GetValues()¶
Get the values of the quantity that you wish to inspect (for non-reduced inspections).
-
void Initialize(const std::unordered_map<std::string, std::string> &Subs, const std::vector<std::string> &options, bool force = false)¶
-
void ReleaseData()¶
Manually release the data arrays.
-
inline void SetInspectionCode(const std::string &code)¶
-
inline ~DEMInspector()¶
Friends
- friend class DEMDynamicThread
- friend class DEMSolver
-
inline DEMInspector(DEMSolver *sim_sys, DEMDynamicThread *dT_sys, const std::string &quantity, const std::string ®ion)¶
Materials and force models¶
-
class DEMMaterial¶
-
class DEMForceModel¶
Public Functions
-
void DefineCustomModel(const std::string &model)¶
Define user-custom force model with a string which is your force calculation code.
-
void DefineCustomModelPrerequisites(const std::string &util)¶
Define user-custom force model’s utility __device__ functions with a string.
-
inline DEMForceModel(FORCE_MODEL model_type = FORCE_MODEL::CUSTOM)¶
-
int ReadCustomModelFile(const std::filesystem::path &sourcefile)¶
Read user-custom force model from a file (which by default should reside in kernel/DEMUserScripts), which contains your force calculation code.
Returns 0 if read successfully, otherwise 1.
-
int ReadCustomModelPrerequisitesFile(const std::filesystem::path &sourcefile)¶
Read user-custom force model’s utility __device__ functions from a file (which by default should reside in kernel/DEMUserScripts).
Returns 0 if read successfully, otherwise 1.
-
void SetForceModelType(FORCE_MODEL model_type)¶
Set the contact force model type.
-
inline void SetMustHaveMatProp(const std::set<std::string> &props)¶
Specifiy the material properties that this force model will use.
- Parameters:
props – Material property names.
-
inline void SetMustPairwiseMatProp(const std::set<std::string> &props)¶
Specifiy the material properties that are pair-wise (instead of being associated with each individual material).
- Parameters:
props – Material property names.
-
void SetPerContactWildcards(const std::set<std::string> &wildcards)¶
Set the names for the extra quantities that will be associated with each contact pair.
For example, history-based models should have 3 float arrays to store contact history. Only float is supported. Note the initial value of all contact wildcard arrays is automatically 0.
-
void SetPerOwnerWildcards(const std::set<std::string> &wildcards)¶
Set the names for the extra quantities that will be associated with each owner.
For example, you can use this to associate a cohesion parameter to each particle. Only float is supported.
-
inline ~DEMForceModel()¶
Friends
- friend class DEMSolver
-
void DefineCustomModel(const std::string &model)¶
Geometry and initialization¶
-
class DEMInitializer¶
Subclassed by deme::DEMClumpBatch, deme::DEMExternObj, deme::DEMMesh, deme::DEMTrackedObj
Public Functions
-
virtual ~DEMInitializer() = default¶
-
virtual ~DEMInitializer() = default¶
-
class DEMClumpBatch : public deme::DEMInitializer¶
Public Functions
-
inline void AddExistingContactWildcard(const std::string &name, const std::vector<float> &vals)¶
-
inline void AddGeometryWildcard(const std::string &name, const std::vector<float> &vals)¶
-
inline void AddGeometryWildcard(const std::string &name, float val)¶
-
inline void AddOwnerWildcard(const std::string &name, const std::vector<float> &vals)¶
-
inline void AddOwnerWildcard(const std::string &name, float val)¶
-
inline DEMClumpBatch(size_t num)¶
-
inline size_t GetNumClumps() const¶
-
inline size_t GetNumContacts() const¶
-
inline size_t GetNumSpheres() const¶
-
inline void SetAngVel(const std::vector<float> &input)¶
-
inline void SetAngVel(const std::vector<float3> &input)¶
-
inline void SetAngVel(const std::vector<std::vector<float>> &input)¶
-
inline void SetAngVel(float3 input)¶
-
inline void SetExistingContacts(const std::vector<std::pair<bodyID_t, bodyID_t>> &pairs)¶
-
inline void SetExistingContactWildcards(const std::unordered_map<std::string, std::vector<float>> &wildcards)¶
-
inline void SetFamilies(const std::vector<unsigned int> &input)¶
Specify the “family” code for each clump.
Then you can specify if they should use some prescribed motion or some special physics (for example, being fixed). The default behavior (without specification) for every family uses “normal” physics.
-
inline void SetFamilies(unsigned int input)¶
-
inline void SetFamily(unsigned int input)¶
-
inline void SetGeometryWildcards(const std::unordered_map<std::string, std::vector<float>> &wildcards)¶
-
inline void SetOriQ(const std::vector<float> &input)¶
-
inline void SetOriQ(const std::vector<float4> &input)¶
-
inline void SetOriQ(const std::vector<std::vector<float>> &input)¶
-
inline void SetOriQ(float4 input)¶
-
inline void SetOwnerWildcards(const std::unordered_map<std::string, std::vector<float>> &wildcards)¶
-
inline void SetPos(const std::vector<float> &input)¶
-
inline void SetPos(const std::vector<float3> &input)¶
-
inline void SetPos(const std::vector<std::vector<float>> &input)¶
-
inline void SetPos(float3 input)¶
-
inline void SetVel(const std::vector<float> &input)¶
-
inline void SetVel(const std::vector<float3> &input)¶
-
inline void SetVel(const std::vector<std::vector<float>> &input)¶
-
inline void SetVel(float3 input)¶
-
inline ~DEMClumpBatch()¶
Public Members
-
std::vector<float3> angVel¶
-
std::vector<std::pair<bodyID_t, bodyID_t>> contact_pairs¶
-
std::unordered_map<std::string, std::vector<float>> contact_wildcards¶
-
std::vector<unsigned int> families¶
-
bool family_isSpecified = false¶
-
std::unordered_map<std::string, std::vector<float>> geo_wildcards¶
-
size_t nClumps = 0¶
-
size_t nSpheres = 0¶
-
std::vector<float4> oriQ¶
-
std::unordered_map<std::string, std::vector<float>> owner_wildcards¶
-
std::vector<std::shared_ptr<DEMClumpTemplate>> types¶
-
std::vector<float3> vel¶
-
std::vector<float3> xyz¶
-
inline void AddExistingContactWildcard(const std::string &name, const std::vector<float> &vals)¶
-
class DEMExternObj : public deme::DEMInitializer¶
API-(Host-)side struct that holds cached user-input external objects.
Public Functions
Add an analytical single-nappe cone side extending indefinitely from `tip` along `axis`.
Add a cone or frustum side clipped to hmin <= dot(point - tip, axis) <= hmax; caps are not included.
Add a cylinder of infinite length, which is along a user-specific axis.
Add a plane with infinite size.
Add a z-axis-aligned cylinder of infinite length.
-
inline DEMExternObj()¶
-
inline float GetMass() const¶
Get mass.
-
inline float3 GetMOI() const¶
Get MOI (in principal frame)
-
inline void SetFamily(const unsigned int code)¶
Define object contact family number.
-
inline void SetInitPos(const float3 displ)¶
Set the initial position for this object (before simulation initializes).
- Parameters:
displ – Initial position.
-
inline void SetInitPos(const std::vector<float> &displ)¶
-
inline void SetInitQuat(const float4 rotQ)¶
Set the initial quaternion for this object (before simulation initializes).
- Parameters:
rotQ – Initial quaternion.
-
inline void SetInitQuat(const std::vector<float> &rotQ)¶
-
inline void SetMass(float mass)¶
Set mass.
-
inline void SetMOI(const std::vector<float> &MOI)¶
-
inline void SetMOI(float3 MOI)¶
Set MOI (in principal frame)
-
inline ~DEMExternObj()¶
Public Members
-
std::vector<DEMAnalEntParams> entity_params¶
-
unsigned int family_code = RESERVED_FAMILY_NUM¶
Means it defaults to the “fixed” family.
-
float4 init_oriQ = make_float4(0, 0, 0, 1)¶
-
float3 init_pos = make_float3(0)¶
-
float mass = 1e6¶
-
std::vector<std::shared_ptr<DEMMaterial>> materials¶
-
float3 MOI = make_float3(1e6)¶
-
std::vector<OBJ_COMPONENT> types¶
-
union DEMAnalEntParams¶
-
class DEMMesh : public deme::DEMInitializer¶
Public Types
Public Functions
-
inline void AddGeometryWildcard(const std::string &name, const std::vector<float> &vals)¶
-
inline void AddGeometryWildcard(const std::string &name, float val)¶
-
inline bool ArePatchesExplicitlySet() const¶
Check if patch information has been explicitly set.
- Returns:
True if patches have been computed via SplitIntoConvexPatches() or set via SetPatchIDs(), false if using default (single patch).
-
inline bool ArePatchLocationsExplicitlySet() const¶
Check if patch locations have been explicitly set.
- Returns:
True if locations have been set via SetPatchLocations(), false if they will be auto-calculated.
-
inline void Clear()¶
Clear all data.
-
inline void ClearWildcards()¶
-
void ComputeMassProperties(double &volume, float3 ¢er, float3 &inertia) const¶
Compute volume, centroid and MOI in CoM frame (unit density).
For shells (`SetShellThickness`), uses a centered-thickening shell model: volume = surface area * thickness.
-
void ComputeMassProperties(double &volume, float3 ¢er, float3 &inertia, float3 &inertia_products) const¶
Compute volume, centroid and full inertia tensor in CoM frame (unit density).
`inertia_products` stores tensor terms (Ixy, Iyz, Izx).
-
std::vector<float3> ComputePatchLocations() const¶
Compute patch locations relative to the implicit CoM of the mesh.
For single patch: returns (0,0,0). For multiple patches: returns average of triangle centroids per patch.
- Returns:
Vector of locations (one per patch).
-
inline DEMMesh()¶
-
inline DEMMesh(std::string input_file)¶
-
inline void DisableShell()¶
Disable shell mode (fallback to zero-thickness triangle surface behavior).
-
inline std::vector<float3> &GetCoordsColors()¶
-
inline std::vector<float3> &GetCoordsNormals()¶
-
inline std::vector<float3> &GetCoordsUV()¶
-
inline std::vector<float3> &GetCoordsVertices()¶
Get the coordinates of the vertices of this mesh.
- Returns:
A reference to the vertices data vector (of float3) of the mesh.
-
std::vector<std::vector<float>> GetCoordsVerticesAsVectorOfVectors()¶
Get the coordinates of the vertices of this mesh.
- Returns:
N (number of vertices) by 3 matrix.
-
inline std::vector<int3> &GetIndicesColors()¶
-
inline std::vector<int3> &GetIndicesNormals()¶
-
inline std::vector<int3> &GetIndicesUV()¶
-
inline std::vector<int3> &GetIndicesVertexes()¶
Get the vertices number of all the triangles of this mesh.
- Returns:
A reference to the vertices number data vector (of int3) of the mesh.
-
std::vector<std::vector<int>> GetIndicesVertexesAsVectorOfVectors()¶
Get the vertices number of all the triangles of this mesh.
- Returns:
N (number of vertices) by 3 matrix.
-
inline float GetMass() const¶
Get mass.
-
inline float3 GetMOI() const¶
Get MOI (in principal frame).
-
inline size_t GetNumNodes() const¶
Get the number of nodes in the mesh.
-
inline unsigned int GetNumPatches() const¶
Get the number of patches in the mesh.
- Returns:
Number of patches. Default is 1 (assuming convex mesh).
-
inline size_t GetNumTriangles() const¶
Get the number of triangles already added to this mesh.
-
inline const std::vector<patchID_t> &GetPatchIDs() const¶
Get the patch ID for each triangle.
- Returns:
Vector of patch IDs (one per triangle). By default, all triangles are in patch 0 (assuming convex mesh).
-
inline const std::vector<float3> &GetPatchLocations() const¶
Get the relative location (to CoM) of each patch.
- Returns:
Vector of locations (one per patch). Will be automatically calculated at initialization if not explicitly set.
-
inline float GetShellHalfThickness() const¶
Get half shell thickness (used internally by kernels).
-
inline float GetShellThickness() const¶
Get full shell thickness.
-
inline DEMTriangle GetTriangle(size_t index) const¶
Access the n-th triangle in mesh.
-
inline void InformCentroidPrincipal(const std::vector<float> ¢er, const std::vector<float> &prin_Q)¶
-
inline void InformCentroidPrincipal(float3 center, float4 prin_Q)¶
If this mesh’s component triangles are not reported by the user in its centroid and principal system, then the user needs to call this method immediately to report this mesh’s volume centroid and principal axes, and nodes will be adjusted by this call so that the mesh’s frame is its centroid and principal system.
-
inline bool IsConvex() const¶
Query whether this mesh is marked convex.
-
inline bool IsNeverWinner() const¶
Query whether this mesh is marked as never-winner.
-
inline bool IsShell() const¶
Query whether this mesh is configured as a shell.
-
bool IsWatertight(size_t *boundary_edges = nullptr, size_t *nonmanifold_edges = nullptr) const¶
Check if mesh is watertight (closed, manifold). Returns true if no boundary/non-manifold edges.
-
bool LoadPLYMesh(std::string input_file, bool load_normals = true)¶
Load a triangle mesh saved as a PLY file (ASCII, triangulated or polygonal)
-
bool LoadSTLMesh(std::string input_file, bool load_normals = true)¶
Load a triangle mesh saved as an STL file (ASCII or binary)
-
bool LoadWavefrontMesh(std::string input_file, bool load_normals = true, bool load_uv = false)¶
Load a triangle mesh saved as a Wavefront .obj file.
-
inline void Mirror(const std::vector<float> &plane_point, const std::vector<float> &plane_normal)¶
-
inline void Mirror(float3 plane_point, float3 plane_normal)¶
Mirror all points in the mesh about a plane.
If this changes the mass properties of this mesh, it is the user’s responsibility to reset them.
-
inline void Move(const std::vector<float> &vec, const std::vector<float> &rot_Q)¶
-
inline void Move(float3 vec, float4 rot_Q)¶
The opposite of InformCentroidPrincipal, and it is another way to align this mesh’s coordinate system with its centroid and principal system: rotate then move this mesh, so that at the end of this operation, the mesh’s frame is its centroid and principal system.
-
inline void Scale(const std::vector<float> &s)¶
-
inline void Scale(float s)¶
Scale all geometry component of this mesh.
-
inline void Scale(float3 s)¶
Scale all geometry component of this mesh. Specify x, y, z respectively.
-
inline void SetConvex(bool convex = true)¶
Mark this mesh as convex for contact reduction purposes.
-
void SetEachTriangleAsPatch()¶
Assign every triangle to its own patch.
Patch IDs are assigned in triangle order as 0, 1, …, GetNumTriangles() - 1. This must be called after loading or constructing the mesh, and the triangle count must fit in the patchID_t representation.
-
inline void SetFamily(unsigned int num)¶
Set mesh family number.
-
inline void SetGeometryWildcards(const std::unordered_map<std::string, std::vector<float>> &wildcards)¶
-
inline void SetInitPos(const float3 displ)¶
Transform the meshed object so it gets to its initial position, before the simulation starts.
-
inline void SetInitPos(const std::vector<float> &displ)¶
-
inline void SetInitQuat(const float4 rotQ)¶
Give the meshed object an initial rotation, before the simulation starts.
-
inline void SetInitQuat(const std::vector<float> &rotQ)¶
-
inline void SetMass(float mass)¶
Set mass.
Set material types for the mesh. Using this method makes a uniform-materialed mesh.
Set material types for the mesh.
The input vector should have the same length as the number of patches in the mesh, and each element is the material for that patch.
This allows you to set different materials for different patches of the mesh, which can be useful if your mesh has multiple convex patches with different material properties.
-
inline void SetMOI(const std::vector<float> &MOI)¶
Set MOI (in principal frame).
-
inline void SetMOI(float3 MOI)¶
Set MOI (in principal frame).
-
inline void SetNeverWinner(bool never = true)¶
Prevent this mesh from ever being chosen as the winner side in island labeling.
-
void SetPatchIDs(const std::vector<patchID_t> &patch_ids)¶
Manually set the patch IDs for each triangle.
Allows user to manually specify which patch each triangle belongs to. This is useful when the user has pre-computed patch information or wants to define patches based on custom criteria.
- Parameters:
patch_ids – Vector of patch IDs, one for each triangle. Must have the same length as the number of triangles in the mesh. Patch IDs should be non-negative integers starting from 0.
-
inline void SetPatchLocations(const std::vector<float3> &patch_locations)¶
Set the relative location (to CoM) of each patch.
Allows user to manually specify the location of each patch relative to the mesh’s center of mass.
- Parameters:
patch_locations – Vector of locations (float3), one for each patch. Must have the same length as the number of patches in the mesh.
-
inline void SetShellThickness(float thickness)¶
Treat this mesh as a shell surface with finite thickness. Thickness must be finite and non-negative.
-
inline unsigned int SplitIntoConvexPatches(float hard_angle_deg, const PatchSplitOptions &opt)¶
-
inline unsigned int SplitIntoConvexPatches(float hard_angle_deg, const PatchSplitOptions &opt, PatchQualityReport *out_report)¶
-
unsigned int SplitIntoConvexPatches(float hard_angle_deg, const PatchSplitOptions &opt, PatchQualityReport *out_report, const PatchQualityOptions &qopt)¶
Split the mesh into connected patches based on face-normal and optional quality constraints.
The default overload preserves the original angle-threshold region-growing behavior. The extended overload can also fill a quality report and apply optional concavity/patch-normal checks.
-
inline unsigned int SplitIntoConvexPatches(float hard_angle_deg = 30.0f)¶
-
inline void UseNormals(bool use = true)¶
Instruct that when the mesh is initialized into the system, it will re-order the nodes of each triangle so that the normals derived from right-hand-rule are the same as the normals in the mesh file.
-
inline ~DEMMesh()¶
Public Members
-
unsigned int cache_offset = 0¶
-
unsigned int family_code = RESERVED_FAMILY_NUM¶
Means it defaults to the “fixed” family.
-
std::string filename¶
file string if loading an obj file
-
std::unordered_map<std::string, std::vector<float>> geo_wildcards¶
-
float4 init_oriQ = make_float4(0, 0, 0, 1)¶
-
float3 init_pos = make_float3(0)¶
-
bool is_convex = false¶
-
bool is_shell = false¶
-
bool isMaterialSet = false¶
-
std::vector<float3> m_colors¶
-
std::vector<int3> m_face_col_indices¶
-
std::vector<int3> m_face_n_indices¶
-
std::vector<int3> m_face_uv_indices¶
-
std::vector<int3> m_face_v_indices¶
-
std::vector<float3> m_normals¶
-
std::vector<patchID_t> m_patch_ids¶
-
std::vector<float3> m_patch_locations¶
-
std::vector<float3> m_UV¶
-
std::vector<float3> m_vertices¶
-
float mass = 1.f¶
-
bool mass_specified = false¶
-
std::vector<std::shared_ptr<DEMMaterial>> materials¶
-
size_t mesh_template_mark = NULL_MESH_TEMPLATE_MARK¶
-
float3 MOI = make_float3(1.f)¶
-
bool moi_specified = false¶
-
bool never_winner = false¶
-
unsigned int nPatches = 1¶
-
size_t nTri = 0¶
-
bodyID_t owner = NULL_BODYID¶
-
bool patch_locations_explicitly_set = false¶
-
bool patches_explicitly_set = false¶
-
float shell_thickness = 0.f¶
-
bool use_mesh_normals = false¶
Public Static Functions
-
struct PatchQualityOptions¶
-
struct PatchQualityPatch¶
Public Members
-
float coherence_r = 1.0f¶
-
unsigned int concave_crossings = 0¶
-
unsigned int hard_crossings = 0¶
-
PatchQualityLevel level = PatchQualityLevel::SAFE¶
-
unsigned int n_tris = 0¶
-
unsigned int unoriented_edges = 0¶
-
float worst_angle_deg = 0.0f¶
-
float coherence_r = 1.0f¶
-
struct PatchQualityReport¶
Public Members
-
unsigned int achieved_patches = 0¶
-
PatchConstraintStatus constraint_status = PatchConstraintStatus::SATISFIED¶
-
PatchQualityLevel overall = PatchQualityLevel::SAFE¶
-
std::vector<PatchQualityPatch> per_patch¶
-
unsigned int requested_max = std::numeric_limits<unsigned int>::max()¶
-
unsigned int requested_min = 1¶
-
unsigned int achieved_patches = 0¶
-
struct PatchSplitOptions¶
-
inline void AddGeometryWildcard(const std::string &name, const std::vector<float> &vals)¶
deme::DEMMeshConnected is a compatibility type alias for
deme::DEMMesh and therefore does not have a separate Doxygen class page.
Sampling¶
-
class PDSampler : public deme::Sampler¶
-
class GridSampler : public deme::Sampler¶