isaaclab_contrib.mdp

isaaclab_contrib.mdp#

Sub-package for MDP (Markov Decision Process) components contributed by the community.

Actions#

Action terms for multirotor control.

This module provides action terms specifically designed for controlling multirotor vehicles through thrust commands. These action terms integrate with Isaac Lab’s MDP framework and Multirotor assets.

Classes

`ThrustActionCfg`	Configuration for the thrust action term.
`ThrustAction`	Thrust action term that applies the processed actions as thrust commands.

Thrust Action Configuration#

class isaaclab_contrib.mdp.actions.thrust_actions_cfg.ThrustActionCfg[source]#

Bases: ActionTermCfg

Configuration for the thrust action term.

This configuration class specifies how policy actions are transformed into thruster commands for multirotor control. It provides extensive customization of the action processing pipeline including scaling, offsetting, and clipping.

The action term is designed to work with Multirotor assets and uses their thruster configuration to determine which thrusters to control.

Key Configuration Options:

scale: Multiplies raw actions to adjust command magnitude
offset: Adds a baseline value (e.g., hover thrust) to actions
clip: Constrains actions to safe operational ranges
use_default_offset: Automatically uses hover thrust as offset

Example Configurations:

Normalized thrust control around hover:

thrust_action = ThrustActionCfg(
    asset_name="robot",
    scale=2.0,  # Actions in [-1,1] become [-2,2] N
    use_default_offset=True,  # Add hover thrust (e.g., 5N)
    clip={".*": (0.0, 10.0)},  # Final thrust in [0, 10] N
)

Direct thrust control with per-thruster scaling:

thrust_action = ThrustActionCfg(
    asset_name="robot",
    scale={
        "rotor_[0-1]": 8.0,  # Front rotors: stronger
        "rotor_[2-3]": 7.0,  # Rear rotors: weaker
    },
    offset=0.0,
    use_default_offset=False,
)

Differential thrust control:

thrust_action = ThrustActionCfg(
    asset_name="robot",
    scale=3.0,
    use_default_offset=True,  # Center around hover
    clip={".*": (-2.0, 8.0)},  # Allow +/-2N deviation
)

See also

ThrustAction: Implementation of this action term
ActionTermCfg: Base action term configuration

Attributes:

`asset_name`	Name or regex expression of the asset that the action will be mapped to.
`scale`	Scale factor for the action.
`offset`	Offset factor for the action.
`debug_vis`	Whether to visualize debug information.
`clip`	Clipping ranges for processed actions.
`preserve_order`	Whether to preserve the order of the asset names in the action output.
`use_default_offset`	Whether to use default thrust configured in the multirotor asset as offset.

asset_name: str#

Name or regex expression of the asset that the action will be mapped to.

This should match the name given to the multirotor asset in the scene configuration. For example, if the robot is defined as robot = MultirotorCfg(...), then asset_name should be "robot".

scale: float | dict[str, float]#

Scale factor for the action. Default is 1.0, which means no scaling.

This multiplies the raw action values to adjust the command magnitude. It can be:

A float: uniform scaling for all thrusters (e.g., 2.0)
A dict: per-thruster scaling using regex patterns (e.g., {"rotor_.*": 2.5})

For normalized actions in [-1, 1], the scale determines the maximum deviation from the offset value.

Example

# Uniform scaling
scale = 5.0  # Actions of ±1 become ±5N

# Per-thruster scaling
scale = {
    "rotor_[0-1]": 8.0,   # Front rotors
    "rotor_[2-3]": 6.0,   # Rear rotors
}

offset: float | dict[str, float]#

Offset factor for the action. Default is 0.0, which means no offset.

This value is added to the scaled actions to establish a baseline thrust. It can be:

A float: uniform offset for all thrusters (e.g., 5.0 for 5N hover thrust)
A dict: per-thruster offset using regex patterns

If use_default_offset is True, this value is overwritten by the default thruster RPS from the multirotor configuration.

Example

# Uniform offset (5N baseline thrust)
offset = 5.0

# Per-thruster offset
offset = {
    "rotor_0": 5.2,
    "rotor_1": 4.8,
}

debug_vis: bool#: Whether to visualize debug information. Defaults to False.

clip: dict[str, tuple[float, float]] | None#

Clipping ranges for processed actions. Default is None, which means no clipping.

This constrains the final thrust commands to safe operational ranges after scaling and offset are applied. It must be specified as a dictionary mapping regex patterns to (min, max) tuples.

Example

# Clip all thrusters to [0, 10] N
clip = {".*": (0.0, 10.0)}

# Different limits for different thrusters
clip = {
    "rotor_[0-1]": (0.0, 12.0),  # Front rotors
    "rotor_[2-3]": (0.0, 8.0),   # Rear rotors
}

preserve_order: bool#

Whether to preserve the order of the asset names in the action output. Default is False.

If True, the thruster ordering matches the regex pattern order exactly. If False, ordering is determined by the USD scene traversal order.

use_default_offset: bool#

Whether to use default thrust configured in the multirotor asset as offset. Default is True.

