[isaacsim.core.experimental.actuators] Isaac Sim Core (Actuators)#

Version: 0.2.1

Overview#

The isaacsim.core.experimental.actuators extension provides high-level runtime support for Newton actuators on robot articulations in Isaac Sim. It adds a thin wrapper that owns one or more actuator pipelines per articulation, registers a pre-physics callback, and writes the resulting joint efforts back to the Articulation on every step. Actuators can either be authored on the asset in USD (so they travel with the robot file and can be loaded unchanged by any Newton-aware application, including Isaac Lab) or built in Python at runtime for cases where USD authoring is impractical.

Note

This extension is experimental. Class names, USD schema attribute names, and parsing semantics may change in future releases.

Key Components#

`ArticulationActuators`#

The ArticulationActuators class wraps an Articulation and is the primary user-facing object in the extension. On construction it either discovers NewtonActuator prims under the articulation root in USD, or accepts a list of Python-built configs via from_actuators. On each physics tick its pre-physics callback reads joint state and target, evaluates each actuator’s delay → controller → clamping pipeline, and writes the resulting effort back to the articulation. USD DriveAPI gains on actuated DOFs are zeroed automatically so the implicit drive does not fight the actuator output.

`ActuatorConfig`#

The ActuatorConfig dataclass bundles the three components of a single actuator’s pipeline: a required Newton DriveBase, an ordered list of optional ClampingBase stages, and an optional Delay. Used together with from_actuators to attach actuators to an articulation without touching USD. Subclasses of newton.actuators.DriveBase, ClampingBase, or Delay are accepted, so custom control laws can be plugged in by user code without modifying the Newton library.

USD Authoring#

The USD authoring helpers — add_actuator together with the per-component config dataclasses PDControlConfig, PIDControlConfig, NeuralControlConfig, MaxEffortClampingConfig, DCMotorClampingConfig, PositionBasedClampingConfig, and DelayConfig — define NewtonActuator prims under an Actuators scope on the articulation root and apply the matching Newton USD API schemas. An authored actuator looks like:

def Scope "Actuators" {
    def NewtonActuator "panda_joint1_actuator" (
        prepend apiSchemas = ["NewtonPDControlAPI", "NewtonMaxEffortClampingAPI"]
    ) {
        rel newton:targets = </Franka/panda_link0/panda_joint1>
        float newton:kp = 400.0
        float newton:kd = 40.0
        float newton:maxEffort = 87.0
    }
}

The schema names live in the shared Newton USD schema, so any Newton-aware application — including Isaac Lab — can parse the same prim and recover the same actuator model.

`Articulation Actuators` OmniGraph Node#

The extension ships an omni.graph.action.execution-style node, registered as isaacsim.core.experimental.actuators.ArticulationActuators (UI name Articulation Actuators, category Newton Actuators). On its first execIn pulse the node lazily constructs an ArticulationActuators for the configured robotPath; from then on subsequent pulses re-apply the optional feedforwardCommand input. The node only operates on USD-authored actuators.

Functionality#

Two Construction Paths#

Discover from USD — pass an articulation root to ArticulationActuators and the constructor walks the USD subtree, parses every NewtonActuator prim, and rebuilds the pipeline.
Build in Python — call from_actuators with a list of (ActuatorConfig, dof_name) pairs. Useful when iterating on parameters or attaching custom controller subclasses that have no USD schema equivalent.

Composable Per-Actuator Pipeline#

Every actuator is a delay → controller → clamping pipeline applied to a single DOF. Built-in components from newton.actuators cover the common cases (PD / PID / neural-MLP / neural-LSTM controllers; symmetric, DC-motor, and position-based clampings; per-step input delay), and any subclass of the corresponding base class can be substituted from user code.

Autonomous Pre-Physics Stepping#

Once constructed, the wrapper registers its own pre-physics callback and runs the actuators on every physics step independent of further user code. The callback can be disabled by passing auto_step_pre_physics=False, in which case the user calls step_actuators manually — useful for tests that need deterministic single-step control.

Feedforward Effort#

