Simulation setup
What a designer must do
- Pin simulator versions, and read the docs at that version [1].
- Write the physics options into the file. Do not inherit defaults [2], [3].
- Audit the model before you touch the solver [4], [5]. Run the description checklist first.
- Set the timestep from the task, then check it by halving [6].
- 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].
- Rerun stored trajectories after an upgrade. MuJoCo 4.0.0 lists a breaking engine change to
sidesitesemantics 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.
| Software | Doc version in the guidelines | Simulation guidelines | Latest release on record |
|---|---|---|---|
| MuJoCo | 4.0.0 docs (one guideline: stable alias, 4.0.0 on 2026-11-08) | Most | 4.0.0, 2026-11-06 |
| Isaac Lab | 3.0.0 docs | Several below, such as fixed-seed reproduction [9] | v3.0.0, 2026-10-20 |
| Newton | 1.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 SDK | 5.8.0 docs | [10] | PhysX SDK 5.9.0 (tag 110.1-omni-and-physx-5.9.0), 2026-07-14 |
| Omni Physics guide | Latest alias, captured 2026-11-08, linked from Isaac Lab 3.0.0 docs | [11], [12] | No version shown |
| Isaac Sim | Repo tag v6.2.0, in the Isaac Sim guidelines | None. See chapter 25 | v6.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.
| Setting | Start at | Source |
|---|---|---|
| Integrator | implicitfast | [14] |
| Solver | Newton | [15] |
| Cone, manipulation | Elliptic, impratio about 10 | [16] |
| Timestep, contact-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 objects | [6] |
solref[0], rigid contacts | 0.004 to 0.01 s | [17] |
solref[0] floor | At 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
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | MuJoCo 4.0.0 docs, Modeling | Set integrator, cone and solref explicitly. The internal defaults are not the recommended values | lint: option element sets integrator and cone | [2] |
| should | MuJoCo 4.0.0 docs, Modeling | Write physics options explicitly, so a default change cannot alter trajectories | lint: integrator, cone, solver and timestep are in the file | [3] |
| guide | MuJoCo 4.0.0 docs, Changelog | 4.0.0 lists a breaking engine change to sidesite semantics for tendon wrapping | sim: compare stored trajectories | [8] |
| must | MuJoCo 4.0.0 docs, Changelog | Upgrading a pre-split mujoco Python install: uninstall first or force-reinstall | sim: import and step a model | [19] |
Timestep
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | MuJoCo 4.0.0 docs, Modeling | Contact-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 objects | sim: halve the step, compare the task metric | [6] |
| guide | MuJoCo 4.0.0 docs, Modeling | Locomotion: 5 to 15 ms can work. Verify on your model | sim: halve the step, compare the gait metric | [20] |
| must | MuJoCo 4.0.0 docs, Modeling | solref[0] at or above 2 times the timestep. With refsafe, standard integrators clamp lower values | lint: solref[0] over timestep per class | [18] |
| should | Omni 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 more | sim: reduce dt until instability stops, record it | [11] |
| should | Newton 1.7.0 docs, Simulation Tuning | Reduce dt or add substeps before you raise stiffness | sim: stability across dt before any stiffness change | [21] |
| guide | Omni 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 speed | sim: sweep position iterations | [12] |
| must | Isaac Lab 3.0.0 docs, Tune MJWarp | Keep policy decimation out of stability fixes. If the physics step is unstable, fix the physics | review: decimation changes have a control reason | [22] |
Integrator and solver
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | MuJoCo 4.0.0 docs, Modeling | Use implicitfast for most models. It costs nearly the same as Euler | lint: integrator is implicitfast, or justified | [14] |
| must | MuJoCo 4.0.0 docs, Modeling | Flex elasticity needs discrete. Implicit and implicitfast raise an error | sim: compile and step | [23] |
| guide | MuJoCo 4.0.0 docs, Modeling | Recheck at upgrades. MuJoCo is trialling discrete as the replacement recommendation | review: read the integrator note | [24] |
| should | MuJoCo 4.0.0 docs, Modeling | Vibration from explicit damping feedback: switch to implicit or implicitfast | sim: compare contact-force chatter | [25] |
| should | MuJoCo 4.0.0 docs, Modeling | Default to the Newton solver. Use CG only if profiling shows that factorizing the Hessian takes most of each step | sim: profile step time by stage | [15] |
| should | MuJoCo 4.0.0 docs, Modeling | Try diagexact when bodies run far from qpos0 or have strongly anisotropic inertia and the solver diverges | sim: 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].
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | MuJoCo 4.0.0 docs, Modeling | Elliptic cones with impratio about 10 for manipulation, 10-100 for legged robots, when slip matters | lint: cone and impratio set for the task | [16] |
| should | MuJoCo 4.0.0 docs, Modeling | With pyramidal cones, avoid large impratio values | lint: flag high impratio with pyramidal | [28] |
| should | MuJoCo 4.0.0 docs, Modeling | noslip_iterations of 1-3 only for residual slip. It about doubles step time and makes inverse dynamics ill-defined | sim: drift and step time with and without | [29] |
| should | MuJoCo 4.0.0 docs, Modeling | Do not expect exact zero slip. Soft contact slips under sustained load, and NoSlip does not guarantee zero | sim: hold a grasp, log drift against tolerance | [30] |
| should | MuJoCo 4.0.0 docs, Modeling | Lower solref[0] to 0.004-0.01 for rigid contacts, 0.004-0.005 for loop closures | lint: report solref[0] | [17] |
| should | MuJoCo 4.0.0 docs, Modeling | To set stiffness and damping independently, use the direct negative solref format | review: sysid and restitution models use it | [31] |
| must | MuJoCo 4.0.0 docs, Modeling | Do not confuse solimp with solref. Setting solimp to 0.01 for d_0 nearly disables the constraint | lint: flag solimp[0] far below the default | [32] |
| guide | MuJoCo 4.0.0 docs, Modeling | Lower solref and switch to elliptic cones before raising solimp d_0 | review: the tuning log shows this order | [27] |
Run settings
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | Isaac Lab 3.0.0 docs, Tune MJWarp | Keep NewtonCfg debug_mode on until the solver budget is validated across the full reset, command and randomization distribution | sim: log iteration-cap hits | [33] |
| must | PhysX SDK 5.8.0 docs, Best Practices | Raise the maximum angular velocity when a fast spinner matters. The default is a low 7.0. The sentence states no unit | sim: spin a body, read the result | [10] |
| should | MuJoCo docs stable alias (4.0.0 on 2026-11-08), Simulation | Do not expect trajectories to reproduce across different warmstarts | sim: save and restore warmstart | [34] |
| guide | Newton 1.9.0.dev0 docs (latest alias on 2026-11-08), Deterministic Simulation | Use SolverSteel when determinism matters. Otherwise measure the cost for your solver | sim: repeat a run, compare bit for bit | [35] |
| guide | MuJoCo 4.0.0 docs, Modeling | Tune to a stated goal on the speed-fidelity trade-off. Measure throughput headless with testspeed | sim: 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.
- Classify the failure: initialization, control, model or capacity. Do this before contact tuning [4].
- Load paused. Check overlaps, mesh mismatch, hulls, inertia, scale and axes [37].
- Reproduce with a fixed state, seed and action sequence. Change one variable at a time [9].
- Fix geometry, mass, drive and contact values. Solver options come after that [5].
- Do not sweep iterations past the plateau [38].
| Level | Doc version | Requirement | Check | Source |
|---|---|---|---|---|
| should | MuJoCo 4.0.0 docs, Modeling | Load paused and rule out modeling bugs before tuning | sim: run the paused checklist | [37] |
| should | MuJoCo 4.0.0 docs, Modeling | Stiffer contacts do not cure a modeling bug. They can add chatter or diverge | review: tuning log names the model check | [39] |
| should | Newton 1.7.0 docs, Simulation Tuning | Rule out initialization, control, model and capacity causes first | review: the report classifies the failure | [4] |
| should | Newton 1.7.0 docs, Simulation Tuning | Physical values first, solver options after | review: solver changes follow the audit | [5] |
| should | Newton 1.7.0 docs, Simulation Tuning | Harder contact is not always more stable. Tune to task metrics, not one penetration number | sim: task metric and jitter across stiffness | [40] |
| should | Newton 1.7.0 docs, Simulation Tuning | Extreme solver settings do not hide model errors. Bad mass ratios and overlaps usually stay unstable | sim: test with defaults after each model fix | [41] |
| should | Isaac Lab 3.0.0 docs, Tune MJWarp | Fixed state, seed and action sequence; one variable at a time | sim: stored script reproduces the failure | [9] |
| should | Isaac Lab 3.0.0 docs, Tune MJWarp | Repair the asset or controller. No solver setting makes an invalid one correct | review: audit done before tuning | [42] |
| should | Isaac Lab 3.0.0 docs, Tune MJWarp | Stop sweeping iterations at the plateau. They cannot fix bad inertia, reset penetration or excess stiffness | sim: sweep one limit, plot the metric | [38] |
| should | Isaac Lab 3.0.0 docs, Troubleshooting | 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 | sim: assert finite state and observations each step in debug runs | [7] |
| should | Isaac Lab 3.0.0 docs, Prepare an Asset for Newton with MJWarp | Newton-only failure: keep the smallest fixed-state reproduction and record the first non-finite quantity | sim: store both | [43] |
| should | MuJoCo 4.0.0 docs, Modeling | High-frequency, low-amplitude vibration: the usual solution is to reduce the timestep and/or add armature to the relevant joints | sim: 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
- Nothing from the Isaac Sim docs host is in the database. The Isaac Sim guidelines come from the repo at tag v6.2.0, mostly from agent-written notes. See chapter 25.
- No guideline gives a general MJWarp recipe like the MuJoCo one above. For PhysX, Isaac Lab states a contact-rich baseline [50]. MJWarp values exist only in shipped tasks (chapter 26), and Isaac Lab says not to copy those as defaults [51].
- SO-101 timestep and contact values exist only in shipped configs: on the typing task, physics dt 0.01 s [52] and a pyramidal cone with
impratio1.0 [53]; on the workshop teleop environment, sim dt 1/120 [54]. The bands above are general MuJoCo guidance.
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.
- 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.”
- 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
- Write physics options explicitly so that a future default change cannot silently alter trajectories. Level: should. mujoco.readthedocs.io 2026-11-08
- 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.”
- 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.”
- This guideline is held back: its source does not allow us to publish it yet.
- 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”
- MuJoCo 4.0.0 lists a breaking engine change to sidesite semantics for tendon wrapping. Level: guide. mujoco.readthedocs.io 2026-11-08
- 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.”
- 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
- 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
- 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
- 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.”
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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.”
- 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.”
- Use the discrete integrator for MuJoCo flex elasticity, because implicit and implicitfast raise an error. Level: must. mujoco.readthedocs.io 2026-11-08
- Recheck the integrator choice at upgrades, because MuJoCo is trialling discrete as a replacement recommendation. Level: guide. mujoco.readthedocs.io 2026-11-08
- If a MuJoCo model vibrates with explicit damping feedback, switch to implicit or implicitfast. Level: should. mujoco.readthedocs.io 2026-11-08
- 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
- 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
- Avoid large impratio values when MuJoCo uses pyramidal cones. Level: should. mujoco.readthedocs.io 2026-11-08
- 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
- 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
- To set stiffness and damping independently in MuJoCo, use the direct negative solref format. Level: should. mujoco.readthedocs.io 2026-11-08
- 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
- 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”
- 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
- 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.”
- 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
- Load the MuJoCo model paused and rule out modeling bugs before tuning parameters. Level: should. mujoco.readthedocs.io 2026-11-08
- 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”
- 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
- 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.”
- 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.”
- 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.”
- 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”
- 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
- 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.”
- 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
- 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.”
- 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”
- 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.”
- 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,”
- 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.”
- 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)”
- 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",”
- The workshop SO-101 teleop environment uses sim dt = 1/120. Level: guide. raw.githubusercontent.com 2026-11-09“self.sim.dt = 1 / 120”