Resting contact on a pinned cloth table: elastic cube, stacked sheets, fast impact

Vanilla VBD contact (penalty_dat) against the ALM-DAT contact row (alm_dat, with Coulomb friction and gap-rate damping) on three scenes: a dropped elastic cube, four stacked sheets (python -m newton.examples vbd_rest_on_contact), and five sheets falling freely at 1 m/s with no table. Branch ankac/alm-dat-fable-review, snapshot see git plus the example commit, CPU run, Warp 1.17.0, 2026-10-05.

1. Simplest test: an elastic cube dropped on the pinned cloth plane

A 4x4x4 cm tetrahedral cube (density 1 g/cm³, 125 g lumped, k_mu = k_lambda = 1e+05 dyn/cm², no material damping) starts with its bottom face 1 cm above the pinned 16x16 cm cloth table and falls under gravity. Contact settings shared by every scene on this page (margin 0.2 cm, gap 0.1 cm, ke 1e+04, kd 1e+02, mu 0.5), 5 iterations, 10 substeps, 60 fps. Curves are the lowest cube vertex above the table and the largest vertex speed; the dashed line is the margin.

Both paths land and rebound alike. The vanilla path settles within a quarter second and rests one cushion deflection below the margin with sub-micron jitter. The ALM path rests lower because its linear cushion (K = 1e4 dyn/cm per row) is softer than the penalty barrier near the rest point, and it keeps a few cm/s of elastic ringing: the cube has no material damping and the contact damping only acts on closing motion. Before friction and damping were added the ALM cube rested at 0.115 cm with five times the jitter and was still drifting down at 3 s.

2. Stacked sheets: default path versus alm_dat, both with friction 0.5

