DPM Troubleshooting -- Common Errors, Convergence Failures, and Diagnostic Procedures

#+CATEGORY: cfd

#+TAGS: DPM troubleshooting convergence errors diagnosis particle-lost incomplete stuck

#+MATURITY: growing

DPM Troubleshooting :: Common Errors, Convergence, and Diagnostics

This page collects the most frequently encountered DPM problems, their symptoms, root causes, and fixes. Organized by category: particle tracking failures, convergence issues, visualization problems, and UDF compilation errors.

Particle Tracking Failures

"Particle stuck" or "Particle path aborted"

Symptom: DPM Summary shows a large number of "incomplete" or "aborted" particles.

Root causes and fixes:

Cause	Diagnostic	Fix
-------	------------	-----
`Max Steps` too low	Check DPM Summary: "incomplete" count is high	Increase Max Steps from 500 to 5000+
Particle timestep too large	Particles skip cells; Fluent reports "particle lost"	Reduce Lagrangian time step factor (0.1--0.5 of cell transit time)
Reversed flow at pressure outlet	Particles re-enter domain through outlet	Enable "Prevent Reversed Flow" or add a buffer zone
Very low velocity in region	Particles stall and never leave a cell	Add small seeding velocity or check continuous-phase convergence
Singular mesh (zero-volume cell)	Particle velocity calculation fails	Fix mesh quality (check `orthogonal quality > 0.1`)
Injection inside solid region	All particles immediately abort	Check injection coordinates against domain geometry

Fix: Increase max steps via TUI

  solve/set/dpm-iterations 10000
  define/models/discrete-phase/max-steps 5000

"Particle lost" error

Symptom: Fluent prints Warning: particle path lost for injection-X, particle Y and terminates DPM.

Root causes: 1. Large cell-size jump (particle moved from a small cell to a very large cell) 2. Negative cell volume in mesh 3. Particle velocity is NaN (usually from a UDF bug)

Fixes:

= define/models/discrete-phase/numerics/track-time-scale =: reduce from 0.1 to 0.01
Check mesh: = mesh/check-quality =
If using a UDF, add guards: if (!isfinite(force)) return 0.0;

Convergence Issues

DPM source terms oscillate

Symptom: After enabling two-way coupling, residuals of the continuous phase do not decrease; they oscillate or diverge.

Root causes and fixes:

Cause	Fix
-------	-----
Source term too large for under-relaxation	Reduce DPM under-relaxation factor from 1.0 to 0.5 or 0.3
Insufficient DPM iterations per coupling loop	Increase DPM iterations per coupling step
Coupling frequency too aggressive	Couple every 20 iterations instead of every 1
Mass loading ratio > 1	Consider using coupled (strong) coupling iteration

TUI commands for under-relaxation

  solve/set/dpm-under-relaxation 0.5
  solve/set/dpm-iterations 500
  solve/set/discrete-phase/coupling-interval 20

Continuous phase diverges after DPM coupling

Symptom: Continuous phase converges well without DPM; after enabling coupling, residuals spike.

Fixes (in order): 1. Reduce DPM under-relaxation to 0.3 2. Check that DPM mass source is small relative to throughflow 3. Ensure continuous phase is well-converged BEFORE starting DPM coupling 4. Start with one-way coupling, confirm DPM converges, then enable two-way coupling gradually

Number of DPM iterations needed

Scenario	Recommended iterations
----------	----------------------
One-way, simple trajectories	100--500
One-way, stochastic tracking (DRW)	500--2000
Two-way, dilute	500--2000 per coupling step
Two-way, moderate loading	1000--5000 per coupling step
Coupled (strong) iteration	5--10 strong iterations

Visualization Problems

Particle tracks all go in a straight line

Cause: DRW not enabled; particles follow deterministic mean flow only.

Fix: Models > Discrete Phase > Physical Models > Enable Stochastic Tracking with Number of Tries = 10--20.

