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

Version: 0.1.0

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 Controller, an ordered list of optional Clamping stages, and an optional Delay. Used together with from_actuators to attach actuators to an articulation without touching USD. Subclasses of newton.actuators.Controller, Clamping, 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: str | None = None, _skip_discovery: bool = False, )#

Bases: object

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

Parses NewtonActuator prims from the USD subtree under the first matched articulation instance, constructs one newton.actuators.Actuator per prim (fanned out to all N robot instances via indices), zeros UsdPhysics.DriveAPI gains on every actuated joint, and on each physics pre-step reads articulation state + control targets, steps every actuator, and writes the resulting efforts back to the articulation.

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 the articulation’s 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 an ActuatorParsed target path is not a DOF of this articulation, or if two 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]], *, 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 names.

The warp arrays inside each ActuatorConfig’s controller (e.g. kp, kd) must be sized for n_robots = len(Articulation(paths)). The Actuator wrapper (including index arrays) is built internally by this method.

The order of entries in actuators does not affect the result — the set is always stored sorted by DOF index.

Parameters:

paths – Single path or list of paths to articulation root prims.
actuators – List of (config, dof_name) pairs. dof_name is the last path segment of the target joint (e.g. "RevoluteJoint").
auto_step_pre_physics – Forwarded to the underlying __init__.

Returns:

A fully initialised ArticulationActuators driven by the provided configs.

Raises:

ValueError – If a dof_name is not found or matches multiple DOFs.
ValueError – If the same DOF name appears more than once in actuators.

Example:

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

>>> cfg = ActuatorConfig(
...     controller=ControllerPD(
...         kp=wp.array([100.0], dtype=wp.float32),
...         kd=wp.array([10.0], dtype=wp.float32),
...     )
... )
>>> actuated = ArticulationActuators.from_actuators(  
...     "/World/Robot",
...     [(cfg, "RevoluteJoint")],
... )

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.

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

Example:

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

property actuators: list[newton.actuators.Actuator]#

Get the Newton Actuator instances owned by this wrapper.

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: Controller, clamping: list[Clamping] = <factory>, delay: Delay | None = None, )#

Bases: object

Component bundle passed to ArticulationActuators.from_actuators.

Holds the Newton controller, optional clamping stages, and an optional delay. The warp arrays inside each component must be sized for n_robots, which can be obtained from len(Articulation(paths)) before constructing this config. The ArticulationActuators builds the Actuator wrapper (including index arrays) internally.

Parameters:

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

Example:

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

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

clamping: list[Clamping]#

controller: Controller#

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 (ControllerNeuralMLP or ControllerNeuralLSTM) 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#