set_dof_feedforward_effort_targets adds a per-DOF effort that is summed with the controller output every tick. With kp and kd zeroed this reduces to a pure open-loop torque drive, making it a convenient hook for gravity-compensation, learned residual policies, or any feed-forward torque component. Feedforward only affects DOFs that have an explicit actuator attached.

Partial Coverage#

Not every joint of an articulation has to be actuated. Joints without an explicit NewtonActuator prim (or matching from_actuators entry) keep their authored UsdPhysics.DriveAPI stiffness/damping and behave exactly as they would on the unmodified asset.

Cross-Application Portability#

Because the underlying actuator components and USD schema both live in Newton, USD-authored actuators on a robot file are application-agnostic: the same asset loaded in |isaac-sim_short| or in Isaac Lab will be reconstructed with the same effective control law. This extension is the |isaac-sim_short| runtime side of that portability story.

Tutorials#

Hands-on tutorials covering each construction path live under docs/isaacsim/newton_actuators_tutorials/:

Set Up Actuators from Python — building an actuator entirely in Python with from_actuators.
Author and Parse Actuators from USD — using add_actuator to bake actuators onto an asset and re-loading the saved file.
Drive an Actuated Robot from OmniGraph — wiring the Articulation Actuators node into an Action Graph.
Tips — practical guidance on armature, physics rate, and diagnosing high-frequency vibration.

Runnable companion scripts ship under standalone_examples/api/isaacsim.core.experimental.actuators/ and can be invoked via ./python.sh.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.core.experimental.actuators

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.core.experimental.actuators" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.core.experimental.actuators. Then, toggle the enable control button if it is not already active.

Python API#

Warning

The API featured in this extension is experimental and subject to change without deprecation cycles. Although we will try to maintain backward compatibility in the event of a change, it may not always be possible.

The following table summarizes the public API of the isaacsim.core.experimental.actuators extension.

`ArticulationActuators`	Newton actuator manager for an Articulation that computes and applies joint efforts each step.
`ActuatorConfig`	Component bundle passed to ArticulationActuators.from_actuators.
`PDControlConfig`	Configuration for a PD position-velocity controller.
`PIDControlConfig`	Configuration for a PID position-velocity controller.
`NeuralControlConfig`	Configuration for a neural-network controller (MLP or LSTM).
`MaxEffortClampingConfig`	Configuration for symmetric max-effort clamping.
`DCMotorClampingConfig`	Configuration for DC motor four-quadrant effort clamping.
`PositionBasedClampingConfig`	Configuration for position-dependent effort clamping via a lookup table.
`DelayConfig`	Configuration for command-input delay.
`add_actuator`	Author a NewtonActuator prim targeting one or more DOFs of an articulation.

Wrappers#

class ArticulationActuators( paths: str | list[str], *, auto_step_pre_physics: bool = True, device: wp.DeviceLike = None, _skip_discovery: bool = False, )#

Bases: object

Newton actuator manager for an Articulation that computes and applies joint efforts each step.

Parses the NewtonActuator prims of the first matched articulation, groups them into Newton actuator batches replicated across all N robot instances, zeros UsdPhysics.DriveAPI gains on every actuated joint, and on each physics pre-step reads articulation state and control targets, steps every actuator, and writes the resulting efforts back to the articulation. For Python-built actuators, meaning those supplied through ArticulationActuators.from_actuators, each user-provided (ActuatorConfig, dof_names) group becomes one Newton Actuator.

All N instances share identical actuator topology and parameters (the prototype-reference pattern). Per-instance USD overrides are not read.

The pre-physics callback is enabled at construction unless auto_step_pre_physics=False. Disabling it (at construction or via disable_auto_step_pre_physics()) prevents unintended last-writer-wins when multiple ArticulationActuators objects target overlapping DOFs.

Use articulation to access the underlying Articulation for setting position/velocity targets, reading state, or modifying drive gains.

Lifetime#

