Gain Tuner Extension

The Gain Tuner tunes the drive gains of a selected robot articulation and validates them with a suite of tests. Use it when importing a new robot or when fine-tuning the gains of an existing one. It reads and edits gains from whichever backend authors them — PhysX UsdPhysics.DriveAPI drives, MuJoCo (mjc:*) actuator parameters, and Newton actuator schemas — and adapts its fields, columns, and save targets to the active physics engine.

This extension is enabled by default. If it is ever disabled, re-enable both isaacsim.robot_setup.gain_tuner and isaacsim.robot_setup.gain_tuner.ui from the Extension Manager. To open it, go to Tools > Robotics > Asset Editors > Gain Tuner. Robots on the stage that have the Robot Schema applied automatically appear in the Robot dropdown in the window header. If the selected robot has no Robot Schema, the panel shows an ADD ROBOT SCHEMA button that applies the schema in place.

The window has two tabs: Gain Settings, where you inspect and edit per-joint gains, and Test Gains, where you configure and run the validation tests and review their results. A read-only Backend and Solver tag in the header names the physics engine and solver currently active; the Gain Tuner reports these but does not change them.

For a hands-on walkthrough that uses the UR10 manipulator, see the Tutorial 11: Tuning Joint Drive Gains tutorial.

Overview

The purpose of the Gain Tuner is to find the drive gains for each robot joint so that the robot is able to follow commanded trajectories according to the robot’s expected behavior.

The Gain Tuner offers a table for editing gains manually and a suite of tests for assessing their quality.

• Gain Settings: A single continuous table that lists every tunable joint as one row. Edit stiffness and damping (or Kp/Kd/Ki, depending on the joint’s backend) directly in the table, multi-select rows to edit many joints at once, and open a per-joint detail panel for advanced parameters. See The Gain Settings Page.

• Test Gains: A suite of tests for evaluating joint behavior:

  • Snap to Limits — commands joints to their lower and upper limits to verify they can reach their full range of motion.

  • Sinusoidal — drives joints with continuous sinusoidal trajectories.

  • Step Function — drives joints with step-function trajectories.

  • Stress — drives joints with extreme random commands to surface instabilities that can appear during reinforcement learning training.

  • dt Sweep — runs each joint’s step response across a range of physics timesteps to characterize how its position-control accuracy degrades as the timestep grows.

• Test Results: Per-joint and all-joints results tables with a scene-level verdict banner, above plots of the tracked joint positions (and efforts, when the active backend reports measured joint forces) compared against the commanded trajectory.

Understanding Joint Drives

Joint Drives are dual-proportional controllers used to set a joint to a given target. One proportional gain is moderating the error in position, while the other gain is moderating the error in velocity. For historical reasons, these gains are called Stiffness and Damping, respectively.

Note

These Joint drives are implicit - meaning the position and velocity constraints are imposed by the drive with respect to the current time-step. In engineering this is typically done where it uses a closed loop control with readings of the previous time-step of position and velocity and reacting to it for future control. Refer to Articulation Joint Drives.

Stiffness is similar to a spring stiffness constant multiplying the error in position, as if the spring was stretched by that amount. Damping comes from the effect of targeting zero velocity and therefore any movement would result in a reaction that attempts to stop it. You can actually have it track a velocity that is different than zero and the effect is the same as stiffness would be in position.

\[\tau = \text{stiffness} * (q - q_{\text{target}}) + \text{damping} * (\dot{q} - \dot{q}_{\text{target}})\]

where \(q\) and \(\dot{q}\) are the joint position and velocity, respectively. When \(\dot{q}_{target} = 0\), the system reduces to a conventional PD controller on the joint position.

This formula applies for both revolute and prismatic joints.

The joint max force will act as a clamp for \(\tau\), and finally, the drive type will dictate if the effort will be applied directly as a torque or force, or if it will be converted into an acceleration applied to the bodies connected to the joint. An Acceleration drive is normalized by the joint’s mass, so it is invariant to the robot’s configuration and behaves as an ideal actuator.

Drive Modes

This dual-proportional controller provides two main ways to control the robot:

• Position target - used for controlled joints that are driven by defining a target distance/angle that the connected bodies should be.

• Velocity target - usually done for wheels or other free-spinning objects.

To have a position-controlled joint: set Stiffness to something greater than zero and Damping can be any value. To have a velocity-controlled joint: set Stiffness to zero and Damping to any value greater than zero.

The Gain Settings Page

The Gain Settings tab holds one collapsible Gains Settings section: a single continuous table with a joint list on the left and a per-joint detail panel below it. Every tunable joint appears as one row, showing an index, the joint name, and the gain and advanced columns. Mimic joints are constraint-driven rather than independently tunable, so they do not appear as rows.

Editing gains in the table

• Direct editing. Edit a joint’s gain by typing a new value into its cell in the table.

• Multi-select mass editing. Select multiple rows with Ctrl-click (toggle a row) or Shift-click (select a range), then edit a gain cell to apply the new value to every selected, editable joint in that column at once. Read-only and inapplicable cells are skipped. With a single row selected, the edit applies only to that joint.

