01Contact models
14 capabilities · Verified 8 / Contract pending 6
Linear spring + Coulomb friction
Verified
Sand
NoteNo 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
Parameter panel5 items
| Parameter | Unit | Range | Calibration | Notes |
| Contact stiffness | MPa | 1 – 5,000 | L1 | Not the material Young's modulus: it is a contact-level equivalent stiffness, to be inverted from the macroscopic modulus |
| Poisson's ratio | — | 0 – 0.49 | L0 | Only splits the normal/tangential stiffness; do not look it up in a handbook as a material Poisson's ratio |
| Inter-particle friction coefficient | — | 0 – 1 | L1 | The internal friction angle of sand depends mainly on it; the same μ with a different preparation method can differ by more than 10° |
| Particle-wall friction coefficient | — | 0 – 1 | L1 | Affects the shear band thickness near the boundary; do not default it to mu_pp |
| Restitution coefficient | — | 0 – 1 | L0 | In quasi-static cases it barely matters; local damping is what actually suppresses kinetic energy |
Engine-layer mapping (not shown in the interface)
FrictMatIp2_FrictMat_FrictMat_FrictPhysLaw2_ScGeom_FrictPhys_CundallStrack
These class names are for developers only; they never appear in the user interface.
Hertz–Mindlin (non-linear elastic)
Verified
Sand
NoteThe 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)
Parameter panel7 items
| Parameter | Unit | Range | Calibration | Notes |
| Contact stiffness | MPa | 1 – 5,000 | L1 | Not the material Young's modulus: it is a contact-level equivalent stiffness, to be inverted from the macroscopic modulus |
| Poisson's ratio | — | 0 – 0.49 | L0 | Only splits the normal/tangential stiffness; do not look it up in a handbook as a material Poisson's ratio |
| Inter-particle friction coefficient | — | 0 – 1 | L1 | The internal friction angle of sand depends mainly on it; the same μ with a different preparation method can differ by more than 10° |
| Particle-wall friction coefficient | — | 0 – 1 | L1 | Affects the shear band thickness near the boundary; do not default it to mu_pp |
| Restitution coefficient | — | 0 – 1 | L0 | In quasi-static cases it barely matters; local damping is what actually suppresses kinetic energy |
| Rolling friction coefficient | — | 0 – 1 | L1 | The main means of simulating angularity with spherical particles; the angle of repose is more sensitive to it than to μ |
| Elastic rolling stiffness | N·m/rad | 0 – 1,000 | L1 | Leave 0 = automatic: derived as kr = kn·R² (bit-for-bit the same convention as the benchmark KROT_WALL); fill it in explicitly only when a calibration overrides it. The engine does not compute krot itself — passing 0 straight through means the moment is always zero (measured my relative error 1.000) |
Engine-layer mapping (not shown in the interface)
FrictMatIp2_FrictMat_FrictMat_MindlinPhysLaw2_ScGeom_MindlinPhys_Mindlin
These class names are for developers only; they never appear in the user interface.
Independent normal/tangential stiffness
Verified
Sand
NoteMeasured on real runs (Q181, 2026-11-12; probes, jobs, .dres pair and results kept in out/evidence/knks-viscoelastic-q181/): two-sphere probes gave the pair stiffness = reciprocal sum of the two bodies' values (5e5 & 5e5 → 2.5e5; 5e5 & 1.5e6 → 3.75e5, both exact; force = kn·overlap) and the end-to-end settle run shows every one of 6 381 contacts at kn = 150 000 exactly — the contract value, no spread (the direct route has no radius dependence). The engine class the old plan named here is a Scholtès-type joint model (per-closure stiffness, tension, brittle length — for rock joints, not sand), so the real route is a linear viscous-elastic material with direct stiffness and zero damping. The self-built kernel implements the same rule natively (its linear spring is the same constitutive law), so this is the only new contact model both engines run. Time step: the Rayleigh estimate derives the modulus from the given stiffness (E = 2·kn/d_mean) — the auto dt follows it, measured. Validation V026 refuses the model/stiffness mismatch in both directions
Parameter panel4 items
| Parameter | Unit | Range | Calibration | Notes |
| Direct normal stiffness | N/m | 0 – 1e+09 | L1 | The pair stiffness between two identical particles — the contact combines the two bodies by the measured reciprocal sum, so the reference equal-radius pair gets exactly this value. No radius dependence: every pair gets the same kn |
| Direct tangential stiffness | N/m | 0 – 1e+09 | L1 | — |
| Inter-particle friction coefficient | — | 0 – 1 | L1 | The internal friction angle of sand depends mainly on it; the same μ with a different preparation method can differ by more than 10° |
| Particle-wall friction coefficient | — | 0 – 1 | L1 | Affects the shear band thickness near the boundary; do not default it to mu_pp |
Why this status
Use 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)
Engine-layer mapping (not shown in the interface)
ViscElMatIp2_ViscElMat_ViscElMat_ViscElPhysLaw2_ScGeom_ViscElPhys_Basic
These class names are for developers only; they never appear in the user interface.
Bonded contact (wet sand / cohesive soil)
Verified
Cemented
NoteMeasured 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)
Parameter panel6 items
| Parameter | Unit | Range | Calibration | Notes |
| Contact stiffness | MPa | 1 – 5,000 | L1 | Not the material Young's modulus: it is a contact-level equivalent stiffness, to be inverted from the macroscopic modulus |
| Poisson's ratio | — | 0 – 0.49 | L0 | Only splits the normal/tangential stiffness; do not look it up in a handbook as a material Poisson's ratio |
| Inter-particle friction coefficient | — | 0 – 1 | L1 | The internal friction angle of sand depends mainly on it; the same μ with a different preparation method can differ by more than 10° |
| Particle-wall friction coefficient | — | 0 – 1 | L1 | Affects the shear band thickness near the boundary; do not default it to mu_pp |
| Contact cohesion | kPa | 0 – 500 | L2 | 0 = cohesionless sand. On the contact phys it lands as a force: normalAdhesion = shearAdhesion = cohesion·R_min² (measured: 50 kPa, R 2–3 mm → 0.20–0.45 N) |
| Rolling bond stiffness | N·m/rad | 0 – 1,000 | L2 | Shared with the Mindlin path. Under bonded it converts once into the engine's dimensionless rolling ratio (the contact gets kr = ratio·ks·R²) — exact at the reference radius R = d_mean/2 |
Engine-layer mapping (not shown in the interface)
CohFrictMatIp2_CohFrictMat_CohFrictMat_CohFrictPhysLaw2_ScGeom6D_CohFrictPhys_CohesionMoment
These class names are for developers only; they never appear in the user interface.
Linear viscoelastic (Kelvin–Voigt)
Verified
Special
NoteMeasured on real runs (Q181, 2026-11-12; probes, jobs, .dres and results kept in out/evidence/knks-viscoelastic-q181/): stiffness stays on the existing young/poisson knobs (measured pair kn = E·R, ks = kn·ν — the same serial rule the kernel's linear law uses, so the numbers carry over); damping is a direct coefficient (mat.cn = 100 → pair cn = 50, force = −50 N at 1 m/s relative velocity, measured exactly; end-to-end settle run: every one of 6 463 contacts at cn = 0.4 exactly, kn spread 1.0–1.5e5 = E·r across the grading). Two measured facts that contradict the old plan: restitution does not derive the damping (en = 0.5 with zero damping stays undamped — the restitution knob remains record-only here), and a material pair with the damping fields left unset aborts the engine in C++ (not catchable), which is why the engine always writes them explicitly. The explicit integrator puts a hard stability ceiling on the dashpot, cn·dt/(2·m_min) ≤ 1: the first evidence run (cn = 50, ratio 6.7) blew the specimen apart — particles at 10.9 km — and the validate rule V028 now refuses the combination before the Run button (it also caught the intermediate cn = 2 attempt, ratio 2.15). The self-built kernel refuses this model (no dashpot) — it is YADE/WSL only. Validation V027 refuses the model/damping mismatch in both directions
Parameter panel6 items
| Parameter | Unit | Range | Calibration | Notes |
| Contact stiffness | MPa | 1 – 5,000 | L1 | Not the material Young's modulus: it is a contact-level equivalent stiffness, to be inverted from the macroscopic modulus |
| Poisson's ratio | — | 0 – 0.49 | L0 | Only splits the normal/tangential stiffness; do not look it up in a handbook as a material Poisson's ratio |
| Inter-particle friction coefficient | — | 0 – 1 | L1 | The internal friction angle of sand depends mainly on it; the same μ with a different preparation method can differ by more than 10° |
| Particle-wall friction coefficient | — | 0 – 1 | L1 | Affects the shear band thickness near the boundary; do not default it to mu_pp |
| Normal viscous damping | N·s/m | 0 – 10,000 | L1 | Viscous force = cn_pair·v_rel. Not the same thing as global local damping: it enters the contact force, the latter only damps velocity |
| Tangential viscous damping | N·s/m | 0 – 10,000 | L1 | — |
Why this status
Impact, 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
Engine-layer mapping (not shown in the interface)
ViscElMatIp2_ViscElMat_ViscElMat_ViscElPhysLaw2_ScGeom_ViscElPhys_Basic
These class names are for developers only; they never appear in the user interface.
Bonded particle model CPM (concrete / rock)
Verified
Cemented
Parameter panel3 items
| Parameter | Unit | Range | Calibration | Notes |
| Crack-onset strain (strength = E×it) | — | 1e-05 – 0.01 | L2 | — |
| Relative ductility (softening span) | — | 1 – 100 | L2 | — |
| Disable damage (elastic reference) | — | — | — | — |
Why this status
Parameter-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
Engine-layer mapping (not shown in the interface)
CpmMatIp2_CpmMat_CpmMat_CpmPhysLaw2_ScGeom_CpmPhys_CpmIp2_FrictMat_CpmMat_FrictPhysLaw2_ScGeom_FrictPhys_CundallStrack
These class names are for developers only; they never appear in the user interface.
Jointed rock JCFpm (intact-rock bond envelope)
Verified
Rock
NoteProbed 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)
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Bond tensile strength | kPa | 0 – 50,000 | L2 | The tension cutoff of the bond break envelope — the bond breaks at min(this, bond_cohesion/tanφ) (measured). Rock: 1–50 MPa |
| Bond cohesion | kPa | 0 – 50,000 | L2 | The shear intercept of the bond's Mohr–Coulomb envelope; also enters the tensile break as c/tanφ — at 0 the bonds break instantly, so both values must be > 0 (measured) |
Engine-layer mapping (not shown in the interface)
JCFpmMatIp2_JCFpmMat_JCFpmMat_JCFpmPhysLaw2_ScGeom_JCFpmPhys_JointedCohesiveFrictionalPMIp2_FrictMat_FrictMat_FrictPhysLaw2_ScGeom_FrictPhys_CundallStrack
These class names are for developers only; they never appear in the user interface.
Capillary liquid bridge (unsaturated sand)
Verified
Water
Parameter panel4 items
| Parameter | Unit | Range | Calibration | Notes |
| Liquid bridge volume (per contact) | m³ | 1e-15 – 1e-09 | L2 | — |
| Surface tension γ | N/m | 0.01 – 0.1 | L0 | — |
| Wetting contact angle (degrees) | — | 0 – 90 | L1 | — |
| Bridge force model | — | — | L2 | — |
Why this status
Parameter-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
Engine-layer mapping (not shown in the interface)
ViscElCapMatIp2_ViscElCapMat_ViscElCapMat_ViscElCapPhysLaw2_ScGeom_ViscElCapPhys_Basic
These class names are for developers only; they never appear in the user interface.
Lubrication force (wet particles / slurry)
Contract pending
Water
Parameter panel3 items
| Parameter | Unit | Range | Calibration | Notes |
| Fluid viscosity | Pa·s | 0.0001 – 10 | L1 | — |
| Surface roughness | — | 0 – 0.1 | L1 | — |
| Max acting gap | ×R | 0 – 100 | L1 | — |
3 contract field(s) still missing to land thiscontact.lubrication.viscositycontact.lubrication.roughnesscontact.lubrication.gap_max
Why this status
Probed 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
Engine-layer mapping (not shown in the interface)
FrictMatIp2_FrictMat_FrictMat_LubricationPhysLaw2_ScGeom_ImplicitLubricationPhys
These class names are for developers only; they never appear in the user interface.
Polyhedral particle
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
PolyhedraMatIp2_PolyhedraMat_PolyhedraMat_PolyhedraPhys
These class names are for developers only; they never appear in the user interface.
Mortar contact
Contract pending
Cemented
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
MortarMatIp2_MortarMat_MortarMat_MortarPhys
These class names are for developers only; they never appear in the user interface.
Bubble / foam
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
BubbleMatIp2_BubbleMat_BubbleMat_BubblePhys
These class names are for developers only; they never appear in the user interface.
Luding contact (with hysteresis)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
LudingMatIp2_LudingMat_LudingMat_LudingPhys
These class names are for developers only; they never appear in the user interface.
Unsaturated soil (suction)
Contract pending
Water
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
PartialSatMatIp2_PartialSatMat_PartialSatMat_MindlinPhys
These class names are for developers only; they never appear in the user interface.
03Geometry modelling
10 capabilities · Verified 5 / Contract pending 5
Box (block)
Verified
Geometry
Noterole=container compiles into six walls (faces may be open); role=fill compiles into a fill domain
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Centre | mm | — | — | — |
| Full edge lengths | mm | 1 – 5,000 | — | Full length, not half length: the contract uses full length and divides by 2 only when compiling to walls (that one place) |
Cylinder (block)
Verified
Geometry
NoteThe 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)
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Radius | mm | 0.5 – 2,000 | — | — |
| Height | mm | 0.5 – 5,000 | — | — |
Swept profile (extrude)
Verified
Geometry
NoteThe 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)
Parameter panel3 items
| Parameter | Unit | Range | Calibration | Notes |
| Profile polygon | mm | — | — | Local 2D point list; concave polygons allowed (L-shaped retaining walls), the volume is computed from the signed area |
| Extrusion axis | — | — | — | — |
| Extrusion length | mm | 0.5 – 5,000 | — | — |
Boolean excavation (cut)
Verified
Geometry
NoteFoundation 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
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Boolean operation | — | — | — | target is carved away by tool; the carved block does not become a domain of its own, it only exists as a hole |
Excavation during the run (construction stage)
Verified
Geometry
NoteThe 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)
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Excavation time | s | 0 – — | — | Empty = excavate at build time (initial cut); a value = delete particles once the solve phase reaches that moment |
Arbitrary polyhedron (vertices + faces)
Contract pending
Geometry
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
The 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)
Contract pending
Geometry
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Unioning 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)
Contract pending
Geometry
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Layered 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)
Contract pending
Geometry
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Real 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)
Contract pending
Geometry
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
A 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)
05Loading & servo
6 capabilities · Verified 6
Displacement loading (constant-rate push)
Verified
Loading
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Loading rate | m/s | 1e-05 – 0.1 | — | Too fast = inertial effects pollute the strength; the criterion is the quasi-static number I = rate·√(ρ/E)/σ |
| Target displacement | mm | 0.1 – 100 | — | — |
Strain loading (normalised by specimen height)
Verified
Loading
NoteTriaxial uses it: displacement divided by the current specimen height, not the initial height (a big difference under large deformation)
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Axial strain rate | 1/s | 0.0001 – 1 | — | — |
| Target strain | — | 0.001 – 1 | — | — |
Constant-stress servo (axial / normal)
Verified
Loading
NoteA second channel parallel to the main drive, not a fourth LoadMode; on the same wall group each controls one component
Parameter panel3 items
| Parameter | Unit | Range | Calibration | Notes |
| Target stress | kPa | 1 – 5,000 | — | — |
| Servo gain | — | 0.01 – 2 | — | Estimated online from the measured stiffness; too large oscillates, too small cannot catch up |
| Pre-load duration | s | 0 – 10 | — | Must be long enough: unloading is hysteretic, overshoot does not come back (Q21 measured 0.4 s returns only half). From contract v2.0 it becomes "main drive t_start" + "servo ramp", but the UI still shows this one cell |
Constant-stress servo (radial / confining)
Verified
Loading
NoteOn 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
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Confining stress | kPa | 1 – 5,000 | — | — |
Drum lift (formwork removal)
Verified
Loading
NoteThe pile-angle case uses it; the drum is a friction boundary, lifting too fast drags the specimen up
Parameter panel2 items
| Parameter | Unit | Range | Calibration | Notes |
| Lift velocity | m/s | 0.0001 – 0.1 | — | — |
| Lift distance | m | 0.001 – 0.2 | — | — |
Constant-stress creep
Verified
Loading
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
A 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)
06Solver components
4 capabilities · Verified 2 / Contract pending 2
Time integration (translation + rotation + local damping)
Verified
Solver
NoteRotation 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)
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Local damping | — | 0 – 0.9 | — | Quasi-static work relies on it to suppress kinetic energy; 0.7 is a common starting point, do not confuse it with contact damping |
Engine-layer mapping (not shown in the interface)
NewtonIntegrator
These class names are for developers only; they never appear in the user interface.
Automatic time step (Rayleigh criterion)
Verified
Solver
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Time step | s | 1e-09 – 0.01 | — | Auto = Rayleigh critical × safety factor 0.6; written into .dres/meta, must be carried along when reproducing |
CFD–DEM coupling (fluid)
Contract pending
Solver
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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)
Engine-layer mapping (not shown in the interface)
FlowEngine
These class names are for developers only; they never appear in the user interface.
YADE's built-in triaxial engine
Contract pending
Solver
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Re-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
Engine-layer mapping (not shown in the interface)
TriaxialCompressionEngine
These class names are for developers only; they never appear in the user interface.
07Command stream & extensions
6 capabilities · Verified 6
Command stream (Python form)
Verified
Command stream & extensions
Notedem/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)
No parameters: the contract fields are not defined yet, the panel is pending.
Short-command form (one per line)
Verified
Command stream & extensions
NoteAnother layout of the same command sequence (render_short / parse_short) — for people to copy, for external tools to read; not a second semantics
No parameters: the contract fields are not defined yet, the panel is pending.
Operation recording (UI → command stream)
Verified
Command stream & extensions
Notefrom_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
No parameters: the contract fields are not defined yet, the panel is pending.
Parameter sweep / batch submission
Verified
Command stream & extensions
NoteA job list + one summary table; Monte Carlo slopes and μ sensitivity analyses rely on it. The loop is closed end-to-end: dem/sweep.write_jobs() emits the job JSON, and the desktop Jobs panel (Solve › Jobs…) discovers out/jobs/*.json and runs them — locally through the reference kernel (no WSL: ≤150 grains and ≤4 000 steps, the same two ceilings KernelEngine refuses on) or through YADE/WSL via the same JobRunner the single Run button uses — then opens the resulting .dres.
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Verified: 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)
Verified
Command stream & extensions
NoteThe original plan — replace the contact law with a user-written law functor — was measured impossible on 2022.01a (a pure-Python law functor is not dispatchable: the C++ dispatcher demands functor-class type declarations; and overriding go on a concrete functor subclass is silently ignored while the base C++ law keeps running). The contract therefore landed as an additive per-iteration Python callback: validate V035 checks the reference resolves, the local kernel refuses the field
Parameter panel1 items
| Parameter | Unit | Range | Calibration | Notes |
| Custom force hook | — | — | — | A .py file path (relative = case directory, must define def hook():) or module.path:attribute; called once per iteration after the contact law and adds forces/moments on top of it — never replaces it |
Why this status
Verified 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)
Verified
Command stream & extensions
Notedem/ui/console_panel.py: a QPlainTextEdit REPL that preloads from dem.scene import *, executes input with captured stdout, repr's the last top-level expression, shows the traceback on error, optionally runs a %%dsl cell (defensive, skipped when dem.dsl.parse is absent), and emits sceneBuilt(SceneDesc) on 'Send to editor'.
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Covered 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.
08Results & analysis
2 capabilities · Verified 2
Direct-shear peak / residual strength
Verified
Results & analysis
Noteτ = 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
No parameters: the contract fields are not defined yet, the panel is pending.
Mohr–Coulomb envelope (c, φ)
Verified
Results & analysis
NoteAcross 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 τ
No parameters: the contract fields are not defined yet, the panel is pending.
09Full-surface register
13 capabilities · Verified 1 / Contract pending 12
Bond creep extension (shear / twist relaxation)
Verified
Cemented
NoteMeasured on real runs (Q215, 2026-11-17; probe scripts and outputs kept in out/evidence/bond-creep-q215/): two bonded R=5 mm spheres, sheared at constant velocity then held — with shear_creep on and viscosity 10 the shear force −0.0260 → −0.0122 → −0.0058 N over 0/500/1 000 hold steps (mid/start 0.47; the engine source's exponential predicts 0.47 exactly), viscosity 100 ten times slower, off → no decay; with twist_creep on (geometry-side creep bookkeeping wired) and viscosity 100 the twist moment −6.40e-5 → −2.88e-5 → −1.30e-5 N·m (mid/start 0.451, formula 0.45). Three probe-verified facts the register had to absorb: ① the name this row carried at registration is a dead legacy alias — calling it raises KeyError in the engine namespace; the real class is the same bond law the verified cohesion capability rides on, so this row is that law's creep switch surface, not a separate law (the exact engine names live in the mapping table); ② the twist creep is subtracted on the GEOMETRY side — the sphere-pair geometry functor's own creep flag defaults to False and silently discards the law's creep bookkeeping unless the engine sets it (measured: flag off → the moment never decays); ③ twist_creep together with the law's incremental rotation form aborts in C++ (probe abort_case.py) — the engine keeps the plain rotation form, and the mapping table documents why it must stay that way. The kernel refuses the whole bonded route, so this is YADE-only (validate V038)
Parameter panel3 items
| Parameter | Unit | Range | Calibration | Notes |
| Shear creep | — | 0 – 1 | L2 | The bond's stored shear force relaxes exponentially: Fs(t) = Fs0·exp(−ks·t/creep_viscosity). Measured 2026-11-17 at ks 1.5e4 N/m: viscosity 10 halves the force in ~0.47 ms, viscosity 100 ten times slower, off → the force never decays |
| Twist creep | — | 0 – 1 | L2 | The bond's twist ANGLE relaxes (the moment follows). Needs the geometry-side creep bookkeeping (the engine wires Ig2 creep=True) and forbids the law's incremental rotation form — measured C++ abort; the engine never uses that form |
| Creep viscosity | N·s/m | 0 – 1e+12 | L2 | The relaxation clock of both switches. The shear branch divides ks·dt by it, the twist branch folds in (2·R_min)²/16 — YADE shares one number across two dimensionally different branches, stated rather than hidden. Required > 0 when a switch is on (V038) |
Why this status
Use 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
Engine-layer mapping (not shown in the interface)
CohFrictMatIp2_CohFrictMat_CohFrictMat_CohFrictPhysLaw2_ScGeom6D_CohFrictPhys_CohesionMoment
These class names are for developers only; they never appear in the user interface.
Normal-inelastic bonded contact
Contract pending
Cemented
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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
Engine-layer mapping (not shown in the interface)
InelastCohFrictMatIp2_2xInelastCohFrictMat_InelastCohFrictPhysLaw2_ScGeom6D_InelastCohFrictPhys_CohesionMoment
These class names are for developers only; they never appear in the user interface.
Hertz with linear shear addition
Contract pending
Sand
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Law2_ScGeom_MindlinPhys_HertzWithLinearShear
These class names are for developers only; they never appear in the user interface.
Hertz-Mindlin Deresiewicz (full slip)
Contract pending
Sand
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Law2_ScGeom_MindlinPhys_MindlinDeresiewitz
These class names are for developers only; they never appear in the user interface.
Hertz + capillary bridge combo
Contract pending
Water
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Ip2_FrictMat_FrictMat_MindlinCapillaryPhysLaw2_ScGeom_CapillaryPhys_Capillarity
These class names are for developers only; they never appear in the user interface.
Continuum damage mechanics contact (CDM)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Ip2_FrictMat_FrictMatCDM_MindlinPhysCDMLaw2_ScGeom_MindlinPhysCDM_HertzMindlinCDM
These class names are for developers only; they never appear in the user interface.
Visco-capillary liquid bridge
Contract pending
Water
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
ViscElCapMatIp2_ViscElCapMat_ViscElCapMat_ViscElCapPhysLaw2_ScGeom_ViscElCapPhys_Basic
These class names are for developers only; they never appear in the user interface.
Viscous friction (Cundall-Strack + dashpot)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
FrictViscoMatIp2_FrictViscoMat_FrictViscoMat_FrictViscoPhysLaw2_ScGeom_FrictViscoPhys_CundallStrackVisco
These class names are for developers only; they never appear in the user interface.
Two-sphere simple viscoelastic model
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
SimpleViscoelasticMatLaw2_Spheres_Viscoelastic_SimpleViscoelastic
These class names are for developers only; they never appear in the user interface.
Simplified kinematic contact (L3/L6 geometry family)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
ElastMatElasticMatGranularMatLaw2_L3Geom_FrictPhys_ElPerfPlLaw2_L6Geom_FrictPhys_Linear
These class names are for developers only; they never appear in the user interface.
Stiffness-scalar contact variant (SCG)
Contract pending
Sand
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Law2_SCG_KnKsPhys_KnKsLaw
These class names are for developers only; they never appear in the user interface.
Cable / grid element contacts (cylinder and grid chains)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Law2_CylScGeom6D_CohFrictPhys_CohesionMomentLaw2_GridCoGridCoGeom_FrictPhys_CundallStrackLaw2_ChCylGeom6D_CohFrictPhys_CohesionMoment
These class names are for developers only; they never appear in the user interface.
Tetrahedron contact (norm-simple)
Contract pending
Special
No parameters: the contract fields are not defined yet, the panel is pending.
Why this status
Registered 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.
Engine-layer mapping (not shown in the interface)
Law2_TTetraSimpleGeom_NormPhys_SimpleIp2_ElastMat_ElastMat_NormPhys
These class names are for developers only; they never appear in the user interface.