Fidelity, banging, and what humans actually do: the reference-engine investigation

This document consolidates one thread of the workbench's development: the user reported that the scripted pusher "bangs" into the T on pymunk, that superdex bangs too, and that pymunk-reference — although much gentler — still goes back and forth. The underlying question was sharper than the symptom: if the original code is in hand, how can the values and the behaviour be a bit off? Answering that required separating three things that had been tangled together: how faithful the reference engine is, what the scripted policy was doing, and what the human demonstrations that everyone trains on actually contain.

The sections below follow the order in which the questions were settled.

1. Is pymunk-reference a 100% replica?

Verdict: it was 95%; it is now ~98%. The missing 2% is deliberate and written down.

The audit went element by element against the published gym-pusht source, with each row backed by a measurement rather than a reading.

The defect the user was sensing was real

gym-pusht's reset(seed=783958) places the block at (231.16, 332.93). The workbench placed it at (271, 267). The published draw had been reproduced exactly, but the sampled pose was then applied through the workbench's own round-tripping setter (angle first) instead of gym-pusht's legacy setter (position, then angle). Because pymunk rotates a body about its centre of gravity, that order shifts the block by roughly 75 px. Every reference episode watched up to that point had therefore started from a pose that seed never produces upstream — a genuine "the values are a bit off".

The fix routes a sampled start through the legacy setter, exactly as upstream does, while an explicit reset(state=...) keeps round-tripping (that path is for everything that is not a published seed). The proof is on the live server, not only in tests:

live pymunk-reference, seed 783958 -> block (231.162, 332.927) angle 4.229
gym-pusht reset(seed=783958)       -> block (231.162, 332.927) angle 4.229

Two tests that had pinned the old, wrong behaviour were rewritten to assert the corrected semantics. The cross-version parity harness (ours on pymunk 7.3.0, the published env on 6.11.1 in its own virtualenv — it cannot run on pymunk 7 because it calls a Space API that was removed) still reports 0.000e+00.

The banging is 0% the reference

Neither gym-pusht nor LeWM ships a controller that approaches the block. gym-pusht's data was driven by human teleoperation; LeWM's WeakPolicy is seeded random relative offsets clipped to the block's neighbourhood. The retreat-and-ram cycle is entirely the workbench's own ScriptedPushPolicy. Measured on seed 783958 over 150 control steps:

pymunk-reference only looks gentler because a kinematic pusher cannot bounce off the block. So "you have the original code but the behaviour is off" resolves cleanly: the environment is a replica; the thing pushing in it was never part of the original.

2. Does a proper approach policy exist anywhere public?

The rule set for the search was strict: a policy counts only if its code is readable or its generated data is inspectable. Hearsay and README claims without artefacts do not count.

Verdict: no public, working scripted approach-and-push controller for the pymunk Push-T exists.

Two things are worth stating plainly:

1. Every "expert" Push-T dataset in the world-model literature is the same 206 human demonstrations, replayed with noise. There is no scripted expert behind any of them. The gentle, contact-holding motion people have in mind is a human moving a mouse.
2. The one scripted heuristic that does exist is the same naive rule the workbench's policy started from — go behind the block on the goal→block axis and push through — and it fails every episode.

The only claimed working controller (the Goldberg-lab paper) describes plan → approach → push → retreat, a contact library, a quasi-static model, and greedy contact selection by dominant pose error. No code or data yet, so by the rule above it does not exist — but its architecture is the informed design, and it explicitly includes a retreat phase, so "never retreat" is not the target either.

Three options were put to the user: build the controller from the paper's description, fix the retreat-and-ram in the existing heuristic, or replay the human demonstrations as the policy. The user's answer was a fourth: measure the humans first.

3. How humans push the T

Data and a provenance decision

The LeWM paper's dataset is the DINO-WM set, which is the Diffusion Policy human teleop episodes replayed with injected action noise to reach 18.5k–20k trajectories. The pushing skill in that data is a human's; the noise is synthetic. For velocity, acceleration and jerk statistics the noised copies would be actively misleading, so the analysis uses the 206 clean demonstrations (LeRobot pusht_keypoints, 8 keypoints per frame, 10 Hz). Block pose is recovered per frame by a rigid fit to the keypoints (max residual 3.8e-05 px); the dataset's reward column was checked against the repository's coverage() to 2.2e-07.

All 206 episodes contain contact; the first 50 were analysed and the remaining 156 held out to score the contact-selection rule. Contact is defined as distance(agent centre, T outline) - 15 <= 1 px; the gap histogram has a spike in (−1, 0.5] px from the collision slop and a flat tail beyond, so the threshold is not sensitive.