Each instance registers callbacks with the process-wide SimulationManager. Tear instances down explicitly via close() or by using them as a context manager (with ArticulationActuators(...) as actuated: ...). A __del__ fallback also calls close() on garbage collection, but ordering is non-deterministic so it must not be relied on.

param paths:: Single path or list of paths to articulation root prims. May include regex matching multiple instances.
param auto_step_pre_physics:: When true, register the pre-physics callback immediately so actuators are stepped automatically on every physics tick.
param device:: Warp device on which to allocate per-actuator scratch buffers. When None, use Warp’s default device.
param _skip_discovery:: Internal flag used by from_actuators to bypass USD discovery so actuators can be supplied directly from Python.
raises ValueError:: If a USD actuator target is not a DOF of this articulation, or if two USD actuators resolve to the same DOF index.

Example:

>>> from isaacsim.core.experimental.actuators import ArticulationActuators

>>> with ArticulationActuators("/World/Robot") as actuated:  
...     actuated.step_actuators(step_dt=1.0 / 60.0)

__enter__() → ArticulationActuators#

Return self so the instance can be used as a context manager.

Returns:: This ArticulationActuators instance, unmodified.

__exit__( exc_type: object, exc: object, tb: object, ) → None#

Deregister all callbacks on exit from the context-managed block.

Parameters:

exc_type – Exception class raised inside the with body, or None.
exc – Exception instance raised inside the with body, or None.
tb – Traceback associated with exc, or None.

close() → None#

Deregister all callbacks held by this instance. Safe to call multiple times.

Prefer using ArticulationActuators as a context manager (with ... as actuated:) so close() is invoked automatically on block exit; call this method explicitly only when the wrapper’s lifetime cannot be bounded by a with statement.

Example:

>>> actuated.close()  

disable_auto_step_pre_physics() → None#

Opt out of the pre-physics actuator callback.

Example:

>>> actuated.disable_auto_step_pre_physics()  

enable_auto_step_pre_physics() → None#

Opt in to the pre-physics actuator callback. Persists across stop/start cycles.

Example:

>>> actuated.enable_auto_step_pre_physics()  

classmethod from_actuators( paths: str | list[str], actuators: list[tuple[ActuatorConfig, str | list[str]]], *, device: wp.DeviceLike = None, auto_step_pre_physics: bool = True, ) → ArticulationActuators#

Construct an ArticulationActuators entirely from Python-built ActuatorConfig objects.

No USD scanning is performed. This is the escape hatch for cases where USD authoring is unavailable or impractical — the caller supplies the complete set of actuator configurations and their target DOF groups.

Each entry becomes exactly one Newton Actuator. Every per-motor Warp array inside its ActuatorConfig components must contain n_robots * n_target_dofs values in robot-major order: all named DOFs for robot zero, then all named DOFs for robot one, and so on. Component parameters declared as shared apply to the whole group and are not repeated per motor.

actuated_dof_indices is always sorted by DOF index. actuators follows the supplied group order and is not positionally aligned with that DOF list. Within a multi-DOF group, name order determines the component-array value order.

Parameters:

paths – Single path or list of paths to articulation root prims.
actuators – List of (config, dof_names) pairs, where dof_names is either one DOF name or a list of DOF names. Each name must match an entry in Articulation.dof_names (e.g. "shoulder_joint"). One pair produces one vectorized Newton Actuator for the entire group.
device – Warp device on which to allocate per-actuator scratch buffers. When None, use Warp’s default device.
auto_step_pre_physics – Forwarded to the underlying __init__.

Returns:

A fully initialised ArticulationActuators driven by the provided configs.

Raises:

TypeError – If a target is neither a string nor a list[str].
ValueError – If a target group is empty, a DOF name is not found, or a DOF appears more than once in actuators.

Example:

>>> import warp as wp
>>> from isaacsim.core.experimental.actuators import (
...     ActuatorConfig,
...     ArticulationActuators,
... )
>>> from newton.actuators import DrivePD