• Search. A search field filters the rows by joint name.

Dynamic columns

The columns shown adapt to the selected robot rather than following a fixed catalog:

• Stiffness / Damping (labeled Kp / Kd for a Newton actuator) are always present, and a Ki column appears when a joint uses a PID Newton actuator.

• Advanced columns (Armature, Max Force, Max Joint Velocity, Joint Friction) appear automatically when at least one shown joint has a value to show in them, and hide when none do. Armature and Joint Friction resolve a value from any joint that carries one of the backing joint schemas, because the active engine’s own default stands in for an unauthored parameter and is marked (default). Max Joint Velocity appears only once a shown joint authors a finite limit, since an unclamped joint reads unlimited rather than a number, and Max Force appears only for a joint that authors an explicit drive force limit. A cell with nothing to state renders as - and is uneditable. See Advanced actuator parameters.

• Units appear in the stiffness and damping column headers and in each cell’s tooltip. Revolute (angular) joints read in degrees under PhysX and radians under the Newton backend; prismatic joints use the stage’s linear unit. A mixed angular/linear selection is labeled mixed.

• The hamburger column picker on the toolbar chooses which columns are shown. It is populated dynamically from the loaded articulation, listing only the categories and columns that apply to the shown joints, so a pure UsdPhysics.DriveAPI asset shows no MuJoCo or Ki entries. Each column starts from the schema-driven default; toggling a checkbox forces that column on or off.

Note

If you do not see all available columns in the table, widen the Gain Tuner panel or the Isaac Sim application window, or enable the column from the hamburger picker. Some columns are hidden when the window is too narrow.

Joint detail panel

Selecting a single row focuses that joint and builds a compact detail editor below the table. It contains the Controller Gains form (labeled and unit-annotated from the joint’s active gain source), the collapsible Advanced Actuator Parameters section described in Advanced actuator parameters, and a validation summary. The detail panel appears only for a single selection.

When a joint authors more than one gain source, the detail panel shows a per-joint Source toggle, and the table shows a matching Source column; the two stay in sync. The toggle lets you view the gains from each backend that authors them (PhysicsDriveAPI / MuJoCo-native / Newton Actuator), with the active one tagged (Active). Switching the source is an inspection-and-comparison view only — just the active source is editable.

Physics Backends and Gain Sources

The Gain Tuner works across multiple physics backends and multiple gain sources on the same robot. It detects both automatically and adapts its fields, columns, editability, and save targets to whatever is active.

Physics backends and solvers

The Gain Tuner detects the physics engine and solver Isaac Sim currently has active and shows them as read-only Backend and Solver tags in the window header:

• PhysX — the classic backend. It has no separately named solver, so the tag reads PhysX.

• Newton with the MuJoCo solver — the Newton backend running the MuJoCo solver, reported as Newton in the backend tag and MuJoCo in the solver tag.

The Gain Tuner only reports the backend and solver; it never changes them. It reads whatever gains each backend authors and dynamically relabels the gain parameters to match the active source — Stiffness / Damping for a PhysX DriveAPI drive versus Kp / Kd (plus Ki) for a Newton actuator. If you switch the physics backend or the Newton solver while the Gain Tuner is open, it re-detects the change, updates the Backend/Solver tags, and rebuilds the Gain Settings view so the parameter labels and the editable-versus-read-only state stay correct for the newly active backend.

Gain sources on a joint

A single joint may carry more than one gain source. The Gain Tuner reads all of them and lets you choose which one is active per joint:

• PhysX ``UsdPhysics.DriveAPI`` — the standard stiffness/damping drive gains, consumed by the active physics backend unless a Newton actuator is driving the joint.

• MuJoCo (``mjc:*``) — MuJoCo-native actuator parameters carried on the asset for sim-to-sim work.

• Newton actuator schemas — a NewtonActuator prim applying NewtonPDControlAPI or NewtonPIDControlAPI with newton:kp / newton:kd / newton:ki, linked to the single DOF it drives.

When a joint authors more than one source, the table shows a Source column and the detail panel shows a matching per-joint Source selector; the two stay in sync. Selecting a source shows that backend’s gains, with the active one tagged (Active):

• Which source is active. A Newton actuator is backend-independent: while it drives a joint, its Kp/Kd/Ki are the active source regardless of the selected backend. MuJoCo (mjc:*) gains are the active source only when the Newton MuJoCo solver is running and no Newton actuator drives the joint; otherwise the PhysX DriveAPI drive is active.

• Editable versus read-only. Only the active source is editable and testable. The other sources are shown read-only for inspection and comparison — in particular, mjc:* gains are editable and testable only under the Newton MuJoCo solver and are read-only otherwise.

• Test routing. Test commands are always routed to the active source: position/velocity targets drive the joint through whichever of DriveAPI, the MuJoCo solver, or the Newton actuator is currently active for that joint.

