Convergence study: where the defaults come from

Regenerate this file and the literal tables in src/pusht_sim/envs/recommended.py with:

PYTHONPATH=src .venv/bin/python scripts/convergence_study.py

Measured pymunk on 2026-09-24T15:51:08+00:00, superdex on 2026-09-24T15:52:47+00:00.

Result

Read the last column against the second: on pymunk it is a real convergence result with headroom left, 2.0x cheaper than the yardstick; on superdex the recommendation is the yardstick itself - nothing cheaper held tolerance, so this engine has no measured headroom on this suite. What both replace is the same thing - hand-picked defaults that miss the tolerance by orders of magnitude. The rest of this document is how those numbers were obtained.

Method

Open-loop replay. The scripted driver reacts to what the physics does, so re-running it at a coarser setting changes the commands as well as the response, and the two effects are then impossible to separate. Instead the command sequence is generated once per scenario at the reference setting and replayed verbatim by every rung of every ladder. What is left over is integration error and nothing else.

Worst case over the suite. The seven scenarios each stress a different part of the simulator - pure sliding (t1), torque from an off-centre push (t2, t7), wall contact (t3), a long contact history (t4), a small contact patch on a long lever (t5), sub-degree alignment (t6). Averaging over them would let the one case that breaks disappear into six that do not, so every verdict below is the worst scenario, not the mean. Scenarios used: t1, t2, t3, t4, t5, t6, t7.

Tolerances. 1 workspace unit of final block position, 0.02 rad (1.1 degrees) of final block angle, 0.01 of goal coverage. These are pusht_sim.runs.TOL_POSITION/TOL_ANGLE/TOL_COVERAGE, the same numbers a run diff calls "the same answer", so a default chosen here and a run compared there cannot disagree. One unit is one millimetre of table; the block is 120 units across.

The reference has to earn it. There is no closed form for a frictional push, so the finest rung of each ladder stands in for the true answer - but only if refining actually helps. Before anything is measured, every rung takes a rest test: the pusher is commanded to hold its starting position and the block, which nothing is pushing, must stay put. The best rung of a ladder sets the floor, and the yardstick is the finest rung whose drift is no more than double that floor. Rungs coarser than the yardstick are still swept - failing to be a good ruler does not disqualify a setting from being measured. This is not a formality: on superdex the rest test rejects sim_hz past 320, contact_stiffness past 10000 as a yardstick.

Selection rule. The cheapest rung that is inside tolerance and whose every finer rung is also inside tolerance. The second clause matters: a coarse setting can cross the reference by luck, and a table that stopped at the first pass would ship that crossing point. Then a stability margin: a value within 2x of a setting measured to diverge is stepped one rung away from the cliff. Finally the whole combination is re-measured together, because the knobs interact.

Horizon. Episodes are scored at 40 control steps (4 s at 10 Hz control), not the full 120-step episode, and that is deliberate. Push-T under open-loop replay is a contact problem: once two runs disagree about whether a corner caught, the gap grows on its own. The sim_hz tables below show how little headroom there is - even a factor-of-two refinement at the top of the ladder still moves the final pose by more than the tolerance at 4 s - and the agreement windows show the published defaults parting company with the reference within a fraction of a second. Scoring at the full episode length would measure that amplification rather than integration error, and every rung would fail for the same reason. The agreement window is where the limit gets reported instead of hidden.

Cost. Wall-clock seconds per episode over the same 40 steps, run serially so the number describes the setting rather than the machine's core count. Absolute values are laptop-CPU specific; the ratios are the point.

pymunk

pymunk: rest test (choosing the yardstick)

Pusher commanded to hold its starting position; the number is the worst distance the block travels anyway, over the suite. Scenario t7 starts with the pusher already overlapping the block, so some separation motion is unavoidable on any setting - the question is which rungs stay near that floor and which invent motion of their own. A rung that more than doubles the floor is not a yardstick others can be measured against, however small its step; it is still swept as a candidate if it is coarser than the one that is.

• sim_hz reference 1280 - every rung stayed within 1.16 u of the 1.16 u floor.

• solver_iterations reference 64 - every rung stayed within 1.16 u of the 1.16 u floor.

• pusher_sides reference 64 - every rung stayed within 1.00 u of the 0.28 u floor.

Reference setting, each knob at the finest rung the rest test trusts: sim_hz=1280, solver_iterations=64, pusher_sides=64, control_hz=10 - 95 ms per episode.

pymunk: sim_hz

Physics steps per simulated second. The primary resolution knob: halving the step should stop changing the outcome once the run has converged.

Chosen: sim_hz=640 - cheapest rung inside tolerance with every finer rung also inside it.

pymunk: solver_iterations

Constraint iterations per step in pymunk, Newton iterations per step in SuperDex.

