mjlab.actuator

Actuator implementations for mjlab.

Classes

Actuator ActuatorCfg ActuatorCmd BuiltinActuatorGroup BuiltinMotorActuator BuiltinMotorActuatorCfg BuiltinPositionActuator

BuiltinPositionActuatorCfg BuiltinVelocityActuator BuiltinVelocityActuatorCfg BuiltinMuscleActuator BuiltinMuscleActuatorCfg XmlActuator XmlActuatorCfg

IdealPdActuator IdealPdActuatorCfg DcMotorActuator DcMotorActuatorCfg LearnedMlpActuator LearnedMlpActuatorCfg

Base

class mjlab.actuator.Actuator

Bases: ABC, Generic[ActuatorCfgT]

Base actuator interface.

__init__(cfg: ActuatorCfgT, entity: Entity, target_ids: list[int], target_names: list[str]) → None

property has_delay: bool

Whether this actuator has delay configured.

property command_field: Literal['position', 'velocity', 'effort'] | None

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

property target_ids: Tensor

Local indices of targets controlled by this actuator.

property target_names: list[str]

Names of targets controlled by this actuator.

property transmission_type: TransmissionType

Transmission type of this actuator.

property ctrl_ids: Tensor

Local indices of control inputs within the entity.

property global_ctrl_ids: Tensor

Global indices of control inputs in the MuJoCo model.

abstractmethod edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

initialize(mj_model: MjModel, model: mujoco_warp.Model, data: mujoco_warp.Data, device: str) → None

Initialize the actuator after model compilation.

This is called after the MjSpec is compiled into an MjModel.

Parameters:

• mj_model – The compiled MuJoCo model.

• model – The compiled mjwarp model.

• data – The mjwarp data arrays.

• device – Device for tensor operations (e.g., “cuda”, “cpu”).

apply_delay(cmd: ActuatorCmd) → ActuatorCmd

Apply delay to the command_field target. No-op without delay.

set_lags(lags: Tensor, env_ids: Tensor | slice | None = None) → None

Set delay lag values for specified environments.

Built-in actuators with the same delay config share a fused delay buffer for performance. Calling set_lags on any one of them affects the entire fused group.

Parameters:

• lags – Lag values in physics timesteps. Shape: (num_env_ids,) or scalar.

• env_ids – Environment indices to set. If None, sets all environments.

get_command(data: EntityData) → ActuatorCmd

Extract command data for this actuator from entity data.

Parameters:

data – The entity data containing all state and target information.

Returns:

ActuatorCmd with appropriate data based on transmission type.

abstractmethod compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

reset(env_ids: Tensor | slice | None = None) → None

Reset actuator state for specified environments.

Resets delay buffers if present. Subclasses that override this should call super().reset(env_ids).

Parameters:

env_ids – Environment indices to reset. If None, reset all environments.

update(dt: float) → None

Update actuator state after a simulation step.

Base implementation does nothing. Override in subclasses that need per-step updates.

Parameters:

dt – Time step in seconds.

class mjlab.actuator.ActuatorCfg

target_names_expr: tuple[str, ...]

Targets that are part of this actuator group.

Can be a tuple of names or tuple of regex expressions. Interpreted based on transmission_type.

transmission_type: TransmissionType = 'joint'

Transmission type. Defaults to JOINT.

armature: float | None = None

Reflected rotor inertia. None preserves the XML value.

frictionloss: float | None = None

Friction loss force limit. None preserves the XML value.

Applies a constant friction force opposing motion, independent of load or velocity. Also known as dry friction or load-independent friction.

viscous_damping: float | None = None

Passive viscous damping coefficient. None preserves the XML value.

Produces a dissipative force f(v) = -b·v proportional to velocity. Always present regardless of actuator activity. Unlike damping (the PD derivative gain kv, which is active control), this is a passive property.

Maps to <joint damping> for JOINT transmission and <tendon damping> for TENDON transmission. Ignored for SITE.

delay_min_lag: int = 0

Minimum command delay in physics timesteps.

Each step, a lag is sampled uniformly from [min, max]. The command target arrives that many steps late at the actuator’s control law. Models communication and bus latency between the policy and the motor (as opposed to observation delay, which models sensor pipeline latency).

delay_max_lag: int = 0

Maximum command delay in physics timesteps. Set > 0 to enable delay.

delay_hold_prob: float = 0.0

Probability of keeping the current lag instead of resampling.

