Demulate · User manual

Generated file, do not edit by hand. The reference half is derived from dem/template.py, dem/cards.py and dem/capability.py; rerun python tools/gen_manual.py. tests/test_manual.py compares byte for byte, so editing either side without the other turns red.

This manual covers two questions: what this program can do, and what the number on the screen means. It starts where the window is already open.

Installing it, the launcher, "double-click does nothing", where the result files go → START-HERE.md. That document ends where this one begins.


1 · The loop

Every case in this program is the same five steps. There is no sixth.

# Step Where What changes
1Pick a templateLaunch pageWhich physics the case will have. This decides everything downstream — it is not a skin
2Set parametersRight-hand panelThe scene, the estimate and the command stream all follow the same numbers
3RunToolbar RunValidation first; a bad parameter is refused in a second, not after forty minutes
4Read the resultResult pageCurves, cards, and the frame timeline. Every number carries where it came from
5Keep itFile › SaveOne .demcase file with the parameters you set

The panel is the whole interface: the template decides what is on it, and nothing on it is hard-coded. Add a parameter to a template and it appears — there is no second place to edit.

1.1 Two levels of parameters

Each template has ~20 parameters, which is too many to lay out flat and too few to hide. The panel splits them:

Everything in section 3 below is the basic set. Nothing is missing from the program: the advanced group is one click away, and its default is the value the template was calibrated with.

1.2 What you can trust on screen

Shown Means
A number with ~An estimate from a measured price per step, not a measurement. Order of magnitude — 2× either way
A number without ~Measured, from a result file that exists
Not computable on a cardThe card stays and says what is missing. It never disappears — a vanished card reads as "this template never had that quantity"

2 · The five templates at a glance

Template The question it answers Default scale What you get
pile-angle · Pile angleParticles fall from a slump cylinder and form a cone; the angle of repose is measured. The most common calibration case~2,119 particles · ~9 minAngle of repose, Pile outline, Time history
direct-shear · Direct shearThe lower half of the split box is fixed and the upper half shears along x; outputs a shear stress–displacement curve~1,420 particles · ~57 minShear stress–displacement curve, Peak shear stress, Normal stress history, τ/σn
triaxial · TriaxialCylindrical specimen under constant confining stress with axial loading; outputs deviator stress–axial strain → c, φ, dilatancy angle~1,874 particles · ~3.5 hDeviator stress–axial strain, Peak deviator stress, Lateral stress history, Volumetric strain (porosity history)
box-lift · Box liftThe box is lifted out of a pile of material; outputs a lift force curve. The standard case of the EDEM Calibration Kit~2,752 particles · ~20 minLift force curve, Peak lift force, Lift force / specimen self-weight
slope · SlopeThe slope body fails and slides under gravity; outputs a displacement field and the runout extent. MatDEM's flagship scenario~383 particles · ~53 sDisplacement field, Velocity field, Runout extent, Runout

The default scale is the one the template was calibrated at. It is not the only size that works — it is the size whose numbers have been checked.


3 · The templates in detail

Each chapter lists the parameters in the basic group, the presets, and the cards you will see afterwards. Read the What it does column once: these are the sentences that were learned by running the case, not by reading the code.

3.1 pile-angle · Pile angle

Particles fall from a slump cylinder and form a cone; the angle of repose is measured. The most common calibration case

Slump-cylinder method. Inner diameter = drum height / 2 (H/D is always 2.0, the test standard; the inner diameter is not a separate parameter)

What you get

- Angle of repose - Pile outline - Time history

The parameters you will actually turn