Chosen: solver_iterations=1 - cheapest rung inside tolerance with every finer rung also inside it.

pymunk: pusher_sides

Polygon resolution of the pusher disc. Geometric discretisation of the contact patch.

Chosen: pusher_sides=16 - cheapest rung inside tolerance with every finer rung also inside it.

pymunk: the recommendation

Verified jointly, not just knob by knob: at sim_hz=640, solver_iterations=1, pusher_sides=16 the whole suite replays 0.468 units and 0.0034 rad from the reference at worst (t7), 0.252 units on average, no scenario diverged, 46.8 ms per episode against the reference's 95.3 ms (2.0x cheaper).

What this replaces. The hand-picked SimParams defaults - sim_hz=100, solver_iterations=10, pusher_sides=24 - score 2.720 units and 0.0224 rad from the reference at worst (t1) for 26.3 ms per episode. That is 3x the tolerance, at 0.56x the recommendation's cost - which is the whole reason this study exists.

Agreement window. Over a full 120-step episode the recommended setting tracks the reference for 63 control steps (6.3 s) before the worst scenario (t2) drifts past 1 unit; the published defaults manage 5 steps (0.5 s). Per scenario: t1 106, t2 63, t3 120, t4 120, t5 120, t6 120, t7 120. The gap between those two numbers is the cost of the hand-picked defaults: an open-loop replay of a contact-rich push amplifies any disagreement, so a setting that is slightly wrong early is arbitrarily wrong later.

Not gratuitously conservative: sim_hz=20, solver_iterations=1, pusher_sides=16 - the recommendation with one knob stepped back down - misses by 76.20 units on t3, 76x the tolerance. tests/test_recommended.py re-runs exactly that.

superdex

superdex: rest test (choosing the yardstick)

Pusher commanded to hold its starting position; the number is the worst distance the block travels anyway, over the suite. Scenario t7 starts with the pusher already overlapping the block, so some separation motion is unavoidable on any setting - the question is which rungs stay near that floor and which invent motion of their own. A rung that more than doubles the floor is not a yardstick others can be measured against, however small its step; it is still swept as a candidate if it is coarser than the one that is.

• sim_hz reference 320 - rejected as a yardstick: 160 (2.41 u of drift), 640 (20.82 u of drift), 1280 (71.49 u of drift) against a 0.88 u floor.

• solver_iterations reference 64 - rejected as a yardstick: 1 (10.54 u of drift), 2 (5.16 u of drift), 4 (6.65 u of drift), 8 (3.49 u of drift), 16 (5.18 u of drift) against a 0.67 u floor.

• pusher_sides reference 64 - rejected as a yardstick: 4 (44.33 u of drift), 8 (3.48 u of drift), 16 (6.41 u of drift), 32 (4.38 u of drift) against a 1.48 u floor.

• contact_stiffness reference 10000 - rejected as a yardstick: 100000 (4.84 u of drift), 1e+06 (4.93 u of drift), 1e+07 (7.49 u of drift) against a 1.58 u floor.

Reference setting, each knob at the finest rung the rest test trusts: sim_hz=320, solver_iterations=64, pusher_sides=64, contact_stiffness=10000, control_hz=10 - 200 ms per episode.

superdex: sim_hz

Physics steps per simulated second. The primary resolution knob: halving the step should stop changing the outcome once the run has converged.

Chosen: sim_hz=320 - no cheaper rung held tolerance, so this is the reference itself - this knob has not demonstrated convergence, it has run out of headroom.

superdex: solver_iterations

Constraint iterations per step in pymunk, Newton iterations per step in SuperDex.

Chosen: solver_iterations=64 - no cheaper rung held tolerance, so this is the reference itself - this knob has not demonstrated convergence, it has run out of headroom.

superdex: pusher_sides

Polygon resolution of the pusher disc. Geometric discretisation of the contact patch.

Chosen: pusher_sides=64 - no cheaper rung held tolerance, so this is the reference itself - this knob has not demonstrated convergence, it has run out of headroom.

superdex: contact_stiffness

Penalty coefficient of the contact model. Too soft and the pusher sinks into the block; too stiff and the solver needs more iterations.

Chosen: contact_stiffness=10000 - no cheaper rung held tolerance, so this is the reference itself - this knob has not demonstrated convergence, it has run out of headroom.

superdex: the step/stiffness corner

Each sweep above holds the other knobs at their finest trustworthy rung, which is the most stable corner of the space - so a stiffness/step interaction cannot show up there. This grid puts them back together at the recommended solver effort and facet count, over the whole ladder of both knobs rather than only the rungs the rest test trusts: a blow-up is an absolute fact about a setting and is worth knowing wherever a user might go. Cells show the worst-case position error in units against the reference, or the scenarios that diverged; cells marked ~ use a rung the rest test rejected as a yardstick, so read their error as indicative and their stability as exact.

