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