>>> cfg = ActuatorConfig(
...     controller=DrivePD(
...         kp=wp.array([100.0, 200.0], dtype=wp.float32),
...         kd=wp.array([10.0, 20.0], dtype=wp.float32),
...     )
... )
>>> actuated = ArticulationActuators.from_actuators(  
...     "/World/Robot",
...     [(cfg, ["shoulder_joint", "elbow_joint"])],
... )
>>> len(actuated.actuators)
1
>>> actuated.actuators[0].num_actuators
2

reset() → None#

Zero all stateful actuator state (PID integrals, delay buffers).

Called automatically on each PHYSICS_READY event and available for manual invocation.

Example:

>>> actuated.reset()  

Set per-DOF feedforward effort targets consumed by step_actuators.

These values are passed through the actuator pipeline (controller + clamping) on the next step_actuators call. They have no effect on joints that do not have a corresponding actuator.

Parameters:

target_feedforward_efforts – Feedforward efforts [N or N·m], shape (N, D) or broadcastable.
indices – Prim indices subset.
dof_indices – DOF indices subset.

Example:

>>> import numpy as np

>>> actuated.set_dof_feedforward_effort_targets(  
...     np.array([5.0, -3.0]),
...     dof_indices=[0, 1],
... )

step_actuators( step_dt: float, context: Any = None, ) → None#

Compute and apply actuator efforts for one physics timestep.

Parameters:

step_dt – Physics timestep in seconds.
context – Unused; accepted to satisfy the SimulationManager callback signature.

Example:

>>> actuated.step_actuators(step_dt=1.0 / 60.0)  

property actuated_dof_indices: list[int]#

Get the sorted unique DOF indices covered by the owned actuators.

This contains one entry per DOF, not one entry per Actuator.

Returns:: A copy of the actuated DOF index list, sorted ascending.

Example:

>>> actuated.actuated_dof_indices  
[0, 1, 2]

property actuators: list[Actuator]#

Get the Newton Actuator instances owned by this wrapper.

One actuator can control multiple DOFs, so this list is not positionally aligned with actuated_dof_indices.

Returns:: A shallow copy of the owned Actuator list.

Example:

>>> actuated.actuators  
[<newton.actuators.Actuator object at ...>, ...]

property articulation: Articulation#

Get the underlying Articulation wrapper.

Returns:: The Articulation driven by this instance.

Example:

>>> actuated.articulation  
<isaacsim.core.experimental.prims.Articulation object at ...>

Configuration dataclasses#

class ActuatorConfig( controller: DriveBase, clamping: list[ClampingBase] = <factory>, delay: Delay | None = None, )#

Bases: object

Component bundle passed to ArticulationActuators.from_actuators.

Holds the Newton drive, optional clamping stages, and an optional delay. The per-motor warp arrays inside each component must be sized for n_robots * n_target_dofs, where n_target_dofs is one for a scalar DOF name or the length of the target DOF list. n_robots can be obtained from len(Articulation(paths)) before constructing the config. The ArticulationActuators builds the Actuator wrapper, including index arrays, internally.

Parameters:

controller – Any Newton DriveBase subclass with pre-built warp arrays.
clamping – Ordered list of ClampingBase stages applied after the drive.
delay – Optional Delay applied to input targets before the drive.

Raises:

TypeError – If a component does not have the required Newton actuator type.

Example:

>>> import warp as wp
>>> from isaacsim.core.experimental.actuators import ActuatorConfig
>>> from newton.actuators import DrivePD

>>> cfg = ActuatorConfig(
...     controller=DrivePD(
...         kp=wp.array([100.0], dtype=wp.float32),
...         kd=wp.array([10.0], dtype=wp.float32),
...     )
... )

clamping: list[ClampingBase]#

controller: DriveBase#

delay: Delay | None = None#

class PDControlConfig(kp: float, kd: float, const_effort: float = 0.0)#

Bases: object

Configuration for a PD position-velocity controller.

Corresponds to NewtonPDControlAPI in the Newton USD schema.

Parameters:

kp – Proportional (position) gain.
kd – Derivative (velocity) gain.
const_effort – Constant bias effort added to the controller output.

Example:

>>> from isaacsim.core.experimental.actuators import PDControlConfig

