Design Book › Simulation setup

Simulation setup

What a designer must do

  1. Pin simulator versions, and read the docs at that version [1].
  2. Write the physics options into the file. Do not inherit defaults [2], [3].
  3. Audit the model before you touch the solver [4], [5]. Run the description checklist first.
  4. Set the timestep from the task, then check it by halving [6].
  5. Assert finite state in debug runs. On Isaac Lab PhysX backends, a newly imported robot without tuned parameters can go unstable, often sending NaNs into RL training [7].
  6. Rerun stored trajectories after an upgrade. MuJoCo 4.0.0 lists a breaking engine change to sidesite semantics for tendon wrapping [8].

Scope: the simulation guidelines. A simulator's settings are a recipe. Write them down [3], pin the version [1], and change one at a time [9]. Each table states the doc version the guideline came from, as the guideline states it.

Versions

Guidelines quote the doc they were read from. The release dates come from the catalog's release records.

Versions
SoftwareDoc version in the guidelinesSimulation guidelinesLatest release on record
MuJoCo4.0.0 docs (one guideline: stable alias, 4.0.0 on 2026-11-08)Most4.0.0, 2026-11-06
Isaac Lab3.0.0 docsSeveral below, such as fixed-seed reproduction [9]v3.0.0, 2026-10-20
Newton1.7.0 docs (one guideline: 1.9.0.dev0, latest alias on 2026-11-08)Several below, such as classifying the failure first [4]v1.7.0, 2026-10-14
PhysX SDK5.8.0 docs[10]PhysX SDK 5.9.0 (tag 110.1-omni-and-physx-5.9.0), 2026-07-14
Omni Physics guideLatest alias, captured 2026-11-08, linked from Isaac Lab 3.0.0 docs[11], [12]No version shown
Isaac SimRepo tag v6.2.0, in the Isaac Sim guidelinesNone. See chapter 25v6.2.0, 2026-10-14

No simulation guideline cites Isaac Sim. The Isaac Sim guidelines do. They were read from the Isaac Sim repo at tag v6.2.0, because the docs host's terms restrict automated access and its source row stays held. Of the 142 Isaac Sim guidelines, 109 come from agent-written notes in the repo's skills/ folder, so read those as guidance. Isaac Sim and Isaac Lab marks them.

The PhysX docs read are one minor version behind the newest tag on record. Check the maximum angular velocity default against your version [10], [13].

MuJoCo starting recipe

Each value comes from one guideline below. Set them in the file, then test on your model.

MuJoCo starting recipe
SettingStart atSource
Integratorimplicitfast[14]
SolverNewton[15]
Cone, manipulationElliptic, impratio about 10[16]
Timestep, contact-rich manipulationStart near 2 ms, which may already be on the long side. Use 0.5 to 2 ms with stiff grippers, high gains or thin objects[6]
solref[0], rigid contacts0.004 to 0.01 s[17]
solref[0] floorAt least 2 times the timestep[18]

Check the last two together. At the default 2 ms step, the solref[0] floor sits at the low end of the rigid-contact band, 0.004 s [18], [17].

Defaults and upgrades

Defaults and upgrades
LevelDoc versionRequirementCheckSource
shouldMuJoCo 4.0.0 docs, ModelingSet integrator, cone and solref explicitly. The internal defaults are not the recommended valueslint: option element sets integrator and cone[2]
shouldMuJoCo 4.0.0 docs, ModelingWrite physics options explicitly, so a default change cannot alter trajectorieslint: integrator, cone, solver and timestep are in the file[3]
guideMuJoCo 4.0.0 docs, Changelog4.0.0 lists a breaking engine change to sidesite semantics for tendon wrappingsim: compare stored trajectories[8]
mustMuJoCo 4.0.0 docs, ChangelogUpgrading a pre-split mujoco Python install: uninstall first or force-reinstallsim: import and step a model[19]

Timestep

