Known limits¶
Every known limit of the Alloy physics engine, grouped by area: what goes wrong, how large it is and what to do instead today. The one-line list is Keep in mind.
Compile, memory and speed¶
- An interrupted first compile can damage the kernel cache: later runs then fail with a
JSONDecodeErroror an nvJitLink error. Delete the folder~/.cache/warpand build again. env.close()does not free GPU memory, so a larger environment built later in the same process can step many times slower with no error. Use one environment size per process, or start a new process.- A robot, a cable and cloth together in one scene can force a very small coupled step, and the scene then steps
very slowly. Run
alloy.estimate(scene, worlds, seconds)before you build.
Rigid bodies and contact¶
A fast small body passes through a thin static part¶
What is wrong
Rigid contact has no swept test. A body that travels about its own size in one rigid step meets a thin part already overlapping it, and the contact cannot stop it: it comes out of the far side. A 2 cm steel ball dropped on a static 1 cm plate lands from 4 m (8.9 m/s) and passes through from 5 m (9.9 m/s). Below that speed the ball lands, but dips into the plate first, by more than the travel of one step. Thin moving parts pass at much less travel: coins and pins 2-6 mm thick went through a 5 mm pane at 3.8 mm per step, and a pin of radius 1.5 mm at 1.4 mm per step, so no single travel per step is safe for every part (second table).
Since this page was written the build warns and health flags it (below); the pass-through itself is not fixed.
Number
Steel ball on a static plate 0.3 m above the ground, Scene(dt=0.01) (rigid step 1.25 ms), CPU, MuJoCo C route,
main ba2713ec0. The ball's speed is swept in 0.25-1 m/s steps at two or three start offsets within one step's
travel; "passes from" is the travel per rigid step (speed x step) at the first speed that passes. One run per
case (the CPU repeats bit for bit). Probe and rows: development notes, not shipped.
| ball radius | plate | passes from (speed at 1.25 ms) | travel per step there |
|---|---|---|---|
| 10 mm | 2 mm | 6.5 m/s | 8.1 mm |
| 10 mm | 5 mm | 7.5 m/s | 9.4 mm |
| 10 mm | 10 mm | 9.0 m/s (8.5-9.5 over start offsets) | 10.6-11.9 mm |
| 10 mm | 20 mm | 11.5 m/s | 14.4 mm |
| 10 mm | 40 mm | 18.0-18.5 m/s | 22.5-23.1 mm |
| 5 mm | 10 mm | 6.0-6.5 m/s | 7.5-8.1 mm |
| 25 mm | 10 mm | 13.0 m/s | 16.2 mm |
- Above the first passing speed the ball passed in 207 of 207 cases started with a speed and in all but 1 of 81 drops.
- The rigid step: the same travel per step (10.6-11.2 mm, 10 mm ball and plate) at 2.5, 1.25 and 0.625 ms, so the
passing speed doubles when the step halves (4.5, 9.0, 17.5 m/s); at 0.3125 ms it is 25 m/s (7.5-8.1 mm).
Scene(dt=...)of 5, 10 or 20 ms does not change the rigid step (1.25 ms in all);scene.rigid_stepdoes, and so does adtof 1 ms or less. - A 5 cm cube (125 g) is not monotone: on the 10 mm plate it first passes at 15.5-18 m/s (19-23 mm per step), lands again between 16 and 18 m/s at one start offset, and passes at every speed from 18.5 m/s.
- A landing ball still dips: at 5 / 7 / 8.5 m/s its lowest point goes 8.4 / 11.1 / 14.0 mm below the plate's top face (the plate is 10 mm thick) before it is pushed back out. On the ground plane alone it never passes, and dips 1.2 to 1.9 x the travel per step, by where in a step it meets the plane: 9 mm at 6 m/s, 16 mm at 10 m/s, 31 mm at 19 m/s when started with that speed; 25.6 and 26.8 mm in drops from 6 and 8 m (10.8 and 12.5 m/s).
profile="precision"and the CPU's MuJoCo Warp route (ALLOY_CPU_ROUTE=warp, the GPU's code; 1 m/s grid) give the same 9 m/s. One L4, 1,024 worlds: the same drops pass (5 m and up) and land (4 m).- The contact gap (5 mm; a robot's
contact_gap=) does not change any of this: gaps of 5, 10, 20 and 40 mm gave the same rows to the last digit.
Thin parts onto a thin pane: a static glass pane 5 mm thick, parts dropped from 1.0 m (4.4-4.6 m/s) or 7.7 m
(12.3-12.4 m/s) with scene.rigid_step pinned (0.3125 ms in the last column), 32 worlds per cell, one L4 (MuJoCo
Warp), alloy 0.1.0 (rc6-1110); each cell counts the worlds that read TUNNEL. Probes: development
probes (probe3.py and its log), not shipped.
| moving part (thinnest size) | 3.8 mm per step (12.3 m/s, 0.3125 ms) | 1.9 mm (12.3 m/s, 0.156 ms) | 1.4 mm (4.5 m/s) |
|---|---|---|---|
| ball, radius 5 mm (10 mm) | 0 of 32 | ||
| cube 10 mm | 0 of 32 (7 INVALID, no TUNNEL) | ||
| ball, radius 3 mm (6 mm) | 7 of 32 | ||
| capsule, radius 3 mm, lying flat (6 mm) | 32 of 32 | 0 of 32 | 0 of 32 |
| coin 4 mm thick, radius 12 mm, flat | 32 of 32 | 0 of 32 | 0 of 32 |
| coin 2 mm thick, flat (tilted 12 degrees) | 32 of 32 (32 of 32) | 0 of 32 (16 INVALID, no TUNNEL) | 0 of 32 |
| capsule, radius 1.5 mm, flat (upright) | 32 of 32 (32 of 32) | 32 of 32 | 19 of 32 |
- At the default 1.25 ms step (5.7 mm per step at 4.5 m/s) all four thin parts passed in 32 of 32 worlds, with FAST_CONTACT seen in every world; at the pinned steps FAST_CONTACT never showed and the build did not warn.
- The sample scene (a 4 mm coin tilted 12 degrees, a radius 3 mm capsule lying across and a radius 5 mm ball on the same pane) held from 4.4-4.85 m/s at 0.3125 ms (1.4-1.5 mm per step): no TUNNEL and no INVALID world in 2,048 (a development sample, not shipped).
- A smaller pinned step did not do worse when re-run: the sample scene (run.py, 256 worlds, 12.2-12.4 m/s) read TUNNEL in 256 of 256 worlds at 0.3125 ms (3.8 mm per step) and was OK in 256 of 256 at 0.156 and 0.078 ms on one L4 (main 3beb7251c; the 0.078 ms row also on rc6-1110), and in 8 of 8 at 0.078 ms on the CPU (MuJoCo C and the Warp path; development notes, not shipped). So on this scene 1.9 mm per step, about half the 4 mm coin, held.
Why
MuJoCo's contacts are soft and are found from where the bodies are at each step, with no test of the path between steps. A contact pushes a body out along the shortest way; once the body's centre is past the middle of a thin part, that way is the far side. The 5 mm contact gap only lists the pair early: no force acts until the surfaces overlap (measured: gaps of 5 to 40 mm change nothing).
What Alloy does about it
- Build warning: when a body's start drop makes it travel more than 5 mm per rigid step onto a static part thinner
than twice that travel,
alloy.buildwarns once, naming the body, the part's thickness, the speed, the travel per step and three fixes with numbers (a rigid step, a lower drop, a thicker part).alloy.estimate(...)["rigid_step"]["warnings"]has the same text. Both bounds are below every passing case in the first table (the lowest pass is 7.5 mm per step; every pass has twice its travel above the plate's thickness), but not below the thin-part cases: parts 2-6 mm thick passed at 1.4-3.8 mm per step with no warning and noFAST_CONTACT, and onlyTUNNELcaught them. It reads start drops only: a body thrown, pushed or accelerated during the run gets no build warning, and neither does a drop onto the ground or a thick part. - Health:
FAST_CONTACT(DEGRADED while it happens) when a body moves more than 5 mm toward a static shape in one rigid step, the shape is thinner along the approach than twice that travel, and the body ends within 5 mm of it;TUNNEL(INVALID: the world is frozen,sim.check()names the body and the part,profile="precision"raises at the check) when a point inside a body enters a static shape and leaves through the opposite side (or, from 2 mm deep, through any side but the one it entered by), or the whole body ends inside one (a ball about 2 cm or more under the ground plane).docs/guide/health.md. On one L4 the check cost about 4 % of a 1,024-world run (3 runs each way, inside their spread). FAST_CONTACTshows for 64 rigid steps after the approach (80 ms at 1.25 ms) and then clears: readsim.health()during the run, since a read at the end shows no trace of it. Underprofile="fast"(checks every 10 exchanges) a scene with more than 6 rigid steps per exchange can miss it.TUNNELstays.
Not covered
- The flags follow points inside each moving body's shapes (the centre and, for a capsule, cylinder or long box,
two points on its long axis) against static boxes, planes, spheres, capsules, cylinders and static convex meshes
that fill their bounding box (a plate or block given as a mesh). A robot link that swings through a static
plate reads
TUNNEL. A part of a body that passes between those points (a corner of a wide box clipping a thin static edge) is not seen. - The points sit inside the moving body (a box's axis points half its thinnest edge from its faces), so a thin moving part (a 0.8 mm card, a 2 mm plate) that leaves a static part by another side is caught only once its surface is about half its thickness plus 2 mm inside: past PEN_WARN (1 mm) anyway.
- A static box counts as passed only through its thickness: a point that slides along one of its faces while a little inside it (a thin latch tab under a 1.4 mm port roof, in by the front face and out by the back) is not a pass, and neither is a point that moves inside a thin wall along its plane (the penetration flags see how deep it is).
- Not judged, by name; each of these passes with no flag today:
- a ball through a thin free (not static) plate resting on supports: two moving bodies;
- two balls closing at 20-30 m/s that swap sides: two moving bodies;
- a kinematic paddle driven at 16-20 m/s through a resting ball: a kinematic object;
- a static mesh that is not a filled box (a concave mesh, a decomposed part, a thin shell).
- A fast body that lands near a part's edge can be pushed out sideways by the contact (45 mm past a plate's edge in
one of 16 worlds of a 15 m/s drop) and fall on: it went round the part, not through it, so no
TUNNEL; the build warns for such a start drop. - A cable dropped across the edge of a plate can end lying partly under it without passing through it (it is
dragged round the edge by its hanging half): that reads no
TUNNEL, rightly. - The flags watch simulations made by
alloy.build/alloy.load. The bench harness's direct stepping (alloy.bullyDirectSim on the MuJoCo C route) is not watched. - Fast bodies still pass through; the run is flagged, not corrected.
Workaround
No travel per step is safe for every part: the bound depends on the thinner of the two parts (moving or static), its
shape and how it meets the other (a 10 mm ball held at 3.8 mm per step on a 5 mm pane; a capsule of radius 1.5 mm
passed in 19 of 32 worlds at 1.4 mm). To lower the risk, step rigid bodies finer with scene.rigid_step (a rigid-only
scene; at 0.3125 ms the 4-12 m ball drops above all land) or alloy.Scene(dt=0.0003) in a scene with robots, slow the
body, or make the parts thicker. Then measure your own part at your speed: run it in many worlds and read
sim.check(), where TUNNEL (INVALID) names each world a body passed in. The build warning and FAST_CONTACT fire
only above 5 mm per step, so they do not cover thin parts.
Fix
Not small: making contacts act before the surfaces meet (a contact margin of about the travel per step) stops the pass-through in a probe (a 10 / 20 / 40 mm margin moved the passing travel to 18.8 / 26-27.5 / 39-41 mm) but bodies then rest that margin above their support. The planned fix is the rigid step following the speed (sub-steps while a body's travel per step is above the cap), with its own laws. The alternative on the contact side, also not small: a speculative normal row on listed pairs that are still apart, which stops only the approach that would overlap within the step and is idle at rest.
A box sliding at metres per second hops and rocks¶
What is wrong
A box on MuJoCo's soft contact that slides fast lifts off its support and rocks, more the faster it slides. Its
slide keeps the Coulomb rate. A cube pushed along the floor to about 2.5 m/s rises a few millimetres and pitches by
1-2 degrees peak to peak (a small cube by up to 7 degrees), where a rigid one would stay flat. A low, wide box
slides flat. Slow slides (the light-box law tests/contact/test_light_sliding_tip.py, up to 1.6 m/s) stay within
0.1 mm.
Number
Cubes (1,000 kg/m3) on the ground (mu 0.5), settled, then pushed at their centre by 1.5 mu m g, so they reach about 2.5 m/s in 1 s. CPU, main 132d4450f (free bodies on rk4), the same to the last digit as release-1109; measured with A development probe (2026-11-09, not shipped):
| run | rise by 1 s (2.5 m/s) | pitch, peak to peak | slide / 0.5 mu g |
|---|---|---|---|
| 0.3 m cube, rigid step "auto" (5 ms here) | 3.4 mm | 1.2 deg | 0.998 |
| 0.3 m cube, step pinned at 1.25 / 10 ms | 9.0 / 1.9 mm | 1.4 / 1.5 deg | 0.995 / 1.000 |
| 0.1 m cube, "auto" | 4.1 mm | 2.4 deg | 0.998 |
| 0.05 m cube, "auto" | 2.2 mm | 7.4 deg | 0.999 |
| 0.3 m cube, MuJoCo C alone, stock solref (0.02, 1), elliptic, 5 ms | 16.6 mm | 1-2 deg | - |
| 0.3 m cube, MuJoCo C alone, stock, pyramidal, 5 ms | 94 mm at 4 m/s | 20 deg | - |
A 40 x 40 x 10 cm box pushed the same way slides flat: 0.24 deg peak to peak, 0.25 mm.
Why
MuJoCo's soft friction rows ask for a reference acceleration of about -b v_slip, with b = 2 / (dmax tau). It grows with the sliding speed, and the friction cone couples it into the normal rows, so a sliding face is pushed off its support step by step (contact-light-sliding-tip.md has the same mechanism at a short time constant). A box also feels the friction's moment about its centre, mu N h / 2: the leading edge digs in and the box rocks on its corners, and a small one rocks more. Raw MuJoCo C does it at its stock gains, on both cones and at 1.25 and 5 ms; stiffer, less damped contacts are worse (solref 0.01, 0.7 tumbled it).
Workaround
- Slide fast things on wide bases, or slowly: the 0.3 m cube rose 0.2 mm by 1 m/s.
- A finer rigid step does not help: at 1.25 ms the 0.3 m cube rose 9 mm, against 3.4 mm at "auto"'s 5 ms.
- Read the slide's position and speed, which keep the Coulomb rate, not its height.
Planned fix
None scheduled. Candidate: a longer friction time constant (solreffriction). It holds a light sliding box flat (contact-light-sliding-tip.md), but stiction creep grows with it, so a law for fast slides comes first.
A body on collision="sdf" or "mesh" contacts never fully rests, and under 40 g or from 40 kg it fails¶
What is wrong
A scene with an add_mesh(..., collision="sdf") or "mesh" shape is collided by Newton's contact pipeline instead of
MuJoCo's own (alloy.build's contacts="auto"; contacts="newton" asks for it by hand). A rigid body in such a
scene behaves in one of three ways, set by its mass:
- Under about 40 g it is thrown off. The world goes INVALID (ENERGY_JUMP), but not always at once: the body can
first bounce up to 64 mm above the height it was dropped from, for up to 2 s, with health still OK. Do not trust a
light body on these contacts before sim.check()["ok"] has been read at the end of the run.
- From about 40 g to 35 kg it settles but never fully rests. It ends within 0.25 mm of its rest height with
health OK, and keeps vibrating by 0.01 to 0.3 mm. sim.state() shows a speed of 2 to 25 mm/s that never reaches
zero. With collision="convex" the same body is at rest to the last digit.
- From about 40 kg it sinks in. The world goes INVALID (PEN_FAIL) at the first contact, about 9 mm deep.
A static sdf or mesh part that only liquid touches is not affected (a mesh cup holds its liquid).
Until 2026-11-09 these bodies also gained energy at each bounce and never came to rest, with health OK: free bodies
stepped on rk4, whose four stages saw the pipeline's once-per-step contacts frozen. That is fixed (law:
tests/contact/test_newton_contacts_rest.py); this page is what is left.
Number
A cube of 12 triangles, collision="sdf", dropped 1 cm onto the ground; dt=0.01 (rigid step 1.25 ms), 1 world,
CPU (MuJoCo Warp route), 5 s, main 105c33f6c with the fixed rigid step these scenes keep. Edges from 2 cm to 1 m at
densities from 50 to 8,000 kg/m3 (53 cases): the behaviour follows the mass, not the size. "Vibration" is the height's
range and the largest speed over the last second. "At rest" would be a speed under 1 mm/s: no case reaches it.
| mass (edge) | end height - rest | vibration | health |
|---|---|---|---|
| 0.4 g to 8 g (2 to 5 cm) | - | - | INVALID (ENERGY_JUMP) within 0.1 s |
| 13.5 g (3 cm) | rose 23 mm above its drop | - | INVALID after 0.3 s |
| 20 g (10 cm) / 25 g (5 cm) | rose 26 / 6 mm above its drop | - | INVALID after 0.7 s |
| 27 g / 30 g (3 cm) | rose 19 / 11 mm above its drop | - | INVALID after 2.0 / 1.9 s |
| 35 g (10 cm) | rose 64 mm above its drop | - | INVALID after 1.4 s |
| 40 g (3 cm, 10 cm) | 0.00 mm | 0.010 mm, 8 mm/s | OK |
| 50 g (2 cm / 10 cm) | 0.00 / -0.01 mm | 0.003 mm, 4 mm/s / 0.057 mm, 25 mm/s | OK |
| 62 g to 73 g (2 to 5 cm) | 0.00 mm | 0.03-0.05 mm, 15-19 mm/s | OK |
| 0.125 kg to 0.5 kg (3 to 20 cm) | -0.03 to 0.00 mm | 0.000-0.024 mm, 2-7 mm/s | OK |
| 1 kg / 2.7 kg (10 cm) | -0.01 / -0.04 mm | 0.018 / 0.042 mm, 7 mm/s | OK |
| 5 kg (10 cm) / 8 kg (20 cm) | -0.11 / 0.00 mm | 0.12 / 0.10 mm, 15 / 8 mm/s | OK |
| 20 kg (20 cm) / 25 kg (50 cm) | -0.07 / -0.09 mm | 0.18 / 0.20 mm, 8 mm/s | OK (PEN_WARN at first contact) |
| 30 kg / 35 kg (20, 50 cm) | -0.23 / -0.21 mm | 0.25 / 0.27 mm, 9 mm/s | OK (PEN_WARN at first contact) |
| 40 kg (20 cm) to 8,000 kg (1 m) | about 9 mm deep | - | INVALID (PEN_FAIL) within 0.1 s |
collision="mesh"gives the same rows as"sdf"(checked at 27 g, 0.5 kg, 5 kg, 20 kg and 125 kg).- A 0.5 kg, 10 cm cube on a static box: 149.993 of 150 mm, 0.014 mm, 5 mm/s. A 4 cm, 0.1 kg
add_boxon a static sdf or mesh cube: 119.998 of 120 mm, 0.027 mm, 18 mm/s. A 4 cm, 50 g ball on a static sdf slab: 120.003 of 120 mm, 0.011 mm, 9 mm/s. One L4 gives the same heights within 0.02 mm, and vibrations of 0.015-0.048 mm at 5-15 mm/s. - Finely meshed flat faces do rest: a 0.5 kg cube of 768 triangles (sdf or mesh) ends at 50.000 mm with no vibration, on the CPU and on an L4. A 10 cm sphere of 1,280 triangles ends 0.14 mm low and moves 0.11 mm at 38 mm/s.
- The heavy limit is for a 1 cm drop (0.44 m/s at contact). A higher drop lowers it: a 1 m, 100 kg cube dropped 5 cm goes INVALID too, where the same cube as a convex hull rests 0.43 mm deep with health OK.
- A smaller
dtdoes not rescue a light body: a 5 g, 2 cm cube also fails atdt=0.002anddt=0.004. - No row that stays valid rises above its drop height.
Why
On this pipeline a contact row takes the pair table's stiffness and damping (2 MN/m per material, damping from the pair's restitution) instead of the gains MuJoCo's own contacts get, which are sized for the body's mass and the step. - The damping is light (a damping ratio of 0.11 for the default pair). At a 1.25 ms step gravity alone changes the speed by 12 mm/s per step, so the body leaves the contact for one step in about nine and is caught again: a steady cycle instead of rest. - The stiffness is one number for every mass. On a body under about 40 g it is too stiff for the step, and the contact goes unstable; how soon the energy check catches it depends on how the first bounces fall. On a body of 40 kg it is too soft (the solver's soft contact acts on many times the body's mass), so the body sinks a centimetre before it stops. - These scenes keep the fixed rigid step. The coarser steps a rigid-only scene may otherwise take are sized for MuJoCo's own gains: at the 5 and 10 ms the planner would pick, a 5 kg cube vibrated by 1.0 mm at 87 mm/s and a 20 kg one by 2.5 mm at 116 mm/s with PEN_WARN.
With these rows on the geoms' own gains (a probe, not shipped) the 0.5 kg cube on the ground and on the box, the box on the static cube and the ball on the slab all rest exactly (no vibration), and the 5 g cube rests too. The 100 kg cube still sinks 1 cm at its first contact: rows on this pipeline start only once the surfaces overlap.
Workaround
- Use
collision="convex"for a solid, roughly convex part and"decompose"for a concave one that moves: both collide on MuJoCo's own contacts and rest exactly, at any mass. - Keep
"sdf"and"mesh"for static concave parts (cups, bins, holes) and for moving bodies of about 40 g to 35 kg that need the exact concave shape, and readsim.check()["ok"]after the run: outside that range the world reads INVALID, for light bodies only after up to 2 s. - To tell whether such a body has settled, compare its height over time (it stays within 0.3 mm), not its speed against zero.
Planned fix
After the release candidate: contact rows from Newton's pipeline take the geoms' own gains on MuJoCo, as MuJoCo's own contacts do (the pair table keeps the friction). The probe above is that change; it is what widens the mass range and ends the vibration. The first-contact depth of heavy bodies needs rows that start before the surfaces meet, which is not scheduled.
Known gap: light slender rigid parts spin and roll slower about their thin axis (the inertia floor)¶
What is wrong
- A light slender free part (a marker pen, a pencil, a thin rod or a utensil) has a tiny inertia about its long axis. A contact at its rim then spins it to hundreds of rad/s, 0.4-0.7 rad per 1.25 ms rigid step. The contacts, linearised over that much rotation, inject energy, and a crowded scene can blow up.
- So Alloy raises such parts' rotational inertia at build (
alloy.contact.inertia_floor, 2026-11-08). A free MuJoCo body is raised when: - its largest / smallest principal inertia is at least 4;
- its smallest is below m·r0²;
- it is not in a precision pair.
- It gets armature on its 3 rotational dofs, up to m·r0². r0 = 9 mm at the default 1.25 ms rigid step (flat below, in proportion above).
- Such a part therefore spins and rolls slower about its thin axis than the real part, and tumbles slightly slower. Every other body is unchanged, bit for bit.
- Not covered (they keep their inertia; if one spins up, e.g. a coin struck at its rim, use a rigid step below
1.25 ms,
Scene(dt)<= 1 ms, and readsim.health()): - compact parts, however light, whose largest / smallest principal inertia is under 4: a thin disc or coin (2), a short cylinder, a marble, a cube;
- parts in a precision pair (the precision ladder sizes its own pairs);
- robot links and parts of multi-body objects.
Number
- YCB's large marker (15.8 g, 121 mm, axial radius of gyration 6.2 mm):
- its axial inertia goes from 6.1e-7 to 1.28e-6 kg m² (x2.09);
- rolling down a slope, it accelerates 0.76x the true value, (1 + 0.40) / (1 + 0.83) at its 9.9 mm radius;
- its tumbling inertia goes up 3 %.
- Any raised part rolling on a round face of radius R accelerates (1 + r_g²/R²) / (1 + r0²/R²) times the true
value, r_g being its own smallest radius of gyration. A solid 9 mm-radius cylinder: 0.75x (the law in
tests/contact/test_inertia_floor.py, within 3 %). - Without the floor, a clutter pile (100 objects dropped into a bin, 8 worlds, CPU) had 3 of 8 worlds INVALID. A marker reached 240 m/s, +705 J against the pile's 70 J.
- With it the pile is clean at 0.625, 1.25 and 1.5625 ms: 0 INVALID and nothing faster than the 3.3 m/s free fall
- 1 m/s (measured with development scripts, not shipped).
- The law (
tests/contact/test_inertia_floor_pile.py) runs seeds 0, 1 and 2. It requires: - no world's energy above its start + 1 %;
- no body above 2 x the free fall (6.6 m/s);
- no INVALID world and no SPIN.
- Fastest bodies are 3.26 / 4.47 / 3.76 m/s. Seed 1's is a hand-off: a 2.4 m/s box strikes a marker, and the bodies around it lose energy.
- At 1.25 ms, 8 mm gives 0 INVALID but still flings a body to 9.7-17 m/s; 7 mm leaves 3 of 8 INVALID.
Why
- The rotation per step, not the hulls: one convex hull or merged hulls still fail 3-4 of 8. RK4 vs implicit and MuJoCo's multi-CCD change nothing essential.
- A smaller step alone is not clean: at 0.625 ms a 6.5 mm floor still leaves 1 of 8 INVALID.
- The integrators take the contact geometry at the start of a step, which a part spinning 0.5 rad per step leaves far behind.
Workaround
- Exact rolling or spinning of such a part (a rolling pencil, a spun pen) needs the floor off and a smaller rigid
step:
scene.set_inertia_floor(False)(inertia_floor: falseon a scene card). Checksim.health(). - The build warning names every raised part and its increase;
sim.routes()[name]["reasons"]says so too.
Planned fix
- Contacts that follow the rotation within a step (substepping only the fast-spinning body, or a rotation-aware contact frame). Then the floor can go.
- A spin health flag (DEGRADED above 0.5 rad per step, naming the body and the fix) is coming.
- Estimate: several days, research grade. Not scheduled.
Rigid clutter: first-order spin in free flight on MuJoCo Warp, rk4's cost on the CPU's MuJoCo C route¶
What is wrong
Which integrator a robot-free scene of free bodies steps on depends on the route (alloy.scene.integrator_route):
- MuJoCo Warp (any GPU, and the CPU warp route ALLOY_CPU_ROUTE=warp): more than 8 free bodies, none raised by the
inertia floor, step on implicitfast with rk4's contact gains and a cap on the friction rows' pull (F6 R1, back on
2026-11-09 with the friction cap). A body tumbling in the air there turns first order: about 0.6 % of its angular
momentum over a 2 s toss at 10 rad/s; A4's torque-free tumble drifts 2.3e-3 at 1.25 ms against rk4's 1.1e-4 (bound
1e-3).
- MuJoCo C (the CPU default): the cap has no hook there yet, so the same scene keeps rk4, which collides once per
stage: about four collision passes per step, 3-6x slower per step than implicitfast would be.
- Up to 8 free bodies, or one the inertia floor raises, step on rk4 on both routes.
sim.routes() names the integrator and the reason on every object.
Number
CPU, the default route, the rocking law's cases (tests/bench/test_rocking_law.py; pitch peak to peak of a cube pushed at its COM by 1.5 mu m g, mu 0.5, beside 8 resting cubes; per-route result rows, not shipped): - 30 cm cube over 2 s (to 4.9 m/s), last third: MuJoCo C (rk4) 3.86 deg, lift 17.5 mm; MuJoCo Warp (R1 + cap) 0.48 deg, lift 0.8 mm. Without the cap R1 rocked 36.4 deg (MuJoCo C), which is why R1 was off until the cap. - 5 cm cube over 2 s: rk4 flips it (the sliding hop); R1 + cap 0.14 deg. - The 27-cube stacks benchmark: rk4 at 2.5 ms and R1 + cap at 5 ms both settle to 0.22 mm, 0 falls. - On the CPU, MuJoCo C's rk4 still steps these scenes faster than MuJoCo Warp's implicitfast (0.23 against 0.87 s per simulated second for the pushed cube beside 8; 1.33 against 1.69 for two stacked worlds).
Why
implicitfast integrates a body's rotation to first order: the gyroscopic term w x (I w) drifts unless the inertia is isotropic. rk4 integrates contact four times per step. Uncapped, implicitfast let a sliding body rock and grow (MuJoCo's soft friction pull, -b v_slip, coupled into the normal rows by the elliptic cone); the cap saturates that pull, and it is a MuJoCo Warp kernel.
Workaround
- Accurate spin in the air in a large scene:
profile="precision"keeps rk4, or keep the scene at 8 free bodies. - Robot scenes are not affected: they step on implicitfast on either route.
Planned fix
The same cap on the MuJoCo C route (the friction cap's rule after mj_step1 in alloy/route/_mjc/step.c; on Alloy's
numpy tick it matched MuJoCo Warp to 3 digits) would let the C route take R1 too.
Free-body stacks step 2.4x slower by default than stock Newton MuJoCo; the opt-in fast mode softens contacts¶
Status: open. Since 2026-11-09 (RIGID-DEFAULT) the default steps free-body clutter on implicitfast with a capped
friction pull, at a step that keeps contacts as stiff as at the fixed step. The opt-in rigid fast mode
(profile="fast", or scene.rigid_step = "fast") also softens contacts (a resting body sinks up to 1 % of its
thinnest member); in one run it stepped these stacks at about the stock solver's speed. It states what it gives up.
What
A scene of resting free rigid bodies (box stacks, piles) steps through the public API by default slower than the same
bodies in a stock Newton SolverMuJoCo with its default settings and one 10 ms step per period.
- The default on MuJoCo Warp (a GPU, or the CPU with ALLOY_CPU_ROUTE=warp): an entry of more than 8 free bodies
steps on implicitfast with Alloy's own contact gains, at the largest step that keeps contacts as stiff as at the
fixed 1.25 ms step: 5 ms for the 27-cube stacks, 2 steps per 10 ms period. The friction rows' pull is capped at 20
m/s², so a pushed or sliding box no longer hops and rocks (rigid-sliding-box-hops.md).
Stock solves once per period, with softer contacts.
- Still on rk4: an entry of 8 or fewer free bodies (free flight stays accurate), and every entry on the CPU's
MuJoCo C route (the default for device="cpu"), which has no friction cap
(rigid-clutter-rotation.md names each route's integrator).
- The fast mode steps such scenes at the largest step whose predicted rest sag stays within 1 % of each body's
thinnest member (10 ms here), with the same cap (on MuJoCo C: on rk4, no cap), and keeps 4 contact points per box
face instead of up to 8.
Number
One L4, 3,072 worlds of 27 resting 1 m cubes (10 kg/m³, a 3 x 3 x 3 stack, the benchmark's jitter), 3.29 s simulated, main 04f81f0ff of 2026-11-09, back to back; real time summed over the worlds (simulated world-seconds per wall-second):
default (profile="standard") |
profile="fast" |
stock Newton SolverMuJoCo |
|
|---|---|---|---|
| integrator, step | implicitfast + cap, 5 ms (2 per period) | implicitfast + cap, 10 ms | 10 ms, 1 per period |
| 3,072 worlds | 766x (774x / 759x; 0.42x stock) | 2,093x (one run; about stock's speed) | 1,816x (1,835x / 1,796x) |
| 1 world | 8.9x | 17.7x (another L4, 2026-11-09) | 15.5x |
| settle error, median / worst | 0.19 / 2.23 mm | 0.86 / 0.87 mm | 1.00 / 3.26 mm |
All 3,072 stacks stand in every row. Before RIGID-DEFAULT the default stepped these cubes on rk4 at 2.5 ms: 92-96x. Without the cap the default runs 756x, worst settle 1.65 mm: the cap costs nothing in speed.
Why
- The default step: at the 10 ms period these cubes' contacts would be 0.25x as stiff as at the fixed step (rest sag 1.17 mm against 0.295 mm under three cubes' load, the build's own check), so the default takes 5 ms: two contact solves per period against stock's one, each about 1.2x stock's.
- rk4 where it stays: with 8 or fewer free bodies, implicitfast's first-order spin is a visible error in free flight; on the MuJoCo C route the friction cap is missing, and under implicitfast a sliding box rocks more and more there: a 30 cm cube sliding at 5 m/s toppled within 2 s. So every entry on that route stays on rk4, the fast mode's too (that cube in fast mode: 6 deg and an 8 cm hop on MuJoCo C; under 1 deg and 1 mm on MuJoCo Warp; the rows are in development notes, under the cube pushed and sliding at 5 m/s per CPU route; not shipped).
Workaround
alloy.build(scene, profile="fast")on a scene of free rigid bodies (orscene.rigid_step = "fast"with any profile that allows it). It costs: contacts softer than at the fixed step (a resting body sinks up to 1 % of its thinnest member); on the CPU's MuJoCo C route it keeps rk4, and a tall body sliding at m/s rocks and hops (a 30 cm cube at 5 m/s: 6 deg, 8 cm; under 1 deg and 1 mm on MuJoCo Warp); under the fast profile a world latched INVALID freezes at its last saved checked state, up to 9 steps before the failure at one step per period. The build warns once, andsim.routes()andalloy.estimate(...)["rigid_step"]["fast"]say so.- On the CPU,
ALLOY_CPU_ROUTE=warptakes MuJoCo Warp's route (implicitfast + cap for clutter).
Planned fix
After launch: the friction cap on the MuJoCo C route, so a CPU build takes the same route as a GPU; then implicitfast with the cap for entries of 8 or fewer free bodies, behind the free-flight laws.
Steel in the bundled Newton 1.8 lets a robot arm's contacts through 54 times more often than the copy before it¶
What is wrong
Steel (SolverSteel, Newton's reduced-coordinate rigid solver) comes inside Alloy's bundled Newton. No default route
uses it: robots and rigid objects step on MuJoCo. It is reached only by opting in, in one of two ways:
- RouterConfig(pile_backend="steel") (engine layers) sends a pile of more than 50 free bodies per world to a solver
entry named "steel". Alloy registers no such entry, so the build raises BuildError: ... no solver capability
'steel' until you register one (a solver plug-in around SolverSteel).
- Engine-layer code that steps alloy._vendor.newton.solvers.SolverSteel itself.
Since Alloy's Newton moved to release 1.8 (db915e1c), Steel on a robot arm that picks and places blocks lets parts
pass through each other in about a third of the episodes. The Steel of the Newton copy Alloy bundled before
(ac7f7830 plus our fixes) did that in under 1 % of them at the same settings. Stacks of free bodies, which is what
pile_backend routes, are not affected.
Number
The scene is Alloy's pick-and-place benchmark (T12: a Franka arm and 8 blocks), in 2 s episodes on one L4. An episode counts as a glitch when the benchmark's watch flags it; nearly every one here is a penetration over 1 cm. The benchmark's bar is under 0.1 % of episodes. Glitched episodes / episodes (upper 95 % bound):
| Steel's settings | Newton 1.8 (db915e1c) |
the copy before (ac7f7830 + ours) |
|---|---|---|
| 0.625 ms step, baumgarte 0.2 (its default), 16 iterations | 162 / 512 = 31.6 % (35.2 %) | 3 / 512 = 0.59 % (1.5 %) |
| the same with 2,048 articulated rows instead of 1,024 | 163 / 512 = 31.8 % (35.4 %) | - |
| 0.625 ms step, baumgarte 0.05, 8 iterations | 338 / 1,024 = 33.0 % (35.5 %) | 66 / 1,024 = 6.4 % (7.85 %) |
- 54 times is 31.8 % against 0.59 %.
- Alloy's default route (MuJoCo Warp) on the same scene, with the same watch: 0 / 3,072 (upper 95 % bound 0.098 %), on Newton 1.8 as before it.
- Free bodies: 27 one-metre cubes in 9 stacks, 3,072 worlds, 10 ms step. Both Steel copies: 0 / 3,072 stacks fall or keep moving, and the cubes rest 0.31 mm (Newton 1.8) and 0.32 mm (before) from their ideal height (median).
- Both Steel copies also fail two of Alloy's friction laws: a box loaded below its friction limit creeps 5.5 mm where the law allows 0.01 mm (A5.onset), so it has no clean slip force either (A5.isotropy). The sliding law passes (stop distance within 0.61 %, bound 1 %).
Why
Not found. The change is inside Steel's 46 commits between the two copies and has not been bisected. - It is not the contacts: fed the same contacts, the two copies still differ, and both import the same model (the same margins and gaps). - It is not a full buffer: the newer Steel builds up to about 2,000 articulated constraint rows per world where the older one stays under 1,024, but 2,048 rows give the same rate (31.8 %).
Workaround
- Keep the default,
pile_backend="mujoco". Robots always step on MuJoCo."kamino"is the other pile entry that ships registered. - If you register Steel yourself, use it for free bodies only, and read
sim.check()after every run: a part that passed through another shows as PEN_FAIL, a full Steel buffer as ROW_OVERFLOW. - Tuning does not recover the newer copy: Steel's own baumgarte and twice the iterations took the older copy from 6.4 % to 0.59 %, and left the newer one at 32 %.
Planned fix
None on our side: no Alloy route steps Steel, and the cause is in the solver. We measure the same rows again at the next Newton update. Steel becomes a registered entry only when it keeps this scene under 0.1 % and passes the three friction laws.
A lightly pressed sliding contact tips when its MuJoCo gains bypass the route¶
What. A box pressed lightly onto a face while it slides (a magnet eraser on a board) tips over at a 1.25 ms rigid
step, but only in scenes that write MuJoCo contact gains themselves (Newton shape ke / kd on MuJoCo-owned bodies,
as the plug-in test harness's scenes do). On the default route (the public API, library scenes) the same contact
slides flat: the law tests/contact/test_light_sliding_tip.py checks a 48 g box down a 44 deg slope at mu 0.5 (the
eraser's press / weight ratio) and a 20 g cardboard box on a 50 g dynamic plate.
Number. Harness gains (Newton reads kd 2e3 as tau = 2 / kd = 1 ms; MuJoCo's refsafe raises it to 2 dt; impratio 1): the box tips 14 deg in 0.3 s (peak 23 deg) and its face lifts 11 mm off the board; with a magnet's 1/h^4 pull, 61 deg. Default route: rotation 0.04-0.11 deg and lift 0.01-0.08 mm (2-48 g; ABS, steel, glass, PMMA, cardboard, paper board, foam; 44-60 deg slopes, up to 1.6 m/s).
Why. MuJoCo's soft friction rows ask for a reference acceleration of -b·v_slip, b = 2 / (dmax·tau): at tau = 2 dt and 1 m/s that is ~800 m/s^2, and the cone lifts the sliding box off its face each step until it rocks over. The route's gains keep tau at ~8-12 dt for such pairs (a body's material gains mix with the face's, MuJoCo solmix) with impratio 300. A 25 ms friction time constant alone (solreffriction) also holds it at the harness's normal gains.
Workaround. Build contact gains with the route's alloy.scene.native_gains.apply_native_gains (or keep tau = 2 / kd
at 8 dt or more), or run at dt <= 2.5e-4 s. Do not lengthen the friction time constant everywhere: stiction creep
grows with it (a box held at 98 % of its friction limit crept 3 mm/s at 2.5 ms, 34 mm/s at 12.5 ms).
Planned fix. The plug-in harness taking the route's gains and impratio (alloy/plugins/harness; its laws' rows
would move, so their owners re-baseline): about half a day plus the re-baselines.
Known gap: full-surface mesh contacts can take a wrong inside/outside sign from Warp's ray parity¶
What is wrong
- On a watertight mesh, Newton signs soft contacts by Warp's ray parity (
wp.mesh_query_point_sign_parity, Warp 1.18.0). At degenerate points, where the ray grazes a shared edge or vertex, parity gives the wrong side: inside for a point in a cup's cavity, or outside for a point inside its wall. - Alloy re-signs the per-particle rows (Newton's
create_soft_contacts) after each collide with a perturbed-parity vote (alloy.contact.mesh_sign, 2026-11-07). That covers static meshes and every mesh outside a destination's full-surface set. - Not re-signed: the full-surface records of
soft_contacts_meshthat VBD-family destinations take on moving meshes (robot links, grippers, tools;ProxyContactPipeline(full_surface=True)). Their vertex-face records take the sign from the same parity (_mesh_partition_sign), and so do the edge-penetration checks (_is_inside). A record with the wrong sign has its INSIDE flag, and so its normal, the wrong way round. The soft particle is then pushed toward the far side of the surface for that substep, or a penetration-recovery record is added for a particle outside the mesh.
Number
- A trace on
open_cylinder(0.03, 0.06, 0.004): one wrong point (cavity, 4.3 mm from the inner wall, n.(x - p) = -4.257 mm). 0 errors in 200,000 random cavity points. Moving one ulp off the point gives the right sign. - So it is rare, a measure-zero sheet hit by a float32 position. It has not been seen on a full-surface record, but it has not been looked for there either.
Why
- Ray parity counts surface crossings along one ray. A ray through a shared edge or vertex counts that crossing twice, or not at all.
- The full-surface pass emits feature records (vertex-face, face-vertex, edge-edge) with sign flags. Those flags drive
the separate geometry evaluation and
mesh_contact_valid, so flipping a normal after the fact, as the per-particle fix does, would leave the flag and the recovery records inconsistent.
Workaround
- None needed in most scenes. If a VBD contact on a moving mesh kicks the cloth the wrong way for one substep, at a fixed position that does not repeat one ulp away, suspect this gap.
- To rule it out, give that shape per-vertex contact: leave it out of
full_surface_shapes. Its rows then go through the re-signed per-particle path.
Planned fix
- Re-sign the full-surface vertex-face records the same way. After the mesh block is detected, run the perturbed-parity vote at each record's particle on a parity-signed mesh. Where it disagrees, toggle the record's INSIDE flag, drop a recovery record whose particle the vote puts outside, and re-run the block's evaluation (it is pure per record).
- The edge-penetration check (
_is_inside) needs the same vote, which means a copy of that kernel, like the vertex query inalloy.contact.mesh_cull. - Estimate: 1.5-2 days, including a planted degenerate point on a moving mesh as the law and a GPU check that the records are otherwise identical. Not scheduled; upstream reporting is on hold.
A hydroelastic precision fit leans past its clearance under a side push¶
What is wrong
A peg seated in a bore whose precision features (an object card's precision_features) are mode: hydroelastic
leans about 1.3 times as far as the clearance allows when it is pushed sideways at its top, and the bore's wall takes
about 0.1 mm of penetration. A rigid peg would stop at the geometric limit, where its two wall contacts meet the bore.
The same pair in mode: sdf (the default) stops within 2 to 6 % of that limit, by push direction, with under 25 µm
of penetration (precision-sdf-side-lean-direction.md).
Number
A 12 mm peg in a 12.2 mm bore, 20 mm deep (0.1 mm radial clearance; allowed lean 0.575 deg), 50 µm voxels,
kh 1e11. It is pushed 5 N sideways at its top for 0.5 s at a 0.3125 ms step, in 16 worlds with small random tilts and
offsets. GPU (L4), tests/contact/test_lean_gpu.py (bounds: 1.05 times the limit, 50 µm):
| pair mode, path | lean / allowed | wall penetration | commit |
|---|---|---|---|
| hydroelastic, MuJoCo Warp / Newton | 1.276 / 1.245 | 114 / 106 µm | 4b324c7 (2026-11-01) |
| hydroelastic, MuJoCo Warp, kh 1e12 | 1.338 | 130 µm | e7e697f (2026-11-01) |
| hydroelastic, MuJoCo Warp / Newton | 1.299 / 1.240 | - | rc2-1109 f94bcfc50 (2026-11-09) |
| sdf, MuJoCo Warp / Newton | 1.026 / 1.026 | 15 / 15 µm | 4b324c7 (2026-11-01) |
| hydroelastic, both paths, Newton 1.8 | 1.277-1.312 / 1.250-1.256 | 100-113 / 113-118 µm | bump (2026-11-10) |
| sdf, both paths, Newton 1.8 | 1.048-1.055 / 1.040-1.044 | 13-20 / 10-14 µm | bump (2026-11-10) |
- The same fit's insertion law (CT-1,
tests/contact/test_peg_hole_gpu.py: a 50 N press and 5 N side pushes) reads, on one L4 at main f207ccaff, a deepest single sample of 100.5 µm against its 100 µm target in 1 of 3 runs; the others stay under it, and p99 is 19 µm against 50 µm. Its parent commit passed 3 of 3: at one failing run in six, the two are not shown to differ. MuJoCo Warp's GPU contact solve does not repeat run to run, so that worst sample moves by about 0.5 %. The test marks that one bound as an expected failure that may pass; p99, tunnels, dropped contacts and a 110 µm guard stay hard.
Why
Not resolved. A stiffer pressure field does not help (kh 1e12 leans further), so the field's modulus is not the limit. The likely cause is the stiffness cap that the contact layer puts on precision rows at this step: their time constant is at least two steps. The cap would hold the two wall patches of a leaning peg softer than the pressure law asks. The sdf mode's per-patch weights reach the limit at the same step.
Workaround
- Use
mode: sdf(the default) for fits that carry side loads. - Where a hydroelastic pair is needed (contact area, pressure), allow about 0.1 mm more wall penetration and 30 % more lean than the clearance gives.
Planned fix
None scheduled. First check: the realised stiffness of the wall rows against the pressure law's (kh/2) A while the peg leans, at this step and at half of it.
A precision fit pushed sideways leans 2 to 6 % past its clearance, by push direction¶
What is wrong
A peg seated in a bore (mode: sdf, the default) and pushed sideways at its top leans 2 to 6 % further than the
clearance allows, and how much depends on the direction of the push in the world frame. The same peg, bore and force
read 1.02 times the limit in one direction and 1.05 or more in another, on Newton 1.8 and before it. A rigid peg
would stop at the limit in every direction. The law for this fit is 1.05 times the limit; a push along a world axis
on Newton 1.8 reads 1.048 to 1.055 on the MuJoCo Warp path, on and over it. The wall penetration is 13-20 µm of the
50 µm allowed.
Number
A 12 mm peg in a 12.2 mm bore, 20 mm deep (0.1 mm radial clearance; allowed lean 0.575 deg), pair stiffness 2e6 N/m. It is pushed 5 N sideways at its top for 0.5 s at a 0.3125 ms step, in 16 worlds with small random tilts and offsets. GPU (one L4), MuJoCo Warp path, 2026-11-09. Lean / allowed, worst world / mean over the worlds:
| push direction, from +x | Newton before 1.8 (main 47157c433) | Newton 1.8 (bump 43ae205ba) |
|---|---|---|
| 0° | 1.026 / 1.024 | 1.051 / 1.044 |
| 7.5° | 1.044 / 1.040 | 1.044 / 1.029 |
| 15° | 1.040 / 1.035 | 1.029 / 1.024 |
| 22.5° | 1.025 / 1.019 | 1.023 / 1.020 |
| 30° | 1.021 / 1.017 | 1.033 / 1.020 |
| 45° | 1.045 / 1.041 | 1.040 / 1.038 |
| 60° | 1.029 / 1.025 | 1.032 / 1.025 |
| 90° | 1.026 / 1.023 | 1.048 / 1.040 |
| 135° | 1.044 / 1.040 | 1.040 / 1.037 |
| 180° | 1.026 / 1.025 | 1.051 / 1.043 |
| 270° | 1.027 / 1.025 | 1.048 / 1.039 |
Repeats of the 0° push, 2026-11-09 and -10. tests/contact/test_lean_gpu.py makes this push: its law is 1.05, an
expected failure on Newton 1.8's MuJoCo Warp path (7 of the 15 runs read under 1.05), with a hard guard at 1.08.
It also holds the pushes at 45° and 135° to 1.05 (1.040 and 1.039-1.040, 3 runs each); the push at 7.5° read
1.048, 1.046 and 1.052 in 3 more runs and is an expected failure of the same kind.
| Newton | path | runs | worst world | mean over the worlds | wall penetration |
|---|---|---|---|---|---|
| before 1.8 | MuJoCo Warp | 6 | 1.026 (every run) | 1.024-1.025 | 15-16 µm |
| before 1.8 | Newton | 4 | 1.026 (every run) | 1.026 | 14 µm |
| 1.8 | MuJoCo Warp | 15 | 1.048-1.055 | 1.041-1.046 | 13-20 µm |
| 1.8 | Newton | 11 | 1.040-1.044 | 1.037-1.038 | 10-14 µm |
The lean holds for another 0.5 s of push (1.052 after 0.5 s and after 1.0 s). On the MuJoCo Warp path a world can lean 0.01 further for about 8 steps when the row of its bottom patch is re-picked (seen once in two runs read at every step). A solver tolerance of 1e-8 or 300 iterations changes none of these numbers.
Why
The lean past the limit is the penetration of the peg's two wall patches divided by the 19.9 mm between them. The contact layer gives each patch (the rows of one pair whose normals fall in the same 27° cone) the pair's stiffness and shares it equally among the rows of the patch that touch. With one touching row the top patch sinks 3.8 µm and the bottom one 1.3 µm: 1.026. Newton's contact reduction keeps, for each of its own normal bins, the deepest contact and the outermost ones. When the push points near the edge of a bin, the contacts kept at that edge sit on the bore's rim 18-22° from the deepest one and still touch, 0.4-3 µm deep. Each takes an equal share of the stiffness, so the deepest row keeps a half or a third of it and sinks to 6.2-8.6 µm: 1.035-1.055.
Counted per world at the end of the push: before Newton 1.8 at 180°, all 16 worlds have one touching top row (3.8 µm) and read 1.023-1.026; on Newton 1.8 at 180° they have two or three (8.3, 3.0 and 0.4 µm in one world) and read 1.036-1.051; on Newton 1.8 at 7.5°, 13 worlds have one (1.023-1.033) and 3 have two (1.038-1.044).
Newton 1.8 turned the reduction's normal bins so that every world axis sits 14° from a bin edge. That moved a push along a world axis from the middle of a bin to near an edge. The spread itself is older: before 1.8 it shows at 7.5°, 45° and 135°.
Workaround
- Allow 6 % more lean than the clearance gives for a side-loaded fit: 11 µm of summed wall penetration over 20 mm of engagement at 5 N.
- Where the lean matters more than that, turn the scene so the side load points 22.5° off a world axis in the plane across the fit's axis (1.023 on Newton 1.8).
Planned fix
Share the patch stiffness by depth instead of equally, so a row that barely touches takes almost none. Planned
after the release candidate; it turns the expected failure in tests/contact/test_lean_gpu.py back into a pass. A
first trial (2026-11-09) reads 1.022-1.036 in the six directions tried on the MuJoCo Warp path and 1.032 at 0° on
Newton's, but is not ready: on the MuJoCo Warp path the barely touching rows then switch between loaded and
speculative from step to step, and in 1 to 3 of 16 worlds the lean jumps to 1.05-1.10 for about 20 steps, several
times in 0.4 s. The share law has to keep such rows from switching first.
A peg that rolls on its precision partner slowly gains speed¶
What is wrong
A precision pair (a peg and the block it fits, precision_partners on their cards) is made for the fit: the peg in
its bore. A peg that misses the bore, tips over and rolls across the top of the block speeds up a little by itself
instead of slowing down. The world's health stays OK: the energy check flags a gain of 10 % of the scene's energy
scale, and this one stays under it over a few seconds.
The shipped demo_peg_d12 no longer shows it: since 2026-11-10 every world of the demo starts inside the fit's
clearance and the peg seats. Any scene where a part rolls or slides for long on its precision partner can.
Number
demo_peg_d12 with its former start spread (the peg up to 0.5 mm off the axis, against 0.1 mm of radial clearance),
profile precision, one L4, in an energy sweep of 53 scenes:
- worlds where the peg missed the bore and rolled on the block: the peg's speed rose about 10 % in 1.7 s, and the
world's energy rose by 1.1 to 5.8 % of the scene's energy scale;
- worlds where the peg seated in the bore: 0 %;
- the other scenes of the sweep that were measured: 0 %.
It has not been measured for other parts (a bolt rolling on its nut, a plug on its receptacle) or on the CPU.
Why
Not found yet. The contacts of a precision pair come from the precision layer, built from the two features' exact shapes, and the pair's plain contact is switched off. A contact point that travels round a rolling peg is the case those rows were not written for: the fit's laws (clearance, lean, insertion) all hold the peg nearly still in its bore.
Workaround
- Start a precision fit inside its clearance, so the part seats (the demo does; a peg dropped 0.15 mm or more off the axis of a bore without a chamfer lands on the rim).
- For a part that is meant to roll or slide on the other, do not use the precision pair: place a copy of the card
without
precision_partners, and the two collide as plain shapes (a bored block then collides as its convex hull: its bore is closed). - In a long run, compare the part's speed over time; do not rely on
sim.check()alone for this.
Planned fix
After the release candidate: reproduce it with a peg laid on the block, find the row that does the work, and add the law that a rolling peg's energy never rises.
Stock SolverVBD rigid bodies: an applied torque wraps and a spin slows down¶
What is wrong
Newton's SolverVBD builds each rigid body's inertial target with one first-order rotation step,
normalize(q + dt/2 omega q), where omega already includes dt I^-1 tau from any torque in body_f. A step that asks
for an angle x then turns 2 atan(x / 2). That gives two errors.
- An applied torque reaches the body short, and can wrap. x = dt² tau / I. A light, thin body (a cable segment)
has a tiny axial inertia, so x is large. A clamped 12-segment rod twisted 0.51 and 0.21 of T L / (G J) at
0.01 / 0.03 N m; the A11.torsion rod twisted 0.018 of it.
- A spinning body slows down. Each step loses (omega dt)² / 12 of the spin, so a body that rolls feels a drag
that grows with speed and is first order in dt.
Number
CPU, 1.25 ms, measured with two development scripts, a single-body roll and a roll check (not shipped). One rigid capsule (r 5 mm, 0.3 m, 1200 kg/m³) and a 12-segment rod roll down an incline, mu 0.8, 0.4 s from rest:
| body, slope, dt | acceleration / its rolling value | energy lost |
|---|---|---|
| capsule, 10°, 1.25 ms | 0.956 | 4.8 % |
| capsule, 10°, 0.625 ms | 0.983 | 2.5 % |
| capsule, 20°, 1.25 ms | 0.830 | 15 % |
| rod on the first-order target, 10°, 1.25 ms | 0.948 | 5.1 % |
- The (omega dt)² / 12 loss predicts 4.1 % at 10° and 16 % at 20°.
- The loss does not move with contact damping, stiffness (ke 250-25,000), friction_epsilon or hard contacts.
Why
The target's rotation is a first-order (Cayley-like) step, not the exponential map. A torque in the target is also scaled by dt² / I, which no rotation step can take for large values: even an exact exp map wraps past pi.
Workaround
- Rods (ROD_VBD):
alloy.solvers.rod.SolverVBDRodfixes both for its chain bodies. - Torques go into the chain's Gauss-Newton step as a potential: twist exact to 1e-7.
- The target rotates by exp(omega dt) (
exact_rotation_target): rolling 0.998 / 0.991 of its value at 10 / 20 deg. - Other bodies on VBD: use a smaller
dt(the spin loss is first order in it), and keep applied torques with dt² tau / I well under 1. Alloy routes free rigid bodies to MuJoCo, which does not have either error.
Planned fix
None for stock SolverVBD bodies. The same exp-map target belongs in Newton's forward_step_rigid_bodies; that is
an upstream change, not scheduled.
Robots and grasping¶
No call attaches or welds an object to a gripper, outside ClothFold-v0's opt-in grasp="attach"¶
What is wrong. A robot holds an object by contact and friction only. There is no call that attaches or welds an object to a gripper while a simulation runs, and so none that releases one. A script or policy that closes the fingers and then fixes the object to the hand has no equivalent here: if the grip does not hold by friction, the object slips or stays behind.
One exception: the ClothFold-v0 environment's opt-in grasp="attach" (alloy.envs.cloth_attach). While its
fingers are closed on the towel, the towel vertices between them are held to a finger by stiff springs, and let go
when the fingers open. It is a one-way shortcut, not a friction grasp (the gripper does not feel the towel's weight),
and it exists only in that environment, for its towel (docs/guide/envs.md).
The number. There is no error to measure: the call does not exist. What the two ways to hold an object did in
trials (docs/guide/robots.md, Grasping): by friction, the default 2 mm cloth slipped out of a fingertip pinch (0 of
64 worlds carried an edge); a cup built into the hand's body in the robot's MJCF poured 96-99 % into a second
container in all 64 worlds.
Why. Not built. Outside that one environment, the public API has no call that fixes an object to a robot's hand, or frees it, while a simulation runs.
Workaround. Two ways, both in docs/guide/robots.md, Grasping:
- A friction grasp. Set the friction with the object's material or friction=, or with
scene.set_friction(a, b, mu) for the finger-object pair. Give the fingers enough actuator force to squeeze (MJCF
kp times the target error), close them onto the object, then ramp the lift. Judge the grasp by the object: record
its .pos and check that it follows the gripper.
- A body of the hand. To carry something rigidly, put its geoms in a <body> under the hand body of the robot's MJCF,
with no joint between them. It then moves exactly with the hand, and it pours from a held container. The cost: the
object cannot be put down.
Planned fix. None planned.
Robot scenes take 1.25 ms physics steps unless you ask for a coarser one¶
What is wrong
A scene with a robot steps its rigid bodies at the fixed step: 1/600 s snapped down to the grid dt / 2**j, which is
1.25 ms at dt=0.01 and at dt=0.005. So one control period costs 8 physics steps at dt=0.01 and 4 at
dt=0.005, also for a robot whose servos and contacts would be stable at a larger step. Scenes of free rigid bodies
only already pick the largest stable step by themselves (docs/guide/worlds.md); robot scenes do not.
The larger step is opt-in. Set it before building:
scene.rigid_step = 0.0025 # pin a step in seconds (snapped down to the grid dt / 2**j)
scene.rigid_step = "auto" # or: the largest step every cap below allows, never under the fixed step
sim.routes() and alloy.estimate(scene, worlds, seconds)["rigid_step"] name the step and what bound it. A scene
that never sets rigid_step builds and steps exactly as before.
The caps a robot adds (the free bodies beside it keep their own):
- servo: for every position servo, omega dt <= max(1, zeta), with omega = sqrt(kp / I), zeta = (kv + joint
damping) / (2 sqrt(kp I)) and I the joint's inertia at the start pose, armature included. The cap reads each joint alone at the start pose: a folded arm has a smaller inertia, and the servos together have a stiffer mode than any one joint (1.34x on the Panda, 1.16x on the Go2, 1.00x on FR3, UR10e, G1 and the LEAP hand, the worst of 200 poses). The cap sits a factor 2 or more below the stability limit, which covers both. Past it a step
response is off by more than about a tenth of the step; the servo is unstable at 2 zeta + 2 sqrt(zeta^2 + 1).
- damping: joint damping and a servo's kv weaken a contact's push on the joint by 1 / (1 + dt b / I),
b = kv + joint damping. 1 + dt b / I may be at most 1.25 times its value at 1.25 ms, so a link's contact sinks
at most 25 % deeper than at the fixed step. This is the cap that holds stiff, heavily damped arms.
- solref: dt <= tau / 2 for the time constant of every contact shape, joint limit and equality row the robot file
writes. MuJoCo raises a smaller tau to 2 dt, so those rows get softer by (tau / 2 dt)^2.
- link_gap: v dt <= the robot's contact gap (5 mm, or add_robot(..., contact_gap=)): a link travels at most
its contact gap per step, so a contact starts at most that deep; v is the speed of the farthest collision point
below one joint at 2 rad/s (0.5 m/s for a slide, or the file's joint velocity limit when that is lower). Several
joints moving together give a faster tip.
- loose_body: a loose free body in the robot file (a box or a mug beside an arm) must not get a softer contact than
at 1.25 ms. Alloy stiffens a light loose body's contact as far as the step allows, so a light one holds 1.25 ms.
"auto" takes the largest grid step that passes all of them. A pinned step is taken as asked; the build then warns once and names each cap it breaks, the joint or shape, and the cost (for example "contacts 0.25x as stiff as at 1.25 ms").
Number
- Physics steps per control period at the fixed step: 8 at
dt=0.01, 4 atdt=0.005; withrigid_step = 0.005atdt=0.005: 1. - The shipped Go2 (
emb_e8_go2): "auto" gives 2.5 ms, half the physics steps. The damping cap binds: at 5 ms a calf's contact would sink 1.48x deeper than at 1.25 ms. link_gap allows 5 ms (its feet reach 0.32 m from the hip axis: 7.8 ms), its 20 ms default time constants 10 ms and its servos 18 ms. - The shipped Panda (
emb_e2_panda): "auto" stays at 1.25 ms. Three caps hold it: damping (its servos'kvof 450 on a joint inertia of 0.22 kg m2: contacts on its links would sink 1.72x deeper at 2.5 ms, 3.15x at 5 ms), solref (its file's 2.5 ms contact time constant on the arm, its table and props: 0.25x as stiff at 2.5 ms, 0.06x at 5 ms; the FR3 and UR10e files write the same) and loose_body (the box, cylinder and mug in its file: 0.25x as stiff at 2.5 ms, 0.06x at 5 ms). link_gap gives 3.2 ms (it reaches 0.79 m from joint 2), the finger coupling's 5 ms time constant 2.5 ms, its servos 5 ms.
Rows (dt=0.005; the step pinned with scene.rigid_step; speed against the same robot at 1.25 ms):
| scene | 2.5 ms (2 steps per period) | 5 ms (1 step per period) |
|---|---|---|
| speed, 1,024 worlds on one L4: Panda, FR3, UR10e, LEAP | 1.91-2.05x | 3.3-3.7x |
| speed, 1,024 worlds on one L4: Go2 | 1.66x | 2.45x |
| speed, 4 worlds on the CPU, six robots | 1.65-1.97x | 2.8-4.0x |
| arms moving freely: joints against the 1.25 ms run | within 0.009 rad | within 0.027 rad |
| loose box, cylinder, mug beside an arm: end position | within 0.05 mm | within 0.17 mm |
| LEAP hand: cube stays in the hand (1,024 worlds) | all, 0.04 mm off | all, 0.1 mm off |
| Go2 standing (1,024 worlds) | all stand, base 0.02 mm off | all stand |
| G1: joints against the 1.25 ms run, standing / moving | 0.04 / 0.26 rad | 0.08 / 0.44 rad |
| gripper holding a thin plate: slip (0.57 mm at 1.25 ms) | 1.28 mm | 4.22 mm |
| gripped chain: pad penetration (0.10 mm at 1.25 ms) | 0.34 mm | 0.72 mm |
| pick and place, 2,560 episodes: episodes with a penetration glitch (0 at 1.25 ms) | 12 (0.47 %) | 360 (14 %) |
No world raised a health flag in the free-motion and standing rows. In the LEAP hand's rows a solver warning
(UNCONVERGED) showed in 1 to 3 of 1,024 worlds at 1.25 ms (as shipped too) and at 2.5 ms, in none at 5 ms;
every world passed sim.check(). Reading: a robot that moves, reaches or stands
is as good at 2.5 ms and close at 5 ms; a robot that grips is not, and the build's warning says so (damping,
solref). Under "auto" only the Go2 leaves 1.25 ms (2.5 ms) among the shipped robots: the damping cap holds the
arms and both humanoids, and the LEAP hand is held by the cube in its file and its contacts' time constants
(loose_body, solref). G1 at 1,024 worlds and every robot at 4,096 worlds ran out of memory on a
24 GB L4 at every step, so they have no GPU rows.
A pinned step that breaks the damping or solref cap is not for a robot that grips: at 2.5 ms 0.47 % of pick-and-place episodes had a penetration glitch and at 5 ms 14 % (0 at 1.25 ms).
Why
The fixed step was chosen once for all robots: stiff position servos, thin fingers and contacts written for 1.25 ms. Whether a given robot is stable and as accurate at a larger step depends on its servo gains, its link inertias and the contact time constants in its file, which the caps above now read. Making the larger step the default would change every robot scene's motion, so it stays a choice.
Workaround
- Set
scene.rigid_step = "auto", or pin a step, and readsim.routes()for the step and the cap that bound it. After a pinned step, read the build's warning before trusting grasps and contact depths. - A robot file that writes 2.5 ms time constants on its own shapes, limits or equality rows stays at 1.25 ms under "auto" (the shipped FR3, Panda and UR10e files do). To step it coarser without softer contacts than the file intends, write time constants of at least twice the step you want.
- Light loose objects in the robot file hold "auto" at 1.25 ms. Add them with
scene.add_boxand the like instead: scene objects have their own caps, and a light one still holds the fixed step. - Check the run as always:
sim.check()["ok"]andsim.health().
Planned fix
Not fixed yet:
- the default: a robot scene that never sets rigid_step keeps 1.25 ms;
- arms held at 1.25 ms by their servos' damping, by 2.5 ms contact time constants in their files and by the light
loose objects in them;
- a robot beside cloth, liquid, soft bodies, sand or paste, a kinematic object, a precision fit or an attachment
keeps the fixed step, and so do the precision and debug profiles under "auto"; rigid_step = "fast" is not offered
for robots;
- a servo on a tendon and joint limits written as stiffness and damping (URDF, USD) are not checked by the caps,
and a loose body in the robot file is checked for its contact stiffness only, not for how far it moves in a step.
Making "auto" the default for robots is proposed (it changes only the Go2 among the shipped robots) and waits on a decision.
A long chain of light bodies in a robot file goes non-finite at its first contact on MuJoCo Warp's Newton solver¶
What is wrong
A robot file that is a long chain of light bodies can go INVALID the moment it first touches something. Examples are a
ball chain, a necklace, or a rope of rigid links: from 6 nested bodies, each a small sphere on a ball joint, at
Alloy's default impratio (Why).
sim.health() shows NONFINITE_Q, NONFINITE_QD and FALLBACK_USED. This happens wherever MuJoCo Warp steps the robot:
on a GPU, and on the CPU with ALLOY_CPU_ROUTE=warp. The CPU's default route (MuJoCo C, float64) steps the same chain
without trouble. An INVALID world freezes at its last good state, so read sim.check()["ok"] before you trust a result.
Cables made with scene.add_rod (no clamp) are also MuJoCo chains, but they are not affected: see Why.
Alloy now handles such a chain itself. At build it screens every MJCF and URDF robot file, and when the file is a long
chain of light bodies (the rule in Why) it steps the scene's MuJoCo entry on the CG solver, which stays finite. The build
warns, and the route report says so in a line that starts "mujoco solver: CG for robot". What is left:
- A robot file that sets its own <option solver=...> keeps it: a long chain held on Newton that way still goes INVALID.
- The rule's bound was measured on chains of steel beads. A chain of another shape that falls just above the bound has
no measurement behind it.
- On CG, sim.health() notes UNCONVERGED (the CG residual at its iteration cap), and every robot and rigid body in the
scene steps on CG with the chain, not only the chain.
- USD robot files are not screened.
Number
The rig: steel beads 8 mm across and 10 mm apart. The first bead has a free joint, and each neighbour pair a ball joint.
The chain is added with scene.add_robot(name, mjcf=...) beside a static add_box bench, at dt=1/300 and
contact_capacity=4096. Measured 2026-11-11 on a CPU host and one L4.
| chain | where it starts | MuJoCo Warp (GPU, or CPU with ALLOY_CPU_ROUTE=warp) |
MuJoCo C (CPU default) |
|---|---|---|---|
| 1, 2 or 5 beads | dropped 1 cm onto the bench, or draped over its edge | OK | - |
| 10 beads | in the air, no contact | OK | - |
| 10, 20 or 30 beads | dropped 1 cm onto the bench | INVALID at the landing (t 0.047 s) | OK (30 beads) |
| 30 beads | draped over the bench edge | INVALID at t 0.008 s (L4) | - |
| 60 or 120 beads | dropped or draped | INVALID at the first contact (L4) | - |
- On the 30-bead chain, dropped or draped, none of these changes the result: beads 100x heavier, 16 mm beads, joint damping 1e-3, armature
1e-8 to 1e-6 on every joint,
condim="1", a single friction value,dt=1e-3, two hinges in place of each ball joint, a 0.5 mm or 5 mmcontact_gap. - With Alloy's rule (CG): the 10-bead chain dropped 1 cm lands and stays OK on the CPU with
ALLOY_CPU_ROUTE=warp; held on Newton by its file, it goes INVALID at the landing. The 30-bead chain dropped 1 cm stays OK on one L4 over 0.2 s (PEN_WARN only) (tests/scene/test_robot_chain_cg.py). add_rodwith no clamp, 30 and 40 segments, was run with a 0.6 m cable of radius 2 mm (the default material) and a rod of radius 4 mm with 10 mm segments. Each was dropped flat 1 cm onto the same box or draped over its edge, atdt10 ms and 1/300 s: 16 of 16 runs OK and finite on the CPU withALLOY_CPU_ROUTE=warp, the drapes with PEN_WARN only.
Why
MuJoCo's default solver, Newton, factorizes the matrix H = M + JᵀDJ in float32 in MuJoCo Warp. On a long tree of
light bodies that all touch down at once, this factorization breaks down, and the step returns non-finite values.
Stepping the same robot file with MuJoCo Warp alone, with no Alloy solver code in the step, gives a NaN at the same landing
step. That holds at the current MuJoCo Warp (3.17) and at the previous pin (3.16). With solver="CG", which does not
factorize, MuJoCo Warp stays finite; so does MuJoCo C in float64.
A margin measures it: eps32·|S·JᵀDJ·S| / λ_min(S·M·S), where S = diag(M)^-1/2 and JᵀDJ sums the constraint rows
(alloy.scene.newton_rule, MuJoCo C, the worst control period of a 1 cm drop). The chain makes λ_min small: its joints'
inertias are nearly dependent, whatever the bead mass. The contact rows' curvature grows with the impratio, which Alloy
sets to 300 for a robot whose file sets none.
| chain | λ_min(S·M·S) | impratio | margin | MuJoCo Warp |
|---|---|---|---|---|
| 5 beads | 1.22e-3 | 300 | 11 | OK |
| 6, 7, 8 beads | 6.1e-4, 3.5e-4, 2.2e-4 | 300 | INVALID | |
| 10 beads | 9.9e-5 | 300 | 296 | INVALID |
| 10 beads | 9.9e-5 | 1 (in the file) | 1.0 | OK |
| 30 beads | 2.6e-6 | 300 | 36,400 | INVALID |
| 30 beads | 2.6e-6 | 1 (in the file) | 122 | INVALID |
| 30 beads, armature 1e-6 | 2.4e-4 | 1 (in the file) | 1.6 | - |
add_rod, 30 segments, 4 mm rod and 0.6 m cable |
2.0e-3, 9.9e-4 | 1 | 0.60, 0.94 | OK |
| shipped robots (FR3, Panda, UR10e, G1, H1, Go2, LEAP) | 0.012 (G1) to 0.25 | 1 to 100 | up to 1.95 (LEAP) | OK |
So an add_rod chain stays finite for two reasons together: Alloy's CHAIN armature floor (1e-6 kg·m² on every rotational
dof) raises λ_min about 100x, and a chain on Newton runs impratio 1, not 300. Armature alone did not save the bead chain
at impratio 300 (Number).
Alloy's rule screens the robot file at its own pose (alloy.scene.robot_chain, about 2-45 ms per file) and picks CG
when λ_min(S·M·S) < 1e-3 · max(impratio, 10) / 300: below 1e-3 at the route's impratio 300, so 6 beads and more go to
CG and 5 stay on Newton; at impratio 1 in the file, below 3.3e-5, so 10 beads keep Newton and 30 go to CG. Every shipped
robot is at least 12 times above the bound, and so is every robot file in the repository's library, tests and examples.
Workaround
- Leave the solver unset in a chain's robot file (Alloy picks CG), or put
<option solver="CG"/>in it yourself. The 30-bead chain then lands and rests on the bench on the CPU withALLOY_CPU_ROUTE=warp: the world stays OK.sim.health()notes UNCONVERGED, the CG solver's residual, and PEN_WARN. - On the CPU, keep the default route (MuJoCo C).
- For a cable, cord or rope, use
scene.add_rodrather than a chain of bodies in a robot file.
Planned fix
Done after 0.1.1 for robot files that leave the solver unset (above). Not planned: re-stepping a world on CG when the Newton solver's pivot guard fires. The breakdown itself is in MuJoCo Warp's Newton solver.
Shipped robots left with no targets move away from their start angles¶
What is wrong. A shipped robot added with scene.add_robot(...) and stepped with no targets does not keep the
joint angles it starts at. Two causes, one per robot family:
- The start is outside a joint range (the Franka arms). alloy.build starts a robot at joint angles 0, and on these
arms 0 is outside the range of joint 4 (and of joint 6 on the FR3). The joint limits push those joints into range
in the first 0.2 s, and the servos, whose default target is also 0, then press them against the limit.
- Position servos sag under gravity (the legged robots, the humanoids' arms). A position servo holds a joint by
its error: under a steady load the joint settles torque / kp away from its target. With the source files' gains
that is up to a few degrees.
The health checks do not flag either: sim.check()["ok"] is True in every case below.
The number. Largest |q(2 s) - q(0)| per joint, one world, CPU, 10 ms control steps, no targets; the same to four digits on the MuJoCo C and the MuJoCo Warp routes (and with or without the C extension).
| pack | joint | moves | cause |
|---|---|---|---|
emb_e1_fr3, emb_e4_fr3_bimanual (each arm), emb_e5_fr3_duo (each arm) |
joint 6 | +0.439 rad | start 0 below its range (0.44 to 4.62 rad): pushed to the limit, 0.43 rad of it in 0.1 s |
| same | joint 4 | -0.117 rad | start 0 above its range (-3.08 to -0.117 rad) |
emb_e2_panda |
joint 4 | -0.070 rad | start 0 above its range (-3.07 to -0.070 rad) |
emb_e8_go2 |
rear / front calves | -0.147 / -0.119 rad | the 15 kg body on kp 50 servos (Menagerie's gains): the base settles from 0.288 to 0.264 m |
emb_e8_go2 |
thighs | -0.033 rad | same |
emb_e7_h1_2 |
elbows | 0.045 rad | the arms' weight on kp 80 servos (the source profile's): torque / kp = 0.046 rad |
emb_e7_h1_2 |
shoulder pitch, wrist pitch | 0.028, 0.011 rad | same, kp 120 and 40 (torque / kp 0.032, 0.011 rad); the passive thumb joints follow their mimic parents (0.028 rad) |
emb_e6_g1 |
ankle pitch, waist pitch, knees | 0.022, 0.020, 0.017 rad | kp 500 legs and waist under the body |
| The FR3 and Panda arms' other joints move under 0.002 rad. |
Why. The Franka packs keep the sources' joint zero, which is not inside every joint range; the start pose is
alloy.build's rule (joint angles 0), not the files' init keyframe. The sag is the sources' servo gains: a
real robot's controller adds a gravity feed-forward that these position servos do not have.
Workaround.
- Franka arms: send targets inside the joint ranges, ramped from the start (for example to the pack's init
keyframe, 0 0 0 -1.571 0 1.571 -0.785 on the FR3), before anything that depends on the arm's pose.
- Sag: read the joint state rather than assuming the target, or aim the target past the wanted angle by the sag (the
torque the joint carries divided by its kp, in the pack's scene.xml).
Planned fix. After the release tag the FR3 and Panda packs get a start inside their joint ranges (the joint zero
moved to the home pose, as for the Go2: docs/known_gaps/fr3-link5-link7-exclude.md). The sag is the sources' gains
and stays; no gravity feed-forward is planned.
The shipped Franka arms do not collide link 5 with link 7 (Panda: link 5 with the hand)¶
What is wrong. The FR3 packs (emb_e1_fr3, emb_e4_fr3_bimanual, emb_e5_fr3_duo and their _route /
_stiff variants) carry an <exclude> for the pair link5 / link7, and emb_e2_panda one for link5 / hand: these
bodies never make a contact with each other. The exclude was added because the arms start at joint angles 0, which
is outside the range of joint 4 on every arm (FR3: -3.08 to -0.12 rad) and of joint 6 on the FR3 (0.44 to 4.62 rad),
and there the two links' collision hulls overlap. It also covers poses inside the joint ranges in which the hulls
overlap: there the arm passes through itself with no contact and no health flag.
The number. At joint angles 0 the hulls overlap by 5.6 mm (FR3 and each arm of the bimanual), 42.7 mm (Duo,
link 5 with link 7's hand piece) and 30.2 mm (Panda, link 5 with the hand); at the packs' init pose none overlaps.
Of 20,000 random FR3 poses inside the joint ranges, 198 (1 %) overlap by more than 0.5 mm, the deepest 16 mm, all
with joint 6 at or below 0.66 rad and joint 7 turned far; the Duo is similar, up to 19.7 mm. Not established:
whether the real links touch in those poses (the hulls are convex pieces of the collision meshes), and the Panda's
share of poses (only joint 6 was swept).
Why. alloy.build starts a robot at joint angles 0, not at the file's init pose, and for these arms 0 is
outside a joint range. Without the exclude every scene with one of these arms started with a self-overlap.
Workaround. Keep joint 6 above 0.66 rad while joint 7 is turned far, or check the clearance of link 5 and link 7
along a planned motion yourself (mujoco.mj_geomDistance on the pack's scene.xml).
Planned fix. After the release tag the FR3 and Panda packs get a start inside their joint ranges (the joint zero moved to the home pose, as for the Go2), and the exclude is removed.
A weld or connect in a robot's MJCF is a stiff spring, not a rigid joint: limits of the stiff rule¶
What is wrong. A <weld> or <connect> equality in a robot's MJCF that sets no solref / solimp was
MuJoCo's soft spring: under load the two bodies came apart 2.3 mm per kN on a 9 kg pair. Since the default change
(alloy.build(scene, welds=...) left out is "stiff"), such rows take the stiff rule of scene attachments and hold
3-30 kN to hundredths of a millimetre. What is left: a weld is still a spring whose force stiffness falls with the
lighter body, it trails by a step-size error in motion, and welds="mujoco" (or a row written by hand) keeps
whatever the file says.
The number. Rig: a free 20 kg body welded to a 5 kg body on a slide, pulled sideways (the audit's ERR-11 rig;
tests/precision/test_weld_stiff_law.py), 1.25 ms rigid step, CPU, MuJoCo C and MuJoCo Warp alike:
| pull | welds="mujoco" (MuJoCo's row; the default before the change) |
default (welds="stiff") |
|---|---|---|
| 3 kN | 7.0 mm, JOINT_FAIL | 0.0015 mm, OK |
| 10 kN | 23.3 mm, JOINT_FAIL | 0.0051 mm, OK |
| 30 kN | 70.0 mm, JOINT_FAIL | 0.0152 mm, OK |
Both columns are the row's own compliance to within 2 % (the law): a row carrying a force F rests at
r = F W (1 - d) / (d² k), where W is the two bodies' inverse weights summed (0.117 per kg on the rig), d the
impedance (solimp) and k the stiffness from solref. MuJoCo's defaults (0.02 s, 0.9-0.95) give 2.0e-5 s² x W per
newton; the stiff rule gives 4.3e-9 s² x W at the 1.25 ms step, about 4,600 times less. The stiff rule's stretch grows
with the square of the rigid step (sim.routes() names the step).
In motion a weld also trails by a step-size error that stiffness does not remove. Over one step MuJoCo holds the
row's direction fixed, so a body carried around a curve at acceleration a keeps a small row velocity, and the row's
damping holds it off by B h a / (2 K d): about a h τ for a time constant τ, and (5/3) a h² under the stiff rule
(2.6 µm per m/s² at 1.25 ms). Measured on a 1 kg tool welded 0.4 m out on a link spinning at 2 / 4 / 8 rad/s (the
same law file): default 0.38 / 0.39 / 0.44 mm off (mostly the sag under its own weight), stiff 0.004 / 0.017 /
0.066 mm. A position servo whose target is ramped by sim.run(targets=...) gets a new target once per control
period. A stiff servo then kicks its link every period, and the weld follows those kicks with a larger error: 4.4
mrad and 1.8 mm on that rig at 4 rad/s, the same in plain MuJoCo with the same controls. A shorter control period
(alloy.Scene(dt=...)) makes the kicks smaller. On ordinary arms: the shipped
Franka Panda carrying a 0.5 kg tool welded to its hand peaks at 0.01 mm with stiff welds through slow, fast and
pick ramps, against 0.42-1.49 mm with the default rows, which already read JOINT_FAIL holding still (2.6 mm sag). A
light two-link arm on a very stiff servo (kp 20,000) does read JOINT_FAIL with stiff welds on fast ramps at
dt = 0.01 (2.0-2.2 mm; default 19.6-43.1 mm); at dt = 0.002 it peaks at 0.55 mm.
The stiff rule is stiff in acceleration, so in force a weld is as stiff as its most mobile body lets it be: about
ω² / ((1 - d) W), which is 0.36 / (h² (1 - d) W), or 2.3e8 / W N/m at 1.25 ms with W in 1/kg. The 9 kg pair
above holds 2e9 N/m. A 1 kg body welded to a 1 g carrier (W = 334 per kg) holds 6.9e5 N/m: 0.02 mm under 10 N at
1.25 ms, 0.33 mm at a 5 ms step. A 1 t body hung from that 1 g carrier is outside what a weld row can do: it sags
about 0.1 m and swings, against 5-7 m with MuJoCo's default row. For such a pair, make the heavy body a child of the
carrier (Workaround). The stiff rule costs nothing measurable: 1,024 and 4,096 worlds on one L4 step equally fast (within
0.5 %, three alternating runs), and the solver takes the same single iteration per step.
Where the weld point is matters. In MuJoCo a weld's anchor is a point of its second body, so
<weld body1="b"/> (second body: the world) anchors at the world origin, and a load on b far from that point is
held by the weld's rotation rows: a 20 kg body 0.6 m from the origin moves 0.58 mm under 3 kN with stiff rows (the
same in plain MuJoCo; MuJoCo's default row goes unstable there), against 0.0007 mm with anchor at the body
(<weld body1="b" anchor="0.1 0 0.6"/>) or written <weld body1="world" body2="b"/>.
A weld's rotation rows follow the same rule and are just as limited by the bodies' rotational inverse weights, so a moment shows as an angle first: five 1 kg boxes welded in a 1 m cantilever bend 0.4 mrad under their own weight and 1.7 mrad with 50 N at the tip (JOINT_FAIL from about 25 N), while their weld points move 0.001 mm; released, they are back to 0.0004 mm. MuJoCo's own rows let the same cantilever fall 0.78 m.
How health reads it: JOINT_FAIL (DEGRADED) above 1 mm or 1 mrad for an MJCF weld, which health judges both as a loop joint at that flat floor and as a row at its own limit. On a ramped arm the angle can trip first: a tool welded 0.3 m out on a kp 2,000 link ramped 1.5 rad in 0.5 s peaks at 0.29 mm and about 1 mrad with stiff rows. The stiff rows read far below both. JOINT_FAIL counts here are from a tree with the flag's hold between checks (since e21f29f28).
Why. It is MuJoCo's soft-constraint model working as specified, at defaults chosen for a 2 ms step and light
loads; nothing is wrong in the step or the solver (plain MuJoCo C gives the same numbers). Alloy's stiff rule for
attachments (alloy/scene/weld_impedance.py: stiffness set from the rigid step, impedance 0.999) was never applied
to equalities that come in through a robot file.
Workaround.
- Nothing to do for the common case: leaving welds out gives the stiff rule. Rows that write their own solref or
solimp stay as written (a row written out as exactly solref="0.02 1" solimp="0.9 0.95 0.001 0.5 2" counts as
a default); welds="mujoco" keeps every row as written. alloy.load(path), the command line and the Gym
environments build with the default.
- For a heavy body on a light carrier, or wherever even microns matter: do without the equality. Make the second
body a child of the first in the MJCF, with no joint between them; it then moves exactly with it
(docs/guide/robots.md, Grasping).
- Anchor a weld to the world at the body: <weld body1="world" body2="b"/> or anchor= at the body's position.
Planned fix. None for the rows: the remaining limits are those of a soft-constraint step (smaller steps, or a tree joint instead of an equality, remove them). A public call that attaches or welds an object while a simulation runs is separate and not built (grasp-no-attach-or-weld.md).
The shipped task_bin200 pile starts with 54 capsule pairs 8 mm inside each other¶
What is wrong. library/robots/task_bin200 (200 capsules in a bin) starts from a recorded layout in which 54
pairs of capsules overlap. They push apart in the first steps, so the pile moves at the start although nothing was
dropped, and health reports the overlap: START_PEN at the start and PEN_WARN (deeper than 1 mm) until the pile has
relaxed. The world is DEGRADED during that time, never INVALID.
The number. 54 pairs start 7.97 mm deep (the deepest: o158 with o194). Measured on the CPU's MuJoCo C route:
6.57 mm after the first step, 0.79 mm at 0.05 s, under 1 mm for good after 0.89 s, 0.02 mm at rest (4 s). The depth
never reaches 1 cm. The other bin packs (task_bin10, task_bin50, the box bins) are dropped piles that start
without overlap. Not measured: this pack on MuJoCo Warp.
Why. The layout is the recorded one (trace r5), kept so that the pack and its trace match the recording. The recording's own contact model let the capsules sit that deep.
Workaround. Let the pile relax before measuring: sim.settle(1.0) runs 1 s and makes the relaxed pile the state
sim.reset() returns to. Or start the measurement after 0.9 s.
Planned fix. After the release tag the relaxed layout becomes the pack's start, and the trace and its goldens are made again from it.
Known gap: a MuJoCo body's coupling proxy carries an isotropic mass, heavier than the body along its moving axis¶
What
- A MuJoCo body coupled into another solver (VBD cloth, SPH, MPM) is represented there by a proxy with one scalar
mass and inertia:
1 / body_invweight0. - MuJoCo's
body_invweight0is trace(W)/3, where W is the body's 3x3 translational (or rotational) block of J M^-1 J^T at qpos0. - So in the other solver a body that moves along one axis responds as if it were 3x heavier along that axis (a slider, the tip of a hinged body; 1.5x with two free axes): a contact there pushes it back less than MuJoCo then moves it.
- What is sized from the proxy mass no longer reads it (2026-11-07): the exchange clock's interface bound
sqrt(m / k_c), the strong-pair mass and the exchange stiffness cap c·m / dt_x^2 take the body's mass along its most
mobile axis, 1 / lambda_max(W) (
alloy.coupling.axis_mass, lawtests/coupling/test_axis_mass.py). The gap left is the proxy's own dynamics in the destination.
Number
- A 1.5 kg body on one prismatic joint gets a 4.5 kg proxy. A 1.2 g hinge tip 5 cm out gets 3.61 g, against 1.20 g along the direction it moves.
-
In C7's two-pad gripper each pad is 0.56 kg on a jaw slider under a 1 kg vertical carriage: a 1.329 kg proxy, 0.56 kg along the jaw, 2.12 kg along the carriage. Its clock bound was 1.15 ms on the 1.329 kg; it is 0.75 ms on the 0.56 kg now. The CPU coupling suite (136 tests) passes unchanged.
-
What it changes in a coupled contact (CPU Warp route, 2026-11-09, with the momentum-consistent feedback of
alloy.coupling.record_momentum; measured with a development rig, not shipped): a 0.515 kg platen over C3's free 16 g silicone pad, mid-air, as one MJCF body whose joint alone changes: one vertical slider, a hinge 5 cm from its centre of mass, and three slides (an exact proxy with the same contact, the slider's twin). - The proxy's answer to a force along the axis the body moves on is 0.333 of the body's own: 0.647 against 1.941 per kg (slider), 0.571 against 1.712 per kg (hinge). Across that axis the proxy answers at the same 0.333 where the body does not move at all.
- In the first exchange of a contact the slider's proxy gives way 16.1 mm/s where its exact twin gives 65.0 mm/s (0.25x: steeper than the mass ratio).
- Over a whole impact at 0.1 m/s the pad's momentum is 4.0 % (from touch) and 0.6 % (from a 1.7 mm flight) below the twin's. The same exact scene moved 0.3 m up changes by 1.4 % and 5.3 %, so this end-to-end number cannot tell the proxy's mass from float32 position noise. The pair's momentum closes in every run.
- Withdrawn: this page said "+3.5 %" for the slider against a free box (2026-11-08). That compared an
add_boxbody with an MJCF geom, which make different contact; it did not measure the proxy's mass. - Bodies light enough for the error to grow (a 1.2 g hinge tip or a 20 g box on that pad) are a strong pair and run the ADMM coupler, which does not use this proxy.
Why
- trace(W)/3 is the least-squares isotropic fit of W (argmin_a ||aI - W||_F). One scalar cannot match a body whose mobility differs by direction.
- A proxy at the most mobile axis's mass was tried and withdrawn. It scales
body_invweight0by 3·lambda_max/trace, which makes the proxy too light in every other direction. - In a cloth clamp test at the same 0.521 ms exchange step, that variant made the clamp bounce: gap spread 0.72 mm and an 18.2 N force peak, against a 1.2 mu N limit of 15.1 N. The isotropic fit gives 0.0013 mm and 12.5 N.
- The cause is the pads alone. Their proxies dropped from 1.33 to 0.56 kg, while a pad really carries 2.12 kg along the carriage that drags it.
Opt-in fix for VBD (phase 1): ALLOY_PROXY_TENSOR=1
- With
ALLOY_PROXY_TENSOR=1set beforealloy.build(orScheduler(proxy_tensor=True)at the engine layer), a MuJoCo body's proxy in VBD (cloth, soft bodies, rods, film) moves with a 3x3 inverse mass: the body's own W, kept in the body's frame and turned with it. Off by default; with it off the build steps the same kernels on the same inputs (three coupled scenes compared bit for bit against the tree without the change). - The scalar 3 / trace(W) stays for every gate, clock, stiffness cap and solver seed.
- Set it through the environment variable when the build uses
rerun_worlds=orprocesses=: their side simulations read the variable, not the engine-layer argument. - Law
tests/coupling/test_proxy_tensor_law.py(CPU, MuJoCo Warp route, 0.156 ms exchanges), each case on the scalar and on the tensor. A known force along the moving axis of a 0.515 kg platen on one slider, and of the same platen on a hinge 5 cm from its centre of mass: the scalar proxy answers 0.333 of its body's answer (0.647 against 1.941 /kg, 0.571 against 1.712 /kg), the tensor within the law's 10 %. Across the axis the scalar answers 0.333 where the body cannot move, the tensor within 10 % of zero. In the first contact exchange VBD pushes the slider's scalar proxy back 0.248 as far as its exact twin's (16.1 against 65.0 mm/s), the tensor's as far within 10 %. Free bodies stay exact. 29 pass; the 5 scalar cases are the strict xfails that keep this page. - C7's clamp at the 0.52 ms exchange step, the case the most-mobile-axis scalar failed (limits: gap spread under 100 um, peak force under 1.2 mu N = 15.12 N). Scalar, then tensor: 3 mm drag, gap spread 1.1 -> 1.3 um, peak 12.48 -> 12.50 N; 3 mm the other way 2.2 -> 2.0 um, 12.56 -> 12.51 N; 0.5 mm drag 0.39 -> 0.32 um, 6.04 -> 6.54 N; 0.5 mm the other way 0.47 -> 0.22 um, 12.53 -> 12.54 N. No pass-through. The same holds with the floor below at 10 and at 1,000 (largest spread 2.6 um, largest peak 12.58 N). One row depends on the floor: the 0.5 mm drag's peak is 6.04 N scalar and 7.60 / 6.54 / 6.71 N at 10 / 100 / 1,000. Which is closest to the bodies' own clamp force at that closure is not measured yet.
- A lone pad dragging a cotton sheet carries it 97 % of the pad's travel (scalar 99.8 %; the law asks 90 %). A film pinch carries 49.4 of 50 mm either way.
- A scene whose coupled bodies are all free (a box on cloth) keeps the scalar path with the switch on, bit for bit: a free body's W is already I / m.
What phase 1 leaves open
- Two pads dragging one flat sheet is not a usable check of the tensor. The sheet's travel there is set by
VBD's unconverged friction, not by the proxy: of the pads' 8.6 mm it follows +1.7, +0.8 and -1.7 mm at 10, 20 and
40 iterations with the scalar, -0.0, -0.8 and +0.8 mm with the tensor (floor 100), and +0.6, -0.0 and +3.0 mm at
floor 1,000.
tests/coupling/test_pad_drag_law.pyasserts no travel there for that reason. - The sewing ply pinch (
tests/tasks/test_sew_ply_pinch.py, two 0.2 kg pads on two 0.61 mm muslin plies with 10 mm cells) runs the same with the switch on as off. Pressed at 30 N it passes its law (the plies rise at least 40 % of the pads' 10 mm lift). Pressed at 100 N the plies stay on the table either way (-0.94 mm on, -0.93 mm off:docs/known_gaps/sewing-pinch-heavy-press.md). The rig's first version passed at 100 N with the switch off (96 %) only because its pads slid 0.3 mm off the edge of a vertex row and sank between the vertices to the table. The tensor holds the pads where MuJoCo holds them, so with it on that version failed. Its re-cut seats the pads on a vertex row. - Locked directions keep a floor. W of a body on one slider has rank 1, and VBD's body solve needs its inverse.
Each eigenvalue is kept at 1/100 of the largest or more (
ALLOY_PROXY_TENSOR_KAPPA, default 100): across its axis a slider's proxy still gives way 1 % as much as along it. - W is the one at qpos0, turned with the body. That is right when the mobile axis is the body's own (a hinge
tip) or the body does not turn. It is wrong in direction when the axis is fixed in an ancestor and the body turns
against it: a 0.2 kg pole on a 1 kg sliding cart answers a push along the cart's slide at 4.99 /kg upright, proxy
and body alike; turned 90 degrees the body answers 0.83 /kg and the proxy 0.050 /kg (17x too heavy; the scalar is
2x too light there). The floor bounds the error: at
ALLOY_PROXY_TENSOR_KAPPA=10the proxy answers 0.50 /kg (1.7x too heavy). The same holds for a wristed finger on a gantry and for any arm far from its start pose. Pinned as an expected failure intests/coupling/test_proxy_tensor_host.py. - A force off the centre of mass of a hinged body. The translation-rotation block of the 6x6 W is dropped, and the proxy's inertia stays Newton's isotropic fit: such a contact is closer than before, not exact.
- Liquid (SPH) and sand or paste (MPM) still move the proxy with the scalar mass.
- GPU: not run yet (the build warns). A model with tendons keeps the scalar path. Set the flag before the first step; a captured CUDA graph keeps the kernels it was captured with.
Workaround
- None needed for stability: the clock, the strong-pair class and the cap already use the axis mass.
- For a proxy whose response along its moving axis matters (a light slider pushed by cloth or liquid along its axis), expect the other solver to move it about trace(W)/(3·lambda_max(W)) as much as MuJoCo would (1/3 on one axis); check the source body's motion, not the proxy's.
Planned fix
- Phase 1 (VBD) is in as the opt-in above. It becomes the default when its law passes on the GPU too, the two-pad drag is no worse than the scalar's, and a decision is made.
- Phase 2: the SPH body integrate and harvest. Phase 3: MPM's collider IJtm and rewind. Each reads the same tensor
(
alloy.coupling.proxy_tensor) and gets its own law first. - Later: W per exchange instead of at qpos0, and the translation-rotation block.
Cloth and film¶
A free strip of cloth bends about 35 % too soft along a mesh axis¶
What is wrong
- A cloth sheet (
add_cloth, the VBD cloth route) that bends freely along one of its mesh axes bends as if its rigidity were about 0.64 of its material card'selastic.bending. - A strip clamped level at one end droops too far under its own weight (the textile cantilever test). At a free length L of 1.5 bending lengths on a 12-cell mesh the tip hangs 0.57 L below the clamp. Hinges of exactly the card's rigidity on that mesh would give 0.43 L (+34 %). The smooth elastica gives 0.37 L; the 14 % between the two is the mesh's clamp, which any hinge model has.
- So free cloth bending along a mesh axis bends more than its card says: an edge that hangs square to the grid droops further. Bends across the mesh diagonals are not measured as a droop; by the hinge energy of a uniform bend they hold about 1.1 of the card's rigidity (slightly stiff). Whether this carries part of the woven drape gap (docs/known_gaps/cloth-woven-drape-isotropic.md) is not measured.
- The strip is at rest and
sim.check()is ok. - Not affected, as far as measured: plates supported on their edges. The route's hinge map is fitted there, and converged square plates sag 0.99-1.02 x the Navier value. That is the route's existing coverage, not a new measurement.
Number
The scene (tests/solvers/vbd/test_fabric_bending_law.py): a strip along the mesh's x axis, the two vertex rows of
its first cell held, 12 cells free, free length L = 1.5 c with the bending length c = (D / (w g))^(1/3). D is the
card's elastic.bending and w the areal mass. It hangs in still air (a drag that is critical for the first bending
mode and zero at rest) for 0.4 s. CPU, one world, dt 0.01 s, default cloth accuracy, read at rest (under 1 mm/s).
References, from the card's D, its areal weight and g only: the heavy elastica D θ'' = -w g (L - s) cos θ, clamped
level, tip drop 0.3735 L; and the exact rest of the mesh's own hinge chain (rigid links, a hinge of D / cell at
every node), 0.4261 L at 12 links and 0.3998 L at 24.
| strip | tip drop / L | against the hinge chain |
|---|---|---|
cotton_woven (D 1.98e-5 N m, 300 g/m², c 18.9 mm), 30.7 x 7.1 mm, 3 cells wide |
0.5705 | +33.9 % |
cotton_woven, 12 cells wide |
0.5658 | +32.8 % |
cotton_woven, 36 cells wide |
0.5653 | +32.7 % |
cotton_woven, 24 cells along the free length |
0.5535 | +38.4 % (chain 0.3998) |
cloth_polyester_woven(D 3.43e-6 N m, 158 g/m², c 13.0 mm) gives 0.5696. It is the same strip in bending lengths, so it shows the result does not depend on the card, not a second measurement of the error.cloth_accuracy="super"gives the same drop within 0.0002 L (measured on a 16 x 4 cell mesh).- On Newton 1.8, the engine's next vendored update, the two fabrics give 0.5706 and 0.5697.
- Read as one rigidity on the chain, the drop is that of 0.64 D at 12 cells and 0.62 D at 24.
- On the chain, half the card's rigidity would give 0.6506 L and twice would give 0.2371 L.
Why
- It is the rest state of the hinge energy, not the solve. More iterations give the same drop, and the hinge moments balance the weight's moment at every column of the mesh (0.99-1.04).
- The route writes each hinge as
edge_ke = 0.75 D L / (A1 + A2). On the alternating right-triangle grid only the hinges across the bend carry a bend along a mesh axis, so they hold 0.75 D. The 0.75 is fitted to plate sag, where the diagonal hinges carry the rest. The chain at 0.75 D gives 0.5204 L: most of the gap is this, by design. - That is not all of it: the engine's 0.5705 L is the chain at 0.64 D. With the map at 1.0 (the hinges scaled by 4/3) the tip hangs 0.48 L at 12 cells and 0.46 L at 24, against the chain's 0.43 and 0.40.
- In the rest state the vertex rows zig-zag across the width (about 12 µm on the 7 mm strip), and the strip turns more at each column than the hinges there read: 4 % more at the clamp and 15-22 % more at the next four columns. This was measured on one mesh. That the zig-zag is the cause of the rest is not proven.
Workaround
- None in
add_clothitself: it has no bending setting. - For a sheet that bends freely along a mesh axis only (a strip, an edge that hangs square to the grid): copy the
material card into your own root (
<root>/materials/<name>.yaml,alloy.Scene(roots=[<root>])) withelastic.bendingx 1/0.6. Measured on the cotton cantilever above, on that mesh only: the tip hangs 0.408 L, 4 % under the chain of the true rigidity. - The cost: the hinge stiffness is linear in the card's value, so plates, which are right today, then come out 1.67x too stiff, and a bend across the mesh diagonals holds about 1.9 of the card's rigidity (by the hinge energy, not a measured droop). Do not use it for a sheet that drapes in two directions.
Planned fix
- A hinge map that holds in free cylindrical bending as well as in plate sag. Not scheduled.
- Until then
tests/solvers/vbd/test_fabric_bending_law.pykeeps the hinge-chain law as a strict expected failure and pins the present droop within 3 %, so a change of the hinge stiffness of about 5 % either way fails.
A stiff sheet on the VBD cloth route sags far too deep¶
What is wrong
- A sheet of a stiff material on the cloth route (
add_clothwith PET, nylon, polypropylene, corrugated cardboard, or a metal without a yield law: bending length over 5 cm) is far from converged at the default 40 VBD iterations. It sags several times too deep between supports, and a thin one can slide off round supports into the gap. - Since 2026-11-08 such a sheet starts each step from Newton's inertial guess (
alloy.scene.stiff_sheet). The fabrics' adaptive start gained energy on it: it climbed and never came to rest. It now loses energy and comes to rest, but it still sags too far. sim.check()andsim.health()read OK either way.
Number
Sheets dropped 5 mm onto two 1 cm round supports 10 cm apart, a 20 x 10 cm sheet, CPU, 3 s:
| sheet | plate theory sag | inertial start (shipped), 40 it | adaptive start (before), 40 it |
|---|---|---|---|
| corrugated cardboard, 3 mm | under 0.1 mm | rests, centroid 2.6 mm low, lowest point 12 mm below the support tops | 0.45 m/s at 3 s, walks |
| PET, 0.5 mm | about 0.3 mm | sinks into the gap (centroid 17 mm low), still sliding | climbs 28 mm above the supports, never rests |
At 400 iterations the PET sheet from the inertial guess nearly rests (0.013 m/s) with its centroid still 8.5 mm low. From the adaptive start it still moves at 0.37 m/s and walks 6 mm, so the pump is not only an effect of too few iterations. A dent-and-release rig (80 x 30 mm, round supports 40 mm apart) gives the same picture: about 18 mm mid-span sag for 0.5 mm polycarbonate and PET at every 40-iteration setting.
Why
VBD runs a fixed number of iterations per step. A stiff sheet's bending converges slowly (its stiffness is large against the inertia term m/dt²), so after 40 iterations the step result stays close to where the iterations started. From the inertial guess that is a step with all of gravity and too little of the bending, so the sheet sags. The fabrics' adaptive start keeps only the share of gravity each particle realised over its last step: dropped on the up-swing, kept on the down-swing, which on an unconverged stiff sheet feeds energy in. The library's fabrics (bending length 7-20 mm) converge at 40 iterations and need the adaptive start for their drapes.
Workaround
- A stiff part that only needs to bend a little: make it a rigid box with
rigid=True(without it a box of these materials goes to the cloth route too), at least 1.25 mm thick (the thinnest box the build accepts, at anydt) and with the sheet's own mass. The PET sheet above:scene.add_box("sheet", size=(0.2, 0.1, 0.00125), pos=(0, 0, 0.055625), material="pet", mass=0.0135, rigid=True). On the rig above (CPU) it comes to rest on the support tops, centred, withsim.check()ok, also when dropped from 10 cm; it does not bend at all. A thinner box raisesSceneErrornaming that limit: two thin rigid parts can pass through each other (a 0.5 mm plate dropped 5 mm onto a 0.5 mm shelf fell through it). - A metal sheet that dents: its yield law sends it to the film route (
plastic.model: j2), which handles stiff sheets. - If the sheet's shape matters, raise the iteration count. The sag falls with iterations; check one case against plate theory first.
Planned fix
None before launch. A stiff sheet needs a solve that converges its bending: more iterations scaled to the sheet's stiffness, or the film route for stiff sheets. A velocity-gated adaptive start (a development branch) took out the climb on its rig, but undid the drape's convergence (L5 drape: 4.5 % strain against 0.36 %), so it did not ship.
A woven fabric card from KES data drapes wrong on the VBD cloth route¶
What is wrong
- A cloth card built from a woven fabric's published KES-F data (areal mass, thickness, bending rigidity B) drapes differently from the same fabric on a Cusick drape tester, even when the solve is converged.
- With the shipped KES cards' convention (
cloth_cotton_plain,cloth_polyester_woven: youngs back-calculated from B at the KES thickness, noelastic.cloth, so the router sends it to CLOTH_VBD), a light polyester twill drapes too stiff (+0.08 to +0.12) and a heavy polyester/viscose plain weave hangs far too low (-0.28). A wool plain weave is within 0.05 on four of five meshes and misses on the fifth. cloth_accuracy="super"does not fix it. The DC is converged in iterations, so the gap is in the model, not the solve: membrane locking, the card mapping and the 2 mm contact thickness (Why, below).- The orthotropic membrane (Workaround) brings the twill and the wool within 0.035 on a warp / weft grid mesh, where
an
add_clothsheet gets it by default, and within 0.05 on a mesh that does not follow warp and weft (each triangle carries one yarn; a mesh sheet still needs the route override). The heavy plain weave still hangs 0.16 too low.
Number
D03M (bench/scenarios/fabric_drape*.py, pack bench/scenarios/packs/fabric_drape_petrak2021.json; its L4
result rows are not shipped) and the R6 law on the same data
(alloy.scene.twins.drape_route, dataset bench/rigs/R6.cloth_drape/petrak2021-v1). The data is Petrak, Mahnić
Naglić, Rogale and Geršak 2021 (Materials 14:6259): 30 cm specimens clamped between 18 cm discs, KES-FB inputs, each
fabric's measured DC the mean of 5 specimens. Alloy: the production route, one L4, 8 worlds per fabric, 8 mm mesh,
scored over the last 1 s of 4.5 s.
| fabric | measured DC | super (60 it), mesh seed 0 | 240 it | R6 law, super, mesh seed 7 |
|---|---|---|---|---|
| F1 polyester twill 3/1, 135 g/m², 0.41 mm | 0.222 | 0.302 (+0.080) | 0.315 (+0.093) | 0.342 (+0.120) |
| F4 wool plain, 162 g/m², 0.44 mm | 0.319 | 0.306 (-0.013) | 0.319 (-0.000) | 0.381 (+0.062) |
| F9 polyester/viscose plain, 367 g/m², 2.42 mm | 0.647 | 0.365 (-0.282) | 0.368 (-0.279) | 0.365 (-0.282) |
The mesh moves these by up to about 0.08. Super on a square-grid disc: - 8 mm: F1 0.315, F4 0.367, F9 0.406; - 5 mm: F1 0.300, F4 0.340, F9 0.429. F1 and F9 miss on every mesh. F4's pass is not robust: on the R6 mesher's seed 7 the fold count, and with it DC, changes (2-5x the world spread of seed 0).
The opt-in orthotropic membrane (KES EM warp / weft stretch, KES G shear, KES B per hinge direction; super, 8 worlds, 2026-11-08):
| fabric | warp / weft grid disc, 8 mm, 60 it | same, 160 it | same, contact thickness T0 | R6 mesh (jittered hex), seed 7, T0, before the yarn split |
|---|---|---|---|---|
| F1 | 0.254 (+0.032) | 0.257 (+0.035) | 0.252 (+0.030) | 0.500 (+0.278) |
| F4 | 0.314 (-0.005) | 0.313 (-0.006) | 0.294 (-0.025) | 0.395 (+0.076) |
| F9 | 0.487 (-0.160) | 0.494 (-0.153) | 0.487 (-0.160) | 0.499 (-0.148) |
The same isotropic card convention on that grid disc: 0.315 / 0.367 / 0.406. With one yarn per triangle (2026-11-10)
the jittered-hex disc drapes F1 0.24-0.26 and F4 0.27-0.30 (two mesh seeds, 16 worlds each; Workaround).
DC is converged in iterations there. Measured at the end of the drape (8 worlds), the yarns stretch little: the
largest yarn strain |w| - 1 is 0.6 % at 60 iterations (99th percentile 0.08 %) and 0.03 % at 160. The largest edge
strain, 8 % at 60 iterations and 4.3 % at 160, is the grid's cell diagonals as the sheet shears. On F1, the lightest,
the local shear is not converged at 60 iterations: its 99th-percentile shear angle is 9.5°, against 2.2° at 160 (F4
and F9 about 2° at both). sim.health() does not flag shear, so raise the iterations before reading a woven sheet's
local shear.
The same fabrics with other isotropic membranes (super, 60 iterations; bending and mass unchanged):
| fabric | E h from KES shear G (E h = 2 (1 + nu) G) | E h from KES tensile (EM secant) |
|---|---|---|
| F1 | 0.217 (-0.005) | 0.730 (+0.508), 3 nodes |
| F4 | 0.251 (-0.068) | 0.724 (+0.405), 4 nodes |
| F9 | 0.440 (-0.207) | 0.590 (-0.057) |
Why
Measured (2026-11-08, L4, super, R6 seed-7 mesh, 8 worlds): the drape on CLOTH_VBD is set by the membrane's in-plane stiffness through locking, more than by the bending. - Under the drape's own loads a fabric stretches about 0.02 %, so a converged sheet would sit at its inextensible limit and its DC would hardly move with E h. On the 8 mm mesh it moves a lot. With the bending fixed, scaling the card's E h by 0.3 / 1 / 3 / 10 gives F1 0.225 / 0.347 / 0.564 / 0.714 (F4 0.269 / 0.370 / 0.508 / 0.720). At E h x10 a 6 mm mesh drapes lower than the 8 mm one (F1 0.587 against 0.714). - That is membrane locking: linear triangles cannot fold into a drape's doubly curved shape without stretching, so the stiffer the membrane, the stiffer the drape, and the mesh changes the answer. Scaling the bending by 0.72 moves DC by only 0.04-0.05. - The card mapping decides where on that curve a fabric sits. The convention above (E from B at the KES thickness) makes the membrane's shear stiffness 7x KES G for F1, and its stretch stiffness 17-42x below KES EM (F1). A woven fabric is stiff along its yarns and soft in shear between them, which no single isotropic E h matches. - The sheet's contact thickness matters too. The rig floors it at 2 mm (5x F1's 0.405 mm), and VBD's self-contact then keeps the folds from closing: 9 folds instead of 12. With only the thickness changed to T0 (E h kept, 16 worlds), F1 drapes 0.280 +- 0.006 instead of 0.355 +- 0.014, and F4 0.298 +- 0.003 instead of 0.365 +- 0.011. - The clamp is not the cause (a pinned rim and an unclamped specimen drape within the world spread), nor is the iteration budget (60 and 240 iterations agree), nor settling (9 s drapes as 4.5 s). - The orthotropic membrane does not lock on a grid whose edges run along warp and weft. Each triangle's two yarn conditions are then its two grid-edge lengths, about two per vertex against three degrees of freedom, so the sheet can shear into a drape like a real woven fabric (a Chebyshev net). On an irregular mesh each triangle adds two independent conditions, about four per vertex, and the stiff yarns lock harder than the isotropic membrane does. - F9 (2.42 mm, 367 g/m²) misses with every membrane. Its inputs match the paper's table. The paper's FAST bending (a cantilever, low curvature) is 2.3-2.8x its KES B for every fabric. As a diagnostic (not the pre-registered mapping), FAST bending on the orthotropic membrane drapes F9 within 0.02 (0.630) but F1 and F4 too stiff (+0.105, +0.079). So neither bending source fits all three: F9 bends stiffer at drape curvatures than its KES B, F1 and F4 do not (bending hysteresis, which Petrak does not report, is one candidate).
Workaround
- For the drape shape of a light, limp woven fabric, set the card's youngs from KES shear: E = 2 (1 + nu) G / h, with h
the sheet thickness you pass to
add_cloth. Here it was within 0.07 on F1 and F4. - For a heavy fabric whose hang matters, use the tensile stiffness (E = F / (EM h) from KES-FB1). It was within 0.06 on F9.
- Check one Cusick drape against a measured DC for your fabric before trusting a drape shape.
- For a woven fabric with KES data, use the orthotropic membrane:
- give the material card
elastic.cloth(stretch_warp and stretch_weft = KES load / EM strain in N/m, shear = KES G in N/m per radian, bend_warp and bend_weft = KES B in N m); - an
add_clothsheet (a warp / weft grid, warp along x) then routes tocloth_vbdwith the membrane by default, alone or beside other moving things;sim.routes()says so; - a sheet from a mesh needs the object card's route override
route: {route: cloth_vbd, reason: ...}. Without it the card routes to CLOTH_STYLE3D when nothing else moves and is refused at build beside other moving things (the error names the override). On a mesh without warp / weft edges each triangle carries one yarn, so it does not lock: on the R6 jittered-hex disc F1 drapes 0.24-0.26 and F4 0.27-0.30 (measured 0.222 and 0.319; two mesh seeds, 16 worlds each), as on the grid (0.26, 0.31). Before that split the same disc gave 0.49 and 0.43. The split keeps 1 % of each triangle's other yarn (none at all leaves free modes and the sheet blows up), and the drape depends on that number: F1 0.334 / 0.289 / 0.263 / 0.251 / 0.245 at 10 / 3 / 1 / 0.5 / 0.2 % kept. Youngs randomization of such a card is refused.add_cloth's default cardcotton_wovenis isotropic (youngs and poisson, noelastic.cloth) and is not changed by any of this;cotton_woven_anisois the woven one. The membrane route costs 1.9-2.5x the Style3D route it replaced on grid sheets (a 0.4 m sheet of 625 vertices on a box, 64 worlds, L4: 2,160 against 4,151 world-steps per second; a sheet alone, 1 s on the CPU: 121 s against 49 s), and the sheet drapes differently: on that sheet alone vertices end up to 0.13 m (mean 0.04 m) from where Style3D put them, with a peak edge strain of 8.3 % against 5.0 % (a benchmark audit, 2026-11-10). - CLOTH_STYLE3D is no alternative for these fabrics today. In one world, clamped or not, the Style3D sheet stays
nearly flat (DC 0.98-0.99): its solve locks when the KES stretch stiffness outweighs the inertia per step
(
cloth-style3d-stretch-lock.md).
Planned fix
The law is R6 / D03M: each fabric's DC within 0.05 of its measured value at
convergence. Next:
- F9: its bending at drape curvatures (FAST fits F9 but not F1 / F4; a KES 2HB for it would test the hysteretic
hinge, elastic.bending_hysteresis). A free strip also bends about 35 % too soft on the cloth route (0.64 D;
the cantilever law). With the cards' bending times 1 / 0.6 on the grid, F9 drapes 0.579
(-0.068), F1 0.285 (+0.063) and F4 0.360 (+0.041). So that softness is part of F9's miss, and F1 passes with
today's bending but would leave the 0.05 bar once the hinge map is fixed: the two get re-scored together then.
- Mesh sheets by default: woven cards on a mesh still need the route override (done for grid sheets).
- R6 at the fabrics' real thickness (the 2 mm floor).
Style3D cloth stiff in stretch for its step drapes slowly or stays flat¶
What is wrong
- A cloth card with
elastic.cloth(warp and weft stretch, shear, bending: it routes to CLOTH_STYLE3D) whose stretch stiffness is large for its mass, mesh and step barely bends out of plane: it creeps (about 2 mm/s) and stays nearly flat, whilesim.check()andsim.health()read OK. - Style3D solves each step with a fixed matrix built from the stretch and bending stiffness. When its diagonal outweighs the inertia term m/dt² by more than about a thousand per vertex, each iteration releases only a little of the out-of-plane motion.
Number
- Woven fabrics from KES-F data on a Cusick drape rig (Petrak 2021 F1 / F4 / F9,
alloy.scene.twins.fabric_rigarm A, 8 mm cells, 1.25 ms steps): ratio 9,700 (F1) and 2,900 (F9). They drape to DC 0.98-0.99, against measured 0.22-0.65. - Its own levers barely help (rim sag at 0.7 s):
| change | rim sag at 0.7 s |
|---|---|
| as built | -1.0 mm |
| 40 PCG iterations | no change |
| 40 nonlinear iterations | -3.8 mm (3.5x the wall time) |
| dt / 8 | -11 mm (7.5x the wall time) |
| stretch ÷10 (ratio about 1,000) | still locked, DC 0.949 |
| stretch ÷100 (ratio about 100) | drapes |
- The ratio grows as dt² / (areal mass x cell size²): a finer mesh or a lighter fabric locks sooner.
- The library's
napkin_cotton_anisobuilds at about 1,300, so it warns. Dropped 6.5 cm onto a 12 cm ball, it still hung 27 mm above the floor at 1.5 s; a 30 cm sheet ofcotton_wovenorcotton_woven_aniso(ratio 70) reached the floor. The napkin's own size differs, so this is a sign, not a measured lock.
Why
Style3D solves each step with a fixed matrix built once from the stretch and bending stiffness (projective dynamics).
When its diagonal outweighs the inertia term m/dt² by about a thousand per vertex, each of its iterations releases only
a little out-of-plane motion, so the sheet creeps instead of falling. Probes ruled out the card's units, gravity, the
clamp, bending and contact (bending ÷1000 leaves the sag unchanged). The build warns, with the ratio: "a Style3D
cloth (an elastic.cloth card) is stiff in stretch for its step" (alloy.scene.style3d_lock, threshold 1,000).
Workaround
- For a woven fabric's drape, give the card no
elastic.cloth. It routes to the VBD cloth, which drapes it, within its own isotropy limit (cloth-woven-drape-isotropic.md). - Check one drape against a measurement before trusting a Style3D sheet's shape.
- A coarser mesh lowers the ratio (cell size squared), at the cost of resolution.
Planned fix
None planned. A disclosed tensile cap on the Style3D route needs a decision (F9 at 0.651 against 0.647 with warp and weft capped, F1 0.347 against 0.222). Sources: probe notes, a ratio script and a write-up of 2026-11-08 (not shipped).
Cloth sheets falling onto each other can pass through each other¶
What is wrong
- Sheets dropped onto each other can end with the layer order broken: parts of an upper sheet below the sheet under
it.
add_clothsheets collide with each other (and each with itself) through VBD's self contact, which should keep them apart. - It was seen with several sheets released together over the ground, so each lands on the ones that landed before it.
- Nothing flags it:
sim.health()does not read INVALID, no contact was dropped for lack of room (no SELF_CONTACT_OVERFLOW), andsim.check()["ok"]stays True. - Sheets placed 2.5 mm apart and left to settle kept their order over the 0.15-0.24 s measured.
Number
CPU, the default cloth settings, main 03616d08c (2026-11-10). Cotton sheets of 16 x 16 vertices, 2 mm thick, 5 cm apart in height, released together over a ground plane. Measured per vertex column (the same grid vertex in every sheet) as the height difference to the sheet below; a column is crossed when that is 0 or less (an audit finding, not shipped):
| Sheets | Time reached | Crossed columns | Smallest gap | Self-contact rows used |
|---|---|---|---|---|
| 12 | 1.36 s | 27 | -10.5 mm | 24 / 46 of 32 / 64 |
| 20 | 0.95-0.99 s | 70-108 | -5.3 to -15.3 mm | 24 / 40 of 32 / 64 |
| 12, placed 2.5 mm apart | 0.24 s | 0 | 2.0 mm | - |
| 20, placed 2.5 mm apart | 0.15 s | 0 | 1.98 mm | - |
- The same with the self-contact rows sized to the scene (
docs/known_gaps/vbd-self-contact-buffer-overflow.md): no pair was dropped in either mode. - The fastest particle at the end of the 12-sheet run moved at 1.05 m/s, under the 3 m/s self-contact cap
(
docs/known_gaps/vbd-self-contact-speed-cap.md). Speeds at the moments of impact were not recorded.
Why
- Not traced yet. Ruled out by the rows above: dropped contact pairs (the rows never filled) and contact rows sized too small (the scene-sized rows give the same crossings).
- Open: how the sheets' impacts on the sheets below interact with the motion cap and the truncation that keeps self contact penetration-free, and whether the cloth's step or iteration count changes it.
Workaround
- None verified.
- To check a scene, compare neighbouring sheets' heights yourself (record
"<sheet>.points"and take, per grid vertex, the height difference to the sheet below); health will not report it. - A stack that only needs to rest can be placed instead of dropped: sheets 2.5 mm apart kept their order over the short runs above (not checked over seconds).
Planned fix
- Trace the crossings on the 12-sheet drop (which pairs cross, at what relative speed, before or after the truncation), then fix in the cloth self-contact path. Not before the 0.1.0 tag.
A rigid body smaller than a cloth cell can pass through the sheet¶
What is wrong
- A rigid ball whose radius is under about 0.7 of the sheet's cell size can go through a cloth or film sheet
(
add_cloth, routescloth_vbdandcloth_film) without touching it. The sheet stays where it was. - It happens with a kinematic ball pushed down onto the sheet. A free ball fell through in the audit; see Number.
- Nothing flags it:
sim.health()reads OK (or DEGRADED with UNCONVERGED on the aluminium sheet) andsim.check()["ok"]is True. - It depends on where the ball meets the grid. A ball right over a vertex pressed the sheet at every radius tried (down to 0.2 of the cell). A ball over the middle of a cell passed through below about 0.65 of the cell.
- The build warns when a rigid box, sphere, cylinder or capsule is under 2 cells across (a ball with R / cell under 1.0), naming the sheet, the bodies and the cell size that holds the smallest. It warns by size, wherever the body is, also when it never comes near the sheet. Bodies from a mesh and robot links are not checked.
Number
The scene: two static cylinders (radius 5 mm, length 0.12 m, axes along y, at x = -0.02 and +0.02 m, tops at
z = 0.05 m); a 6 cm x 6 cm sheet resting on them; a kinematic ball 0.5 mm above the sheet. Run 0.3 s, then
sim.drive("tip", velocity=(0, 0, -0.05), duration=0.3) and run 0.4 s: the ball goes down 15 mm. CPU, one world,
dt 0.01 s, thickness 0.25 mm. resolution counts cells, not vertices: 6, 13 and 24 give cells of 10.00, 4.62 and
2.50 mm (the median rest edge of the built grid). A ball that ends with its bottom within 2 mm of the sheet's centre
"pressed" it; one that ends more than 3 mm below the centre, with the sheet where it was, "passed through".
Ball over the middle of a cell (centre z in mm, before to after):
| sheet | cell (mm) | R (mm) | R / cell | sheet centre z | ball bottom z | verdict |
|---|---|---|---|---|---|---|
cotton_woven |
4.62 | 2 | 0.43 | 46.4 to 46.7 | 36.0 | passed through |
cotton_woven |
4.62 | 3 | 0.65 | 46.4 to 46.7 | 36.0 | passed through |
cotton_woven |
4.62 | 3.5 | 0.76 | 46.4 to 37.9 | 36.0 | pressed |
cotton_woven |
4.62 | 4 | 0.87 | 46.4 to 37.4 | 36.0 | pressed |
cotton_woven |
4.62 | 5 | 1.08 | 46.4 to 37.0 | 36.0 | pressed |
aluminium_6061_t6 (cloth_film) |
4.62 | 3 | 0.65 | 48.7 to 48.8 | 36.0 | passed through |
aluminium_6061_t6 (cloth_film) |
4.62 | 4 | 0.87 | 48.7 to 37.9 | 36.0 | pressed |
cotton_woven |
10.00 | 3 | 0.30 | 48.5 to 48.4 | 36.0 | passed through |
cotton_woven |
10.00 | 4 | 0.40 | 48.5 to 48.4 | 36.0 | passed through |
cotton_woven |
10.00 | 5 | 0.50 | 48.5 to 48.4 | 36.0 | passed through |
cotton_woven |
10.00 | 6 | 0.60 | 48.5 to 47.7 | 36.1 | passed through |
cotton_woven |
10.00 | 7 | 0.70 | 48.5 to 40.7 | 36.0 | partly (centre 4.7 mm above the ball) |
cotton_woven |
10.00 | 8 | 0.80 | 48.5 to 37.8 | 36.1 | pressed |
cotton_woven |
2.50 | 2 | 0.80 | 42.3 to 36.7 | 36.0 | pressed |
cotton_woven |
2.50 | 3 | 1.20 | 42.3 to 36.3 | 36.0 | pressed |
Ball over a vertex: every run pressed the sheet (sheet centre within 1 mm of the ball's bottom).
| sheet | cell (mm) | R (mm) | R / cell |
|---|---|---|---|
cotton_woven |
10.00 | 2, 3, 4, 5, 8 | 0.20, 0.30, 0.40, 0.50, 0.80 |
cotton_woven |
4.62 | 2, 3, 4 | 0.43, 0.65, 0.87 |
cotton_woven |
2.50 | 2, 3 | 0.80, 1.20 |
- Mid-cell threshold: the smallest R / cell that pressed is 0.76 at 4.62 mm cells (0.87 for the aluminium film) and 0.80 at 10 mm cells (0.70 was partial). The largest that passed through is 0.65 at 4.62 mm and 0.60 at 10 mm. At 2.50 mm cells the smallest ball tried (0.80) pressed, so no pass-through is measured there.
- On-vertex threshold: none found. The smallest ratio tried, 0.20, pressed.
- Every run here has
sim.check()["ok"]True. Health was OK, except UNCONVERGED (DEGRADED) on both aluminium runs. - The sheet started 0.3 mm above the cylinders, and the ball 0.5 mm above the sheet.
- Not measured: the default 2 mm thickness (in this layout the 2 mm cotton sheet fell off the supports to the ground before the drive, so that case is void); aluminium over a vertex; a free ball (below).
- Free ball: a free 2 g ball (radius 3 mm) on the 4.62 mm sheet did not finish its 1.0 s in 15 minutes on the CPU and was stopped, so it is not measured here. The audit saw a free 2 g ball of that size end on the ground, with the sheet unmoved (aluminium sheet, ball over the middle of a cell).
Why
- Cloth and film touch rigid shapes at their vertices only. Each vertex is a small sphere of half the sheet's thickness.
- There is no contact between a rigid shape and the inside of a cloth triangle. A body that fits between the vertices meets nothing.
- The largest ball that fits between the four vertices of a square cell has a radius of cell / sqrt(2) less half the sheet's thickness, 0.71 of the cell for a thin sheet. That is the measured edge: 0.65 passed, 0.76 pressed.
- A ball over a vertex meets that vertex and presses the sheet, at every size tried.
Workaround
- A finer
resolution, so that the cells are smaller than the body. The build warning's rule: cells at most the ball's radius, half the body's smallest extent. In the rows above R / cell of 0.76 to 0.87 already pressed over a cell middle, the worst case; only two cell sizes above 2.5 mm were scanned, so the rule keeps a margin. - The cost grows with the particle count:
resolutionr gives (r + 1)^2 vertices. Check the step time withalloy.estimatebefore a long run. - A larger tool tip, if the task allows it.
- Do not trust a small body on cloth with no check: read the body's z and the sheet's z after a short run.
Planned fix
- Contact between a rigid shape and a cloth triangle, so that a body between the vertices still meets the sheet. Not scheduled.
A folded cloth keeps moving under the default cloth accuracy¶
What is wrong
- When cloth plies rest on each other (a towel folded in thirds, a sheet folded in half), the stack does not come to rest under the default cloth accuracy. After the grippers let go, the plies keep creeping, where they should settle within a fraction of a second. Since the default holds self-contact particles out of the Chebyshev step (2026-11-09), the stack's height stays under the task's gate, but the plies still move at 0.03-0.06 m/s.
- How high the stack ends up depends on the draw. A 1 µm nudge to the start changes whether the task's 25 mm normal-extent gate passes. On the GPU, a repeat run is another draw, because self-contact sums with atomics.
- A single sheet resting on a body is not affected. A sheet draped on a stand settles: drape coefficient 0.728 at 0.36 % stretch.
Number
Measured on the thirds fold (alloy.tasks.laundry_fold.towel_rig("thirds")): the library terry towel at bath-towel
size, 700 x 450 mm, with self contact, dt 1.25 ms, one world.
- Each run's start is nudged by up to 1 µm in x-y per particle, from its seed. Seed 0 is the law's own start.
- The extent is measured at the law's point, 0.75 s after the last release.
- The speed is the mean particle speed 1.5 s later.
- Data: 2026-11-09, main 7f7e9a937 and F32 3057f60a7. Measured with a development script; its
rows for the spread, settle and proto runs are in the development notes (not shipped).
| solve | runs | normal extent at the law's point | over 25 mm | mean speed 1.5 s later |
|---|---|---|---|---|
| default (adaptive start, Chebyshev rho 0.9, 40 iterations) | 20, CPU + GPU | 12.7-39.0 mm | 8 of 20 (main alone 3 of 10) | 0.065-0.103 m/s (2 runs) |
| default at 100 iterations | 2, GPU | 28.9-34.5 mm | 2 of 2 | 0.075-0.122 m/s |
| Chebyshev off (adaptive start, 40 iterations) | 5, GPU | 14.0-24.8 mm | 0 of 5 | 0.003-0.059 m/s |
| prototype: self-contact particles not extrapolated | 4, GPU | 17.3-29.7 mm | 1 of 4 | 0.035-0.073 m/s |
| A CPU sweep, the default before 2026-11-09 | 8, CPU | 20.6-38.1 mm | 5 of 8 | 0.078-0.093 m/s |
| A CPU sweep, self-contact hold (the default since) | 8, CPU | 14.1-22.2 mm | 0 of 8 | 0.033-0.064 m/s |
The sweeps use the same starts and measure the speed as the
mean over the last 0.5 s of a 1.5 s settle.
- Since the float32 velocity fix (the VBD velocity no longer rounds to ulp(x) / dt; a cloth falls at g at every
substep), the same 8 starts under the hold read 2 of 8 over 25 mm, at 26.0 and 30.5 mm; two starts are at rest.
The thirds fold's 25 mm law is therefore an expected failure that may pass, with a hard guard at 35 mm
(tests/tasks/test_laundry_fold.py).
- 1.5 s after the law's point, 1 of 8 starts is over 25 mm under the hold, against 6 of 8 before.
- While the plies move, a single edge can spike. At the law's point the largest edge elongation is under 3 % on most
starts, but one start under the hold read 27 % for that instant (the fold law allows 30 %) and 0.5 % 1.5 s later.
Chebyshev off and the wider holds showed 9-14 % spikes too; the default before 2026-11-09 showed up to 6 %.
On one GPU start under the default, the extent swings between 31 and 57 mm for the whole 1.5 s. Particle speeds peak at 0.5-2.5 m/s throughout. A three-ply stack at rest is about 14 mm high.
Why
The cause is partly known.
- The default's Chebyshev step (alloy/solvers/vbd/accel.py) extrapolates each particle's iterate. It skips
particles held by a body, shape or attachment contact (AccelState.mark_held), but it still extrapolates
particles held only by cloth-on-cloth contact, which are the fold's plies. The extrapolation over-relaxes there,
and the plies keep moving. With Chebyshev off, no run fails the gate.
- That is not the whole cause. Holding self-contact particles out of the extrapolation (a prototype) helps
less than turning Chebyshev off. And with Chebyshev off, two of five starts still move at 0.03-0.06 m/s after
1.5 s.
- That leftover jitter is VBD self contact's own. A CPU sweep (4 starts per solve, 2026-11-09) found it in stock
VBD at 10 iterations, with no Alloy change: 0.067-0.089 m/s, no start at rest. A towel at rest reads 0.003-0.006
m/s. The adaptive start damps it rather than causing it. With Chebyshev off, 2 of 4 adaptive starts came to rest,
against 1 of 4 inertial starts at 40 iterations.
- More iterations do not help: 100 iterations under the default jitter as much as 40.
- VBD's collision damping feeds it. Self contact and cloth-on-body contact damp only on approach (soft_contact_kd,
Newton's default 10 N s/m). A run restarted a rested thirds fold for 0.5 s (one start, CPU), measuring the mean
speed over the last 0.25 s:
- under the old default: 0.061 m/s, and 0.022 at kd 0;
- under the hold: 0.021 m/s, and 0.0015 at kd 0, at rest;
- with Chebyshev off: 0.006.
Once a fold jitters, kd 0 does not stop it (0.057-0.061 m/s), and kd 100 makes it worse (0.113).
Workaround
- In the engine layer (tasks, rigs), turn the Chebyshev step off: the VBD solver kwarg
alloy_chebyshev_rho=None, e.g.towel_rig("thirds", vbd={"alloy_chebyshev_rho": None}). That gave 0 of 5 over the gate, at the default's 40 iterations. Some starts still creep (Why). - The self-contact hold (VBD solver kwarg
alloy_chebyshev_hold_self_contact=True) is incloth_accuracy"default" and "super" since 2026-11-09: 0 of 8 starts over the gate, against 5 of 8 before. The plies still move (Number). - Do not turn collision damping down for a whole fold (
model.soft_contact_kd): a rested stack calms, but the fold itself then fails its gates on some starts (Planned fix, step 3). cloth_accuracy="fast"also turns Chebyshev off, but it runs 10 iterations (12 % stretch on a drape), and it has not been measured on a fold.- Score a fold's height on its time average, or after a longer settle, and check particle speeds before trusting one frame.
Planned fix
The fix belongs in the accelerated cloth solve; it follows the 2026-11-09 launch. 1. Separate the jitter left with Chebyshev off from what Chebyshev adds. Done: the leftover is self contact's own (Why). 2. Fix both. Done for Chebyshev: the hold is the default since 2026-11-09. It passed the thirds-fold seed spread and the drape laws, CPU and L4. Wider holds did no better: one or three edge rings, 1 of 8 over the gate each; the whole sheet while it touches itself, 2 of 8. 3. Self contact's own jitter: collision damping is the lead (Why), but turning it down is not the fix. A CPU sweep ran the whole thirds fold from 8 starts:
| solve | fails a fold gate | at rest 1.5 s later (under 0.006 m/s) | mean speed |
|---|---|---|---|
| hold (the default) | 0 of 8 | 0 of 8 | 0.033-0.064 m/s |
| hold, kd 0.01 | 1 of 8 (extent 29 mm) | 3 of 8 | 0.000-0.057 m/s |
| hold, kd 0 | 3 of 8 (extent 37 mm; three-ply share twice) | 1 of 8 | 0.000-0.057 m/s |
| no hold, kd 0.01 | 3 of 8 (extent) | 1 of 8 | 0.002-0.065 m/s |
| no hold, kd 0 | 4 of 8 (hems outside three times; extent) | 1 of 8 | 0.001-0.065 m/s |
Less damping lets some starts rest, but the moving fold needs it: the hems land off the stack. Next: damping that stays on during the fold and does not feed a resting stack.
The thirds-fold extent law stays xfail (strict=False), citing this page, until the plies come to rest.
Known gap: folded T-shirt sleeves do not stay folded at the default mesh and contact stiffness¶
What
- In the fold-a-shirt task (
alloy.tasks.laundry_tee), two hands swing the cuffs of a flat T-shirt round its side seams onto the body, hold, and let go. The T-shirt is two cotton panels sewn at the side, sleeve and shoulder seams. - As the hands let go, both sleeves lie on the body.
- With the default rig (
TeeRig(): 20 mm cells, the cloth route's contact stiffness) they then spring part-way back off it and never lie flat. The task's settled gates fail. - With the fine rig (
FINE_TEE: 10 mm cells, particle contact stiffness 2e4 N/m, no contact damping) they stay: every gate passes. That rig is a GPU run (9,300 particles: about 7 min on one L4, about 11 h on one CPU core). - So this is not the fabric springing back. It is the mesh and the contact, see Why.
Number
One L4, plain-weave cotton (h 0.975 mm), 2.5 s swing, 0.5 s hold, the start nudged 1 µm per seed, settled gates:
| rig | starts that pass | sleeve inside the body (gate >= 90 %) | placement RMS (gate <= 45 mm) | normal-gap p90 (gate <= 25 mm) |
|---|---|---|---|---|
| default: 20 mm cells, contact 2e6 N/m | 0 of 6 | 8-92 % | 48-204 mm | 20-94 mm |
| 20 mm cells, contact 2e3 N/m, no contact damping | 0 of 2 | 59-100 % | 76-103 mm | 26-29 mm |
10 mm cells, contact 2e3 to 2e5 N/m, no contact damping (FINE_TEE: 2e4) |
18 of 18 | 100 % | 2-6 mm | 14-17 mm |
the same on cotton_single_jersey (2e3 N/m) |
7 of 8 | 100 % | 3-16 mm | 14-27 mm |
| 12.5 mm cells, jersey | 0 of 1 | 100 % | 10-12 mm | 21-29 mm |
| 10 mm cells, contact 2e3 or 2e4 N/m with the contact damping left on | 0 of 2 | 8-78 % | 100-220 mm | 1-27 mm |
| 10 mm cells, the route's contact | 0 of 1 | 13-100 % | 15-213 mm | 5-33 mm |
0 cloth crossings in every run with the self-contact hold (the cloth default). Stretch under 10 %. On the CPU the default rig reads the same way (2,360 particles: inside 41-100 %, 75-120 mm, 50-54 mm).
Why
- The mesh. Cells of 20 mm cannot crease tighter than about a 2 cm radius. While the hands still hold the cuff, the sleeve stands in a loop 4-6 cm high beside the fold line. On release that loop throws a plain-weave sleeve back out (inside 4-7 % with the plies otherwise at rest), and a jersey sleeve's cuff snaps back 6-8 cm. At 10 mm cells the loop is under 2 cm and the sleeve stays where it was laid.
- The contact. The route takes the particle contact stiffness from the material's bulk stiffness, 2e6 N/m here, against a vertex of 46 mg. The four plies then never come to rest: 3 s after release the typical particle moves at 3-5 cm/s and the sleeves at 0.1-0.5 m/s, mostly up and down, on plain weave and jersey alike, with the acceleration off and at 120 iterations too. Particles over 0.25 m/s, of 2,360: 199-331 at 2e6 N/m, 86 at 2e5, 14-30 at 2e4, 0-4 at 2e3. The contact's damping (Newton's 10) alone keeps a 2e3 N/m fold moving; with it off the fold rests under 1 cm/s. It is the pair that rests a fold, not the stiffness alone: on a towel folded in thirds (CPU, 8 starts, a development sweep) the route's 2e6 N/m with damping 10 ended 0.03-0.06 m/s short of rest on every start, 2e4 with the damping on failed a gate on 4 of 8 (the worst setting), and 2e3 with the damping off rested on all 8 (0.001 m/s, extent 11.9-12.1 mm, 0 crossings).
- Not the cause: the card's bending. An earlier version of this page blamed the plain weave's bending rigidity and the missing bending hysteresis. The jersey card with hysteresis keeps a sleeve inside the body better at 20 mm cells (93-100 %) but does not make it lie flat, and plain weave passes on the fine rig.
Workaround
- Use the fine rig's settings for a garment fold: cells of 10 mm or less, and on the engine model
soft_contact_ke = 2e4,soft_contact_kd = 0(alloy.tasks.laundry_tee.buildshows where). There is no public API setting for the particle contact stiffness yet. - Or score the fold as the hands let go (
TeeVerdict.release_gates), or keep the cuffs held until a later step presses the sleeves flat.
Planned fix
- The route's particle contact stiffness for cloth on cloth: a default from the fabric's own compression, not the bulk stiffness (the unsettled-fold gap, docs/known_gaps/cloth-fold-unsettled-default.md). When that lands the fine rig needs only its mesh.
tests/tasks/test_laundry_tee.pyholds both: the fine rig's fold as a GPU law, and the default rig's settled gates as a strict expected failure.
Cloth held by friction creeps out of a pinch below the Coulomb limit¶
What is wrong
- Cloth held between rigid pads or fingers by friction alone (
cloth_vbdroute) slides out slowly under a steady load, even when the load is well under the Coulomb limit mu N. A real pinch below that limit does not move. - The creep speed does not depend on the step size. It grows with the load: at half the limit it is about 0.3 x
friction_epsilon(2.9 mm/s with the default 1e-2 m/s), and at 0.9 of the limit about 0.7 x (6.8 mm/s). - Over seconds that is centimetres: a corner held for a 10 s carry at half the limit slides about 3 cm.
- Nothing flags it:
sim.health()reads OK.
Number
CPU, plain VBD (SolverVBDAlloy), main 8921e7718 (2026-11-10). A 4 x 12 cm cloth strip (1 cm cells, 1 g vertices,
no gravity) hangs between two static pads that press each of its top 15 vertices with 1 N per pad (mu 0.3, so a
limit of 0.6 N per vertex). A downward load on those vertices, ramped on over 0.1 s, at a fraction of the limit.
Creep speed over the second half of a 1 s run (development notes, not shipped):
| Load / limit | friction_epsilon |
Iterations | Stock creep | Smoothed law | With the stick |
|---|---|---|---|---|---|
| 0.25 | 1e-2 | 10 | 1.34 mm/s | 1.34 mm/s | 0.0000 mm/s |
| 0.5 | 1e-2 | 10 | 2.92 mm/s | 2.93 mm/s | 0.0000 mm/s |
| 0.7 | 1e-2 | 10 | 4.65 mm/s | 4.52 mm/s | 0.0000 mm/s |
| 0.9 | 1e-2 | 40 | 6.82 mm/s (0.5 s run), then off the pads | 6.84 mm/s | 0.0000 mm/s |
| 0.98 | 1e-2 | 40 | off the pads in 1 s | 8.59 mm/s | 0.0000 mm/s |
| 0.5 | 1e-3 | 10 | 0.36 mm/s | 0.29 mm/s | 0.0000 mm/s |
- At 0.9 the stock pinch crept about 7 mm in the first second, off the bottom of the pads, and the strip fell. With the stick its rows moved 3 um in all (the strip's own stretch) and then not at all.
- With
friction_epsilon1e-3 the friction term is ten times stiffer: at 40 iterations the stick holds 0.9 of the limit but slips out at 0.98, as stock does (the solve does not converge so close to the limit;rows_it40.txt). - Past the limit (1.3x) both slide out at the same kinetic friction: the drops after 1 s agree within 0.2 %.
- Coupled, per-vertex contacts (a gripper's two MuJoCo pads at 15 N on a hanging double towel, the lagged coupler, 10 iterations, a load of 0.3 of the limit on the 10-12 particles between the pads; a development script, not shipped): stock creeps 1.21 mm/s, every clamped particle drifting; with the stick 7 of 12 stay within 0.03 mm and a few at the pads' edges shift both ways, a mean of 0.19 mm/s. The force the coupler hands the pads equals the load in both (3.84 N against 3.82 N).
- Coupled, full-surface contacts as a gripper's fingers get them by default (a pad rig,
run_hold: two MuJoCo pads at 15 N, the route's VBD at 40 iterations,friction_epsilon1e-2, 1 s hold; CPU): stock at half the limit slides 2.99 mm and creeps 2.97 mm/s; with the stick 0.000 mm/s at 0.5 and at 0.9 of the limit (0.07 mm once, while the load comes on), and past it (1.2x) the cloth slides out of the pads as with stock.
Why
- VBD's friction is IPC's smoothed Coulomb law on the slip within one step, measured from the step's start. Below a
slip of
friction_epsilonx dt the friction grows smoothly from zero, so holding a load T needs a slip u with mu N (2 - u / eps_u) u / eps_u = T in every step: a creep of friction_epsilon (1 - sqrt(1 - T / (mu N))). - The smoothing keeps the solve stable. A smaller
friction_epsiloncreeps less but stiffens the friction term.
Workaround
- Opt in to stick friction:
body_particle_friction_stick=Truein the cloth's VBD entry kwargs, orALLOY_FRICTION_STICK=1in the environment for every VBD entry of a process (alloy/solvers/vbd/stick.py). - Each cloth vertex keeps an anchor on each of up to three shapes it touches, and its friction slip is measured from where it stuck, not from the step's start. The anchor moves only by the slip past eps_u, so a held vertex stays put below the limit and slides with the same kinetic friction past it. A full-surface contact (a gripper finger's edge or face against the cloth's faces) reads its corners' anchors, mixed by their weights.
- An anchor outlives its contact by 0.02 s, so a finger that chatters (lifts off and touches again) keeps it.
- No vendored change: the anchors shift the contact records' body velocity, so the coupler's feedback to a gripper sees the same friction as the cloth.
- A sheet on a moving plate goes with it as with stock friction (a 10 cm sheet on a kinematic plate, CPU;
development notes, not shipped): driven at 0.05 m/s it lags 0.33 mm (stock 0.35), at 0.3 m/s
11.3 mm (stock 11.3), and closes to 0 after the stop; tilted to half the friction angle it moves 0.29 mm while
tilting (stock slides 3.7 mm downhill) and then holds (stock creeps 3 mm/s). An early version of the stick let a
driven sheet fall behind at
friction_epsilon(10 mm/s); a law pins that. - Limits of the stick:
- a fourth shape on one vertex keeps the smoothed friction on that contact;
- at 10 VBD iterations a load past about 0.7 of the limit that comes on suddenly slips out with or without the stick (the friction solve does not converge from a far first guess); at the cloth route's 40 iterations it holds.
- Without the stick: a lower
friction_epsilonin the entry kwargs (1e-3 creeps ten times slower), or keep holds short.
Planned fix
- The stick by default for cloth, after the grasp law and the cloth environments pass with it (a planned decision).
A robot's friction pinch on cloth creeps, and lets go below its friction limit¶
What is wrong. Cloth held between two gripper fingers by friction alone slides slowly out of the pinch under any
steady load, and falls out before the load reaches the pinch's Coulomb limit (two faces x mu x the grip force). A
task that lifts, carries or folds cloth by a pinch can lose it. The library task that folds a towel,
ClothFold-v0, is marked experimental (docs/guide/envs.md).
The number. Two pads squeeze a hanging double layer of cloth at 15 N, through the robot coupling and the shipped
cloth solver (40 iterations), and a load is hung on the cloth's bottom row (CPU, 1 s hold;
alloy.coupling.pinch_hold.run_hold):
| load / Coulomb limit | 0.5 | 0.75 | 0.9 | 1.2 |
|---|---|---|---|---|
| slide speed, default friction | 2.97 mm/s | 5.05 mm/s | falls out | slides out |
| with stick friction (opt-in) | 0.000 mm/s | 0.000 mm/s | slides out |
A real pinch holds still below the limit and slides above it.
Why. The cloth solver's friction is smoothed Coulomb friction: the slip is measured from where the cloth was at the start of each step, so a held vertex under a steady load slips a little every step, at friction_epsilon x (1 - sqrt(1 - load / limit)): 2.93 mm/s at half the limit, against 2.97 measured. Near the limit the friction solve does not converge, and the cloth falls out early. cloth-friction-creep.md has the solver-level law.
Workaround.
- Stick friction, opt-in: ALLOY_FRICTION_STICK=1 in the environment, or body_particle_friction_stick=True in the
cloth entry's solver options (cloth-friction-creep.md). On the rig above it holds the
pinch still to 0.9 of its limit, with the full-surface contacts robot fingers get. Its effect on ClothFold-v0's
fold count is not measured yet.
- make("ClothFold-v0", grasp="attach"): an opt-in shortcut, not a friction grasp. While the fingers are closed on
the towel, the towel between them is held to a finger until they open, as cloth benchmarks grasp
(alloy.envs.cloth_attach). It is one-way: the gripper does not feel the towel's weight. On the rig above it holds
twice the friction limit (0.5 mm of give).
- Keep a friction grasp short: the creep is mm per second, so a lift and fold of a few seconds holds (ClothFold's pinch
held the towel in every world of every run).
- Judge the grasp by the cloth, not the fingers: record the sheet's points and check that they follow the gripper.
Planned fix. Stick friction is opt-in for now; whether it becomes the default is not decided yet (cloth-friction-creep.md). No date yet.
Cloth gripped by friction on a moving rigid body can slip on it right after the body reverses¶
What is wrong
- Observed with sewing plies without bending on a reversing feed dog, at the default 20 VBD iterations. In the drive strokes right after the dog reverses, the plies move 0.35-0.65 of the dog's travel and slip on its teeth.
- The friction the contacts record is 0.15-0.19 of mu N while it happens. The dog carries 99 % of the 40 N clamp, the foot never lifts, and no fold reaches the teeth. A converged clamp would not slip there.
- Whether a given reversal slips at 20 iterations is close to a threshold: a one-period change in the settle time turns it on or off, with either body feedback.
- With the body feedback that hands the bodies the momentum the cloth took (gaps-now #10a, record momentum, cacec9764), the slip goes away at 100 iterations. With the previous feedback (the records' force at VBD's last iterate), it is still there at 100.
- With the plies' measured (KES) bending, no slip was seen on this machine, at 20 iterations with either feedback or at 100 with the previous one. That is one machine, not a cure.
Number
CPU, Warp route, main 201bdc94a (2026-11-09). The machine is the plain-seam rig (alloy.tasks.sew_seam): two 0.61 mm
muslin plies on a 10 x 11 mm feed dog (pair mu 1.0) under a 20 x 12 mm foot at 40 N, one stitch per 0.2 s cycle,
reversed for the backtacks. Measured with three development probe scripts on this rig (not shipped).
- Feed of the cycles right after the first reversal, in stitch lengths, for plies without bending
(SeamSpec(bending=None)). "Momentum" is record momentum's feedback (main since cacec9764), "records" the previous
one. The settle is in 1/60 s periods (12 is the default):
| VBD iterations | settle | momentum | records |
|---|---|---|---|
| 20 | 11 | 0.58, 0.59 | 0.98 (no slip) |
| 20 | 12 | 0.97 (no slip) | 0.51, 0.51 |
| 20 | 13 | 0.86, 0.86 | 0.51, 0.51; 0.21 at the end reversal |
| 50 | 12 | 0.61, 0.65 | 0.45, 0.30 |
| 100 | 12 | 0.99-1.00 (no slip) | 0.92, 0.88, 0.90 |
| 100 | 13 | 0.95-0.99 (no slip) | 0.59, 0.85, 0.48 |
Every other cycle feeds 0.95-1.03. The seam check asks 0.7-1.15 in every cycle.
- With the KES bending (the default plies), records feedback, the cycles through the reversal feed 0.97-1.01 at both 20
and 100 iterations. Over all 22 cycles at 20 iterations, the momentum feedback feeds 0.98-1.00 and the records
feedback 0.87-1.01.
- In the slipping cycle (20 iterations, records feedback, settle 12, drive periods 3-7):
- the dog moves 0.38-0.54 mm per period and the plies 0.18-0.28 mm, both plies alike (they slip on the teeth, not on
each other); the next forward stroke loses 0.76 mm in one period;
- N_dog 52 -> 42 N, N_bed 0.3-0.6 N;
- friction use |F_t| / (mu N_dog) is 0.15-0.19 as a period mean and up to 0.55 in one exchange.
At 50 iterations it is the same with either feedback: the plies move at a third to half the dog's speed through
whole strokes, at a friction use of 0.12-0.18.
- The friction law: VBD's IPC friction reaches a use r at a slip speed of x * friction_epsilon, with (2 - x) x = r.
The rig's friction_epsilon is 1e-3 m/s (sew_ply_pinch.vbd_kwargs), so r 0.15-0.55 allows 0.08-0.33 mm/s. The
measured slip is 8-20 mm/s, and 45 mm/s in the worst period: 25-250 times more.
- The momentum books through the drive stroke: the records' force and the plies' momentum change differ by 7-11 N at 20
iterations, 3-5 N at 50 and about 2 N at 100, mostly along the feed. The records under-read the dog's push (about
3 N against the foot's measured 6.5 N sliding drag) while the stack moves steadily with it.
Why
- Not the friction law: its smoothing allows 25-250 times less slip at the recorded forces.
- Not a load split: the bed carries under 1 % of the clamp in the slipping strokes.
- Not a fold under the foot: the sole stays at 1.10-1.23 mm, and the highest ply beside the foot reaches 2.9-3.2 mm.
- An unconverged coupled solve: the slip comes in the first strokes after the dog reverses, and it is gone at 100 iterations when the bodies get the momentum the cloth took. With the records' force fed back, the bodies take impulses the cloth never did (the books above), and the slip stays at 100 iterations.
- The working guess for why the reversal and the missing bending matter: the solve's tangential iterate on the dog's contacts starts from the previous direction's state, and a cloth with no bending stiffness gives the iterate nothing that couples the particles across the teeth. Not yet traced.
Workaround
- Keep a cloth's measured bending (the material's KES values, or the route's defaults). Do not zero it to simplify a scene that grips the cloth by friction.
- In a task that grips cloth through a reversal, read the cloth's own motion against the gripper's per cycle (feed,
carry), not only at the end. If it slips at the default 20 iterations, re-run at 100 (
iterations=): with main's feedback the sewing rig then fed every cycle through the reversal.
Planned fix
- Trace the solve at the reversal: the per-iteration tangential residual and friction use of the dog's contacts in the first stroke after a flip, at 20 and 100 iterations. Then decide whether the cloth entry needs more iterations where a reversing body grips it (a contact-driven iteration count) or a better start for the tangential iterate. Not scheduled.
- Other cases this may also affect: robot pinches that carry cloth through a load reversal (ClothFold; not measured), and the 3-ply pinch (press, then lift). Its carry was 67 % when it was written. On main it is 25-54 % at 30.5 / 30.0 / 29.5 N (52 % at the test's 30 N, 25 % at 30.5 N, under the 40 % minimum). With the records feedback the stack is not lifted at all: -18 to -19 % at all three loads. Readers: sewing, cloth fold.
Cloth resting under its own weight away from the world origin grips harder than its friction says¶
What is wrong
- A VBD sheet that rests on a support under its own weight should slide when the slope passes its friction angle.
- On a table top at 0.75 m it holds, or creeps at a fraction of the right speed. This holds with
make_vbd(..., coarse_contact=True)too, which slides it correctly at z = 0. - The friction load of each light vertex comes out many times its weight, so friction is effectively several times mu for a sheet loaded only by its weight.
- Pressed contacts are not affected: a pad dragging the sheet across a table at 0.4 m or 0.75 m follows Coulomb as it does at z = 0.
Number
CPU, make_vbd (log barrier), 4 ms, 10 iterations. A 7 x 7-vertex sheet on 8.5 mm cells: 20 mg vertices, r 1 mm.
mu_eff 0.2, a 35 deg slope made by tilting gravity, 0.2 s. The block value is 80.4 mm. Measured on
wp11-coarse-contact on 2026-11-08, with development probe scripts (not shipped).
| table top | contact law | stock VBD | coarse_contact |
|---|---|---|---|
| z = 0 | log barrier | 0.17 mm | 81.9 mm |
| z = 0 | linear penalty | 0.06 mm | 80.9 mm |
| z = 0.75 m | log barrier | 0.16 mm | 10.5 mm |
| z = 0.75 m | linear penalty | 0.04 mm | 0.035 mm |
- Stock holds at every height. That is a separate gap: the slope test's stock xfail in
tests/solvers/vbd/test_coarse_contact.py. That law (mu 0.5, 0.4 s, block 128.7 mm) gives 128.0 mm with coarse_contact at z = 0 and 0.6 mm at 0.75 m (its strict xfail). - A plane tilted at the origin. Its normal coordinate mixes y and z of about 3 cm. Barrier with coarse_contact: 42.9 mm against 80.4 at mu 0.2, and 2.2 mm against 32.2 at mu 0.5.
- Per-vertex trace (penalty, tilted plane, 49 vertices). The normal converges to 1.9 nm by iteration 3. Then 8-14 vertices per iteration land 40, 80 or 160 nm deep. Their contact force is up to 250x the vertex weight, and the sheet's summed load is 15-30x its weight.
- The drag law at 0.4 m and 0.75 m (C7 pad, coarse_contact): 0.973 of the pad's travel, the same as at z = 0.
- Not yet measured on library scenes.
Why
- Positions are float32 world coordinates. A coordinate can only move in steps of its float32 spacing: 2 nm at 3 cm, 30 nm at 0.4 m, 60 nm at 0.75 m.
- The penalty's resting depth is smaller than that. It is about weight / ke = 2e-5 x 9.81 / 1.3e5 = 1.5 nm, so a resting vertex lands one spacing to either side of it:
- out of contact, the next solve pushes it tens of nm deep;
- in contact, its force is ke x depth (8 mN = 40x the weight at 60 nm).
- Friction follows that force. It is mu x the current normal force, so the sheet sticks.
- The barrier rests deeper, but on the tilted plane it shows the same quantized depths.
- Pressed contacts are unaffected: a pad pushing far more than one spacing x ke resolves fine.
Workaround
- When a result depends on cloth sliding under its own weight: put the support near the world origin (the table
top at z = 0, the sheet within a few cm of it) and use
coarse_contact=True(opt-in). - Otherwise, treat friction between a resting sheet and a support well away from the origin as an upper bound.
Planned fix
- A follow-up, not started. Candidates:
- take each vertex's friction load from its normal momentum balance (resolution m / dt^2 x spacing, under 1e-3 of the weight) instead of the contact law's force;
- give VBD positions a per-object origin.
- After step 3's regression list.
A cloth particle that starts a step inside a rigid contact is thrown out at its depth / dt¶
What is wrong
- A cloth particle that starts a step inside a rigid object's contact distance leaves it at about the depth the step pushed it out by, divided by the step. How stiff the contact is does not matter.
- Small steps make it large: robot fingers coupled to cloth step the cloth at 19.5-39 us, where 0.5 mm of depth is 18.7 m/s.
ClothFold-v0's friction pinch is where it shows. As the closing fingers squeeze the gathered towel corner, a corner particle is thrown at 14-33 m/s and SPEED_FAIL marks the world INVALID (frozen), in about 40 % of the worlds of the pinch-and-lift repro.- The health report names the fastest gripper body with that speed, not the particle. In 19 of 23 such resets every gripper body was under 3 m/s.
Number
One 60 mg particle (1 mm radius), started inside a static box, no gravity. CPU, make_vbd's defaults (log-barrier
contact), contact stiffness 2e6 mixed with the box's 2.5e3. Main 816eca76e, 2026-11-10; a development
probe, not shipped.
| Start depth | Step | Leaves at | Depth / step |
|---|---|---|---|
| 0.12 mm | 20 us | 3.4 m/s (5.2 with Newton's linear penalty) | 6.0 m/s |
| 0.17 mm | 39 us | 3.4 m/s | 4.4 m/s |
| 0.17 mm | 20 us, 40 iterations | 5.3 m/s | 8.5 m/s |
| 0.5 mm | 20 us | 18.7 m/s | 25 m/s |
| 0.8 mm | 20 us | 31.6 m/s | 40 m/s |
- The speed equals the depth the step resolved / dt to 0.1 %. Some depth is left at the step's end (0.13 mm of the 0.5 mm) and is resolved in the next step.
- ClothFold, the pinch-and-lift repro (GPU, 128 worlds, 2026-11-10; development notes, not shipped): 55 worlds reset, at 20.2-37.5 m/s (median 25.1).
- In 45 of the 62 reset dumps the probe's fastest towel particle matches the reported speed to 0.1 m/s.
- In world 12, a corner particle went from 0.6 to 13.9 m/s in one 39 us exchange while the finger's records went from 0 to 0.12 mm penetration at 47 N. The particle left along the finger's normal; the finger moved at 0.2 m/s.
Why
- VBD solves a step implicitly and reads each particle's velocity off its displacement, v = (x - x_start) / dt. The depth a particle starts inside is undone within the step, and that displacement becomes speed.
- Contact damping acts only while a particle approaches.
- The only bound on the speed is self contact's motion truncation, 0.85 mm per detection: 44 m/s at 39 us, 87 m/s at 19.5 us.
- Not traced: how a towel particle gets 0.5 mm or more inside a finger at a step's start. It is either the particle's own move or a newly listed edge or face record (full-surface contacts are on in ClothFold). The finger's record plane was not stale: the finger moved 2-4 um per exchange.
Workaround
- Opt-in:
body_particle_exit_speed=<m/s>in the cloth solver's settings (Truefor 1 m/s), orALLOY_EXIT_SPEED=<m/s>in the environment (alloy/solvers/vbd/exit_speed.py). - How it works (split impulse): after each step, a particle whose record started the step inside its contact distance keeps its solved position. The outward normal speed that undoing the start depth gave it, past the cap, is taken off.
- A corner of an edge or face record loses its share of that speed.
- It never takes more than the particle's own outward speed, so a particle resting on a pad that pulls away is not pulled after it.
- A particle in several records is cut by the one that cuts most, so one started deeper in one finger's record and thrown out of the other finger's is capped too.
- Tangential velocity is untouched, and so is a particle that was already leaving.
- An impact still stops in one step.
- On the probe's particle 0.5 mm deep it leaves at 1.0 m/s instead of 18.7 m/s; on a cloth face pressed 0.3 mm into a
sphere, at 1.04 m/s instead of over 5 m/s (
tests/solvers/vbd/test_exit_speed.py). - Limits:
- It removes energy and momentum from the particle only. A body that VBD integrates keeps the push it got in the step; the coupler's record-momentum feedback gives a robot body back only what the particles took.
- A particle squeezed sideways out of a wedge between two records leaves along the wedge, not along either normal, and that speed is not capped.
- Measured on ClothFold (one L4 per run, main b5121ce81 with
ALLOY_EXIT_SPEED=1.0; 2026-11-11 11:58Z): - The pinch-and-lift repro, 128 worlds: no world reset, against 31 with the cap off.
- The task, 960 worlds a side, against a control of 1,088 a side with the cap off (main 1db240364; the trees differ by the cap and by changes ClothFold does not use). The shipped demo's frozen worlds fell from 10.8 % to 6.0 %, the slow-release script's from 8.9 % to 6.8 %.
- Its fold count did not rise measurably with the demo (+1.6 points, t 0.8). It rose 5.6 points (t 2.4) with the slow release.
- The resets left come while the fingers squeeze and carry the towel in the turn (4.7 % of the worlds, against 5.9 % with the cap off). At and after the release they fell from 3.9 % to 1.7 %. Which exit the cap misses in the turn is being traced (a wedge exit, a stretch snap, or a neighbour of a capped particle).
Planned fix
- The cap as a default (the ClothFold rows above), after a decision and an audit verdict.
- The turn's resets: a probe dump splits the fastest particle's speed by record count, normal and tangent, and edge stretch.
- Then trace how the particle starts a step that deep, which the cap does not fix.
Cloth and soft solids with self contact move at most about 3 m/s¶
What is wrong
- In a VBD entry with self contact (
add_cloth's default, a cloth card withfeatures.self_contact, two or more cloth or soft-solid objects), nothing moves faster than a cap. A sheet dropped from 1 m reaches 3 m/s and then falls at a constant 3 m/s instead of 4.4 m/s at the floor. - On fine meshes the cap is lower (see Number).
- Before 2026-11-08 the cap was much lower: 0.82 m/s for the 0.6 mm towel card and 2.72 m/s for a 2 mm sheet at the 1.25 ms step.
Number
- Rule: cap = 0.85 (margin + gap) / step, where margin is the contact thickness h and the step is the cloth's
physics step. The route (
alloy.solvers.vbd.reach) picks the gap from the step so that the cap is 3 m/s: gap = max(0, min(3 step / 0.85, 0.75 ℓ) - h), with ℓ the median rest edge length. A finer step shrinks the gap and the cap stays 3 m/s. - The cap rises above 3 m/s only when the gap is 0, that is when the step is under 0.85 h / 3 m/s: 0.57 ms for a 2 mm sheet. Below that it is 0.85 h / step.
- On fine meshes, where 0.75 ℓ binds, it is lower than 3 m/s: at the 1.25 ms step that is a median edge under 5.9 mm.
- A control dt above 1.25 ms does not change the step:
Scene(dt=...)of 10, 5 or 2.5 ms still steps the cloth at 1.25 ms (800 steps/s). - Measured (CPU, 0.3 m sheet, resolution 16, 0.03 kg, dropped from 1.6 m, fall speed fitted over 0.35 to 0.4 s; free fall is 3.68 m/s at the middle of that window, 3.92 m/s at 0.4 s):
- 2 mm sheet, Scene dt 10 ms, step 1.25 ms: 3.00 m/s (cap 3);
- 2 mm, dt 1.25 ms, step 1.25 ms: 3.00 m/s (cap 3);
- 2 mm, dt 0.625 ms, step 0.625 ms: 3.00 m/s (cap 3, gap 0.2 mm);
- 2 mm, dt 0.5 ms, step 0.5 ms: 3.40 m/s (cap 3.4, gap 0);
- 2 mm, dt 0.25 ms, step 0.25 ms: 3.58 m/s (cap 6.8, so not capped; 3 % under free fall's 3.68, which is float32 rounding of the velocity at fine steps);
- 4 mm, dt 1.25 ms: 3.00 m/s (cap 3); 4 mm, dt 0.625 ms: 3.67 m/s (cap 5.4: free fall);
- 2 mm, 5 mm cells (resolution 61, median edge 7.5 mm), dt 1.25 ms: 3.00 m/s (cap 3; 0.75 ℓ does not bind);
self_contact=False, dt 10 ms: 3.70 m/s (free fall).- Earlier numbers: with the old reach the cap was 0.816 and 2.72 m/s (development scripts, not shipped).
- Fine meshes, where 0.75 ℓ binds:
- Skin/fat pads (ℓ 4.7 mm, margin 1.38 mm): 2.4 m/s;
- a 2 mm-cell sheet at h 0.6 mm: about 1 m/s.
Why
- Newton's penetration-free truncation (DAT) caps every particle's motion between self-contact detections at 0.5 · 0.85 · (margin + gap). A step detects twice.
- A larger gap lifts the cap, but it lists more candidate pairs: the cost grows with the reach.
- Past about a cell, the pairs overflow Newton's fixed per-vertex buffers, and the overflowing pairs are dropped (docs/known_gaps/vbd-self-contact-buffer-overflow.md).
- The 3 m/s bound and the 0.75-edge cap were chosen by measurement:
- at 5 m/s a towel's fast pinch ran 9x slower and its half fold failed;
- at 3 m/s, 0 crossings, the same fold quality, 1.5-2.8x the old cost on towels, and 3.35x faster on a 4 mm drape.
Workaround
Scene(dt=...)alone does not raise the cap. Halving the control dt does not double it: at the route's reach the cap is 3 m/s at every step down to 0.57 ms (2 mm sheet).- A thicker sheet with a fine enough step: a 4 mm sheet at a 0.625 ms step (
dt=0.000625) fell freely (3.67 m/s, cap 5.4). A 4 mm sheet at 1.25 ms stayed at 3.00 m/s. - A 2 mm sheet needs a step under 0.57 ms: 3.40 m/s at 0.5 ms, not capped at 0.25 ms.
- A finer step takes more steps per simulated second: 2 x at 0.625 ms and 5 x at 0.25 ms, against 1.25 ms.
- Self contact off (
self_contact=False) removes the cap (3.70 m/s, free fall), and with it layer-on-layer contact. - Engine layer, not public API: an explicit
particle_self_contact_gapin the VBD entry's kwargs wins over the rule (keep margin + gap under one rest edge length, or pairs overflow), andalloy_self_contact_speedsets the rule's motion bound. No speed was measured for either.
Planned fix
- None planned in the reach rule itself.
- A detection inside the iterations would lift the cap at less cost than a larger reach. Newton's ITERATIONS schedule does that; it is not measured yet.
VBD self contact drops pairs over its fixed buffers¶
What is wrong
- Newton's VBD self-contact detection stores each vertex's colliding triangles and each edge's colliding edges in
fixed per-element buffers: 32 and 64 entries (
particle_vertex_contact_buffer_size,particle_edge_contact_buffer_size). Since 2026-11-10 Alloy sizes those rows to the scene by default and grows them before they drop a pair ("Rows sized to the scene" below). What is left is the limits listed there: rows at their cap, and the solvers that keep the fixed rows. - Pairs beyond a buffer's capacity are dropped. Since 2026-11-08 health flags the world that dropped them:
SELF_CONTACT_OVERFLOW, DEGRADED for the rest of the run, with
check()still ok (docs/guide/health.md). Since 2026-11-10 it also measures whether the surfaces then passed through each other, INVALID on request ("Pass-through after dropped pairs" below). - The rows hold every pair in the VBD entry: within one cloth or soft body and between two of them.
- A dropped pair is never resolved, so the two surfaces can pass into each other.
Number
- A skin pad on a fat pad (CPU, 1.25 ms, margin 1.38 mm), with the reach set to 7.35 mm (an uncapped 5 m/s motion bound, a test of the reach rule):
- 1,890 vertices and 4,527 edges were over capacity: up to 85 of 32 and 151 of 64;
- the skin reached 1.02 mm into the fat;
- measured with a development overflow script (not shipped).
- At the route's reach, the same scene peaks at 14 of 32 and 24 of 64: 3.53 mm under the 0.75-edge cap (2.76 mm before 2026-11-08: 2 of 32, 9 of 64).
- Not measured: deep piles of folded cloth, where many layers lie within one reach.
Why
- The buffers are preallocated per element and sized once at solver construction.
- The detector counts every pair it finds (
TriMeshCollisionInfo.*_count) but writes only up to the capacity.alloy/precision/self_contact.pyreads the overflow after every detection.
Workaround
- Nothing to do for most scenes: rows sized to the scene are the default.
ALLOY_SELF_CONTACT_ROWS=fixedin the environment (every VBD entry of the process), oralloy_self_contact_rows="fixed"in one VBD entry's kwargs, goes back to Newton's fixed rows. - Keep the self-contact reach under one rest edge length. The route's rule caps it at 0.75.
- To check a scene, read
sim.health(): SELF_CONTACT_OVERFLOW names the worlds that dropped pairs.
Rows sized to the scene (the default since 2026-11-10)
- What it does (
alloy/solvers/vbd/self_contact_rows.py,alloy/integration/row_growth.py): - each row has its own size, never under 32 / 64;
- at the end of every control period, rows more than 75 % full grow, before they drop a pair;
- a period in which a row did drop pairs is run again on the larger rows, so no accepted period has a dropped pair (one exception on a GPU: a row that fills from under half full to past its size within one period is seen a period late, so that period stands and health keeps SELF_CONTACT_OVERFLOW; see the limits below);
- inside a period nothing is read on the host; a growth drops the captured CUDA graphs, which are captured again.
- Numbers (one world, CPU, 1 s, flat 16 x 16 cotton sheets of 0.3 m stacked 2.5 mm apart on a table; a development script, not shipped):
| Sheets | Fixed 32 / 64: peak pairs | Fixed: dropped | Sized rows: peak pairs | Sized: dropped | Row memory |
|---|---|---|---|---|---|
| 4 | 24 / 45 | 0 | 24 / 45 | 0 | 1.8 MiB, unchanged |
| 8 | 32 / 60 | 0 | 32 / 60 | 0 | 3.7 -> 5.5 MiB (grown once, before a drop) |
| 12 | 40 / 76 | up to 8 / 12 per row, flag raised | 48 / 90 | 0, no flag | 5.5 -> 8.6 MiB (3 growths, 1 period re-run) |
- A sheet folded over a bar and a sheet draped over a post peak at 8 / 15: no growth, no array replaced, the same mean height to the last printed digit and the same wall time.
- A scene whose rows stay under 75 % full steps bit for bit as with fixed rows (CPU law).
- Wall time of the 12-sheet run: 5 % more than with fixed rows.
- Memory: 8 bytes per pair slot. A fixed vertex row is 256 B and a fixed edge row 512 B: about 1.8 kB per cloth particle, for every world. Growth is per row, so only crowded rows cost more.
- Limits (what is still wrong):
- a row stops at 256 pairs, and a solver's rows at 4 times their fixed size in bytes (at least 256 MiB;
alloy_self_contact_row_bytesin the entry's kwargs raises it). Past either, pairs drop as before, the build logs it once with the fix, and health raises SELF_CONTACT_OVERFLOW; - not covered: a solver whose rows belong to a collision pipeline (rigs built with
collision_pipeline), and Newton's deterministic modes (their record arrays are sized for 32 / 64): both keep the fixed rows, and the solver logs it; - the triangle-to-vertex rows are not grown. Health's watch reads them too, so the flag rises if a pile fills them; in the stacks above they did not (no flag with sized rows);
- a rig that drives the solver itself must run its first step outside a captured graph and detect self contact in every step, as Alloy's routes do;
- with
rerun_worlds(the side simulation that re-runs worlds) the side simulation's rows keep their build size: they do not grow, and a pair dropped inside it triggers no re-run; - a re-run starts from the period's start, so a run that grew differs from one that had the larger rows from the start only by the pairs the first attempt dropped; the first attempt is discarded;
- a grown row is sized past its need (overshoot): growth at least doubles a row, so the largest rows ended at 144 / 256 slots for a peak of 56 / 91 pairs (12 sheets, GPU). Tighter growth is open;
- on a GPU, while no row is over half full, the rows are read a period late: a row that goes from under half full to over full within one period drops pairs without a re-run (health keeps SELF_CONTACT_OVERFLOW for it); from then on the rows are tracked per row and read every period, so the next drop re-runs;
- growing costs time once, in the periods that grow: a growth captures the CUDA graphs again, and a period that dropped pairs runs twice. On the 12-sheet, 16-world GPU run below that was 19 s more over 1 s of simulation (53 s against 34 s for the first half second); later periods ran at the fixed rows' speed;
alloy.estimatedoes not count the self-contact rows in its memory: 64 worlds of the 12-sheet stack hold about 354 MiB of rows before growth and 591 MiB after (scaled from 2 worlds, an audit), against an estimate of 146 MiB for the whole scene;- sized rows keep the pairs a crowded row used to drop; they do not stop sheets crossing in general. 12 or 20 sheets falling together from 5 cm apart end with layers passed through each other in both modes, with no row over 24 / 46 pairs (no pair dropped; a separate gap);
- these keep the fixed 32 / 64 rows: the side simulation of
rerun_worlds, Newton's deterministic modes, rows owned by a collision pipeline (above), and everySolverVBDan Alloy module builds itself instead of through a scene's VBD entry (alloy.solvers.vbd.make_vbd): the cucumber-slicing job (alloy/tasks/job_slice_sim.py), the coupling and topology rigs, the test rigs. - On a GPU (one L4, CUDA graphs on, 1 s, the same stacks in many worlds; development notes, not shipped):
| Scene, worlds | Fixed 32 / 64 | Sized rows | Row memory | Warm world-steps/s, fixed -> sized |
|---|---|---|---|---|
| 4 sheets, 64 | no drop | no growth | 118 MiB, unchanged | 134 -> 134 |
| folded sheet, 64 | no drop | no growth | 65 MiB, unchanged | 2,705 -> 2,634 |
| 12 sheets, 16 | flag raised | no flag: 7 growths, 4 periods re-run | 89 -> 157 MiB | 191 -> 190 |
| 8 sheets, 256 | flag raised | no flag: 4 growths, 1 period re-run | 945 -> 1,513 MiB | 103 -> 111 |
- The periods that grew cost time once: the first half second of the 12-sheet run took 53 s against 34 s (re-runs and graphs captured again); the second half took the same 34 s.
- GPU cloth that touches itself does not repeat bit for bit (
docs/guide/worlds.md): two fixed-row runs of the 4-sheet stack differ by 6 um, and a sized-row run differs from a fixed-row one by the same 6 um. The bit for bit law is a CPU law. - Not measured: the GPU's total memory at the peak (the table is the rows' own bytes).
- A scene that never fills a row (a finding from the rc1 audit): a calm drape (one L4, 64 worlds, default accuracy,
wall plus read time, 3 rounds; development notes, not shipped) ran 6.3 % slower with sized rows than with
fixed rows in rc1, and 0.2 % slower after 0.1.1. There were two causes. A host read every period made the host
wait for the GPU; it is now a period late while no row is over half full. The two per-row arrays allocated at
build were never used in such a scene, yet made every captured period 5 % slower (
notes/gap-13b/vmprobe3; mechanism unknown); they are now allocated when a row first passes half full. Law R5 (L4): a calm 64-world sheet makes no read that waits and runs within 3 % of fixed rows. - The default since 2026-11-10: it changes nothing below the fill mark (CPU bit for bit, law R3) and replaces dropped pairs where a scene is crowded (law R1).
Pass-through after dropped pairs (opt-in since 2026-11-10)
- Dropped pairs are often harmless, so SELF_CONTACT_OVERFLOW alone stays DEGRADED. On request health also measures
whether they let surfaces pass through each other (
alloy/precision/self_contact_cross.py), after every self-contact detection (16 per control period atdt=0.01): - every particle of a row that dropped a pair is marked (the vertex, an edge's two ends), for the rest of the run;
- a world has passed through when two triangles that share no vertex intersect and one has a marked vertex, or when a marked vertex went through a triangle's inside to its other side since the detection before (two flat layers swap sides this way without any triangle pair ever intersecting).
ALLOY_SELF_CONTACT_CROSSin the environment at build (CheckPolicy.self_contact_crossat the engine layer):off(the default: no meter at all, every step as before),report(the count is in the world's health row,self_contact.crossed_pairs; the world stays DEGRADED) orinvalid(such a world is INVALID, frozen as a blown cloth is, andsim.check()names it: "passed through").- Laws (CPU,
tests/precision/test_health_self_contact_cross.py; world 1's rows shrunk after build, world 0 keeps its rows as the control): - two sheets stacked on the ground, rows of one pair: world 1 drops up to 14 pairs a row, nothing passes through, the sheets rest 2.0 mm apart: DEGRADED with the switch on;
- a sheet dropped tilted onto one draped over a stand, rows of no pair: world 1 crosses from step 9 (72 triangle pairs): INVALID and named with the switch on; world 0 never crosses;
- the stack with a 1 kg upper sheet, rows of no pair: it sinks flat through the lower one from step 4 with no triangle pair intersecting; only the side-change clause sees it (it read 0 before that clause).
- Miss test (two sheets, 6 ways of loading them, rows of 0 and 1 pair, 100 steps; a development script, not shipped): all 6 runs with rows of no pair passed through, and each was caught by the step its layers inverted; no run with rows of one pair swapped or crossed; the control world never.
- Cost with the meter on (CPU, 4 worlds of two 20 x 20 sheets): 0.4 % per step when nothing drops (no marked vertex: no search), about 2 % with a quarter of the particles marked. Off (the default): none, and no step changes (CPU law: on and off step bit for bit).
- Scenes (CPU, the switch on
invalid; development notes, not shipped): of 22 library scenes, examples and cloth tasks run with the fixed 32 / 64 rows, only the skin pad on a fat pad (3 pairs dropped) and 8 or 12 stacked sheets (8 and 16) dropped pairs; none passed through (crossed 0, DEGRADED as before, no new INVALID). With the default rows sized to the scene, those three drop nothing and the meter has nothing to judge. - Not seen by design: sheets that pass through each other with every pair kept (no row dropped), as in the separate gap above; an auditor's sheet dropped onto another at full rows ended with 5 vertex columns up to 1.3 mm below the lower sheet's, health OK.
- Limits:
- only surfaces whose rows dropped pairs are watched: sheets that pass through each other with every pair kept (12 or 20 sheets falling together, above) are not seen;
- a particle that moved more than the self-contact query radius between two detections (a reset, a teleport) is not judged for that move; a vertex that went round a free sheet edge inside one such short move would read as a pass-through (not seen in the laws or the sweep);
- a period that re-runs on grown rows puts the marks and counts back to its start, with the dropped count; an engine rollback of some worlds (a coupled re-run, a watchdog's recover) puts their counts back with health's arrays, and clears their marks and skips their side changes at the next detection: a pass that was thrown away leaves no crossing, at the cost of a possible miss;
- the side-change clause needs a detection every step (Alloy's routes detect twice per step); with a longer detection interval it can only miss;
- not run on a GPU yet: the meter is launches only on arrays made at attach, as the overflow count it extends.
Planned fix
- Done (2026-11-08): the SELF_CONTACT_OVERFLOW health flag, DEGRADED. In a calm two-sheet stack with rows shrunk to one pair, one edge dropped up to 14 pairs and the sheets still lay 2.0 mm apart: dropped pairs do not always mean pass through, so the flag does not make a world INVALID.
- Done (2026-11-10): rows sized to the scene, above, opt-in first, then the default.
- Done (2026-11-10, opt-in): the pass-through law and meter above; INVALID with
ALLOY_SELF_CONTACT_CROSS=invalid. - Open: INVALID by default (needs the sweep on more scenes, a GPU run and a decision); tighter growth (the overshoot);
growing rows in the side simulation of
rerun_worlds.
Known gap: paper and film keep only a flat fold made on one mesh line¶
What
- The film route's fold memory lives on mesh edges. Each edge has a yield angle from its material card
(
film.dead_fold_yield: paper_80gsm 36 deg, film_hdpe 73 deg); bent past it, the edge's rest angle follows. The angle is per edge, whatever the cell size. - A bend that spreads over several rows of edges keeps each edge under its yield angle, so the sheet springs back flat. A paper or HDPE sheet bent 90 deg over a plate edge does not keep the fold. A real sheet pressed over a sharp edge keeps part of it.
- A sheet folded flat about one mesh line keeps its fold, and library objects with creases (bags, cartons) fold on their crease lines.
- A 180 deg fold pressed against a plate goes INVALID (PEN_FAIL; film-thin-sheet-box-edge.md).
Number
CPU, 1 world, a 40 x 30 mm sheet of 0.1 mm at 2.35 mm cells, half under a static plate, the other half folded up by a
kinematic paddle, held 0.3 s and let back (the audit's rig; re-measured on main 692add686, after the drive-timing
change 7690f7a84: every number here as before but the 180 deg row's):
- 90 deg over the plate edge. The bend sits on three rows of edges: 46 / 25 / 9 deg for paper_80gsm, 38 / 29 / 10
deg for film_hdpe. Paper: one row is 11 deg past its 36 deg and keeps that (rest angle 11.5 deg); the flap is back
at 0.02 deg. HDPE: no edge reaches 73 deg; the flap is back at 0.01 deg. paper_kraft, film_ldpe and film_lldpe
return to 0.00-0.08 deg as well (the audit's runs, CPU and NVIDIA L4).
- Plate edge on a vertex row. The bend becomes a loop over about nine rows, 31 deg at most; nothing yields.
- 170 deg over a 1.25 mm plate. Edges reach 31-36 deg; nothing yields; the flap returns to 0.2 deg.
- 180 deg against the plate. INVALID at 1.24 s for paper (1.26 s for HDPE), PEN_FAIL first read at 1.0 mm, 2.8 mm
deep at its deepest (edges had yielded by then: rest angles to 66 deg for paper, 36 deg for HDPE).
- 135 deg arc (the audit's run): paper_80gsm keeps 175 deg, film_hdpe opens to 0.4 deg (0.6 deg 1.5 s later).
- The engine's own law (alloy.solvers.film.laws.fold_release: a strip folded flat about one mesh line, let go,
no gravity): HDPE 15 um opens to 79 deg against its 73 deg, paper_80gsm to 53.5 deg against its 36 deg. The test
allows 15 deg and runs HDPE and LLDPE only, so paper's 17 deg miss was never tested.
Why
The yield angle comes from a flat-fold measurement (the angle a pressed fold opens to) and is applied to each mesh edge as an angle. A real sheet yields by curvature, so one sharp bend and the same bend spread over three cells are the same event; here they are three edges, each under its limit. The result depends on where the fold falls on the mesh and on the cell size. Paper's 17 deg in the flat-fold law is not diagnosed.
Workaround
- Put a mesh line on the fold and fold the sheet flat about it, or use a library object with creases on its fold lines (the paper bags and cartons).
- Do not expect a bend over an edge or around a tool to leave a crease.
- Read
sim.check()after a tight fold against a body.
Planned fix
After the release: a yield by curvature (an edge's yield angle from the bend it shares with its neighbours, so a fold yields the same on any mesh), and the flat-fold law run on the paper cards.
Known gap: a paper or film sheet much thicker than its card is launched when folded¶
What
- A paper or plastic-film sheet (route
cloth_film) given about 3x or more of its card's thickness goes INVALID when it is folded.add_cloth(..., material="paper_80gsm", thickness=0.001)is a 1 mm sheet of 80 gsm paper, 10x the card's 0.10 mm. A kinematic paddle folds half of it over: the sheet is launched (SPEED_FAIL, 40-72 m/s) as the paddle nears vertical, or goes PEN_FAIL. film_ldpe at 1 mm does the same. - At the card's own thickness the same fold works: paper_80gsm, film_hdpe and film_ldpe at 0.1 mm fold to 178 deg,
are pressed, and stay shut after the paddle goes back (
sim.check()ok). add_cloth's thickness defaults to 2 mm, the cloth default: give a paper or film sheet its card's thickness.cotton_woven(routecloth) folds cleanly at 1 and 2 mm.
Number
The fold: a 15 x 15 cm sheet (31 x 31 cells, 4.84 mm), half on a static plinth, half on a 4 mm kinematic paddle,
sim.drive(..., angular_velocity=(0, 3.2, 0), pivot=<the midline>) to 178 deg, scene dt 5 ms. CPU, main f9340c512,
1 world; paper_80gsm unless named:
| thickness | result |
|---|---|
| 0.1 mm (the card's) | folds to 178 deg, pressed 0.3 s, paddle back: the flap stays shut (1.1 deg open), sim.check() ok; film_hdpe and film_ldpe the same (1.0 deg) |
| 0.3 mm | INVALID at 0.93 s (paddle at 170 deg): CLOTH_STRETCH, 2.6 mm into the plinth |
| 1 mm | INVALID at 0.82 s (paddle at 94 deg): SPEED_FAIL, the sheet at 41.6 m/s |
| 1 mm, 40 VBD iterations (10 by default) | INVALID earlier, at 0.71 s (132 deg), 47 m/s |
- The jump is in one 1.25 ms film step, in VBD's solve. The fastest particle goes from 0.89 to 54.9 m/s, and 376 of 1,024 particles pass 5 m/s. The strain projection after it lowers the peak (41.6 m/s), it does not cause it.
- From 71 deg on, VBD already moves free-edge particles at up to 4x the paddle's own speed there.
- With the projection off, the contact skin limit on, or the film's friction terms off, it still fails (0.78-0.86 s).
- With the opt-in
FilmConfig(limiter="stress")it is not flagged, but the sheet thrashes (3-13 m/s every step, the fold angle jumping between 12 and 175 deg). - It does not need the paddle to move. Driven to 60 or 70 deg at 3.2 rad/s and held still, it fails at 0.70 and 0.745 s. Driven at 0.5 rad/s, holds at 30-75 deg pass and 85 deg fails.
- A 12 mm paddle and plinth do not help: paper 72 m/s, film_ldpe 48.5 m/s, both at about 0.84 s.
- Earlier trees: PyPI 0.1.0rc2 and rc6-1110 gave the same result, and an earlier main read PEN_FAIL 4-19 mm at 0.54-1.39 s. Neither 1-2 mm, dt 5 or 2.5 ms, nor fold rates of 1.5-3.2 rad/s helped.
Why
Not fully diagnosed. VBD's own solve diverges in a single film step, and the divergence grows with thickness, not with fewer iterations. The likely mechanism: a sheet's bending stiffness grows as the cube of its thickness, while the film route keeps VBD's membrane at 1e-4 of the material's stiffness (the strain limit holds the stretch instead). So at 1 mm, a 1000x stiffer bend acts against a soft membrane in each vertex's local solve, and a sheet bent near the fold, carrying its own weight sideways, gets steps that do not settle. The cloth route keeps its full membrane and does not do this.
Workaround
- Give a paper or film sheet its card's thickness (
paper_80gsm0.1 mm; the card's note says its caliper):add_cloth(..., material="paper_80gsm", thickness=1e-4). - For a thick, foldable sheet, use a cloth material, or build the folded part from creased cards (the library's paper bags and cartons fold on their crease lines).
- Always read
sim.check(): the failure is flagged (SPEED_FAIL or PEN_FAIL), and the world is frozen, never silently wrong.
Planned fix
Planned, with no release named: - A build warning when a film sheet's thickness is well past its card's (the 0.3 mm threshold above is 3x). - Then the solve itself: the membrane share that keeps VBD's local solves stable for a bending-stiff sheet, or the stress limiter, whose membrane is the film's own stiffness past the cap (it did not blow up here, but it did not settle either). - docs/guide/deformables.md should say to pass the card's thickness for paper and film (that page is its owner's edit).
Known gap: a very thin film draped over a sharp box edge goes INVALID (the fix is opt-in for this release)¶
What
- A 0.05 mm film (route
cloth_film) draped over a static box's edge pushes particles into the box until health's depth limit fires (PEN_FAIL), and the world goes INVALID. The library'sfilm_ldpe_sheet(0.3 m, 50 um LDPE) did it, as doesadd_cloth(..., thickness=5e-5, material="film_ldpe"). Found in an audit (docs/guide/deformables.md warns about it). - The fix is in the film plug-in,
FilmConfig.contact_skin_entry(alloy/solvers/film/skin.py), and is off by default in this release: with it the same scenes stay valid with no penetration flag (tests/solvers/film/test_film_skin.py), but one Bonds law (a label rolled onto a tube at 1.25 mm cells) reads no roller load with it on. It goes on by default once that law re-passes. - The fix covers static shapes only. A film on a dynamic or kinematic body (a free box, a tray moved
with
sim.drive, a robot's pads) keeps VBD's overshoot below, since those contact planes move with the body.
Number
- Off, the release default (CPU, 1 world: a static 0.1 m cube,
film_ldpe_sheet2 mm over its top, scene dt 0.01): PEN_FAIL at t 0.11 s, 0.52 mm (limit 0.5 mm = half the particle's 1 mm contact skin). A smaller scene dt did not help: the film steps at its own 1.25 ms. - On: 0.3 s with no penetration flag, deepest contact 0.05 mm; the world is DEGRADED by the strain projection's UNCONVERGED flag only (film-projection-force.md). The engine rig at the API's gains (0.15 m sheet, 7 mm edges): 0.22 mm deep without the limit; with it 0.001 mm after VBD and 0.05 mm after the projection (0.1 and 0.2 s).
- NVIDIA L4, 8 worlds, 0.3 s: the library sheet and a 50 um
add_clothover the cube, 0.001 mm deep andsim.check()ok (before: INVALID, PEN_FAIL 0.54 mm and 0.45 mm). - Cost: a drape step +4 % on the CPU, +10 % on an L4 without graph capture (the film suite's wall: within its run to run spread).
Why
Two stages each pushed contact vertices into the box (measured per film step, the contact records' own planes): - VBD's step from outside the skin. Newton's VBD gives a particle-shape contact no Hessian while the particle is outside its skin. A film vertex just outside took its Newton step with the membrane's and inertia's small Hessian alone, overshot into the shape, and the contact's full stiffness (ke 2e6 N/m on a 2-9 mg particle) threw it back in the next iteration. The step ended wherever the last iteration left it: 0.23 mm into the skin at 10 iterations, 0.16 mm at 200, the depth non-monotone in the count. - The strain projection. It moves vertices after VBD and ignored contacts that carry no force yet, so it pulled the taut sheet over the edge: VBD left the library sheet 0.001 mm deep (with the fix above), the projection took it to 0.52 mm.
The fix limits both, for film particles and static shapes: in each VBD iteration a vertex outside the skin may enter it by at most 0.2 % of its contact radius (1 um), so the next iteration has the contact in its Hessian; inside the skin it is VBD's, so the limit holds no load. After the projection a vertex VBD left lightly touching (within 2 um of the skin) ends at most 10 % of the skin deep (0.05 mm); a loaded vertex is left as before. The excess goes back out along the record's normal, at the particle's deepest record only (two coplanar boxes would push it twice). - The guard's 10 %: at 1 um it narrowed a roller's contact patch on a tube by 6 % (the Bonds C-1 law), since a lightly pressed patch edge is the projection's to set. - The entry: 5 % (25 um) left ~50 N on a vertex at the box's gains, and the friction on it tore the library sheet at the cube's corner (55 % stretch). - A first version held vertices it had placed in the skin there, so they could not take load through contact depth. Eight Bonds laws read zero wet-out pressure under a roller; fixed before merge.
Workaround
- At static shapes, engine layers:
FilmConfig(contact_skin_entry=0.002)for the SolverFilm entry. Throughalloy.build: a film of 0.1 mm or more at sharp static edges, or a rounded edge (a capsule or cylinder along it, or a mesh with a bevel). - Check
sim.check(): an INVALID world is flagged and frozen, never silently wrong. - On a dynamic or kinematic body: a film of 0.1 mm or more at its sharp edges, or a rounded edge (a capsule or cylinder along it, or a mesh with a bevel); grip.py keeps the projection from deepening only the contacts that already carry force.
Planned fix
On by default after the release, once the Bonds C-1 tube row at 1.25 mm cells re-passes with it (the other Bonds, film, dent and soft-body laws re-pass already). Then dynamic and kinematic bodies, the same two limits against planes that move with the body (Newton's rigid-soft DAT does that for its own truncation); not yet scheduled. docs/guide/deformables.md's warning should now name moving bodies only (that page is its owner's edit).
Metal sheets on the film: VBD sags a stiff sheet at real density, and the hinge network bends unlike a plate¶
Status: open. J2 metal sheets (P3) are on main; their laws run mass-scaled, which hides both limits. A J2
film runs 20 VBD iterations from the inertial start. That stops the sag from yielding for a 6061 or brass sheet on 5 mm
cells; steel, stainless and copper sheets, and any metal on finer cells, still yield under their own weight before
anything presses them. add_cloth with a j2 material always makes a film sheet. Design, laws and the full numbers are in the sheet-plasticity
development notes (not shipped).
What is wrong
- A stiff sheet sags, and the sag could yield.
scene.add_cloth(..., thickness=t, material="aluminium_6061_t6")(anyplastic.model: j2card) routescloth_film. At the card's real density VBD's Gauss-Seidel does not reach a metal sheet's statics in a step's iterations, so a sheet draped over a bar or laid on supports droops far below its static shape: a metal sheet in a scene looks floppy. - At VBD's 10 iterations that sag bent the sheet past yield. The sheet then kept a dent nothing pressed, and
plastic_strainread it. - At 20, the J2 film's default, it still does for most sheets: a 6 cm, 0.25 mm sheet at rest on two supports
reads ε̄p 0 in 6061 and brass on 5 mm cells, 0.001-0.007 in steel, stainless and copper, and 0.009-0.016 in
6061 and steel on 3 mm cells (a finer mesh sags more: 2 mm, then 5-9 mm).
sim.check()stays ok. The sag is 1,000 x or more the static one. - A dented sheet on box edges creeps. Released from a press, it stays on round or box supports. On round supports it settles within 1 mm; on the sharp edges of boxes it keeps sliding sideways, about 1 mm/s.
- VBD's adaptive start throws a dented sheet. With
alloy_initial_guess="adaptive"(the J2 default in b650fd2fd only), a dented metal sheet released from a press walked sideways and climbed off its supports, whilesim.check()stayed ok. Stiff CLOTH_VBD sheets did the same until 24178a806, which starts them inertial. - The hinge network is not the plate. Each hinge carries the plane-strain J2 section on its own curvature. Bent along the mesh grid that is exact, but:
- under a concentrated load (a cylinder pressing a strip) the network is more compliant than the plate;
- bent at an angle to the grid it is stiffer below yield (up to 1.5 × at 45°), and past yield it carries more moment than the plate (up to 1.94 ×);
- a dent's kept depth therefore depends on the mesh.
Number
- Sag (CPU, main a08d7007e): a 1 mm steel strip on two supports 100 mm apart, dt 2e-5, 50 ms. The static sag is 5.4 µm, and the first swing reaches 10.8 µm. Measured sag by solver setting:
- default start, 20 iterations: 1,170 µm;
alloy_initial_guess="adaptive": 42 µm;- adaptive plus
alloy_chebyshev_rho0.9: 100 µm at 20 iterations, 49 µm at 60.
At dt 1 ms the real-density strip fell off its supports in every variant. - Sag that yields, through the API (CPU, dt 0.01, a 6 cm, 0.25 mm 6061 sheet, res 13, 1.5 s):
| case | inertial, 10 iterations (before P3's follow-ups) | adaptive, 10 (b650fd2fd) | inertial, 20 (the J2 default now) |
|---|---|---|---|
| hung over a 20 mm bar | droops 9 mm, ε̄p 9.6e-4 | rings 1.5-5 mm, ε̄p 0 | 5.1 mm, ε̄p 0 |
| on two 10 mm round supports 4 cm apart (static sag ~2 µm) | 2.7 mm, ε̄p 1.8e-3 | 0.27-0.36 mm, ε̄p 0 | 1.9 mm, ε̄p 0 |
A second, independent measurement of the 10-iteration inertial start: 10-15 mm and 0.0041 over a bar; 0.0003-0.0012
after a 0.14-0.3 mm drop onto round supports. At 40 iterations the bar droop is 3.1 mm. With
alloy_chebyshev_rho 0.9 on the inertial start at 20 (main 4522df750): bar 3.2 mm, round supports 1.5 mm, ε̄p 0,
every press-and-release case below stays on its supports, 1.14 x the step cost. Still 100 x or more the statics,
so the default stays as it is.
- Yield at rest, by metal and mesh (CPU, dt 0.01, main 270ead86d; the 6 cm, 0.25 mm sheet laid on two 10 mm round
supports 4 cm apart, nothing pressing; found by the pre-release audit, then re-measured).
Sag and largest ε̄p at 0.2 s, and at 1.0 s where they moved:
| material | res 13 (5 mm cells) | res 21 (3 mm cells) |
|---|---|---|
| aluminium_6061_t6 | 2.2 mm, 0 | 5.4 mm, 0.0085 (7.7 mm at 1 s) |
| steel_carbon | 2.2 mm, 0.0025 | 7.6 mm, 0.0152 (9.0 mm, 0.0159 at 1 s) |
| stainless_304 | 2.1 mm, 0.0015 | |
| copper_c110 | 3.5 mm, 0.0072 |
The audit's rows (a 0.2 mm lower start): brass 0, steel 0.0014, stainless 0.0007, copper 0.0055 at res 13; 6061 on
2 mm cells (res 31) 0.110, sag 10.3 mm; a 0.5 mm 6061 sheet at res 13 0.0014. Scene dt 0.005 gave identical
digits, an L4 the same to 4 digits. The static sag is about 2 µm and its strain 1e-6.
- Press and release (the press rig, CPU, dt 0.01; test_a_dented_sheet_released_fast_stays_on_its_supports): the
same sheet on two 10 mm round supports 4 cm apart (or 2 cm boxes 5 cm apart), pressed 15 mm by a kinematic 5 mm
sphere, released at 0.1 m/s (fast) or 0.02 m/s (slow), watched to t 3 s. Re-measured on main 692add686, after a
drive's velocity began one physics step earlier (7690f7a84); the runs that leave their supports are chaotic, so
their heights and times moved, the outcomes did not:
- inertial, 10: stays on round supports and on boxes (1.3 mm sideways). On the first metal-sheet commit the box
case went INVALID (PEN_FAIL, contact 0.6 mm deep); it no longer does;
- adaptive, 10: walks sideways within 0.5 s of the release's end, climbs to 75 mm (supports' tops at 50 mm) and is
18-29 mm off to the side and falling at t 3 (before the drive change: 74-80 mm, on the ground by t 2.9); on
boxes it climbs to 93 mm and is on the ground by t 1.6. Slow: stays on, wandering (top 52.7-55.1 mm, 2.7 mm
sideways). At 40 iterations it climbs to 84 mm; with Chebyshev 0.9 at 40 it climbs slower, to 81 mm at t 3.
Nothing flags it: sim.check() stays ok, health reads DEGRADED (UNCONVERGED) as during any press, and the film
ledger's largest one-step energy gain does not move (6.9 µJ, from the press): the climb of about 0.6 mJ comes
over tens of steps;
- inertial, 20: stays on both, fast or slow. Round: settles, 0.7 mm sideways. Boxes: 2.4 mm sideways by t 3 and
still moving; on boxes health also reads CLOTH_STRETCH (the sheet 67 % past its rest size over the edges,
DEGRADED). A flat sheet at rest stays still with every start.
- Network (CPU; the strip and can rows mass-scaled ×10⁴ / ×10³, quasi-static):
- elastic 3-point bending of a 1 mm steel strip deflects 1.20 / 1.27 / 1.33 × the plane-strain beam for 5 / 10 /
20 mm strips (a narrow real plate: 1.10 ×);
- pure bending at 30° / 45° to the grid (sheet_laws.s1_off_axis): below yield its stiffness is 1.375 / 1.5 ×
the plate's; past yield (8 κ_y) it carries 1.80 / 1.94 × the plate's moment and keeps 0.92 of the plate's
curvature. Both are pinned by test_s1_off_axis_measures_the_hinge_networks_anisotropy;
- a 0.2 mm tinplate can wall pressed 8 mm by a fingertip keeps 1.07 / 0.96 / 0.68 mm on 32 x 8 / 48 x 14 /
64 x 20 walls. With the stretch cap at 5 % instead of σ_y/E it keeps 0.14 mm (48 x 14).
Why
- Sag: a metal sheet's bending stiffness D/dx⁴ dwarfs its mass per step (ρ t / dt²), and VBD's per-vertex Gauss-Seidel moves a long-wavelength bend a little per iteration. The inertial start puts a full step of gravity into every vertex's guess, and too few iterations leave much of it in the result. More iterations take it out.
- Adaptive start: it keeps gravity in a vertex's guess only where the vertex accelerated downward on the last step (Chen et al. 2024). That removes most of the sag (the 1 mm strip: 1,170 -> 42 µm). But a stiff sheet far from converged follows its guess, so gravity then acts one step late. A restoring force with a lag feeds energy in, and a dented sheet resting on two supports rocks itself off them.
- Network, a film model property (the film route; the J2 section only uses it):
- The membrane runs at 1e-4 of the material for VBD, and the strain cap carries the stretch, so in-plane shear and twist are nearly free below the cap and rigid past it.
- On the alternating right-triangle grid the axis hinges read κxx and κyy and the diagonals the twist κxy. With ke = D/l_h on all of them the energy is κxx² + κyy² + 4 κxy², where a plate's cylinders take 2 κxy².
- Under a concentrated load the rows zig-zag cell by cell, a mesh-scale mode that only the diagonal hinges resist.
- Each hinge yields on its own curvature: there is no plate plasticity (no biaxial interaction).
- Halving the diagonals' section (tried as P3b, not landed) makes elastic cylinders exact at every angle (1.000), but makes the zig-zag cheaper: 3-point compliance 1.51-1.61 ×, and the strip's set no longer matches its hinges. Past yield it still carries 1.38 / 1.44 ×, since independent hinges sum to 1.5 M_p at 45°.
Workaround
- Shape and dent laws: run mass-scaled with gravity off and a slow press, as S2 / S3 do (
sheet_dent.py,sheet_can.py). Light hinge damping while the sheet yields, and heavy damping once nothing yields any more. - A J2 film runs 20 iterations. More cut the sag further (40: 3.1 mm over the bar, 2x the cost); in engine-layer
rigs pass
iterations=to SolverFilm. - Keep
alloy_initial_guess="adaptive"off a J2 sheet that moves under gravity. The mass-scaled laws run with gravity off, where it changes nothing. - Give a pressed metal sheet round supports (
add_cylinder), not sharp box edges. - Read
plastic_strainon the sheet at rest, before the press: anything above 0 there is the sag, not the task. Count only what the press adds, and keep the mesh coarse (5 mm cells or larger): a finer one sags and yields more. - Bend along the mesh grid where the bend line is known (a fold, a cylinder press): the network is exact there.
- Read a dent's depth as mesh-dependent: compare meshes before trusting a number.
Planned fix
After the 1109 release. More iterations and Chebyshev buy factors of 1.3-1.6; the sag needs a solve that moves the whole sheet's bend at once (a Newton or multigrid step on the bending, in the film route or VBD; the cloth-stiff-sheet-sag has the same need). - J2 films run 20 iterations from the inertial start. An adaptive start without the lag (or one used only near convergence) is the VBD accelerators' call. CLOTH_VBD keeps it for fabrics, which the drape needs, and since 24178a806 starts sheets with a bending length over 50 mm (PET, nylon, PP, cardboard) inertial; their sag is cloth-stiff-sheet-sag.md. - A plate-like network needs hourglass control, or another bending discretization, in the film route. That is a film design change, not a J2 one.
Film: the strain projection carries no force¶
Status: open; being fixed now (2026-11-08). The projection's reaction on pinned vertices is read
out (below); it does not reach bodies yet. An opt-in limiter that carries force, FilmConfig(limiter="stress"), is
in (below, "The stress limiter"); the default is still the projection.
What
SolverFilm keeps a film near-inextensible with a strain-limit projection. Its VBD membrane runs at 1e-4 of the material's stiffness. After the VBD solve, the projection moves vertices directly, by inverse mass, and keeps no multipliers. The tension it enforces is never a force, so no rigid body or robot feels it. That covers: - a tape or label bond holding a film edge; - pads pinching a film; - a wrist force sensor above a carried bag.
Only VBD's own terms reach bodies: contact, friction, bonds and the soft membrane.
Number
- Bond tractions. In a 90° peel of a 25 x 100 mm PET 80 µm strip (G = 380 J/m², 50 mm/s), bonds acting through the projection read 42.9 N against Kendall's 8.7 N, with a large sideways component.
- The same peel with the in-plane stiffness inside VBD (full membrane, gravity off): the grip reads 9.66 N against 9.62 N. That route fails under gravity, because Gauss-Seidel does not converge on a stiff sheet: paper sags 725x.
- The reaction, measured.
SolverFilm.projection_reaction[N, per particle, the last step] holds what the projection puts on each pinned vertex: per constraint, minus the momentum it gives its free vertices, shared by its pinned ones (strain.vertex_reaction; positions unchanged). On a hung strip it equals minus the projection's momentum change of the free film over dt within 0.5 % every step (tests/solvers/film/test_film_projection_reaction.py). A constraint's share is split equally among its pinned vertices, so only sums over pins are forces; a torque needs the split by moment balance (slice 2). WithFilmConfig.mass_ratio_cap> 0, free-free pairs and unpinned triangles (the capped centroid) do not conserve momentum among free vertices, so then the free film's momentum change is not all from the pins (from review). - The limiter does not converge on a loaded strip. A 40 x 80 mm HDPE 15 um strip hung from its top row, with 2-50 g on its bottom row, stands 2-22x past its strain cap (p99) at 16-64 Jacobi sweeps and rings (0.3-1 m/s). So its reaction reads the dynamics of an unconverged stretch, not the weight (50 g: 0.47 N vs 0.49 N at 0.6 s). Unloaded, a strip's own weight (0.43 mN) stays under what the 1e-4 membrane holds at the cap (2.6 mN), and the projection never acts.
- Pinches. The film grip terms cancel the projection's pull on a pinched vertex, with no reaction on the pad. So the pads carry a strap's weight only through VBD's contact and friction on the pinched vertices. This follows from the construction; it has not been measured as a force.
The stress limiter (opt-in)
FilmConfig(limiter="stress") (engine layers; alloy/solvers/film/stress.py) drops the projection. Past its cap a
triangle is an elastic membrane of the film's real stiffness, E h / (1 - nu²), inside VBD's own vertex solve, so the
tension is a force and a heavy load's own solve sees the film's stiffness. Below the cap the film is VBD's soft
membrane, as before. SolverFilm.limiter_force [N, per particle, the last step] is the limit's force on each
particle, pinned ones too (each pin its own force, so moments are right).
The same strip (40 x 80 mm HDPE 15 um, pinned top row), CPU, 10 VBD iterations
(tests/solvers/film/test_film_limiter_laws.py):
| load on the bottom row | stretch past the cap (x cap) | pins' force / weight | load's vertical speed |
|---|---|---|---|
| 2 g | 1.001 (projection 11.5) | 0.742 (0.638) | 0.009 mm/s (projection 10) |
| 50 g | 1.030 (24.4-33.6) | 0.989 (1.008) | 0.016 mm/s (83) |
| 500 g | 1.286 (16.6-18.8) | 0.998 (0.914) | 0.16 mm/s (38) |
The projection does not converge, so its numbers move from machine to machine (two CPUs shown); the stress limiter's repeat within 1 %.
- The stretch past the cap is elastic (50 g: 0.07 % of the length; 3 % of the 3.7 % cap at the pinned row, which cannot narrow). The limit has no Poisson coupling, so in a one-way pull it is 27 % stiffer than the film: the strip stretches 0.79-0.82 of m g / (E h b) past the cap.
- At loads near the film's own weight
limiter_forceunder-reads the pins' reaction by up to a quarter: the 2 g strip's missing 5 mN is carried by VBD's soft membrane below the cap, whichlimiter_forceleaves out (the law's floor for it, 0.67 of the weight, is set from that membrane's pull at the cap). From 50 g it reads 0.99 or more. - An off-centre load: the pins' moment matches the free film's weight-less-inertia moment within 0.9 % over 0.4 s (0.2 % and 0.9 % on two machines; 10 % rms per step: VBD at 10 iterations). A 50 g pendulum: period within 0.03 %, 7 % of the swing energy lost per period (the implicit step's own damping), none gained. A load taken off: the pins read the film's own weight within 0.1 % after 10 steps (the projection's load recoils at 270-370 mm/s).
- No yield; an overload is not flagged. Past the cap the film stays elastic at any load. 100 g to 1 kg hold steady; 5 kg (49 N, 2.2x the strip's 22 N yield force) is still stretching at 36 mm/s after 2 s, 3.8x past the cap, with no health flag (CLOTH_STRETCH warns only past 50 %).
- The loaded particles still move against each other across the pull at 2-20 mm/s: with the cross direction slack this model has next to no shear stiffness (a real film has).
- The model is soft below its cap (a real film is elastic from zero strain): a load let go at the film's rest length first falls the slack (cap x length, 3 mm here) and is caught there; the fall's energy is lost.
- float32: a particle's
limiter_forceis quantised at about E h eps32 |x| (1.8 mN 1 m from the origin for this film). Sums hold: the 2 g strip's pins read 0.742 of its weight at the origin, 0.738 at 1 m, 0.736 at 4 m.
Not covered yet: tear seams and compress caps (the build refuses them with this limiter), the contact skin and grip limits with it, forces on bodies through contact, bonds and pinches (the next slice), GPU numbers.
Why
The projection is position-based. Strain caps and long-range limits are Jacobi sweeps of corrections, with no multipliers λ. Bonds added inside the projection (an XPBD bond after each sweep) cannot be consistent, because the caps keep no λ to balance them.
Workaround
- Bonds (
alloy/plugins/bonds). Bonded vertices are pinned for the projection. The peel force comes from Kendall's energy balance, T = G(θ)·b/(1 - cos θ), and is applied to the grip body with the reaction on the substrate. The free arm's internal forces never reach a body. - Pinches (
FilmConfig.projection_friction,static_friction_hessian; the C16 film-grip development notes, not shipped). A pinch holds within mu·N, so a carried bag stays in the jaws, and a force-limited servo still sees the right squeeze. Read the carried weight from the scene's masses, not from the jaws. - A task that needs the robot-side force of a stiff film: check it on plain VBD with the full membrane and gravity off.
Planned fix
Steps:
- Done: the reaction on pinned vertices is read out; the opt-in stress limiter carries a hung load (above).
- Multipliers on the projection were tried and dropped: a multiplier updated by local sweeps under-estimates by the
load-to-vertex mass ratio (15,000 here), as the projection's corrections do, and carried into VBD as a force it was
unstable on 0.36 mg vertices.
- Next: forces on bodies with the stress limiter (a 90° peel against Kendall, a pinched strap's weight on the pads),
then tear seams and the grip and skin limits with it.
- Then the default: every film, Bonds and paper-pack law with limiter="stress", and a decision.
Known gap: the open-carton peel throws a light body in some worlds (1 in 40 with the task's caps)¶
What
alloy/tasks/gift_carton_tape.py(open-carton): the hook's tine holds the tape's tab (the Bonds grip) and peels the seam tape off at ~180 deg. In some worlds, at the moment the arm goes taut or in the first ~0.5 s of peeling, a light body is launched past 20 m/s: the hook's wrist or palm, or the -y major (31 g). That world goes INVALID (sim.check()reports it) and fails the task.- Which worlds fail follows the VBD colouring: Newton colours identical worlds differently, so identical worlds diverge.
Number
- Without the caps (the default tine, 0.9 mm over the held row): 3 of 24 GPU worlds (16 worlds x 1.0 s of the peel: 1; the task on 8 worlds: 2).
- The first merge's tine, 0.1 mm over the row: the hook was launched in 2-9 of 16 worlds at the taut moment, on every tree tried.
- With the coupler's exchange caps (c 4, c_d 0.5, which the task sets): 1 of 40 (two 16-world probes 0 and 0, the task 1 of 8).
- The task (NVIDIA L4, 8 worlds x 31.25 s): 6 of 8 succeed with or without the caps (the taped-carton measurements in the development notes, not shipped).
Why
- A rigid body's contact force from the film reaches it one exchange late (lagged coupling). Where the tape folds and snaps taut under the tine, the film's strain projection is unconverged and that lagged force spikes for one exchange, on the tine or, through Bonds' pull at the front, on a flap.
- With the tine 0.1 mm over the held row, the folded arm was pinched between the tine and the board (the film collides at 0.5 mm); 0.9 mm removes the pinch. The later spikes remain.
- The coupler's exchange caps (described in their design note, not shipped) limit the lagged contact stiffness and
damping and stop most of them. They are off by default: on by default for every film's coupled bodies (route c,
22248a172) they slowed the bag task's carton-off-the-mouth GPU test from 24 min to over 3 h, so they are opt-in again.
The task sets them for its own build (
gift_carton_tape.exchange_caps, route b), andsim.routes()names them where they are on.
Workaround
- Run more worlds and keep those
sim.check()passes: an INVALID world is flagged and frozen, never silently wrong. - The task builds with the caps (c 4, c_d 0.5):
with gift_carton_tape.exchange_caps(4.0, 0.5): alloy.build(...)does the same for another scene with a film coupled to light bodies. The engine layers take them too:FilmConfig(exchange_caps=(4.0, 0.5))for the film entry, or anIntegrationProfilewithscheduler_policy=SchedulerPolicy(exchange_stiffness_c=4.0, exchange_damping_c=0.5), passed toalloy.integration.wiring.build_simulation.
Planned fix
- A public way to set the caps (
alloy.build) is a post-launch change (2026-11-08 15:16Z: no new public knob before launch). Caps on by default need the bag slowdown understood first. - The rest (1 in 40) needs a converged film solve where the arm snaps taut.
Known gap: the wrapped present cannot be unwrapped yet¶
What
- The reference task set's unwrap-gift task: tear the taped wrapping paper off a present box until the box is free of paper (paper on at most 5 % of the box's surface, the box closed and upright).
- Alloy has the start state: the library's
gift_wrapped_present, a 187 x 132 x 55 mm box wrapped in 82 um kraft wrapping paper (girth wrap with the seam under the box, ends folded; its OBJ carries the flat sheet, so a card can put tear lines on it), placed on its box byalloy.tasks.gift_present.add_present(the wrapped-present measurements in the development notes, not shipped). - No task unwraps it: there is no scripted motion that takes the paper off, and no test of one.
Number
- The task is not run: 0 % of the paper comes off (the reference's gate: paper on at most 5 % of the box).
- The start state rests: on an NVIDIA L4, 64 worlds x 1 s, the wrap moves at most 1.7 mm and the box tilts at most 0.3 deg, health ok (the wrapped-present measurements in the development notes, not shipped). With tear lines, 25 of 64 worlds lose the rest within 0.2 s (reason 5).
- The reference task set's own demonstrations did not unwrap it either, even with hands that attach to the paper.
Why
- Nothing to take hold of. The paper lies flat on the box. The gantry's fingers and hook
(
alloy/tasks/gift_gantry.py) pinch or push edges that stand free; the wrap's free edges are the seam's edge, pressed under the box, and the end flaps' edges, lying flat on the stacked end layers. The film's grip (alloy/solvers/film/grip.py) holds a sheet between two jaws, which also have to get round an edge first. - The layers stand 1 mm apart. A film particle collides at 0.5 mm, so every layer stands a pitch of 1 mm off the one below it (12 times the paper's 82 um), and an end stacks up to six layers. No tine or finger fits between two layers to lift a flap, and a thinner contact radius would need a finer clock than the coupling already runs.
- Tape. The reference tapes the seam and the ends. The Bonds plug-in bonds film to rigid bodies only; tape on paper needs film-to-film bonds that break by peel, which are not modelled.
-
Cost. The box on the film couples at the lightest body's clock: about 0.16 ms (j = 6), so a task of tens of seconds is a GPU-only run.
-
Tear lines do not hold on the folded wrap. Tear lines on the flat sheet build (alloy/solvers/film/layout.py: 390 edges at 44 mm, every vertex copy on the sheet's grid), but with them the present does not rest. On an NVIDIA L4, 64 identical worlds x 0.2 s: 25 lose the rest (the outer layer of an end stack peels out from 0.04 s, the box tips 17 deg by 0.2 s, the film's strain projection unconverged), 39 rest; without tear lines all 64 rest (wrap <= 2.1 mm, box tilt <= 0.4 deg). Which worlds fail follows the VBD colouring: Newton's colour balancing colours identical worlds differently (worlds 41-63 alike). One world on a CPU with world 41's colouring moved 20 mm by 0.08 s and kept going; with world 0's it moved 13 mm at 0.04 s and settled back to 4 mm. So the library card has no tear lines.
Workaround
None for the whole task. For tearing a wrap by hand, use paper_wrap_tear_sheet lying flat with an edge the gripper can
pinch (the tear-line measurements in the development notes, not shipped); the wrapped present serves as a resting start
state (for looks, perception and contact with the box).
Planned fix
Not scheduled: unwrap-gift was parked on 2026-11-07 for the open-carton task. It needs: - A grasp for a sheet lying on a surface: an attachment-style hold on film particles under a fingertip (as the reference's hands), or a finger that slides under a lifted corner. - Film-to-film tape: breakable bonds between two film layers with a peel law (an extension of the film's seams). - A paper contact radius nearer the sheet's thickness, with the clock it needs. - Seams that hold a folded sheet in every colouring (or one colouring per world), so the wrap can carry tear lines.
A two-pad pinch does not lift plies it presses hard¶
What is wrong
Two pads that land on a stack of fabric plies on a table, press, close and lift carry the stack up when the press is light. Pressed at 100 N, the closing pads gather nothing: they rise and the plies stay on the table. The world is valid throughout (no health flag), so a script that only checks health reads a grasp that did not happen.
Before 2026-11-10 the sewing note stated a 96 % carry at 100 N. That row was not a pinch: the pads had slipped off the mesh's vertex row and stood on the table, and the lift drew up cloth that lay above their bottoms.
Number
The rig of alloy.tasks.sew_ply_pinch (CPU): two 16 x 6.4 mm pads, 0.2 kg each, on 0.61 mm muslin plies (10 mm
cells) on a table; press, close at 10 N per pad, lift 10 mm. Each pad is centred on a vertex row; every row below is
pressed (each ply has a vertex under each pad through press and close, no pad reaches the table, no constraint row
dropped). Spot n2 VM, main ec7a47cb2 + the rig; carry is the rise of the particles between the faces over the pads'
9.94 mm.
| plies | press | carry | pad bottom over the table |
|---|---|---|---|
| 2 | 10 N | 9.88 mm, 99 % | 0.76 mm |
| 2 | 30 N | 8.81 mm, 89 % | 0.62 mm |
| 2 | 100 N | -0.93 mm (on the table) | 0.31 mm |
| 3 | 30 N | 8.02 mm, 81 % | 0.87 mm |
| 3 | 100 N | -0.80 mm (on the table) | 0.44 mm |
- Two plies at 100 N with the pads opened 16 mm instead of 13.6 mm (still on the row): -0.90 mm.
- With a 1 mm self-contact radius on the cloth (the sewing proof's setting) the 100 N pinch lifts two plies: 9.81 mm, 99 %. One row.
- Between 30 and 100 N only one press was run, with Newton's linear contact penalty: 50 N, 3.92 mm (39 %).
- Under 100 N the two plies' 1.22 mm stack is pressed to 0.31 mm under the pads.
Why
Not established. What the rows show: - The loss comes with the press, not with the ply count: two and three plies both lift at 30 N and both stay at 100 N. - Each pad bears on one vertex of each ply (a 6.4 mm pad on a 10 mm grid), so the whole press goes through that vertex, and the stack under the pad is squeezed to a quarter of its free thickness (two plies 0.31 of 1.22 mm, three 0.44 of 1.83 mm). - With a 1 mm self-contact radius the pads sit higher under the same press (0.42 mm), and the pinch lifts the plies. A finer mesh under the pads has not been tried.
Workaround
- Press lightly before closing: 10 to 30 N lifts two plies (99 %, 89 %).
- Check the grasp, not only health:
PinchResult.pressedin this rig; in your own scene, that the cloth between the fingers rises with them. - Mesh the cloth so that a finger pad covers vertices in its interior (the rig's pads cover one row; a pad on a row's edge gives carries that move by tens of points with the landing spot).
Planned fix
After the release candidate, with the cloth-grasp work (a law for lifting a ply stack off a flat support): the same pinch on a finer mesh, and the press swept between 30 and 100 N.
Liquids and heat¶
Liquid in narrow containers and thin streams needs finer particles than the default¶
What
- Liquid runs at 4 mm particle spacing by default (
liquid_accuracy="default")."super"gives 2 mm spacing, at about 16x the cost. - An opening narrower than 8 particles across is too coarse. That covers a cup, a bottle mouth, a hole or a funnel neck the liquid sits in or must pass through: under 32 mm at default, 16 mm at super.
- Liquid poured into it partly misses.
- Liquid at rest in it can start INVALID: particles jet off the walls in the first few hundredths of a second, and the health monitor freezes the world.
- Containers narrower than 24 mm are unreliable at both settings.
- A pour whose nozzle is under 2 particles across is a column of single drops, not a stream (under 8 mm at default), and most of it scatters.
- The build warns once about each case. The warning names the item, its width in particles, and the fix:
liquid_accuracy="super", a wider opening, or a pour with a higherrateor lowerspeed. It never refines silently. It checksadd_open_box,add_open_cylinder,add_block_with_holeand cards with apassage_width; anadd_meshcontainer is not checked.
Number
CPU probes through alloy.Scene, main 14275571e (development probe scripts, not shipped):
- Pour (half the cup's volume, the stream half its width), share kept in the cup:
- 4 mm: 95.6 % at 24 mm (6 across); 99.7 % at 32, 48 and 70 mm (8, 12 and 18 across).
- 2 mm: 97.6-99.8 %.
- Water at rest, 40 mm deep:
- 4 mm: cups of 12, 16 and 24 mm (3, 4 and 6 across) went INVALID with ENERGY_JUMP within 0.04 s. 32 and 48 mm were
healthy.
- 2 mm: 8 and 16 mm went INVALID. 12 mm stayed healthy but lost 68 particles over the rim.
- Stream into a 70 mm cup, share that lands: 36 % at 1 particle across (either spacing); 99.0-100 % at 2-5
across.
Why
- SPH resolves the pressure near a wall over a kernel of 2 particle spacings each side.
- With fewer than about 8 particles across, the kernels of opposite walls overlap. The pressure solve then has almost no bulk to balance, so the first steps push particles off the walls.
- A one-particle stream has no neighbours to hold it together.
- The 24 mm floor at super is measured, not explained. It may come from the cup's walls:
add_open_cylinderbuilds them from 24 flat 4 mm slabs.
Workaround
- Build with
liquid_accuracy="super"when the warning says it is enough (openings of 24-32 mm, streams of 4-8 mm). - Otherwise widen the container, or widen the pour's stream (
rateup,speeddown).
Planned fix
None scheduled. A third, finer setting would cost about 16x more again.
A pour alone can splash a few percent over its container's rim, and health stays OK¶
What
- A stream from
add_pourlanding in an open container can throw part of the liquid over the rim. With the liquid alone (liquid and static objects only), 3 % of a 6 ml pour went over the rim in the scene below; a 20 ml pour stayed in. - Beside cloth with no free rigid body it is a fifth of the pour or more through 0.1.1 (20 % of the 6 ml pour, 24 % of the 20 ml pour). After 0.1.1 both stay in.
- All of it goes over the rim. No particle passed through a wall in these runs: the walls hold.
- Health stays OK, and
sim.check()["ok"]is True. Only liquid that leaves the scene's bounds counts as escaped (retired_particles); liquid that leaves a container does not.
Number
CPU, 0.6 s simulated. Two static add_open_box containers, 8 x 8 x 6 cm and 10 x 10 x 8 cm inside with 5 mm walls.
Pours of 6 ml (94 particles) and 20 ml (312 particles) at 0.1 l/s, from 12 cm above the floor. The cloth is a 10 cm
sheet lying 30 cm away. A particle counts as through a wall when its path in one step crossed wall solid. The same
counts on one L4.
| scene | 6 ml outside | 20 ml outside | through a wall |
|---|---|---|---|
| no cloth | 3 of 94 (3 %) | 0 | 0 |
| cloth, no free rigid body, through 0.1.1 | 19 of 94 (20 %) | 74 of 312 (24 %) | 0 |
| cloth, no free rigid body, after 0.1.1 | 0 | 0 | 0 |
| cloth and a free 2 cm ball | 0 | 0 | 0 |
Cost of the change made after 0.1.1, one world on one L4:
- the two pours beside cloth: 79.5 -> 110 wall seconds per simulated second, because the liquid takes 3.3x the steps
while it pours;
- a cup of water at rest beside cloth: 9.05 -> 9.78 wall seconds per simulated second, with the same number of liquid
steps;
- a 10 cm cotton sheet (resolution 10) dropped 2 cm onto 0.8 l of water in a static 13 x 13 cm box: 33 -> 88 s per
10 ms step after first touch;
- the same scene with a paper_80gsm sheet: 2.3x over its first 0.3 s.
Why
- A stream landing on a floor needs small liquid steps while it lands.
- Alone, the liquid steps at one fixed step chosen at build from an assumed contact speed of 0.5 m/s. A stream from 12 cm lands at about 1.5 m/s, three times faster than that step allows.
- Beside cloth, the liquid used to step at its own stability limit, measured from its top speed, with no margin. After 0.1.1 it takes a quarter of that limit while it moves fast; at rest it keeps its largest step.
Workaround
- Count the liquid that stays in the container yourself, from
"<name>.points"and"<name>.active"insim.state(), instead of trusting a clean health report.
Planned fix
Planned, with no release named: the liquid alone chooses its step while it runs, as it does beside other solvers, with a law that a pour keeps its particles in an open box alone.
Liquid poured on a fabric sheet makes the world INVALID; cloth takes up no water¶
What is wrong
Two separate limits.
- A stream landing on a fabric sheet breaks the world. This happens with self-contact on, which is the
default. Within a few hundredths of a second after the stream lands, health flags ENERGY_JUMP, and often
SPEED_FAIL too. The world goes INVALID and is frozen (
sim.check()["ok"]is False). The same scene withadd_cloth(..., self_contact=False)stays OK, and so does a film sheet (film_ldpe, routecloth_film; paper sheets not measured). In those runs the water rests on the sheet and none passes it. - Cloth takes no water. There is no absorption, no wetting and no seepage. A sheet gains no weight from the water on it, and its friction and drape do not change when wet. Real untreated cotton wets at once, soaks up about 1-3 times its own weight and lets water through once saturated. In the simulation every fabric acts as a watertight sheet.
Number
The scene: a 0.2 m cotton_woven sheet (2 mm, about 12 g, 20 mm cells) resting on the rim of a static open box.
A 20 ml add_pour at 0.5 m/s starts 5 cm above it; the stream lands at about 0.06 s. CPU, Scene(dt=0.005), one run
per row (the CPU repeats bit for bit).
| variant | first INVALID |
|---|---|
| as above (self-contact on, the default) | 0.080 s, ENERGY_JUMP + SPEED_FAIL (21 m/s) |
self_contact=False |
none to 0.6 s; all 244 particles rest on the sheet |
material="film_ldpe", 20 mm or 5 mm cells |
none to 0.6 s |
sheet mass 4 g, 120 g or 360 g (mass=) |
0.075-0.115 s |
dt 2.5 ms or 1 ms |
0.077 s / 0.087 s |
cells 10 mm or 40 mm; cloth_accuracy="super"; liquid_accuracy="super" |
0.075-0.115 s |
| stream 0.2 m/s | 0.105 s |
| sheet on a full block top instead of a rim | 0.39 s, SPEED_FAIL |
- A towel draped over a static block and a 2 m/s stream also went INVALID soon after the stream landed.
- A world that fails does not recover: run to 3 s, the default row stays frozen from 0.080 s.
- In one development run with the freeze turned off, 1.2 % of the poured particles ended below the sheet, 9 cm from its border. They were carried through within one 2.5 ms step while the sheet under the stream moved at 3-4 m/s.
- Only this rim scene was measured with
self_contact=False, for 0.6 s. A drape, a fold, a long pour and a robot holding the cloth were not.
Why
The failure needs both the sheet's self-contact and liquid on the sheet. The same sheet with no liquid, or with the pour landing beside the box, stays OK with self-contact on. Changing mass, time step, mesh, accuracy settings or the number of coupling passes does not remove it; turning self-contact off does. The exact mechanism is not yet found.
Separately, the liquid sees the cloth as a zero-thickness two-sided wall. Nothing sweeps a fast particle's path against the sheet, and a particle that has crossed stays on the far side. That is how a sheet moving fast lets particles through.
There is no absorption model, so limit 2 is simply missing.
Workaround
- Pour onto a sheet that never folds with
add_cloth(..., self_contact=False). It is also about 1.4x cheaper per step on a GPU (docs/guide/deformables.md). - Use a film sheet (
material="film_ldpe") where a watertight sheet is what you want. - Check
sim.check()["ok"]after any pour onto cloth: a frozen world looks calm. - To show a wet towel's weight, add the water's mass to the cloth (
add_cloth(mass=...)) and leave the liquid out: the added mass stands in for the water.
Planned fix
Not in this release. In this order: 1. Find and fix the self-contact failure under a stream, with laws: a pouch of fabric holds a poured volume for 10 s, and a drop landing on one cell does not pass. The stream's momentum on the sheet must match rho Q v. 2. No pass-through: the cloth's thickness and a swept test for the liquid against the sheet. 3. An opt-in absorption model: particles taken into a per-vertex water mass up to the fabric's measured capacity, with that mass added to the cloth.
Wet friction and wet bending need measurements of a named fabric wet and dry before they get a model. No date yet.
Cloth, liquid and a light free rigid body do not build in one scene¶
What is wrong
A scene with a liquid, cloth (or a soft body) and free rigid bodies builds only when the rigid bodies are heavy
enough against the cloth. When the free rigid bodies and robot links together weigh less than twice the cloth and
soft bodies together, alloy.build raises BuildError, wherever the objects are, even far apart. The same scene
without the liquid builds, and so does the same scene without the cloth.
Number
The rule is a mass ratio: cloth and soft mass over rigid mass above 0.5 is refused. Example: a 20 g sheet, water in a static tub and a free ball of 34.9 g (radius 2 cm, default material) 1.4 m away: ratio 0.57, refused; the error gives 40.1 g as the lightest ball that builds. With a 100 g box and a 10 g sheet (ratio 0.1) the scene builds and steps.
Why
A rigid body that is light against the cloth it could touch needs the strongly coupled solver pair: the cloth's load on the body is too large for the lagged exchange that heavier bodies use. That pair cannot step a liquid in the same scene yet. The test is by mass only, not by distance, so a light body is refused even where it could never reach the cloth.
Workaround
The error's fix names each of these with its number:
- make the free rigid objects heavier, to at least twice the cloth and soft bodies in all (mass=);
- make the light objects static=True when they do not need to move, or kinematic=True to move them yourself
(sim.drive);
- make the cloth lighter;
- build the liquid in a scene of its own.
Planned fix
The strongly coupled pair beside a liquid, or the lagged pair for light bodies that cannot reach the cloth. No date yet.
A floating container much lighter than the liquid filling its outline is refused¶
What
- A rigid container flagged by its card (
features.passage_width: a cup, bowl, tray or boat) floating in SPH liquid routes like any floating body. The liquid's solver integrates it inside every SPH step at its effective mass, as a strong pair (staggered, never ADMM). - That holds up to D5's ratio m_a/m_s = ρ_liquid·V_outline/m of 50 (
coupler_select.FLOATING_CONTAINER_RATIO_MAX). V_outline is the container's outline volume (its box for a mesh), so the air inside counts. - Above 50 the build raises
FloatingContainerError(aRouteError). The message names the ratio and the mass that would route. - Light bodies that are not flagged containers (a foam block, an unflagged mesh cup) are not bounded. They route as before, beyond what was measured.
Number
- What was measured: open cups 60 x 60 x 50 mm (an
add_meshopen box, collision "sdf"), released just over still water in 140 and 400 mm tanks. Particle radius 2 mm (h = 8 mm), default dt, 2 s per case. GPU (L4) throughalloy.Sceneand the MuJoCo proxy. - D5 ratios 3, 6, 10, 30 and 50 all held. Walls were 8, 4 and 2 mm (h, h/2, h/4). Every world was healthy, no water entered a cup, and the settled bottom matched the tank's rise minus the draft m/(ρ·L²) within 0.27 mm.
- Nothing above 50 was run. The laws and their logs are in the development notes (not shipped).
- On the CPU, one ratio-3 release with 4 mm walls went INVALID at 0.55 s: a particle went 4.1 mm into the wall, and the health limit is half its thickness. The same case was healthy on the GPU.
Why
- A coupled step feeds the body forces from a liquid that moves with it. When the liquid it must push aside outweighs the body many times over, the correction can overshoot (the added-mass instability).
- Integrating the body inside SPH's step removes most of it, and the probes show it holding to 50. Above that, stability is not shown.
- The complete fix interlinks the body's motion with the pressure solve (Gissler et al. 2019), which is not built (the engine specification's section on this coupling, not shipped).
Workaround
- Make the container heavier: the message gives the mass that routes. Most real ones are inside the bound already: a 2 mm-walled 80 mm plastic cup is at about 10-20, a ceramic mug at about 2.
- Or use a smaller outline, or make it static (
static=True) or kinematic when it need not float. - A container on a robot or in a hand is not floating, so the bound does not apply.
Planned fix
Gissler interlinked pressure (the engine specification's section on this coupling, and option (a2) in the liquid-coupling scope note; neither shipped) if a task needs floating containers lighter than 1/50 of their outline's liquid. Not scheduled.
Liquid beside a paste or powder: the paste is a solid wall to the liquid (no wetting, no percolation)¶
Status: open, by design for now. A liquid (SPH) and a paste or powder (MPM) in one scene step together since the liquid-paste coupling change, but they meet only at the paste's surface.
What
Since the liquid-paste coupling change an SPH liquid and an MPM paste or powder step in one scene; before, the build refused them. The paste's particles are a moving wall of the liquid, and the liquid's pressure pushes back on them, so a paste block floats, sinks and gets pushed around as it should. A whisk or spoon stirs both.
What is not modelled is everything that happens inside the paste or powder:
- liquid does not soak into a powder or seep through its pores;
- a powder does not wet, dissolve, hydrate into a batter or form lumps;
- nothing sticks at the contact line (no contact angle between the liquid and the paste);
- the liquid slips along the paste's surface, as it does along every wall in a routed scene: SPH wall viscosity (no-slip) is off by default, so a paste blob in a viscous liquid feels its pressure but not its skin friction.
A flour heap in milk is therefore a heap of dry grains that the milk flows around. It is also squeezed by the full liquid pressure, where a real wet powder carries only its buoyant weight (Terzaghi's effective stress). Mixing spreads the two materials through each other, at the size of a few particles; it does not blend them into one.
Three cases are refused at build, with the fix named:
- a second liquid on the MPM route (liquid_mpm) beside an SPH liquid;
- a liquid that starts inside the paste or powder;
- a cloth or soft body in the same scene (as before).
Number
| check | result | how |
|---|---|---|
| Archimedes, 3 cm cube, rho 600 | submerged 0.606-0.611 against 0.602 | one L4, 4 mm liquid spacing, 2 s |
| Archimedes, 2.4 cm slab, rho 600 | draft 1.07-1.08 x rho_s / rho_f H (under 2 particles) | CPU law; L4, graphs |
| fluid force on a floating block | 1.003 x its weight (cube); 1.02-1.03 x (slab, bobbing) | same runs |
| paste bed under poured water | carries the column, rho_f g V, within 5 % | CPU law |
| momentum through the interface | exact to float32; a slab's drop within 0.65 % of its weight | CPU laws |
| a world beside another | bitwise the same whatever the other world's paste does | CPU law; one L4 |
| liquid inside the paste | 0 particles | every law run |
| sphere settling, 0.9 Pa s, no-slip | paste 3 mm/s, rigid 3.5 mm/s, Stokes 14.7 mm/s | L4, 2 mm spacing |
| passes per exchange | 2.48 mean (4.12 before the L2 gate), cap 8; 8 beside a robot | CPU, 1.6 cm cube |
| cost, 4000 liquid + 1728 paste particles | about 1.2 s per 10 ms period on an L4, 30 s on the CPU | 1 world |
| cost, slab scene, 64 worlds | 2.7 s per 10 ms period on an L4 | 64 worlds |
- A floating cube between 0.21 and 0.79 of the liquid's density tips onto an edge, as a real one does. Use a flat slab, or a cube outside that range, to see it float upright.
- The interface is resolved at the liquid's spacing: 4 mm by default, 2 mm with
liquid_accuracy="super". - The settling sphere is slow because of the liquid's own viscous drag at 2 mm spacing: a rigid sphere through the same liquid is as slow. The paste's particle wall drags like a rigid wall.
- A robot arm beside the paste and the liquid steps (the paste follows the arm one exchange behind, the liquid and the paste converge together), but every exchange takes the full 8 passes, about 3x the coupling cost without the arm.
- Heat between the liquid and the paste (both are particles to the heat model) is not checked in a coupled scene.
Why
- The liquid sees the paste as a boundary built from its particles (
alloy.solvers.sph.particle_walls): at each liquid particle, the paste's local surface and velocity. It has no model of liquid between the grains. - No-slip needs the SPH wall viscosity (
boundary_viscosity), which the router does not set for any wall; the particle wall reads it like any wall when it is set. - The two solvers run separately and meet every exchange: the paste moves, then the liquid, then the liquid's force goes back to the paste. Wetting and percolation need the two to share a grid (a two-phase mixture), and hydration needs mass to move from one solver to the other. Neither exists yet.
Workaround
- For something floating, sinking or being pushed through a liquid (a dumpling, dough in water, a paste blob), use it as is. Give the paste a few liquid particles across: about 1.5 cm or more at default accuracy.
- For a batter or a dissolved powder, use one material for the result. A batter card (
batter_bread_wheat,batter_cake_quinoa) mixed with a spoon behaves like the batter, not like flour plus milk. - Pour the liquid onto the paste or powder (
Scene.add_pour) instead of starting it inside.
Planned fix
- Hydration (after the coupling's laws pass): a powder particle takes up the liquid it touches and turns into batter, with mass moving exactly from the liquid to the powder. Lumps follow from wetting only the exposed surface. Sized at about 4-5 days.
- Percolation and hindered settling need the shared grid (a two-phase mixture in MPM). Not planned before launch.
Heated liquid does not convect: buoyancy=True gives the first push only¶
What. By default, particle heat changes a liquid's temperature but not how it moves. Liquid heated from below
stays in layers instead of turning over, when in reality it rises in natural convection and mixes the pot.
scene.set_heat(buoyancy=True) adds the thermal buoyancy force for water, and a hot region starts to rise at the
right rate, but the flow stalls after about a millimetre: convection does not develop, and a heated pan stays
layered with it on as with it off. It is off by default, and only water has the density data it needs; the build
says so for other heated liquids (chocolate, porridge).
Number. Off (the default): water 14 mm deep on a floor held at 80 °C for 90 s, starting at 20 °C, averages
53.6, 30.0, 22.7 and 22.5 °C in its four 4 mm layers from the bottom up. At this depth and temperature difference the
Rayleigh number is about 1e7, so real water would be convecting and well mixed. On, with 80 °C water in 20 °C water
(CPU laws, tests/plugins/test_thermal_buoyancy.py):
- at the default liquid accuracy, the start of rise matches the Boussinesq estimate for a body of fluid starting
from rest, g Δρ/ρ / (1 + C_a), over the first 30 ms: a sphere of radius 16 mm (C_a 1/2) 0.94 of it, and a
horizontal cylinder of radius 12 mm (C_a 1) 0.91 of it;
- at liquid_accuracy="super" (8 particles across the radius instead of 3) the same cylinder starts slower, 0.78 of
the estimate;
- afterwards the rise falls behind the free estimate, to 0.65 of it at 150 ms, at both accuracies and for both
shapes. The cause is not pinned. It does not shrink with finer particles, so it is not the region's size in
particles. Under test: the liquid's velocity smoothing, applied every step, so more often at the finer step;
- the flow then stalls. Hot water (80 °C) beside cold (20 °C) in a 60 x 60 mm cup, 32 mm deep, side by side: real
water would trade places in under a second (front speed about 4 cm/s). Here the hot half's mean height is 0.7 mm
above the cold half's at 0.25 s, 1.1 mm at 1 s and 1.2 mm at 2 s, then still; a full exchange would end at 16 mm.
At liquid_accuracy="super" it reads 1.3 mm at 0.25 s. A pan of water 16 mm deep on an 80 °C floor has the same
four layer temperatures after 30 s with buoyancy on as off (38.4, 22.6, 22.4, 20.3 °C from the bottom up);
- the cause of the stall is not pinned. Not the cause: the pressure solve's tolerance (10x and 100x tighter: 1.3 and
1.2 mm at 2 s) and wall friction (off: 1.0 mm). The liquid's velocity smoothing is part of it: with it off (not a
public setting) the same cup reads 3.3 mm at 2 s and is still creeping, 10x slower than real;
- the laws check the force at the start of rise only;
- the buoyancy force's work is booked in the health energy check as external work. It matches the work summed
independently over every particle to 1e-5 (the test's bound is 1e-3).
Why. The liquid solver keeps one rest density per material, so heat alone moves nothing. The buoyancy force is the
Boussinesq approximation: each liquid particle gets F = m (ρ(T) − ρ̄) / ρ̄ g. ρ(T) for water is NIST's table at 1 atm
(NIST Chemistry WebBook, 0-95 °C, with the 4 °C maximum; alloy.plugins.thermal.phase_materials.WATER_DENSITY). ρ̄ is
the mean over all the water in the world, so the forces sum to zero (to the sums' 2^-40 fixed point, about 1e-8 of the
water's weight), and heating all the water evenly moves nothing. It is off by default until a default change is ruled
on. Other materials have no ρ(T) table yet. With time_scale above 1, heat runs that many times faster than motion
while buoyant flow does not, so convection is that much weaker relative to conduction than in reality (the Rayleigh
number is divided by time_scale); the build warns once when both are set.
Workaround. There is none that gives convection: buoyancy=True does not mix a heated liquid. Stir it (a
kinematic paddle), or read only results that conduction controls (a solid or paste that melts, a food block's core),
and compare the heat that went in (heat_in_J) with the mean temperature. With buoyancy=True, two separate bodies
of water in one world (a hot cup and a cold cup) share one ρ̄, so each feels a small force against its container,
about Δρ/ρ of its weight (1.5 % at 60 K).
Planned fix. First the stall: a law for a lock exchange's front speed, and the liquid solver's damping of slow flows under it. Then buoyancy on by default for water, and ρ(T) tables for the other heat materials, from sourced data. No date yet.
Boiled-off liquid particles stay in the solver and can block a heater¶
What. When a liquid particle boils off, the heat plug-in stops exchanging heat with it, but the particle stays in the liquid solver with its mass and position. A boiled-off layer on a heater holds the remaining liquid off the heater, so heating stops.
Number. Water at 99 °C on a 177 °C plate: heating stops once the bottom layer, 25 % of the mass, has boiled off. The rest stays at 99.05 °C.
Why. The liquid solver has no public call yet to remove particles during a run.
Workaround. Read evaporated_in_solver from the plug-in. It counts the boiled-off particles that are still in
the solver, and a run that boils must check it is 0. Keep boiling scenes short of boil-off, or heat with
power_density (volumetric, needs no contact).
Planned fix. The plug-in will retire boiled-off particles once the liquid solver has a retire call; it is in progress.
A cylinder's force pressure lags when its chamber is joined to another chamber by a wide edge¶
What. Each actuator reads its chamber's pressure from the node's own implicit response to the step's volume change
(_force_pressure in alloy/plugins/fluid/actuators.py): P + (P' - P)·κ/(κ + dt·Σg). That response holds every
neighbour node at its step-start pressure, which is right for a reservoir or a large accumulator. When the edge goes to
another small chamber and dt·Σg ≫ κ, the force reads close to the step-start pressure. The oil column's stiffness then
acts a step late, and its ringing grows.
A second effect of the same split: the network adds a step's source inflow after the force is taken. While a pump is
filling a chamber, the node's end-of-step pressure therefore reads up to K·Q·dt/V above the pressure the piston acts
with.
Number. A forklift lift line (F2): a pump node of 0.5 L joined by a 1e-7 m³/(s·Pa) hose to the free-lift and main cylinders (0.1 L dead volume each), at the 1.25 ms task step. - Unladen carriage: the lift pressure swung between -3 and +5 MPa gauge, and the carriage crept 10 mm while held. - Gauge while flowing (one shared node instead, 0.1 L dead volume per cylinder): in mid free lift the node read 8.0 MPa while the piston acted with 5.97 MPa (34 % high). With the line's 1 L in the dead volumes it reads about 0.7 MPa high. Holding pressures read true.
Why. Per step, each actuator writes its chambers' volumes and takes its force from the pressure each node would reach on its own; the network then steps every node together (implicit in the conductances) and adds the sources' inflow. A neighbour held at its old pressure is right for a reservoir but not for a small chamber, whose pressure moves with the first one's within the step; and the inflow arrives after the force was taken.
Workaround.
- For a common line (one pump teed to several cylinders), declare the node Node(shared=True): one oil volume and one
pressure, the chamber of every actuator on it, with the coupling implicit through the node.
- For pressure readouts while oil flows, use piston_pressure (the gauge pressure each actuator's force acted with,
A and B sides) instead of the node's pressure.
Planned fix. Not scheduled. A network-implicit force pressure: the coupled response of the connected nodes to the actuators' volume changes, and the step's known source inflow added to the force's prediction.
Known gap: a syringe pushed by a constant force rebounds after its air leaves¶
What
- The
syringeplug-in (alloy.plugins.library.syringe) is stable only because the plunger's joint carries the needle's liquid column as armature: the column's added mass ρ·L·A²/a, about 1 kg for a 3 mL barrel on a 25 G x 16 mm needle (syringe.inertance). - That mass is real while liquid flows through the needle. It is not real while only air leaves, or while the syringe is capped, but the plunger carries it then too.
- A plunger pushed by a constant force (the
pushinput with nothing else on it) therefore gathers momentum while the air leaves almost unresisted. It rams the liquid, rebounds below atmospheric pressure and draws air back in through the needle. - A plunger moved by a finger at a set speed (a robot's position or velocity drive), as in the syringe tasks, is not affected: laws G-1..G-6 run that way.
Number
3 mL barrel (8.59 mm bore), 2.8 mL of water and 0.3 mL of air, nozzle up, 25 G x 16 mm needle open to the air, armature 1.01 kg, a 2 N push, CPU, 1.25 ms step: - the plunger reaches 0.11 m/s in 60 ms. A 2 g plunger alone would settle at about 0.23 m/s within milliseconds, braked by the air through the needle (estimated: 2 N over the air's A²/G ≈ 8.7 N·s/m), and stop on the liquid; - after the air is out, the barrel pressure swings between 50 and 205 kPa (absolute), and the needle carries air back in while it is below 101 kPa.
Why
- A plunger force computed from the fluid is explicit. Without the armature a 2 g plunger behind a 25 G needle is unstable above about 8 µs, and a capped all-liquid barrel above about 56 µs.
- The armature is set once, in the model, so it cannot follow the phase in the needle. Changing the body's mass at run time instead would keep the velocity across a 500x jump and inject energy.
Workaround
- Drive the plunger by its joint: a position-and-speed drive on the plunger's prismatic joint
(
JointTargetMode.POSITION_VELOCITY, asalloy/tasks/syringe_rig.pydoes), not by a bare force. - Not by a finger or gripper pushing the flange through contact with clearance either: the column's armature (1 kg on a 3 mL barrel behind 25 G) rattles in the play and on the contact spring, and the barrel pressure swings about ±50 % at 1 mm/s (the syringe tasks' first rig). A robot hand on the plunger needs a grip with no play, or the joint drive above.
- With both gains set, Newton's default drive mode is POSITION, which damps toward zero speed and ignores
joint_target_qd: passactuator_mode=newton.JointTargetMode.POSITION_VELOCITYto make the drive track a speed. - If a force push is needed, push slowly or add viscous stopper friction (
Syringe.viscous) so the plunger stays near its terminal speed through the air phase.
Planned fix
An implicit joint damper set per world by the plug-in (the needle's A²/G only while liquid flows), so the armature can drop to the plunger's own mass. That needs a plug-in hook to the solvers' per-world joint damping on both CPU and GPU routes (the syringe tasks are ported, merged 43f77f638).
A surface film is one-way with what it does not declare¶
What. A surface film (the SurfaceFlow plug-in) couples only to what its config names:
- the bodies its charts ride;
- its tools (Applicator): the underside ploughs the film and the pad presses back;
- its lumped films' bodies;
- with sph=True, the SPH liquid its drops join.
Anything else passes through the film as if it were not there, and feels nothing from it. That covers every other
colliding body (a dropped block, a robot's links, a pusher) and other particles (cloth, paper, paste, soft bodies,
SPH liquid without sph=True). The film also keeps its depth under them: a block resting in a puddle neither
displaces the water nor floats on it, and a cloth laid on a wet plate does not get wet.
Number. The material sweep (the material-combination matrix, finding F3, not shipped), 1 mm of water on a plate: - a block, cloth, paper, sponge, paste, water or the pusher comes down onto the plate as if the water were not there: the block's bottom lands at the plate top to 0.1 mm, and the cloth at its bare-plate height; - every cell keeps its depth; - the film's ledger stays exact.
Why. The film is a height field on charts. It reads the geometry of declared tools (tool_geometry), applies
their pad forces (pad_implicit) and books what they carry. It has no contact query against the rest of the scene,
and other solvers do not see it.
Now. Setup warns once, naming the undeclared colliding bodies and the particle count
(alloy/plugins/surface_flow/oneway.py; flow.one_way holds the text, None when nothing passes through).
Workaround.
- To couple a rigid body (a sponge's holder, a scraper, a robot's tool), declare it as a tool: Applicator(body=...,
shape="rect" | "disc" | "roller"), with a Store if it should pick up or lay film. The film then sees its
underside and pushes back on it.
- SPH liquid landing on a film joins it with sph=True.
- For a porous sheet that should soak up a film, model the sheet as the chart, with absorption.
- Cloth, paper, MPM paste and soft bodies have no workaround.
Planned fix. Not in v1, which warns instead. The two-way fix, estimated:
1. Rigid bodies and robot links, about one week. Every colliding shape of an
undeclared body becomes an implicit ceiling over the charts it overlaps (boxes, spheres, capsules and cylinders
exactly; meshes sampled by SDF), with the pad's pressure and drag back on the body. Tools already work this way,
so the step is: shape queries for 2-3 days, the force and its stability bound for 1-2 days, and laws (a block
displacing a puddle, a floating board, lubricated sliding) for 1-2 days.
2. Particles (cloth, paper, MPM, soft, SPH without sph=True), 2-3 weeks across owners (VBD, MPM, SPH). Each
solver would need:
- the film displaced by its particles' footprints;
- the film's forces on the particles (drag, capillary adhesion);
- the water a cloth or paper takes up;
- a stability bound per solver pair.
Not in v1.
Cables and rods¶
A cable on the chain route creeps back in a held twisting grip on the CPU¶
What is wrong
A short elastic rod with no clamp routes to the chain: a string of capsules in MuJoCo, stepped with the robot. Since
the chain-grip rule (alloy.contact.chain_grip), a chain beside a moving body (a robot, or a dynamic or kinematic
object) follows a gripper that squeezes and twists it, on the CPU and on the GPU. A 4 N squeeze sinks the pads 0.1 mm
into a 3 mm cable, not 1.5 mm. Before the rule it followed half the twist and lost most of that within a second.
- On the CPU (MuJoCo C), while the gripper holds still, the cable slowly turns back against its own torque: about
0.14 % per second.
- On a GPU (MuJoCo Warp) the held cable stays with the grip since 2026-11-10 (the stick anchor,
alloy.contact.mjw_stick_anchor; before it, it crept 2 % per second, and 10 % in 0.7 s in a rigid grip). What is
left there is under "What the anchor does not hold".
sim.routes()["<rod>"]["reasons"] says when the rule covers a cable ("chain grip beside ...").
Number
The rig of tests/api/test_rods_grip.py on the chain:
- a 0.4 m USB cable (r 3 mm, 20 segments of about 1 g), its start welded;
- its end between two 0.2 kg sliding pads on a wrist, squeezing 4.2 N;
- the wrist rolls 0.3 rad about the cable over 0.5 s, then holds.
The table gives the cable end / wrist. Measured with development scripts (a probe that applies the candidate rule as a patch, its GPU runs and a chain-clamp script; not shipped).
| route | ramp's end | after 0.7 s held | after 5 s held | pad depth |
|---|---|---|---|---|
| CPU, MuJoCo C | 1.0000 | 0.9997 | 0.9931 | 0.10 mm |
| GPU, MuJoCo Warp (an L4) | 1.0000 | 1.0000 | 1.0000 | 0.10 mm |
| GPU, MuJoCo Warp before the stick anchor | 0.9976 | 0.9828 | 0.8651 | 0.10 mm |
| either route before the rule | 0.50 | 0.08 | - | 1.54 mm |
the same rig on rod_vbd |
1.01 | 1.02 | - | - |
- The held cable creeps about 0.14 % per second on MuJoCo C (8 % over a minute). On MuJoCo Warp it does not move in
the fourth decimal over 5 s, the same in every world at 64 and 1,024 worlds (one L4, 2026-11-10); without the
anchor (
ALLOY_STICK_ANCHOR=0) it creeps about 2 % per second (0.9976 -> 0.9828 over 0.7 s, 0.8651 after 5 s). - The creep falls faster than 1 / impratio on MuJoCo C: 0.69 / 0.08 / 0.01 % over 5 s at impratio 300 / 1,000 / 3,000. MuJoCo Warp runs the rule at impratio 30, not 300 (Why).
- A rigid grip (pads welded to the wrist, 0.1 mm into the cable; a GPU chain rig, not shipped) on MuJoCo Warp: 0.9974 at the ramp's end and 0.9976 after 0.7 s, 2 s and 5 s, the same at 1, 64 and 1,024 worlds. Without the anchor it followed 0.978 and ran on to 0.899 / 0.762 / 0.523 after 0.7 / 2 / 5 s. On MuJoCo C the welded rig holds: 1.0000, -0.03 %. Fingers held by position servos, between the two, are not measured.
- The anchor adds no torque of its own. The wrist's torque over the cable's G J theta / L (the law of
tests/api/test_rods_chain_clamp.py, 3 % on MuJoCo C, where it reads 0.997) on the CPU's MuJoCo Warp route, held 2 s: welded pads 1.04 with the anchor (1.044 after 0.7 s, 1.039 after 2 s), against 1.14 rising to 1.30 without it as the cable ran on; sliding pads 0.90 with it and 0.92-0.94 without (MuJoCo C reads 0.89 there: the pads also carry the sagging end's weight). The welded rig is 4 % over on MuJoCo Warp, outside the 3 % of the MuJoCo C law. - The anchor's own laws (
tests/contact/test_mjw_stick_anchor.py): a cube pushed at 0.3 of its friction limit moves 3.02 um in 2 s without the anchor and 0.0001 um with it; pushed past the limit it slides and coasts the same with and without (0.2723 m in 0.6 s, deceleration 0.96 mu g).
What the anchor does not hold (MuJoCo Warp)
- A pair lets go when the pull it would need passes its friction limit (the contact's cone, or 20 m/s2 if that is lower). It sticks again only once the rows' own demand has fallen under half of that limit. So a contact that has slid and still carries more than half of its friction limit keeps MuJoCo's rows and creeps as before.
- A pair that has no contact for one step loses its anchor and starts afresh when it touches again.
- A cable link anchors up to 4 partners at a time; a fifth keeps MuJoCo's rows.
- Contacts between two links of the cable are not anchored, and neither are contacts of any other body: the anchor is on the chain-grip links only. A scene without one is bit for bit unchanged.
- Elliptic friction cones only (what the chain-grip rule runs); MuJoCo C and rk4 entries keep MuJoCo's rows.
- A gripped cable's links are anchored against whatever they touch, a table or the floor too: that is static friction, and it is new for a draped cable under a small side load, which used to creep along the table.
- The anchor's pull is not booked separately in the health monitor's energy check. It is bounded by the friction cone times the slip a stuck pair holds (under a micrometre in the rows above).
ALLOY_STICK_ANCHOR=0in the environment turns the anchor off (the rows of 2026-11-09).sim.reset()and a re-run of a period take each world's anchors back with the world.
Why
MuJoCo makes every constraint soft, friction too. With soft friction rows, a steady load far below the friction limit
still creeps.
- On MuJoCo Warp the chain-grip links' contacts get a stick anchor: their two sliding rows also pull back on the slip
the pair has built up since it last stuck, limited to the friction cone. Past the cone the pair lets go and its
rows are MuJoCo's own again, bit for bit, until its sliding has died down (above). It is a MuJoCo Warp kernel:
MuJoCo C keeps its rows, and so does rk4.
- On MuJoCo C the rule runs Newton at impratio 300, which makes the friction rows 300 times stiffer than the normal
row. They are still not rigid.
- MuJoCo's no-slip pass, which would hold the cable exactly, does not run with the discrete integrator the chain needs
for its stiff joints.
- The rule runs impratio 30 on MuJoCo Warp, which builds the Newton Hessian in float32. At 300 a gripped chain's
comes out indefinite by rounding alone, and float32 Newton does not converge on a cable resting beside a robot: it
ran at its 100-iteration cap in 97 % of periods, 18-25x the step on an L4, even with the Hessian damped. If the
float32 factorization still fails at 30, alloy.precision.mjw_chol redoes it in float64 with its pivots floored at
the Hessian's float32 rounding.
Workaround
- On a GPU nothing is needed for a held grip. On the CPU, a long hold that must not creep: put the cable on the
elastic rod. Any
clamp=("start"or"end") routes it torod_vbd, and so does a material that yields (plastic.model: j2);sim.routes()confirms the route.segments=does not change the route. Onrod_vbdit follows the gripper within 0.05 % and holds after the gripper stops. Beside a robot it costs much more (rod-vbd-beside-robot-cost.md).add_rod(..., clamp="start", route="chain")is the exception: it keeps the cable on the chain with its first link welded, which is cheap beside a robot, and keeps the CPU's creep (the table's rows are that rig). - Read the cable's own twist (
"<rod>.twist", its segments' quaternions), not the gripper's angle.
Cost
- CPU, MuJoCo C: +33 % per simulated second with a gripped cable (the api_speed robot scene, 1 world: 0.947 -> 1.257 s). The Panda scene with a cable lying on its table showed no measurable cost (1.53 / 1.47 s).
- GPU, MuJoCo Warp, an L4, the same scene: 1.62x / 1.14x / 1.10x at 64 / 1,024 / 4,096 worlds (1.17 -> 1.89, 5.32 -> 6.05, 21.2 -> 23.4 s per simulated second). The stick anchor adds 4 % / 3 % / 0 % at 1 / 64 / 1,024 worlds on the gripper rig.
Planned fix
None scheduled. Candidates: - a contact that slid and is still loaded past half its friction limit on MuJoCo Warp: the half is what keeps a sliding contact Coulomb's; sticking again right up to the cone needs a test on the rows' own state; - the MuJoCo C creep: a higher impratio (1,000 creeps ten times less at about the same cost).
A chain rod resting on an elastic rod sinks into it¶
What is wrong
A rod on the chain route laid across a rod on the elastic-rod route (rod_vbd, for example a clamped wire) does not
rest on top of it. It sinks into the wire by up to the wire's radius. With a thin wire the overlap is deeper than
half the wire's thickness, so the health check flags PEN_FAIL, the world becomes INVALID and is frozen. The flag is
right: the motion is wrong.
Number
CPU, a chain rod of radius 4 mm laid across a clamped copper wire:
- wire radius 1.5 mm: the rod's crest sits 1.5 mm low (the wire's whole radius), at dt 0.01 and 0.005 alike;
PEN_WARN and PEN_FAIL latch at 0.285 s and sim.check()["ok"] is False;
- wire radius 3 mm: the crest sits 1.9 mm low, the deepest contact is 2.5 mm (84 % of the radius);
sim.check()["ok"] stays True with a warning.
Two rods that never touch are not affected: each moves as it does alone
(tests/api/test_rods_mixed.py: 0.000 um for the clamped rod, 0.014 mm for the chain at rest).
Why
Not pinned yet. The two rods step in different solvers (the chain in the rigid solver, the elastic rod in its own),
and their contact is carried by the strong coupler between them, not by either solver's own contact. A smaller dt
does not change the overlap, so it is not a step-size error.
Workaround
- Put both rods on one route. Two chain rods touch as rigid bodies do:
add_rod(..., clamp="start", route="chain")keeps a clamped rod on the chain. Two elastic rods share one solver. - Keep a chain rod and an elastic rod apart, or accept the overlap with a thick elastic rod (3 mm radius: 1.9 mm),
and read
sim.check().
Planned fix
The contact between a chain rod and an elastic rod at the stiffness of the rods' own contacts, with a resting law (crest height within a stated share of the thinner radius). After the release tag.
A thin elastic rod can fall through a soft body between its vertices¶
What is wrong
- An elastic rod (
add_rod, routerod_vbd) dropped on a soft body (a soft material such assilicone_40a, routesoft_vbd) can sink through it to whatever is below. The soft body does not move. - It happens when the rod is thinner than the gaps between the soft body's vertices. A rod that lands between two rows of vertices falls straight through. One that lands on a row rests there for a moment, rolls off sideways, then falls through.
- Nothing flags it.
sim.check()["ok"]is True andsim.health()shows no penetration, because the rod and the soft body never touch. The build does not warn.
Number
- Scene. A 0.2 x 0.2 x 0.04 m
silicone_40apad lies on the ground. A copper wire (copper_c110, radius 1.5 mm, 0.16 m long, along y) is dropped from 30 mm above the pad's top. CPU, one world,dt0.01 s, a development probe script (not shipped). - The pad's mesh. Its vertex rows are 12.5 mm apart (16 x 16 x 3 cells, 1,156 vertices). Each vertex touches what comes within 2.5 mm of it. So the wire meets a vertex only when its centre line passes within 4 mm of it, and the gap between two rows that it meets nothing in is 12.5 - 2 x 4 = 4.5 mm wide.
Pad bottom 4.5 mm above the ground, pad top 42.4 mm once settled. z is the wire's centre line, so 1.5 mm is the
wire on the ground. In both runs sim.check()["ok"] is True with no problems listed.
| wire starts over | what happens | lowest z at the end |
|---|---|---|
| a vertex row (x = 0) | rests 4 mm above the top from 0.10 s, slides 3.4 mm aside by 0.40 s, falls | 1.5 mm at 0.50 s |
| a gap between rows (x = 6.25 mm) | never touches the pad, falls straight through | 1.5 mm at 0.15 s |
- The audit's start. The audit's pad started with its bottom 1 mm above the ground, inside the vertices' 2.5 mm
reach. The ground pushed it up at the first steps: its top rose from 41 mm to 77.6 mm by 0.10 s before it fell back.
sim.check()then lists ENERGY_JUMP, andokstays True. The wire still ended on the ground the same way (1.5 mm at 0.50 s from over a row, at 0.15 s from a gap), so the jump is not the cause.
Why
- A soft body touches rigid shapes and elastic rods at its vertices only. Each vertex is a small sphere, here of radius 2.5 mm, a fifth of the cell. There is no contact between a rod and the faces of the soft body between the vertices.
- A rod meets a vertex only when its centre line passes within the rod's radius plus the vertex radius of it. When half the vertex spacing is larger than that (6.25 mm against 1.5 + 2.5 mm here), the rod fits between two rows and meets nothing.
- A round rod resting on a single row of vertices is not stable. Any sideways offset tilts the vertices' push away from the row, so the rod rolls off into a gap.
- Cloth has the same limit for small rigid bodies: cloth-small-body-passes-through.md.
Workaround
- If the softness of the body does not matter to the task, make it rigid:
add_box(..., rigid=True). The same wire on the same pad made rigid rested on its top (centre line 1.50 mm above it, the wire's radius, through 0.60 s;sim.check()["ok"]True, no problems). An elastic rod beside rigid bodies is verified against a law. - The chain route is not a way out here. A cable of the same size on it (
cable_usb_composite,sim.routes()sayschain), dropped on the same pad, failed its health check as it landed: PEN_FAIL between 0.05 and 0.10 s, the world frozen with the cable still 9 mm above the pad,sim.check()["ok"]False. - Size check. A soft box of volume V gets cells about (6 V / 5,000)^(1/3) on a side (12.4 mm for this pad), with vertices of a fifth of a cell. A rod whose radius plus that vertex radius is under half a cell can fall between the rows.
- Read the rod's lowest z and the soft body's top after a short run before you trust a rod on a soft body.
Planned fix
- Contact between rod segments and the faces of a soft body, so that a rod between vertices still meets the surface. Until then, a build warning when a rod is thinner than the soft body's gaps. After the 0.1.0 release.
A wire loaded close to its fully plastic moment settles slowly and less accurately¶
What is wrong
A yielding wire (a rod_vbd rod whose card has plastic.model: j2) updates each joint's rest shape once per solver
step, from the converged pose (explicit in time). Under a held moment close to the section's fully plastic moment
M_p (or torque T_p) the wire takes many steps to settle, because the section is nearly flat there: a small moment
step gives a large curvature step. The settled curvature is then less accurate: the fibre section's few-tenths-
of-a-percent error in M becomes several percent in κ.
Number
CPU, SolverVBDRod, a clamped copper-like wire (0.2 m, R 1 mm, 20 segments; E 117 GPa, σ_y0 70 MPa, perfectly
plastic), gravity off, end moment ramped over 0.2 s, held, released (tests/solvers/rod/test_rod_plastic.py rig):
| end moment | loaded κ vs the closed form | residual κ after release |
|---|---|---|
| 1.2 M_y (0.71 M_p) | -0.13 % | -4.8 % of itself, 0.13 % of the loaded κ |
| 1.5 M_y (0.88 M_p) | +0.20 % | +0.84 % |
| 1.65 M_y (0.97 M_p), 0.4 s hold | -17 % (not settled) | -27 % |
| 1.65 M_y, 1.6 s hold | +1.9 % | +3.2 % |
Torsion (T_p = 4 T_y / 3): 1.15 T_y, loaded -0.38 %; 1.25 T_y (0.94 T_p), loaded +0.74 %. The residual twist is within 0.4 % and 0.7 % of the loaded twist.
Why
- The rest update is a fixed-point iteration with the elastic stiffness as its step. It contracts by (1 - k_t / k), with k_t the section's tangent stiffness, which goes to 0 at M_p for a perfectly plastic wire.
- The 220-fibre section is within 0.35 % of the closed-form M(κ) and T(φ') up to 0.98 M_p
(
alloy/solvers/plastic/j2.py). Near M_p, dM/dκ is small, so that error in M is several percent in κ.
Workaround
- Load a wire to at most about 0.9 M_p when the bent shape matters, or hold the load longer. At 0.97 M_p it took 1.6 s to settle.
- Card hardening (H > 0, e.g.
copper_c110's 603 MPa) keeps k_t above 0 and helps. - Read
"<rod>.plastic_strain"to see where and how far a wire yielded.
Planned fix
An implicit rest update, with the section's tangent in the rod solve's joint Hessian, so the step converges like the elastic one. Not scheduled. Reversed loading has no Bauschinger effect (the model: plasticity-metal.md).
A rod folded tighter than one segment passes through itself¶
What is wrong
A rod on the elastic-rod route (rod_vbd) collides with itself: every pair of segments that are not neighbours
makes contacts. When the rod folds back on itself (a hairpin, a coil) more tightly than one segment's length, the
segments at the fold overlap. They go deep, the world fails its health check (PEN_FAIL, ENERGY_JUMP), and it is frozen
at its last good state.
Number
CPU, alloy.Scene + alloy.build. A USB cable (cable_usb_composite, r 3 mm), laid flat on the ground as a
hairpin: two 0.15 m legs 30 mm apart, joined by a half circle. A held 0.05 N push on one leg's end closes the legs
(a development script and its logs, not shipped):
| segments (length) | closest legs, centre to centre (6 mm = touching) | sim.check() |
|---|---|---|
| 40 (8.7 mm, 1.45 diameters) | 5.0-5.4 mm | fails at 0.55 s: a 5.7 mm deep contact, an energy jump |
| 80 (4.3 mm, 0.72 diameters) | 6.7-7.7 mm, legs touching and holding | ok |
Why
Two causes, not yet separated: - The fold at the hairpin's end closes to about the rod's own radius. A segment longer than that fold cannot bend around it, so the segments on either side of it overlap. - Contacts between two segments of the same rod are solved Jacobi: each treats the other as held for that iteration. This is stated in the rod solver's own notes. It is weaker than the contact against a fixed or rigid body.
Workaround
- Where a rod folds or coils, give it segments shorter than about its diameter (
Scene.add_rod(segments=)). - Read
sim.check()after a run in which a rod touches itself.
Planned fix
- Self contact solved inside the chain's own block solve, so a fold is not Jacobi. It is not scheduled.
- Coils and knots get a law of their own (contact force and the shape they settle to) before anyone relies on them.
A thin rod's twist vibration rings too slowly or not at all (CHAIN route)¶
What is wrong
- A flexible rod object (a card the router reads as a rod, such as a cable laid along a curve) goes to the CHAIN route: MuJoCo D6 joints with a twist spring k = G J / l per link. Under a steady end torque it twists by exactly T L / (G J). That is law A11.torsion, error 1.1e-6.
- How the twist moves on the way there is not physical for thin rods. A real rod released from a twist rings at its first torsional mode. Alloy's chain, at the production step, either decays smoothly (card damping) or rings at a few steps per period and dies out within tens of milliseconds (near-undamped). At a step small enough to resolve the mode, it rings 2.6x too slowly.
- Bending dynamics are not affected. Their modes are far slower and have their own laws (A11.cantilever, the rod self-test, the hanging-chain swing that A10's armature check moved by 0.28 % at most).
Number
CPU, MuJoCo C, measured with development scripts (a twist-release script and a floor-pair script; not shipped). The rod is the law's: 30 links, 0.5 m, 2 mm radius, G J = E I / 1.3. It is twisted 0.5 rad, held, then released. The continuum's first torsional mode is 3,051 rad/s (486 Hz, period 2.06 ms).
| step | armature on each twist dof | damping | released twist |
|---|---|---|---|
| 1.25 ms (production) | 1.29e-6 kg·m² (stability term, 2,478x the link's I) | 0.05 | decays, e-fold 3.6 ms (continuum: 4.5) |
| 1.25 ms (production) | same | 0.0005 | rings a few steps per period, gone in 20-50 ms |
| 25 µs | 1e-6 kg·m² (the floor, 1,923x) | 0.0005 | period 5.32 ms (2.58x) |
| 25 µs | none (probe only) | 0.0005 | period 2.061 ms (+0.07 %) |
Damping is the bend-mode damping ratio the chain's stiffness-proportional damping is set from; at 0.05 the continuum's twist mode is damping-limited too.
On the ROD_VBD route (a development twist-release script, not shipped). This is Newton's
Cosserat rod on SolverVBDRod, the same rod from the ROD_VBD emitter, with no armature:
| step | damping | released twist |
|---|---|---|
| 1.25 ms (production) | 0.05 | decays, no ringing, e-fold 5.1 ms (continuum: 4.5) |
| 1.25 ms (production) | 0.0005 | 0.042 rad after one step: backward Euler damps the mode out within ~2 steps |
| 25 µs | 0.0005 | period 2.080 ms (+1.0 %) |
So the chain itself carries torsion correctly; the armature is what slows it. An estimate, not measured beyond this rod: the first mode's period grows by about sqrt(1 + a (pi / 2N)² / I), with a the armature, I = m r² / 2 one link's axial inertia and N the link count (2.5 here at 25 µs, measured 2.58). - The stability term makes this sqrt(1 + (omega1 h)² / 2) for any radius: 2.9x for this rod at the production step, where the mode lands at about 4.4 steps per period (it can never exceed omega h = sqrt(2)) and implicitfast damps it out. - The floor's share shrinks as r⁴: for a 1 cm rod of the same length and links it is about 0.4 %.
Why
- The torsional wave speed sqrt(G / rho) is about that of sound in the material, so a rod short enough to handle has its first twist mode at hundreds of Hz. Its period is 4 L / sqrt(G / rho), independent of the radius: at 10 steps per period the 1.25 ms step resolves only rods longer than about 3 m of this material.
- The CHAIN emitter gives every rotational dof armature max(2 k h² / 4 - I, 1e-6 kg·m²). The first term keeps implicitfast stable at the step h; the floor keeps MuJoCo Warp's float32 Newton solver finite on contact-loaded light links (A10's rope went non-finite in 16 of 16 worlds at 1e-9). On a thin rod's twist axis both are far more than the link's own inertia, and armature acts on the joints' relative rates, which the twist mode drives.
Workaround
- For a steady or slowly applied twist (a cable routed with a set twist, unwinding paced by damping) none is needed: statics are exact, and the damped release decays in 3.6 ms against the continuum's 4.5 ms.
- A thick rod's twist vibration needs a step that resolves it (omega1 h well under 1, e.g. 20 steps per period); the floor then moves it little (the estimate above). Check sqrt(1 + a (pi / 2N)² / I) for your rod first.
- No setting removes CHAIN's floor, so on CHAIN a smaller
dtalone gives the 2.6x-slow mode above. - A thin rod's torsional vibration (a torsional pendulum, a twist wave) needs the ROD_VBD solver (no armature) at a step that resolves the mode: the period came out +1.0 % at 25 µs. ROD_VBD is routable from R2 of the rod change.
Planned fix
None planned. The floor could drop where float32 does not apply (the CPU route runs MuJoCo C in float64), or on the twist dofs if the float32 failure does not need them there (A10 found armature on one dof group alone not enough). Either needs A10's 16-world check rerun. Revisit if a task needs torsional vibration; the law to add is the release period against omega1 within a few percent at a resolving step.
An elastic rod beside a robot runs far slower than the chain on the CPU¶
What is wrong
A rod on the elastic-rod route (rod_vbd) that a robot can touch steps in its own solver. The robot steps in
MuJoCo, and the two exchange forces many times per control step. On the CPU that makes a rod-and-robot scene much
slower than the same rod on the chain route, which steps inside MuJoCo with the robot.
Number
CPU, one core, warm, a 0.4 m USB cable (r 3 mm, 20 segments), alloy.Scene + alloy.build. Measured with a
development API-speed script (not shipped).
| scene | chain | rod_vbd |
|---|---|---|
| the cable dropped on the ground | 0.90 s per simulated second | 2.49 s |
| the cable's end squeezed by two 0.2 kg pads on a MuJoCo wrist | 1.00 s | 94.9 s (95x) |
The clamped gripper rig of tests/api/test_rods_grip.py runs 82.9 s per simulated second. A rod-only solver entry
runs 4 VBD iterations; at 10, on the same machine, the three rows read 4.49, 161.2 and 137.1 s (before a cached
attribute lookup in the coupled model view, the squeezed cable took 216 s).
On one L4 GPU (MuJoCo Warp), in simulated s per wall s summed over worlds, at 4 iterations. Both scenes were
measured in one run on one tree (2026-11-09; development scripts, not shipped); every row passed sim.check().
The squeezed cable (the CPU table's second row):
| worlds | 1 | 64 | 256 | 1,024 | 4,096 |
|---|---|---|---|---|---|
| chain | 1.2 | 35 | 105 | 168 | 172 |
| rod_vbd | 0.062 | 2.6 | 6.2 | 17.6 | not measured |
| chain / rod_vbd | 20x | 13x | 17x | 10x |
The clamped gripper rig of tests/api/test_rods_grip.py, the chain by clamp="start", route="chain":
| worlds | 64 | 1,024 |
|---|---|---|
| chain | 55 | 225 |
| rod_vbd | 2.6 | 17.7 |
| chain / rod_vbd | 21x | 13x |
So on a GPU rod_vbd beside a robot runs 10-21x slower than the chain. An earlier run of the squeezed cable read
22-55x: its rod_vbd rows were at 10 iterations (half the speed), and its chain rows read 61 and 160 at 64 and 256
worlds, on an earlier tree.
Why
The exchange step is the largest dt / 2^j no longer than 0.5 sqrt(m / k), where m is the lightest robot body that
could touch the rod and k the contact stiffness (2e6 N/m). Two 0.2 kg pads give 158 us, so j = 6: 64 exchanges per
10 ms control step, each one a MuJoCo step and two coupling passes of a 4-iteration VBD solve of the rod and the
robot bodies that touch it. The chain needs none of this.
- On the CPU the time is in the solver's launches, not the physics: an exchange at 10 iterations was about 380 small
kernel launches, about 90 us each, and MuJoCo takes 3 % of the wall.
- One coupling pass instead of two, or 2 VBD iterations instead of 4, is faster but loses the grip: the cable
stops following the wrist (tests/api/test_rods_grip.py).
Workaround
- Short elastic rods next to a robot route to the chain by default; keep them there unless the scene needs the elastic rod (more than 40 segments, both ends clamped, a yielding wire).
- A rod clamped at one end can stay on the chain:
add_rod(..., clamp="start", route="chain"). The gripper rig then runs 1.3 s per simulated second on the CPU instead of 83 s, and holds its twist as the rod does (on the CPU a held chain creeps back about 0.14 % per second;docs/guide/rods.md, Robots). - Give pads and links near the rod realistic masses: the clock grows with sqrt(m).
- Run elastic-rod-and-robot scenes on a GPU, many worlds at once: on one L4 the squeezed cable ran 17.6 simulated
s per wall s over 1,024 worlds (the table above;
docs/guide/rods.md, Routes).
Planned fix
- The per-period exchange ladder (a world re-runs only the period that needs a finer step) does not change these rows: none of their periods refined.
- A cheaper exchange. Done: a cached attribute lookup in the coupled model view (216 -> 161 s, bit for bit the same result) and 4 VBD iterations for a rod-only entry (161 -> 95 s; the grip law holds); a clamped short rod on the chain as an opt-in (Workaround). Next: fewer launches per exchange, or a coupling that holds a stiff pad contact at a coarser step.
rod_vbdbeside a robot at 4,096 worlds was not run in this pass.- The default stays the chain for short rods until this gap closes.
- GPU free rods were named the next candidate to move to
rod_vbd. Throughalloy.buildon an L4 the chain is faster at 1,024 worlds (178 against 148 simulated s per wall s) androd_vbdat 4,096 (303 against 180;docs/guide/rods.md, Routes).
Soft bodies, cutting and plasticity¶
Known gap: a body dropped on a soft solid bounces back far more than the materials' restitution says¶
What is wrong
- A rigid body landing on a soft solid (a VBD tet mesh: pads, foams, silicone) bounces back almost as fast as it arrived. The soft solid's bulk returns the impact energy, and the card's restitution sets nothing on this path.
- The contact records between the body and the soft solid do not change this: scaling their damping 0.2x to 3x leaves the bounce the same. The dissipation that should set it is missing in the bulk (material damping), not at the interface.
- A body landing on a cloth lying on a support is different. There the records' damping does set the bounce (with the cloth's own contact with the support), and no measured reference exists to size it from: cotton's card restitution 0.0 is a model value.
Number
CPU, Warp route, main cacec9764 (2026-11-08); measured with a development bounce probe script (not shipped). Each landing body's record damping is scaled x1 (as built), x0.2 and x3. - C3's 0.515 kg wood_beech platen dropped 1 mm onto its 40 x 40 x 10 mm tissue_fat_silicone pad on the ground: lands at 0.154 m/s and rebounds at 0.137 m/s, e 0.89 (x1), 0.88 (x0.2), 0.88 (x3). The pair's card restitution (the lower of the two materials) is 0.2. - A 2 kg steel_carbon ball dropped 5 mm onto an 11 x 11 cotton_woven cloth (0.05 kg) on the ground: lands at 0.342 m/s, e 0.62 (x1), 0.76 (x0.2), 0.41 (x3). Cotton's card restitution is 0.0 (model), steel's 0.6. - Resting loads are right: the same platen at rest reads stretch 0.9035-0.9040 against the analytic 0.9029 (known gap coupled-record-damping).
Why
- The soft solid's elasticity has almost no material damping. An impact's strain energy comes back as rebound, and the records' damping only acts over the thin contact layer.
- A cloth on a support is one layer thick. Most of the dissipation is in the records against the body and in the cloth's own contact with the support, so the records' damping moves the bounce.
Workaround
- For a resting load (a box on a pad, a weight on a cloth), none is needed: place the body on the soft solid, or let it
settle (
sim.settle), instead of dropping it. - For a landing whose bounce matters, keep the landing pair rigid-on-rigid, where the card's restitution sets the bounce through MuJoCo.
Planned fix
- Soft solids: a material damping term for VBD tet solids, sized from the card (a loss factor, or the restitution of a drop test). Its law: C3's 1 mm drop rebounds within 0.1 of a measured e. Not scheduled.
- Cloth landings: record damping sized from the pair only once a measured drop reference exists (a body on cotton over a hard support). The restitution-sized record damping of gaps-now #10a (slice B) was measured and dropped on 2026-11-08: the numbers above have no sound target to size it to.
A small body resting on a coarse soft solid can sink into one surface particle past health's limit¶
What is wrong
- A soft solid (
soft_vbd) touches rigid bodies through one particle per mesh vertex. The particle radius r is 1/5 of the tet mesh's shortest cell edge. A 15 x 15 x 5 cm pad has 12.5 mm cells and r = 2.5 mm, so its surface particles stand 7.5 mm apart. A body smaller than a few cells can come to rest on a single particle. - Health's limit for a soft contact is r (half of 2r, the thinner part), and a deeper contact held for 0.1 s fails the world (PEN_FAIL). In sample-sweep's drop, a steel ball came to rest 3.36 mm into one particle, and the world froze 0.1 s after it settled.
- Every landing touches 3.4-3.7 mm for a moment (DEGRADED, PEN_WARN). Whether the body then rests that deep depends
on where and how it settles, so the same drop at another
dtor start height can pass. - A soft solid placed flush on its support starts one radius inside it. Alone on the ground, such a pad is thrown 3.6 cm up within 0.09 s, and nothing is flagged.
Number
One L4, main bd9e6b412 (rc6 steps the same code). Sample-sweep's ab_drop4 panel sil scene without its render: a
static worktop (top at z 0), a 15 x 15 x 5 cm silicone_40a pad (845 particles, r 2.5 mm) and a 27 mm
steel_carbon ball (80 g) dropped 15 cm onto the pad's top. Scripts: development probes, not shipped.
| pad | dt |
result |
|---|---|---|
| flush on the worktop (pos z 0.025) | 0.01 | INVALID at 0.536 s: the ball rests 3.36 mm into one particle |
| flush | 0.005 | check ok; the ball rests 0.2-0.4 mm deep |
| lifted one radius (pos z 0.0275) | 0.01 | check ok; 1.2 mm for a moment at a landing, then 0.2-0.3 mm |
| lifted one radius | 0.005 | check ok; 3.7 mm and 1.5 mm for moments at landings |
- In the frozen run the ball sits on the pad's top-centre particle. The next particles are 3.7-4.3 mm from touching it, so that one particle carries the ball's 0.79 N at 3.36 mm. Rolling over the same particle in the lifted run, the ball was 0.2 mm deep.
- The ball bounces several times before it settles (
soft-solid-bounce.md), so the runs settle in different places. - The flush pad alone, at
dt0.005: its bottom is at 5 mm after one step, 3.6 cm at 0.09 s, then it falls back.
Why
- Contact with a soft solid is vertex-only (
alloy/scene/emitters/deformable.py,soft_particle_radius): the surface between vertices does not push back. A body larger than the gaps cannot pass through, but it can balance on one vertex. - Health measures a soft contact against r, the particle's own radius.
- Not traced: why one particle holds the ball 3.36 mm deep in the frozen run, against 0.2 mm when the ball rolls over it.
- A VBD solid rests one radius above what it touches, so a solid placed flush starts that far inside its support, and the first steps push it out.
Workaround
- Place a soft solid one particle radius above its support (its pos z + r), not flush.
- Under a small body, use a finer tet mesh (the object card's
budget.tetssets the cell), so several particles carry the body. - At
dt=0.005the same drop passed. Always readsim.check()["ok"]after a body settles on a soft solid.
Planned fix
- Contact on a soft solid's surface faces, not only its vertices (as cloth's full-surface contacts do), or a surface-particle radius sized to the gaps.
- A start-overlap check for soft and cloth vertices (START_PEN today judges rigid contacts only), so a flush placement is reported at build.
Known gap (model limit): a flat tool pressed into soft FEM compresses it without limit¶
What
- Every cut model (pre-split seams, seam lattices, virtual-node copies) parts material only where a blade edge passes.
- A flat face pushed into a soft block cannot cut it, so the block is squeezed without limit. Tets invert, and any fragments cut from them later flip.
- An edge pressed where no seam plane lies under it does the same, for example a knife pressed onto cut slices that lie flat (the robot case below).
Number
- Random action traces on
cut_block_free(agar-like block, 5e4 Pa, 4 worlds, 0.3 s) took whole tets to 85 % principal strain at p90 and 208 % at most before a split. - The fragments inherited that strain: p90 35 %, max 198 %.
A robot case: a knife pressed onto cut slices (JOBRK finding 1, 2026-11-09)
- Setup: the T2 cucumber clear, restored from its hand-over checkpoint (4 worlds, t 105.9 s). The right arm pushes the knife straight down onto 1 mm cut slices that lie flat on the board, with their seam normals 81-89 deg from the blade normal. The blade comes down across the slices, so it lies on no seam plane that could open, and it crushes them.
- At 0.1 m/s, all 4 worlds go INVALID at t 106.8-107.9 s. In 3 worlds a slice particle is 1.6-1.7 mm into the blade; in the fourth the material is pressed 1.2 mm into itself.
- At the 0.6 m/s command (the hand reaches 0.23 m/s), 3 of 4 worlds go INVALID as the knife reaches the board (t 106.36-106.40 s). In two, a slice particle is 0.6 mm into the board; in the third, the material is 2.0 mm into itself. After that impact the knife turns in the grip by 0.6, 5.3 and 22 deg. At 0.1 m/s it never turned.
- A second effect, now limited to seams aligned with the blade face: in that push the cutter damaged every seam bond
its edge reached (the edge's depth times its travel, in any direction), with no test of the blade's alignment.
BladeContactdoes test it (min_alignment0.5). Of the 134 bonds the 0.1 m/s push broke, 115-117 (86-87 %) had their seam normal at |n . blade normal| < 0.5, with a median of 0.002-0.05 in three worlds.BladeContactwould not have opened them. The same holds for 23-24 of the 25 bonds damaged past 0.5 but still intact. - Since 2026-11-09 the cutter has the same test (
TopologyController.Config.cut_alignment, default 0.5): a blade cuts only seams within 60 deg of its own plane, so those bonds stay welded. - The 17-19 aligned bonds of that push can still break, and the crush itself is unchanged.
- The push has not been re-run with the gate. A unit law covers the case: a blade pressed through a flat seam
touches none of its bonds (
tests/topology/test_cut_alignment.py). - Workaround: clear cut pieces with something other than the blade edge, as a scripted clear in a robot cutting scene does (the pads push from behind the last cut). From the same restore it kept all 4 worlds valid over 9 s (max penetration 0.21 mm).
The cutting tasks after the cutter's alignment gate (2026-11-10)
Random legal blade paths, 2,048 episodes each, seed 100000, 2 s, one L4, both arms on one commit (f690c5e48). "Any
seam" is the rule before, kept as the targets cut_block_stroke_anyseam and cut_block_free_anyseam.
| Task | Rule | Failed (S1) | Flagged only (S2) | Clean |
|---|---|---|---|---|
cut_block_stroke |
any seam | 615 | 2 | 1,431 |
cut_block_stroke |
gated | 86 | 3 | 1,959 |
cut_block_stroke |
gated, with the blade contact's re-entry case (the default since 2026-11-10) | 12 | 0 | 2,036 |
cut_block_free |
any seam | 1,954 | 1 | 93 |
cut_block_free |
gated | 1,326 | 16 | 706 |
- A repeat of three of these runs read 82 / 4 (stroke, gated), 1,324 / 15 (free, gated) and 1,957 / 1 (free, any seam): about +-10 episodes run to run.
- The S2 episodes are all
STRAIN_RANGE, this page's flag. In the repeat, all 15 ofcut_block_free's were failed (PEN_FAIL) episodes under any seam; none was clean before. They read S2 now because the failure that came first is gone. - World by world in that repeat, any seam to gated: 628 failed episodes became clean, 15 became flagged only, 1,314
stayed failed, and 10 clean ones failed. The 19 gated episodes whose cause reads
inverted_tetswere failed under any seam too (17 as PEN_FAIL). - What still fails:
cut_block_stroke's 86 were PEN_FAIL late in the episode (median tick 94 of 125). Of 4 traced, 3 were an edge coming down again into an opened cut 0.1-0.9 mm off its seam: the freed twin lay just across the blade's mid-plane and the blade's bottom pressed on it, 0.53-0.58 mm deep against the 0.5 mm limit. The blade contact now puts a twin that lies ahead of a descending edge on its own face (BladeContactConfig.reentry; the rule before is the targetcut_block_stroke_noreentry), and 12 of 2,048 fail.- 10-12 fail with it in four runs (two of them an independent audit's), and some of these are new with the case:
worlds 13, 1432 and 2021 failed with it and were clean without it in both audit runs, and only 6 of the 10-11
left are shared with the rule before. CPU replays, both arms, of the 10 from one run:
- 1077 and 1432: the case draws a parted twin from past the far face (0.8-1.3 mm across the mid-plane, the blade 1 mm thick) back into it, and the far face's stock record reaches 0.66 / 0.86 mm. Without the case 1432 is clean and 1077 fails later. A follow-up that allows the case only for a twin whose centre is inside the blade's thickness was tried and not merged:
- it removed this pull, but the pull also kept twins on their side in other worlds (1343, 557, 1911), which then failed or were flagged without it;
- its count stayed within the run-to-run spread (9-14 against 10-15 in 2,048, two runs each by an independent audit).
- In both mechanisms, two contradictory blade records take turns at a rule's boundary: the ramp's edge here, and the cut-front pair cap in 1343.
- A rule that keeps a twin's face side fixed through a contact is the planned fix.
- 360 and 497 (the same with and without the case): the seam's bottom corner twin is inside the neighbouring piece after the cut is through. 835: the same with the case, clean without it.
- 1024, 1798, 1868 and 2021 are clean on the CPU in both arms, and 1288 is clean with the case (flagged only without it): those failures were seen only on the GPU.
- No robot scene has fired the re-entry case yet: a robot cutting scene (a first press, and two rounds with the
knife sweep) and a dough-cutting clip counted 0 records, so the default changes nothing there. Its evidence is
cut_block_stroke(86 -> 12, in two runs) and the law intests/topology/test_blade_contact_zone.py. cut_block_free's 1,326 are not diagnosed. Its cut faces do not collide (no self-contact on that task), so part of them is cut pieces passing through each other.
Why
- The FEM is linear-elastic on a fixed mesh.
- No cut model splits a tet under a face, and nothing remeshes as the material deforms.
- The model is valid only well below these strains.
Workaround
- The cutting tasks hold face-first blade motion to a +-1 mm band, because a cutting task drives the edge. The
tasks are
cut_block_stroke,cut_block_freeandcut_block_free_copies. - The health flag
STRAIN_RANGE(DEGRADED) marks any world past 60 % principal strain, so results past the range are flagged, not silent. The strain is measured byalloy.topology.soft_strain.SoftStrain.
Planned fix
- Large-deformation remeshing, after launch.
- The second effect: a re-run of JOBRK's push with the cutter's alignment gate, to count the bonds it still breaks
Known gap: cut_model: copies on a coarse mesh (pieces with one node layer, no kerf, what .points holds)¶
What
With topology: {cut_model: copies} a knife cuts a soft object along any path. A cut tet's material goes to two
fragment tets of the whole tet's shape. Each fragment keeps the mesh nodes on its own side of the cut and takes a
copy vertex for every node on the far side. Those copies are not material: they lie outside the piece and nothing
touches them. That gives five limits, all largest on a coarse mesh.
- A piece needs two layers of mesh nodes. A piece left with one layer of nodes has nothing under its cut side, so it tips toward the knife and leans through it.
- The knife opens no kerf between nodes. Only mesh nodes meet the blade's faces. Where no node lies within the blade's thickness, the cut faces stay inside the blade.
"<name>.points"holds the copies too. They sit on their mesh node until a cut wakes them, then some lie outside the material. A bounding box or centroid taken over.pointsafter a cut is wrong.- A cut piece can creep on the ground at the soft solver's default accuracy.
- A drawing from
alloy.exportframes shows each fragment as its whole tet, so the two pieces overlap across the cut by up to one cell, and the cut face itself is not drawn.
Also: one knife per world. A second blade in a world raises ValueError at build, naming both blades.
Number
All on the CPU, on the example's 20 x 15 x 15 mm agar block (50 kPa) of 96 tets (cells 5 x 7.5 x 7.5 mm) and its
1.2 mm knife at 0.05 m/s (examples/topology/cut_anywhere.py; main 6f5da6ef2 with this page's commit; the y cut's
node positions, the parting and the creep speeds measured again on main 692add686, after a drive's velocity moved one
physics step earlier: the same; the copy below the ground was 2.0 mm before this page's fix).
| Limit | Case | Value |
|---|---|---|
| 1 | knife plane 1.7 mm off the middle y plane (2 cells across): the 5.8 mm piece has one node layer | its top outer nodes move from y 7.5 mm to 2.3 mm by 0.4 s (the knife's plane is at 1.7 mm); sim.check() ok |
| 1 | knife plane 1.7 mm off the middle x plane (4 cells across): both pieces have two layers or more | every node within 0.1 mm of its settled height, none sideways; 24 tets cut; max penetration 1 um |
| 2 | that x cut, knife still in the block | the pieces have parted 0.09 mm (blade 1.2 mm) |
| 3 | that block | 135 points for 45 mesh nodes; in the y cut a copy read 1.8 mm below the ground plane |
| 4 | that x cut, the 8.3 mm piece (1.8 g), after the knife stops | 0.56 mm/s for at least 2.7 s at 10 solver iterations; 0.41 at 20, 0.21 at 40, 0.007 at 160 (set on the engine's solver in a probe) |
| 4 | the 11.7 mm piece (2.8 g) | 0.005 mm/s |
Why
- 1, 3: a copy stands in for a node of the other piece, so it carries no ground or blade contact (a far copy pushed
by the blade shoved material at 0.39 m/s in an off-node stroke,
alloy/topology/vnode_split.py). A piece is held up by its own mesh nodes only. - 2: contact is between particles (mesh nodes) and shapes. A cut face between nodes has no collider.
- 4: the soft solver runs 10 iterations per step and its momentum correction is off while a body touches the ground
(
alloy/solvers/vbd/solver.py, Scope). The leftover is a small steady push on a piece whose mass hangs past its last supported node row. The probe raised the count on the engine's solver; whether a scene setting (cloth_accuracy) reaches a soft body's solve was not tried. - 5: the frame's
mesh_tetsare the fragment tets; where the cut plane crosses them is not exported.
Workaround
- Place the cut, or choose the tet budget, so that each piece keeps at least two layers of mesh nodes across its thinnest direction. In the example the knife crosses the block's long axis (5 mm cells), not its short one.
- For a kerf of the blade's thickness use cells no larger than the blade is thick. That is not measured here.
- Read a cut object's mesh nodes, not all of
.points:nodes = frame_export(sim, [0])[0].topology.mesh_vertex_active["<name>"]taken before any cut is True for the mesh nodes (from alloy.export import frame_export); index.pointsor the frame'smeshes["<name>"]with it. frame.topology_version >> 40is the number of tets cut so far.- Do not read a cut piece's rest position to better than 1 mm per second of simulated time.
Planned fix
None scheduled. A cut-face collider (2) and ground contact for the material under a copy (1) are the two changes that would remove the mesh-size limits; exporting each split tet's cut plane would fix the drawing (5).
Known gap (reference limit): the seam knife-force reference holds only until the first cut¶
What
- The knife-force calibration on a soft block (TOP-2) uses a pre-split seam twin as its reference.
- After the first node is cut, the twin's force is a contact artefact, not cutting resistance.
- So the calibration describes only the force before the first cut and the cut timing. It does not describe the force while the blade cuts through.
Number
- After the first cut, the seam twin reads 0.65-0.95 N down to 3.5 mm. Each stuck twin carries 0.12-0.19 N of it.
- With face-aware blade contacts, the same twin reads about 0 N.
- Before the cut, virtual-node copies match the twin within 2.1 % pointwise:
- peak 0.613 vs 0.615 N;
- mean 0.421 vs 0.422 N;
- cut at step 205 vs 206.
Why
- The reference runs on stock contacts.
- Its cut twins stay stuck under the edge and compress the column below.
- The + twin is pushed onto the wrong face and rides up.
Workaround
- Cut models are judged on the pre-cut segment and on the cut timing.
- The production cut targets use face-aware blade contacts, so they do not carry the plateau. Seams use
BladeContact; copies useVNodeTopology. - The copies' Simulation entry splits with the
leadrule, so its knife meets no cutting resistance at all.
Tried: a face-aware seam reference (2026-11-08)
Setup: the TOP-2 rig on agar (softness 1, cut_spring_ke 1000) on CPU, at the law's dt (5e-4 s) and at dt/2. The knife force is read two ways: - the twin's readout: normal penalty force only; - VBD's whole contact law at the solved positions: normal, damping and Coulomb friction, with the knife's descent velocity set.
Results:
- Friction is part of the force today.
- Stock seam twin: the whole contact law reads 0.674 N pre-cut peak against the normal-only 0.615 N (+10 %).
- Copies under the same readout: 0.678 N, so pre-cut agreement is unchanged.
- The seam twin's drive used to set no knife velocity, so its friction never saw the descent; the copies twin's
did. Both now set it (twin._drive_knives). The seam twin's normal-only numbers do not move: peak 0.615 N before
the cut, the first cut at step 206, 0.956 N after it.
- The seam twin under BladeContact (C2's ramp) is not a reference:
- the knife's depth at the first cut is 3.0 / 2.94 mm (dt / dt/2), against 1.16 / 1.10 mm with stock contacts;
- before that cut the knife carries 2.1 N, all face friction (the normal-only readout reads 0 N);
- particles reach 4.0 / 7.7 m/s (worse at dt/2).
Twins activated by bond damage ahead of the edge go onto the faces while still welded. They clamp the blade, and the edge stops loading their bond. - Copies under face contacts (work rule) are not converged: - past the first cut the force peaks at 9.0 / 7.8 N and dips to -3.5 N; - particles reach 5.4 / 6.0 m/s; - 18 / 15 nodes are cut by 4.3 mm.
Measured with a development probe script (not shipped).
Planned fix
- The face-aware reference needs face records that do not clamp the blade before the bond breaks.
- The readout and both twins' knife velocities should match VBD's contact law.
- Or a measured cut-through force (for example agar cutting data) for the
worksplit rule. There is none in the repository: DiSECt's force CSVs are LS-DYNA output.
Plasticity: J2 covers soft volumes, joint springs, metal sheets, wires and coil springs; bulk metal parts stay rigid¶
Status: open, being closed in phases by the J2 metal-sheet change. Build estimate below.
Now covered
- One J2 model (
alloy/solvers/plastic/j2.py): von Mises, linear isotropic hardening. Card fieldsplastic.model: j2,plastic.yield_stress(σ_y0),plastic.hardening_modulus(H). A j2 card keeps its solid route; a yield_stress alone still makes a paste. Metal cards carry sourced values (db81a79f0). - Soft volumes that yield (VBD tets,
alloy/solvers/plastic/tets.py): a j2 card on the soft_vbd route. - MuJoCo 4.0's column row: onset bracket (76, 77] mm against 76.45 analytic (RERUN.md's
alloy.scene.analytic_plastic:column_case). - A stretched bar's plastic strain is within 0.3 % of the 1-D law.
- Off is bitwise the stock solver. The hook costs about 1.05x a VBD step (CPU, 8,640 tets), 0.99x on an L4.
- At a small yield strain (σ_y / E under 10 %) a resting soft body can yield spuriously, and the build warns: plasticity-soft-tets-low-yield.md.
- A bent tet bar keeps a bend (
analytic_plastic.bend_case), but only to 0.75-1.26 of the section's closed-form residual at 4-8 elements through the depth: linear tets bend about 11 % stiff, and VBD settles bending slowly. Precise bending is the sheet and rod sections' job. - L4 smoke: 64 column worlds yield in height order, with the onset bracket (75.87, 76.51] mm.
- Joint springs that yield (P2,
scene.set_joint_yield,alloy/plugins/joint_yield): a hinge's torsion spring or a slide's spring (MJCFstiffness,springref) takes a permanent set past a yield torque or force, with optional linear hardening. The 1-D J2 return moves MuJoCo's own per-world spring reference (MuJoCo Warp'sqpos_springrows, each C-route world's model), so no force is added. - J1, a torsion spring cycled past yield with hardening (forward set, reverse yield, an elastic poke): rests within 2.2e-8 rad of the closed form. J2, a preloaded slide overloaded and released: set q_max - F_y / k within 6e-9 m. Both CPU routes (MuJoCo C, MuJoCo Warp).
- Off is bitwise: no yield set, no plug-in; a yield never reached gives the stock trajectory bit for bit.
- The hook costs about 40-60 µs per physics step on a loaded 4-core host (2-3 % of a step), on both CPU routes.
- Metal sheets that dent (P3,
alloy/solvers/film/sheet_j2.py):scene.add_cloth(..., material=<a j2 card>)routescloth_film, whose hinges carry the plane-strain J2 section and keep a dent;"<sheet>.plastic_strain"reads it. S1 pure bending within 0.27 % of the closed form (Gardiner within 0.33 %); S2 a strip dented by a cylinder follows the statics and its kept curvature hinge by hinge; S3 a can wall keeps a fingertip dent (measured rows). Design and numbers: the sheet-plasticity development notes (not shipped). Its limits (VBD sags a stiff sheet at real density; the hinge network bends unlike a plate): film-metal-sheets.md. - Wires and coil springs that yield (
rod_vbd,alloy/solvers/rod/plastic.pyon the shared J2 fibre section): a rod whose card hasplastic.model: j2(e.g.copper_c110) keeps a bend or twist past yield, and"<rod>.plastic_strain"reads it. Laws (tests/solvers/plastic/test_rod_laws.py,tests/solvers/rod/ test_rod_plastic.py; solver laws, 4 VBD iterations; CPU, copper, perfectly plastic): - a 0.2 m cantilever wire at a root moment of 1.5 M_y deflects within 0.7 % of the closed form on the rod's own joints and keeps a tip set within 2.8 % of it;
- a coil spring (coil radius 10 mm, 3 turns, 32 segments per turn) compressed at a wire torque of 1.25 T_y compresses within 0.9 % of wire torsion theory and loses 0.58 mm of free length against the theory's 0.57 mm (+2 %). At 16 segments per turn it keeps 8 % less: each joint twists about its segment's axis, half a corner off the wire's tangent, so give a coil at least 32 segments per turn;
- below yield both spring back fully.
A yielding rod always steps on
rod_vbd, which is slow beside a robot. Near the fully plastic moment it settles slowly and less accurately: rod-plastic-near-full-yield.md.
Limits of the J2 model
- No kinematic hardening: no Bauschinger effect. A reversed load yields at -σ_y(ε̄p), the isotropic surface, so cyclic bending under-predicts reverse yielding.
- No metal bulk forming on VBD tets: at E 200 GPa a VBD tet volume needs tiny steps. The volume laws use soft solids (E 1e5 Pa, as MuJoCo's column), and a forged or pressed metal block is not claimed.
- Joint yield (P2) covers one-axis MJCF joints on the MuJoCo routes. Hinge and slide joints with a linear
spring only. Not yet beside cloth, liquid or soft bodies: the build refuses a coupled stepper, naming this file.
The return runs once per physics step, after it, on the step's coordinate, as MuJoCo's own spring is explicit.
Tendon springs, rods and cables stay elastic. MuJoCo 4.0's own MJCF spring-yield attribute is not read: Newton's
importer drops it, so give the yield with
scene.set_joint_yield. - The soft_vbd default start under-converges a tall soft solid: Newton's inertial start settles a 70 mm column
(E 1e5) 1.6-2x past its static sag at 20-100 iterations, and 1.04x with Chebyshev 0.9. VBD's adaptive start
(
alloy_initial_guess="adaptive") settles it to 0.999; the column twin uses it. A plastic soft body on the default start would yield early.
What is wrong
What Alloy's plasticity covers today:
- Soil and grains (implicit MPM, grain_mpm): Mohr-Coulomb through plastic.friction_angle + plastic.cohesion.
Cards: soil_sand_dry, soil_clay_loam, soil_loam_moist, soil_hardpan, sand_silica_dry, flour_wheat, rice_grain.
Laws: a vertical cut stands below the critical height, column collapse vs Lube 2004, cone index vs Luke 1992
(the soil design note, not shipped).
- Pastes and dough (implicit MPM, paste_mpm): yield stress + Bingham / Herschel-Bulkley flow. Cards:
dough_wheat, batter_bread_wheat, peanut_butter, mayonnaise, sauce_ketchup, yogurt_plain, the paints.
- Paper and plastic film (cloth_film): an elastic-perfectly-plastic bending hinge (crease memory: past a yield
angle the rest angle follows; alloy/solvers/film/hinge.py, the dead-fold test), plus an in-plane strain cap at
yield / E. No hardening.
What it does not cover:
- Bulk metal bending and forming. A thick metal part (a bar, a bracket, a rack) keeps the rigid route and never
takes a permanent bend; J2 runs on soft volumes, joint springs and thin sheets only (Now covered). Before
the J2 metal-sheet change none of the 11 metal cards had plastic fields; they now carry sourced J2 values.
- Springs that yield, apart from joint springs and j2 rods (above). MuJoCo tendon springs, rod and cable cards
without plastic fields, and the clips' sprung members are linear elastic at any load. An overloaded spring of
that kind returns to its rest length.
What a user sees if they try:
- A metal bar or sheet bent by a robot or a press does not deform (rigid route). Nothing warns.
- A metal card given plastic.yield_stress (say 250 MPa) is routed paste_mpm with the reason "paste: yield
stress 2.5e+08 Pa". It becomes MPM particles: a pressure-independent yield (Newton's implicit MPM with friction 0)
at the router's voxel, min(d/4, 5 mm). A 200 x 20 x 20 mm bar gets 4 voxels across, 5,120 particles. A
200 x 50 x 2 mm sheet fails to build: "CapacityError: sheet: 1280000 MPM particles > budget 200000". Nothing about
that MPM solid is validated as a metal: stiffness, yield, hardening, spring-back.
- A wire or coil spring whose card has no plastic fields springs back fully past its yield load.
Number
- Before the J2 metal-sheet change: law tests for metal plasticity 0, metal cards with plastic fields 0 of 11 (now: Now covered).
- The probe above: CPU, main a6b698923,
alloy.buildonly, no step.steel_carbonplusplastic.yield_stress250 MPa: - the 200 x 20 x 20 mm bar routes paste_mpm, 5 mm voxel, 5,120 particles;
- the 200 x 50 x 2 mm sheet: CapacityError, 1.28 M particles;
- plain steel_carbon, the same 2 mm sheet: rigid.
- Scale of what is missing:
- steel yields at about 0.11 % strain (S235: 235 MPa / 210 GPa); the film route's paper caps at 1.4 %;
- a 1 mm steel sheet's elastic curvature limit is 2 sigma_y / (E t), about 2.2 1/m (a 0.45 m radius);
- before P3 no route resolved it: MPM needs sub-mm voxels, and the film hinge had no hardening and no metal card (P3's J2 sheets now resolve sheet bending; a bulk part still has no route).
Why
The plastic models were built for what the task list asked for: food, soil, paper and film. Metal parts entered as rigid bodies (connectors, tools, racks), where the contact matters and their deformation does not.
The pieces that exist do not combine into metal bending:
- MPM's yield is volumetric and needs many voxels across a thickness;
- the film hinge is the right shape for sheet bending (moment-curvature at hinges), but it is perfectly plastic and
tuned to paper's yield angles;
- rods yield (j2 cards on rod_vbd), but a rod is a line, not a bulk part.
Workaround
- For a permanent bend in a task, model the bent part in its bent shape (a second card), and switch it at the step the bend happens.
- A clip or spring on a hinge or slide joint:
scene.set_joint_yield(joint, torque= or force=)gives it a permanent set. A rod or tendon that must not exceed yield: read its force (sim.state, or the rod's internal moment) and fail the task when it passes the material's yield load. - Do not put
plastic.yield_stresson a metal card: it turns the part into an unvalidated MPM paste.
Planned fix
None scheduled. Build estimate, in the order it would pay off:
1. Springs and wires that yield: done (J2 rod joints on rod_vbd, 2026-11-08; the laws above: a cantilever's
tip set, and a coil spring's free-length loss against wire torsion theory). Its limit is near full yield:
rod-plastic-near-full-yield.md.
2. Sheet-metal bending: done (P3, the J2 metal-sheet change: J2 sheets on the film route, laws S1-S3). Its own
limits: film-metal-sheets.md.
3. Bulk metal parts, 1-3 weeks. Either:
- validate Newton's implicit MPM von Mises (friction 0, yield_stress, hardening) at metal stiffness, about
1 week; limited by resolution, needs ~8 voxels across a section;
- or add J2 return mapping to VBD tet soft bodies, 2-3 weeks with a tensile-curve law and a bending law.
Only if a task needs bulk forming.
A soft body that yields can yield spuriously at rest when its yield strain is small (under about 10 %)¶
Status: open, accepted for launch (2026-11-09). The build warns. A punch dent in a metal-like solid is not supported on this route. Since 2026-11-10 such a solid can run on MPM instead, opt-in (Workaround), where it yields at its yield stress but reads a punch's force low (plasticity-mpm-solid-punch-force.md).
What is wrong
A soft body made of a plastic.model: j2 card (the soft_vbd route, VBD tets) should yield only where its stress
passes σ_y. When σ_y / E is small, a body resting on the ground under gravity also yields where the stress is far
below σ_y. It then slumps and creeps.
The cause is VBD's unconverged solve. At the start, and every step at rest, the solver leaves the lower layers more compressed than the static solution. The J2 return reads that strain as real and keeps it as plastic flow. With gravity off, nothing yields.
It applies to every solid (tet) body of a j2 card whose σ_y / E is under about 10 %, resting or pressed: metal-like
solids (σ_y / E about 0.1-0.3 %) and most plastics. Sheets and cans of metal cards (add_cloth, the cloth_film
route) are a different route and are not affected.
Number
CPU, blocks with a 30 x 30 mm footprint (E 3 MPa, ν 0.3, 1,000 kg/m³, perfectly plastic) resting on the ground, default mesh (about 3,000 tets), default VBD iterations (10). "Top" is the top face's height above the ground, which includes the 0.66-0.75 mm contact gap under the bottom face; the elastic 30 mm block's top sits at 30.62-30.75 mm.
30 mm tall, 0.4 s; its self-weight stress is about 300 Pa (strain 0.01 %):
| σ_y / E | σ_y | tets yielded | largest plastic strain | top after 0.4 s |
|---|---|---|---|---|
| 0.33 % | 10 kPa | 100 % | 23 % and growing | 28.07 mm, still sinking |
| 1 % | 30 kPa | 78 % | 7.8 %, still growing | not measured |
| 3.3 % | 100 kPa | 28 % (the bottom layers) | 3 %, then stops | 30.54 mm, steady |
| 10 % | 300 kPa | none | 0 | not measured (no plastic strain) |
The 1 %, 3.3 % and 10 % rows were measured on 2026-11-08 on the mesh before that day's fix (4,374 tets).
At σ_y / E 0.33 %, changing where each step's solve starts, or adding iterations, shrinks the spurious strain but does not remove it. 60 mm tall, 0.5 s; true self-weight strain 0.02 %:
| solve (probe settings, not public options) | tets yielded | largest plastic strain | wall time per simulated s |
|---|---|---|---|
| adaptive start (a resting body is a fixed point) | 86 % | 9.7 %, growing | 37 s |
| adaptive start, plasticity off for the first 0.2 s | 69 % | 1.7 %, growing | 36 s |
| adaptive start, 40 iterations, plasticity off for the first 0.1 s | 58 % | 0.62 %, then stops | 142 s |
| the same with Chebyshev acceleration (ρ 0.8) | 27 % | 0.55 %, then stops | 143 s |
The 30 mm block with the adaptive start and 0.2 s without plasticity does not yield; the 60 mm block does, so no start rule carries. The spurious strain grows with the load (about ρ g h / E, times what the solve leaves unconverged: 25-150x here).
Why
- J2 is exact only on a converged elastic state: it turns any strain above yield into permanent strain.
- VBD solves a soft body by per-vertex sweeps. A tall body under gravity needs many sweeps before the ground's support reaches its top, so the lower layers are over-compressed meanwhile, and a tall body's slow mode keeps moving at rest.
- With a small yield strain, that excess is enough to yield: even at 4x the iterations it is 25x the true strain.
Workaround
- Metal dents: use a sheet or a can of a metal card (
add_cloth(..., material="aluminium_6061_t6", thickness=...),docs/guide/deformables.md, Metal sheets). Those dent, spring back below yield and keep a dent past it. - A soft solid that yields: keep its yield strain well above its weight strain. For the 30 mm block, 10 % or more (σ_y ≥ 0.1 E). The build warns below 10 %, naming this page; a taller or heavier body may need more.
- A solid with a small yield strain, opt-in: give its object card the route override
paste_mpm(scene.add_box(..., card_extra={"route": {"route": "paste_mpm", "reason": "j2 solid on MPM"}})). It then steps on implicit MPM as a von Mises solid and does not yield at rest; a block squeezed between plates yields within 1 % of σ_y. Cards with a hardening modulus are refused (of the shipped metalsbrass_c360,steel_zinc_platedandsteel_tinplatehave none), and a punch's force reads low there (plasticity-mpm-solid-punch-force.md). - Read the plastic strain on the engine (
TetPlastic.ebar) to check that a resting body has not yielded. The API has no soft-body plastic-strain key yet.
Planned fix
After launch (2026-11-09): solid j2 cards with σ_y / E under 10 % route to implicit MPM by themselves, once the punch laws pass there (the open part: plasticity-mpm-solid-punch-force.md). The route is opt-in until then, and the VBD tet route keeps the warning.
A yielding solid on MPM: a punch's force converges for soft solids, and for metals only with mass scaling¶
Status: open. The route is opt-in (a plastic.model: j2 solid whose object card overrides its route to paste_mpm).
Uniform compression yields at the card's yield stress there. Since 2026-11-10 the route's entry solves each step to
tolerance 1e-5 with up to 1,000 sweeps and runs on the dense grid on any device; a punch's force then converges on
soft solids, but it is not verified against the indentation laws. Metals are supported on this route only with
quasi-static mass scaling (scene.set_quasi_static_mass_scale, opt-in, for a block that rests under a tool): without
it their stress solve does not converge, so a tool's force reads a few % of the truth, and the build warns.
What
- Stiff solids read a tool's force low. Each step Newton's implicit MPM solves the stress with projected
Gauss-Seidel and drops what it has not converged when it stops (
carry_residual_strain="none"). The sweeps a step needs grow with the square of the wave speed: in the rows below they follow roughly 0.2 (c dt / h)^2, with c = sqrt(E / density), dt the MPM step and h the particle spacing (half the voxel). That is a rough fit to the rows that converge (E 3-300 MPa, one voxel and step; the coefficient runs 0.05-0.2 there), not a derived law, and nothing stiffer converged, so the numbers for metals extrapolate it by 3-4 decades. At 3 mm voxels and the 1.25 ms step that is about 390 sweeps for E 3 MPa at 1,076 kg/m3, 3,900 for 30 MPa, and an extrapolated 1.6 million for brass (97 GPa, 8,500 kg/m3). A card over the entry's 1,000 gets a build warning naming the number. All three shipped j2 cards the route takes (brass_c360,steel_tinplate,steel_zinc_plated) are metals, so all three warn. - No punch law is claimed. On a resolved rig, converged at 1.5 mm voxels, the mean pressure by the measured contact radius reads 2.4 of the yield stress (the usual 2.8-3.0 is for shallow dents; the value at this rig's a / R is being cited), and the elastic force does not follow Hertz at 3 or 1.5 mm voxels. The force starts about 0.2 voxel before the surfaces meet.
- A tool that is moved (
kinematic=True,sim.drive) leaves a dent that follows it and stays, on soft and stiff cards alike. A tool that presses with a given force, or lands on the solid, sinks too deep where the force reads low.
Number
CPU dense grid unless named; a kinematic ball pressed at 2 mm/s into a block on a rough floor; E 3 MPa, Poisson 0.3
unless named. Rows: development notes, not shipped (rig rig3.py, batches b1-b4, g1-g4).
Converged share of the force at 1.0 mm (5 mm ball pressed to 1.2 mm, the force read as it passes 1.0 mm; 30 x 30 x 15 mm block, 3 mm voxels, 4,000 particles), by sweeps per step; the yield stress is E / 312 (brass's ratio) except the first row (50 kPa):
| E (density 1,076 kg/m3 unless named) | sweeps needed (estimate) | 250 | 1,000 | 4,000 | 16,000 |
|---|---|---|---|---|---|
| 3 MPa, yield 50 kPa | 390 | 0.84 | 0.99 (the route since 2026-11-10) | 1.00 | |
| 30 MPa | 3,900 | 0.63 | 0.94 | 1.02 | |
| 300 MPa | 39,000 | 0.07 | 0.28 | 0.77 | 0.98 |
| 3 GPa | 390,000 (extrapolated) | 0.03 | 0.11 | 0.43 | |
| brass, 97 GPa, 8,500 kg/m3 | 1.6 million (extrapolated) | 0.002 | 0.007 | 0.03 | 0.11 |
- Converged reference: E 3 MPa at 4,000 sweeps, 3.90 N; the stiffer rows scale it with the yield stress (p_m / yield 3.02 at E 3 MPa, yield 9.6 kPa, which converged in about 100 sweeps).
- A shorter MPM step also converges (0.99-1.01 at 0.31-0.08 ms), at 2-7x the wall time of 1,000 sweeps.
Pressing at half the speed changes nothing (within 2 %). Newton's
carry_residual_strain="unconverged", a Krylov pass before Gauss-Seidel, the batched or reordered sweeps, and other warm starts give no gain; without a warm start the force is 1 % of the converged one. - The route's change, one L4, the same rig, identical worlds: 3.31 N before (tolerance 1e-4, 250 sweeps; 1, 64 and 1,024 worlds), 3.86 N after (64, 256 and 1,024 worlds; both at 1.0 mm), the same in every world (spread under 3e-7); 1.4-1.5x the wall time (1,024 worlds: 2,666 s against 3,808 s for 1.2 s simulated). Under CUDA graphs the entry had the sparse grid, where the force rose from 2 mm above the surface and read 2.56 N at 1.0 mm; the dense grid reads 3.864 N on the L4 and on the CPU alike. Running without graphs cost nothing for this one-world scene (52 s eager on the dense grid against 90-100 s with graphs on the sparse grid, 1.2 s simulated, single runs); graphs against eager at many worlds is not measured.
Resolved rig: 25 mm ball, frictionless, block 72 x 72 x 36 mm on node planes, pressed at 2 mm/s; soft j2 card (E 3 MPa, yield 10 kPa, E* a / (Y R) about 115-160 at a / R 0.35-0.49). Readings, not laws:
| 3 mm voxels (55,000 particles) | 1.5 mm voxels (442,368; 4,000 sweeps, converged) | |
|---|---|---|
| mean pressure / yield at 1.5-2.5 mm, by the measured contact radius (grid nodes; top-layer particles) | 2.11-2.24 (particles unresolved) | 2.43-2.46; 2.36-2.44 |
| the same by the nominal radius sqrt(2 R depth) | 2.85-3.39 | 2.75-2.89 |
| from the slope (least-squares line of force on depth, 1.0-2.5 mm; p_m = slope / (2 pi R)) | 2.04 | 2.55 |
| where the force starts, against the surfaces meeting | 0.66 mm early (0.22 voxel) | 0.28 mm early (0.19 voxel) |
| elastic force against depth, 1-2.5 mm (Hertz: d^1.5) | about d^0.52 | about d^0.84 |
At 1.5 mm voxels the two measured radii agree within 2 % and exceed sqrt(2 R depth) by 8-10 % (pile-up). Brass x16,000 reads 2.2-2.4 by the measured radius at 1.5 mm (1,000 sweeps), within 2-5 % of the soft card. The elastic force at 2 mm reads 0.57 of the 3 mm row's: it is not converged with the voxel, and an earlier "0.97 of Hertz" at 3 mm was two curves crossing, not a match. A 0.75 mm row and the cited mean pressure at this a / R decide what is claimed.
Why
- Gauss-Seidel moves stress one cell per sweep and damps a smooth error slowly, and an implicit step of a stiff solid leaves little inertia to steady it: the sweeps needed go as (c dt / h)^2. What a step does not converge it drops.
- Newton's rheology solve adds a fixed 1e-6, in SI units, to every local Delassus block. A soft card's own block is about 6e-4, so it does not matter there; a metal under quasi-static mass scaling has blocks of about 1e-7 to 1e-9 (x1,000 to x64,000; read at x16,000: 1.3e-9 to 5.5e-9), where it makes every Gauss-Seidel step about 12-770x too short: mass-scaled brass stalled at 0.35-0.48 of its force at 1,000 sweeps and 0.73-0.83 at 4,000. Since vendored patch 0015 the route's entry runs at 1e-12 (a soft card's punch force moves by 7e-5 on the small rig above); unscaled brass still reads 0.007, so this alone does not make metals work.
- Not established (a hypothesis): the slope and the force disagree because the grid's contact surface is not the material's. The force starts about 0.2 voxel before the surfaces meet at 3 and at 1.5 mm voxels, and halving the voxel moves the slope reading from 2.04 to 2.55, toward the measured-radius reading. (An earlier reading at 3 mm, "particles stand 0.9 mm off the ball", came from the coarse top-layer sampling; at 1.5 mm the particle radius exceeds the nominal one.)
Workaround
- Soft solids (E / density under about 7,000 m2/s2 at 3 mm voxels: E under about 8 MPa at 1,000 kg/m3) converge with the route's defaults. For a force read, keep the block's faces on node planes (sizes that are whole multiples of the voxel) and expect the contact to start a third of a voxel early.
- Metals (a block that rests on the ground or a static box under a tool):
scene.set_quasi_static_mass_scale("block", tool_speed=0.002)multiplies its density by s with its weight kept true.scale="auto"takes the largest s whose inertial share v sqrt(E rho s) / yield stays within 1 % at that tool speed (brass at 2 mm/s: x2,913); a given s over 1 % warns and over 5 % is refused, and so is a block that does not rest on a support. Brass with "auto" pressed at 2 mm/s reads 0.991 of its converged force at 1 mm on the small rig (0.007 unscaled); on 1,024 worlds on one L4 (one run), 0.989 with "auto" against 0.007 unscaled, every world the same force and none flagged. Quasi-static only: the block is s times heavier for anything that moves it (a drop, a throw, a fast hit). A block that loses its support falls s times slowly (g / s: brass x29 pushed off a table's edge fell 32 mm in the 0.46 s after it began to fall, where g / s gives 36 mm and g 1.0 m), and health flags it QUASI_STATIC while it is pushed and all the way down: use the setting only for a block that stays on its support. The declaredtool_speedis your statement of how fast anything presses on the block. At build, "auto" stays within 1 %, a given s warns over 1 % and is refused over 5 %. At run time a world reads DEGRADED with QUASI_STATIC while the block as a whole moves faster than halftool_speed(its mass-weighted mean velocity: a correct press reads at most 0.14x), or a body touching it moves faster than 12xtool_speed. Not flagged, a tool up to 12x the declared speed reads the force within about 9 % (medians +1 to +3 %; the speed table below). 12x is a conservative choice: 30x measured within 10 % too, and 100x is the first speed clearly off (up to 38 % low where it first hits); a flag you can avoid by declaring the true speed costs little, and the 9 % scatter of the declared-speed press itself on 1.5 mm voxels leaves no room to set the bound tighter. The inertial-share formula gives 7 and 23 % at 3x and 10x, against those medians: the build bounds are conservative too. A block pushed along is flagged. Carried at its declared speed, the push read 4.4x the unscaled block's force at x2,913 ("auto" for 2 mm/s) and +5.0 % at x29 ("auto" for 20 mm/s), and the block slid on 0.1-0.6 mm after the pusher stopped (unscaled: under 0.01 mm). Those are bounds, not exact errors: unscaled brass is itself no clean reference (its stress solve does not converge, so it acts soft). Without the setting, move the tool and read the dent's shape, not the force. Metal sheets and cans dent on another route (add_cloth(..., material="aluminium_6061_t6"),docs/guide/deformables.md).
Speed table: the force of a tool faster than declared against the declared-speed press at the same depth (25 mm ball rig, brass x16,000, one L4; each period of the faster tool against the median of the declared press's 5 periods within 0.02 mm of its depth; development notes, not shipped). Part of each spread is noise: one period of the declared-speed press scatters up to 9 % from its neighbours on 1.5 mm voxels (2 % on 3 mm). A CPU repeat of the 10x row read +6.1 % at 2 mm.
| tool (flagged?) | voxel | 0.2-0.5 mm deep (first contact) | 0.5-1 mm | 1-2 mm |
|---|---|---|---|---|
| 3x (no) | 3 mm | +0.8 to +1.5 % | -0.6 to +2.1 % | -0.4 to +4.4 % |
| 3x (no) | 1.5 mm | -1.6 to +1.4 % | -3.8 to +6.4 % | -1.8 to +7.8 % |
| 10x (no) | 3 mm | +1.8 to +2.9 % | -0.8 to +4.6 % | -0.2 to +7.3 % |
| 10x (no) | 1.5 mm | -8.7 to -2.7 % | +0.5 to +6.9 % | +0.1 to +9.2 % |
| 30x (yes) | 3 mm | +1.8 % (0.4 mm) | -6.2 to +5.6 % | -3.8 to +7.0 % |
| 30x (yes) | 1.5 mm | -9.6 % (0.4 mm) | -4.2 to 0.0 % | +0.1 to +3.8 % |
| 100x (yes) | 3 mm | +4.9 to +7.2 % | -11.5 to +11.7 % | -2.5 to +6.3 % |
| 100x (yes) | 1.5 mm | -38 % (0.2 mm), -20 % (0.4 mm) | -7.5 to +0.2 % | -6.9 to +4.7 % |
Planned fix
After 0.1.1 (dents slice 2b): the quasi-static mass scaling above is done (on the resolved rig, brass x16,000 follows the soft solid of the same E / yield within 2.4 % at 0.5-2.5 mm; development notes, not shipped). Next (2026-11-11): a 0.75 mm row and a Richardson extrapolation of the mean pressure and the elastic exponent over 3, 1.5 and 0.75 mm, against the mean pressure the literature gives at this a / R (not 2.6-3.2 by default). If they agree, the default route for small yield strains follows with that law; if not, the gap stays as stated here.
A bit that lands on an exposed bar never cuts it¶
What is wrong. A bit that meets a bar before its hole has a stage (a bar whose top is at the concrete's face) is held there and reported jammed with its thrust, but cuts nothing into the bar, however hard it is pushed. A bar under any cover is cut: the bit opens its hole in the concrete, meets the bar inside it, cuts into the bar at the steel estimate when pressed past the chisel threshold, and drills on once the hole's bottom has passed the bar (the rebar section of the drill-holes design note, not shipped).
The number. A #4 bar whose top is the face, a 12.7 mm bit at 1.8 J x 85 /s fed 0.5 mm onto it: held, thrust
over 100 N, removed 0 and bar_cut 0 (test_a_jam_on_an_exposed_bar_is_reported).
Why. The cut into a bar moves a stage's bottom. A hole is opened by its first cut, and the bar stops that cut, so there is no stage whose bottom could move.
Workaround. Give the bar a little cover (0.1 mm is enough to open the hole first).
The fix and when. Open the hole's first stage, at zero depth, when the point lands on a bar, so the jam's cut has a bottom to move. Small; not in plan (no task drills an exposed bar).
Drilled holes are seen by listed pins only¶
What is wrong. The drill plug-in records each hole it cuts (Drill.holes()), and the parts listed as the
drill's pins (bolts, dowels, anchors) pass through those holes. Every other body still meets the undrilled
shapes. A bolt that is not listed rests on the face over a hole as if the hole were not there. So does a pencil
dropped into a drilled hole, or a second drill bit's housing. A pin listed for the drill also meets only the drilled
parts through the plug-in: the whole pin (shank and head) must have no solver collision with them, or the head is
seated twice (by the solver and by the plug-in).
The number. Not a magnitude: a body that is not listed sees no hole at all. The listed pins pass the holes they
fit, with their heads seated F / k (0.75 mm at 150 N) into the face. They are stopped at any push, resting where the
end meets the narrowing to within 1 µm of the geometry plus F / k: by a hole narrower than the shank or a pilot, a
stepped hole's shoulder, a blind hole's point cone, an undrilled face, or two parts' holes that no single axis fits
(offset by more than both clearances; a chamfered end guides an offset pin in only within them). A head narrower
than a counterbore rests on its floor. A pin pushed hard can still tip over: its seated head resists tilt only
as a disk on four rim springs, k r_h^2 / 2 per axis (4.2 N m/rad for an M8 head at 2e5 N/m), so a push F applied a
lever L above the head tips it once F L exceeds that plus whatever holds the pin's axis. In the laws' scene (a 20 N
m/rad hold, 25 mm up) an aligned square bolt passes cleanly at 2000 N; a chamfered one guided in 0.7 or 0.95 mm off
is clean at 1000 N and lost at 2000 N; one pre-tilted 1 deg passes at 1000 N but ends 13 deg tilted. A chamfered
bolt wedged on a second part's misaligned mouth holds upright only to about 150 N (2.7 deg at 150 N, 16 deg at 300
N; it tips over at 500 N): the walls of the first part's hole resist its tilt by two springs a plate thickness
apart (k s^2 / 2, 3.6 N m/rad for 6 mm at 2e5 N/m) plus the pin's hold, while the chamfer pushes the tip sideways
with about the whole push. Hold the axis firmly (a gripper) to push harder. A chamfered end resting on a mouth it
does not fit can gain energy when nothing damps it: its landed spring holds the deeper of the landed and today's
rest and turns between a 45 deg and an axial push, which is not one potential, so a bounce with sideways motion
pumps (0.13 to 0.40 J from a 0.01 J nudge at 150 N, undamped). A chamfered pin therefore needs damping of at least
2e-4 s (the default), where the same nudges settle; 1e-4 s still gains. The laws are pin_through (square end) and
pin_chamfer (chamfered end), both at 150 N, in tests/plugins/test_drilling.py.
Why. Contact geometry is fixed when a scene is built: MuJoCo and Newton cannot cut a hole in a box shape during a run. The drill owns the contact between its pins and the parts it drilled, as it owns the bit's contact.
Workaround. List the body as one of the drill's pins: Drill(pins=(Pin("bolt", tip=..., radius=..., head=...),)),
with the pin's collision with the drilled parts turned off (ShapeConfig(has_shape_collision=False), or a
collision filter). Its shank is then a segment with a radius. A body that is not a straight shank, such as a cable
or a bit of debris, has no workaround yet. A listed wedge anchor (Pin(anchor=...)) reads its clamp load T / (K d)
but does not apply it: the pin springs hold the clamped parts. It has no pull-out capacity either: the clip holds
by the pin spring (pulled at 5 kN it slides about 25 mm and stays engaged), and the concrete's strength is unused.
The fix and when. Holes as solver geometry: a per-world SDF of a part with its holes, which other bodies would meet. This is an engine change on the precision contact route, not in plan.
A weld bead's start, its tack starts and a crater mid-joint are not right yet¶
What. GridThermal (the weld heat plug-in: a heat grid with melting, a moving arc and deposited weld metal) lays
a bead whose steady part and, with the pool flow on (as in the welding tasks), end crater at a joint's end are sound,
but three places are wrong. Where an arc starts on cold steel, the first wire piles up on steel that has not melted (a
cold lap, the root not fused for a millimetre or two). Where a pass runs over the start of an earlier tack weld, the
bead laps the plate by two cells where one is allowed, the root stays unfused for 1.5 mm, and the leg on the upright
member is 0.4 to 0.9 mm short. Where a pass stops mid-joint (half-fillet), the crater's bead is one cell short of size
(6.0 mm where 6.35 mm is asked).
Number. Gym-Anything's four welding tasks, run with its own program on its own grid and judged by a port of its
evaluator (alloy.tasks.weld_ga_tasks, one L4 each). The tasks run the cap model with the pool flow
(weld_ga.ARC_PRESSURE, Gym-Anything's arc force; GridThermal's own default leaves the flow off), and score fillet-2f
0.806, set-up-and-weld 0.806, half-fillet 0.761 and tack-and-weld 0.808 of 1 (without the flow: 0.774, 0.774, 0.753
and 0.775; half-fillet's difference is within one section's credit); none succeeds, with the flow or without.
Gym-Anything's own weld model scores 0.894 on fillet-2f by its own evaluator (it leaves a 5.5 mm cold lap at its own
start), so 0.894 is the mark, not 1. On fillet-2f the steady bead is 6.64 mm (6.35 mm is asked; Gym-Anything's is 6.71
mm), and throat, convexity, the five fusion sections and the crater pass. The failures: the root is not fused on 1.25
to 2.75 mm and 9.25 to 10.75 mm (it must be fused from 5 mm on); the lap is 0.75 mm at the strike and 0.5 mm over the
tack starts (0.5 and 0.25 mm are allowed); the size is under 6.35 mm on 18 % of the weld, at the two tacks (least 5.5
mm). The steady bead's penetration into the plate is 0.93 mm (mean over 30 to 110 mm) where Gym-Anything's is 1.5 mm.
Why. The pool's metal is shared along the liquid run at one pressure and dented by the arc
(alloy/plugins/thermal/grid_flow.py, on in the welding tasks, off by default: arc_pressure), but each slice's
surface is one circular cap with no weight. Gym-Anything's liquid lies on the plate under gravity, its first droplets
stack as a dome until the steel under them melts, and a bulge can roll onto cold steel; without these the wire must
land where the arc was 0.5 s before, which leaves the first 0.5 s of wire at the strike point. The tack starts follow
from the tacks themselves: they fuse less of the upright member than Gym-Anything's.
Workaround. Judge a bead more than 15 mm from a start or a tack's start: there size, throat, convexity, fusion and
the crater follow the heat input. The pool flow is verified at 0.25 mm cells at the joint (a 30 mm fillet at 0.5 mm
cells also ran without a starved section; it warns on cells coarser than 0.6 mm); on a coarser grid leave
arc_pressure at its default (off).
Planned fix. None in this weld model: measured, not solvable with it (heat-v3-design, Next slices). Two
slices aimed at the starts, each run with the wire landing under the arc on fillet-2f: the pool's shape with the
liquid's weight (opt-in bead_model="surface") scores 0.789, and Gym-Anything's cold starts (the droplets
stacked as a dome on cold steel, measured, not shipped) 0.794 with the cap model and 0.798 with the surface,
against 0.784 for the cap model alone and the shipped 0.806 (its landing delay of 0.5 s is our estimate; 0.828 needs
a delay tuned to the score). With the dome the tack starts hold Gym-Anything's metal (13-17 mm2 a slice against its
13; 26-29 with the delay) and, in the cap model, the root under the first tack's start fuses, but the arc start's
first 5.5 mm, the size and the overlap at the starts still fail, so no task succeeds.
Known gap: trapped air under a label is scored at 20 mm², not the task's 3 mm² inside a barcode¶
What is wrong
- The
bondsplug-in's trapped-air pockets (Bonds.Config.trapped_air,alloy/plugins/bonds/air.py) resolve a pocket to the label's mesh cells. The task's label criteria ask for no trapped air larger than 20 mm² over the label and no larger than 3 mm² inside its barcode. - Label stock (60 µm BOPP) behaves at 2 mm cells, where one cell is 4 mm². So the 20 mm² criterion is scored (about 5 cells), and the 3 mm² barcode criterion is not: a 3 mm² pocket is smaller than one cell.
- Each label task's result says
barcode trapped-air: not scored (needs < 1.5 mm cells; 60 µm stock freezes below that)(air.BARCODE_NOT_SCORED), and the task counts as partial on that criterion. No binary proxy stands in for it.
Number
B2 resolution check (a write-up of 2026-11-08, not shipped), 60 µm BOPP (E 2 GPa ESTIMATE), film route as shipped (dt 1 ms, 10 VBD iterations), CPU, built near z = 0: - a 20 mm cantilever sags 0.96-1.07x plate theory at 2 mm cells; 1.5 mm cells sag about 20 % stiff and ring; 1 mm cells are iteration-dependent and settle 3x too stiff (0.08 mm for 0.25); 0.5 mm cells do not move; - a pad press at 2x the bond pressure bonds the whole label at 2 and 1.5 mm cells and nothing at 1 mm; - scoring 3 mm² needs cells of about 0.7 mm or finer.
Why
The film route's bending stiffness converges ever more slowly as cells shrink: stiffness relative to inertia grows as D/ℓ⁴, so at fixed iterations a fine sheet of stiff stock is effectively frozen. Built far from the origin, float32 positions freeze it sooner (the ulp at 0.5 m swallows each step's move), so label scenes are built near z = 0.
Workaround
- Score the 20 mm² criterion at 2 mm cells (the pocket rig's laws T-1 and T-2 run there) and report the barcode criterion as not scored.
- A thinner or softer stock, or a barcode region meshed finer, does not help today: the stock itself freezes.
Planned fix
A film-solver item (the film route): bending that converges at sub-millimetre cells for stiff stock (a multigrid or Chebyshev-accelerated bending solve, or a hinge model whose stiffness does not grow as D/ℓ⁴ per iteration), checked by the B2 resolution probe (a 60 µm BOPP cantilever within 5 % of plate theory at 0.7 mm cells, and a pad press that bonds there). Then the pocket model scores the 3 mm² criterion unchanged. Not scheduled.
Sand and pastes¶
Some pairs of materials do not build in one scene¶
What is wrong
One scene can hold robots, rigid bodies, cloth, liquids, sand, pastes, soft bodies and cables, but not every pair of
them. alloy.build refuses the pairs below with a BuildError (UnsupportedPairError) that names the two objects,
their routes and the nearest setup that does build. A pair is refused whether or not the two objects ever touch.
| Pair | What would happen | Nearest setup that builds (as the error names it) |
|---|---|---|
| Sand or paste with fabric cloth | the two solvers cannot exchange contacts yet | make the grains or paste rigid (rigid=True); or a paper or foil sheet, which runs beside sand or paste, slowly (8.3 s per 10 ms control step on the CPU) |
| Sand or paste with a soft body | the same | rigid=True on one of them; there is no other way |
| Sand or paste with a clamped cable (an elastic rod) | the same | make the grains or paste rigid; or keep the cable on the chain route (an unclamped rod of at most 40 segments with an elastic material, or clamp="start", route="chain") |
| A soft body with a paper, film or foil sheet | the same | rigid=True on the soft body; or a woven material such as cotton_woven for the sheet, which does not keep a fold as paper does |
| Fabric cloth with a paper, film or foil sheet | the two kinds of sheet do not touch, so the cloth would fall through | a woven material for both sheets; or the two sheets in separate scenes |
A liquid with a second liquid on the paste solver (liquid_mpm) |
the second liquid would be a solid wall to the first, so they would never mix | both liquids on the default liquid route |
| A clamped cable beside a paper, film or foil sheet, in some scenes | the two solvers cannot exchange contacts yet | the cable on the chain route; or a woven material for the sheet |
Two more refusals are about where a liquid starts, not about the pair: a liquid that starts inside a paste or powder
(start it beside the material or pour it on top: liquid beside paste), and a liquid that starts
inside a free cloth or soft container (make the container static, or pour the liquid in with add_pour).
"Sand or paste" here is every material on the MPM solver: grains, pastes, and liquids routed there. "Fabric cloth"
is a sheet on the cloth solver (sim.routes(): cloth_vbd); paper, plastic film and metal foil sheets are on the
film route (cloth_film).
Number
There is no size to measure: the build stops before the first step. Three of the refusals were checked on the CPU
on 2026-11-18 (a 0.1.8 pre-release build), each a BuildError whose text starts UnsupportedPairError:
- a cotton sheet and a block of
sand_silica_dry; - a cotton sheet and a
paper_80gsmsheet; - a block of
sand_silica_dryand a cable withclamp="start".
Why
Each kind of material steps in its own solver, and two solvers share a scene by exchanging contact forces. The cloth and soft-body solver cannot yet take contacts from the sand and paste solver, or from the film route, over a whole surface: before the refusal was added, such a scene built and then stopped at its first step with a solver error and no fix. Fabric cloth and a film sheet built and ran, but did not touch, and the cloth fell through the paper.
Workaround
Do what the error names (the table's last column); e.fix carries it. Where only one object matters as a
deformable, make the other rigid with rigid=True. Pairs that do share a scene: a robot or rigid bodies with any one
of these materials; fabric cloth with a liquid; fabric cloth with a soft body; a liquid with sand or paste (the
paste is a wall to the liquid); a cable on the chain route with sand or paste.
Planned fix
Not scheduled. Each pair needs the two solvers to exchange contacts over a surface, which is engine work per pair. Until then the refusal stays, so a scene that builds does not stop at its first step for this reason.
MPM floors between grid planes: slow flows on the ground (sparse) or leaks through thin floors (dense)¶
What is wrong. Newton's MPM grids handle a wall well only when it lies on, or well inside, a plane of grid nodes. Alloy runs the sparse grid by default. Its node planes sit at half voxels, (k + 1/2) x voxel, so the ground (z = 0) lies exactly midway between two of them. Material resting directly on the ground then shears too little in its bottom one or two particle layers: pastes, viscous liquids and other flows along the ground run slow. Newton's dense grid has its planes on whole voxels, so the ground case is right. But a floor thinner than a voxel that rests on the ground (a 4 mm container floor) then has no node plane inside it, and particles leak through. The sparse grid holds such floors. Fills in containers are the common case, so sparse is the default (2026-11-07). Sparse entries warn once when their material starts within a voxel of a ground plane.
The number. CPU, 5 mm voxel.
| Case | Sparse (default) | Dense (ALLOY_MPM_GRID=dense) |
|---|---|---|
| Newtonian film on the ground, 20 mm, 10 deg, 20 Pa·s: speed / analytic | 0.821 | 0.970 |
| same, 200 Pa·s | 0.874 | 0.995 |
| honey_box_150ml in liquid_box_56 (4 mm floor) after 0.3 s: lowest particle | 5.24 mm (rests on the floor) | -0.24 mm (leaks) |
A container that moved at many GPU worlds lost sand into or through its floor at every floor thickness measured (4, 6 and 10 mm): a separate fault, not this one, fixed for 64 worlds and below (mpm-moving-container-many-worlds.md).
On the sparse grid the film ratio is the same at a 2.5 mm voxel (0.811-0.817) and at half the time step (0.821). A floor raised 1 mm (0.2 voxel) off the midplane gives 1.016. Rows and probes: the development scripts and result rows of a development ticket (not shipped).
Why. Newton applies a collider at grid nodes: a node inside it takes the wall's velocity. A wall halfway between
two planes couples the lowest particles to the wall too strongly; a floor with no node inside it has nothing to hold
material out. Sparse: grid_offset = 0.5 in SolverImplicitMPM. Dense: planes at floor(bbox_min / voxel).
Workaround. For a flow along the ground that has no floor thinner than a voxel (a film or pour speed, a paste
spreading on the ground plane), ask for the dense grid: ALLOY_MPM_GRID=dense, an entry's grid_type="dense", or
with alloy.integration.mpm_grid.grid_override("dense"): around the build (the film law tests do this). Dense needs
a run without CUDA graph capture: under graphs the entry keeps Newton's persistent sparse grid. Build containers with
floors at least one voxel thick (a container that moved at many GPU worlds was a separate fault:
mpm-moving-container-many-worlds.md). The run's solvers record the grid in use as solver.alloy_grid. A dense grid that
would need more than 4 cells per particle is built sparse when its start box is that large, with one warning. If it
grows that large mid-run (particles thrown far apart), a one-world entry switches to sparse with one warning, and an
entry of separate worlds raises MPMGridOverflowError: on CUDA Newton's next step failed to rebind its collision
fields after such a switch (64 worlds, 2026-11-07), and on the CPU separate worlds have no sparse grid.
The fix and when. Newton should place walls between node planes correctly, or at least let the sparse grid take a
half-voxel translation (warp.fem's Nanogrid already takes translation). It is reported upstream as a Newton bug;
the fix comes with a Newton pin bump, after launch. The GPU cost of dense against sparse at 64-1,024 worlds is a row
of the Nov 8 reconciliation pass.
Pastes and viscous liquids run slow along the ground (MPM, default grid)¶
What is wrong. Liquids and pastes on the MPM paste route (anything thicker than 1 Pa·s, or with a yield stress: honey, ketchup, mayonnaise, the food pastes) flow slower than their card viscosity says along the ground, or along any floor that lies midway between two of the grid's node planes. The bottom one or two particle layers move at about half their real speed; above them the paste shears at its card viscosity. The cause is the MPM grid's floor offset, mpm-sparse-floor-offset; this page gives the paste-flow numbers.
The number. A Newtonian film on an incline between frictionless side walls, 20 mm thick, 10 deg, on the ground; depth-averaged speed against the analytic mean at its own thickness:
| Film | Sparse grid (default) | Dense grid |
|---|---|---|
| 20 Pa·s | 0.82 (0.821 at a 5 mm voxel, 0.817 at 2.5 mm) | 0.970 |
| 200 Pa·s | 0.874 | 0.995 |
| 20 Pa·s, 30 deg | 0.927 | |
| Bingham, 50 Pa yield, 50 Pa·s, 30 mm, 30 deg (law L4) | 0.995 | 1.055 |
The whole film carries a near-constant speed deficit from its base: 2.2-2.7 mm/s at 20 Pa·s, at 10 or 30 deg and at 5 or 2.5 mm voxels, so slow films lose the largest share. On the dense grid the Bingham film of law L4 runs 5.5 % fast (its 0.995 on the sparse grid included the base's slowdown). Spreading, slumping and stopping on a slope are set by the yield stress and are not affected.
Why. The default sparse grid puts its node planes half a voxel off the origin, so the ground lies exactly between two and the boundary condition holds the bottom layers back over half a cell. The dense grid puts the planes on the ground; it is right for flows along the ground, but a floor thinner than a voxel resting on the ground (a 4 mm container floor) leaks there, so fills in containers keep the sparse grid.
Workaround. For a flow along the ground with no floor thinner than a voxel (a film, a pour speed, a paste spreading
on the ground plane), ask for the dense grid: ALLOY_MPM_GRID=dense, or
with alloy.integration.mpm_grid.grid_override("dense"): around the build, in a run without CUDA graphs (the
"debug" profile). The film laws (L4, L5) do this. Otherwise expect films on the ground to run slow by about 2-3 mm/s
at 20 Pa·s: 18 % for a 20 mm film at 10 deg, 7 % at 30 deg. Liquids under 1 Pa·s route to SPH and are not affected.
The fix and when. Sparse stays the default (2026-11-07). A sparse grid that places walls between node planes correctly, or takes a half-voxel offset, is a Newton fix, after launch (mpm-sparse-floor-offset). It also feeds paste-shear-thinning.
Granular MPM: slopes rest at the card's friction angle; a collapsed heap's flank reads lower, a free end slumps¶
Status: the slope part is closed (2026-11-09). Sand rests at its card's friction angle within 1-2 deg; the
first reading, that it "stands well below the friction angle", came from a law whose layer had a free end. What is
left: the flank a collapse leaves is not the repose angle (26-27 deg for this sand), a squat collapse's runout still
grows with resolution at 16 cells, and one angle serves for both starting and stopping. Pair friction to an MPM
object (set_friction) was ignored and is fixed (2026-11-08).
What
- Slopes (closed). A layer of soil_sand_dry (34.5 deg) held between end walls rests at 33 deg and flows at 36. A free end of the same layer relaxes to a wedge whose surface is at 33-34 deg to the horizontal.
- A free end slumps, as it should. A layer on a plate tilted below the friction angle cannot keep a free end: the end relaxes to a wedge at the friction angle, so it slumps back about H / (2 tan(phi - beta)) from the toe (H the depth, beta the plate's slope). For a 2 cm layer of this sand that is 4.5 cm at 22 deg, 6.7 cm at 26 and 12.7 cm at
- On a short plate the whole layer moves. The first law for this page read that as flow below the friction angle.
- A collapsed heap's flank is not the repose angle. A squat block whose sides collapse runs out past the wedge it would rest in, so its flank ends under the friction angle: 26-27 deg for this 34.5 deg sand, the same at 4, 8 and 16 cells in plane strain. To read a repose angle, use a walled layer or a free end's wedge (above).
- Runout of a squat collapse (open). That block's runout is 0.68, 0.83 and 0.93 of its height at 4, 8 and 16 cells: still rising. In 3D the 4-cell block also reads a lower flank (22 deg) than the 8-cell one (27 deg).
- One angle (open). Real sand starts to avalanche a few degrees above the angle it stops at (glass beads: 5-8 deg, GDR MiDi 2004). Alloy's sand starts and stops at the card's angle.
- Friction to MPM (fixed).
scene.set_friction(a, b, mu)used to write rigid contact pairs only, so a pair set between an MPM object and a table or tool was ignored, without a warning. Since 2026-11-08 the build writes every sourced pair (fromset_frictionor a library pair card) into the MPM collider (alloy.integration.mpm_pairs). One limit remains: one MPM solver gives a shape one friction for all its materials, so a shape that two MPM materials pair with differently is refused at build, naming both.
Number
All rows: soil_sand_dry (34.5 deg), 5 mm cells, plane strain between frictionless side walls, a plate with friction
1.2, CPU, 2026-11-09 (laws in tests/integration/test_mpm_cone.py).
Layer 2 cm deep between frictionless end walls (a tilting box). Top of the middle third, travel and speed:
| slope | box 16 cm, after 1.0 s | box 64 cm, after 0.3 s |
|---|---|---|
| 26 deg | 0.02 mm, at rest | |
| 30 deg | 0.05 mm, at rest | 0.08 mm, at rest |
| 33 deg | 0.37 mm, 0.08 mm/s | 0.52 mm, 0.35 mm/s, slowing |
| 36 deg | 1.9 mm, 1.8 mm/s, speeding up | 6.9 mm, 22 mm/s |
| 38 / 39 deg | 8.7 mm, 8.8 mm/s (39) | 12.8 mm, 85 mm/s (38, at 0.2 s) |
- The short box holds longer above the angle because its toe wall carries a layer only 4 cells deep.
- A layer 4 cm deep (8 cells) in the 16 cm box is at rest at 30 and 33 deg too (0.12 and 0.18 mm at 0.9 s).
The same layer, 16 cm long, with both ends free, after 1.5 s:
| slope | top of the middle third | wedge surface, to the horizontal | top dropped back from the toe (estimate) |
|---|---|---|---|
| 22 deg | 1.0 mm, at rest | 32.8 deg | 5.7 cm (4.5) |
| 26 deg | 8.1 mm, at rest | 33.2 deg | 9.2 cm (6.7); 8.2 cm at 0.7 s |
| 30 deg | 60 mm, 1 mm/s, stopping | 33.8 deg | the whole layer (12.7) |
Squat block in plane strain, height over half-length 0.5, on a table with friction 0.8, both ends free, at rest (the flank is a linear fit to the surface between 15 % and 85 % of the top; a wedge at 34.5 deg would run out 0.73 H):
| block height | cells up the flank | flank | runout / height | top left flat at |
|---|---|---|---|---|
| 2 cm | 4 | 26.6 deg | 0.68 | 0.99 H |
| 4 cm | 8 | 27.2 deg | 0.83 | 0.99 H |
| 8 cm | 16 | 26.3 deg | 0.93 | 1.00 H |
- By height band the 8 cm block's flank is 20 deg in its lowest third and 25-26 deg above.
The same in 3D, height over half-width 0.44, settled from 0.2 s (2026-11-08):
| block | cells up the flank | flank | edge runout |
|---|---|---|---|
8 x 8 x 2 cm, table mu 0.4 (set_friction(..., 0.8), before the fix) |
4 | 21.5 deg | 1.83 cm |
8 x 8 x 2 cm, table friction=0.8 |
4 | 22.3 deg | 1.36 cm |
16 x 16 x 4 cm, table friction=0.8 |
8 | 27.2 deg | 3.34 cm |
- A squat block's flank also depends on how far the block spreads. With table friction 0.1 instead of 0.8, it runs out 8.9 cm and the flank reads 8 deg.
- A tall column's runout matches the dry-collapse law (Lube et al. 2004) within 1-4 %.
Why
- The yield rule is Newton's Drucker-Prager cone, sqrt(J2) <= mu p, and Alloy passes the card's tan(phi) as mu. In a flow that keeps its volume the stress lines up with the strain rate, so the shear on the slip plane reaches mu times the normal stress and a slope rests at tan(beta) = mu: the card's angle.
- A wedge that has just stopped reads 1-2 deg under the angle because a moving toe overshoots.
- The first diagnosis (2026-11-08) was wrong. Its layer had free ends, and the stresses read behind the retreating toe (along the slope 0.6-0.9 of the one normal to it) were taken for a fault of the cone. With end walls the same layer rests at 30 deg, where that law saw 52 mm of travel.
- The collapsed heap: a collapse is not a slow relaxation. The falling side arrives with speed and runs out past the static wedge, so the flank it leaves is under the repose angle; the free end on a tilted plate, which moves less, ends 1-2 deg under it. The flank's angle does not change with resolution; the runout does, and is not converged.
- The friction gap (fixed): pair friction lived only in the rigid contact table. Nothing passed it to the MPM collider until the build learned to (2026-11-08).
Workaround
- Contain a slope that must stand: a wall or a lip at its lower end, or leave room for the end to slump (the estimate above).
- A heap whose shape after a collapse matters: 16 or more cells up the block, and expect the runout to be a few percent short still. Do not read a repose angle from it.
ALLOY_MPM_CONE=mcis not a workaround. It was offered here on 2026-11-08 for slopes; it sets Mohr-Coulomb's compression-cone match, mu = 6 sin(phi) / (sqrt(3) (3 - sin(phi))), which is the cone of a 38.9 deg sand for a 34.5 deg card. The walled layer then still rests at 36-40 deg, and a collapsing column stops 31 % short of the dry-collapse runout (CARD-9, Lube et al. 2004; 2 % by default). It stays as an opt-in for comparing with codes that use that match (sim.routes()names it).- Friction against MPM material:
set_friction(sand, table, 0.8)andadd_box(..., friction=0.8)on the shape now step the sand alike. With two MPM materials on one shape, give both the same pair friction.
Planned fix
- Slopes: none needed. The laws are the tilting box (rests at 33 deg, flows at 36) and the free-end wedge (31.5-35.5 deg, slump-back within 1.5x the estimate).
- Squat collapses: the runout's convergence past 16 cells is not measured (32 cells is 200,000 particles on the CPU). No change to the solver is planned for it.
- Start and stop angles: not planned.
- Pair friction to MPM: done (2026-11-08).
MPM: at many GPU worlds, sand and paste sank into bodies they touched (fixed for 64 worlds and below)¶
Status: fixed for 64 worlds and below (0.1.0). Alloy now picks a particle's grid cell in integers
(alloy.integration.nanogrid_lookup, which replaces one Warp function at run time: alloy/_vendor/VENDORED.md).
Above 64 worlds, MPM with a body is not validated: Newton's sparse grid runs out of capacity (status 8) or memory
before the fix's law can run there, and such a build warns (alloy.integration.mpm_moving).
What
- Before the fix, at many worlds on a GPU, MPM grains (sand, soil, paste) sank into bodies they touched, and
sim.check()stayed ok. Affected: a container that a drive moves, a kinematic tool or press, a robot's link, and a free box resting on the material. A sand slab on the ground alone held (an audit): static shapes did not show it. - How much grew with the world's place in the batch: world 0 of 64 read like a lone world, and the last worlds were the worst. Sand in a lifted open box sank into or through its floor at every floor thickness measured (4, 6 and 10 mm, against a 5 mm voxel).
- With the fix, at 64 worlds every world reads as one world does, in each scene re-run (Number).
- A build with MPM material and any body that is not welded to the world (free, kinematic or an articulation), on a GPU at more than 64 worlds, warns.
Number
One L4, 2026-11-11. Bodies in the material: the largest number of grains more than 1 mm inside the body at any control period, per world. Before: main; after: the integer lookup (the law runs, not shipped).
| scene (grains per world) | 1 world | 64 worlds before: world 0 / last 8 mean / worlds with any | 64 worlds after |
|---|---|---|---|
| kinematic blade ploughing a sand slab (16,128) | 4 | 4 / 66 / 64 | 4 in every world |
| blade: worlds with grains through it (behind its face) | 0 | 57 of 64 | 0 |
| kinematic plate pressing a dough block (6,912) | 0 | 1 / 32 / 64 | 0 in every world |
| a free 0.3 kg box resting on a sand slab (an audit) | 0 | 45 of 64 (at most 5) | 0 in every world |
| plate, every world's grid offset shifted 131,072 voxels | about 633 in every world, world 0 included | 0 in every world | |
| servo gantry's finger pushed into sand and swept (13,824) | 11 | 12 / 76 / 64 | 12 in every world (an audit) |
- 1 world is bit for bit with Warp's own lookup (it has no offsets, and that branch is unchanged).
- Newton's and Alloy's GPU MPM laws pass with the fix (17 tests).
- The lifted box, with the fix (an audit, 6 mm floor, 64 worlds): 0, 0 and 0 worlds at 0.099, 0.100 and 0.101 m/s (before: 42, 0 and 13), the 64 worlds within 0.007 mm of each other; a 128-world lift sank none.
- The lifted box before the fix: sand_silica_dry 4 x 4 x 2 cm in an open box 6 x 6 x 5 cm inside, at rest for 0.05 s, then lifted for 0.15 s at the speed shown, and read 0.05 s after the lift stops. Worlds out of 64 with a grain centre within 1.5 mm of the floor's mid-plane or below it:
| floor | 0.099 m/s | 0.0995 | 0.100 | 0.1005 | 0.101 |
|---|---|---|---|---|---|
| 4 mm | 0 | 43 | 0 | ||
| 6 mm | 42 | 0 | 0 | 32 | 13 |
| 10 mm | 52 | 56 | 24 | 0 | 0 |
- 1 world read 0 at all five speeds (6 mm floor) and at 0.099, 0.100 and 0.101 (4 mm). The deepest grain went up to 15.7 mm below the floor's bottom face (6 mm floor at 0.101).
- Above 64 worlds (a free box on a 2 x 2 x 1 cm slab, with the fix and without): at 256 worlds the grid rebuild failed with status 8 and the step ended in SparseMemoryError; at 1,024 worlds the runs stalled past 25 minutes, and once ended in CUDA error 700 (mpm-gpu-memory.md).
Why
- Alloy steps the worlds of an MPM entry in one shared sparse grid (Warp's
fem.Nanogridwith environments). Each world's cells sit at an integer offset along one axis: world w is about 22 w voxels out at this size. - Warp's cell lookup for such a grid added the world's offset to the particle's local grid coordinate in float32 and then took the floor. Near a cell face that floor can land in the neighbouring cell, and the error grows with the offset: 1e-4 voxel at 1,400 voxels, 0.016 voxel at 131,072. The material's contact with a body that moves, or rests on it, turned those misplaced grains into grains inside the body.
- The fix takes the floor of the local coordinate, then adds the integer offset, so every world's lookup is exact wherever it sits in the grid.
- It was not the floor's thickness, which is what mpm-sparse-floor-offset.md covers, and not a race: every run repeated to the digit.
Workaround
- 64 worlds or fewer per GPU: none needed.
- Above 64 worlds with a body: build 64 worlds or fewer per GPU, or check the lowest grain against the floor or tool
yourself (
sim.check()does not flag a sunk grain). - On another Warp than the pinned 1.18.0, or an edited lookup, the fix stays off with a logged warning and the old fault returns: there build 8 worlds or fewer, or step on the CPU.
Planned fix
- Done (0.1.0): the integer cell lookup.
- Above 64 worlds: the sparse grid's capacity and memory (mpm-gpu-memory.md), then the fix's law (per-world counts flat in the offset) at 256 and 1,024 worlds.
- A health check that flags MPM particles inside a collider.
- Upstream Warp: the same lookup in integers (upstream posting is on hold).
MPM on the GPU: CUDA graphs cost ~10x the memory of an eager step; too big for graphs runs eager, too big for both is refused¶
Status: guarded, not fixed. A scene whose MPM step does not fit as CUDA graphs runs without them (the MPM graph guard), and one that fits in neither mode is refused before its first step. With the check off, a full GPU on an MPM step is a clean error, not CUDA error 700. The graph mode's memory itself is not reduced yet (the follow-ups below). Warp's unchecked allocation is written up for upstream (an issue draft, not shipped) but not posted.
What
Implicit MPM's step builds warp.fem sparse systems every step. Their size follows the MPM particles, and depends on
how the step runs:
- As CUDA graphs (the default on CUDA): capture needs Newton's rebuildable sparse grid, and everything built on it
is sized by its reservation. The graph also keeps every temporary of the step alive at once. Beside a kinematic or
dynamic body, Newton's subgrid collider matrix adds 160 triplets per particle. Alloy reserves twice the cells the
material fills at the start (it fills one cell per 5-9 particles; alloy.integration.mpm_grid, the MPM graph
guard), and a grid that outgrows that is doubled and its period re-run (grid_growth).
- Eager (no graphs): Newton's per-step sparse grid, sized by the cells in use, temporaries freed as it goes.
When the GPU filled up inside the sparse build, Warp's native code (wp_bsr_matrix_from_triplets_device) did not
check its scratch allocation and went on. The next kernels failed with CUDA error 700, which leaves the context
unusable. Nov 8 reconciliation pass: soil_dig at 64 worlds on an L4, and the 1,024-world sand-fill rows.
Alloy now does two things:
- alloy.integration.mpm_memory.plan, in wire, before any solver is built:
- graphs that fit: nothing changes;
- graphs that do not fit, eager that does: the scene runs without graphs, with a note (graphs off: ...) in
sim.engine.parts.notes and the log;
- neither: MPMMemoryError (a CapacityError) with the predicted bytes against the device's free bytes, the worlds
that would fit, and the fix.
ALLOY_MPM_MEMORY_CHECK=off skips it, and graphs stay as asked.
- alloy.integration.sparse_guard and alloy.integration.native_guard: before each of Warp's native calls on an MPM
step, they reserve its scratch through Warp's allocator on CUDA, and raise SparseMemoryError or NativeMemoryError
instead. Covered: the sparse triplet build, NanoVDB grid builds and in-place rebuilds, radix sorts and run-length
encodes. This is the backstop when the prediction is low or the check is off.
- When a step graph runs out of memory all the same (the prediction was low, or the device filled up after the
build), the simulation steps down to smaller graphs, then to none, and the period it was for steps without graphs
at once (2026-11-10). Before that period it drops its captured graphs (they are captured again when
next launched), collects simulations dropped earlier, hands the pools' unused memory back and clears the error the
failed allocation leaves in Warp (Why, below). If the device then has no room for the eager scratch still to come
(1 kB per MPM particle), it raises MPMMemoryError with the bytes needed and free. Before this fix that period died
with "CUDA error 101: invalid device ordinal" in a prefix sum: sand at 64 worlds late in a speed sweep on one L4.
Number
L4, 23 GB, Warp 1.18 (memory probes and Nov 8 triage runs, not shipped):
| mode | per MPM particle, beyond the model | MiB per world (dough_ball under a press, 17,256 particles) |
|---|---|---|
| graphs, one cell per particle reserved (before a2), beside a body | 22-28 kB (Nov 8: 24.9-31 kB); predicted 32 kB | 398 |
| graphs, reserved from the cells in use (a2) | ~9 kB | 150 (8 worlds; 347 ms per period, was 770) |
| graphs, no body | 2.7-4.2 kB (Nov 8 rows); predicted 6 kB | - |
| graphs, no body: a pile of 200 g of sand on a table, 64 worlds, 492,032 particles (one T4, 2026-11-10) | 10.6 kB (5.2 GB beyond a 2.2 GB model); predicted 6 kB | 81 |
| eager, any scene | 1.6-2.6 kB; predicted 3 kB | 38-42 |
- What fits an L4 as graphs: soil_dig 32 worlds (15.4 GB), soil_whisk 16 worlds (11.7 GB).
- What fits eagerly, measured: dough 256 worlds (10.4 GB peak), sand fill 256 worlds (11.8 GB), soil_dig 64 worlds (2.8 GB).
- Speed at 8 worlds (dough, ms per 10 ms period): graphs 771, eager 353. At 256 worlds eager: 9.7 s per period (dough), 6.5 s (sand).
Why
- The step's memory is Newton's implicit-MPM warp.fem systems. Under capture they are sized by the reserved grid, not by the cells in use. The needs are not known until the step runs, so Alloy predicts them from measured rates.
- Warp's native triplet build (
wp_bsr_matrix_from_triplets_device, Warp 1.18) takes its scratch throughScopedTemporarywithout a null check. An out-of-memory there is printed, not raised, and the kernels that follow read null buffers. - Warp's NanoVDB grid builder (
rebuild_count_points, volume_builder.cu) and its run-length encode do not check their allocations either; its radix sort returns without raising. Beforenative_guard, on an L4 with ~2.5 GB free (a ballast array holding the rest), soil_dig at 64 worlds with the check off failed in the grid rebuild: "out of memory" printed, thenRuntimeError: Failed to create volume, then error 700 on every later free. - Warp's BVH and mesh builds (bvh.cu, mesh.cu) are unchecked too: a create writes through null pointers, and so does an LBVH rebuild. An MPM step's moving colliders refit their meshes. Since 07df81039 the guard reserves a create's scratch and the tree it keeps first (LBVH scratch 52 B and tree 84 B per item; a mesh's bounds 24 B and winding data 288 B per triangle; cuBQL's terms doubled; 4 MiB for CUB). A rebuild or refit is bounded by the size its create recorded. The guard installs with the first MPM entry, so a scene without MPM (cloth only) still builds them unchecked.
Limits of the prediction (review of the first version):
- The graph rate beside a body applies whenever the scene has any body. It was measured with a moving body inside
the material. Newton's collider matrix does not grow only near a body: it is sized by the reserved collider nodes
(160 triplets per reserved cell, no distance test). On one L4, dough at 16 worlds as graphs, a
press inside the dough, a press 1 m away and no press all peaked at 129.1 MiB per world. A far robot is therefore
not charged early. The split between the rates with and without a body may be stale in that scene; it is kept,
because a lower prediction would move scenes onto graphs without a law.
- The rate without a body is low for a pile that spreads: the sand pile above took 10.6 kB per particle as graphs,
against 6 kB predicted. On one L4 (2026-11-10, the speed table's command) it runs at 1, 16 and 64 worlds (64: as
graphs, 557 world-steps/s); at 256 worlds (1.97 M particles) the plan predicts 11.8 GB as graphs, they need over
20 GB, and the step-down cannot carry it: after a graph out-of-memory the MPM step goes on with the grid sized for
capture, so its eager periods need far more than an eager run from the start (about 6 GB here). It stops with a
clean SparseMemoryError (the process keeps its GPU). Workaround: at most 64 worlds of it on an L4, or
profile="debug", which runs without graphs. Planned for a later release: the no-body rate raised to
12 kB, with the estimate's rows re-checked, so such a scene starts without graphs.
- Above 64 worlds, MPM with a body is not validated, and the build warns: Newton's sparse
grid runs out of capacity (status 8) or memory. On one L4, a free 0.3 kg box on a 2 x 2 x 1 cm sand slab at 256
worlds failed its grid rebuild with status 8 and stopped with a clean SparseMemoryError; at 1,024 worlds the runs
stalled past 25 minutes, and once an out-of-memory in Warp's sparse transpose (wp_bsr_transpose_device, which the
guard does not cover) ended in CUDA error 700. That range is also where the integer cell lookup's law has not run
(mpm-moving-container-many-worlds.md).
- The free memory is read after Warp's mempool hands back what it holds unused. It does not include the graph
memory pool, so a process still holding another simulation's captured periods reads low.
- The check first runs a full garbage collection and trims Warp's graph pool, then reads the free memory. A
simulation dropped earlier in the process (an earlier test, a notebook cell, a sweep's last world count) is a
reference cycle: its device arrays and graphs stay allocated until Python's cycle collector runs, which it rarely
does in a long process (rc3: one process running the coupling and integration GPU tests read 11.8 GB free before
256 dough worlds, which were refused; a one-world liquid scene left 3.8 GB held after sim.close() on a T4).
Until 2026-11-10 the collection ran only when the mode asked for did not fit, so a sweep's leftovers let graphs
start in what was left. A simulation that is still referenced is not freed: drop it (del sim, and anything that
holds it), or build in a fresh process.
- After any CUDA allocation failure in a process, the next Warp native built on CUB (a prefix sum, a radix sort, an
array sum, a run-length encode) fails once in its sizing call with "CUDA error 101: invalid device ordinal",
whatever memory is free again; kernels and allocations in between do not clear it (Warp 1.18, driver 580, one T4:
8 orders of calls). A prefix sum then raises; a sort returns with its keys unsorted, a sum and an encode with
their output unwritten. Alloy takes that failure with one tiny prefix sum
(alloy.integration.native_guard.absorb_stale_error) where it handles an allocation failure and goes on: the
graph step-down, and before the next guarded native after a refused one. Code of yours that catches a CUDA
out-of-memory error and goes on in the same process should call it too. Warp's native code prints the failure it
takes ("Warp CUDA error 101: invalid device ordinal (in function scan_device ...)") on stderr once, after the
step-down's out-of-memory warning: that line is the absorbed error, and stepping goes on.
The guard wraps Warp's native function only on the audited Warp (1.18) with the audited argument types. On another Warp it logs a warning and stays off, and the prediction is the only protection.
Workaround
- For graph speed on fewer worlds: fewer worlds, or fewer particles (a coarser spacing).
- A scene refused in both modes: fewer worlds (the error says how many fit) or a bigger GPU.
alloy.estimate(scene, worlds)gives the graph-mode MPM memory before a build (6ea274528); for many worlds the eager rate (3 kB per particle) applies instead.
Fix
- Upstream Warp: check every native scratch allocation and raise (sparse build, grid builder, run-length encode, BVH, mesh), and raise when a sort cannot get its buffer. Clear the CUDA runtime's error after a failed allocation, and check the sizing calls of the sort, the sum and the encode (not written up for upstream yet).
- Alloy: done for scenes with an MPM entry (BVH and mesh guards). Install the guard in the wiring as well if a cloth-only scene path ever builds them per step.
- Alloy, memory (MPM graph guard follow-ups):
- done (a2): the graph grid is reserved from the cells in use, grown on overflow. The check still predicts graphs at one cell per particle, on purpose: 64 dough or sand worlds then fit as graphs but ran 3.0-3.1 s per period against 1.8-2.0 s eager, so scenes past that size stay eager;
- a per-scene prediction of the collider matrix (from the bodies' footprints in the grid), instead of one rate for any scene with a body.
MPM at many worlds: the rheology solve sets the speed (256 dough worlds ~7.6 s per 10 ms period on an L4)¶
Status: open. The solve tolerance is 3e-4 by default since 2026-11-08 (22 % faster for dough), after a law re-pass. A faster solver is planned after launch (2026-11-08).
What
An implicit-MPM step (pastes, dough, sand and soil) solves the material's stress with Newton's projected Gauss-Seidel until the residual is under a tolerance or 250 iterations. That solve is over half of an eager dough period at 256 worlds (57 % at the default tolerance, 64 % at 1e-4). More worlds cost proportionally more: the GPU is already full of work at 256.
Number
L4, 256 worlds, eager periods (the memory check's choice at this size), 10 ms periods (the rheology-default rows, not shipped, 2026-11-08):
| scene | tolerance 1e-4 (before) | tolerance 3e-4 (default) | memory per world |
|---|---|---|---|
| dough ball pressed by a plate | 9.78 s | 7.60 s (-22 %) | 37 MiB |
| sand fill | 6.73 s | 6.69 s (-1 %) | 45 MiB |
Where a period goes (same L4, 256 dough worlds eager; Newton's own phase timers, which synchronize, so a period reads about 1 s slower than untimed):
| phase | tolerance 3e-4 | tolerance 1e-4 |
|---|---|---|
| whole period | 8.64 s | 10.44 s |
| strain (rheology) solve | 4.91 s (57 %) | 6.71 s (64 %) |
| allocate grid | 1.13 s | within 2 % |
| elasticity | 1.05 s | within 2 % |
| rasterize collider | 0.60 s | within 2 % |
| scratchpad, strain matrix, the rest | 0.31, 0.14, each other under 0.12 s | within 2 % |
The solve's loop (16 solves, counted on the host) averages 203 sweeps at 1e-4, with 9 of 16 at the cap. At 3e-4 it averages 130, with 2 of 16 at the cap. So the 22 % from the looser tolerance is all the solve's.
One world on the CPU: a pressed dough ball takes 205 iterations per solve on average and often hits the 250 cap (0.2 s, 160 solves); at 3e-4 it takes 153. The sand fill converges in fewer iterations, so the tolerance barely changes its time.
Why
A Gauss-Seidel sweep moves information about one cell. A body many cells across therefore needs on the order of the square of its width in sweeps before its bulk mode settles. Newton's other solvers do not help: - the struct-of-arrays Gauss-Seidel is bitwise the same and no faster; - Jacobi always hits the cap; - conjugate residual followed by Gauss-Seidel takes as many iterations and is 2.1x slower; - Newton refuses conjugate gradient with contacts.
Workaround
- The default tolerance is 3e-4, a 3x looser residual than Newton's 1e-4.
ALLOY_MPM_TOLERANCEchanges it when a scene is built (alloy.integration.mpm_solve):ALLOY_MPM_TOLERANCE=1e-4for the tighter solve. A scene's own MPM solver arguments win over both. - Effect: a pressed dough ball's particles move by mean 0.08 mm, max 0.65 mm against 1e-4, 2.3x the solver's own floor (1e-4 against 1e-5: mean 0.035, max 0.14 mm).
- Validation: every MPM law and the dough, paste and soil tasks pass at it within their own bands.
- Accepted range: 1e-5 to 3e-4. Looser values are refused, because every solve would stop unconverged.
- Fewer worlds per GPU also help, since time scales with worlds once the GPU is busy. The CPU runs one world per core
(
processes=). - Not offered: Newton's older trilinear collider basis (
collider_basis="Q1"). It ran 256 dough worlds in 6.14 s (-37 %) and sand in 4.90 s (-27 %), but it failed its contact laws (Newton moved to the quadratic S2 basis for contact quality): - a paste layer below its stop thickness slid 28 mm (law: under 1 mm);
- a strip footing at 0.8 of Prandtl's bearing load sank 60 mm (law: under 1 mm);
- the soil cone factor fell to 4.3-5.3 (law: 5-35, measured 7.5-11.9 past one radius);
- the paste slump read 0.321 against Pashias' 0.235 (law: within 0.07);
- the dig scoop lifted 2.7 g instead of 8.0 g and poured none into the bucket.
A robot or a free body beside MPM (robot + sand)
A Panda plunging its fingers into a 4 cm tray of dry sand and dragging them (35,000 grains), L4, CUDA graphs, per 10 ms control period while the fingers are in the sand, one build (main, 2026-11-09):
alloy.build(mpm_coupling=...) |
1 world | 64 worlds |
|---|---|---|
| "standard": 2 passes per exchange, 1.25 ms exchanges | 0.365 s | 13.24 s |
| "auto" (the default; robot-only scenes): 1 pass, 1.25 ms | 0.188 s (1.9x) | 7.02 s (1.9x) |
| "fast": 1 pass, 2.5 ms (opt-in) | 0.107 s (3.4x) | 3.83 s (3.5x) |
The fast row comes from the commit that added it (cd4c7e4c1; the same engine code for fast). Before the proxy-body fix below, rc2-1109 took 1.336 s (1 world) and 18.84 s (64 worlds) for the same scene.
- Fixed (default since 2026-11-09): the MPM solver never wrote its proxy bodies to its output, so the coupler read
a moving robot's travel as a coupling error and halved the exchange step for the rest of the run
(
alloy.integration.mpm_bodies;ALLOY_MPM_BODY_CARRY=offrestores the old output). - auto (the default;
alloy.integration.mpm_clock,mpm_robots): one coupling pass per exchange instead of two, at the standard exchange step, when every coupled pair ends in MPM, the scene has a servo-driven robot, and every body that starts within 2 cm of the material is that robot's link or welded; otherwise standard. Against standard on the rows above: finger end height within 0.03 mm; the sand surface within 0.19 mm on average (95 % of 5 mm columns within 0.8 mm; two standard runs differ by 0.03 mm), no grain spilled either way; no re-run or escalation. It is decided at build: a free body that reaches the sand later also runs one pass. A 2 cm steel block dropped 4 cm onto sand rests within 0.5 mm of standard and moves under 1 cm/s from 0.3 s (tests/integration/test_mpm_clock.py). - fast: also 2.5 ms exchanges. A robot held by its servos shows no change (finger end height within 0.2 mm), but a free body does: the dropped block rests 3.3 mm deeper, and a heavy cup resting on sand bobs by about 15 µm (up to 7 mm/s) for about 0.3 s. Use it for robots and tools in sand or paste, not for free objects that must rest on it.
sim.routes()names the setting and why on the MPM object ("mpm_coupling");ALLOY_MPM_COUPLINGoverrides it for a whole run.- Where the time goes, 64 worlds in contact (standard): MPM 90 % (MuJoCo 10 %); in MPM, the strain solve 72 %, elasticity 7 %, collider rasterization 6 %, grid allocation 5 %.
Planned fix
- Tolerance 3e-4 as the default: done (2026-11-08), in its own commit after the law re-pass above.
- A faster solver, measured (an Anderson-acceleration probe). Anderson-accelerated Gauss-Seidel takes 1.6-2.4x fewer sweeps per solve on the CPU (1 and 2 worlds; the dough within mean 0.06 mm of GS). On the L4 at 256 worlds the loop drops from 130 to 84 sweeps, but the untimed periods are equal (7.56 against 7.59 s). Not merged.
- Converged worlds are skipped: done (5fd256eaf). Newton's Gauss-Seidel sweep skips the worlds that the per-world stop has frozen, so results are bitwise the same. L4, 256 dough worlds:
- presses at spread heights, so the worlds stop at different sweeps: 7.87 against 10.10 s per period (strain solve 4.16 against 6.39 s);
- identical worlds: no change.
- After the solve: grid allocation, elasticity and the collider rasterization take about 2.8 s of a timed 8.6 s period together.
- Not planned, by decision: an iteration cap of 100, tolerance 1e-3, or half-precision solves. Each leaves the solve unconverged or below its own resolution.
MPM: on the dense grid, a world that outgrows the grid's box couples the worlds by one rounding step¶
Status: open, narrow. Upstream fix proposed (Newton: integer cell origin, cell size exactly the voxel).
What
Implicit MPM's dense grid is one box shared by every world (Newton Grid3D with one environment per world). A
particle's cell and weights come from (x - lo) / cell_size, with cell_size = (hi - lo) / res. When the box
changes, both round differently, so every world's arithmetic moves by about one float32 ulp.
Alloy keeps a multi-world dense grid's box fixed: the first step's box plus 8 voxels each side
(alloy.integration.mpm_worlds). While every particle stays inside it, each world's trajectory is bitwise
independent of the others (tests/integration/test_mpm_world_independence.py). When a particle in any world leaves
the box, it grows for every world. A warning is logged once, and at that step the worlds couple by about one ulp.
The per-world sparse grids (the default on CUDA) index voxels from the origin and do not have this coupling.
CPU worlds split over worker processes (alloy.build(scene, device="cpu", processes=N)) hold the whole scene's
start box in every worker (mpm_worlds.start_box / hold_box, 9a1bd07da), so a world steps the same in
any split. When a particle leaves the held box, only its own worker's box grows. From then on that worker's
worlds differ by about one ulp from a run with another split, or with one process.
Number
- Newton's own dense grid, which follows every world's particles each step: melting world 1 next door moved world 0 by 1.5e-8 m with a fixed iteration count and 3.1e-8 m with each world's solve stopping on its own. That is melt_chocolate's scene, CPU, 2 worlds, 6 periods.
- With the held box, 0 (bitwise), while no particle leaves it.
- Three paste worlds in 1, 2 and 3 worker processes: bitwise the same
(
tests/parallel/test_cpu_worlds.py::test_a_paste_world_steps_the_same_in_any_process). Before the shared start box, the split moved a world by 2.2e-5 m at 2 worlds per process (mayonnaise paste, 0.05 s), and by 3.6 mm at one world per process, which built Newton's sparse single-world grid.
Why
A box that holds still for some worlds while others outgrow it has to depend on them. A box that never moves costs memory with no bound: Newton marks active cells in an array over the whole box every step.
Workaround
- Use the sparse grid (the default; on CUDA it is per world).
- On the CPU, where Newton builds no per-world sparse grid, start the material near where it will stay, or set
grid_paddingso the first box has room for the motion.
Related
Newton sets two material switches from every world's particles when the solver is built: the compliant path
(min_young_modulus < inf) and hardening (max_hardening > 0). A world of rigid-plastic particles next to an elastic
one moved by 1.9e-5 m in a plain-Newton test. Alloy's material cards always give a finite E, so the compliant path is
on in every Alloy MPM scene. Worlds that differ in whether they harden would still couple.
Planned fix
In Newton: a dense grid that locates cells by floor(x / voxel) minus an integer origin, with its cell size exactly
the voxel. Alloy's write-up for upstream (an issue text and a repro script, with the per-world stop) is not shipped.
Shear-thinning pastes thin a little too little (MPM paste route)¶
What is wrong. A material with Herschel-Bulkley fluid.consistency K and fluid.flow_index n (yogurt, batters,
purees, peanut butter, tomato concentrate) thins with shear rate a little less strongly than its card says. Slow flow
under low stress runs close to the card's speed; flow at higher stress runs up to ~15 % slow. The yield stress and a
constant (Bingham) viscosity are right.
The number. Law L5: 20 mm films of K 10 Pa·s^n, n 0.4 on 3 and 4.5 deg slopes, 600 mm long, on the dense grid (the film laws' grid). Speed / analytic at the window thickness; the slope exponent should be 1/n = 2.5:
| Voxel | 3 deg | 4.5 deg | Fitted 1/n |
|---|---|---|---|
| 5 mm | 0.993 | 0.864 | 2.16 |
| 2.5 mm | 0.989 | 0.878 | 2.21 |
| Before the fix (per-particle strain rate, 5 mm) | 1.76 | 1.41 | 1.95 |
| 5 mm, CPU, re-measured on main 4522df750 (2026-11-08) | 1.001 | 0.867 | 2.15 |
| 5 mm, CPU, a linear least-squares fit instead of the mean (tried, not landed) | 1.24 | 1.09 | 2.18 |
The test is tests/solvers/mpm_rheology/test_herschel_bulkley.py::test_l5_power_law_index_from_two_slopes_on_gpu
(1/n within 15 %).
Why. eta = K gdot^(n-1) is taken per particle from the strain rate. Each particle's velocity gradient carries about 0.5-2 1/s of noise in every component. For n < 1 that noise collapsed eta where the true shear rate is small: in the plug-like upper half of a film, eta read 11-16 Pa·s instead of 34-158, and the film ran 1.5-2.5x too fast. The strain-rate tensor is now averaged over each particle's neighbours within two voxels before eta is taken from it, which cancels the noise. Near a base or a free surface the average is one-sided. A hat-weighted linear least-squares fit removes that bias (on a synthetic linear shear profile, at the base: the fit 1.04, the mean 3.32, true 1.00), but on L5 it sped both films up (1.24, 1.09) and left the exponent at 2.18: the one-sided bias is not what holds the exponent low, and the cause is not yet identified. The numbers are for 20 mm (four-voxel) films. In layers thinner than about four voxels (a 5-10 mm smear at a 5 mm voxel) the two-voxel average spans the whole thickness and is one-sided everywhere, so that bias applies throughout the layer.
Workaround. For spreading, slumping, holding a shape or stopping on a slope, the yield stress dominates and the results hold (laws L1-L3). For flow speed, expect the card's speed within about 15 %, slow at the higher stresses. Check against the card's flow curve at the shear rate you care about. A Bingham card (yield stress and a viscosity fitted at your shear rate, no K and n) is exact at that rate. On the default sparse grid, flows along the ground also run slow (mpm-viscous-film).
The fix and when. After the 1109 release: find what holds the exponent low first (the linear fit at boundaries is
ruled out, above). The candidate left is the strain rate from the grid nodes inside Newton's flow rule. Probes: a
development script for L5 on CPU (FIT=1 swaps the fit in) and a fit-check script (not shipped).
A material cannot both melt and shear-thin¶
What is wrong. The thermal plug-in writes a melting material's MPM viscosity (its melt law, from
alloy/plugins/thermal/phase_materials.py) before each solver step. The Herschel-Bulkley update rewrites the
viscosity of every particle with fluid.consistency inside the step. On a material with both, the melt law is lost
without a warning.
The number. No library material has both today (dark_chocolate and porridge_oat melt, none of them has K and n);
tests/solvers/mpm_rheology/test_herschel_bulkley.py::test_no_library_material_both_shear_thins_and_melts keeps it
that way. A custom card with both would run with the HB viscosity only.
Why. Both features write the same per-particle array, model.mpm.viscosity, and there is no rule yet for
combining a temperature factor with a shear-rate law.
Workaround. Give a melting material its melt law only (no consistency / flow_index), or a shear-thinning
paste no melt law.
The fix and when. When the first material needs both (melted chocolate is shear-thinning): scale K by the thermal factor inside the Herschel-Bulkley kernel, or refuse the combination at build. Not scheduled.
A tool thinner than a paste's grid cell drags it in pulses (whisk wires, skewers)¶
What is wrong. An MPM paste is stepped on a grid, voxel = min(d_feature / 4, 5 mm), and Newton's MPM colliders
are SDF or mesh shapes sampled at the grid nodes. A rod, wire or skewer thinner than a cell touches nodes only part
of the time, so it pushes the paste in pulses as it crosses them, and its mean drag depends on how long you average.
A rod two cells wide (10 mm at the default 5 mm voxel) drags the rigid-plastic force. A spoon, spatula or knife blade
is wider than that.
In the 1109 release (rc2-1109) a thin tool beside a paste fails the build instead: the voxel rule took a moving rod's diameter as a container size, so the voxel became d/4 and a rod under about 8 mm asked for more MPM particles than the budget (CapacityError). Main since 1a23be349 builds every rod at the paste's own voxel.
The number. CPU. Mayonnaise (Bingham, yield stress τ_y 96 Pa) 30 mm deep in a 120 x 60 mm tub; a vertical kinematic rod of diameter d, its tip 10 mm above the floor (immersed L = 20 mm), dragged sideways at 20 mm/s; force from the MPM collider impulses on the rod, averaged over the second half of the drag. A rigid-plastic medium resists F = N_p τ_y d L with N_p = 9.14 (smooth) to 11.94 (rough) (Randolph & Houlsby 1984, a laterally loaded pile).
| d | Main (1a23be349), 5 mm voxel | rc2-1109 (before the fix) |
|---|---|---|
| 10 mm | N_p 9.53 (0.5 s drag; 9.6 over 0.3 s) | voxel 2.5 mm, N_p 7.1 |
| 5 mm | N_p 15.3 (15.5 over 0.3 s): acts about a cell wide | BuildError: 830,208 MPM particles > budget 200,000 |
| 1.5 mm | N_p 19.8 over 0.5 s, 8.5 over 0.3 s: pulses, 50 ms means 0-0.14 N | BuildError: 31,097,760 particles |
The probe is a development drag script (env D in mm, T the drag time); rows on the fix are a
development results file (neither shipped).
Why. On a 5 mm grid a sub-cell rod is seen by the few nodes it covers at each moment. Gym-Anything handles thin stirrers with marker segments and a cylinder drag law, which Alloy does not have.
Workaround. For a mixing or stirring force that matters, model a whisk or skewer as rods or paddles at least two cells (10 mm) wide; a 10 mm rod drags within the rigid-plastic band. On rc2-1109, a tool under about 8 mm beside a paste does not build: use a tool whose middle extent is 20 mm or more (a 10 x 20 mm paddle).
The fix and when. A drag-marker coupling for thin rigid tools in MPM (a coupling feature, not a paste one), after the 1109 release. The voxel rule is fixed on main (1a23be349).
Health, determinism and coupling¶
GPU: rigid bodies and robots in contact do not repeat bit for bit¶
What is wrong
On a GPU, two runs of the same scene with the same seed give the same bits only while no body takes more than
one contact pair: free flight, a robot arm touching nothing, one sphere or one flat box on the ground. As soon as
bodies pile, tumble onto an edge, or a robot touches its table or an object, repeat runs differ, and worlds that
start identical differ from each other. This holds at every profile: "standard" and "precision" ask for
repeatable runs but get none on a GPU (the build logs "effective determinism NONE (requested RUN_TO_RUN) ...
Warp deterministic lowering is off"). On the CPU the same scenes repeat bit for bit.
The differences start at float32 roundoff and stay there in a resting scene; where contact is chaotic (a pile of spheres, a grasp) they grow until worlds land in different places.
sim.health() on a GPU lists the notice DET_DOWNGRADED in every world of a rigid, robot or cloth run, at every
profile, also in the scenes that do repeat. A notice leaves the world OK (until 2026-11-10 it made every such world
DEGRADED at "standard" and "precision", and "fast" did not list it).
A build under profile="precision" on a GPU warns once that its runs will not repeat, with the reason; the other
profiles say it through the notice and the build log only.
Number
One L4 (driver 580), 4 worlds, seed 3, dt=0.01, 2 s, largest difference in position (m) or quaternion between
two runs. Fresh builds in one process, two processes, and a run repeated after sim.reset() give the same picture;
main b9441c38 and the Newton 1.8 / MuJoCo Warp 3.17 tree agree (on that tree the two-process check ran for the
tilted box only, and the Panda row at "fast" stopped with a CUDA graph error: no number; 2026-11-10).
| Scene | standard | precision | fast |
|---|---|---|---|
| Sphere in free fall | same bits | same bits | same bits |
| One sphere dropped on the ground | same bits | same bits | same bits |
| One box resting flat on the ground | same bits | same bits | same bits |
| Robot arm, one joint ramp, touching nothing | same bits | same bits | same bits |
| One tilted box dropped on the ground | 4e-7 | 2e-8 to 5e-7 | 8e-7 |
| 10 cubes of 5 cm dropped into a pile | 5e-6 to 4e-5 | 5e-5 | 4e-6 to 9e-6 |
| A scanned mesh object on the ground | 1e-4 | 9e-5 | 1e-4 |
| Capsule and cylinder dropped on a table | 1e-3 to 2e-2 | 1e-3 to 2e-2 | 1e-3 to 2e-2 |
| Panda arm with its table, box and mug | 1e-2 | 1e-2 | 1e-2 |
| 10 spheres dropped into a pile | 0.4 to 1.9 | 0.4 to 1.9 | 0.4 to 1.9 |
- On that machine's CPU, the six scenes run there (free fall, sphere, flat box, tilted box, cube pile, sphere pile): the same bits in every profile, health OK. The other four were not run on the CPU.
- A task result moves with it: the pick-and-place example (
05_pick_place) at 64 worlds landed 62, then 61 of 64 with the same seed (0.969, then 0.953). "precision"does not buy repeat runs: the cube pile differs by 5e-5 there, and a warm 2 s run cost 2.2 s against 0.99 s at"standard".
Why
MuJoCo Warp builds its contact and constraint lists with atomic counters, so on a GPU the order of the rows depends on thread timing; the solver's sums then round differently from run to run. One contact pair has one order. Warp's ordered lowering, which would fix the order, is off for this route on CUDA.
Workaround
- Need the same bits (a regression test, a replay): run on the CPU (
alloy.build(scene, device="cpu"); many worlds withprocesses="auto"). - On a GPU, compare runs with a tolerance, and judge a task by its success rate over worlds and seeds, not by one run: expect a few worlds in a hundred to change sides between two runs of a contact-rich task.
Planned fix
- Repeat runs: Alloy's ordered MuJoCo Warp route (sorted contact rows, fixed-order sums) repeats bit for bit on a
GPU at 1,024 worlds (
tests/precision/test_mjw_route_gpu.py), but it is an engine-layer option, off by default and not reachable fromalloy.build; its cost and coverage on these ten scenes are not measured yet.
Rigid and robot overlap flags: what PEN_WARN and PEN_FAIL do not catch yet¶
What is wrong
Since the fix of audit finding ERR-1, sim.health() flags overlap between rigid bodies and robot parts. The limit
of a contact is 1 cm, or half the thinner part along the contact normal when that is less. PEN_WARN (DEGRADED)
while a contact is deeper than 1 mm or past its limit; PEN_FAIL (INVALID, the world frozen, profile="precision"
raising alloy.SimulationError from sim.step / sim.run) when a contact has stayed past its limit for 0.1 s of
simulated time, or past twice the limit (2 cm, or through the thinner part) at the fourth health check in a row; for
a body larger than 20 cm that hard depth is 10 % of the smaller moving body's smallest size (a static shape sets
none). Cloth on rigid bodies follows the 0.1 s rule only: a box dropped 3 cm onto a 2 mm sheet pushes cloth
particles 2.7 mm into it for a few steps without passing the sheet. A fast body's one-step dip into a thin part is
left to FAST_CONTACT and TUNNEL. Each world also reports peak_penetration_m, its deepest contact since the build
or the last reset. Before the fix no rigid or robot contact raised either flag. Seven limits remain:
- The flags follow the depth at the latest check. PEN_WARN clears when the bodies come apart, so a run that ends at
rest can read OK after a dip; peak_penetration_m and sim.check() ("deepest contact ... mm") keep it.
- A landing or a bounce that passes 1 cm for less than 0.1 s reads PEN_WARN, not PEN_FAIL, by rule: a soft contact
compresses that far in a hard impact, and further for a large body. Between 1 cm and the hard depth a world
therefore steps on for up to 0.1 s before it freezes (up to 2 cm deep for small bodies, 10 cm for a 1 m crate),
and past the hard depth for three checks (3.75 ms at the default 1.25 ms step).
- The 0.1 s clock is one per world, not one per contact: different contacts dipping past their limits one after
another keep it running, so a long stream of landings on thin parts can reach PEN_FAIL with no single contact
resting deep. No shipped scene does (bins and marbles read PEN_WARN while they land and OK at the end).
- On a thin part PEN_WARN also fires under 1 mm: past half the part's thickness (a 1.6 mm connector part at
0.88 mm).
- A frozen world shows its last good state, so max_penetration_m beside PEN_FAIL can read less than the depth
that failed. That depth is peak_penetration_m, and it is in the world's problem text.
- A robot file whose contacts are soft on purpose rests deeper than 1 cm and reads INVALID while it stands still,
unless the scene names it in scene.relax_contact_depth (Workaround). MuJoCo Menagerie's ANYmal C is one: its
feet (solimp 0.015) rest 17.2 mm into the floor, and plain MuJoCo C reads the same depth. So the physics
matches MuJoCo, and it is this health rule that freezes the world. To see it:
sim = alloy.load("<menagerie>/anybotics_anymal_c/scene.xml", worlds=2, device="cpu"), sim.step(100), then
sim.check()["ok"] is False, with PEN_FAIL and START_PEN.
- A legged robot that falls and stays down can read INVALID. Three biped files run with no policy (an H1, a simple
humanoid and a Cassie) fell in every world, and their links then lay 2.0 to 3.1 cm into the floor, past the 1 cm
limit: after 4 s, 976, 419 and 14 of 1,024 worlds were frozen (one L4). They lay as deep before the fix, when
nothing flagged it. Robots that stood in the same runs (a G1, a Go2, an ANYmal D) were not flagged. So a
rollout in which a biped falls can end with frozen worlds; no workaround is measured.
Number
CPU, 1 world, dt=0.01 (physics step 1.25 ms), MuJoCo C and MuJoCo Warp routes alike
(tests/precision/test_health_pen_mujoco_law.py; the same on one L4 for the box cases):
- A 0.3 m box on a 50 g, 5 cm cube. 5 kg: 0.35 mm, OK. 80 kg: 2.9 mm, PEN_WARN. 200 kg: rests 7.0 mm deep,
PEN_WARN; it passes 1 cm for a few milliseconds as it lands. 500 kg: passes 2 cm at t = 0.105 s, PEN_FAIL,
frozen. 2,500 kg on a 2.5 g cube: PEN_FAIL.
- Health's depth equals the depth worked out from the bodies' heights within 0.01 mm.
- A position-servoed arm link (kp 20,000) pressed onto a table passes 1 cm at t = 0.355 s and is frozen at
t = 0.455 s, 18.7 mm deep. Before the fix it went 104.5 mm into the table with health OK.
- 5 cm balls dropped 0.3, 0.6 and 0.9 m with restitution 0.6 dip 5.8, 8.2 and 10.1 mm at the bounce: PEN_WARN
while deep, OK at rest, never INVALID. A 10 cm, 5 kg cube dropped 0.4 m: the same.
- A 1 m cube at 10 kg/m3 dropped 5 cm / 0.5 m / 2 m / 5 m / 10 m dips 5.9 / 19 / 39 / 63 / 87 mm, each for under
50 ms past 1 cm, and rests 0.05 mm deep: PEN_WARN while deep, never INVALID (87 mm is under its 10 cm).
- Thin parts (tests/precision/test_health_pen_measured.py): a 5 mm plate pressed 2 / 3 / 6 mm into the ground
reads PEN_WARN / PEN_FAIL after 0.1 s / PEN_FAIL at the fourth check; a 2 mm sheet at 0.5 / 1.5 / 2.5 mm reads
no flag / PEN_FAIL after 0.1 s / PEN_FAIL at the fourth check.
Why
Contact on the MuJoCo route is soft: depth grows with load and with impact speed. The checks read MuJoCo's own contact distances each physics step and keep the latest reading and the deepest one, with one clock per world for how long a contact has been past its limit. Which flags were raised earlier in a run is not kept yet.
Workaround
- Read
sim.health()["worlds"][w]["peak_penetration_m"]after a run, orsim.check(), which also names the pair of objects. - A scene that overlaps by design at a thin part (a blade edge on a strap) marks those shapes at the engine layer:
sim.engine.health.relax_thin_part_rule(shape_ids)holds them to the 1 cm rule alone. - Two parts that press into each other by design (a sprung connector finger on its card) mark the pair instead:
relax_designed_overlap(sim.engine, [(("finger", "card"), "0.85 mm preload")])fromalloy.precision.health_penlifts the thin-part limit between those two only; against every other shape it still applies. - Contacts a robot file makes soft on purpose:
scene.relax_contact_depth("anymal")(a robot, one of its bodies"anymal/LF_SHANK", or an object) judges each of its contacts by the depth past the contact's own MJCFsolimpwidth, when that is wider than MuJoCo's 1 mm default; contacts at the default keep the rule. ANYmal C's feet (solimp="0.015 1 0.03": 30 mm) then stand OK withsim.check()["ok"]True on the CPU, andmax_penetration_mstill reads the true 17.2 mm (sim.check()lists that depth as a warning).depth=states the allowance in metres instead. PEN_WARN fires 1 mm past the allowance, PEN_FAIL 1 cm past it for 0.1 s, START_PEN alike. For a file you wouldalloy.load, take an editable copy:scene = alloy.Scene.load(path)(Menagerie's scene.xml names the robot"scene":scene.names()),scene.relax_contact_depth("scene"),alloy.build(scene)(tests/precision/test_health_pen_soft_relax.py).scene.to_json()keeps the relax;scene.save()'s cards do not (it warns). - Lower
dt, lighter loads or stiffer contact materials reduce the depth itself. - For the ANYmal C above (measured standing, CPU): in a copy of
anymal_c.xmldelete the feet'ssolimp="0.015 1 0.03"(MuJoCo's default contact stiffness then applies) and raise the base from z 0.62 to 0.64 (at 0.62 the legs start 10.5 mm into the floor). It then stands OK for 5 s, 1 mm deep at rest. Either change alone is not enough. This changes the foot compliance the file's authors chose, so a policy trained on the soft feet may behave differently; walking and the GPU are not measured. The tworelax_...calls above do not help here: both still hold a contact to the 1 cm limit.
Planned fix
A "seen since reset" flag list beside the current flags, so a PEN_WARN raised during a run is visible at its end (in work under audit finding ERR-11). Not scheduled: a shorter dwell for stiff contacts.
Known gap: worlds of a coupled scene share one exchange clock, so one world's events change every world's steps¶
What is wrong
- A coupled scene (MuJoCo + VBD cloth or soft parts under the Scheduler) picks one exchange interval dt_x and one set of per-entry substeps for all its worlds each control period.
- Every per-world stability estimate feeds that choice by its minimum. VBD's is 0.4 · r / |v| over its fastest particle. So when one world's state changes the choice, every world steps differently from then on.
- That includes a world re-run after a force jump. The re-run is refined to dt_x / 2^k, and its own later trajectory can move the clock. The other worlds are restored exactly to their first-run state, then step on that changed clock and leave the trajectory they would have had alone.
- Same seed, same device stays bit-for-bit (the whole scene is deterministic). Only "this world does what it would do by itself" does not hold.
- A re-run steps every world. The worlds that did not trip are computed again at the finer step and then put back, so they pay that period's compute twice. That holds for a force-jump re-run, a world's first escalation (below) and a contact-band re-run.
Escalations (2026-11-08)
- Before: a world's escalation (its energy or residual rule tripped, not a force jump) raised the clock's floor for good, and on the second trip switched the pairs to their strong mode, for every world. A randomized C3 box-on-pad benchmark (64 worlds, L4) tripped in 1-11 different worlds in each of periods 1-5. The floor went from 0.156 ms to 0.0195 ms with staggered coupling for all 64 worlds, and 0.5 s never finished.
- Now (
alloy.coupling.ladder): a world's first escalation re-runs that world's period at one grid level finer per re-run (up to 2), for that period only. The floor and the coupling mode stay, and the next period starts on the clock the scene's bounds pick. - The lasting ladder still acts in two cases: the same world trips again within the watchdog window (1 s), or a period ends still escalated. A resting instability needs that.
sim.health()["refined_periods"]counts the refined periods per world.- The kept worlds stay bitwise on a run without the trip
(
tests/coupling/test_period_ladder.py::test_kept_worlds_are_bitwise_a_run_without_the_trip): the clock is not moved.
Number
- A towel on a box (
tests/coupling/test_rollback_bitwise.py, CPU, 2 worlds, C3's per-body record gains): - the reference's VBD stable step at P+2 is 1.59e-4 s, 1.8 % above the 2-substep threshold (dt_x 1.5625e-4 s);
- after a refined re-run of world 1 its towel drapes about 9 % faster (max particle speed 0.69 vs 0.63 m/s), so its stable step is 1.46e-4 s;
- at P+3 the scene takes 4 VBD substeps instead of 2, and the kept world 0 leaves the reference in that period.
test_a_refined_world_changes_the_shared_clock_for_every_worldshows this. The restore itself is exact: on the reference's clock the kept world stays bitwise on it (test_a_refined_rerun_leaves_the_kept_world_on_the_reference).- The demonstration sits on that 1.8 % margin. Sub-ulp changes to VBD velocities move it (2026-11-08: velocity from the true displacement), and then the re-run world no longer crosses the threshold. The test is xfail(strict=False) until it has a scenario with margin. The clock is still the minimum over worlds.
Opt-in: clock_worlds
alloy.build(scene, clock_worlds=n)moves the up to n worlds that need the smallest exchange step into a second simulation of n worlds, where they step on their own clock; the worlds left in the main simulation share the larger step that the neediest of them asks for. A world's re-run ask enters the second simulation alone instead of re-running every world. Off by default;sim.report()["world_clock"]has the books (exchanges, the estimateexchanges_shared,residents,paused,limits).- It fixes the "one world's need sets every world's step" half of this gap for the worlds it moves: the worlds left in the main simulation step bit for bit as if the moved ones were parked by hand; a moved world matches its run without the option only to rounding (as a different world count does).
- Speed: on 64 worlds of a robot beside a towel with randomized pad masses (one L4) it ran 1.12-1.24x faster with clock_worlds=4 (41.5 s per period off; 33.6-37.0 s on, 3 runs). On the CPU with few worlds the second simulation's fixed cost can make it slower (4 worlds: 0.88x).
- Limits (each in
sim.report()["world_clock"]["limits"]): the sticky floor and the coupling mode are each simulation's, not each world's; a moved world takes the second simulation's substep rungs; moved worlds go through the host every period; neither simulation keeps its captured graphs across a reset;alloy.envs.VectorEnvandalloy.liveworld ops refuse such a simulation (writes straight to engine state still bypass the move back); a moved world that fails, and GPU runs, have no law yet. Not with liquid, MPM, the contact gate, the CPU's default MuJoCo route,processes=,rerun_worldsor user plug-ins. - Still open: bitwise independence across layouts. A world does not step bit for bit the same in a 4-world and a 1-world simulation, because VBD's solve reads a batch-wide total whose rounding depends on the other worlds (development notes, not shipped). Until that leak is closed, "this world does what it would do alone" holds to rounding, not to the bit.
- Laws: tests/coupling/test_world_clock_run.py, test_world_clock_review.py, test_world_clock_laws.py.
Why
- The Scheduler steps all worlds in one launch per exchange with one dt_x and one substep count per entry. Per-world substeps would need per-world loop bounds in every coupled kernel and graph.
Workaround
- To compare worlds as independent experiments, keep them in separate builds (or
processes=on the CPU, one world per process), or read results only from periods before any re-run (traj.meta["health"], rollback counts insim.engine.rollbacks, refined periods per world insim.health()["refined_periods"]). - Randomized worlds in one build are fine for statistics. Just do not treat one world's trajectory as what it would do alone.
Planned fix
- Per-world substep counts (a per-world loop bound in the coupled kernels and their graphs), or a clock chosen from the unaffected worlds plus a separate pass for the refined one.
- Estimate: 1-2 weeks across the coupling layer. Not scheduled.
A frozen world still sets a coupled scene's clock, so a start overlap can make each control step take minutes¶
What is wrong
- Health freezes an INVALID world by putting it back to its period-start state after every exchange. The solvers still step it from there on every exchange, and in a coupled scene (cloth or a soft body beside a free rigid body or a robot: MuJoCo and VBD under the Scheduler) the shared exchange clock still reads it.
- A world that froze at its start because a sheet or soft body began inside a rigid part (or the ground) is the bad
case. Every exchange pushes the same vertices out again, and the clock reads their speed: its contact-band bound
and VBD's stable step halve the exchange step. At the finer step the same depth is undone in less time, so the
speed reads higher again. Within three control steps the clock is at its finest step (
dt / 1024) and VBD's substeps climb toward their top rung (64), on a world whose result is thrown away. - The clock is shared, so every world of the scene steps at that rate (Number, 4 worlds).
- Without a free rigid body or robot there is no coupled clock: the frozen world then costs a bounded amount.
- A start overlap this shallow is not named: health's start-overlap check (START_PEN) judges rigid contacts, not cloth or soft-body vertices. The latch warning gives only indices ("particle 810 / shape 5").
Number
One L4 and the CPU (Warp route), main bd9e6b412 (2026-11-11). The reproduction: a 15 cm cotton_woven sheet (10 g,
resolution 30) centred at z 0.103 over add_open_box(inner=(0.10, 0.10, 0.10), wall=0.008), whose rim is at
0.108 (the cavity floor is one wall higher than pos), so the sheet starts 5 mm inside the four walls; a 27 mm
steel_carbon ball (80 g) at z 0.36; dt=0.01.
- With the ball: INVALID at the first check (PAIR_PEN_FAIL, 4 mm into a wall; ENERGY_JUMP; vertices leaving the
walls at 10.9 m/s). Per control step:
| step | L4 wall | CPU wall | exchanges | VBD substeps | what the clock read |
|---|---|---|---|---|---|
| 0 | 3.8 s | 89 s | 128 | 1 | the ball's interface bound, 1.0e-4 s |
| 1 | 20.5 s | 829 s | 256 | 4 | band bound 4.6e-5 s (vertices at 11 m/s) |
| 2 | 154.5 s | (stopped) | 1,024 | 8 | band bound 3.0e-6 s (about 170 m/s), finer than the finest step |
| 3 | over 2,500 s (cut) | 1,024 | 64 | bound 5.7e-7 s; 270,857 graph nodes an exchange, over the budget: eager |
sample-sweep measured the same on rc2 (3.7, 20.2, 153.6 s) and rc6 (step 3 over 600 s).
- Without the ball (cloth alone, no coupled clock): INVALID at step 1 as well (CLOTH_STRETCH, ENERGY_JUMP), at a
steady 0.77 s per step on the L4. The 0.15 s per step first reported as this scene's baseline was also a frozen world.
- The same scene with the sheet at z 0.115 (7 mm above the rim): no flags; 0.06 s per step without the ball, and a
steady 2.0 s per step with it (128 exchanges of 15 ms in CUDA graphs: the documented clock for a body of 80 g
beside cloth, docs/guide/deformables.md, Cost).
- 4 worlds on the L4, the ball in each: every sheet at 0.115, a steady 2.48 s per step (128 exchanges). World 0's
sheet at 0.103 and worlds 1-3 at 0.115: 4.3 s, then 24.0 s (256 exchanges, VBD 4), then step 2 at 1,024 exchanges
with VBD 16, whose exchange (68,688 graph nodes) is over the graph budget and runs eagerly: it had run over 19 min
when the spot VM was reclaimed. Worlds 1-3 stayed healthy and paid all of it.
- A soft body shows it too. A 15 x 15 x 5 cm silicone_40a pad placed flush on the ground (its vertices then start
one particle radius, 2.5 mm, inside it), with the same ball resting 2 mm above it, latched at step 0 (dt=0.005).
Its steps grew to 37 s, 140 s and 265 s on the CPU. On the L4 they took 56, 64 and 42 s, then 5.7 s each. The same
pad and ball placed clear step in 0.02-0.14 s on the L4.
Why
- The latch's source is the period start (
alloy/integration/simulation.py, Latch source), restored after every exchange; the frozen world is still a world of the Scheduler, so its estimators and contact band feed the clock (SchedulerMixin.choose_clock). Re-stepping a start overlap from the same state every exchange makes the exit-speed kick ofcloth-contact-exit-kick.mdgrow as the step shrinks. - Parked worlds (
alloy/coupling/parked.py) do exactly what a frozen world needs (no clock bound, no re-run asks, held). WithoutALLOY_PARK_LATCHEDonlyclock_worlds=parks worlds; the health latch does not.
Workaround
- Opt-in:
ALLOY_PARK_LATCHED=1in the environment, before the build (alloy/integration/park_latched.py). At the end of the period a world latched in, it is parked in the Scheduler as parked worlds are: it holds no clock bound, asks for no re-run and is held. The substeps it raised drop at once. A reset unparks it. Turn it on for a coupled scene (cloth or a soft body beside a robot or a free rigid body) run with many worlds or for long, when frozen worlds are not reset at once. Nothing changes until a world freezes. After that the other worlds step on their own clock, so their results differ from a run without it. Scenes built withclock_worlds=are left alone (their driver parks worlds itself). - With it, wall time per control step on the same L4:
| scene | without it | with it |
|---|---|---|
| 1 world, frozen at step 0 | 3.8, 20.5, 154.5 s, then over 2,500 s | 3.8 s, then under 3 s (0.5 s once captured) |
| 4 worlds, world 0 frozen | 4.3, 24.0 s, then over 19 min | 4.3, 3.4, 15.7 s, then 2.5 s |
| 1,024 worlds, world 0 frozen | 119 s, then over 37 min (cut) | 116 s, then 2.5, 11.3, 11.3, 6.7 s, then 2.1 s |
- All 4 worlds healthy take 2.5 s a step. All 1,024 take 2.0 s after the same graph warm-up (3.2, 10.9, 11.2, 6.8 s), with the option and without it: with no world frozen it costs nothing measurable.
- The 1,024 worlds: a 9 cm sheet (resolution 8, 5 g) over a 6 cm open box with an 8 mm wall, and a free 1 kg ball, in each world; world 0's sheet starts 5 mm inside the walls. Without it, step 1 runs 1,024 exchanges at 64 VBD substeps, eagerly (158,231 graph nodes an exchange).
- Read
sim.check()["ok"]orsim.health()after the first step. A world INVALID at step 0 or 1 is almost always a start overlap: move the object clear and build again. - Place cloth and soft bodies clear of what they rest on: a sheet above a box's rim (
add_open_box's rim isposz + wall + depth), a soft body one particle radius above the ground or a support (VBD solids rest one radius above what they touch; the radius is 1/5 of the tet mesh's shortest cell edge). - Without the option, a world that froze later still costs every world while the clock reads it:
sim.reset()brings it back to its start;alloy.build(..., clock_worlds=n)moves the neediest worlds onto a clock of their own.
Planned fix
- The option as the default, after a decision: it changes the other worlds' steps only after a world has frozen.
- START_PEN for cloth and soft-body vertices, naming the object and the part, so a start overlap is reported as one.
Known gap: with the opt-in contact gate, cloth resting on fixed geometry while the robot is away settles at a coarser step¶
What is wrong
- The contact gate is experimental and not advertised (2026-11-08). Its loss against today's clock in the scene where it releases the clock is fixed (Speed below).
- The contact gate (
ClockPolicy.contact_gate, off by default;alloy/coupling/contact_gate.py) releases the exchange clock while a robot is away from the cloth. Today's clock instead holds the lightest robot link's bound the whole run. - While released, VBD steps the cloth at the coarser exchange step, because VBD's own step follows the exchange step.
- Cloth that rests on fixed geometry meanwhile (a table that is part of the robot's file, the floor) settles slightly differently than under today's clock.
- When the robot then touches the cloth, the pair is armed and runs today's clock exactly. The small offset carried into contact grows there like any other perturbation.
- There is no drift caused by the contact itself: from one state, the gated run equals today's clock bitwise (CPU).
Number
- Scene: L4 GPU, 4 worlds, robot_cloth_liquid (a Panda arm reaches a 0.3 m towel lying on its table, beside a water box; built by a development script of mixed-material speed scenes, not shipped). Control period 10 ms, 30 timed periods; the arm touches the towel at period ~25.
- The gate runs 8 exchanges per period for the 24 periods before the arm arrives; today's clock runs 128.
- When the arm arrives the towel is 0.6 mm off at its centre. Three runs of today's clock agree there to 0.00 mm.
- Final towel offset against today's clock (main 16281ba5e, one gated run against 2 runs of today's clock): 1.7-2.1 mm at the centre and 8.1-8.8 mm RMS over the particles.
- Today's run-to-run floor, from 3 pairs of today's runs: 1.6-2.5 mm centre, 7.0-9.8 mm RMS.
- The water moves 0.04 mm at its centre and 2.4 mm RMS over its particles (floor 0).
- Before wp4's MuJoCo -> VBD -> SPH chain (3dddcdfaa) the same scene ended 4.5-9.4 mm off at the centre against a 2.0-4.9 mm floor.
- Scenes where the arm is near the cloth from the start keep today's clock and stay within the floor: robot_cloth (towel draped on the arm) and robot_cloth_drop (towel dropped onto a swinging arm).
Why
- VBD is implicit: how the towel settles on the table depends on its step. Released, the step is 0.16-0.6 ms (1.25 ms exchange, 2-8 substeps); under today's clock it is 78 us.
- The gate keeps today's clock only for coupled pairs in or near contact, as designed. A fixed body cannot hold the clock, so cloth touching it does not arm the pair.
Workaround
Leave the gate off (the default) when the cloth's settled shape before contact matters at the 1-2 mm level.
Speed (the chain's pass loop, fixed)
- Since wp4's MuJoCo -> VBD -> SPH chain (3dddcdfaa), each released 1.25 ms exchange ran the chain's coupling pass loop to k_max: 8 passes. The cause (speed-now S2, 2026-11-09): the released arm's lagged MuJoCo -> VBD pair still counted in its world's residuals. A lagged pair's velocity residual is the link's lag behind its source, a dt_x, the same in every pass: 0.012-0.035 m/s against tol 0.01 at 1.25 ms (0.005-0.007 at 78 us), with no force on any proxy. Short worlds re-ran the period, the captured passes rose to 8 and the exchange graph grew past the 65,536-node budget, so it ran eagerly.
- Fix: a released proxy adds no residual (
alloy.coupling.residuals.ResidualInputs.gated). The gate released it because it cannot touch within the period, and the safety net re-runs any period in which it did.tests/coupling/test_contact_gate_residual.py: with nothing touching, the state is bitwise the same in 2 passes instead of 8. - Speed after the fix (rc2-1109, 64 worlds, one L4, the towel falling beside water in robot_cloth_liquid, 6 timed
periods): 6.8 s per 10 ms period against today's clock's 17.5 s, so 2.6x faster. Before the fix the gate took
65 s. The result rows for
gatefix,baseandgateare in a speed run's output (not shipped).
Planned fix
- Probe (2026-11-08), report only: keeping VBD's fine step while the gate is released removes the towel's offset (0.00 mm when the arm arrives), but costs more: 41-62 s per period at 64 worlds against 9.3 s. The water still moves 2.4 mm RMS.
- The settling offset is within today's run-to-run floor at the end of the measured scene (Number). Default-on is speed-now S2's call, on its laws (the speed-now plan, not shipped).
Known gap: contact between a soft or cloth particle and a MuJoCo body takes its gains from the exchange clock¶
What is wrong
- A particle solver (VBD: soft solids, cloth, film) feeds its contact force back to a MuJoCo-owned body through the
lagged proxy. Newton's feedback is the contact records' force at VBD's last iterate
(
coupling_harvest_proxy_wrenches), which an unconverged solve does not give the particles. - Fixed where a world is closed (2026-11-08,
alloy.coupling.record_momentum, gaps-now #10a slice A): the feedback gets the particles' own momentum change over the step (less gravity and their external forces), shared over the contacts they touch by force; a lone body gets back exactly what they took. A world stays on Newton's feedback when something outside the records moves its particles: a pinned, inactive or proxy particle (cloth hung from a pin, cut fragments, liquid proxies in the cloth's view), or a dynamic body VBD itself integrates. - The records' damping is still one-sided (it acts only while the particle approaches the body) and sized from the clock (below), not from the pair's restitution.
- Every record touching the body carries the soft material's K (2e6 N/m by default), and the exchange clock bounds by one record. Under a wide body that adds up to far more than the lagged exchange holds.
- So Alloy does not take these gains from the material (
alloy.contact.particle_gains, 2026-11-08). The n records VBD lists against a card body of mass m share one spring and one damper, held to the exchange clock's own bounds for that body at the exchange interval dt (bound 0.5 = the clock's safety x omega_dt_max): - per record, ke = min(VBD's mix, 0.5² m / (dt² n)) and kd = 0.5 m / (dt n);
- so the body meets a contact of damping ratio 0.5 (restitution about 0.16 for that contact alone) whose stiffness grows as dt shrinks.
- The card's K only caps ke; the card's restitution sets nothing. Records on static shapes keep Newton's soft mix. Robot links are not covered: their records still read the importer's values (not measured).
- A particle view whose shape ids are not the Model's keeps VBD's mix, with a warning. Newton's pin (d15a836c) keeps them global under compaction, so this does not happen today.
Number
CPU, development probe scripts (not shipped). C3 box_on_pad: a 0.515 kg platen on a 40 x 40 x 10 mm pad of 900 particles, 7-9 mg each, analytic stretch 0.9029. At dt 1/6400 s it lists 1,457 records on 226 pad particles: 3.6e3 N/m and 1.13 N·s/m each. - At rest the result is right: placed at its contact distance, the platen reads stretch 0.9035-0.9040 at 0.74-0.8 s. Its first compression peaks at 0.888 near 22 ms (a sudden load; undamped it would reach 0.806). - A 1 mm drop rings down slowly: stretch 0.905-0.911 at 0.44-0.5 s (box ±3 µm), as with the first version's fixed 1e4 N/m and 1 N·s/m per record. - A 0.5 kg steel ball dropped 2 mm on an 11 x 11 cloth (3 cm vertex spacing, few records) rests 0.05 mm into its contact distance by 0.1 s; a 2 kg ball 0.10 mm by 0.15 s. With the fixed per-record gains the 0.5 kg ball hovered 0.65-0.97 mm off at 0.15-0.3 s and the 2 kg ball sank 0.2-0.9 mm. - Momentum, mid-air (CPU, 2026-11-08, development probe scripts, not shipped; law tests/coupling/test_record_momentum.py, which compares against a second world where the body falls free above the particles): - Newton's feedback: C3's platen at 0.1 m/s onto its free pad gains the pair +2.4 mN·s (4.5 % of its 51.5 mN·s, 1.3x what the pad took); in the first contact exchange the platen was fed 0.587 mN·s for the pad's 0.030. A 2 kg ball at 0.31 m/s into an 11 x 11 cloth: +27.5 mN·s (4.4 % of 626; the cloth took 3.1). - With the fix: +0.004 mN·s (platen) and 0.23 mN·s (ball, mostly the cloth's own fast fall below). - The law's scenes (Warp CPU route, worst excess against what the particles took): Newton's feedback 214 % (ball) and 543 % (platen); with the fix 7.8 % and 0.7 %. On that route the 0.5 ms exchange can make and break a contact inside one step (no record force at its end); the correction then goes by record count. - On main a coupled cloth in free fall fell 2 % faster than g (+0.20 m/s², 2026-11-08). It is not this feedback: VBD's float32 velocity update v = (x - x_prev) / dt quantizes each velocity change to ulp(z) / dt on fine steps (a triage write-up, not shipped). It biases a momentum check by about 10 mN per 50 g at that height and step; the law compares against a second world on the same route. - A 2 kg ball dropped 5 mm on that cloth lying on the ground lands at 0.34-0.36 m/s and rebounds at 0.20-0.25 m/s (e 0.58-0.69; with the fix about 0.23 m/s, e 0.68, resting 0.08 mm into contact). The cloth's own contact with the ground sets that bounce. - At the material's 2e6 N/m per record, the Warp route's first rebound injected energy (ENERGY_JUMP latch at 18 ms). With MuJoCo's native gains read as forces (before 2026-11-08) the pad did not load (stretch 0.998). - Landings are therefore softer than the material's restitution says. - Under its own weight a body sinks about 4 g dt² into the contact: 1 µm at dt 1/6400 s, 11 µm at 1/1920 s. A light body pushed by a large force F sinks 4 F dt² / m.
Why
- VBD is not converged at its 10 iterations. Its penetration-free truncation also limits how far a particle may move per iteration. So the relative velocity in the damping term at the last iterate is not the one the particle ended with.
- The reaction is evaluated, not accumulated: it is not the impulse integrated over the iterations.
- The clock's interface bound reads one record's stiffness and damping from the Model, not the records' sum.
Workaround
- For a resting load (a box on a pad, a cloth under a weight) none is needed.
- For a landing whose bounce matters, keep the lighter body rigid-on-rigid. The card's restitution is not used: the records against the body have damping ratio 0.5, and a cloth lying on a support bounces the body back at e 0.6-0.7 through its own ground contact.
- For sub-millimetre fits, use rigid precision pairs instead.
Planned fix
- Done: the momentum-consistent feedback (slice A above).
- Not planned as a default: record damping sized from the pair's restitution, and an exchange clock from the summed stiffness of a body's records (gaps-now #10a slice B, measured and dropped 2026-11-08). A body landing on a cloth lying on the ground rebounds at e 0.76 / 0.62 / 0.41 with the records' damping x0.2 / x1 / x3, against cotton's model restitution 0.0 (no measured reference); on a soft pad the bounce (e 0.89) is the pad's bulk, whatever the records do (known gap soft-solid-bounce). The summed-stiffness clock would take C3's ~265 touching records at the material's 2e6 N/m to dt_x ~16 us (today 156 us), about 10x the exchanges.
- Robot links get the momentum-consistent feedback above; their records still read the importer's gains.
Cameras¶
- Each new look of the full camera (
quality="full": other lights, colours or a look file) compiles again, about 100 s the first time on one L4. Keep one look for a whole run; a look used before starts in under a second. - Lighting set with
camera_scene(sim, lighting=...)carries into later defaultsim.render()calls on that simulation. Render the default pictures first, or build a second simulation for them.
Env camera images are bright and grainy¶
What is wrong
- The ready-made envs' camera observations (
camera=True: 64 x 64 pixels, 4 samples per pixel, no denoiser, the default studio light) come out with visible sampling noise, and bright on a light scene.
Number
- Each env's camera image of world 0 at reset (CPU), against a 256-sample image of the same pose: mean brightness of 255, RMS noise in grey levels at 4 / 16 / 64 samples, and the pixels within 5 levels at 4 samples:
GripperLiftCamera-v0: brightness 212; noise 4.2 / 1.7 / 0.9; 85 % within 5 levels.PickPlace-v0(varied looks, no texture images on disk): 124; 4.8 / 1.9 / 0.9; 85 %.DrawerOpen-v0(a cabinet drawn with its texture image): 176; 16.8 / 6.4 / 2.9; 45 %. Fine texture detail is what 4 samples per pixel average least well.- More samples cut the noise as above; each step costs about that factor in render time.
Why
- The env camera favours images per second for training (4 samples, no denoiser) and uses the studio light of the quick-look renders.
Workaround
- Build your own
alloy.camera.Camera(..., spp=16)over the env's sim for cleaner images, and passrender(..., exposure=-1)(one stop darker) when the images look washed out.
Planned fix
- Expose the env camera's samples, denoiser and exposure as env options (after the launch).
Glass objects render opaque unless a look file makes them glass¶
What is wrong
- An object of a glass material (
material="glass_soda_lime") is drawn as an opaque coloured solid, on the default fast camera and withquality="full"alike: what stands behind a pane or inside a glass is hidden. - Liquids are different:
quality="full"draws a sim's liquids as clear liquid.
Number
- A red cube 20 cm behind a 1 cm glass pane: hidden in both looks; with the look file below the cube is seen through the pane.
Why
- By design the fast camera draws matte surfaces only.
quality="full"gives every object a matte plastic of its colour: a physics material card does not choose how an object looks.
Workaround
- Give the object a glass look in a look file, which also turns on the full-material camera:
look = {"materials": {"pane_glass": {"preset": "glass_clear"}}, "assign": [{"match": "pane", "material": "pane_glass"}]}, thensim.render(look=look)oralloy.camera.camera_scene(sim, look=look).matchis a part of the object's name. - Depth and segmentation images always take the glass surface (they do not see through it).
Planned fix
- Default looks by material family (glass, metal, rubber) for
quality="full"(after the launch).
A robot file with one visual-only geom draws only its visual geoms¶
What is wrong
- Images (
sim.render,alloy.Camera) draw a robot from its visual geoms when its MJCF has any: geoms withcontype="0" conaffinity="0". Its collision geoms are then not drawn, though MuJoCo's own viewer draws geoms of groups 0 to 2. - A hand-written robot with one such geom (a marker, a spout, a decoration) draws as that geom alone; the rest of the robot is invisible. Physics is not affected: the hidden geoms still collide.
- A robot file with no visual-only geom draws all its collision geoms (the arm in AGENTS.md section 5 is drawn). Robots from the shipped library draw their visual meshes as before.
Number
- One capsule arm with a 1 cm visual-only sphere on it: the sphere is drawn, the capsule is not (1 of 2 geoms drawn).
Why
- The importer splits a file's geoms into visual and collision geoms. When the file has visual geoms, it shows those and hides every collision geom, as robot files with separate display meshes expect.
Workaround
- Give each part you want drawn a visual twin: the same geom with
contype="0" conaffinity="0" density="0"(no contact, no mass), next to the collision geom. - Or drop the visual-only geoms from the file: a file with none draws its collision geoms.
Planned fix
- At import, keep collision geoms of groups 0 to 2 visible, as MuJoCo does (robot files with display meshes put their collision geoms in group 3, so they stay hidden).