>>> cfg = PDControlConfig(kp=500.0, kd=50.0)

const_effort: float = 0.0#

kd: float#

kp: float#

class PIDControlConfig( kp: float, ki: float, kd: float, integral_max: float = inf, const_effort: float = 0.0, )#

Bases: object

Configuration for a PID position-velocity controller.

Corresponds to NewtonPIDControlAPI in the Newton USD schema.

Parameters:

kp – Proportional (position) gain.
ki – Integral gain.
kd – Derivative (velocity) gain.
integral_max – Anti-windup clamp applied symmetrically to the integral term. Pass math.inf to disable anti-windup.
const_effort – Constant bias effort added to the controller output.

Example:

>>> from isaacsim.core.experimental.actuators import PIDControlConfig

>>> cfg = PIDControlConfig(kp=500.0, ki=10.0, kd=50.0, integral_max=200.0)

const_effort: float = 0.0#

integral_max: float = inf#

kd: float#

ki: float#

kp: float#

class NeuralControlConfig(model_path: str)#

Bases: object

Configuration for a neural-network controller (MLP or LSTM).

The concrete class (DriveNeuralMLP or DriveNeuralLSTM) is selected at parse time by inspecting the model_type metadata stored inside the checkpoint at model_path.

Corresponds to NewtonNeuralControlAPI in the Newton USD schema.

Parameters:: model_path – Path to the pre-trained model checkpoint (e.g. a TorchScript .pt file). The file must contain a model_type metadata entry with value "mlp" or "lstm".

Example:

>>> from isaacsim.core.experimental.actuators import NeuralControlConfig

>>> cfg = NeuralControlConfig(model_path="/path/to/policy.pt")

model_path: str#

class MaxEffortClampingConfig(max_effort: float)#

Bases: object

Configuration for symmetric max-effort clamping.

Clamps actuator output to the range [-max_effort, +max_effort].

Corresponds to NewtonMaxEffortClampingAPI in the Newton USD schema.

Parameters:: max_effort – Maximum output effort limit (force or torque).

Example:

>>> from isaacsim.core.experimental.actuators import MaxEffortClampingConfig

>>> cfg = MaxEffortClampingConfig(max_effort=100.0)

max_effort: float#

class DCMotorClampingConfig( saturation_effort: float, velocity_limit: float, max_motor_effort: float, )#

Bases: object

Configuration for DC motor four-quadrant effort clamping.

Models a motor whose available output effort decreases linearly with joint velocity:

effort_max(vel) = min(saturation_effort * (1 - vel / velocity_limit), max_motor_effort)

Corresponds to NewtonDCMotorClampingAPI in the Newton USD schema.

Parameters:

saturation_effort – Peak motor effort at stall (zero velocity).
velocity_limit – Maximum no-load joint velocity at which the motor produces zero effort in the direction of motion. Pass math.inf to disable the velocity-dependent saturation.
max_motor_effort – Hard upper bound on the effort-speed envelope. Pass math.inf to leave uncapped.

Example:

>>> from isaacsim.core.experimental.actuators import DCMotorClampingConfig

>>> cfg = DCMotorClampingConfig(saturation_effort=120.0, velocity_limit=10.0, max_motor_effort=100.0)

max_motor_effort: float#

saturation_effort: float#

velocity_limit: float#

class PositionBasedClampingConfig( lookup_positions: list[float], lookup_efforts: list[float], )#

Bases: object

Configuration for position-dependent effort clamping via a lookup table.

The maximum output effort is interpolated from a table of (position, effort) pairs. Positions outside the table range are clamped to the nearest endpoint.

Corresponds to NewtonPositionBasedClampingAPI in the Newton USD schema.

Parameters:

lookup_positions – Sorted (monotonically non-decreasing) joint positions [rad or m] for the lookup table. Must be the same length as lookup_efforts and non-empty.
lookup_efforts – Non-negative maximum output efforts corresponding to each entry in lookup_positions. Must be the same length as lookup_positions.

Raises:

ValueError – If lookup_positions is empty.
ValueError – If lookup_positions and lookup_efforts have different lengths.

