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),
... )