delay_update_period: int = 0

How often to resample the lag, in physics timesteps (0 = every step).

delay_per_env_phase: bool = True

Stagger lag resampling across environments so they don’t all update on the same step.

abstractmethod build(entity: Entity, target_ids: list[int], target_names: list[str]) → Actuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

class mjlab.actuator.ActuatorCmd

High-level actuator command with targets and current state.

Passed to actuator’s compute() method to generate low-level control signals. All tensors have shape (num_envs, num_targets).

position_target: Tensor

Desired positions (joint positions, tendon lengths, or site positions).

velocity_target: Tensor

Desired velocities (joint velocities, tendon velocities, or site velocities).

effort_target: Tensor

Feedforward effort (torques or forces).

pos: Tensor

Current positions (joint positions, tendon lengths, or site positions).

vel: Tensor

Current velocities (joint velocities, tendon velocities, or site velocities).

Builtin Actuators

class mjlab.actuator.BuiltinActuatorGroup

Bases: object

Groups builtin actuators for batch processing.

static process(actuators: list[Actuator]) → tuple[BuiltinActuatorGroup, tuple[Actuator, ...]]

Classify actuators into builtin groups and custom actuators.

Non-delayed builtins go into direct index groups. Delayed builtins with matching delay config are fused into shared delay buffer groups. Everything else is returned as custom actuators.

Parameters:

actuators – List of initialized actuators to process.

Returns:

A tuple of (builtin group, custom actuators).

initialize(num_envs: int, device: str) → None

Create fused delay buffers for delayed builtin groups.

apply_controls(data: EntityData) → None

Write builtin actuator controls to simulation data.

__init__(_index_groups: dict[tuple[type[BuiltinMotorActuator | BuiltinMuscleActuator | BuiltinPositionActuator | BuiltinVelocityActuator], TransmissionType], tuple[Tensor, Tensor]], _delayed_groups: list[_FusedDelayGroup]) → None

class mjlab.actuator.BuiltinMotorActuator

Bases: Actuator[BuiltinMotorActuatorCfg]

MuJoCo built-in motor actuator.

property command_field: Literal['position', 'velocity', 'effort']

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

