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.
`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.
`debug_vis`	Whether to visualize debug information.

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,
}

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.

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

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.
`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.
`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.

Methods:

`__init__`(cfg, env)	Initialize the action term.
`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.
`serialize`()	General serialization call.
`set_debug_vis`(debug_vis)	Sets whether to visualize the action term data.

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

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 _sphinx_paramlinks_isaaclab_contrib.mdp.actions.thrust_actions.ThrustAction.set_debug_vis.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.

Additional Public Classes#

The following classes are part of the public isaaclab_contrib.mdp API.

`NavigationAction`	Convert high-level navigation commands to thrust commands.
`NavigationActionCfg`	Configuration for the navigation action term.

class isaaclab_contrib.mdp.NavigationAction[source]#

Bases: ThrustAction

Convert high-level navigation commands to thrust commands.

This action term extends ThrustAction with a geometric tracking controller. The controller computes force and torque commands from navigation setpoints and allocates the resulting wrench to individual thrusters through the multirotor allocation matrix.

The three-dimensional action contains normalized magnitude, inclination, and yaw components. Each component is clamped to the dimensionless range [-1, 1] before conversion to controller setpoints. For a clamped action \((a_m, a_i, a_y)\), the inclination angle is \(\theta = a_i\,\mathtt{max\_inclination\_angle}\) [rad] and the translational magnitude is \(m = (a_m + 1)\,\mathtt{max\_magnitude} / 2\). The translational setpoint is \((m\cos\theta, 0, m\sin\theta)\), where its units depend on the configured Lee controller: position [m], velocity [m/s], or acceleration [m/s^2]. The yaw setpoint is \(a_y\,\mathtt{max\_yaw\_command}\) and represents a yaw rate [rad/s] for velocity and acceleration control or a relative yaw angle [rad] for position control.

The action term constrains lateral motion to keep commands inside the camera field of view. It resets controller state, including integral terms, when reset() is called.

Example

cfg = NavigationActionCfg(
    controller_cfg=LeeVelControllerCfg(...),
    asset_name="robot",
    max_magnitude=2.0,
    max_yaw_command=1.047,
    max_inclination_angle=0.785,
)
nav_action = NavigationAction(cfg, env)

Methods:

`__new__`(args, *kwargs)
`__init__`(cfg, env)	Initialize the action term.

classmethod __new__(*args, **kwargs)#

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

Initialize the action term.

Parameters:

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

class isaaclab_contrib.mdp.NavigationActionCfg[source]#

Bases: ThrustActionCfg

Configuration for the navigation action term.

This action term constrains the controller action to be within the field of view (FOV) of the camera sensor. Specifically:

y-component: Always 0, as the camera FOV constraint restricts lateral movement
x and z components: Derived from the action max_magnitude and max_inclination_angle, ensuring the desired acceleration/velocity/position vector remains aligned with the camera’s viewing direction

This constraint ensures that navigation commands respect the sensor’s field of view limitations, preventing commands that would be out of the camera’s visual range.

See NavigationAction for more details.

Methods:

`__new__`(args, *kwargs)
`__init__`([class_type, asset_name, ...])

classmethod __new__(*args, **kwargs)#

__init__(class_type: type[NavigationAction] | str = <factory>, asset_name: str = <factory>, debug_vis: bool = <factory>, clip: dict[str, tuple[float, float]] | None = <factory>, scale: float | dict[str, float] = <factory>, offset: float | dict[str, float] = <factory>, preserve_order: bool = <factory>, use_default_offset: bool = <factory>, controller_cfg: LeeVelControllerCfg | LeePosControllerCfg | LeeAccControllerCfg = <factory>, max_magnitude: float = <factory>, max_yaw_command: float = <factory>, max_inclination_angle: float = <factory>) → None#

isaaclab_contrib.mdp

Contents

isaaclab_contrib.mdp#

Actions#

Thrust Action Configuration#

Thrust Action Implementation#

Additional Public Classes#