Divergence boundary. Nothing diverges above 40 Hz (dt = 0.0250 s); at or below it the solver gives up once the contact is at least 1e+06 N/m stiff. Cell by cell: 20 Hz at stiffness 1e+06 diverges on t2; 20 Hz at stiffness 1e+07 diverges on t1, t2, t6, t7; 40 Hz at stiffness 1e+07 diverges on t1, t2, t3, t6, t7. The recommended rate sits 8x above that boundary and the recommended stiffness 100x below it. tests/test_recommended.py re-runs the diverging cell nearest safety (sim_hz=40, contact_stiffness=1e+07, solver_iterations=64, pusher_sides=64) and requires it to blow up, so this boundary cannot quietly become a claim about an engine that has since been fixed.

superdex: the recommendation

The recommendation is the reference setting itself: no cheaper rung of any ladder held tolerance, so this engine has no measured headroom on this suite. It costs 200.1 ms per episode. That is a real result, not a missing one - the tables above show every rung that was tried and by how much it missed.

What this replaces. The hand-picked SimParams defaults - sim_hz=100, solver_iterations=10, pusher_sides=24, contact_stiffness=100000 - score 24.831 units and 1.1244 rad from the reference at worst (t3) for 97.4 ms per episode. That is 25x the tolerance, at 0.49x the recommendation's cost - which is the whole reason this study exists.

Agreement window. The recommendation is the reference here, so asking how long it tracks the reference is vacuous. The informative comparison is the published defaults: over a full 120-step episode they track it for 1 control steps (0.1 s) before t7 drifts past 1 unit. Per scenario: t1 11, t2 9, t3 23, t4 120, t5 17, t6 14, t7 1.

Not gratuitously conservative: sim_hz=320, solver_iterations=64, pusher_sides=4, contact_stiffness=10000 - the recommendation with one knob stepped back down - misses by 200.19 units on t7, 200x the tolerance. tests/test_recommended.py re-runs exactly that.

Caveats

• Held fixed. control_hz is pinned at 10 Hz throughout: it defines the task (how much authority the policy has) rather than the accuracy of the answer, so sweeping it would measure a different problem, not a finer one. Mass, density, friction and the pusher gains are held at their published values - they change the physics being simulated, so a difference there is sensitivity, not error, and there is nothing to converge to. SuperDex's integration_method stays at bdf1; BDF2 is a different integrator, not a finer rung of the same ladder, and mixing it in would make the sweep compare two things at once. contact_damping stays at its published 0: a damped contact would change the physics rather than resolve it, and the rest tables show what the undamped choice costs.

• The knobs interact. The single-knob tables hold everything else at the reference rung, which is the most forgiving corner of the space. The grid is where that shows: superdex blows up at sim_hz=20 with contact_stiffness=1e+06, a pair neither single-knob sweep can reach. A user who moves two knobs at once off these defaults is outside what was measured.

• The reference is a stand-in. Errors are measured against the rung the rest test trusts, not against truth. On this run on superdex the rest test rejects sim_hz past 320, contact_stiffness past 10000 as a yardstick, so those finest rungs are measured and reported but cannot be the yardstick. If a whole ladder shares a bias - a contact model that is systematically too soft, say - none of these tables can see it. The compare_backends harness is the cross-check for that: two engines sharing a bug is much less likely than one.

• One scenario carries the rest test. Every rest number above is scenario t7, because t7 is the only case whose starting pose puts the pusher inside the block; the other six sit still at every rung on both engines. How an engine resolves an initial overlap is a real property worth knowing - it is what disqualifies a rung as a yardstick here - but it is a different question from integration accuracy, and it is being answered by a sample of one.

• The driver hits hard. The scripted policy issues absolute position targets, and when it switches from circling the block to pushing it the target can jump most of the workspace in one control period. The pusher then arrives at over a metre per second, and a high-speed impact is the single most step-size-sensitive event in the whole task. It is what sets the rates above: pymunk needs 640 Hz against a published 100 Hz; superdex needs 320 Hz against a published 100 Hz. A gentler policy would need less of all of it.

• One horizon, one policy. Scoring is at 40 control steps (4 s) under the scripted policy, for the reason in the method section. The agreement window is the honest statement of how far that extends. The numbers are a floor on required fidelity, not a ceiling.

• Single sample per scenario. Scenarios are deterministic fixed poses, so repeats would be identical and there is no variance to report; the spread across the seven cases is doing the job a confidence interval would do elsewhere.

• Timings are machine-specific. Wall-clock milliseconds per episode were measured serially on one laptop CPU. The ratio between a setting and the reference travels; the absolute number does not.