DPM Concentration contour is zero everywhere

Possible causes:

Check	Command	What to look for
-------	---------	-------------------
DPM Summary	Report > DPM Summary	Are particles reaching the domain?
Injection active	Graphics > Particle Tracks	Do tracks exist?
Cell volume	Report > Cell Volume	Are cells near-zero?
Concentration scaling	Contours > DPM Concentration > Options	Auto-range might miss small values; set manual range

Concentration seems unrealistic (too high or too low)

Diagnostic: Compute expected concentration analytically.

For a surface injection of mass flow rate \dot{m}_p into a cross-section A with velocity U:

If the simulation gives c that differs by more than a factor of 2, check: 1. Injection flow rate units (kg/s vs. kg/m^2/s) 2. Particle density (wrong density = wrong parcel mass = wrong concentration) 3. Number of parcels (too few = statistical noise)

DPM Summary Diagnostic Table

After running DPM (Report > Discrete Phase > Summary), check:

Status	What it means	Action needed?
--------	--------------	----------------
Escaped at outlet	Correct for exhaust particles	No
Trapped at walls	Particle deposited on surface	No (unless you expected reflection)
Incomplete	Exceeded max steps	Yes: increase steps or check mesh
Evaporated	Droplet fully evaporated	No (for droplet type)
Aborted	Force or position singular	Yes: check UDF, mesh, injection

Typical healthy DPM Summary:

If "Incomplete" exceeds 1--2%, track down the cause before trusting results.

UDF Compilation Errors

Error	Cause	Fix
-------	-------	-----
`error C2065: 'P_DIAM' undeclared`	Missing `#include "dpm.h"`	Add both `udf.h` and `dpm.h`
`error C2143: syntax error missing ';'`	Typo or missing statement terminator	Check line above error
`LNK2019: unresolved external`	Function name mismatch	`DEFINE_DPM_BODY_FORCE(name, ...)`: check `name` matches hook
`warning C4715: not all paths return value`	Conditional without `return`	Ensure every branch returns a `real` value
Runtime crash: `SIGSEGV` at `C_T(c,t)`	Particle not in valid cell	Add guard: `if (NULLP(t)) return 0.0;`
UDF loads but has no effect	Hook not connected to injection	Models > DPM > Interaction: select UDF for each relevant field

Performance Issues

DPM run is extremely slow

Cause	Fix
-------	-----
Too many parcels	Reduce parcel count; use more parcels-per-injection but fewer injections
DRW with 100 tries	Reduce tries to 10--20; use residual convergence to find minimum
Max Steps = 50000 (over-cautious)	Set to 5000; only increase if "incomplete" count is high
Small cells in mesh	Use mesh adaptation or `min cell length > 0.1 * particle diameter`
Single-processor run	Enable parallel DPM (distributed memory)

Memory overflow during DPM

Symptom	Fix
---------	-----
Segmentation fault after many DPM iterations	Increase RAM or reduce parcel count
"Memory allocation failed"	Reduce number of DPM iterations per coupling loop
Swap thrashing	Close other applications; reduce mesh size

Common Mistakes Checklist

Before trusting DPM results, verify:

[ ] Continuous phase is fully converged (residuals dropped 3+ orders)
[ ] DPM Summary: "Incomplete" < 1% of total parcels
[ ] Injection mass flow rate matches physical source term (check units)
[ ] Drag law is appropriate for Re_p range
[ ] DRW enabled if dispersion matters (Number of Tries >= 10)
[ ] Boundary conditions: correct BC for each zone (trap/escape/reflect)
[ ] For two-way coupling: DPM under-relaxation < 1.0
[ ] For UDFs: force magnitude is physically reasonable (compare to gravity)
[ ] Mesh quality: minimum orthogonality > 0.1, no warped cells near injection
[ ] Particle max steps sufficient (increase if any "incomplete" flagged)