For editable PhysX DriveAPI gains, the detail editor also offers a natural-frequency tuning mode. See Tuning Gains.

Advanced actuator parameters

The Advanced Actuator Parameters section of the joint detail panel exposes the per-joint settings that are not drive gains: Armature, Max Drive Force, Max Joint Velocity, and Joint Friction. For a joint driven by a Newton actuator the section instead shows that actuator’s control-range, force-limit, saturation, and anti-windup values, read-only. The section does not expose the drive type. The Gain Tuner reads it only to convert between gains and natural frequency; to change it, edit the joint’s UsdPhysics.DriveAPI drive in the Properties panel.

Armature, Max Joint Velocity, and Joint Friction are authored per backend, on the joint schema the running engine consumes:

• Under Newton the panel reads and writes newton:armature, newton:velocityLimit, and newton:friction.

• Under PhysX it reads and writes physxJoint:armature, physxJoint:maxJointVelocity, and physxJoint:jointFriction.

An edit authors only the active backend’s schema and leaves the other backend’s value untouched. Two different values are a deliberate authoring choice rather than a fault: the two formulations need separate tuning, and PhysX’s dimensionless jointFriction coefficient does not convert to Newton’s load-independent newton:friction effort at all. Where the two disagree, the line under the field states each backend’s value, which one is in effect, and which schema an edit will author. The same text is available as the tooltip of the matching table cell.

Under PhysX there is no chain: only physxJoint:* is read. Under Newton the value in effect is the first authored value in the order the running solver resolves — newton:*, then mjc:* under the MuJoCo solver, then physxJoint:*. A joint that authors only the PhysX half is therefore simulated from it until you edit the field, which moves the value onto newton:*. Two exceptions follow from Newton’s own resolvers: joint friction has no physxJoint:* fallback, so a friction value authored only for PhysX is simulated by nothing under Newton, and mjc:* never takes part in resolving the velocity limit. The panel names an authored value that the active backend never reads whenever that value differs from the one in effect. It reads mjc:* for reporting but never writes it.

Because newton:* leads under every solver, a value authored there is in effect whichever solver is running. Only when nothing is authored that far does the answer depend on the solver, so a joint whose mjc:* and physxJoint:* halves disagree reads blank until the Solver tag names a solver, and the panel says the value cannot be determined rather than guessing one.

Engine defaults

A parameter that no schema authors still has a value in the simulation, so the field shows the engine’s own default, muted and marked (default), rather than a zero nobody chose. Armature defaults to 0.1 under Newton and 0 under PhysX, and an unclamped velocity limit reads unlimited. While the timeline is playing, the panel prefers what the running engine reports for armature and the velocity limit over the documented default, because that value is measured rather than assumed.

A (default) reading is what the engine will simulate, not an opinion recorded in the asset. Nothing is written to USD until you type a value into the field, and saving never turns a default into an authored value.

Copying values to the other backend

Copy To PhysX and Copy To Newton — the label names whichever backend is not active — write the focused joint’s values onto the inactive backend’s schema, leaving the values shown here unchanged. Copy All To PhysX and Copy All To Newton do the same for every tunable joint as a single undoable edit. Both are opt-in and one-directional, and they change what the other backend simulates, so a notification reports how much was written. Two things are skipped: a parameter the other backend already simulates, and a parameter showing (default), which has nothing authored to carry over. Use these buttons to seed a backend that has nothing authored, not to keep the two backends in step.

Backends the panel cannot author for

These three fields have to know which joint schema the running engine reads. When the active engine is one the Gain Tuner has no schema for — remotesim, an engine it does not recognize, or an engine query that returned nothing — the fields are disabled and the section states why, and the matching table columns are hidden. Writing physxJoint:* on the chance that the engine reads it would author a value nothing consumes, which looks identical to a successful edit. In this state the Backend tag reads the engine’s own name, or unknown when the engine could not be read at all. The drive gains, the tests, and the charts are unaffected.

Note

Newton reads armature, joint friction, and the velocity limit from the stage once, when the simulation starts, so an edit made while the timeline is playing does not reach the running solver. Stop and play again to apply it — the panel says so while Newton is playing. PhysX picks up such an edit on the next step.

For where each schema’s tuned values are written on save, see Save Targets and Backend Mirroring.

Tuning Gains

The Joint Gains are a pair of Stiffness and Damping values that are used to drive the joint. They are applied to the joint in the form of a drive that applies an effort (Force/Torque) to the joint, based on the error between the desired position and velocity or both. This Effort is computed as:

\[Effort = K_p * (Position_{Desired} - Position_{Current}) + K_d * (Velocity_{Desired} - Velocity_{Current})\]

Where \(K_p\) is the Stiffness and \(K_d\) is the Damping.

From this formula, you can describe the different modes of the joint drive:

• Position Drive: When the joint drive is in position mode, the desired position is the target position. This requires the stiffness to be greater than 0, and the damping to be any value.

• Velocity Drive: When the joint drive is in velocity mode, the desired position is the current position, and the desired velocity is the target velocity. This requires the stiffness to be 0 and the damping to be any value.

