Robot description checklist
What a designer must do
- Run this checklist on every model before you tune anything. A bad model looks like a bad solver [1].
- Block on any
must failure. - Run the static checks on each commit. Run the sim and measure checks when the model or the robot changes.
- Record each waiver with a reason in the model's own documentation [2].
This is the checklist for a robot model. It covers URDF, SDF, MJCF and USD: model format and units, mass and inertia, collision geometry, and joints. Each row is one check, so a linter can report the check, its level, the element and a message.
How to read the checklist
The Kind column comes from the guideline's check field.
How to read the checklist| Kind | Meaning | Needs |
|---|
| lint | model-lint: read or compile the model | The file |
| sim | Load or step the model | A simulator |
| measure | Compare with the robot | The real robot |
| review | A person checks a record | A reviewer |
Each format's source, as the guidelines state it:
How to read the checklist| Format | Spec the guidelines cite | Section |
|---|
| URDF | ROS wiki URDF joint and link specs, unversioned, captured 2026-11-08 | URDF |
| SDF | SDFormat spec 1.12 | SDF |
| MJCF | MuJoCo 4.0.0 docs | MJCF |
| USD | OpenUSD release alias, captured 2026-11-08; Isaac Lab 3.0.0 docs | USD |
| Frames | REP 103, REP 105, REP 120; REP 199 is a draft | Frames |
| CAD export | onshape-to-robot docs, latest alias, no version shown | CAD export |
Units
Units| Level | Kind | Format | Condition | Source |
|---|
| must | lint | URDF, ROS | Length in metres, mass in kilograms, time in seconds, angle in radians. Reject other units | [3] |
| should | review | All | The model README names each departure from REP 103 and its reason | [2] |
| should | lint | MJCF | Gravity, geometry size and density agree with one unit system. Prefer MKS | [4] |
| must | lint | All | Total mass and bounding box match the measured robot. Catches millimetre-for-metre errors | [5] |
| guide | lint | MJCF | compiler/angle is set explicitly. MJCF defaults to degrees; URDF input always reads radians | [6] |
| must | lint | USD | Joint limits equal source limits after radian-to-degree conversion. The schema reads one-dimensional angles in degrees | [7] |
| should | lint | USD | Read metersPerUnit and kilogramsPerUnit from each composed layer. Each can differ | [8] |
Frames
Frames| Level | Kind | Format | Condition | Source |
|---|
| must | lint | All | Each rotation matrix in the frame tree has determinant +1 | [9] |
| should | review | ROS | Body frame: x forward, y left, z up | [10] |
| must | lint | ROS | Each camera has an _optical child frame: z forward, x right, y down | [11] |
| should | review | All | Prefer quaternions or matrices. No Euler field lacks a stated order | [12] |
| must | lint | Mobile | base_link has no movable joint between it and the base body | [13] |
| should | review | Mobile | No long-horizon goal is expressed in odom. It drifts | [14] |
| should | review | Mobile | No local control loop reads pose in map. It can jump | [15] |
| guide | lint | Arm | Flange +X points away from the parent link. Draft REP, treat as a convention | [16] |
| guide | measure | Arm | tool0 matches the controller's all-zeros TCP. Draft REP | [17] |
| guide | lint | Arm | The flange link has no visual or collision child. Draft REP | [18] |
| should | lint | Humanoid | Under REP 120, sole frame Z is normal to the foot contact face | [19] |
URDF
URDF| Level | Kind | Condition | Source |
|---|
| must | lint | Forward kinematics at zero matches CAD joint locations. The joint sits at the child link origin | [20] |
| must | lint | Conversion code reads rpy as fixed-axis roll, pitch, yaw, in radians | [21] |
| should | lint | Each revolute, continuous and prismatic joint has an axis element. Omitted means x | [22] |
| should | lint | Axis vector norm equals one | [23] |
| must | lint | Reject a revolute or prismatic joint with no limit element | [24] |
| must | lint | Each limit holds effort and velocity | [25] |
| guide | lint | On revolute and prismatic joints, lower and upper are set, with lower below upper. Each omitted bound defaults to zero. Omit them for continuous joints | [26] |
| must | lint | No duplicate joint names | [27] |
| guide | lint | Each non-fixed child link has an inertial element. The element is optional; omitted means zero mass and zero inertia | [28] |
| must | lint | Inertia is about the link's center of mass. Recompute from the mesh and compare | [29] |
| should | lint | Each actuated joint has a dynamics element. Damping and friction default to zero | [30] |
CAD export
These rows cover onshape-to-robot, from its docs under the latest alias, with no version shown. See also Format conversion.
CAD export| Level | Kind | Condition | Source |
|---|
| must | review | Exported joint count equals intended degrees of freedom. A mate without the special prefix is ignored | [31] |
| should | review | Export log holds no orphaned-link warning. That link becomes fixed to the base | [32] |
| should | measure | Jog each real joint positive and compare with the model. Use the inv suffix to flip it | [33] |
| should | review | Exported limits match the CAD mates. ignore_limits drops them | [34] |
SDF
SDF| Level | Kind | Condition | Source |
|---|
| guide | lint | Resolve expressed_in on each axis before comparing with CAD. The default is the joint frame | [35] |
| should | review | Metadata names the spec version. It can differ from the libsdformat release | [36] |
| must | lint | Check ixy sign against a point-mass test. The spec uses -m x y | [37] |
| must | lint | Flag negative effort. SDF does not enforce a negative limit | [38] |
MJCF
MJCF| Level | Kind | Condition | Source |
|---|
| must | lint | Compiled world poses match CAD. MJCF poses are local to the parent | [39] |
| must | lint | Names are unique per element type. Code lookups use the exact case | [40] |
| should | review | No literal element index in code that reads model data | [41] |
| guide | lint | No massless moving body. MJCF needs no dummy bodies for sensors | [42] |
| must | lint | Each body has an inertial element, or a geom mass or density chosen for its material. The default assumes water density | [43] |
| must | lint | inertiagrouprange or density=0 excludes either visual or collision geoms from inertia | [44] |
| should | lint | List bodies whose mass came from geom inference | [45] |
| should | sim | Thin 2D or non-watertight meshes set the mesh inertia attribute to shell. Compile and read body mass | [46] |
| must | lint | Principal inertias satisfy A + B >= C in all permutations | [47] |
| guide | lint | balanceinertia is false in the released file. It silently replaces bad inertias with their average | [48] |
| should | review | Correct unrealistic inertias in the CAD or URDF file. Where you cannot edit an imported model, bound mass and inertia when it compiles, with boundmass and boundinertia | [49] |
| guide | lint | boundmass is unset in a finished model | [50] |
| should | lint | The compiler does not set settotalmass. The MuJoCo 4.0.0 docs mark it deprecated | [51] |
| should | lint | Report the largest mass and inertia ratio across each joint and expected contact. Keep it below about 1000:1 | [52] |
| should | lint | Flag links with inertia near 1e-6 and no geometry | [53] |
| must | lint | ctrlrange lies inside joint range, except a gripper that must close past pad contact | [54] |
| should | lint | Each position actuator sets kv or dampratio, and forcerange. The defaults are kv zero and unlimited force | [55] |
| should | lint | Compare armature with link inertia about the joint axis on wrists, fingers and ankles | [56] |
| must | sim | Backlash uses two coaxial hinges with armature on the driven one. Compile and step | [57] |
| should | sim | Light links with force-limited actuators have armature and passive damping. Step the largest command on the lightest link | [58] |
| should | review | Each frictionloss value has a measured stiction reason | [59] |
| must | sim | margin is zero, or paired with a matching gap. Measure the rest height of a known box | [60] |
| must | sim | Mesh collides as its convex hull. Toggle the hull view. A concave part needs a decomposition | [61] |
| should | lint | Report the share of mesh collision geoms. Prefer primitives | [62] |
| should | lint | No high-polygon visual geom has a nonzero contype or conaffinity | [63] |
| should | sim | priority is set on the geom whose contact values must win. Slide test against the measured angle | [64] |
| should | lint | Fingertip, grasp-pad and settling curved-object geoms have condim 4 or 6. Keep 3 elsewhere | [65] |
| should | lint | No near-zero friction under pyramidal cones. Use condim 1 | [66] |
| must | measure | Gripper force times friction well exceeds object weight, before you tune slip | [67] |
| should | lint | The flag element does not disable multiccd or nativeccd | [68] |
| should | sim | Load paused and count contacts at the initial state | [69] |
| must | sim | Speculative contacts only on supported geometry. Not height fields, SDFs or flexes | [70] |
| should | sim | Rerun the tunneling regression after each MuJoCo upgrade. The docs say the behaviour may still change | [71] |
USD and Isaac Lab
USD and Isaac Lab| Level | Kind | Condition | Source |
|---|
| must | review | Record articulation root, fixed-base form, joint merging, joint types, axes and limits against the source robot | [72] |
| should | lint | List all per-body gravity overrides and justify each | [73] |
| must | sim | Load the asset and fail on any placeholder inertia warning | [74] |
| should | lint | Report bodies that author both mass and density. Mass wins | [75] |
| must | review | Each armature value has a physical source or a response test. It is not a patch for bad mass, units or resets | [76] |
| must | sim | Compare collision and visual views per link. Visual parity is not collision parity | [77] |
| must | sim | Run the overlap check across the full reset distribution | [78] |
| must | sim | Size nconmax and njmax separately from a measured worst case, plus task-specific headroom | [79] |
| should | review | Each capacity change cites an overflow in the diagnostics | [80] |
| should | sim | Run once with actuator_value_resolution_debug_print on. A config override replaces the USD value per joint and property | [81] |
| should | lint | Fail when all joints share one effort value on a robot with mixed actuators | [82] |
| must | lint | Mimic followers have zero stiffness and damping on multi-backend assets | [83] |
| should | review | The actuator model is the simplest that meets the requirements | [84] |
| guide | sim | Use DCMotor where the model needs a four-quadrant torque-speed envelope, not a fixed effort clip. Compare torque against the motor curve at peak speed | [85] |
| should | sim | Log the share of time that targets sit at a joint limit | [86] |
| must | sim | Command past the limit under MJWarp and record the speed. MJWarp drops joint_velocity_limit | [87] |
| must | review | Hardware speed limits live on the robot controller, not only in simulation config | [88] |
| should | review | actuator_velocity_limit and joint_velocity_limit are both set on purpose per joint | [89] |
| should | sim | Retune damping after increasing armature, then rerun the step response | [90] |
PhysX and Newton
PhysX and Newton| Level | Kind | Doc | Condition | Source |
|---|
| must | sim | PhysX SDK 5.8.0 | Step once from the reset state. Fail on any contact not intended. Overlapping bodies may explode, so limit the de-penetration velocity | [91] |
| should | sim | Omni Physics guide | List contact pairs at rest. Filter by pair, not all self-collision | [92] |
| guide | sim | Omni Physics guide | Compare stability with self-collision on and off, as a diagnostic only | [93] |
| should | sim | Omni Physics guide | Inspect link masses and inertias in OmniPVD. Avoid large ratios | [94] |
| must | lint | Newton 1.7.0 | Mass above zero and inertia positive definite for each dynamic body | [95] |
| should | lint | Newton 1.7.0 | No zero-mass body is used as a fixed support. Use is_kinematic | [96] |
| should | lint | Newton 1.7.0 | Measured links carry lock_inertia=True | [97] |
| should | sim | Newton 1.7.0 | Build with validate_inertia_detailed on. Fail on any corrected body | [98] |
| must | lint | Omni Physics guide | Compute sqrt(stiffness/inertia) * dt per drive. Avoid values much greater than 1 | [99] |
| guide | lint | Omni Physics guide | Report damping / (2 * sqrt(stiffness * inertia)) with the smallest relevant inertia | [100] |
| should | sim | Omni Physics guide | Add feed-forward such as gravity compensation before very high stiffness | [101] |
| should | sim | Omni Physics guide | Apply a step target and log peak joint force. Bound it with a force limit or a rate limiter | [102] |
| should | lint | Omni Physics guide | Each joint effort limit matches the cited datasheet value | [103] |
| should | lint | Omni Physics guide | Armature equals rotor inertia times ratio squared | [104] |
| guide | sim | Omni Physics guide | Test a stiff grasp with and without mimic compliance | [105] |
| guide | sim | Omni Physics guide | For RL, consider a generous 200-300 deg/s limit on revolute joints. Count unstable resets | [106] |
Real parts and the SO-101
The first row compares the model with the built robot. No file check can replace it. The second is specific to the SO-101.
Real parts and the SO-101| Level | Kind | Condition | Source |
|---|
| guide | measure | Weigh each removable link and compare with the model. CAD mass is not a measurement | [107] |
| guide | lint | Leader model armature differs by joint gear ratio. The SO-101 leader uses several gear ratios; the follower uses 1/345 gearing | [108] |
Worked example: SO-101
The database holds SO-ARM101 limits from the upstream MJCF. The source marks them as simulation model values, not a maker datasheet.
Worked example: SO-101| Joint | Range (rad) | Actuator force range (N·m) |
|---|
shoulder_pan | -1.91986 to 1.91986 | -2.94 to 2.94 |
shoulder_lift | -1.7453293 to 1.7453293 | -2.94 to 2.94 |
elbow_flex | -1.69 to 1.69 | -2.94 to 2.94 |
wrist_flex | -1.658063 to 1.658063 | -2.94 to 2.94 |
wrist_roll | -2.7438473 to 2.8412063 | -2.94 to 2.94 |
gripper | -0.174533 to 1.7453292 | -2.94 to 2.94 |
Compare this with the 12 V servo. These are reviews of database values. Nobody ran a linter on the files.
- The force range is the stall figure. ±2.94 N·m equals the 30 kg.cm stall torque that the project README gives for the 12 V STS3215-C018. Its rated torque is lower; take it from the maker's sheet. As a maximum output limit, that meets the guideline to set each joint's maximum force from the actuator specification [103]. But stall torque is a momentary maximum [109], so size duty against the rated value [110].
- The SO-ARM100 URDF fails the effort check. The SO-ARM100 URDF in the database sets
effort="35" and velocity="1" on shoulder_pan, shoulder_lift, elbow_flex and wrist_flex. One oversized value across the robot is what the per-joint effort guideline rejects [82]. This is the SO-ARM100 file, not the SO-101 file. - The armature check cannot run from a datasheet. The geared-armature guideline needs rotor inertia [104]. The database has the gear ratio but no STS3215 rotor inertia. Fit armature from logs [111].
- Base mass needs a scale. The SO-ARM101 MJCF gives 0.147 kg for the base body. Only the base mass of the SO-101 model is in the database. Masses and inertias taken from CAD are not measured values [107], so weigh the parts.
Where the database is thin
models has no USD row for any robot, so the USD section has no worked example.- Isaac Sim guidelines come from the Isaac Sim repo notes. The docs-site guidelines stay held. See Isaac Sim and Isaac Lab.
- No guideline gives USD-specific collision approximation settings. The nearest is the URDF importer's default collision type, Convex Hull [112].
- Drive defaults are partly covered. USD drive gains on actuated joints are zeroed automatically [113], a gain set to None keeps the USD value [114], and the importer has stated presets [115], [116].
- The database does not hold SO-101 link masses beyond the base, or its URDF limit values.
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.
- Load the MuJoCo model paused and rule out modeling bugs before tuning parameters. Level: should. mujoco.readthedocs.io 2026-11-08
- Write down the reason for any departure from the REP 103 units or axes in the model's own documentation. Level: should. ros.org 2026-11-08“choosing different conventions should be well justified and well documented.”
- In a ROS-facing model, state length in metres, mass in kilograms, time in seconds and angle in radians. Level: must. ros.org 2026-11-08“We have chosen to standardize on SI units.”
- MuJoCo fixes no unit system, so choose one consistent system for each MJCF file, and prefer MKS because the engine's defaults assume it. Level: should. mujoco.readthedocs.io 2026-11-08
- Before any tuning, check mesh scale and total mass to catch a millimetre-for-metre mistake. Level: must. mujoco.readthedocs.io 2026-11-08
- MJCF angles default to degrees, while URDF input is always parsed as radians. Level: guide. mujoco.readthedocs.io 2026-11-08
- In USD physics, convert radian limits and angular values to degrees, because the schema reads one-dimensional angles in degrees. Level: must. openusd.org 2026-11-08
- Check the unit metadata of every USD file composed into a robot stage, because each referenced file can carry different units. Level: should. openusd.org 2026-11-08
- Every frame must be right handed. Level: must. ros.org 2026-11-08“All systems are right handed.”
- Align a ROS robot body frame with x forward, y left and z up. Level: should. ros.org 2026-11-08“x forward y left z up”
- Give a camera a second frame with the _optical suffix, with z forward, x right and y down. Level: must. ros.org 2026-11-08“z forward x right y down”
- Store rotations as quaternions or matrices where you can, and name the convention whenever Euler angles appear. Level: should. ros.org 2026-11-08“Euler angles are generally discouraged due to having 24 'valid' conventions”
- Attach base_link rigidly to the mobile base; do not place it on a moving part. Level: must. ros.org 2026-11-08“The coordinate frame called base_link is rigidly attached to the mobile robot base.”
- Do not use the odom frame as a long-term reference, because it drifts. Level: should. ros.org 2026-11-08“drift makes it a poor frame for long-term reference.”
- Do not use the map frame for local sensing and acting, because its pose can jump. Level: should. ros.org 2026-11-08“discrete jumps in position estimators make it a poor reference frame for local sensing and acting.”
- On a serial arm, point flange +X away from the last link. This comes from a draft REP, so treat it as a convention, not a settled standard. Level: guide. gavanderhoorn.github.io 2026-11-08“Positive X (x+) must always point away from the last link”
- Make tool0 equal the controller's all-zeros TCP. This comes from a draft REP. Level: guide. gavanderhoorn.github.io 2026-11-08“shall match exactly an all-zeros TCP as defined by the robot controller.”
- Keep geometry off the flange frame so end effectors attach cleanly. This comes from a draft REP. Level: guide. gavanderhoorn.github.io 2026-11-08“flange shall not have any geometry associated with it.”
- On a humanoid using REP 120, make the sole frame's XY plane coplanar with the contact surface. Level: should. ros.org 2026-11-08“frame must be coplanar with the support body contact surface.”
- Author a URDF joint origin as the parent-to-child transform; the joint sits at the child link origin. Level: must. wiki.ros.org 2026-11-08“The joint is located at the origin of the child link”
- Read URDF rpy as fixed-axis rotations in radians: roll about x, then pitch about y, then yaw about z. Level: must. wiki.ros.org 2026-11-08“first roll around x, then pitch around y and finally yaw around z. All angles are specified in radians.”
- Write the axis on every moving URDF joint, because an omitted axis silently becomes the x axis. Level: should. wiki.ros.org 2026-11-08“<axis> (optional: defaults to (1,0,0))”
- Normalize every URDF joint axis. Level: should. wiki.ros.org 2026-11-08“The vector should be normalized.”
- Every revolute and prismatic URDF joint needs a limit element. Level: must. wiki.ros.org 2026-11-08“<limit> (required only for revolute and prismatic joint)”
- Every URDF limit element needs both effort and velocity values. Level: must. wiki.ros.org 2026-11-08“velocity (required)”
- URDF lower and upper bounds each default to zero when omitted; omit them for continuous joints. Level: guide. wiki.ros.org 2026-11-08“lower (optional, defaults to 0)”
- Give each URDF joint a unique name. Level: must. wiki.ros.org 2026-11-08“Specifies a unique name of the joint”
- A URDF link's inertial element is optional; if left out, it defaults to zero mass and zero inertia. Level: guide. wiki.ros.org 2026-11-08“<inertial> (optional: defaults to a zero mass and zero inertia if not specified)”
- Author URDF inertia about the link's center of mass, not about the link origin. Level: must. wiki.ros.org 2026-11-08“about Co (the link’s center of mass)”
- Write URDF dynamics values on purpose, because damping and friction default to zero, in units that depend on the joint type. Level: should. wiki.ros.org 2026-11-08“damping (optional, defaults to 0)”
- When exporting with onshape-to-robot, name every kinematic mate with its special prefix, because other mates are ignored. Level: must. onshape-to-robot.readthedocs.io 2026-11-08
- Treat an orphaned-link warning from onshape-to-robot as an error to resolve, because that link becomes fixed to the base. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Verify each exported joint direction; use the onshape-to-robot inv suffix when a joint must turn opposite to the CAD mate. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Set the ignore_limits export option only on purpose, because it drops the CAD joint limits from the model. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- An SDF joint axis uses the joint frame unless expressed_in names another frame. Level: guide. sdformat.org 2026-11-08“The axis is expressed in the joint frame unless a different frame is expressed in the expressed_in attribute.”
- Record the SDF specification version apart from the libsdformat release, because the two numbers can differ. Level: should. sdformat.org 2026-11-08“This version number may be different from the release version of libsdformat”
- Check the sign of products of inertia when moving data into SDF, because the spec uses the -m x y convention. Level: must. sdformat.org 2026-11-08“the product of inertia convention -m x y (not +m x y) is used”
- Do not write a negative SDF effort value unless you want no limit, because SDF then does not enforce it. Level: must. sdformat.org 2026-11-08“Limit is not enforced if value is negative.”
- Treat MJCF positions and orientations as local to the parent, not as world values. Level: must. mujoco.readthedocs.io 2026-11-08
- Keep MJCF names unique within each element type, and treat them as case-sensitive. Level: must. mujoco.readthedocs.io 2026-11-08
- Look up MuJoCo elements by name in control and test code, not by a hard-coded index. Level: should. mujoco.readthedocs.io 2026-11-08
- Native MJCF sensors do not require massless dummy mounting bodies. Level: guide. mujoco.readthedocs.io 2026-11-08
- Do not rely on inferred mass for hollow printed shells or dense metal links, because MuJoCo assumes water density. Level: must. mujoco.readthedocs.io 2026-11-08
- When inferring inertia from geoms, count either visual or collision geoms, not both. Level: must. mujoco.readthedocs.io 2026-11-08
- Check whether each MJCF body has an inertial element, because the auto setting infers mass from geoms only when it is missing. Level: should. mujoco.readthedocs.io 2026-11-08
- For thin 2D or non-watertight meshes, set mesh inertia to shell so compile-time volume computation does not fail. Level: should. mujoco.readthedocs.io 2026-11-08
- Each body's principal inertias must satisfy A+B>=C in all permutations, or MuJoCo rejects the model. Level: must. mujoco.readthedocs.io 2026-11-08
- With MuJoCo balanceinertia enabled, invalid principal inertias are silently replaced by their average. Level: guide. mujoco.readthedocs.io 2026-11-08
- This guideline is held back: its source does not allow us to publish it yet.
- Treat boundmass as a quick fix for massless moving bodies, and not as a modeling method. Level: guide. mujoco.readthedocs.io 2026-11-08
- Do not build on compiler settotalmass in MuJoCo 4.0.0, because the docs mark it as deprecated. Level: should. mujoco.readthedocs.io 2026-11-08
- Keep mass and inertia ratios across contacts and joints below about 1000:1, or expect worse MuJoCo solver accuracy. 1000 ratio Level: should. mujoco.readthedocs.io 2026-11-08
- This guideline is held back: its source does not allow us to publish it yet.
- Keep position command ranges inside joint ranges, except for a gripper that must close past pad contact. Level: must. mujoco.readthedocs.io 2026-11-08
- Set damping and a force bound on every MuJoCo position actuator, because kv defaults to zero and force is unlimited. Level: should. mujoco.readthedocs.io 2026-11-08
- Add realistic armature on wrists, fingers and ankles, because reflected rotor inertia often exceeds their link inertia. Level: should. mujoco.readthedocs.io 2026-11-08
- Model MuJoCo backlash with two coaxial hinges, and put armature on the driven one, or the joint-space inertia matrix is singular. Level: must. mujoco.readthedocs.io 2026-11-08
- Add armature and passive damping on light links with force-limited MuJoCo actuators, because saturation removes implicit damping. Level: should. mujoco.readthedocs.io 2026-11-08
- Use MuJoCo frictionloss only where Coulomb stiction matters, because each joint adds a constraint row; use damping otherwise. Level: should. mujoco.readthedocs.io 2026-11-08
- Leave MuJoCo margin at zero unless you pair it with a matching gap, or objects hover by margin minus gap. Level: must. mujoco.readthedocs.io 2026-11-08
- Assume a MuJoCo mesh collides as its convex hull; a concave part needs a decomposition. Level: must. mujoco.readthedocs.io 2026-11-08
- Prefer primitives to meshes for collision in MuJoCo, because they improve both speed and contact normals. Level: should. mujoco.readthedocs.io 2026-11-08
- Put MuJoCo visual meshes in a default class with contype and conaffinity at zero, so that they do not collide. Level: should. mujoco.readthedocs.io 2026-11-08
- Set MuJoCo priority on the geom whose contact parameters must win, because equal-priority geoms take the larger friction. Level: should. mujoco.readthedocs.io 2026-11-08
- Use condim 4 or 6 on MuJoCo fingertips, grasp pads and curved objects that should settle rather than roll indefinitely; keep 3 elsewhere. Level: should. mujoco.readthedocs.io 2026-11-08
- For a frictionless MuJoCo contact use condim 1, not near-zero friction, which ill-conditions pyramidal cones. Level: should. mujoco.readthedocs.io 2026-11-08
- Ensure that maximum gripper force times sliding friction well exceeds the object's weight before you tune slip in MuJoCo. Level: must. mujoco.readthedocs.io 2026-11-08
- For flat contacts, keep multiccd enabled; keep nativeccd enabled for accurate, efficient convex collision detection. Level: should. mujoco.readthedocs.io 2026-11-08
- Load a MuJoCo model paused and check for intersecting geoms before you tune contacts. Level: should. mujoco.readthedocs.io 2026-11-08
- This guideline is held back: its source does not allow us to publish it yet.
- Recheck speculative-contact behaviour when you upgrade MuJoCo, because the docs call the feature new and subject to change. Level: should. mujoco.readthedocs.io 2026-11-08
- Before simulating a new USD asset, verify its articulation root, fixed-base form, joint merging, joint types, axes and limits. Level: must. isaac-sim.github.io 2026-11-08“Verify the articulation root, fixed-base representation, fixed-joint merging, nested rigid bodies, joint types, axes, and limits.”
- Set each per-body gravity override on purpose, because a stale override can make a task differ from scene gravity. Level: should. isaac-sim.github.io 2026-11-08“A stale override can make a task differ from scene gravity.”
- An importer warning about placeholder inertia means the model is wrong; fix it before any further work. Level: must. isaac-sim.github.io 2026-11-08“Treat a placeholder inertia warning as a modeling failure”
- In USD, remember that an authored mass overrides density, so a density edit has no effect on a body with explicit mass. Level: should. openusd.org 2026-11-08
- Armature is a physical term; do not use it as a patch for wrong mass, inertia, units or a penetrating reset. Level: must. isaac-sim.github.io 2026-11-08“do not use it to hide bad body mass, inertia, units, reset penetration, or contact capacity.”
- Apply a collision API only to geometry that you intend to collide, and do not treat a good visual match as proof of collision correctness. Level: must. isaac-sim.github.io 2026-11-08“visual parity is not collision parity.”
- Reject resets with robot-object or robot-support penetration before the first physics step. Level: must. isaac-sim.github.io 2026-11-08“Reject robot-object and robot-support penetration, impossible mimic states, and invalid randomized geometry before the first physics step.”
- Size MJWarp nconmax and njmax separately from the measured worst case plus task-specific headroom; do not derive njmax from nconmax. Level: must. isaac-sim.github.io 2026-11-08“Do not derive njmax directly from nconmax.”
- Do not raise capacity to repair bad collision geometry, material or convergence, because it cannot fix them. Level: should. isaac-sim.github.io 2026-11-08“Capacity cannot fix incorrect collision geometry, contact material, or convergence.”
- Print the resolved Isaac Lab actuator values, because a config override replaces the USD value per joint and per property. Level: should. isaac-sim.github.io 2026-11-08“actuator_value_resolution_debug_print”
- Derive each joint's effort limit from its own motor and gearbox; a single large value across the robot is not acceptable. Level: should. isaac-sim.github.io 2026-11-08“choosing both from the motor and gearbox rather than using one oversized value for the whole robot.”
- With Newton and PhysX on one asset, drive only the mimic leader; give the follower zero stiffness and damping. Level: must. isaac-sim.github.io 2026-11-08“Zero stiffness and damping are what disable the second PD drive.”
- Choose the simplest actuator model that meets your requirements. Level: should. isaac-sim.github.io 2026-11-08“Choose the simplest model that meets your requirements.”
- Use DCMotor when the actuator model needs a four-quadrant torque-speed envelope rather than a fixed effort clip. Level: guide. isaac-sim.github.io 2026-11-08“Same PD torque, clipped to a four-quadrant torque-speed envelope.”
- During policy transfer, stop targets short of the hard limits of each joint. Level: should. isaac-sim.github.io 2026-11-08“keep targets away from hard joint stops”
- Do not count on joint_velocity_limit under MJWarp, because MJWarp drops it; bound speed in task or control logic. Level: must. isaac-sim.github.io 2026-11-08“MJWarp drops that field, while Kamino honors it.”
- Do not treat Isaac Lab joint_velocity_limit as a safety clamp, because its enforcement depends on the backend. Level: must. isaac-sim.github.io 2026-11-08“is not a backend-independent safety clamp”
- Keep the physical actuator_velocity_limit distinct from the solver joint_velocity_limit when you transfer a policy. Level: should. isaac-sim.github.io 2026-11-08“distinguish the physical actuator_velocity_limit from the solver joint_velocity_limit”
- Retune damping after increasing armature, because the effective natural frequency and damping ratio change. Level: should. isaac-sim.github.io 2026-11-08“Retune damping after increasing armature because the effective natural frequency and damping ratio change.”
- PhysX rigid bodies created overlapping may explode, because the SDK resolves penetration in one step; limit the de-penetration velocity. Level: must. nvidia-omniverse.github.io 2026-11-08
- Filter unintended contact between non-adjacent PhysX links by pair, instead of turning off all self-collision. Level: should. docs.omniverse.nvidia.com 2026-11-08
- To diagnose unexplained instability, disable self-collision once as a test, and then find the offending pair. Level: guide. docs.omniverse.nvidia.com 2026-11-08
- In PhysX articulations, avoid large mass and inertia ratios, because an impulse can give a light body very large velocity. Level: should. docs.omniverse.nvidia.com 2026-11-08
- Give each dynamic body positive mass and a physically meaningful inertia tensor. Level: must. newton-physics.github.io 2026-11-08“Every dynamic rigid body in Newton needs positive mass and a physically meaningful inertia tensor for stable simulation.”
- In Newton, make a body immovable with is_kinematic, not with zero mass. Level: should. newton-physics.github.io 2026-11-08“do not rely on zero mass to make a body immovable.”
- In Newton, set lock_inertia=True on bodies with measured mass properties, so that later shapes cannot change them. Level: should. newton-physics.github.io 2026-11-08“Use lock_inertia=True to protect hand-specified mass properties from subsequent shape additions.”
- During Newton model development, turn on validate_inertia_detailed and read the per-body corrections. Level: should. newton-physics.github.io 2026-11-08“to get per-body warnings for any mass or inertia values that were corrected.”
- Avoid drive gains where natural frequency times timestep is much greater than 1, mainly on mimic and gripping joints. 1 dimensionless Level: must. docs.omniverse.nvidia.com 2026-11-08
- Estimate angular drive damping ratio as damping over 2 sqrt(stiffness times inertia), with the smallest relevant inertia. Level: guide. docs.omniverse.nvidia.com 2026-11-08
- Improve position tracking with feed-forward such as gravity compensation before raising stiffness to very high values. Level: should. docs.omniverse.nvidia.com 2026-11-08
- Bound large drive forces with a force limit or a rate limiter on drive targets. Level: should. docs.omniverse.nvidia.com 2026-11-08
- Set each simulated joint's maximum force from the actuator specification when one exists. Level: should. docs.omniverse.nvidia.com 2026-11-08
- Set armature for a geared actuator from rotor inertia and ratio, as J times G squared, where G is motor speed over output speed. Level: should. docs.omniverse.nvidia.com 2026-11-08
- Add compliance to mimic joints in PhysX when they compete with contacts and stiff drives. Level: guide. docs.omniverse.nvidia.com 2026-11-08
- For PhysX RL training, consider a generous maximum joint velocity of 200-300 deg/s on revolute joints to reduce early instability. 200-300 deg/second Level: guide. docs.omniverse.nvidia.com 2026-11-08
- This guideline is held back: its source does not allow us to publish it yet.
- The SO-101 leader uses several gear ratios, while the follower uses 1/345 gearing. Level: guide. huggingface.co 2026-11-08
- A servo's stall torque is its maximum momentary output and differs from its continuous rating. Real-world output is generally closer to the performance-graph measurements. Level: guide. emanual.robotis.com 2026-11-08
- In continuous operation keep motor torque below the thermally set continuous limit, not the peak or stall value. Level: must. hades.mech.northwestern.edu 2026-11-08
- Fit armature, damping, friction, gains, inertia and delay to hardware logs with optimization, rather than hand-tuning, when matching a specific robot in MuJoCo. Level: should. mujoco.readthedocs.io 2026-11-08
- The URDF importer's default collision_type is Convex Hull. Level: guide. raw.githubusercontent.com 2026-11-09
- USD drive gains on actuated joints are zeroed automatically so the implicit drive does not fight the actuator; joints without an actuator keep their drive gains. Level: must. raw.githubusercontent.com 2026-11-09
- Zero-gain USD drives select effort mode in ImplicitActuatorCfg; a gain set to None keeps the USD value, so pick each on purpose. Level: guide. raw.githubusercontent.com 2026-11-09“A gain set to ``None`` keeps”
- The stated preset for position-controlled teleoperation is a position drive with stiffness 800 and damping 40. Level: guide. raw.githubusercontent.com 2026-11-09
- The stated preset for an RL agent that commands torques is drive type none with stiffness and damping 0. Level: guide. raw.githubusercontent.com 2026-11-09