Timestep
LevelDoc versionRequirementCheckSource
shouldMuJoCo 4.0.0 docs, ModelingContact-rich manipulation: start near 2 ms, which may already be on the long side. Use 0.5 to 2 ms with stiff grippers, high gains or thin objectssim: halve the step, compare the task metric[6]
guideMuJoCo 4.0.0 docs, ModelingLocomotion: 5 to 15 ms can work. Verify on your modelsim: halve the step, compare the gait metric[20]
mustMuJoCo 4.0.0 docs, Modelingsolref[0] at or above 2 times the timestep. With refsafe, standard integrators clamp lower valueslint: solref[0] over timestep per class[18]
shouldOmni Physics Articulation Stability Guide, latest alias, captured 2026-11-08 (linked from Isaac Lab 3.0.0 docs)In PhysX, complex mechanisms often need smaller timesteps. Closed articulation loops often need more than the default 60 Hz, and humanoids are often simulated at 100 Hz or moresim: reduce dt until instability stops, record it[11]
shouldNewton 1.7.0 docs, Simulation TuningReduce dt or add substeps before you raise stiffnesssim: stability across dt before any stiffness change[21]
guideOmni Physics Articulation Stability Guide, latest alias, captured 2026-11-08 (linked from Isaac Lab 3.0.0 docs)When a smaller step fixes instability, try fewer TGS/PGS position iterations to win back speedsim: sweep position iterations[12]
mustIsaac Lab 3.0.0 docs, Tune MJWarpKeep policy decimation out of stability fixes. If the physics step is unstable, fix the physicsreview: decimation changes have a control reason[22]

Integrator and solver

Integrator and solver
LevelDoc versionRequirementCheckSource
shouldMuJoCo 4.0.0 docs, ModelingUse implicitfast for most models. It costs nearly the same as Eulerlint: integrator is implicitfast, or justified[14]
mustMuJoCo 4.0.0 docs, ModelingFlex elasticity needs discrete. Implicit and implicitfast raise an errorsim: compile and step[23]
guideMuJoCo 4.0.0 docs, ModelingRecheck at upgrades. MuJoCo is trialling discrete as the replacement recommendationreview: read the integrator note[24]
shouldMuJoCo 4.0.0 docs, ModelingVibration from explicit damping feedback: switch to implicit or implicitfastsim: compare contact-force chatter[25]
shouldMuJoCo 4.0.0 docs, ModelingDefault to the Newton solver. Use CG only if profiling shows that factorizing the Hessian takes most of each stepsim: profile step time by stage[15]
shouldMuJoCo 4.0.0 docs, ModelingTry diagexact when bodies run far from qpos0 or have strongly anisotropic inertia and the solver divergessim: fwdinv discrepancy with and without[26]

Do not confuse MuJoCo's Newton solver [15] with the Newton physics engine [21]. The first is a solver option. The second is a separate engine with its own rows here.

Contact

Tuning order matters: lower solref and switch to elliptic cones before you raise solimp d_0 [27].

Contact
LevelDoc versionRequirementCheckSource
shouldMuJoCo 4.0.0 docs, ModelingElliptic cones with impratio about 10 for manipulation, 10-100 for legged robots, when slip matterslint: cone and impratio set for the task[16]
shouldMuJoCo 4.0.0 docs, ModelingWith pyramidal cones, avoid large impratio valueslint: flag high impratio with pyramidal[28]
shouldMuJoCo 4.0.0 docs, Modelingnoslip_iterations of 1-3 only for residual slip. It about doubles step time and makes inverse dynamics ill-definedsim: drift and step time with and without[29]
shouldMuJoCo 4.0.0 docs, ModelingDo not expect exact zero slip. Soft contact slips under sustained load, and NoSlip does not guarantee zerosim: hold a grasp, log drift against tolerance[30]
shouldMuJoCo 4.0.0 docs, ModelingLower solref[0] to 0.004-0.01 for rigid contacts, 0.004-0.005 for loop closureslint: report solref[0][17]
shouldMuJoCo 4.0.0 docs, ModelingTo set stiffness and damping independently, use the direct negative solref formatreview: sysid and restitution models use it[31]
mustMuJoCo 4.0.0 docs, ModelingDo not confuse solimp with solref. Setting solimp to 0.01 for d_0 nearly disables the constraintlint: flag solimp[0] far below the default[32]
guideMuJoCo 4.0.0 docs, ModelingLower solref and switch to elliptic cones before raising solimp d_0review: the tuning log shows this order[27]

