Troubleshooting
Common symptoms, probable causes and recommended actions for rapid resolution.
19.1 STL does not appear
Probable causes: file was not actually imported (silent I/O failure); scale too small or too large (geometry outside the viewport); camera positioned away from geometry; invalid file path after moving project; STL removed from the original folder between executions; material/transparency making viewing difficult.
Actions: use Camera Reset; open STL Information to check path and dimensions; check the scale and bounding box; check the list of active STLs; save and reopen the project.
19.2 Particles do not appear
Probable causes: simulation has not yet generated .bin; incorrect result folder; snapshots not loaded; displayed snapshot is old or sparsely populated; inlet was not added to list (configured but not included); simulation ended without particles (N=0). Action: check the path of the result folder, reload snapshots, navigate to a dense snapshot and confirm that the inlet appears in Configured Items.
19.3 Inlet does not inject
Check: initial and final inlet time; mass or particle flow rates; injection speed (cannot be zero); direction of normal (most common cause of an inactive inlet); material assigned to the inlet; position within the computational domain; if inlet was added to the list; possible initial collision with geometry.
19.4 Outlet does not remove
Check: direction of normal; plane geometry/removal region; if the particles actually cross the region; any offset along the normal; active outlet time interval.
19.5 Geometry with incorrect movement
Check: type of motion selected; speed vector; rotation centre (in the case of rotational motion); angular velocity unit (rad/s, not °/s); acceleration ramp; displayed axis and preview of the motion over time.
19.6 Unstable simulation
Symptoms: particles "explode" out of the domain; kinetic energy grows without limit; high overlap δₙ (above ~1–2% of the radius); unrealistic speeds; solver or GPU generate overflow error.
Recommended action (in order): (1) halve Δt and test again; (2) check for particles born within geometry (initial overlap); (3) reduce the initial velocity of particles in the inlet; (4) check the quality of the STL mesh; (5) review stiffness and calibration before reducing E.
Instability after fragmentation
The smallest fragment may require a smaller step than fed particles. Check the GUI suggestion; follow 12.6 to choose and apply the step. Do not treat d_min as a guaranteed minimum birth size. Before reducing Young’s modulus, retain consistency with DWT calibration and walls (10.7).
Missing capillary interaction or unexpected inventory
Check that pair cohesion is set to Liquid bridge: positive content alone does not activate it. Review global properties, angle, bridge limit, surface inventory and recorded fields. Chapter 16 explains volume interpretation. See 28.7 for clump and breakage combinations.
19.7 Quick Table of Symptoms and Actions
| SYMPTOMS | FIRST ACTION |
|---|---|
| Particles cross wall | Reduce Δt; increase the STL mesh density |
| Energy grows without cause | Reduce Δt; review initial overlaps |
| Case runs too slowly | Enable Verlet search; use more threads; consider GPU execution for a large case |
| Heap does not stabilise | Increase μ, μ r; check damping (cn) |
| Hopper always clogs | Reduce μ or cohesion; review geometry angle |
| Drum does not cascade | Increase rotation; check particle-wall friction |
| CPU/GPU results differ | Run a simple validation case; compare trends, not absolute values |
19.8 Strategies for numerical divergence
When the simulation diverges - kinetic energy grows without limit, particles escape the domain, overlap δₙ above ~1–2 % of radius, unrealistic speeds or NaN/overflow on console - attack the problem on three fronts, in this order: timestep, then materials and interactions, then mesh. Change one factor at a time and rerun a short interval to isolate the cause.
First action — timestep
The divergence almost always begins with a Δt that is too large. Halve Δt and observe: if the energy stops growing, the step was the cause. In automatic mode, reduce the Rayleigh factor (α R) from 0.30 to 0.15–0.20; with cohesion or very rigid contacts, go to 0.05–0.10. Perform a convergence study: divide Δt successively until the quantity of interest (flow rate, angle, force) stops changing.
Material adjustment
| SYMPTOMS | MATERIAL ADJUSTMENT | WHY |
|---|---|---|
| Stiff contacts require a very small Δt | Reduce Young’s modulus E (e.g. from 10⁹ to 10⁷–10⁸ Pa) | Softens contact and lengthens collision time; verify overlap and calibrated response, especially for DWT/breakage |
| Heap "explodes" on contact | Reduce eₙ (more dissipation) and check density ρ | A high eₙ retains impact energy; a lower eₙ increases damping |
| Particles vibrate or shake at rest | Increase damping (lower eₙ) or review minimum radius | High stiffness + Δt at the limit generates numerical resonance |
| Heap slides too much | Increase μ and enable μ_r (rolling) | Reproduces interlocking of angular grains |
Interaction adjustment
The interaction is the pair material × material — calibrate the pair, not just the isolated materials. For divergence:
- Pair restitution eₙ - if the particle-wall pair returns too much energy (particles bouncing non-stop), reduce eₙ of that interaction;
- Friction μ - very low friction lets the material flow as liquid and never stabilize; start at μ ≈ 0.3–0.5 and calibrate using the angle of repose;
- Rolling resistance μ_r - spheres without rolling resistance form unstable heaps; activate the CDT model with μ r > 0;
- Cohesion - cohesion requires a smaller Δt; if cohesion has been activated and the case has diverged, reduce Δt before anything else and confirm that k (or γ) is not orders of magnitude above a physically appropriate value;
- Pair overrides - check that a manual override (kₙ, cₙ) has not introduced a stiffness incompatible with Δt.
Mesh adjustment (STL)
Poorly prepared STL geometry is a frequent cause of particle leakage and contact instability:
- Triangles too large - if a triangle is much larger than the particles, the contact can "slip" over the edges; remesh so each triangle is comparable in size to a few particle diameters;
- Tiny Triangles / Slivers - thin and degenerate triangles generate bad normals and erratic force; clean the mesh before importing;
- Inverted normals - normals pointing to the wrong side causes the particle to be pushed into the wall; check the orientation of the faces;
- Holes / non-watertight mesh - holes in the mesh allow particles to escape; use closed geometry (watertight) for contours;
- Initial overlap - particles born within the mesh receive enormous force in the first step; move the inlet away from the wall or reduce the injection speed.