• None: When the joint drive is in none mode, the joint drive is not active. The joint can still be controlled by applying a direct effort. This requires the stiffness to be 0 and the damping to be 0.

• Mimic: When the joint drive is in mimic mode, the joint drive is driven by the mimic joint. This means that the joint drive will not be active, but the mimic joint’s attributes of Natural Frequency and Damping Ratio can still be configured through the Tuner.

This Dampener-Spring model can also be described in terms of the natural frequency and damping ratio:

\[ \begin{align}\begin{aligned}\omega_n = \sqrt{\frac{K_p}{m}}\\\zeta = \frac{K_d}{2 m \omega_n}\end{aligned}\end{align} \]

Where \(\omega_n\) is the natural frequency and \(\zeta\) is the damping ratio, and \(m\) is the computed joint inertia based on the mass of the robot at both sides of the joint. The damping ratio is such that \(\zeta = 1.0\) is a critically damped system, \(\zeta < 1.0\) is underdamped, and \(\zeta > 1.0\) is overdamped.

From the above formula, observe that there are two ways to tune PhysX DriveAPI gains:

• Stiffness / Damping — edit the stiffness and damping values directly, in the table or in the detail panel’s Controller Gains form.

• Natural Frequency / Damping Ratio — the Gain Tuner computes the stiffness and damping for you from a target natural frequency (Hz) and dimensionless damping ratio, using the joint’s effective inertia and drive type.

Note

Because the robot is a structure that is made of multiple links and moving joints, the natural frequency of each joint is dependent on the robot’s configuration. To establish a standard, the natural frequency of the robot at its home configuration is used.

Tuning modes

For a joint with editable PhysX DriveAPI gains, the detail panel’s Controller Gains form has a toggle that switches between Stiffness / Damping and Natural Frequency / Damping Ratio. In natural-frequency mode the two gain fields show the target natural frequency and damping ratio; edits are converted back to drive stiffness and damping and written to the same DriveAPI attributes, so saving persists them unchanged. Natural-frequency mode needs the joint’s effective inertia, which is computed once the timeline has played; until then the fields prompt you to play the timeline. The toggle is hidden for Newton actuator gains, MuJoCo raw parameters, and mimic joints.

Natural-frequency mode uses the joint’s drive type in the conversion, but does not let you change it. For the remaining per-joint settings the detail panel exposes, see Advanced actuator parameters.

The tunable Degrees of Freedom (DOF) of the robot are displayed in accordance with what is defined in the robot’s joint list.

Tuning Workflow

Gain tuning is an iterative process. The recommended workflow moves through two stages:

1. Set initial gains using the position or velocity drive heuristics below.

2. Tune and evaluate using the built-in test modes, each targeting a different aspect of joint behavior:

   • Snap to Limits (default) — commands joints to their lower and upper limits. Use this to verify that gains are strong enough to reach the full range of motion and that limits, gains, and collision geometry are mutually consistent.

   • Sinusoidal — drives joints with a continuous repeating waveform. Use this to evaluate how well gains track smooth motion and to identify underdamping or overdamping from the shape of the tracking curve.

   • Step Function — drives joints with sudden position changes. Use this to evaluate how quickly and accurately gains respond to discrete commands, as a closer approximation of how a policy issues targets during training.

Once gains are satisfactory across these test modes, run the Stress test to confirm they are robust under the extreme commands typical of reinforcement learning training, and optionally the dt Sweep to confirm the gains still track accurately at the physics timestep you intend to ship, before moving to Isaac Lab.

Note

The specific tuning process may vary based on the characteristics of the robot and its control system.

Position Drive

For each joint of the robot:

1. Start by setting the damping to zero and only tuning the stiffness. This will help you establish a stable response without the influence of the derivative term.

2. Increase the stiffness until the joint is able to converge near the target position.

3. Reduce the stiffness by one order of magnitude.

4. After setting the stiffness, add damping with one order of magnitude lower than stiffness. This will be your baseline for the parameters and in general should not overshoot. If you want a faster response, reduce damping further.

5. Fine-tune both gains around this established baseline to achieve the desired performance, considering factors such as stability, response time, and overshoot.

6. If you want to emulate a control that includes gravity compensation, select all rigid bodies of the robot and check Disable Gravity in the properties panel.

Velocity Limit and Industrial Robots

Many robots, including the majority of industrial robots, come with pre-tuned PD control for their joint drives and can be set up to have a perfect position control response, always driving at the given joint velocity limit. To reproduce this behavior, increase the joint stiffness from the previous tuning heuristic by a factor of two and define the maximum joint velocity in Joint > Advanced > Maximum Joint Velocity in the Properties panel. Run the simulation to verify the joint velocity is meeting the specification and fine-tune the stiffness until the joint max velocity limit is within tolerance. If stiffness is too high, the max velocity may still be violated, so it is not advised to add infinite stiffness to the joint — instead operate with stiffness similar to the values calibrated without a max joint velocity.