The headline: humans do not retreat and ram

Per-frame roles were assigned from contact state, the agent's velocity split into normal and tangential components at the nearest outline point, and block motion.

Retreat is 2.7% of all motion. What replaces it is orbiting: 72% of no-contact motion is tangential to the outline at a gap of about 37 px, followed by a four-frame radial approach. A typical episode has three contact bouts of about 17 frames, with 16 frames between them. The dominant role sequence is idle → approach → touch → push → slide → push.

Touching

• Head-on: incidence 17° to the inward normal; 72% of touches within 30°; only 7% glancing.
• From behind, as seen from the goal: 24° off the goal→block axis at touch.
• Slowing in: arrival speed 67 px/s, about half the orbit speed.
• Edge chosen by goal geometry, not proximity: the edge nearest the pusher at the previous release is used only 9% of the time.

Pushing — the strongest result

Block rotation follows the lever arm of the push about the CoG: correlation r = 0.87, slope 0.56 °/s per px, and the sign is correct in 100% of frames in which the block rotates faster than 2 °/s. The lever is chosen deliberately, scaled to the angle error:

A released bout takes the position error from 96 px to 48 px and the angle error from 53° to 5°, with 0.95 of the CoG displacement along the goal direction.

Release — when to let go

Release is triggered by geometry, not by distance. Push alignment (the angle between the push normal and the CoG→goal direction) is 26° at touch and 89° at release — above 45° in 91% of releases. The block is stopped first (0.4 px/s on the release step); the pusher then swings about 89° around the block and touches again roughly 16 frames later.

Choosing the next contact

The unfitted rule "push where the inward normal points at the goal, as close to the CoG line as possible" predicts the human's edge in 57% of touches under cross-validation and 49% on the external hold-out (540 touches), against 12.5% chance and 23% for always choosing the majority edge. A fitted contact-point model (alignment, torque × angle error, off-centre penalty; weights 1.79, 2.97, 1.92) reaches 56% / 51% and halves the perimeter error (24 px vs 32 px). The torque term does not change which edge is chosen; it moves the contact point along it. A mirrored decision table (goal direction in the block frame × angle error) is in the full report.

What this means for a controller

Orbit at ~120 px/s at a 37 px gap → four-frame normal approach at ~70 px/s → push at ~48 px/s with a lever of 0 px below 5° error and ~42 px above 10° → slide (two frames) to re-aim while alignment stays below 45° → release when alignment exceeds 45–60° with the block stopped → swing ~90° → next contact from the goal-normal rule.

4. Which findings are physics and which are the human

This was the user's sharpest question: of everything in the analysis, what is contributed by the already defined elements — PD law, kinematic pusher, dt, inertia, damping — and what by the operator?

The split is measurable, not arguable

The environment is a deterministic function of the action stream, so the two contributions can be separated by computation. The pure PD law was re-simulated in free space from each recorded start, fed only the recorded actions, and compared with the recorded agent path:

Zero in contact is the decisive number: the pusher is kinematic, the block never acts on it, and the entire agent trajectory is the PD law applied to the mouse. Every agent-side statistic therefore factors as

$$\text{agent path} = \underbrace{\text{PD}(k_p{=}100,\ k_v{=}20,\ dt{=}0.01)}{\text{physics, fixed}} \circ \underbrace{\text{mouse target stream}}{\text{human}}$$

What the physics contributes (fixed by the reference; would change on any other engine)

The PD response to a 100 px step command is 29.6 → 61.6 → 80.8 → 95.6 px over four control steps, with no overshoot, 90% settled at step four, and a peak of 320 px/s: a critically damped lag of about one control step. Its consequences are not human decisions:

What the human contributes (portable across engines)

Measured on the raw commanded targets before any filtering. In every role the agent goes exactly where the mouse points (cos(lead, motion) = 1.00), so these are genuinely the operator's decisions:

Consequences for the controller

• The speeds in the design section are agent speeds. On a kinematic pusher the controller must emit target-stream speeds — the mouse numbers — or it double-filters. On a dynamic pusher (pymunk, superdex) the mapping is different again.
• The rotation gain is reference-only. Do not feed forward 0.56 °/s per px; close the loop on the measured angle error.
• Edge, lever, orbit, incidence and release rules are the transferable content. Lag, smoothing, stop-on-release and the rotation gain are not.

5. Where this leaves the work