Left: the shipped behavior, penalty contact with Coulomb friction mu = 0.5, gap-rate damping kd = 100 and per-color Divide-and-Truncate. Right: the ALM contact row with stored division planes, now with Coulomb friction (a tangential multiplier capped at mu times the row's normal force) and gap-rate damping of the closing motion inside the margin. Both stacks land, settle and rest one margin apart; the mean sheet heights agree to 0.002 cm (0.195 / 0.391 / 0.563 / 0.771 versus 0.196 / 0.393 / 0.565 / 0.773 cm), the vertical jitter over the last two seconds is of the same size on both (0.010 to 0.015 versus 0.004 to 0.016 cm), and the largest sheet speed over the last two seconds is 5.4 cm/s on the default path and 8.7 cm/s on alm_dat. No vertex touches the table on either path and the detector's coverage flag stayed true on alm_dat for the whole run.

3. Why friction and damping were needed: the first alm_dat version

Left: the alm_dat row as first rendered, without friction or damping. The slightly rotated sheets slide apart at 20 to 25 cm/s, the first one reaches the 30 cm table edge at 0.85 s and tips over it, and the others follow; once off the table a sheet falls at exactly 76.5 cm/s, the per-substep DAT motion budget. Nothing interpenetrates, it is sliding. Right: the same row with friction and damping.

Friction-matched control: the default path with mu = 0 (left) against the first alm_dat version (right). Both frictionless runs slide off (first sheet vertex below the table surface at 1.12 s versus 0.85 s; peak sliding speed before leaving the table 24.2 versus 27.0 cm/s), so the dispersal was frictionless physics, not a contact-method defect.

Stacked sheets, timeline (max sheet speed [cm/s] / lowest sheet vertex above the table [cm])

Stacked sheets, rest metrics over the last 2 s (mean height [cm] / max vertical std [cm])

Only meaningful for runs whose sheets are still on the table; falling sheets show large negative heights.

4. Free fall: five sheets 2.5 mm apart, all at 100 cm/s, no table

Five sheets start 0.25 cm apart with the same downward velocity of 100 cm/s (3.3 mm per step at dt = 1/300 s, more than their spacing) and fall under gravity with nothing below them. Every sheet should accelerate at g and the spacing should stay 2.5 mm; there is no physical reason for any contact force, so whatever slows the stack is artificial damping of the contact method. The division planes between neighbouring sheets sit at the midpoints (nobody approaches), 1.25 mm below each sheet, while every sheet wants to move 3.3 mm per step: a single truncation round can admit at most 0.85 x 1.25 mm, a second round re-slides the planes with the committed motion and admits the same fraction of the remainder, and so on. Video at 5x slow motion (one simulation step per frame), static camera; margin 0.2 cm, detection gap 3 cm, friction 0.5, damping 100, 5 iterations.

The final truncation count on its own

Same scene, but the alm_dat runs skip the in-iteration plane refresh (--dat-plane-update-interval 0), so the only truncations are the initial one and the 1, 2 or 5 final rounds (--dat-truncation-iterations). With the default refresh (one round after each of the 5 iterations, the row above) every alm_dat run already resolves the whole stack within the step, which is why the three counts were indistinguishable there.

Why the detection gap had to be widened

With the example's default detection gap of 0.1 cm the per-step motion budget 0.5 x 0.85 x (0.2 + 0.1) cm = 1.275 mm caps the committed speed at 38.2 cm/s on both paths, so every run fell at that speed and the truncation rounds could not matter (alm_dat kept the spacing at exactly 2.50 mm; vanilla spread it to 2.47 to 3.97 mm). The variant above widens the gap to 3 cm so the budget (408 cm/s) does not bind during the 0.3 s shown and only the plane truncation acts.

5. Folded sheets: four sheets folded in half, stacked on the table

Result. With the fold construction of the original grid_on_table script, the vanilla path rests and the ALM-DAT path does not: its two middle sheets are squeezed out of the stack sideways within 0.1 s, crumple, and are flung off the table edge at the motion-budget speed. The first sheet vertex below the table surface (0.41 s, sheet 2) is 15.8 cm from the centre, past the 15 cm table edge, so the sheets left the table rather than crossing it. The detector never overflowed. Whether the middle sheets crossed a neighbouring sheet while being squeezed out was not checked. With a clean fold along a mesh column (5b) both paths settle, sheet means within 0.15 cm of each other.

5a. Fold of the original script

Each sheet is folded by reflecting every vertex right of the sheet's world-x mid-line over it and lifting it by a 0.3 cm fold gap (the construction of the original script). Because every sheet is rotated by up to 0.1 rad, the crease cuts across mesh columns: a vertex just right of the line lands just left of it, 0.3 cm up, so the triangles the crease passes through start crushed to a fraction of their rest size. 4 folded sheets start 0.8 cm apart above the pinned table; same contact settings as section 2, 5 s.

5b. The same stack with a clean fold (crease along a mesh column)

Same sheets, same perturbations, same contact settings; the only change is that each sheet is reflected in its own frame, so the crease follows the middle mesh column and no triangle is crushed. Both paths settle to stable heights; on both, a few vertices keep jittering (largest sheet-vertex speed 21 to 27 cm/s over the last 2 s), as on the vanilla run of 5a.

What goes wrong, from a per-substep probe

Verified cause: the motion budget locks fast vertices at the cap speed. ALM-DAT commits at most one budget of displacement per substep: 0.5 x 0.85 x the 0.3 cm detection radius = 0.1275 cm, which at 600 substeps per second is 76.5 cm/s. The crushed crease triangles push 52 vertices further than that in the very first substep. The commit kernel clips each of them to the budget, so their velocity becomes exactly 76.5 cm/s. In the next substep the inertial target of such a vertex is again exactly one budget away. The step-start truncation spends the whole budget on it, and the commit rule used + |step| <= budget then rejects every later correction in that substep: elastic force, contact row, damping and gravity cannot change its path. Only a stored plane can shorten the step. The vertex therefore stays at the cap until it hits a plane; after the plane releases it, the still-crushed crease asks for more than one budget again and it locks again in the new direction. In the default run 50 to 77 vertices are clamped in every one of the 180 probed substeps, and the largest sheet speed reads 76.50 cm/s in all 300 rendered frames.

The vanilla path uses the same 0.1275 cm constant, but twice per substep and as a plain magnitude clamp. Its self-contact schedule is PRE_POST_INIT: it detects at the substep start, clamps the inertial step to 0.1275 cm from there, detects again at the inertial pose and resets the reference, then clamps the VBD corrections to 0.1275 cm from that second pose. So a vanilla vertex may move up to 0.255 cm per substep (153 cm/s), and because the clamp rescales the whole correction vector, a correction that points back against the inertial motion is always admitted: forces can stop a fast vertex inside the substep. ALM-DAT detects once per substep (PRE_INIT, required by the implementation and by the algorithm's single InitialSphericalQuery(x_start)), so one 0.1275 cm budget covers inertia and corrections together, and its path-length rule rejects backward corrections once the budget is spent. The vanilla path relaxes the same crease at up to 129 cm/s, under its 153 cm/s limit, and is quiet after 0.1 s.

Tests. Raising the cap above the crease's natural relaxation speed removes the failure: with a 0.4 cm detection gap (budget 0.255 cm, cap 153 cm/s) 15 vertices are clamped in the first substep and none afterwards; with 40 substeps (cap 306 cm/s) 7 vertex-substeps are clamped in the first three substeps and none afterwards; both stacks settle. Setting every multiplier to zero after each substep changes nothing, so the multiplier memory across substeps is not the cause. A 100x softer ALM metric still fails but calms down later (no clamped vertices by 0.3 s), so the within-substep multiplier overshoot amplifies the loop but does not start it. The clean fold never clamps a vertex. The re-lock loop between plane releases is my reading of the probe; the per-substep lock itself is in the kernel.

Scene

Four 10x10 cm cloth sheets (1 cm cells, 0.02 g/cm², tri_ke = tri_ka = 1e4, edge_ke = 5, absolute damping tri_kd 0.015 and edge_kd 0.05, contact ke 1e4 and kd 100) start 0.5 cm apart above a pinned 30x30 cm cloth sheet that acts as the table, each shifted by up to 0.2 cm and rotated by up to 0.1 rad. The table is cloth with zero mass, so sheet-on-table and sheet-on-sheet contacts both run through the soft self-contact pipeline and the contact method is the only difference between runs. Self-contact margin 0.2 cm, detection gap 0.1 cm, the table itself has no thickness. 60 fps, 10 substeps, 5 VBD iterations, 300 frames.

How it was produced

python -m newton.examples vbd_rest_on_contact
python -m newton.examples vbd_rest_on_contact --contact-method alm_dat
python -m newton.examples vbd_rest_on_contact --contact-mu 0.0
notes/vbd-rest-on-contact/render_comparison.py render --method ... --frames 300   (headless ViewerGL under Xvfb, CPU)
notes/vbd-rest-on-contact/render_comparison.py compose --left penalty_dat --right alm_dat --name comparison
notes/vbd-rest-on-contact/render_comparison.py compose --left penalty_dat_mu0 --right alm_dat --name comparison_frictionless
notes/vbd-rest-on-contact/render_comparison.py render --fold --fold-gap 0.3 --layer-spacing 0.8 --first-layer-height 0.3 --contact-buffer-scale 2 --method ... --tag fold_...
notes/vbd-rest-on-contact/render_comparison.py render --fold --fold-clean ... --tag foldc_...
notes/vbd-rest-on-contact/fold_probe.py --method alm_dat --fold-gap 0.3 --layer-spacing 0.8 --frames 30 [--fold-clean | --no-fold]
notes/vbd-rest-on-contact/plot_fold_speed.py