__init__(cfg: BuiltinMotorActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.BuiltinMotorActuatorCfg

Configuration for MuJoCo built-in motor actuator.

Under the hood, this creates a <motor> actuator for each target and sets its effort limit and gear ratio accordingly. If armature or frictionloss are set, they override the corresponding joint/tendon properties from XML.

effort_limit: float

Maximum actuator effort.

gear: float = 1.0

Actuator gear ratio.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → BuiltinMotorActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

class mjlab.actuator.BuiltinPositionActuator

Bases: Actuator[BuiltinPositionActuatorCfg]

MuJoCo built-in position actuator.

property command_field: Literal['position', 'velocity', 'effort']

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

__init__(cfg: BuiltinPositionActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.BuiltinPositionActuatorCfg

Configuration for MuJoCo built-in position actuator.

Under the hood, this creates a <position> actuator for each target and sets the stiffness, damping and effort limits accordingly. If armature or frictionloss are set, they override the corresponding joint/tendon properties from XML.

stiffness: float

PD proportional gain.

damping: float

PD derivative gain.

effort_limit: float | None = None

Maximum actuator force/torque. If None, no limit is applied.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → BuiltinPositionActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

class mjlab.actuator.BuiltinVelocityActuator

Bases: Actuator[BuiltinVelocityActuatorCfg]

MuJoCo built-in velocity actuator.

property command_field: Literal['position', 'velocity', 'effort']

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

__init__(cfg: BuiltinVelocityActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.BuiltinVelocityActuatorCfg

Configuration for MuJoCo built-in velocity actuator.

Under the hood, this creates a <velocity> actuator for each target and sets the damping gain. If armature or frictionloss are set, they override the corresponding joint/tendon properties from XML.

damping: float

Damping gain.

effort_limit: float | None = None

Maximum actuator force/torque. If None, no limit is applied.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → BuiltinVelocityActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

class mjlab.actuator.BuiltinMuscleActuator

Bases: Actuator[BuiltinMuscleActuatorCfg]

MuJoCo built-in muscle actuator.

property command_field: Literal['position', 'velocity', 'effort']

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

__init__(cfg: BuiltinMuscleActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.BuiltinMuscleActuatorCfg

Configuration for MuJoCo built-in muscle actuator.

length_range: tuple[float, float] = (0.0, 0.0)

Length range for muscle actuator.

gear: float = 1.0

Gear ratio.

timeconst: tuple[float, float] = (0.01, 0.04)

Activation and deactivation time constants.

tausmooth: float = 0.0

Smoothing time constant.

range: tuple[float, float] = (0.75, 1.05)

Operating range of normalized muscle length.

force: float = -1.0

Peak force (if -1, defaults to scale * FLV).

scale: float = 200.0

Force scaling factor.

lmin: float = 0.5

Minimum normalized muscle length.

lmax: float = 1.6

Maximum normalized muscle length.

vmax: float = 1.5

Maximum normalized muscle velocity.

fpmax: float = 1.3

Passive force at lmax.

fvmax: float = 1.2

Active force at -vmax.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → BuiltinMuscleActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

XML Actuators

class mjlab.actuator.XmlActuator

Bases: Actuator[XmlActuatorCfg]

Wrapper for XML-defined actuators.

__init__(cfg: XmlActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

property command_field: Literal['position', 'velocity', 'effort']

The resolved command field (detected or explicit), not the raw config value.

Set during edit_spec. Use self.cfg.command_field to access the user’s original input (which may be None for auto-detection).

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.XmlActuatorCfg

Wrap existing XML-defined actuators.

Detects the actuator type (position, velocity, motor, muscle) from the MuJoCo spec element during edit_spec, or validates against an explicit command_field if provided.

command_field: CommandField | None = None

If provided, require XML actuators to match this command field. If None, auto-detect strictly from the spec element.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → XmlActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

Ideal PD Actuator

class mjlab.actuator.IdealPdActuator

Bases: Actuator, Generic[IdealPdCfgT]

Ideal PD control actuator.

property command_field: Literal['position', 'velocity', 'effort']

The primary command field this actuator consumes.

Returns None by default. Subclasses should override to return the appropriate field.

__init__(cfg: IdealPdCfgT, entity: Entity, target_ids: list[int], target_names: list[str]) → None

edit_spec(spec: MjSpec, target_names: list[str]) → None

Edit the MjSpec to add actuators.

This is called during entity construction, before the model is compiled.

Parameters:

• spec – The entity’s MjSpec to edit.

• target_names – Names of targets (joints, tendons, or sites) as they appear in the spec. When the entity’s spec_fn uses internal MjSpec.attach(prefix=...), these will include the prefix (e.g., "left/elbow" rather than "elbow").

initialize(mj_model: MjModel, model: mujoco_warp.Model, data: mujoco_warp.Data, device: str) → None

Initialize the actuator after model compilation.

This is called after the MjSpec is compiled into an MjModel.

Parameters:

• mj_model – The compiled MuJoCo model.

• model – The compiled mjwarp model.

• data – The mjwarp data arrays.

• device – Device for tensor operations (e.g., “cuda”, “cpu”).

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

set_gains(env_ids: Tensor | slice, kp: Tensor | None = None, kd: Tensor | None = None) → None

Set PD gains for specified environments.

Parameters:

• env_ids – Environment indices to update.

• kp – New proportional gains. Shape: (num_envs, num_actuators) or (num_envs,).

• kd – New derivative gains. Shape: (num_envs, num_actuators) or (num_envs,).

set_effort_limit(env_ids: Tensor | slice, effort_limit: Tensor) → None

Set effort limits for specified environments.

Parameters:

• env_ids – Environment indices to update.

• effort_limit – New effort limits. Shape: (num_envs, num_actuators) or (num_envs,).

class mjlab.actuator.IdealPdActuatorCfg

Configuration for ideal PD actuator.

stiffness: float

PD stiffness (proportional gain).

damping: float

PD damping (derivative gain).

effort_limit: float = inf

Maximum force/torque limit.

build(entity: Entity, target_ids: list[int], target_names: list[str]) → IdealPdActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

DC Motor Actuator

class mjlab.actuator.DcMotorActuator

Bases: IdealPdActuator[DcMotorCfgT], Generic[DcMotorCfgT]

DC motor actuator with velocity-based saturation model.

This actuator extends IdealPdActuator with a realistic DC motor model that limits torque based on current joint velocity. The model implements a linear torque-speed curve where: - At zero velocity: can produce full saturation_effort (stall torque) - At max velocity: can produce zero torque - Between: torque limit varies linearly

The continuous torque limit (effort_limit) further constrains the output.

__init__(cfg: DcMotorCfgT, entity: Entity, target_ids: list[int], target_names: list[str]) → None

initialize(mj_model: MjModel, model: mujoco_warp.Model, data: mujoco_warp.Data, device: str) → None

Initialize the actuator after model compilation.

This is called after the MjSpec is compiled into an MjModel.

Parameters:

• mj_model – The compiled MuJoCo model.

• model – The compiled mjwarp model.

• data – The mjwarp data arrays.

• device – Device for tensor operations (e.g., “cuda”, “cpu”).

compute(cmd: ActuatorCmd) → Tensor

Compute low-level actuator control signal from high-level commands.

Parameters:

cmd – High-level actuator command.

Returns:

Control signal tensor of shape (num_envs, num_actuators).

class mjlab.actuator.DcMotorActuatorCfg

Configuration for DC motor actuator with velocity-based saturation.

This actuator implements a DC motor torque-speed curve for more realistic actuator behavior. The motor produces maximum torque (saturation_effort) at zero velocity and reduces linearly to zero torque at maximum velocity.

Note: effort_limit should be explicitly set to a realistic value for proper motor modeling. Using the default (inf) will trigger a warning. Use IdealPdActuator if unlimited torque is desired.

saturation_effort: float

Peak motor torque at zero velocity (stall torque).

velocity_limit: float

Maximum motor velocity (no-load speed).

build(entity: Entity, target_ids: list[int], target_names: list[str]) → DcMotorActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.

Learned MLP Actuator

class mjlab.actuator.LearnedMlpActuator

Bases: DcMotorActuator[LearnedMlpActuatorCfg]

MLP-based learned actuator with joint history.

This actuator uses a trained neural network to map from joint commands and state history to torque outputs. The network captures complex actuator dynamics that are difficult to model analytically.

The actuator maintains circular buffers of joint position errors and velocities, which are used as inputs to the MLP. The network outputs are then scaled and clipped using the DC motor limits from the parent class.

__init__(cfg: LearnedMlpActuatorCfg, entity: Entity, target_ids: list[int], target_names: list[str]) → None

initialize(mj_model: MjModel, model: mujoco_warp.Model, data: mujoco_warp.Data, device: str) → None

Initialize the actuator after model compilation.

This is called after the MjSpec is compiled into an MjModel.

Parameters:

• mj_model – The compiled MuJoCo model.

• model – The compiled mjwarp model.

• data – The mjwarp data arrays.

• device – Device for tensor operations (e.g., “cuda”, “cpu”).

reset(env_ids: Tensor | slice | None = None) → None

Reset history buffers for specified environments.

Parameters:

env_ids – Environment indices to reset. If None, reset all environments.

compute(cmd: ActuatorCmd) → Tensor

Compute actuator torques using the learned MLP model.

Parameters:

cmd – High-level actuator command containing targets and current state.

Returns:

Computed torque tensor of shape (num_envs, num_joints).

class mjlab.actuator.LearnedMlpActuatorCfg

Configuration for MLP-based learned actuator model.

This actuator learns the mapping from joint commands and state history to actual torque output. It’s useful for capturing actuator dynamics that are difficult to model analytically, such as delays, non-linearities, and friction effects.

The network is trained offline using data from the real system and loaded as a TorchScript file. The model uses a sliding window of historical joint position errors and velocities as inputs.

network_file: str

Path to the TorchScript file containing the trained MLP model.

pos_scale: float

Scaling factor for joint position error inputs to the network.

vel_scale: float

Scaling factor for joint velocity inputs to the network.

torque_scale: float

Scaling factor for torque outputs from the network.

input_order: Literal['pos_vel', 'vel_pos'] = 'pos_vel'

Order of inputs to the network.

• “pos_vel”: position errors followed by velocities

• “vel_pos”: velocities followed by position errors

history_length: int = 3

Number of timesteps of history to use as network inputs.

For example, history_length=3 uses the current timestep plus the previous 2 timesteps (total of 3 frames).

stiffness: float = 0.0

PD stiffness (proportional gain).

damping: float = 0.0

PD damping (derivative gain).

build(entity: Entity, target_ids: list[int], target_names: list[str]) → LearnedMlpActuator

Build actuator instance.

Parameters:

• entity – Entity this actuator belongs to.

• target_ids – Local target indices (for indexing entity arrays).

• target_names – Target names corresponding to target_ids.

Returns:

Actuator instance.