Example:

>>> from isaacsim.core.experimental.actuators import PositionBasedClampingConfig

>>> cfg = PositionBasedClampingConfig(
...     lookup_positions=[0.0, 0.5, 1.0],
...     lookup_efforts=[100.0, 80.0, 50.0],
... )

lookup_efforts: list[float]#

lookup_positions: list[float]#

class DelayConfig(delay_steps: int)#

Bases: object

Configuration for command-input delay.

Delays commanded position and velocity targets by a fixed number of physics timesteps to model communication or processing lag.

Corresponds to NewtonActuatorDelayAPI in the Newton USD schema.

Parameters:: delay_steps – Number of physics timesteps to delay command inputs. A value of 0 disables delay.

Example:

>>> from isaacsim.core.experimental.actuators import DelayConfig

>>> cfg = DelayConfig(delay_steps=3)

delay_steps: int#

USD authoring#

Author a NewtonActuator prim targeting one or more DOFs of an articulation.

The prim is created at {articulation_root}/Actuators/{name} on the current USD stage. All provided config objects are translated to the corresponding Newton USD API schemas and their attributes are authored immediately.

Target DOFs are identified by name — the last segment of their full USD path (e.g. "RevoluteJoint" for /World/Robot/Arm/RevoluteJoint). The stage is traversed at authoring time to validate that each name resolves to exactly one joint prim under articulation_root.

Parameters:

articulation_root – Root USD path of the articulation (e.g. "/World/Robot").
target_names – Name or list of names of the target joint DOFs (last path segment).
name – Name for the NewtonActuator prim, used as the final path segment under {articulation_root}/Actuators/.
controller – Controller configuration. Must be one of PDControlConfig, PIDControlConfig, or NeuralControlConfig.
clamping – Optional list of clamping configurations. Each entry must be one of MaxEffortClampingConfig, DCMotorClampingConfig, or PositionBasedClampingConfig. Each clamping type may appear at most once.
delay – Optional command-input delay configuration.
overwrite_existing – When True, silently replace any existing prim at the computed path; otherwise raise ValueError if a prim already exists there.

Returns:

The newly created NewtonActuator Usd.Prim.

Raises:

ValueError – If overwrite_existing is False and a prim already exists at the computed path.
ValueError – If any entry in target_names does not match exactly one joint DOF under articulation_root.
ValueError – If clamping contains duplicate config types.
ValueError – If clamping contains a PositionBasedClampingConfig with invalid lookup table data.

Example:

>>> from isaacsim.core.experimental.actuators import (
...     add_actuator,
...     PDControlConfig,
...     MaxEffortClampingConfig,
...     DCMotorClampingConfig,
...     DelayConfig,
... )

>>> prim = add_actuator(  
...     "/World/Robot",
...     target_names="RevoluteJoint",
...     name="elbow_actuator",
...     controller=PDControlConfig(kp=500.0, kd=50.0),
...     clamping=[
...         MaxEffortClampingConfig(max_effort=100.0),
...         DCMotorClampingConfig(saturation_effort=120.0, velocity_limit=10.0, max_motor_effort=100.0),
...     ],
...     delay=DelayConfig(delay_steps=2),
... )

Omnigraph Nodes#

The extension exposes the following Omnigraph nodes:

Articulation Actuators

Python API

[isaacsim.core.experimental.actuators] Isaac Sim Core (Actuators)#

Overview#

Key Components#

ArticulationActuators#

ActuatorConfig#

USD Authoring#

Articulation Actuators OmniGraph Node#

Functionality#

Two Construction Paths#

Composable Per-Actuator Pipeline#

Autonomous Pre-Physics Stepping#

Feedforward Effort#

Partial Coverage#

Cross-Application Portability#

Tutorials#

Enable Extension#

Python API#

Wrappers#

Lifetime#

Configuration dataclasses#

USD authoring#

Omnigraph Nodes#

`ArticulationActuators`#

`ActuatorConfig`#

`Articulation Actuators` OmniGraph Node#