Run settings

Run settings
LevelDoc versionRequirementCheckSource
shouldIsaac Lab 3.0.0 docs, Tune MJWarpKeep NewtonCfg debug_mode on until the solver budget is validated across the full reset, command and randomization distributionsim: log iteration-cap hits[33]
mustPhysX SDK 5.8.0 docs, Best PracticesRaise the maximum angular velocity when a fast spinner matters. The default is a low 7.0. The sentence states no unitsim: spin a body, read the result[10]
shouldMuJoCo docs stable alias (4.0.0 on 2026-11-08), SimulationDo not expect trajectories to reproduce across different warmstartssim: save and restore warmstart[34]
guideNewton 1.9.0.dev0 docs (latest alias on 2026-11-08), Deterministic SimulationUse SolverSteel when determinism matters. Otherwise measure the cost for your solversim: repeat a run, compare bit for bit[35]
guideMuJoCo 4.0.0 docs, ModelingTune to a stated goal on the speed-fidelity trade-off. Measure throughput headless with testspeedsim: testspeed before and after[36]

Debug order

Work down this list. Each step rules out a class of cause before you spend time on the next.

  1. Classify the failure: initialization, control, model or capacity. Do this before contact tuning [4].
  2. Load paused. Check overlaps, mesh mismatch, hulls, inertia, scale and axes [37].
  3. Reproduce with a fixed state, seed and action sequence. Change one variable at a time [9].
  4. Fix geometry, mass, drive and contact values. Solver options come after that [5].
  5. Do not sweep iterations past the plateau [38].
Debug order
LevelDoc versionRequirementCheckSource
shouldMuJoCo 4.0.0 docs, ModelingLoad paused and rule out modeling bugs before tuningsim: run the paused checklist[37]
shouldMuJoCo 4.0.0 docs, ModelingStiffer contacts do not cure a modeling bug. They can add chatter or divergereview: tuning log names the model check[39]
shouldNewton 1.7.0 docs, Simulation TuningRule out initialization, control, model and capacity causes firstreview: the report classifies the failure[4]
shouldNewton 1.7.0 docs, Simulation TuningPhysical values first, solver options afterreview: solver changes follow the audit[5]
shouldNewton 1.7.0 docs, Simulation TuningHarder contact is not always more stable. Tune to task metrics, not one penetration numbersim: task metric and jitter across stiffness[40]
shouldNewton 1.7.0 docs, Simulation TuningExtreme solver settings do not hide model errors. Bad mass ratios and overlaps usually stay unstablesim: test with defaults after each model fix[41]
shouldIsaac Lab 3.0.0 docs, Tune MJWarpFixed state, seed and action sequence; one variable at a timesim: stored script reproduces the failure[9]
shouldIsaac Lab 3.0.0 docs, Tune MJWarpRepair the asset or controller. No solver setting makes an invalid one correctreview: audit done before tuning[42]
shouldIsaac Lab 3.0.0 docs, Tune MJWarpStop sweeping iterations at the plateau. They cannot fix bad inertia, reset penetration or excess stiffnesssim: sweep one limit, plot the metric[38]
shouldIsaac Lab 3.0.0 docs, TroubleshootingOn Isaac Lab PhysX backends, a newly imported robot without tuned parameters can go unstable, often sending NaNs into RL training. Consult the stability guidesim: assert finite state and observations each step in debug runs[7]
shouldIsaac Lab 3.0.0 docs, Prepare an Asset for Newton with MJWarpNewton-only failure: keep the smallest fixed-state reproduction and record the first non-finite quantitysim: store both[43]
shouldMuJoCo 4.0.0 docs, ModelingHigh-frequency, low-amplitude vibration: the usual solution is to reduce the timestep and/or add armature to the relevant jointssim: view contact forces, compare both changes[44]