Velocity Drive

For each joint of the robot:

1. Start by setting the Stiffness to zero and only tuning the damping.

2. Increase the damping until the joint is able to converge near the target velocity.

3. If the robot may carry additional load, slightly increase the damping (for example, add 10% extra) to account for the extra load.

4. You can limit the joint’s output by either setting the max joint velocity, or restricting the max joint force to impose a maximum joint load effort.

Save Targets and Backend Mirroring

Tuned gains are written to USD layers from the Save Target row below the joint table. Following the NVIDIA Isaac Sim Asset Structure, joint gains are a physics configuration and are saved on a physics layer.

• DriveAPI save target. Stiffness and damping default to the neutral, human-editable payloads/Physics/physics.usda layer, which stays first in the Save Target dropdown. The dropdown also lists every other payloads/Physics/*.usda layer found on the stage — for example a backend-specific physx.usda overlay — so you can route the DriveAPI write to a particular layer. If you make no explicit choice, physics.usda is used.

• Mirror to MuJoCo (opt-in). When DriveAPI is the active source, the Mirror tuned DriveAPI gains to MuJoCo checkbox controls whether saving also writes the tuned Kp/Kd into the robot’s MuJoCo (mjc:*) actuator parameters. It is off by default, so a save never touches MuJoCo actuator prims unless you opt in, and PhysX and MuJoCo gains can intentionally differ. The checkbox appears only when the robot has MuJoCo-native gains and the MuJoCo solver is not active; when ticked, its target layer defaults to mujoco.usda. When the MuJoCo solver is active, mjc:* is the active source and is edited and saved directly instead of mirrored.

• Newton actuator writeback. When a joint is driven by a Newton actuator, saving writes the tuned gains back onto the actuator prim’s newton:kp / newton:kd / newton:ki attributes. This is on by default because the actuator is the joint’s own active source; its target layer defaults to the actuator prim’s defining layer.

• Advanced joint parameters. Armature, joint friction, and the velocity limit are routed per schema rather than to one layer. An authored newton:* value is engine-neutral, so it joins the DriveAPI gains on the selected Save Target layer (physics.usda by default). An authored physxJoint:* value is a PhysX opinion, so it goes to the physx.usda overlay when the robot has one, and otherwise stays on the layer that already defines it rather than leaking into the neutral layer. Only values that are explicitly authored are written: a parameter left at an engine default is never stamped into the asset. See Advanced actuator parameters.

Press Save to author the collected edits into the chosen layers.

Test Gains

The Test Gains tab hosts the validation workflow in two collapsible sections: Test Gains Settings (run button, duration, mode selector, per-mode options, and the per-joint test-configuration table) and Charts, which holds the results tables and the trajectory plots. A progress bar appears while a test runs. The tab offers a suite of tests that let you quickly assess the quality of the current set of gains under different conditions. Each test is divided by sequences, where a sequence is a group of joints tested together. The sequence is defined per joint and is an index of the order in which the test runs. For each sequence the robot resets to its initial configuration before the test begins.

All tests send position commands for position drives and velocity commands for velocity drives. In position commands the target velocities are always zero, so that joint damping is properly evaluated. In a real control scenario a proper trajectory command should be sent, where the velocity command is equivalent to the integrated positions of the designated trajectory. Joints driven by a Newton actuator or by active MuJoCo-native gains are commanded during tests as well; their targets are converted to motion by the actuator or MuJoCo solver.

The test modes share the same setup steps:

1. In the per-joint test-configuration table, enable the Test checkbox for the joints you want to evaluate.

2. Assign joints to sequences. Joints in the same sequence are tested simultaneously; joints in different sequences are tested one group at a time, with the robot resetting to its home configuration between sequences. Group joints that are expected to move together.

3. Select the desired test mode in the Test Mode selector (Snap to Limits, Sinusoidal, Step Function, Stress, or dt Sweep), configure its parameters, and press Run Test. You do not need to press Play first: Run Test starts the timeline when the simulation is not already playing. While a test runs the button becomes Cancel Test.

Repeat — adjust gains, re-run, observe — until results are satisfactory. Each test mode surfaces different information, so it is useful to work across several rather than treating any one as definitive.

Reviewing results

Every test mode presents its results at the top of the Test Gains tab, above the trajectory charts, so the scene-level outcome reads first. A verdict banner sits above an all-joints results table with one row per tested joint and a color-coded Result cell. Selecting a joint in the color picker shows its per-joint trajectory in the Position charts below. An Effort chart appears only when the active backend reports measured joint forces; see Visualizing Results.

• Snap to Limits — verdict banner (ALL JOINTS PASSED, ALL GAINS OK - SOME JOINTS BLOCKED, or SOME JOINTS FAILED) above a table of per-limit mean error, max error, and settle time, with a color-coded result (green pass, amber blocked, red fail). Settling time is reported here because it is meaningful for the snap-to-limits response.

• Stress — a mode/seed context line and verdict banner (ALL JOINTS STABLE or INSTABILITY DETECTED) above a table of max velocity, trigger time, trigger velocity, and result (green stable, red unstable).

• dt Sweep — verdict banner (for example ALL ACCURATE AT TARGET DT or ACCURACY DEGRADED AT TARGET DT) above a table of settle time at the target dt, steady-state error, and the accuracy cliff, plus Settle Time vs dt and Steady-State Error vs dt charts.

The Step Function mode additionally reports a per-joint overshoot metric (percent of the step magnitude). Overshoot is reported only for Step Function, because it is the only mode whose command is a clean step-and-hold; Snap to Limits reports its own per-limit error and settle-time metrics instead, and the Sinusoidal and Stress modes report peak/RMS tracking rather than overshoot.

Snap to Limits

The recommended starting point for evaluating a new or modified robot. It commands each joint to its lower limit, holds, then to its upper limit, holds, and finally returns to the home position. The test validates that authored joint limits, drive gains, and collision geometry are all mutually consistent.

Each joint approaches its target and waits to stabilize before the hold phase begins. If a joint does not settle within ten seconds, the test proceeds to the hold phase regardless. During the hold phase, position error is sampled continuously and reported as mean and maximum error over the full hold duration, making the metric robust to residual oscillation.

After the hold, each joint receives one of three classifications:

• Pass: Both limits reached within tolerance.

• Fail: A limit was not reached and the joint was still moving or oscillating, indicating a gains or dynamics issue.

• Blocked: A limit was not reached and the joint was stalled, typically caused by self-collisions or other physical constraints rather than a gains issue.

The total test time is variable: fast robots settle quickly and the test finishes in seconds, while slow or weak drives consume the full timeout per phase.

Per-joint results include settling time (reported separately for the lower and upper limit phases) and mean and maximum hold error at each limit.

Parameters:

Parameter	Description	Default
Hold Duration	Seconds to hold at each target after the joints have settled.	1.0
Tolerance	Position error threshold (rad or m) for the settling check and pass/fail determination.	0.01
Disable Self-Collisions	Temporarily disable self-collisions on the articulation during the test. Useful for distinguishing a Blocked result caused by collision geometry from a Fail result caused by insufficient gains.	Off
Disable Velocity Limits	Temporarily set joint max velocity limits to a very large value for the test duration. Useful for isolating whether a Fail result is caused by insufficient gains or by velocity limits preventing the joint from reaching its target in time.	Off

Interpreting Results:

Each classification points to a different part of the system and suggests a different remedy.

• Pass with long settling time: The joint reaches its target but slowly, indicating the system is overdamped. Try increasing stiffness or reducing damping, then re-run to confirm settling time improves without introducing oscillation. Residual oscillation will appear as elevated mean hold error even on a passing joint.

• Pass with high hold error: The joint reached the limit closely enough to pass the tolerance check but is not holding cleanly — likely underdamped with residual oscillation. Try increasing damping.

• Fail: The joint did not reach its target and was still moving at the end of the timeout. First re-run with Disable Velocity Limits enabled. If the joint passes, the velocity limit is preventing the joint from reaching its target in time and the remedy is raising the velocity limit rather than adjusting gains. If the joint still fails, stiffness is insufficient and should be increased.

• Blocked: The joint stalled before reaching its limit. Re-run with Disable Self-Collisions enabled. If the joint passes, the limit is set beyond what the collision geometry allows — tighten the joint limit in USD rather than adjusting gains. If the joint remains blocked with collisions disabled, examine whether a mimic joint coupling, another joint in the same sequence, or an incorrectly authored limit is constraining motion.

Note

These tests identify that something is wrong and roughly where, but the magnitude of any gain adjustment still requires iteration: change gains, re-run, and observe whether the metric improves. The tests are diagnostic tools, not optimizers.

Sinusoidal

Drives joints with a continuous sinusoidal trajectory for the test duration. Useful for evaluating how well gains track smooth, repeating motion across a joint’s range.

Parameters:

• Test: Check to include the joint in the test.

• Period: The period of the waveform.

• Phase: The phase of the waveform.

• Amplitude: The amplitude of the waveform, from 0 to 100%.

• Offset: The offset of the waveform, from 0 to 100%.

Interpreting Results:

Use the result plots to guide adjustments:

• Measured position closely tracks commanded position: gains are well-tuned for this waveform. Consider tightening the period or increasing amplitude to stress the joint further.

• Measured position lags the command or undershoots: stiffness is likely too low. Increase stiffness and re-run.

• Measured position oscillates or overshoots: damping is likely too low. Increase damping and re-run.

• Measured position is offset from the command at steady state: the joint drive may be saturating at its max force limit. Check the joint max force setting in the Properties panel.

Step Function

Drives joints with a repeating step-function trajectory, alternating between a minimum and maximum position. Useful for evaluating how quickly and accurately gains respond to sudden position changes.

Parameters:

• Test: Check to include the joint in the test.

• Period: The period of the waveform.

• Phase: The phase of the waveform.

• Step Minimum: The minimum value of the waveform, in the joint value units of measurement.

• Step Maximum: The maximum value of the waveform, in the joint value units of measurement.

Interpreting Results:

Use the result plots to guide adjustments:

• Measured position reaches the step target and holds cleanly: gains are well-tuned for this step size and period.

• Measured position overshoots and oscillates before settling: damping is too low. Increase damping.

• Measured position approaches the target slowly or does not reach it within the period: stiffness is too low, or the period is shorter than the joint’s velocity limit allows. Try increasing stiffness or lengthening the period.

• Measured position reaches the step target but with a consistent steady-state offset: the joint drive may be saturating. Check the joint max force setting.

Note

A reasonable goal across the waveform test modes is to find gains that reach the commanded position with overshoot within 1% of the target. The specific tolerance depends on your application.

Stress

The stress test subjects joints to extreme random commands to surface solver instabilities that may appear during reinforcement learning training but are invisible during normal GUI testing. It runs against whichever physics backend is active, so a result characterizes the gains under that backend’s solver and not under the other one. When training a policy with many parallel environments, the exploration space is large and joints may receive rapid, unconstrained commands across their full range. Finding these instabilities in the GUI — where iteration time is fast and the robot inspector is available — is significantly easier than diagnosing them during a training run.

Two sub-modes are available:

Random Walk — Every physics step, a Gaussian-distributed delta is added to each joint’s current position target. Commands are clamped to joint limits. This simulates unconstrained neural-net exploration during early policy training. The standard deviation (sigma) is expressed as a percentage of each joint’s range, so wider joints receive proportionally larger perturbations.

Adversarial — Every N physics steps, all active joints are simultaneously snapped to randomly chosen lower or upper limits (50/50 per joint). This maximizes worst-case solver load by driving extreme correlated configurations that the random walk would only hit rarely, targeting the same failure modes that arise when many parallel training environments simultaneously drive a robot to opposing extremes.

Per-joint instability detection runs every step:

• Velocity exceeding the configurable threshold marks the joint as Unstable.

• NaN in position or velocity marks the joint as Unstable.

• If neither occurs over the full duration the joint is classified as Stable.

The RNG seed is logged so destabilizing runs can be reproduced exactly.

Parameters:

Parameter	Description	Default
Sub-mode	Random Walk or Adversarial.	Random Walk
Duration	Simulation-time seconds to run.	10.0
Velocity Threshold	Absolute velocity (rad/s or m/s) above which a joint is flagged as Unstable.	100.0
Sigma (% range)	Standard deviation of the per-step Gaussian delta in Random Walk mode, expressed as a percentage of each joint’s range.	1.0
Snap Interval	Physics steps between random snaps in Adversarial mode.	10
Seed	RNG seed for reproducibility. Logged in results so a destabilizing run can be reproduced exactly.	42
Disable Self-Collisions	Temporarily disable self-collisions on the articulation during the test. Useful for distinguishing instabilities caused by contact events from those caused by gains.	Off
Disable Velocity Limits	Temporarily set joint max velocity limits to a very large value for the test duration. Useful for isolating whether instabilities are caused by gains or by velocity limits producing large per-step correction errors.	Off

Interpreting Results:

• Stable across both modes: Positive evidence that the gains are unlikely to cause solver instabilities during Isaac Lab training at the configured sigma and snap interval. Document the test parameters alongside the result — a robot that is stable at 1% sigma may not be stable at 5% sigma, and this distinction matters when estimating safety margins for policy training.

• Unstable with self-collisions enabled, Stable with them disabled: The instability is contact-driven rather than gains-driven. Do not adjust gains in response to this result. Instead, examine whether the joint limits allow configurations where self-contact occurs and tighten limits or adjust collision geometry accordingly.

• Unstable with self-collisions disabled: Gains are implicated. Examine the logged time-to-instability and triggering command. A very short time-to-instability at low sigma indicates the gains are marginal even under mild perturbation and significant adjustment is needed. A long time-to-instability at high sigma indicates the gains are robust under realistic conditions and the instability is only reachable at perturbation levels a trained policy would rarely produce.

• Unstable in Random Walk but Stable in Adversarial (or vice versa): The failure mode differs between the two sub-modes and the results can help narrow the diagnosis. Random Walk instabilities tend to arise from the target drifting into a problematic region incrementally. Adversarial instabilities tend to arise from the solver struggling with simultaneous extreme configurations across coupled joints.

Isolating the responsible joints:

When an instability is found, use the logged RNG seed to reproduce the run exactly. Then use the sequencer to re-run the test on progressively smaller subsets of the articulation, binary searching toward the minimal set of joints that reproduces the instability. This isolates which part of the kinematic chain is responsible and is significantly faster than reasoning about the full-robot result. The Robot Inspector can assist in examining the isolated subsystem.

Note

A Stable result is meaningful only at the sigma and snap interval values used. Record these parameters alongside results when assessing readiness for Isaac Lab training.

dt Sweep

The dt Sweep characterizes how each joint’s position-control accuracy changes with the physics timestep. It runs a single-timestep step-response probe at a geometric ladder of timesteps between a finest and a coarsest bound, then compares each level against the finest-dt reference to report settle-time degradation, steady-state error, and the accuracy cliff — the coarsest timestep whose accuracy still tracks the reference. Use it to confirm that gains that pass at a fine timestep still behave acceptably at the timestep you intend to simulate at.

Each joint is classified at a target dt (the timestep you plan to ship). While the sweep runs, the progress readout names the current level, for example dt level 3/10: 120 Hz (dt=0.00833 s).

Parameters are grouped into Timestep range (dt Max, dt Min), Probe (number of steps, target dt, per-level settle timeout, hold duration), and Accuracy thresholds (settle tolerance and the maximum allowed settle-time and steady-state-error degradation before a joint is flagged). Each field carries a units label and an explanatory tooltip. The dt Max / dt Min bounds are validated before the sweep runs: reversed, equal, non-positive, or non-finite bounds are rejected with a notification and the sweep does not start.

Interpreting Results: the verdict is one of ALL ACCURATE AT TARGET DT, ACCURACY DEGRADED AT TARGET DT, JOINTS DID NOT SETTLE AT TARGET DT, or REFERENCE DT DID NOT SETTLE (INDETERMINATE). A joint is indeterminate when its finest-dt reference run never settled, so there is no valid baseline to measure degradation against. The Settle Time vs dt and Steady-State Error vs dt charts plot the swept metrics against the timestep for the joints selected in the color picker.

Visualizing Results

The Position charts plot each tracked joint’s measured trajectory against the commanded trajectory. On backends that report measured joint forces (such as PhysX), an Effort chart appears as well and plots measured forces the same way. Select the joints to display in the color picker; results are color-coded by joint, with measured values shown as a faded version of the commanded trajectory’s color.

Each chart carries its own controls. A legend row above the plot has one checkbox per series group — Command Joint and Observed Joint on a Position chart, Effort on an Effort chart — that shows or hides that group, with a colored dot for every joint the group draws. The dots are read from the trace colors, so a legend entry and its trace always agree. Range sliders with type-in value fields set the visible window on each axis, and Fit Frame View resets both axes to the full recorded extent. Horizontal gridlines land on round values, and zero is always one of them when it falls inside the visible range, highlighted in its own color so you can read the sign and the size of an overshoot straight off the chart.

Below the axis controls, the collapsible Value Readout section reports every visible series at the time you hover over the plot, as one row per joint and one column per legend group. It starts closed and sits below everything else, so opening it moves neither the plot nor the axis controls. A joint with nothing to report at the hovered time — for example a series with too few samples left inside a zoomed window — shows - rather than a blank cell.

Important

The Effort chart requires measured joint forces from the physics backend. The Newton backend does not currently provide them, so when Newton is active — for example after launching with ./isaac-sim.newton.sh or isaac-sim.newton.bat — the Effort chart is omitted. The Position charts and the numeric results tables are unaffected. Seeing only Position charts on Newton is expected behavior, not a failed or incomplete test.

Note

A joint that loses stability mid-test stops producing usable samples — it either records non-finite values or winds up far past its own travel limits. On the Position chart those samples are left off: the trace ends where the response diverged, both axes open on the part of the run that is still readable, and a footer note reports both. Without this, one non-finite or astronomical sample would set the shared axis range and flatten every trace into what looks like an empty chart. Read a trace that stops early as a diverged joint that needs re-tuning, not as the joint’s response, and use Fit Frame View to see the full recorded extent.

The bound each joint is held to comes from its own position limits, so it does not change with the test mode, the commanded amplitude, or which other joints are selected. A joint whose limits do not bound anything — a continuous revolute — falls back to its own commanded peak. The Effort chart has no equivalent reference, so only non-finite effort samples are omitted there; a joint that diverges to a large but finite effort still stretches that chart’s range.

Even if a joint is not listed in the Robot Schema, it is still visualized in the plots if it is part of the physical robot.

To select more than one joint, hold Ctrl and click on the desired joints, or select the first joint and hold Shift and click the last joint to select all joints between them.

Note

Visualization results are only available after tests have finished running. Depending on test configuration, this may take some time.

Tips

• Disable gravity if your robot has built-in gravity compensation or a separate gravity compensation controller.

• Group joints that are expected to move together and tune each group individually first, then combine them for a final test. For a humanoid robot, for example, you may want to separate the legs and arms.

• Reduce the maximum speed of a joint that you are tuning if it is not expected to be commanded to move that fast in practice. Most default maximum velocities in USD are likely impractically high.

• When running the Stress test, document the highest sigma at which all joints are Stable — this is a practical safety margin for your Isaac Lab training configuration.

• If a joint is Blocked in Snap to Limits, use Disable Self-Collisions to confirm the cause before adjusting gains.

Further Learning

• The Tutorial 11: Tuning Joint Drive Gains tutorial for a hands-on walkthrough using the UR10 manipulator.