Adds documentation for Multirotor feature (isaac-sim#4400)

# Description

This MR adds more documentation to the multi-rotor classes to help users
understand the features in more detail.

## Type of change

- Documentation update

## Checklist

- [ ] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have updated the changelog and the corresponding version in the
extension's `config/extension.toml` file
- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Co-authored-by: Pascal Roth <57946385+pascal-roth@users.noreply.github.com>

Author: Mayankm96

docs/source/_static/refs.bib

@@ -183,3 +183,14 @@ @InProceedings{mittal2024symmetry
   pages={7433-7439},
   doi={10.1109/ICRA57147.2024.10611493}
 }
+
+@article{kulkarni2025aerialgym,
+  author={Kulkarni, Mihir and Rehberg, Welf and Alexis, Kostas},
+  journal={IEEE Robotics and Automation Letters},
+  title={Aerial Gym Simulator: A Framework for Highly Parallelized Simulation of Aerial Robots},
+  year={2025},
+  volume={10},
+  number={4},
+  pages={4093-4100},
+  doi={10.1109/LRA.2025.3548507}
+}

pyproject.toml

@@ -66,6 +66,7 @@ section-order = [
     "omniverse-extensions",
     # Group Isaac Lab extensions together since they are all part of the Isaac Lab project
     "isaaclab",
+    "isaaclab-contrib",
     "isaaclab-rl",
     "isaaclab-mimic",
     "isaaclab-tasks",
@@ -90,6 +91,7 @@ section-order = [
 
 "isaaclab" = ["isaaclab"]
 "isaaclab-assets" = ["isaaclab_assets"]
+"isaaclab-contrib" = ["isaaclab_contrib"]
 "isaaclab-rl" = ["isaaclab_rl"]
 "isaaclab-mimic" = ["isaaclab_mimic"]
 "isaaclab-tasks" = ["isaaclab_tasks"]

source/isaaclab_assets/isaaclab_assets/robots/arl_robot_1.py

@@ -10,12 +10,12 @@
 * :obj:`ARL_ROBOT_1_CFG`: The ARL_Robot_1 with (TODO add motor propeller combination)
 """
 
-from isaaclab_contrib.actuators import ThrusterCfg
-from isaaclab_contrib.assets import MultirotorCfg
-
 import isaaclab.sim as sim_utils
 from isaaclab.utils.assets import ISAAC_NUCLEUS_DIR
 
+from isaaclab_contrib.actuators import ThrusterCfg
+from isaaclab_contrib.assets import MultirotorCfg
+
 ##
 # Configuration - Actuators.
 ##

source/isaaclab_contrib/docs/README.md

@@ -1,47 +1,94 @@
-# Isaac Lab: MultiRotor Extension
+# Isaac Lab: Community Contributions
 
-This extension provides comprehensive support for multirotor systems (drones, quadcopters, hexacopters, etc.)
-in Isaac Lab. It includes specialized actuator models, asset classes, and MDP components specifically designed
-for multirotor simulation.
+This extension (`isaaclab_contrib`) provides a collection of community-contributed components for Isaac Lab. These contributions extend the core framework with specialized robot types, actuator models, sensors, and other features that are not yet part of the main Isaac Lab package but are actively maintained and supported by the community.
 
-## Features
+## Overview
 
-The extension provides the following key components:
+The `isaaclab_contrib` package serves as an incubator for experimental and specialized features that:
 
-### Assets
+- Extend Isaac Lab's capabilities for specific robot types or use cases
+- Provide domain-specific actuator models and control interfaces
+- Offer specialized MDP components for reinforcement learning tasks
+- May eventually be integrated into the core Isaac Lab framework
 
-* **`Multirotor`**: A specialized articulation class that extends the base `Articulation` class to support
-  multirotor systems with thruster actuators. This class handles the simulation of multirotor dynamics,
-  including thrust application at specific body locations and integration with the thruster actuator model.
+## Current Contributions
 
-### Actuators
+### Multirotor Systems
 
-* **`Thruster`**: A low-level motor/thruster dynamics model with separate rise/fall time constants. This
-  actuator model simulates realistic motor response characteristics including:
-  - Asymmetric rise and fall time constants
-  - Thrust limits (minimum and maximum)
-  - Integration schemes (Euler or RK4)
-  - Motor spin-up and spin-down dynamics
+Comprehensive support for multirotor vehicles (drones, quadcopters, hexacopters, octocopters, etc.) including:
 
-### MDP Components
+- **Assets**: `Multirotor` articulation class with thruster-based control
+- **Actuators**: `Thruster` model with realistic motor dynamics
+- **MDP Components**: `ThrustAction` terms for RL control
 
-* **Thrust Actions**: Action terms specifically designed for multirotor control, allowing direct thrust
-  commands to individual thrusters or groups of thrusters. These integrate seamlessly with Isaac Lab's
-  MDP framework for reinforcement learning tasks.
+See the [Multirotor Systems](#multirotor-systems-detailed) section below for detailed documentation.
 
-## Using the Extension
+## Extension Structure
+
+The extension follows Isaac Lab's standard package structure:
+
+```tree
+isaaclab_contrib/
+├── actuators/              # Contributed actuator models
+│   ├── thruster.py         # Thruster actuator for multirotors
+│   └── thruster_cfg.py
+├── assets/                 # Contributed asset classes
+│   └── multirotor/         # Multirotor asset implementation
+├── mdp/                    # MDP components for RL
+│   └── actions/            # Action terms
+└── utils/                  # Utility functions and types
+```
+
+## Installation and Usage
 
-To use this extension in your code, import the required components:
+The `isaaclab_contrib` package is included with Isaac Lab. To use contributed components:
 
 ```python
+# Import multirotor components
 from isaaclab_contrib.assets import Multirotor, MultirotorCfg
 from isaaclab_contrib.actuators import Thruster, ThrusterCfg
 from isaaclab_contrib.mdp.actions import ThrustActionCfg
 ```
 
-### Example: Creating a Multirotor Asset
+---
+
+## Multirotor Systems (Detailed)
+
+This section provides detailed documentation for the multirotor contribution, which enables simulation and control of multirotor aerial vehicles in Isaac Lab.
+
+### Features
+
+The multirotor system includes:
+
+#### Assets
 
-Here's how to configure and create a multirotor asset:
+- **`Multirotor`**: A specialized articulation class that extends the base `Articulation` class to support multirotor systems with thruster actuators
+  - Manages multiple thruster actuators as a group
+  - Applies thrust forces at specific body locations
+  - Uses allocation matrices for control allocation
+  - Provides thruster-specific state information through `MultirotorData`
+
+#### Actuators
+
+- **`Thruster`**: A low-level motor/thruster dynamics model with realistic response characteristics:
+  - **Asymmetric rise and fall time constants**: Models different spin-up/spin-down rates
+  - **Thrust limits**: Configurable minimum and maximum thrust constraints
+  - **Integration schemes**: Euler or RK4 integration methods
+  - **Dynamic response**: Simulates motor transient behavior
+
+#### MDP Components
+
+- **`ThrustAction`**: Action terms specifically designed for multirotor control:
+  - Direct thrust commands to individual thrusters or groups
+  - Flexible preprocessing (scaling, offsetting, clipping)
+  - Automatic hover thrust offset computation
+  - Integrates with Isaac Lab's MDP framework for RL tasks
+
+<details>
+
+### Quick Start
+
+#### Creating a Multirotor Asset
 
 ```python
 import isaaclab.sim as sim_utils
@@ -50,88 +97,147 @@ from isaaclab_contrib.actuators import ThrusterCfg
 
 # Define thruster actuator configuration
 thruster_cfg = ThrusterCfg(
-    thrust_limit=(0.0, 10.0),  # Min and max thrust in Newtons
-    rise_time_constant=0.1,     # Time constant for thrust increase
-    fall_time_constant=0.2,     # Time constant for thrust decrease
+    thruster_names_expr=["rotor_[0-3]"],  # Match rotors 0-3
+    thrust_range=(0.0, 10.0),              # Min and max thrust in Newtons
+    rise_time_constant=0.12,               # Time constant for thrust increase (120ms)
+    fall_time_constant=0.25,               # Time constant for thrust decrease (250ms)
 )
 
 # Create multirotor configuration
 multirotor_cfg = MultirotorCfg(
-    prim_path="/World/envs/env_.*/Robot",
+    prim_path="/World/envs/env_.*/Quadcopter",
     spawn=sim_utils.UsdFileCfg(
-        usd_path="path/to/your/multirotor.usd",
+        usd_path="path/to/quadcopter.usd",
+    ),
+    init_state=MultirotorCfg.InitialStateCfg(
+        pos=(0.0, 0.0, 1.0),    # Start 1m above ground
+        rps={".*": 110.0},      # All thrusters at 110 RPS (hover)
     ),
     actuators={
         "thrusters": thruster_cfg,
     },
+    allocation_matrix=[  # 6x4 matrix for quadcopter
+        [1.0, 1.0, 1.0, 1.0],       # Total vertical thrust
+        [0.0, 0.0, 0.0, 0.0],       # Lateral force X
+        [0.0, 0.0, 0.0, 0.0],       # Lateral force Y
+        [0.0, 0.13, 0.0, -0.13],    # Roll torque
+        [-0.13, 0.0, 0.13, 0.0],    # Pitch torque
+        [0.01, -0.01, 0.01, -0.01], # Yaw torque
+    ],
+    rotor_directions=[1, -1, 1, -1],  # Alternating CW/CCW
 )
 ```
 
-### Example: Using Thrust Actions in Environments
-
-To use thrust actions in your RL environment:
+#### Using Thrust Actions in RL Environments
 
 ```python
 from isaaclab.envs import ManagerBasedRLEnvCfg
+from isaaclab.utils import configclass
 from isaaclab_contrib.mdp.actions import ThrustActionCfg
 
 @configclass
-class MyMultirotorEnvCfg(ManagerBasedRLEnvCfg):
-    # ... other configuration ...
-
-    # Define actions
-    actions = ActionsCfg()
+class QuadcopterEnvCfg(ManagerBasedRLEnvCfg):
+    # ... scene, observations, rewards, etc. ...
 
     @configclass
     class ActionsCfg:
+        # Normalized thrust control around hover
         thrust = ThrustActionCfg(
             asset_name="robot",
-            thruster_names=["motor_.*"],  # regex pattern for thruster names
+            scale=2.0,                    # Actions in [-1,1] become [-2,2] N deviation
+            use_default_offset=True,      # Add hover thrust from config
+            clip={".*": (0.0, 10.0)},    # Constrain final thrust to [0, 10] N
         )
+
+    actions = ActionsCfg()
 ```
 
-## Extension Structure
+### Key Concepts
 
-The extension follows Isaac Lab's standard structure:
+#### Allocation Matrix
 
-```tree
-isaaclab_contrib/
-├── actuators/              # Thruster actuator implementations
-├── assets/                 # Multirotor asset classes
-│   └── multirotor/
-├── mdp/                    # MDP components for RL
-└── utils/                  # Utility functions and types
+The allocation matrix maps individual thruster forces to a 6D wrench (force + torque) applied to the multirotor's base link:
+
+```
+wrench = allocation_matrix @ thrust_vector
+```
+
+Where:
+- `wrench`: [Fx, Fy, Fz, Tx, Ty, Tz]ᵀ (6D body wrench)
+- `allocation_matrix`: 6 × N matrix (6 DOF, N thrusters)
+- `thrust_vector`: [T₁, T₂, ..., Tₙ]ᵀ (N thruster forces)
+
+The matrix encodes the geometric configuration of thrusters including positions, orientations, and moment arms.
+
+#### Thruster Dynamics
+
+The `Thruster` actuator model simulates realistic motor response with asymmetric first-order dynamics:
+
+```
+dT/dt = (T_target - T_current) / τ
 ```
 
-## Key Concepts
+Where τ is the time constant (different for rise vs. fall):
+- **Rise Time (τ_rise)**: How quickly thrust increases when commanded (typically slower)
+- **Fall Time (τ_fall)**: How quickly thrust decreases when commanded (typically faster)
+- **Thrust Limits**: Physical constraints [T_min, T_max] enforced after integration
+
+This asymmetry reflects real-world motor behavior primarily caused by ESC (Electronic Speed Controller) response and propeller aerodynamics, which result in slower spin-up (thrust increase) than spin-down. While rotor inertia affects both acceleration and deceleration equally, it is not the main cause of the asymmetric response.
 
-### Thruster Dynamics
+#### Thruster Control Modes
 
-The `Thruster` actuator model simulates realistic motor response with asymmetric dynamics:
+The multirotor system supports different control approaches:
 
-- **Rise Time**: How quickly thrust increases when commanded
-- **Fall Time**: How quickly thrust decreases when commanded
-- **Thrust Limits**: Physical constraints on minimum and maximum thrust output
+1. **Direct Thrust Control**: Directly command thrust forces/RPS
+2. **Normalized Control**: Commands as deviations from hover thrust
+3. **Differential Control**: Small adjustments around equilibrium
 
-This asymmetry reflects real-world motor behavior where spinning up often takes longer than spinning down.
+The `ThrustAction` term provides flexible preprocessing to support all modes through scaling and offsetting.
 
-### Multirotor Asset
+</details>
 
-The `Multirotor` class extends the standard `Articulation` to provide specialized functionality:
+### Demo Script
 
-- Manages multiple thruster actuators as a group
-- Applies thrust forces at specific body locations
-- Integrates with Isaac Lab's physics simulation
-- Provides thruster-specific state information through `MultirotorData`
+A complete demonstration of quadcopter simulation is available:
+
+```bash
+# Run quadcopter demo
+./isaaclab.sh -p scripts/demos/quadcopter.py
+```
+
+---
 
 ## Testing
 
-The extension includes comprehensive unit tests:
+The extension includes comprehensive unit tests for all contributed components:
 
 ```bash
-# Test thruster actuator
+# Test multirotor components
+python -m pytest source/isaaclab_contrib/test/assets/test_multirotor.py
 python -m pytest source/isaaclab_contrib/test/actuators/test_thruster.py
 
-# Test multirotor asset
-python -m pytest source/isaaclab_contrib/test/assets/test_multirotor.py
+# Run all contrib tests
+python -m pytest source/isaaclab_contrib/test/
 ```
+
+## Contributing
+
+We welcome community contributions to `isaaclab_contrib`! If you have developed:
+
+- Specialized robot asset classes
+- Novel actuator models
+- Custom MDP components
+- Domain-specific utilities
+
+Please follow the Isaac Lab contribution guidelines and open a pull request. Contributions should:
+
+1. Follow the existing package structure
+2. Include comprehensive documentation (docstrings, examples)
+3. Provide unit tests
+4. Be well-tested with Isaac Lab's simulation framework
+
+For more information, see the [Isaac Lab Contributing Guide](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html).
+
+## License
+
+This extension follows the same BSD-3-Clause license as Isaac Lab. See the LICENSE file for details.

source/isaaclab_contrib/isaaclab_contrib/__init__.py

@@ -3,7 +3,12 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""Package containing multirotor (drone) support for Isaac Lab."""
+"""Package for externally contributed components for Isaac Lab.
+
+This package provides externally contributed components for Isaac Lab, such as multirotors.
+These components are not part of the core Isaac Lab framework yet, but are planned to be added
+in the future. They are contributed by the community to extend the capabilities of Isaac Lab.
+"""
 
 import os
 import toml

source/isaaclab_contrib/isaaclab_contrib/actuators/__init__.py

@@ -3,5 +3,12 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
+"""Sub-package for thruster actuator models.
+
+This package provides actuator models specifically designed for multirotor thrusters.
+The thruster actuator simulates realistic motor/propeller dynamics including asymmetric
+rise and fall time constants, thrust limits, and dynamic response characteristics.
+"""
+
 from .thruster import Thruster
 from .thruster_cfg import ThrusterCfg

source/isaaclab_contrib/isaaclab_contrib/assets/__init__.py

@@ -3,6 +3,12 @@
 #
 # SPDX-License-Identifier: BSD-3-Clause
 
-"""Sub-package for different Isaac Lab external contributions."""
+"""Sub-package for externally contributed assets.
+
+This package provides specialized asset classes for simulating externally contributed
+robots in Isaac Lab, such as multirotors. These assets are not part of the core
+Isaac Lab framework yet, but are planned to be added in the future. They are
+contributed by the community to extend the capabilities of Isaac Lab.
+"""
 
 from .multirotor import Multirotor, MultirotorCfg, MultirotorData