Your machines

The database has no part row for an RTX 5090 or a MacBook Air M5. One project reports a training run on an RTX 5090 [45]. Isaac Sim's standalone binary lists Windows x86_64 ([46], an agent-written note), and Isaac Lab lists Windows 11 on x86_64 [47]. Newton runs on macOS on CPU only [48]. For mjlab, training needs an NVIDIA GPU, and macOS is for evaluation only [49]. The database has no statement on whether Isaac Sim or Isaac Lab run on macOS, and no guideline on MuJoCo on Windows or Apple silicon. The full tables are in chapter 25. Check each simulator's install docs at your pinned version [1].

Where the database is thin

Sources

Each guideline in this chapter with its source, the date it was read and the exact words of the source. Level: must means breaking it causes failure or harm, should is good practice, guide is a rule of thumb.

  1. Have agents read docs at the pinned simulator version, because the Isaac Lab 3.0.0 project notes that compatibility with later releases has not been validated. Level: must. isaac-sim.github.io 2026-11-08“or later versions has not been validated.”
  2. Set MuJoCo integrator, cone and solref explicitly in each new model, because their internal defaults are not the recommended values. Level: should. mujoco.readthedocs.io 2026-11-08
  3. Write physics options explicitly so that a future default change cannot silently alter trajectories. Level: should. mujoco.readthedocs.io 2026-11-08
  4. Rule out initialization, control, model and capacity causes before you tune contact. Level: should. newton-physics.github.io 2026-11-08“Rule out non-contact issues before tuning contact.”
  5. Fix geometry, mass, drive and contact values first; change solver options only after that. Level: should. newton-physics.github.io 2026-11-08“Tune physical parameters before solver options.”
  6. This guideline is held back: its source does not allow us to publish it yet.
  7. On Isaac Lab PhysX backends, a newly imported robot without tuned parameters can go unstable, often sending NaNs into RL training; consult the stability guide. Level: should. isaac-sim.github.io 2026-11-08“this will often result in NaNs propagating into the learning pipeline”
  8. MuJoCo 4.0.0 lists a breaking engine change to sidesite semantics for tendon wrapping. Level: guide. mujoco.readthedocs.io 2026-11-08
  9. Reproduce a failure with a fixed state, seed and action sequence, and change one variable at a time. Level: should. isaac-sim.github.io 2026-11-08“reproduce one failure with a fixed initial state, seed, and action sequence.”
  10. Raise the PhysX SDK maximum angular velocity when a fast spinner matters, because its default is a low value of 7.0. 7.0 unit not stated in that sentence Level: must. nvidia-omniverse.github.io 2026-11-08
  11. In PhysX, complex mechanisms often need smaller timesteps; closed articulation loops often need more than the default 60 Hz, and humanoids are often simulated at 100 Hz or more. 100 Hz Level: should. docs.omniverse.nvidia.com 2026-11-08
  12. When a smaller PhysX timestep fixes instability, try fewer TGS/PGS position iterations to win back speed. Level: guide. docs.omniverse.nvidia.com 2026-11-08
  13. Have agents verify default values and API names against the code of the installed release, as Newton's tuning guide tells humans and agents to do. Level: must. newton-physics.github.io 2026-11-08“the code is the source of truth.”
  14. Use implicitfast for most MuJoCo models; it costs nearly the same as Euler and integrates velocity feedback implicitly. Level: should. mujoco.readthedocs.io 2026-11-08
  15. Use the MuJoCo Newton solver by default; move to CG only when Hessian factorization dominates step time. Level: should. mujoco.readthedocs.io 2026-11-08
  16. Use elliptic cones with impratio about 10 for MuJoCo manipulation and 10-100 for legged robots when slip matters. 10 impratio Level: should. mujoco.readthedocs.io 2026-11-08
  17. Lower MuJoCo solref[0] to 0.004-0.01 for rigid contacts and 0.004-0.005 for loop closures. 0.004-0.01 s Level: should. mujoco.readthedocs.io 2026-11-08
  18. Keep MuJoCo solref[0] at least twice the timestep; with refsafe, standard integrators clamp lower values. 2 timesteps Level: must. mujoco.readthedocs.io 2026-11-08
  19. When upgrading a pre-split mujoco Python install to 4.0.0, uninstall first or force-reinstall, so that pip does not remove moved files. Level: must. mujoco.readthedocs.io 2026-11-08
  20. For MuJoCo locomotion, a 5-15 ms timestep can work well; verify stability on your model. 5-15 ms Level: guide. mujoco.readthedocs.io 2026-11-08
  21. In Newton tuning, reduce dt or add substeps before you raise stiffness. Level: should. newton-physics.github.io 2026-11-08“Reduce the simulation dt or increase substeps before raising stiffness.”
  22. Keep policy decimation out of stability fixes; if the physics step is unstable, fix the physics. Level: must. isaac-sim.github.io 2026-11-08“Do not change policy decimation merely to conceal an unstable physics step.”
  23. Use the discrete integrator for MuJoCo flex elasticity, because implicit and implicitfast raise an error. Level: must. mujoco.readthedocs.io 2026-11-08
  24. Recheck the integrator choice at upgrades, because MuJoCo is trialling discrete as a replacement recommendation. Level: guide. mujoco.readthedocs.io 2026-11-08
  25. If a MuJoCo model vibrates with explicit damping feedback, switch to implicit or implicitfast. Level: should. mujoco.readthedocs.io 2026-11-08
  26. Try the MuJoCo diagexact flag when bodies operate far from qpos0 or have strongly anisotropic inertia and the solver diverges. Level: should. mujoco.readthedocs.io 2026-11-08
  27. Lower solref and switch to elliptic cones before raising solimp d_0, because they are stronger levers. Level: guide. mujoco.readthedocs.io 2026-11-08
  28. Avoid large impratio values when MuJoCo uses pyramidal cones. Level: should. mujoco.readthedocs.io 2026-11-08
  29. Use MuJoCo noslip_iterations of 1-3 only for residual slip, as it about doubles step time and makes inverse dynamics ill-defined. Level: should. mujoco.readthedocs.io 2026-11-08
  30. Do not expect exact zero slip from MuJoCo contact; soft contact gives nonzero slip under sustained load, and NoSlip does not guarantee zero. Level: should. mujoco.readthedocs.io 2026-11-08
  31. To set stiffness and damping independently in MuJoCo, use the direct negative solref format. Level: should. mujoco.readthedocs.io 2026-11-08
  32. Do not confuse solimp with solref: setting solimp to 0.01 for d_0 nearly disables the constraint. Level: must. mujoco.readthedocs.io 2026-11-08
  33. Keep NewtonCfg debug_mode on until the solver budget is validated across the full reset, command and randomization distribution. Level: should. isaac-sim.github.io 2026-11-08“Turn off debug_mode only after the solver budget has been validated”
  34. Do not expect trajectories to reproduce across different warmstarts, because small differences grow exponentially in many systems. Level: should. mujoco.readthedocs.io 2026-11-08
  35. In Newton, use SolverSteel when determinism matters for articulated or rigid scenes; otherwise measure the cost of determinism for your solver. Level: guide. newton-physics.github.io 2026-11-08“Use SolverSteel when determinism matters for articulated or rigid-body scenes.”
  36. Tune to a stated goal on the speed-fidelity trade-off, then measure throughput headless with testspeed. Level: guide. mujoco.readthedocs.io 2026-11-08
  37. Load the MuJoCo model paused and rule out modeling bugs before tuning parameters. Level: should. mujoco.readthedocs.io 2026-11-08
  38. Stop sweeping iterations when metrics plateau; they cannot compensate for bad inertia, reset penetration or excess drive stiffness. Level: should. isaac-sim.github.io 2026-11-08“More iterations cannot compensate for bad inertia”
  39. Stiffer contacts are not a cure for a modeling bug; they can add chatter or make the simulation diverge. Level: should. mujoco.readthedocs.io 2026-11-08
  40. Do not assume a harder contact is more stable; tune to task metrics, not one penetration number. Level: should. newton-physics.github.io 2026-11-08“Harder is not always more stable.”
  41. Do not hide model errors with extreme solver settings; bad mass ratios and overlapping geometry usually stay unstable. Level: should. newton-physics.github.io 2026-11-08“Do not hide model errors with extreme solver settings.”
  42. Repair the asset or the controller itself; no solver setting makes an invalid one correct. Level: should. isaac-sim.github.io 2026-11-08“A solver setting cannot correct an invalid asset or controller.”
  43. For a Newton-only failure, keep the smallest fixed-state reproduction and record the first non-finite quantity. Level: should. isaac-sim.github.io 2026-11-08“record the first non-finite quantity”
  44. For high-frequency, low-amplitude vibration in MuJoCo, the usual solution is to reduce the timestep and/or add armature to the relevant joints. Level: should. mujoco.readthedocs.io 2026-11-08
  45. The measured training and evaluation wall time was 2 h 38 min 21 s on an RTX 5090; use it as one planning point. Level: guide. raw.githubusercontent.com 2026-11-09“Its measured training/evaluation wall time was **2 h 38 min 21 s** on an RTX 5090.”
  46. The standalone binary is offered on Linux x86_64, Windows x86_64 and Linux aarch64 only on supported DGX Spark systems. Level: must. raw.githubusercontent.com 2026-11-09
  47. Supported platforms are Ubuntu 22.04 or later on x86_64, Linux aarch64 including DGX Spark, and Windows 11 on x86_64. Level: must. raw.githubusercontent.com 2026-11-09“- Ubuntu 22.04+ on x86_64, Linux aarch64 (including DGX Spark), or Windows 11 on x86_64.”
  48. Newton runs on Linux x86-64 and aarch64, Windows x86-64, and macOS on CPU only. Level: must. raw.githubusercontent.com 2026-11-09“- Linux (x86-64, aarch64), Windows (x86-64), or macOS (CPU only) - macOS has no GPU acceleration”
  49. Plan on an NVIDIA GPU for mjlab training; macOS works for evaluation only. Level: must. raw.githubusercontent.com 2026-11-08“mjlab requires an NVIDIA GPU for training. macOS is supported for evaluation only.”
  50. The contact-rich PhysX baseline uses 8 to 64 position and 1 to 4 velocity iterations. Level: guide. raw.githubusercontent.com 2026-11-09“min_position_iteration_count=8, max_position_iteration_count=64, min_velocity_iteration_count=1, max_velocity_iteration_count=4,”
  51. Treat shipped task configs as evidence for a similar workload, not as defaults to copy. Level: should. raw.githubusercontent.com 2026-11-09“Use maintained task configurations as evidence for a similar workload, not as defaults to copy.”
  52. The SO-101 keyboard typing task uses a physics dt of 0.01 s. 0.01 s Level: guide. raw.githubusercontent.com 2026-11-09“sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg(), dt=0.01)”
  53. The SO-101 keyboard typing task on Newton uses a pyramidal friction cone with impratio = 1.0. Level: guide. raw.githubusercontent.com 2026-11-09“impratio=1.0, cone="pyramidal",”
  54. The workshop SO-101 teleop environment uses sim dt = 1/120. Level: guide. raw.githubusercontent.com 2026-11-09“self.sim.dt = 1 / 120”