If True, the offset value is overwritten with the default thruster RPS values from MultirotorCfg.init_state.rps. This is useful for controlling thrust as deviations from the hover state.

If False, the manually specified offset value is used.

Thrust Action Implementation#

class isaaclab_contrib.mdp.actions.thrust_actions.ThrustAction[source]#

Bases: ActionTerm

Thrust action term that applies the processed actions as thrust commands.

This action term is designed specifically for controlling multirotor vehicles by mapping action inputs to thruster commands. It provides flexible preprocessing of actions through:

Scaling: Multiply actions by a scale factor to adjust command magnitudes
Offset: Add an offset to center actions around a baseline (e.g., hover thrust)
Clipping: Constrain actions to valid ranges to prevent unsafe commands

The action term integrates with Isaac Lab’s ActionManager framework and is specifically designed to work with Multirotor assets.

Key Features:

Supports per-thruster or uniform scaling and offsets
Optional automatic offset computation based on hover thrust
Action clipping for safety and constraint enforcement
Regex-based thruster selection for flexible control schemes

Example

from isaaclab.envs import ManagerBasedRLEnvCfg
from isaaclab_contrib.mdp.actions import ThrustActionCfg


@configclass
class MyEnvCfg(ManagerBasedRLEnvCfg):
    # ... other configuration ...

    @configclass
    class ActionsCfg:
        # Direct thrust control (normalized actions)
        thrust = ThrustActionCfg(
            asset_name="robot",
            scale=5.0,  # Convert [-1, 1] to [-5, 5] N
            use_default_offset=True,  # Add hover thrust as offset
            clip={".*": (-2.0, 8.0)},  # Clip to safe thrust range
        )

Attributes:

`cfg`	The configuration of the action term.
`device`	Device on which to perform computations.
`export_IO_descriptor`	Whether to export the IO descriptor for the action term.
`has_debug_vis_implementation`	Whether the action term has a debug visualization implemented.
`num_envs`	Number of environments.
`action_dim`	Dimension of the action term.
`raw_actions`	The input/raw actions sent to the term.
`processed_actions`	The actions computed by the term after applying any processing.
`IO_descriptor`	The IO descriptor of the action term.

Methods:

`__init__`(cfg, env)	Initialize the action term.
`serialize`()	General serialization call.
`set_debug_vis`(debug_vis)	Sets whether to visualize the action term data.
`reset`([env_ids])	Reset the action term.
`process_actions`(actions)	Process actions by applying scaling, offset, and clipping.
`apply_actions`()	Apply the processed actions as thrust commands.

cfg: thrust_actions_cfg.ThrustActionCfg#: The configuration of the action term.

__init__(cfg: thrust_actions_cfg.ThrustActionCfg, env: ManagerBasedEnv) → None[source]#

Initialize the action term.

Parameters:

cfg – The configuration object.
env – The environment instance.

property device: str#: Device on which to perform computations.

property export_IO_descriptor: bool#: Whether to export the IO descriptor for the action term.

property has_debug_vis_implementation: bool#: Whether the action term has a debug visualization implemented.

property num_envs: int#: Number of environments.

serialize() → dict#: General serialization call. Includes the configuration dict.

set_debug_vis(debug_vis: bool) → bool#

Sets whether to visualize the action term data. :param debug_vis: Whether to visualize the action term data.

Returns:: Whether the debug visualization was successfully set. False if the action term does not support debug visualization.

property action_dim: int#: Dimension of the action term.

property raw_actions: torch.Tensor#: The input/raw actions sent to the term.

property processed_actions: torch.Tensor#: The actions computed by the term after applying any processing.

property IO_descriptor: GenericActionIODescriptor#: The IO descriptor of the action term.

reset(env_ids: Sequence[int] | None = None) → None[source]#

Reset the action term.

This method resets the raw actions to zero for the specified environments. The processed actions will be recomputed during the next process_actions() call.

Parameters:: env_ids – Environment indices to reset. Defaults to None (all environments).

process_actions(actions: torch.Tensor)[source]#

Process actions by applying scaling, offset, and clipping.

This method transforms raw policy actions into thrust commands through an affine transformation followed by optional clipping. The transformation is:

\[\text{processed} = \text{raw} \times \text{scale} + \text{offset}\]

If clipping is configured, the processed actions are then clamped:

\[\text{processed} = \text{clamp}(\text{processed}, \text{min}, \text{max})\]

Parameters:: actions – Raw action tensor from the policy. Shape is (num_envs, action_dim). Typically in the range [-1, 1] for normalized policies.

Note

The processed actions are stored internally and applied during the next apply_actions() call.

apply_actions()[source]#

Apply the processed actions as thrust commands.

This method sets the processed actions as thrust targets on the multirotor asset. The thrust targets are then used by the thruster actuator models to compute actual thrust forces during the simulation step.

The method calls set_thrust_target() on the multirotor asset with the appropriate thruster IDs.

isaaclab_contrib.mdp

Contents

isaaclab_contrib.mdp#

Actions#

Thrust Action Configuration#

Thrust Action Implementation#