Panel label Default What it does
Mean particle diameter5.0 mmMedian particle diameter. Halve it and the particle count grows 8×, the time step halves
Contact modelhertz-mindlinbonded adds contact adhesion (contact.cohesion) on top of friction; broken bonds stay broken. kn-ks takes the pair stiffness directly (contact.kn/contact.ks, N/m) instead of deriving it from young/poisson. viscoelastic adds contact damping (contact.cn/contact.cs, N·s/m). cpm bonds every initial contact and damages them (strength = E·epsCrackOnset; softening over epsCrackOnset·relDuctility). capillary pulls grains together with liquid bridges (bridge_volume / surface_tension / contact_angle) — the wet-sand apparent cohesion. jointed-rock bonds the forming contacts and breaks them at a Mohr–Coulomb envelope (measured break at min(tensile_strength, bond_cohesion/tanφ); broken bonds never re-bond). The self-built local kernel runs kn-ks natively but refuses bonded, viscoelastic, cpm, capillary and jointed-rock (use YADE/WSL for those)
Inter-particle friction coefficient0.5The main control on the macroscopic internal friction angle. Measured on S3: 0.3→15.7°, 0.5→23.5°, 0.7→29.2°
Particle-wall friction coefficient0.4Affects sliding at the bottom. The pile angle is very sensitive to it
Bridge volume0.0 m³capillary model only: liquid volume of each bridge (m³). Created at first touch, pulls only while the pair is separated, ruptures at a gap ∝ volume^(1/3). Match it to the grain size — for mm grains use 1e-12 … 1e-10; a µm-scale value on mm grains gives nonsense forces. 0 = unused
Bond tensile strength0.0 kPajointed-rock model only: the tension cutoff of the bond break envelope — the bond breaks at min(tensile_strength, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa. 0 = unused
Bond cohesion0.0 kPajointed-rock model only: the shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly (measured), so both values must be > 0. 0 = unused
Boundaryrigid-wallperiodic = wall-free unit cell: fill + compaction inside the cell, no gravity (a periodic cell has no floor), loading drives the cell itself. Requires the cell size below, forbids walls and gravity (validate V032/V033)
Fibresoffon = mix count flexible fibres into the specimen: chains of grain-scale nodes joined by wire links (tension only, break at break_strain). Grain–fibre contacts stay frictional (measured: the fibre material derives from the grains'). Requires the hertz-mindlin / bonded / jointed-rock grain model and the rigid-wall boundary (V037)
Fibre count20Number of fibre chains, distributed evenly across the rain layers. Each chain also displaces grain volume — the particle count estimate includes its nodes
Fibre length24.0 mmChain length. Must span at least one node spacing (1.05·2·node_radius) — shorter carries no link (V037)
Node radius2.0 mmChain-node sphere radius. Keep it at grain scale (≈ half the mean grain diameter): measured, small light nodes are battered by the deposition flow until their links break
Wire strength500000.0 kPaPlateau stress of the link curve (steel ≈ 0.25–2 GPa, PP ≈ 0.3–0.5 GPa). The link yields here (plastic flow) and breaks at Break strain
Link stiffness200000.0 N/mElastic slope of a link in N/m. The solver has no direct stiffness knob — measured kn = strength·A/(yield·spacing) — so the yield strain is derived from this and must land strictly inside the breaking strain (V037)
Break strain1.0Link breaking strain (relative to node spacing). Measured: mm-scale jostling during deposition strains every link — 0.05 broke them all before loading, ≥ 1.0 kept the chains intact through three rain layers (polypropylene fibres: 20–150 %)
Drum height120.0 mmInner diameter = drum height / 2 (slump-cylinder test standard H/D = 2.0; the inner diameter is not a separate parameter). Below H/D 1.5 the specimen collapses into a pancake and what is measured is the slope of the pancake, not the friction angle (hit in the first version of S2)
Preparation methoddepositHow many lifts the specimen is poured in. cloud does not place the cloud in one go — a cloud at cloud_e=0.70 is 1.7-2x the final volume and cannot fit in a closed drum, so the engine's fallback applies and it pours 3 thick lifts instead of 10. That is a real change: on the default drum preparation is 25,096 steps against 83,655 (measured 2026-11-05), and the angle of repose differs by 0.19 deg (measured on S2). What it is not is a different preparation mechanism — both are gravity deposition. Want a genuinely different method? That is radius-expansion / under-compaction, which S2 measured to fail physically in a rigid drum, which is why the template does not offer them
Target porosity0.520.52 = the value pluviation actually reaches in a D=60 mm drum (measured 0.524 on 2026-10-27). The old default 0.42 is the textbook value for 'medium-dense sand', but pluviation cannot reach it — at 0.42 the engine requests 2806 particles while the drum only holds 2117 (porosity 0.524), so 'estimated 2806 / actual 2117' is 25% off, and the extra space does not exist. Going denser needs compaction (vibration / layered rolling), not turning this number down. The lower the porosity, the higher the angle of repose
Lift the drum after preparationonThe drum lift of the slump-cylinder test. Turning it off means it is no longer an angle-of-repose test: the particles stay enclosed in the drum, the final-frame slope angle is the drum wall's inclination, and the angle_of_repose card refuses to output a number outright (it does not give a wrong number). Only turn it off for a control experiment that deliberately does not collapse
Physical duration0.5 sTime for gravity deposition to come to rest. A 5 mm particle falling 120 mm takes about 0.16 s; 1 s is enough to stabilise

Presets

Preset What it changes
Standard sand (default)(the defaults)
Coarse sandMean particle diameter → 8.0 mm, Inter-particle friction coefficient → 0.6, Particle-wall friction coefficient → 0.5
Glass beads (low friction)Inter-particle friction coefficient → 0.25, Particle-wall friction coefficient → 0.2

Analysis cards on the result page

Card Unit How it is computed
Angle of repose°Final-frame particles are binned by height, the radial 95th percentile is taken per bin, a linear fit is made against (r, z), and only the 15%–85% height band is used
Pile geometrymm heightFinal-frame bounding box and maximum radial radius. Too large an H/R means the pile has not spread yet

Inverse solve — give a target Angle of repose (°) between 15.66 and 32.71, and the program inverts contact.mu_pp to produce it.

This is a curve inversion, not an analytical solution. Calibrated interval μ≥0.3; there is currently no rolling friction, so the absolute angle is about 10° lower than real sand and the inverted μ comes out high. The curve was measured at damping=0.2, μ_pw=μ_pp — the template defaults are already aligned; change either of these two and the curve no longer applies (measured: damping 0.4 raises the angle by about 6° at the same μ)

Three rules, and they are not negotiable: no extrapolation (a target outside the measured interval returns nothing, because there is no data behind it); it is not an analytical solution (curve inversion, with the systematic bias stated above); low quality points stay out of the curve (a point whose R² was 0.50 is dropped rather than dragged in to make the line look straighter).

At default scale — ~2,119 particles · 114,684 steps · ~9 min (medium). The particle count is the one that decides the wait: halving the diameter multiplies it by eight.

3.2 direct-shear · Direct shear

The lower half of the split box is fixed and the upper half shears along x; outputs a shear stress–displacement curve

Constant normal stress: the top plate belongs to the upper group; the main actuator carries it along x to follow the shear and the servo holds it along z at constant stress — one wall group, two controllers, each writing one velocity component (allowed only when the directions do not overlap). Set the normal stress to 0 and it falls back to no external load: then σ_n is only self-weight (≈0.3 kPa), and you can see the peak and the residual but cannot invert c and φ. Inverting c and φ needs at least two normal stress levels, one run each. Loading is displacement control (a stroke is given, not a strain): the nominal shear strain uses the box height (γ₀ = shear displacement / box height), and the γ read by the analysis card uses the first-frame particle outline as the denominator (with headroom the specimen is a few % shorter than the box, so the two differ slightly; the card states which one it used). The upper and lower boxes butt coplanarly at z = H/2, allowing a small number of particles to squeeze out through the seam

What you get

- Shear stress–displacement curve - Peak shear stress - Normal stress history - τ/σn

The parameters you will actually turn

Panel label Default What it does
Mean particle diameter5.0 mmMedian particle diameter. Halve it and the particle count grows 8×, the time step halves
Contact modelhertz-mindlinbonded adds contact adhesion (contact.cohesion) on top of friction; broken bonds stay broken. kn-ks takes the pair stiffness directly (contact.kn/contact.ks, N/m) instead of deriving it from young/poisson. viscoelastic adds contact damping (contact.cn/contact.cs, N·s/m). cpm bonds every initial contact and damages them (strength = E·epsCrackOnset; softening over epsCrackOnset·relDuctility). capillary pulls grains together with liquid bridges (bridge_volume / surface_tension / contact_angle) — the wet-sand apparent cohesion. jointed-rock bonds the forming contacts and breaks them at a Mohr–Coulomb envelope (measured break at min(tensile_strength, bond_cohesion/tanφ); broken bonds never re-bond). The self-built local kernel runs kn-ks natively but refuses bonded, viscoelastic, cpm, capillary and jointed-rock (use YADE/WSL for those)
Inter-particle friction coefficient0.5The main control on the macroscopic internal friction angle. Measured on S3: 0.3→15.7°, 0.5→23.5°, 0.7→29.2°
Particle-wall friction coefficient0.4Affects sliding at the bottom. The pile angle is very sensitive to it
Bridge volume0.0 m³capillary model only: liquid volume of each bridge (m³). Created at first touch, pulls only while the pair is separated, ruptures at a gap ∝ volume^(1/3). Match it to the grain size — for mm grains use 1e-12 … 1e-10; a µm-scale value on mm grains gives nonsense forces. 0 = unused
Bond tensile strength0.0 kPajointed-rock model only: the tension cutoff of the bond break envelope — the bond breaks at min(tensile_strength, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa. 0 = unused
Bond cohesion0.0 kPajointed-rock model only: the shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly (measured), so both values must be > 0. 0 = unused
Boundaryrigid-wallperiodic = wall-free unit cell: fill + compaction inside the cell, no gravity (a periodic cell has no floor), loading drives the cell itself. Requires the cell size below, forbids walls and gravity (validate V032/V033)
Fibresoffon = mix count flexible fibres into the specimen: chains of grain-scale nodes joined by wire links (tension only, break at break_strain). Grain–fibre contacts stay frictional (measured: the fibre material derives from the grains'). Requires the hertz-mindlin / bonded / jointed-rock grain model and the rigid-wall boundary (V037)
Fibre count20Number of fibre chains, distributed evenly across the rain layers. Each chain also displaces grain volume — the particle count estimate includes its nodes
Fibre length24.0 mmChain length. Must span at least one node spacing (1.05·2·node_radius) — shorter carries no link (V037)
Node radius2.0 mmChain-node sphere radius. Keep it at grain scale (≈ half the mean grain diameter): measured, small light nodes are battered by the deposition flow until their links break
Wire strength500000.0 kPaPlateau stress of the link curve (steel ≈ 0.25–2 GPa, PP ≈ 0.3–0.5 GPa). The link yields here (plastic flow) and breaks at Break strain
Link stiffness200000.0 N/mElastic slope of a link in N/m. The solver has no direct stiffness knob — measured kn = strength·A/(yield·spacing) — so the yield strain is derived from this and must land strictly inside the breaking strain (V037)
Break strain1.0Link breaking strain (relative to node spacing). Measured: mm-scale jostling during deposition strains every link — 0.05 broke them all before loading, ≥ 1.0 kept the chains intact through three rain layers (polypropylene fibres: 20–150 %)
Box length80.0 mm—
Box width80.0 mm—
Box height50.0 mm—
Target porosity0.5A real knob since Q55: at the end of preparation the top plate presses down and stops at the target. Pluviation in a square box only reaches 0.52, so 0.50 needs only 2 mm of compression. The lower the setting the more expensive the compaction (the estimate bar moves up a tier), and the price is over-consolidation — the compaction stress exceeds the normal stress, the consolidation phase is unloading and the specimen rebounds
Shear velocity0.0025 m/sConstant velocity of the upper box along +x. Too fast introduces inertial effects (2.5 mm/s on a 50 mm specimen is quasi-static)
Shear displacement0.003 mTotal stroke of the upper box along +x. The nominal shear strain uses the box height (3 mm ÷ 50 mm = 0.06; the dense-sand peak is at 0.02–0.04, and softening is already visible past the peak); the analysis card uses the measured specimen height, which comes out slightly larger (a few %) when there is headroom
Normal stress20.0 kPaConstant vertical stress on the top plate (servo). 0 = no normal load, in which case σ_n is only self-weight (≈0.3 kPa) and c and φ cannot be inverted
Normal pre-load time1.4 sDuration before shearing during which only the normal stress is applied and nothing moves. Included in the physical duration. Give it enough: after the platen seats the specimen rebounds first (measured consolidation start 51 kPa, target 20), and unloading of a granular assembly is hysteretic — 0.4 s only recovers half, the rest has to be made up by the shear phase, so the peak appears while σ_n has not settled yet
Physical duration2.8 sMust be ≥ pre-load time + shear displacement / shear velocity, otherwise the loading does not finish

Presets

Preset What it changes
Standard sand (20 kPa)(the defaults)
Low normal stress (5 kPa)Normal stress → 5.0 kPa
Low velocityShear velocity → 0.0005 m/s

Analysis cards on the result page

Card Unit How it is computed
Shear stress–displacementkPa peakTangential resultant force of the upper box (wall group) / shear area (Lx·Ly). The horizontal axis is the actual stroke of the upper box

Inverse solve — not available for this template. You set the parameters and read the result forward. (An inverse curve is declared only where a spike measured one: single variable, monotonic, R² > 0.9. Currently that is pile-angle only.)

At default scale — ~1,420 particles · 434,350 steps · ~57 min (heavy). The particle count is the one that decides the wait: halving the diameter multiplies it by eight.

3.3 triaxial · Triaxial

Cylindrical specimen under constant confining stress with axial loading; outputs deviator stress–axial strain → c, φ, dilatancy angle

The lateral direction has the servo on by default (confining stress 50 kPa): 48 side-wall segments each close along their outward normal, holding σ_lat at the target value — the standard practice of a constant-confining-stress triaxial test. Boundary friction is set to 0 for a rubber membrane / lubricated end (mu_pw=0): the side-wall area is 4H/D ≈ 8× the cross-section area, and keeping μ_pw=0.4 would inject into q a fake strength proportional to the confining stress. Isotropic consolidation first, then shear: the first 1.5 s only adds confining stress (radial + axial servos pressing to σ₃ at the same time, the main actuator still), otherwise the steep start of the q-ε curve is the confining stress still climbing, not the material response; the window of that axial servo runs until Consolidation time, after which it hands over to the displacement-controlled main actuator. Set the confining stress to 0 and it falls back to the rigid drum (constant volume); then σ_lat varies with dilatancy and the deviator stress is still computed. Inverting c and φ needs at least two confining stress levels, one run each (Mohr circles); a single run gives only one point

What you get

- Deviator stress–axial strain - Peak deviator stress - Lateral stress history - Volumetric strain (porosity history)

The parameters you will actually turn

Panel label Default What it does
Mean particle diameter5.0 mmMedian particle diameter. Halve it and the particle count grows 8×, the time step halves
Contact modelhertz-mindlinbonded adds contact adhesion (contact.cohesion) on top of friction; broken bonds stay broken. kn-ks takes the pair stiffness directly (contact.kn/contact.ks, N/m) instead of deriving it from young/poisson. viscoelastic adds contact damping (contact.cn/contact.cs, N·s/m). cpm bonds every initial contact and damages them (strength = E·epsCrackOnset; softening over epsCrackOnset·relDuctility). capillary pulls grains together with liquid bridges (bridge_volume / surface_tension / contact_angle) — the wet-sand apparent cohesion. jointed-rock bonds the forming contacts and breaks them at a Mohr–Coulomb envelope (measured break at min(tensile_strength, bond_cohesion/tanφ); broken bonds never re-bond). The self-built local kernel runs kn-ks natively but refuses bonded, viscoelastic, cpm, capillary and jointed-rock (use YADE/WSL for those)
Inter-particle friction coefficient0.5The main control on the macroscopic internal friction angle. Measured on S3: 0.3→15.7°, 0.5→23.5°, 0.7→29.2°
Particle-wall friction coefficient0.0Triaxial default 0: the side wall is a rubber membrane and the top platen is a lubricated end. The side-wall area is 4H/D ≈ 8× the cross-section area; μ_pw=0.4 would inject into q a fake strength proportional to the confining stress (measured magnitude 160 kPa). Only change it back when switching to a real rigid drum and wanting to reproduce drum-wall friction
Bridge volume0.0 m³capillary model only: liquid volume of each bridge (m³). Created at first touch, pulls only while the pair is separated, ruptures at a gap ∝ volume^(1/3). Match it to the grain size — for mm grains use 1e-12 … 1e-10; a µm-scale value on mm grains gives nonsense forces. 0 = unused
Bond tensile strength0.0 kPajointed-rock model only: the tension cutoff of the bond break envelope — the bond breaks at min(tensile_strength, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa. 0 = unused
Bond cohesion0.0 kPajointed-rock model only: the shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly (measured), so both values must be > 0. 0 = unused
Boundaryrigid-wallperiodic = wall-free unit cell: fill + compaction inside the cell, no gravity (a periodic cell has no floor), loading drives the cell itself. Requires the cell size below, forbids walls and gravity (validate V032/V033)
Fibresoffon = mix count flexible fibres into the specimen: chains of grain-scale nodes joined by wire links (tension only, break at break_strain). Grain–fibre contacts stay frictional (measured: the fibre material derives from the grains'). Requires the hertz-mindlin / bonded / jointed-rock grain model and the rigid-wall boundary (V037)
Fibre count20Number of fibre chains, distributed evenly across the rain layers. Each chain also displaces grain volume — the particle count estimate includes its nodes
Fibre length24.0 mmChain length. Must span at least one node spacing (1.05·2·node_radius) — shorter carries no link (V037)
Node radius2.0 mmChain-node sphere radius. Keep it at grain scale (≈ half the mean grain diameter): measured, small light nodes are battered by the deposition flow until their links break
Wire strength500000.0 kPaPlateau stress of the link curve (steel ≈ 0.25–2 GPa, PP ≈ 0.3–0.5 GPa). The link yields here (plastic flow) and breaks at Break strain
Link stiffness200000.0 N/mElastic slope of a link in N/m. The solver has no direct stiffness knob — measured kn = strength·A/(yield·spacing) — so the yield strain is derived from this and must land strictly inside the breaking strain (V037)
Break strain1.0Link breaking strain (relative to node spacing). Measured: mm-scale jostling during deposition strains every link — 0.05 broke them all before loading, ≥ 1.0 kept the chains intact through three rain layers (polypropylene fibres: 20–150 %)
Specimen diameter50.0 mmThe diameter should be at least 10× the largest particle diameter
Specimen height150.0 mmJudge H/D by the measured specimen height, not by this number: after pluviation + headroom, the measured specimen height is only ≈0.69× the drum height (150 → 103.5 mm; 100 → 72.5 mm). So with a drum height of 100 the nominal H/D=2.0 but the actual value is only 1.45, below the 2.0 of a conventional triaxial test, and the measured deviation is hard: with the same set of micro-parameters, changing only the drum height from 100 to 150, φ at ε=20% drops from 38.07° to 34.66° (−3.4°), and the porosity over the whole shear goes from 'rising +0.038' to 'falling −0.003' — the pancake specimen is showing fake dilatancy. A drum height of 100 is only enough when 'only the order of magnitude of q matters'
Target porosity0.5Corresponds to an initial void ratio e = φ/(1-φ). Pluviation can only reach 0.45–0.55: in a drum with 5 mm spheres and D=50 mm, loose packing falls in this range; reaching 0.40 needs compaction (vibration / layered rolling). Set below the reachable value, preparation reports 'measured porosity does not match the setting' and the q measured is compaction resistance
Axial strain rate0.05 1/sPlaten velocity = strain rate × specimen height
Target axial strain0.30.3 = 30%. 0.2 systematically under-reports φ by about 4° (Q72/Q73: at ε=0.20 most specimens are still rising steeply, and the final frame is only a cut-off point). 0.30 is the knee — beyond it another 0.05 of strain adds only 0.4°, while H/D has already dropped from 1.67 to the forbidden boundary of 1.50. Changing it requires changing target_time too (V019 blocks it)
Confining stress50.0 kPaConstant lateral stress (servo). 0 = rigid drum without servo (constant volume, σ_lat varies with volume)
Consolidation time1.5 sDuration of isotropic consolidation (radial + axial servos pressing to σ₃ at the same time), after which it hands over to the displacement-controlled main actuator. Included in the physical duration. Too short leaves residual velocity at the shear start (measured: at 0.6 s c50 still has 0.75 m/s at the end of consolidation, 150× the loading velocity) — that residual builds a fake peak at the start of q-ε
Physical duration7.5 sMust be ≥ consolidation time + target axial strain / axial strain rate, otherwise the loading does not finish (7.5 = consolidation 1.5 + 0.30 / 0.05)

Presets

Preset What it changes
Confining stress 50 kPa(the defaults)
Confining stress 100 kPaConfining stress → 100.0 kPa
Loose sandTarget porosity → 0.45

Analysis cards on the result page

Card Unit How it is computed
Deviator stress–axial strainkPa peakq = σ_ax − σ_lat: σ_ax is the resultant force of the upper platen along its outward normal / specimen cross-section (πr², not the platen's square 4r²), and σ_lat is the sum of the side-wall normal projections / wetted lateral area (π·D·specimen height, not the drum height — see Q57)
Axial stress–axial strainkPa peakAxial resultant force of the upper platen (wall group) / specimen cross-section area. The lateral stress is not subtracted, so it is not the deviator stress

Inverse solve — not available for this template. You set the parameters and read the result forward. (An inverse curve is declared only where a spike measured one: single variable, monotonic, R² > 0.9. Currently that is pile-angle only.)

At default scale — ~1,874 particles · 761,597 steps · ~3.5 h (heavy). The particle count is the one that decides the wait: halving the diameter multiplies it by eight.

3.4 box-lift · Box lift

The box is lifted out of a pile of material; outputs a lift force curve. The standard case of the EDEM Calibration Kit

The box of stage ① is a rigid boundary (an open box), not a flexible bucket. Lift force = specimen self-weight + side-wall friction, so the ratio to the self-weight should be above 1

What you get

- Lift force curve - Peak lift force - Lift force / specimen self-weight

The parameters you will actually turn

Panel label Default What it does
Mean particle diameter5.0 mmMedian particle diameter. Halve it and the particle count grows 8×, the time step halves
Contact modelhertz-mindlinbonded adds contact adhesion (contact.cohesion) on top of friction; broken bonds stay broken. kn-ks takes the pair stiffness directly (contact.kn/contact.ks, N/m) instead of deriving it from young/poisson. viscoelastic adds contact damping (contact.cn/contact.cs, N·s/m). cpm bonds every initial contact and damages them (strength = E·epsCrackOnset; softening over epsCrackOnset·relDuctility). capillary pulls grains together with liquid bridges (bridge_volume / surface_tension / contact_angle) — the wet-sand apparent cohesion. jointed-rock bonds the forming contacts and breaks them at a Mohr–Coulomb envelope (measured break at min(tensile_strength, bond_cohesion/tanφ); broken bonds never re-bond). The self-built local kernel runs kn-ks natively but refuses bonded, viscoelastic, cpm, capillary and jointed-rock (use YADE/WSL for those)
Inter-particle friction coefficient0.5The main control on the macroscopic internal friction angle. Measured on S3: 0.3→15.7°, 0.5→23.5°, 0.7→29.2°
Particle-wall friction coefficient0.4Affects sliding at the bottom. The pile angle is very sensitive to it
Bridge volume0.0 m³capillary model only: liquid volume of each bridge (m³). Created at first touch, pulls only while the pair is separated, ruptures at a gap ∝ volume^(1/3). Match it to the grain size — for mm grains use 1e-12 … 1e-10; a µm-scale value on mm grains gives nonsense forces. 0 = unused
Bond tensile strength0.0 kPajointed-rock model only: the tension cutoff of the bond break envelope — the bond breaks at min(tensile_strength, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa. 0 = unused
Bond cohesion0.0 kPajointed-rock model only: the shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly (measured), so both values must be > 0. 0 = unused
Boundaryrigid-wallperiodic = wall-free unit cell: fill + compaction inside the cell, no gravity (a periodic cell has no floor), loading drives the cell itself. Requires the cell size below, forbids walls and gravity (validate V032/V033)
Fibresoffon = mix count flexible fibres into the specimen: chains of grain-scale nodes joined by wire links (tension only, break at break_strain). Grain–fibre contacts stay frictional (measured: the fibre material derives from the grains'). Requires the hertz-mindlin / bonded / jointed-rock grain model and the rigid-wall boundary (V037)
Fibre count20Number of fibre chains, distributed evenly across the rain layers. Each chain also displaces grain volume — the particle count estimate includes its nodes
Fibre length24.0 mmChain length. Must span at least one node spacing (1.05·2·node_radius) — shorter carries no link (V037)
Node radius2.0 mmChain-node sphere radius. Keep it at grain scale (≈ half the mean grain diameter): measured, small light nodes are battered by the deposition flow until their links break
Wire strength500000.0 kPaPlateau stress of the link curve (steel ≈ 0.25–2 GPa, PP ≈ 0.3–0.5 GPa). The link yields here (plastic flow) and breaks at Break strain
Link stiffness200000.0 N/mElastic slope of a link in N/m. The solver has no direct stiffness knob — measured kn = strength·A/(yield·spacing) — so the yield strain is derived from this and must land strictly inside the breaking strain (V037)
Break strain1.0Link breaking strain (relative to node spacing). Measured: mm-scale jostling during deposition strains every link — 0.05 broke them all before loading, ≥ 1.0 kept the chains intact through three rain layers (polypropylene fibres: 20–150 %)
Container length80.0 mm—
Container width80.0 mm—
Container height80.0 mm—
Target porosity0.42—
Lift velocity0.05 m/s—
Lift distance0.06 m—
Physical duration1.3 sMust be ≥ lift distance / lift velocity, otherwise the loading does not finish

Presets

Preset What it changes
Standard(the defaults)
Fast liftLift velocity → 0.2 m/s

Analysis cards on the result page

Card Unit How it is computed
Lift forceN peakVertical resultant force of the box (wall group); the ratio to the specimen self-weight is also given (self-checkable)

Inverse solve — not available for this template. You set the parameters and read the result forward. (An inverse curve is declared only where a spike measured one: single variable, monotonic, R² > 0.9. Currently that is pile-angle only.)

At default scale — ~2,752 particles · 164,212 steps · ~20 min (medium). The particle count is the one that decides the wait: halving the diameter multiplies it by eight.

3.5 slope · Slope

The slope body fails and slides under gravity; outputs a displacement field and the runout extent. MatDEM's flagship scenario

The slope face is drawn (swept profile): the box acts as the container (open top) + a trapezoidal slope body as the fill domain, and the inclined face is the free surface. Slope angle / slope height / slope length are not independent — when the length is not enough the toe is pushed to the left end and the actual slope angle grows (the UI shows it as it is). Cementation needs contact.contact_model = bonded plus a cohesion > 0 (the local kernel cannot run it — it goes through YADE/WSL)

What you get

- Displacement field - Velocity field - Runout extent - Runout

The parameters you will actually turn

Panel label Default What it does
Mean particle diameter6.0 mmMedian particle diameter. Halve it and the particle count grows 8×, the time step halves
Contact modelhertz-mindlinbonded adds contact adhesion (contact.cohesion) on top of friction; broken bonds stay broken. kn-ks takes the pair stiffness directly (contact.kn/contact.ks, N/m) instead of deriving it from young/poisson. viscoelastic adds contact damping (contact.cn/contact.cs, N·s/m). cpm bonds every initial contact and damages them (strength = E·epsCrackOnset; softening over epsCrackOnset·relDuctility). capillary pulls grains together with liquid bridges (bridge_volume / surface_tension / contact_angle) — the wet-sand apparent cohesion. jointed-rock bonds the forming contacts and breaks them at a Mohr–Coulomb envelope (measured break at min(tensile_strength, bond_cohesion/tanφ); broken bonds never re-bond). The self-built local kernel runs kn-ks natively but refuses bonded, viscoelastic, cpm, capillary and jointed-rock (use YADE/WSL for those)
Inter-particle friction coefficient0.6The main control on the macroscopic internal friction angle. Measured on S3: 0.3→15.7°, 0.5→23.5°, 0.7→29.2°
Particle-wall friction coefficient0.5Affects sliding at the bottom. The pile angle is very sensitive to it
Bridge volume0.0 m³capillary model only: liquid volume of each bridge (m³). Created at first touch, pulls only while the pair is separated, ruptures at a gap ∝ volume^(1/3). Match it to the grain size — for mm grains use 1e-12 … 1e-10; a µm-scale value on mm grains gives nonsense forces. 0 = unused
Bond tensile strength0.0 kPajointed-rock model only: the tension cutoff of the bond break envelope — the bond breaks at min(tensile_strength, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa. 0 = unused
Bond cohesion0.0 kPajointed-rock model only: the shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly (measured), so both values must be > 0. 0 = unused
Boundaryrigid-wallperiodic = wall-free unit cell: fill + compaction inside the cell, no gravity (a periodic cell has no floor), loading drives the cell itself. Requires the cell size below, forbids walls and gravity (validate V032/V033)
Fibresoffon = mix count flexible fibres into the specimen: chains of grain-scale nodes joined by wire links (tension only, break at break_strain). Grain–fibre contacts stay frictional (measured: the fibre material derives from the grains'). Requires the hertz-mindlin / bonded / jointed-rock grain model and the rigid-wall boundary (V037)
Fibre count20Number of fibre chains, distributed evenly across the rain layers. Each chain also displaces grain volume — the particle count estimate includes its nodes
Fibre length24.0 mmChain length. Must span at least one node spacing (1.05·2·node_radius) — shorter carries no link (V037)
Node radius2.0 mmChain-node sphere radius. Keep it at grain scale (≈ half the mean grain diameter): measured, small light nodes are battered by the deposition flow until their links break
Wire strength500000.0 kPaPlateau stress of the link curve (steel ≈ 0.25–2 GPa, PP ≈ 0.3–0.5 GPa). The link yields here (plastic flow) and breaks at Break strain
Link stiffness200000.0 N/mElastic slope of a link in N/m. The solver has no direct stiffness knob — measured kn = strength·A/(yield·spacing) — so the yield strain is derived from this and must land strictly inside the breaking strain (V037)
Break strain1.0Link breaking strain (relative to node spacing). Measured: mm-scale jostling during deposition strains every link — 0.05 broke them all before loading, ≥ 1.0 kept the chains intact through three rain layers (polypropylene fibres: 20–150 %)
Slope length120.0 mm—
Slope width70.0 mm—
Slope height70.0 mm—
Slope angle30.0 °Angle between the slope face and the horizontal. Real slope-face geometry (swept profile), not tilted gravity. It is not independent of the slope height and the slope length: when the length is not enough the toe is pushed to the left end and the actual slope angle grows
Contact cohesion0.0 kPa0 = cohesionless granular material (always slides); the larger the more stable
Target porosity0.42—
Physical duration0.5 s—

Presets

Preset What it changes
Loose sand slopeInter-particle friction coefficient → 0.5
Cemented slope bodyContact cohesion → 50.0 kPa, Inter-particle friction coefficient → 0.7

Analysis cards on the result page

Card Unit How it is computed
RunoutmmAdvance distance of the front (99th percentile in x) from the first frame to the last, with the front advance history

Inverse solve — not available for this template. You set the parameters and read the result forward. (An inverse curve is declared only where a spike measured one: single variable, monotonic, R² > 0.9. Currently that is pile-angle only.)

At default scale — ~383 particles · 89,494 steps · ~53 s (light). The particle count is the one that decides the wait: halving the diameter multiplies it by eight.


4 · Reading the estimate before you run

The estimate bar exists because how big a run can be has to be stated before it starts, not discovered after forty minutes. It reads the same numbers the run will use.

Tier Criterion Colour What to do
light≤ 30,000 particles and ≤ 5 mingreenNothing
medium≤ 100,000 particles and ≤ 30 minblueFine, go and do something else
heavy≤ 500,000 particles and ≤ 4 hamberIt will run. Read the hint before starting
blockedanything aboveredIt will not run on this machine. The bar always offers one sentence you can act on

Two things it is not:


5 · What the engine can and cannot do

The catalogue below is not marketing copy: every row is a decision already taken, and the ones that say not doing it carry the reason so that nobody has to argue it again.

Two engines, and the smaller one has two ceilings. Every run goes through YADE inside WSL. When that is missing, the Run button offers the built-in reference kernel instead — but only for cases it can actually finish — ≤ 150 grains and ≤ 4 000 steps — and that is not a particle count with a footnote: a 60-grain case with target_time 30 s is refused on the step ceiling, and the dialog then names the ceiling and the knob that moves it (d_mean for the first, target_time for the second). The offer is made by asking the engine, so a case it would refuse is not offered at all. Production runs still need YADE.

Status Means
verifiedA real case has been run and the numbers were reconciled against a measurement
availableThe engine has it and the mapping is clear, but we have not verified it — traps show up only when it runs
plannedThe engine has it; a contract field or a calibration stage must come first. The panel can draw it, it cannot run yet
excludedDecided against, with the reason attached

61 capabilities: 36 verified · 0 available · 25 planned · 0 excluded.

5.1 Contact models

Capability Status Notes
Linear spring + Coulomb frictionverifiedNo template uses it (Q178): the contract default is hertz-mindlin, all five templates build with it, and the panel has no switch for contact_model at all — so on the desktop this model cannot be selected today. It is kept at verified because the self-built kernel implements it and reproduces YADE's kn/ks formulas bit for bit; the YADE adapter refuses it (linear-spring not implemented), which is why the panel hides the switch. It is the cheap linear route for large-deformation cases once somebody needs it
Hertz–Mindlin (non-linear elastic)verifiedThe default of ContactModel; stiffness varies with overlap, so it is more stable than the linear spring under large deformation. Rolling moment = kr·Δθ increment + eta·Rmean·|Fn| plastic clamp, ineffective under the linear law (CundallStrack has no moment block)
Independent normal/tangential stiffnessverifiedUse it when you do not want Poisson's ratio to decide the kn/ks ratio for you; the calibration stage has to be redone (L1 inverts both quantities from a single uniaxial test)
Bonded contact (wet sand / cohesive soil)verifiedMeasured on real runs (Q180, 2026-11-12; job, .dres pair and probe scripts kept in out/evidence/cohesion-q180/): box-lift base scene, 2 549 particles, cohesion 50 kPa — 5 147 bonds formed during deposition, 1 broken, adhesion 0.20–0.45 N matching the theory cohesion·R_min² at both ends of the grading; the cemented specimen settled 0.46 mm less than the cohesionless control (32.50 vs 32.04 mm top height, same seed). Two facts measured on the real engine surface that contradict the old plan on this row: broken bonds never heal (damage is real and permanent — the 'neverDamage' switch the plan mentioned does not even exist in YADE 2022), and twist stiffness is not a knob (the engine derives it from the tangential stiffness by a fixed ratio — the planned contact.twist_stiffness field would have been a fake knob, so it was never added). Boundaries stay friction-only: the engine has no bonded route for wall contacts (verified instead that the wall still carries the specimen's weight through the ordinary frictional contact). Bonds form on every new contact, including during deposition — cementation starts at preparation, not at a separate 'bonding' stage. Validation V024 refuses the model/cohesion mismatch in both directions; the self-built kernel refuses bonded outright (linear spring only)
Linear viscoelastic (Kelvin–Voigt)verifiedImpact, rockfall, and any case where the energy dissipation must live in the contact law instead of the global velocity damping. For quasi-static work local damping is cheaper, which is why this was never on the critical path
Bonded particle model CPM (concrete / rock)verifiedParameter-direct support landed (Q183, measured on 2022.01a): contacts created while the specimen forms bond automatically (kn = E·A/L with A = πR² and L the actual gap, ks = kn·poisson); contacts created during loading stay frictional and a broken bond never re-bonds (the engine opens the bond-forming window through preparation and locks it at the loading seam — measured: the solver's default window closes after ~10 steps, so with the default the whole deposition would silently run unbonded). Damage (omega) grows past epsCrackOnset, softens over ~epsCrackOnset·relDuctility, and a fully damaged contact carries zero force. The tensile strength is E·epsCrackOnset — the nominal strength field has NO effect on the response (identical pull trajectories for sigmaT = 100 and 10 000), so it is not exposed. neverDamage=True keeps every formation bond at omega ≡ 0. E2e evidence (60 kPa radial squeeze, identical history): damaging variant 15 bonds partially damaged and 0.37 mm more settlement; the neverDamage reference holds 77/77 bonds at omega 0. Wall contacts stay frictional (walls do not bond — the same rule as the bonded model). What this does not include: the calibration workflow (inverting the macroscopic c, φ, σ_t from uniaxial/triaxial curves into epsCrackOnset/relDuctility) — the parameters are taken directly; the inverse solve is a separate capability
Jointed rock JCFpm (intact-rock bond envelope)verifiedProbed and run on 2022.01a (Q188, 2026-11-13; 21 probe scripts and two real end-to-end cases kept in out/evidence/jcfpm-q188/): the bond forms through the Ip2's bond window (default 1 = only the contacts that exist on the first step bond; -1 = open), so the engine reuses the CPM mechanism — the window stays open through preparation (deposition contacts bond) and locks at the loading seam. E2e pair (p21 cell, 47–55 spheres, 600 kPa radial servo, identical history): the strong variant (break criterion 4 MPa) holds 80/88 bonds cohesive, the weak variant (criterion 1 kPa) keeps only 47/90 — 43 pairs lost their bond — the break envelope discriminates the strength parameters on a real run. Measured break criterion (three-point parameter sweep, per-step sampling): σ_break = min(tensile_strength, bond_cohesion/tanφ) — the Mohr–Coulomb envelope's tension side; either threshold at 0 collapses the bond to zero strength (an instant break), so the contract requires both > 0 (V036). The Ip2 writes the stress thresholds directly (FnMax = tensileStrength·A, FsMax = cohesion·A, A = π·R_min²); kn = 2·E·R*, ks = kn·ν. Broken bonds never re-bond; broken pairs carry plain friction (measured: a tension-broken pair re-compressed to 192.9 N through FrictPhys — and the isBroken flag only flips on a SHEAR break, so break bookkeeping must count non-cohesive pairs, not that flag). Walls stay frictional by base-class matching (measured: a sphere resting on a wall AND on an inward-facing facet — the same rule as bonded/cpm). A bonded specimen must not meet a movable compaction platen: the strong variant under the box-lift press stored elastic energy until the whole specimen was launched through the walls (compaction round 6 advanced the platen 773.8 mm onto a 1719.5 mm specimen, every particle at −18 km and 484 m/s) — bonded survives the same press only because its 50 kPa bonds break and release it, so the e2e uses the Q183 no-top-plate recipe. The Weibull cross-section randomisation stays off at its defaults (parameter directness). What this does not include: the joint branches (per-particle joint-plane orientations, the jointXxx material fields) — they need a joint-geometry import (geom-import first), and the joint-roughness field the old plan listed has no knob on the engine surface (a fake knob, never added)
Capillary liquid bridge (unsaturated sand)verifiedParameter-direct support landed (Q184, measured on 2022.01a): each bridge is created at first touch with the given volume, pulls the pair together only while separated (while overlapping the bridge force does not enter the contact force), and ruptures at a gap ∝ volume^(1/3); re-contact forms a new bridge. The contact part is the viscoelastic contact (kn = E·R, ks = kn·ν, damping cn/cs identical), the bridge rides inside the same law — so the apparent cohesion from the bridges adds on top of ordinary friction. The official wet-pair self-check value (2.07328148666e-07 N) is reproduced bit-for-bit. Volume must match the grain size (mm grains: 1e-12…1e-10 m³ — a µm-scale volume drives the numeric table far outside its data, measured: garbage forces). What this does not include: converting a macroscopic water content / degree of saturation into per-contact bridge volumes — the volume is taken directly; the hydrology inversion is a separate capability
Lubrication force (wet particles / slurry)plannedProbed on 2022.01a (out/evidence/lubrication-q185/, 11 probes): the mechanics are excellent — the implicit drainage law reproduces the official analytic sedimentation check to 1.1e-4 and the normal force follows 6π·η·(R)²·v/h within 1 % (R the effective radius) — but the 2022.01a surface cannot carry the product's deposition flow, so it stays planned. Measured blockers: (1) the law aborts (C++ FATAL) on any pair whose first evaluation sees a closed gap (u = −penetration ≤ 0 at creation) — sphere–wall pairs are always created exactly at contact (no pre-contact detection: the wall Ig2 has no interactionDetectionFactor, the wall bounding-box functor has no enlargement), so raining into a container aborts at the first floor touch; (2) pre-creating wall pairs explicitly (utils.createInteraction while the gap is open) and relying on the roughness support (contact at gap 2·ε·a, ε = surface roughness) works mechanically, but the separation suction (∝1/h²) makes free sedimentation numerically explosive at practical fixed dt — a 5-sphere rain blew apart by step ~12 000 (the official examples are all two-sphere, hand-tuned setups); (3) η/ε/kεp are Ip2-level globals, not material fields; the trapezoidal path (resolution=0) avoids the abort but thrashes thousands of minimal sub-steps per step. Q194 probes (out/evidence/lubrication-q194/, 7 probes) replaced the old unlock condition ("a force cap or adaptive dt first") with measured facts: the 5-sphere rain diverges at the approach epoch at EVERY dt tested (2e-6, 2e-7, 2e-8 — the onset is simulated-time-locked, not step-locked) and at both solver resolutions (1 and 2); an isolated sphere–sphere pair survives its own contact transition at dt=2e-8 (u crosses 0, contact engages, force peaks at a bounded 2.74 N — so there is no force spike for a cap to clamp); and the ablation table pins the energy pump — normal-direction lubrication with all walls SURVIVES, the full law with the floor wall only SURVIVES, the full law with the side walls only DIVERGES: the pump lives in the tangential/twist/roll lubrication terms acting on wall-parallel sliding pairs, the one configuration every deposition scene contains. No engine-side force cap or adaptive dt can carry that (nothing spikes to cap; no dt threshold exists). Unlock = an upstream law whose tangential terms are stable under wall-parallel sliding; engine mechanisms cannot fix it
Polyhedral particleplannedRe-opened 2026-11-16 by user directive: the product must cover the full engine surface (the original exclusion reasoning is kept in the changelog). Still needs the arbitrary-polyhedron shape contract, a deposition + rendering path, and a verified case before it can run
Mortar contactplannedRe-opened 2026-11-16 by user directive: full engine coverage. The overlap-with-CPM concern is kept on record; it must earn a verified case against the literature before it ships
Bubble / foamplannedRe-opened 2026-11-16 by user directive: full engine coverage. Outside the geotechnical target scenario, so it enters as planned at the lowest priority; a verified case is still required
Luding contact (with hysteresis)plannedRe-opened 2026-11-16 by user directive: full engine coverage. The original blocker (library absent from the build) no longer applies - the class is confirmed present in the engine inventory probe (Q213); contract fields + a verified case come first
Unsaturated soil (suction)plannedRe-opened 2026-11-16 by user directive: full engine coverage. Suction and degree of saturation are two extra state variables, so the panel read-outs must be designed before wiring; a verified case is still required

5.2 Special physics

Capability Status Notes
Fibre / reinforcement (flexible fibre chains)verifiedProbed and run on 2022.01a (Q189, 2026-11-13; 10 probe scripts in out/evidence/wire-q189/): a fibre is a chain of grain-scale spheres whose consecutive pairs are wire links — measured force = curve(strain)·A, tension only (no compression: a squeezed pair passes through; ks = 0), elastic slope to the curve's first point, plastic plateau (plastD) to break_strain, then the link is deleted (numBrokenLinks counts it on both bodies). Link window: a link forms only at an iteration ≤ linkThresholdIteration (default 1; -1 blocks even pre-created pairs), and a contact formed while the window is closed hangs force-free (its interaction exists but fills no physics — measured: 60 steps of sustained squeezing never filled it) until ANY window step, when the whole hanging batch is filled AND linked at once — so the engine opens the window for exactly one step per chain, keeps every node one spacing from the placed ones, and counts only each chain's structural pairs (a chain folded by compaction may self-tie at Fn ≈ 0; mechanically irrelevant, not counted). Mixed pairs stay frictional: the fibre material derives from the grains' (measured), so grain–fibre and wall–fibre contacts dispatch to the grains' own frictional contact route (measured under hertz-mindlin). E2e (probe 10, layered deposition + ceiling squeeze): chains kept 4/4 links alive through three rain layers and tensioned to ≈ the plateau force (0.30 N of 0.314 N) as the bed compressed. Deposition survival is a parameter question: node radius must stay at grain scale (1 mm nodes among 4 mm grains are launched out of the specimen, probe 9) and break_strain must exceed the mm-scale jostling (0.05 → every link broke; ≥ 1.0 → intact). What this does not include: fibre–fibre contacts between DIFFERENT chains (a cross-chain touch hangs force-free while the window is closed and is not counted by the structural-pair census — the sampler's spacing avoidance makes it unlikely), the rockfall double-twist mesh (isDoubleTwist with its lambda scatter knobs), and fibre orientation control (random uniform; the slab-thinner-than-chain fallback places horizontal and reports it). The kernel refuses fibres (no second population, no wire element)

5.3 Geometry modelling

Capability Status Notes
Box (block)verifiedrole=container compiles into six walls (faces may be open); role=fill compiles into a fill domain
Cylinder (block)verifiedThe axis is fixed to z; as a container it compiles into a 48-segment facet side wall + a bottom face (the same path as the triaxial template)
Swept profile (extrude)verifiedThe minimal version of STKO's extrude: slope wedges, tunnel sections and layered filling all rely on it. Fill domain only — slanted side faces would need a triangular mesh wall, which v1 does not do (V014 blocks it first)
Boolean excavation (cut)verifiedFoundation pits, tunnel bores and excavation faces are all this. A cut means "excavate" no longer needs a command of its own — it is a geometric operation, not a loading mode
Excavation during the run (construction stage)verifiedThe same cut differs by one at_time, and the physics is completely different: an initial cut is "there was never any material here", so the cloud avoids it; an excavation during the run is "fill it up first, suck it out at the right moment", and after the cut the material above collapses. So it lets such processes as "layered excavation / build then excavate / slope cutting" be expressed without adding a template per construction method — construction stages are generic, not cases. The time is relative to the start of the solve phase (end of consolidation; end of preparation when there is no loading). .dres marks the excavated slots with a mask and does not compact the indices (Q37)
Arbitrary polyhedron (vertices + faces)plannedThe contract would need two more fields, points and faces, and the containment test would become a half-space intersection. prism already covers the overwhelming majority of engineering shapes (any profile × one extrusion direction); extrusion in two directions (a true 3D polyhedron) waits until someone really needs it
Boolean union (fuse)plannedUnioning two blocks into one fill domain is equivalent to "fill both" — two fill blocks do that today, so no capability is missing. The real value is "union then cut once"; wait until the cut reuse count goes up
Boolean fragmentation (fragment)plannedLayered filling and staged excavation need it to cut a volume into pieces and assign each one. Multiple materials come first (different μ per layer), and that is an entire missing sub-section of the contract
Import geometry (STEP / STL / DXF)plannedReal terrain and structural surfaces can only come from files, and STL is already in — as a boundary: capability mesh is verified on a real run, and the file is not trusted blindly (winding decided by the enclosed volume and reversed when inward, normals recomputed from the winding, an open surface reported with its volume capped by the opening). What is still missing is the general import: (1) STEP and DXF need a geometry kernel (OCC) — an STL is triangles only, so a CAD solid cannot come in; (2) an imported body can only be a wall, never a fill domain or a cut, so "excavate this pit out of an imported terrain" is not expressible yet
Points and lines (monitoring points / anchors / fibres)plannedA point is a measurement location, a line is an anchor or a fibre. Neither changes the particles, they only change what is recorded and what is reinforced — this waits until post-processing can sample a field by location (right now everything is written out for all particles)

5.4 Boundaries

Capability Status Notes
Box (six walls, faces optional)verified—
Cylinder tubeverified—
Plate (movable, for loading / servo)verified—
Mesh boundary (STL import)verifiedMeasured on a real run (Q179; job, report and the two probe scripts kept in out/evidence/mesh-hopper-q179/): a 144-triangle open hopper (Ø70 → Ø24 mm, 86 mm tall) as the sole container, 667 particles, 11 997 steps, 99.4 s wall clock. All 667 centres ended inside the mesh (worst clearance -2.0 mm to the nearest facet), and the container volume came from the body (1.61e-4 m³), not from the box around it (4.21e-4 m³, 2.62x). Both engines read the same file and both reverse the winding (mesh.facet_winding): a facet's own normal must point toward the material, the STL's must point out of it, and getting it backwards is a run that finishes with every particle on the floor. Two caveats, both reported by the run rather than hidden: (1) the fill came out 667 of 860 requested because the cloud is scattered in the bounding box and then filtered to the body — the per-layer keep fraction is a whole-container average, so a cone narrow at the bottom loses more than it should; (2) porosity settled at 0.785 against a 0.42 setpoint, which is the pluviation ceiling, not a mesh effect (there is no movable platen to compact against)
Periodic boundaryverifiedLanded in Q186 on measured facts (WSL 2022.01a, 2026-11-12): the real switch is O.periodic = True (O.isPeriodic is a fake Python attribute that sets nothing); body positions are not wrapped (the cell machinery handles periodic images, positions stay continuous); a wall cannot coexist with a periodic cell — InsertionSortCollider::spatialOverlapPeri asserts every body's span < 0.99 of the cell dimension and a wall's unbounded box always violates it, a C++ abort Python cannot catch; gravity must be 0 — the cell has no floor and the specimen free-falls forever (measured: velocity grows linearly, never settles); cross-boundary contact works exactly (two spheres straddling a face create a real interaction with a symmetric push-apart force). Periodicity is all-or-nothing: no per-axis switch exists on any engine surface (bounding-box, integrator and cell surfaces censused), so the 2D-periodic + gravity combination of a sand-column RVE is out of reach on this YADE. Loading goes through ONE cell servo (the YADE-class field on the right): measured semantics — stressMask bit set → goal = signed stress, compression negative (goal −1e4 compresses); bit clear → goal = absolute strain target (probe: the unmasked axes relaxed from −2.2 % back toward 0), maxStrainRate caps the cell rate (a 0.2 1/s cap over 0.03 s moved the cell exactly 0.6 %). No stress-rate knob exists — stress axes are capped at 0.5 1/s. The engine refuses displacement mode and wall-group servos on the cell (V033) and keeps whole-span channels only (the goal vector has no time windows). Preparation fills by RSA cloud in an enlarged box and shrinks onto the fixed cell in increments with relaxation (the cell never moves; porosity = 1 − V_solid/V_cell is exact). Scope of the verdict: e2e-verified for stress/strain channels on the cell; cell shear (trsf/velGrad off-diagonal, the periodic simple-shear box) is a next-stage extension, as is time-windowed cell loading

5.5 Loading & servo

Capability Status Notes
Displacement loading (constant-rate push)verified—
Strain loading (normalised by specimen height)verifiedTriaxial uses it: displacement divided by the current specimen height, not the initial height (a big difference under large deformation)
Constant-stress servo (axial / normal)verifiedA second channel parallel to the main drive, not a fourth LoadMode; on the same wall group each controls one component
Constant-stress servo (radial / confining)verifiedOn a cylinder the radial force vectors sum to 0 → must project ΣF·n/ΣA piece by piece; pieces with zero area are excluded from the weighting
Drum lift (formwork removal)verifiedThe pile-angle case uses it; the drum is a friction boundary, lifting too fast drags the specimen up
Constant-stress creepverifiedA stress channel ramps the covering servo's target from the measured stress at the window's first tick (never the contract value) up to base+target_stress at the given rate, then the servo holds it — one drive law shared by both engines (scene.stress_drive_target). Target back-computed from the window span when no rate is given. Measured e2e (Q182 evidence, tiny 4-sphere cell): base picked up 6.24 kPa where the servo contract said 10 kPa (consolidation had not fully converged), the target tracked the 100 kPa/s ramp tick-by-tick, clamped at 26.24 kPa = base+20 kPa, and the measured stress held within 2.9e-6 deviation for the 0.55 s creep hold (mean 1.6% over the whole window); a 50-sphere variant with ~2.2 MPa compaction residual repeated the law unchanged (base 2 226.4 → clamp 2 246.4 kPa, dev 1.7e-5). Creep duration is bounded by target_time (wall clock is not counted)

5.6 Solver components

Capability Status Notes
Time integration (translation + rotation + local damping)verifiedRotation has no contract field (always on): I = 2/5·m·r², angular acceleration uses the same cundallDamp2nd. The moment arm changes with the law: linear r−un/2 (CundallStrack's sphericalBodies shortcut branch), Hertz r−un (Mindlin goes through contactPoint, i.e. the projected point) — both inversions come out exactly 1, the difference is un/2. Reconciliation benchmarks rolling-plane (linear), twist-plane (tangential history rotates with the contact), roll-fric-plane (rolling moment)
Automatic time step (Rayleigh criterion)verified—
CFD–DEM coupling (fluid)plannedRe-opened 2026-11-16 by user directive: full engine coverage. It stays a product of a different order (mesh + fluid solver + two-phase coupling), so it enters as planned behind the contact-model batches; the engine build must gain the flow feature first (self-built rebuild in progress)
YADE's built-in triaxial engineplannedRe-opened 2026-11-16 by user directive: full engine coverage. The black-box concern stands: the engine writes velocities and records stresses internally, so exposing it requires an auditability note on the panel; the hand-written servo route stays the verified default

5.7 Command stream & extensions

Capability Status Notes
Command stream (Python form)verifieddem/dsl.py: Builder builds a scene command by command, from_scene exports it back; the round trip agrees field by field (tests/test_dsl.py, including a direct-shear 10-wall scene that has really been run)
Short-command form (one per line)verifiedAnother layout of the same command sequence (render_short / parse_short) — for people to copy, for external tools to read; not a second semantics
Operation recording (UI → command stream)verifiedfrom_scene() emits every field: a scene clicked together in the UI can become a script at any time. Emitting everything is deliberate — trimming defaults would silently change the scene the moment a contract default changes
Parameter sweep / batch submissionverifiedVerified: build_variants()/write_jobs() produce N distinct SceneDesc variants from one base scene (d_mean / mu_pp / target_porosity / damping), each written as a job JSON, and every variant was solved end-to-end by the reference kernel engine (make_engine(..., kind='kernel').run()) producing a .dres with n_capacity > 0. The sweep is a pure function (no Qt) so it is unit-tested; submission is now wired through dem/jobs.py (discovery + local kernel runner) and dem/ui/jobs_panel.py (the panel, reusing dem/ui/runner.JobRunner for YADE/WSL). The result summary comparison table announced in the note is now landed on the desktop too: dem/sweep.py::collect_variants aggregates one row per variant from its .dres, and dem/ui/sweep_compare.py::SweepComparisonDialog draws the read-only side-by-side table. The entry point is Solve › Parameter sweep… → Compare results… on the sweep dialog. tests/test_sweep_compare.py runs the proven tiny kernel scene on two real variants and asserts all seven scalar metric columns are extracted; a variant whose .dres has not been produced yet is shown as — not run — instead of a silent gap.
Custom force hook (Python plug-in)verifiedVerified end-to-end on 2022.01a: a python callback calling O.forces.addF enters the dynamics every iteration (99 calls/100 steps, the hooked sphere rose 0.9 mm against the control), a file-path hook module is imported inside the solver process and wired through __main__ because the callback's command expression evaluates there. The material library is no longer a closed set — any extra force behaviour is user code, the watershed against closed software like MatDEM
Embedded console (REPL)verifiedCovered by tests/test_console_panel.py (5 passed): a ParticleSpec expression is evaluated and its repr (d_mean=0.005) is shown in the output; 1 + 2 prints 3; raise ValueError('boom') prints the traceback text; assigning a SceneDesc and pressing 'Send to editor' emits sceneBuilt carrying a SceneDesc; the %%dsl magic is gracefully skipped when dem.dsl.parse is absent. ruff check dem tools tests passes.

5.8 Results & analysis

Capability Status Notes
Direct-shear peak / residual strengthverifiedτ = tangential resultant on the loading plate / specimen cross-section (not the plate's footprint); the horizontal axis is the plate's actual travel (not time × rate). σ_n prefers the servo measurement, and the stress ratio uses the two numbers of the same frame — dividing the peak τ by the final-frame σ_n gives a ratio with no physical meaning (measured 0.82 vs 0.51). The numbers have only one implementation: ui/analysis.py::shear_peaks(), shared by the card and the strength envelope
Mohr–Coulomb envelope (c, φ)verifiedAcross cases: the same micro-parameters, only σ_n changed, ≥3 points for a least-squares fit. tools/strength_sweep.py generates/collects/plots, dem/strength.py only does the fit and the Mohr circle geometry (zero dependencies, verifiable on pure synthetic data). Three conventions pinned by tests: ①two points only define a line, they cannot verify straightness (R² is identically 1 as a mathematical necessity, not a quality metric); ②negative c is not clamped (clamping to 0 would silently inflate φ while the UI numbers still look normal); ③the Mohr circle uses that point's own tangent — a point above the fitted line has no circle "tangent to the global envelope". Wired into the window (Q177): Results › Strength envelope… reads the picked files, fits, draws the circles and prints the conditions; the command remains for batches. Direct-shear results only (Q178): a file whose loading axis is z is refused, because dividing the horizontal residual of a vertically driven platen by the cross-section yields a small, non-zero, meaningless τ

5.9 Full-surface register

Capability Status Notes
Bond creep extension (shear / twist relaxation)verifiedUse it when the cemented specimen must relax under sustained load (creep of the bonds themselves, not of the grains): viscous-gelled or salted bonds lose shear capacity over time, and a bonded model without creep holds its peaks forever — measured, the difference between the two settings is the entire decay curve
Normal-inelastic bonded contactplannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2); the engine-functor names corrected 2026-11-17 by namespace probe (the originally registered normal-inelasticity Ip2 name does not exist — the real class pairs the InelastCohFrict material with its own phys functor; exact names in the mapping table when this row gets its contract fields). Needs contract fields, DSL mapping and a verified case before it can run
Hertz with linear shear additionplannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Hertz-Mindlin Deresiewicz (full slip)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Hertz + capillary bridge comboplannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Continuum damage mechanics contact (CDM)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Visco-capillary liquid bridgeplannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Viscous friction (Cundall-Strack + dashpot)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Two-sphere simple viscoelastic modelplannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Simplified kinematic contact (L3/L6 geometry family)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Stiffness-scalar contact variant (SCG)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Cable / grid element contacts (cylinder and grid chains)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.
Tetrahedron contact (norm-simple)plannedRegistered 2026-11-16 under the full-surface directive (Q213 gap matrix G2). Needs contract fields, DSL mapping and a verified case before it can run; the engine class list is confirmed by the inventory probe.

6 · Where the rest of it is written down

If you want to know Read
How to install it, why the window will not open, where files goSTART-HERE.md

The four documents below are design notes in the repository, not in this package: they live under 二-桌面端/02-设计/ next to the source, and copying them here would double every edit. Q178: this table used to print the bare paths, so a user who went looking found nothing — the folder is not in the folder they have.

If you want to know Read (in the repository)
Every parameter including the advanced ones, and the form_spec() contract02-设计/05_template规范.md
What each scene field maps to in the engine02-设计/03_engine映射表.md
What a term means in Chinese and English02-设计/07_术语表中英对照.md
What changed, and why, in what order00-交接与进度.md