[isaacsim.robot_setup.gain_tuner] Gain Tuner#
Version: 3.10.0
Overview#
The isaacsim.robot_setup.gain_tuner extension provides the core library for tuning PD (Proportional-Derivative) gains on robot articulations and running validation tests. Use it programmatically to inspect joint drives, compute effective inertia, execute sinusoidal/step/snap/stress tests, and collect USD layer edits for saving tuned gains.
The interactive Gain Tuner window lives in the companion extension isaacsim.robot_setup.gain_tuner.ui.
Key Components#
GainTuner#
The GainTuner class manages articulation setup, joint discovery, accumulated inertia computation, registered validation tests, and test execution during simulation.
from isaacsim.robot_setup.gain_tuner import GainTuner, GainsTestMode, SinusoidalTest
tuner = GainTuner()
tuner.setup("/World/MyRobot")
tuner.register_test(GainsTestMode.SINUSOIDAL, SinusoidalTest())
tuner.initialize_gains_test({"duration": 2.0, "frequency": 1.0})
Drive helpers and USD save utilities#
isaacsim.robot_setup.gain_tuner.joint_drive_attrs— query stiffness, damping, and drive mode from USD joint prims.isaacsim.robot_setup.gain_tuner.usd_layer_utils— resolve physics layers and collect drive attribute edits for saving.
Multi-backend gain sources#
The isaacsim.robot_setup.gain_tuner.gain_sources module resolves and edits joint
gains across the three backends a robot may author them in: PhysX PhysicsDrive gains,
Newton NewtonActuator PD/PID controllers, and MuJoCo actuator (mjc:*) parameters.
It is engine-aware — for example, when the Newton MuJoCo solver is active
(newton_mujoco_solver_active)
the MuJoCo gains take precedence.
The GainSource enum names each
backend. resolve_joint_gains
reads a joint’s effective stiffness/damping and their defining USD attributes into a
ResolvedGains, while
active_gain_source and
available_viewed_sources
report which backends drive a joint and which may be viewed. Backend maps are built with
build_actuator_gain_map
(Newton) and build_mjc_gain_map
(MuJoCo), and drive_gains_to_mjc /
mjc_params_to_drive_gains
convert between PD gains and MuJoCo parameters.
Edits are written back through a layer-aware save pipeline:
list_gain_save_target_layers
enumerates candidate physics layers,
build_gain_save_plan collects
the attribute edits, and
apply_gain_save_plan authors
them into the chosen layer.
Per-backend advanced joint parameters#
Armature, joint friction, and the joint velocity limit are authored on separate joint
API schemas per backend, and each backend reads its own. The
isaacsim.robot_setup.gain_tuner.joint_schema_attrs module resolves and edits them
without mixing the two backends’ tuning.
resolve_joint_param (and
resolve_joint_params for a
whole joint) returns a
JointParamResolution naming
every schema’s authored value, the schema the active backend resolves, the effective value,
and which authored values are shadowed or never read. Reads follow the schema-resolver order
Newton itself uses, which depends on the running solver — exposed by
resolver_chain,
param_resolver_chain, and
candidate_param_chains,
which report the chain as undetermined rather than guessing when the solver
(newton_solver_type) is unknown.
author_joint_param writes only
the schema named by
backend_write_schema, which
returns None for a backend whose joint schema is unknown — check
backend_supported and disable the
edit rather than guessing. A difference between the two backends is reported as fact by
diverging_joint_params, and
copy_joint_param_to_backend
copies one backend’s value onto the other as an explicit action.
For an unauthored parameter,
JointParamSpec.engine_default
gives the value the engine simulates anyway (Newton’s armature default is
NEWTON_DEFAULT_ARMATURE,
not zero), and
GainTuner.get_dof_engine_armature /
GainTuner.get_dof_effective_max_velocity
report what the running engine really uses, compared with
max_velocity_agrees. Because
only PhysX re-reads these values mid-run
(backend_reads_usd_while_playing),
an edit made under Newton while the timeline plays does not take effect until the next play.
Discretization (dt) sweep#
The isaacsim.robot_setup.gain_tuner.discretization_sweep module implements the
dt-sweep validation test, which probes how a joint’s step response degrades as the physics
timestep grows. dt_sweep_levels
builds the geometric ladder of timesteps between a min/max bound (validated by
validate_dt_bounds), and
DiscretizationSweepTest
runs a single-timestep accuracy probe at each level.
aggregate_dt_sweep compares each
level against the finest-dt reference to compute settle-time degradation, steady-state error,
and the accuracy “cliff” (the coarsest dt still within tolerance), and
select_target_level_index
picks the level closest to a requested target dt so results can be reported for the timestep
the user intends to ship.
Enable Extension#
The extension can be enabled (if not already) in one of the following ways:
Define the next entry as an application argument from a terminal.
APP_SCRIPT.(sh|bat) --enable isaacsim.robot_setup.gain_tuner
Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.
[dependencies]
"isaacsim.robot_setup.gain_tuner" = {}
Open the Window > Extensions menu in a running application instance and search for isaacsim.robot_setup.gain_tuner.
Then, toggle the enable control button if it is not already active.